用戶分群 REST API | Marketing Automation REST API 繁體中文

建立手動更新的名單分群，並按分群 ID 覆蓋、追加或移除成員。

通用說明

請求和響應均使用 UTF-8 編碼的 JSON。
完整呼叫地址由資料中心的 Base URL 與介面路徑組成。Base URL 和 API Key / API Secret 的獲取方式請參見 REST API 概述。
使用 HTTP Basic Authentication：Authorization: Basic ${base64(api_key:api_secret)}。API Key 對應的 API 資料來源決定所屬專案，呼叫方不需要在請求體中傳入專案 ID。
成功響應使用統一結構：code 為 0 表示成功，message 為結果描述，data 為介面資料。成員寫入的分片處理規則取決於操作型別：OVERRIDE 收齊全部分片後才執行；APPEND 和 REMOVE 的每個分片獨立執行。響應中的 data.status 和 data.complete 表示當前處理狀態。

建立名單分群

建立一個更新方式為手動、建立方式為名單上傳的分群。分群建立後成員為空，可使用「更新分群成員」介面寫入名單。

呼叫地址

POST /v1/segments

請求示例

curl -X POST 'https://ma-api.engagelab.com/v1/segments' \ -H 'Authorization: Basic {base64(api_key:api_secret)}' \ -H 'Content-Type: application/json' \ -d '{ "name": "高價值用戶", "description": "透過訂單系統同步的高價值用戶名稱單" }'

              
              curl -X POST 'https://ma-api.engagelab.com/v1/segments' \
  -H 'Authorization: Basic {base64(api_key:api_secret)}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "高價值用戶",
    "description": "透過訂單系統同步的高價值用戶名稱單"
  }'

此代碼塊在浮窗中顯示

請求引數

欄位	型別	必填	描述
`name`	String	是	分群名稱，不能為空，最多 50 個字元；同一專案內不能重名。首尾空格會被去除。
`description`	String	否	分群描述，最多 200 個字元。

返回示例

{ "code": 0, "message": "success", "data": { "segmentId": 123456789, "name": "高價值用戶", "generation": "generation-1" } }

              
              {
  "code": 0,
  "message": "success",
  "data": {
    "segmentId": 123456789,
    "name": "高價值用戶",
    "generation": "generation-1"
  }
}

此代碼塊在浮窗中顯示

欄位	型別	描述
`segmentId`	Long	新建分群 ID，後續名單寫入時使用。
`name`	String	分群名稱。
`generation`	String	當前成員版本標識。新建分群的成員為空。

更新分群成員

透過單一介面覆蓋、追加或移除名單。介面只接受當前專案中建立方式為名單上傳、更新方式為手動且狀態為生效中的分群。用戶標識必須能匹配到專案中已有的可用用戶；介面不會建立用戶資產。不滿足分群條件時返回 55210–55214（見錯誤響應），可直接定位原因。

呼叫地址

POST /v1/segments/{segmentId}/members

請求示例

以下示例把一次 OVERRIDE 操作拆成兩個分片。每個 batchId 表示一項名單操作；所有分片必須使用相同的 batchId、operation 和 batchCount。OVERRIDE 收齊全部分片後才執行名單變更。APPEND 和 REMOVE 則會在各自分片請求成功時立即生效。

curl -X POST 'https://ma-api.engagelab.com/v1/segments/123456789/members' \ -H 'Authorization: Basic {base64(api_key:api_secret)}' \ -H 'Content-Type: application/json' \ -d '{ "batchId": "crm-sync-20260915-001", "operation": "OVERRIDE", "batchIndex": 0, "batchCount": 2, "members": [ {"euid": "100001"}, {"identityName": "user_id", "identityValue": "user-002"} ] }'

              
              curl -X POST 'https://ma-api.engagelab.com/v1/segments/123456789/members' \
  -H 'Authorization: Basic {base64(api_key:api_secret)}' \
  -H 'Content-Type: application/json' \
  -d '{
    "batchId": "crm-sync-20260915-001",
    "operation": "OVERRIDE",
    "batchIndex": 0,
    "batchCount": 2,
    "members": [
      {"euid": "100001"},
      {"identityName": "user_id", "identityValue": "user-002"}
    ]
  }'

此代碼塊在浮窗中顯示

收到第一個 OVERRIDE 分片時，響應中的 status 為 RECEIVING、complete 為 false。提交剩餘分片時使用相同的 batchId，並將 batchIndex 設定為 1。

請求引數

欄位	型別	必填	描述
`segmentId`	Long	是	路徑引數，目標分群 ID。
`batchId`	String	是	一次完整名單操作的批次 ID，長度不超過 128 個字元，只能包含英文字母、數字、點、下劃線、冒號和連字元。同一專案、同一分群下 24 小時內作為冪等標識使用。
`operation`	String	是	名單操作：`OVERRIDE`（覆蓋）、`APPEND`（追加）、`REMOVE`（移除）。
`batchIndex`	Integer	是	當前分片序號，從 `0` 開始，且必須小於 `batchCount`。
`batchCount`	Integer	是	此次操作的分片總數，範圍為 1–10。所有分片合計最多 10,000 個成員標識。
`members`	Array	是	當前分片的成員標識，不能為空，每片最多 1,000 個。每個元素使用下表中的一種標識格式。

members 元素支援以下兩種格式，euid 不能與 identityName / identityValue 同時傳入：

欄位	型別	描述
`euid`	String	專案內 EUID，須為正整數格式，例如 `"100001"`。
`identityName`	String	專案中已配置的用戶標識名稱，不能為空，最多 128 個字元。
`identityValue`	String	用戶標識值，不能為空，最多 256 個字元；與 `identityName` 配套使用。超過 256 個字元不會整單失敗，該行計入 `invalidCount`。

名單操作說明

操作	說明
`OVERRIDE`	收齊全部分片後，以本次提交且匹配成功的用戶替換現有名單。若匹配到的可用用戶為空，整單拒絕並返回 `55214`，現有名單不變。
`APPEND`	當前分片請求成功後，將其中匹配成功的用戶追加到現有名單；已在群用戶不會重複加入。無需等待其他分片。
`REMOVE`	當前分片請求成功後，從現有名單移除其中匹配成功的用戶；不在群用戶不會產生額外變更。無需等待其他分片。

batchId 相同的重試必須提交相同的操作、batchCount 和分片內容；同一 batchId、同一 batchIndex 不可提交不同內容。冪等結果保留 24 小時。

OVERRIDE 的分片會暫存至全部收齊後再執行；暫存資料按 24 小時 TTL 過期，過期前未收齊時不會變更名單。APPEND 和 REMOVE 的每個分片獨立生效，batchCount 和 batchIndex 仍用於分片標識、冪等和進度統計，不會阻止當前分片執行。

每次成功的名單變更會在分群更新記錄中留下來源為 REST API 的記錄。OVERRIDE 按完成的批次記錄，APPEND 和 REMOVE 按成功分片記錄；審計記錄不包含未匹配或無效標識值樣例。

返回示例

分片尚未收齊：

{ "code": 0, "message": "success", "data": { "batchId": "crm-sync-20260915-001", "operation": "OVERRIDE", "status": "RECEIVING", "complete": false, "expectedBatchCount": 2, "receivedBatchCount": 1, "inputCount": 2, "matchedCount": 2, "unmatchedCount": 0, "unmatchedSamples": [], "unmatchedSamplesTruncated": false, "invalidCount": 0, "invalidSamples": [], "invalidSamplesTruncated": false, "enterCount": 0, "exitCount": 0 } }

              
              {
  "code": 0,
  "message": "success",
  "data": {
    "batchId": "crm-sync-20260915-001",
    "operation": "OVERRIDE",
    "status": "RECEIVING",
    "complete": false,
    "expectedBatchCount": 2,
    "receivedBatchCount": 1,
    "inputCount": 2,
    "matchedCount": 2,
    "unmatchedCount": 0,
    "unmatchedSamples": [],
    "unmatchedSamplesTruncated": false,
    "invalidCount": 0,
    "invalidSamples": [],
    "invalidSamplesTruncated": false,
    "enterCount": 0,
    "exitCount": 0
  }
}

此代碼塊在浮窗中顯示

OVERRIDE 批次處理完成：

{ "code": 0, "message": "success", "data": { "batchId": "crm-sync-20260915-001", "operation": "OVERRIDE", "status": "COMPLETED", "complete": true, "expectedBatchCount": 2, "receivedBatchCount": 2, "inputCount": 3, "matchedCount": 2, "unmatchedCount": 1, "unmatchedSamples": [ {"identityName": "user_id", "identityValue": "user-not-found"} ], "unmatchedSamplesTruncated": false, "invalidCount": 1, "invalidSamples": [ {"identityName": "not_configured", "identityValue": "example"} ], "invalidSamplesTruncated": false, "enterCount": 2, "exitCount": 1 } }

              
              {
  "code": 0,
  "message": "success",
  "data": {
    "batchId": "crm-sync-20260915-001",
    "operation": "OVERRIDE",
    "status": "COMPLETED",
    "complete": true,
    "expectedBatchCount": 2,
    "receivedBatchCount": 2,
    "inputCount": 3,
    "matchedCount": 2,
    "unmatchedCount": 1,
    "unmatchedSamples": [
      {"identityName": "user_id", "identityValue": "user-not-found"}
    ],
    "unmatchedSamplesTruncated": false,
    "invalidCount": 1,
    "invalidSamples": [
      {"identityName": "not_configured", "identityValue": "example"}
    ],
    "invalidSamplesTruncated": false,
    "enterCount": 2,
    "exitCount": 1
  }
}

此代碼塊在浮窗中顯示

APPEND 或 REMOVE 分片成功時，即使 batchCount 大於已收到的分片數，當前分片仍會立即生效並返回 complete: true。例如，batchCount 為 2、當前只收到第一個分片時，響應中的 receivedBatchCount 為 1，status 為 COMPLETED。

{ "code": 0, "message": "success", "data": { "batchId": "crm-sync-20260915-append", "operation": "APPEND", "status": "COMPLETED", "complete": true, "expectedBatchCount": 2, "receivedBatchCount": 1, "inputCount": 2, "matchedCount": 1, "unmatchedCount": 1, "unmatchedSamples": [ {"identityName": "user_id", "identityValue": "user-not-found"} ], "unmatchedSamplesTruncated": false, "invalidCount": 0, "invalidSamples": [], "invalidSamplesTruncated": false, "enterCount": 1, "exitCount": 0 } }

              
              {
  "code": 0,
  "message": "success",
  "data": {
    "batchId": "crm-sync-20260915-append",
    "operation": "APPEND",
    "status": "COMPLETED",
    "complete": true,
    "expectedBatchCount": 2,
    "receivedBatchCount": 1,
    "inputCount": 2,
    "matchedCount": 1,
    "unmatchedCount": 1,
    "unmatchedSamples": [
      {"identityName": "user_id", "identityValue": "user-not-found"}
    ],
    "unmatchedSamplesTruncated": false,
    "invalidCount": 0,
    "invalidSamples": [],
    "invalidSamplesTruncated": false,
    "enterCount": 1,
    "exitCount": 0
  }
}

此代碼塊在浮窗中顯示

欄位	型別	描述
`batchId`	String	本次名單操作的批次 ID。
`operation`	String	本次名單操作。
`status`	String	`RECEIVING`：`OVERRIDE` 等待分片；`PROCESSING`：當前請求等待名單變更鎖；`COMPLETED`：當前操作已完成。
`complete`	Boolean	`OVERRIDE` 表示全部分片已應用；`APPEND`/`REMOVE` 表示當前分片已應用，不代表所有分片都已提交。
`expectedBatchCount`	Integer	預期分片總數。
`receivedBatchCount`	Integer	已收到的不同分片序號數量；對於 `APPEND`/`REMOVE`，該值僅用於統計，不影響當前分片執行。
`inputCount`	Integer	有效輸入行數 = `matchedCount` + `unmatchedCount`，不含無效標識。`OVERRIDE` 統計已收到分片（完成時為整個批次）；`APPEND`/`REMOVE` 統計當前分片。
`matchedCount`	Integer	匹配到可用用戶的標識數。
`unmatchedCount`	Integer	未匹配到可用用戶的標識數。
`unmatchedSamples`	Array	未匹配標識樣例，元素結構與請求的成員標識相同，最多返回 100 條。
`unmatchedSamplesTruncated`	Boolean	未匹配樣例是否因 100 條上限而截斷。
`invalidCount`	Integer	無效標識數，不計入 `inputCount`。包括：`euid` 非正整數、與 identity 欄位同傳、`identityName`/`identityValue` 為空或不配套、`identityName` 超過 128 字元、`identityValue` 超過 256 字元、標識名未在專案中配置、同一標識匹配到多個可用用戶。
`invalidSamples`	Array	無效標識樣例，元素結構與請求的成員標識相同，最多返回 100 條。
`invalidSamplesTruncated`	Boolean	無效樣例是否因 100 條上限而截斷。
`enterCount`	Integer	本次執行實際新增的在群用戶數。
`exitCount`	Integer	本次執行實際移出分群的用戶數。

樣例沿用請求中的成員標識物件結構，可能包含傳入的 identityValue。服務端僅在 24 小時冪等結果快取中暫存樣例，不會將其寫入審計記錄；請按自身資料合規要求處理響應及日誌。

如果響應為 PROCESSING，可使用相同 batchId、batchIndex 和原分片內容重試，取得冪等結果。該介面沒有獨立的批次進度查詢介面。

錯誤響應

錯誤響應仍使用 code 和 message 欄位；HTTP 狀態碼及通用返回碼說明請參見 HTTP 狀態碼。

HTTP 狀態碼	返回碼	描述
401	`40050`	API Key / API Secret 鑑權失敗，或 API 資料來源已禁用。
400	`40026`	當前專案中已存在同名用戶分群（建立路徑，Metadata 透傳）。
400	`40032`	用戶分群數量已達上限（建立路徑，Metadata 透傳）。
400	`55201`	用戶分群不存在（名單寫入路徑）。
400	`55210`	分群建立方式不支援 REST API 名單寫入：目標分群不是名單上傳建立（如規則建立的分群）。
400	`55211`	分群更新方式不支援 REST API 名單寫入：目標分群不是手動更新。
400	`55212`	分群當前生命週期狀態不支援 REST API 名單寫入：目標分群不在生效中。
400	`55213`	分群當前沒有可用成員版本，暫不支援 REST API 名單寫入。
400	`55214`	不允許用空名單覆蓋分群：`OVERRIDE` 收齊後匹配到的可用用戶為空。
400	`55004`	請求欄位或名單批次引數不符合要求。
503	`55207`	分群後設資料暫不可用。
500	`55000`	服務端內部錯誤。

建立分群時，Metadata 返回的業務錯誤碼和 message 會透傳給呼叫方，例如同名 40026、數量達上限 40032。名單寫入路徑的「分群不存在」返回 55201，不再使用 40027。

未匹配或無效的成員標識不會導致名單操作整體失敗（OVERRIDE 在匹配用戶為空時除外，見 55214）。響應會同時返回數量和最多 100 條標識樣例。樣例可能包含 identityValue，請妥善保護響應資料。