段作業是一個非同步過程,可按需建立訪問群體段。 它引用 段定義,以及 合併策略 控制方式 Real-time Customer Profile 合併配置檔案片段中重疊的屬性。 當網段作業成功完成時,您可以收集有關網段的各種資訊,如處理過程中可能發生的任何錯誤以及受眾的最終大小。
本指南提供資訊以幫助您更好地瞭解段作業,並包括使用API執行基本操作的示例API調用。
本指南中使用的端點是 Adobe Experience Platform Segmentation Service API。 在繼續之前,請查看 入門指南 要成功調用API,您需要瞭解的重要資訊,包括必需的標頭以及如何讀取示例API調用。
通過向IMS組織發出GET請求,您可以檢索IMS組織的所有段作業清單 /segment/jobs
端點。
API格式
的 /segment/jobs
終結點支援多個查詢參數以幫助篩選結果。 雖然這些參數是可選的,但強烈建議使用它們以幫助降低昂貴的開銷。 調用此終結點時沒有參數將檢索組織可用的所有導出作業。 可以包括多個參數,用和符號分隔(&
)。
GET /segment/jobs
GET /segment/jobs?{QUERY_PARAMETERS}
查詢參數
參數 | 說明 | 範例 |
---|---|---|
start |
指定返回的段作業的起始偏移。 | start=1 |
limit |
指定每頁返回的段作業數。 | limit=20 |
status |
根據狀態篩選結果。 支援的值為NEW、QUEUDED、PROCESSING、SUCCEEDED、FAILED、CANCELED、CANCELED | status=NEW |
sort |
對返回的段作業進行訂單。 以格式寫入 `[attributeName]:[desc | asc]`。 |
property |
篩選器分段作業並獲取給定篩選器的準確匹配項。 它可以以下列格式之一寫入:
|
property=segments~segmentId==workInUS |
要求
curl -X GET https://platform.adobe.io/data/core/ups/segment/jobs?status=SUCCEEDED \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
回應
成功的響應返回HTTP狀態200,其中列出指定IMS組織的段作業清單為JSON。 以下響應返回IMS組織所有成功的段作業的清單。
以下響應已被截斷空間,將只顯示第一個返回的作業。
{
"_page": {
"totalCount": 14,
"pageSize": 14
},
"children": [
{
"id": "b31aed3d-b3b1-4613-98c6-7d3846e8d48f",
"imsOrgId": "E95186D65A28ABF00A495D82@AdobeOrg",
"sandbox": {
"sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
"sandboxName": "prod",
"type": "production",
"default": true
},
"profileInstanceId": "ups",
"source": "scheduler",
"status": "SUCCEEDED",
"batchId": "678f53bc-e21d-4c47-a7ec-5ad0064f8e4c",
"computeJobId": 8811,
"computeGatewayJobId": "9ea97b25-a0f5-410e-ae87-b2d85e58f399",
"segments": [
{
"segmentId": "30230300-ccf1-48ad-8012-c5563a007069",
"segment": {
"id": "30230300-ccf1-48ad-8012-c5563a007069",
"expression": {
"type": "PQL",
"format": "pql/json",
"value": "{PQL_EXPRESSION}"
},
"mergePolicyId": "25c548a0-ca7f-4dcd-81d5-997642f178b9",
"mergePolicy": {
"id": "25c548a0-ca7f-4dcd-81d5-997642f178b9",
"version": 1
}
}
}
],
"metrics": {
"totalTime": {
"startTimeInMs": 1573203617195,
"endTimeInMs": 1573204395655,
"totalTimeInMs": 778460
},
"profileSegmentationTime": {
"startTimeInMs": 1573204266727,
"endTimeInMs": 1573204395655,
"totalTimeInMs": 128928
},
"totalProfiles":13146432,
"segmentedProfileCounter":{
"94509dba-7387-452f-addc-5d8d979f6ae8":1033
},
"segmentedProfileByNamespaceCounter":{
"94509dba-7387-452f-addc-5d8d979f6ae8":{
"tenantiduserobjid":1033,
"campaign_profile_mscom_mkt_prod2":1033
}
},
"segmentedProfileByStatusCounter":{
"94509dba-7387-452f-addc-5d8d979f6ae8":{
"exited":144646,
"existing":10,
"realized":2056
}
},
"totalProfilesByMergePolicy":{
"25c548a0-ca7f-4dcd-81d5-997642f178b9":13146432
}
},
"requestId": "4e538382-dbd8-449e-988a-4ac639ebe72b-1573203600264",
"schema": {
"name": "_xdm.context.profile"
},
"properties": {
"scheduleId": "4e538382-dbd8-449e-988a-4ac639ebe72b",
"runId": "e6c1308d-0d4b-4246-b2eb-43697b50a149"
},
"_links": {
"cancel": {
"href": "/segment/jobs/b31aed3d-b3b1-4613-98c6-7d3846e8d48f",
"method": "DELETE"
},
"checkStatus": {
"href": "/segment/jobs/b31aed3d-b3b1-4613-98c6-7d3846e8d48f",
"method": "GET"
}
},
"updateTime": 1573204395000,
"creationTime": 1573203600535,
"updateEpoch": 1573204395
}
],
"_links": {
"next": {}
}
}
屬性 | 說明 |
---|---|
id |
段作業的系統生成的只讀標識符。 |
status |
段任務的當前狀態。 狀態的潛在值包括「NEW」、「PROCESSING」、「CANCELLED」、「CANCELLED」、「FAILED」和「SUCCEEDED」。 |
segments |
包含有關在段作業中返回的段定義的資訊的對象。 |
segments.segment.id |
段定義的ID。 |
segments.segment.expression |
包含有關段定義表達式的資訊的對象,用PQL編寫。 |
metrics |
包含有關段作業的診斷資訊的對象。 |
metrics.totalTime |
包含分段作業啟動和結束時間以及所用總時間的資訊的對象。 |
metrics.profileSegmentationTime |
包含分段評估開始和結束的時間以及所用總時間的資訊的對象。 |
metrics.segmentProfileCounter |
按段基準限定的配置檔案數。 |
metrics.segmentedProfileByNamespaceCounter |
每個段上每個標識命名空間限定的配置檔案數。 |
metrics.segmentProfileByStatusCounter |
每個狀態的配置檔案計數。 支援以下三種狀態:
|
metrics.totalProfilesByMergePolicy |
每個合併策略的合併配置檔案總數。 |
您可以通過向以下站點發出POST請求來建立新段任務 /segment/jobs
端點,並在主體中包括要從中建立新受眾的段定義的ID。
API格式
POST /segment/jobs
要求
curl -X POST https://platform.adobe.io/data/core/ups/segment/jobs \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '
[
{
"segmentId": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
}
]'
屬性 | 說明 |
---|---|
segmentId |
要為其建立段作業的段定義的ID。 這些段定義可以屬於不同的合併策略。 有關段定義的詳細資訊,請參閱 段定義端點指南。 |
回應
成功的響應返回HTTP狀態200,其中包含新建立的段作業的詳細資訊。
{
"id": "d3b4a50d-dfea-43eb-9fca-557ea53771fd",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
"sandboxName": "prod",
"type": "production",
"default": true
},
"profileInstanceId": "ups",
"source": "api",
"status": "NEW",
"segments": [
{
"segmentId": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
"segment": {
"id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "workAddress.country = \"US\""
},
"mergePolicyId": "e161dae9-52f0-4c7f-b264-dc43dd903d56",
"mergePolicy": {
"id": "e161dae9-52f0-4c7f-b264-dc43dd903d56",
"version": 1
}
}
}
],
"requestId": "Hw1jdAHeuWHVKVxcAPFrLCbbjkriDl9v",
"schema": {
"name": "_xdm.context.profile"
},
"_links": {
"cancel": {
"href": "/segment/jobs/d3b4a50d-dfea-43eb-9fca-557ea53771fd",
"method": "DELETE"
},
"checkStatus": {
"href": "/segment/jobs/d3b4a50d-dfea-43eb-9fca-557ea53771fd",
"method": "GET"
}
},
"updateTime": 1579304260000,
"creationTime": 1579304260897,
"updateEpoch": 1579304260
}
屬性 | 說明 |
---|---|
id |
新建立的段作業的系統生成的只讀標識符。 |
status |
段任務的當前狀態。 由於段作業是新建立的,因此狀態始終為「NEW」。 |
segments |
包含有關此段作業正為其運行的段定義的資訊的對象。 |
segments.segment.id |
提供的段定義的ID。 |
segments.segment.expression |
包含有關段定義表達式的資訊的對象,用PQL編寫。 |
通過向Web站點發出GET請求,可檢索有關特定段作業的詳細資訊 /segment/jobs
端點,並提供要在請求路徑中檢索的段作業的ID。
API格式
GET /segment/jobs/{SEGMENT_JOB_ID}
屬性 | 說明 |
---|---|
{SEGMENT_JOB_ID} |
的 id 要檢索的段作業的值。 |
要求
curl -X GET https://platform.adobe.io/data/core/ups/segment/jobs/d3b4a50d-dfea-43eb-9fca-557ea53771fd \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
回應
成功的響應返回HTTP狀態200,其中包含有關指定段作業的詳細資訊。
{
"id": "d3b4a50d-dfea-43eb-9fca-557ea53771fd",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
"sandboxName": "prod",
"type": "production",
"default": true
},
"profileInstanceId": "ups",
"source": "api",
"status": "SUCCEEDED",
"batchId": "651fc109-3963-48d2-aa98-9e3cc2003bac",
"computeJobId": 39312,
"computeGatewayJobId": "a0099ab6-11ab-4c2b-a0ea-6162e16806bd",
"segments": [
{
"segmentId": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
"segment": {
"id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "workAddress.country = \"US\""
},
"mergePolicyId": "e161dae9-52f0-4c7f-b264-dc43dd903d56",
"mergePolicy": {
"id": "e161dae9-52f0-4c7f-b264-dc43dd903d56",
"version": 1
}
}
}
],
"metrics": {
"totalTime": {
"startTimeInMs": 1579304313411
},
"profileSegmentationTime": {}
},
"requestId": "Hw1jdAHeuWHVKVxcAPFrLCbbjkriDl9v",
"schema": {
"name": "_xdm.context.profile"
},
"_links": {
"cancel": {
"href": "/segment/jobs/d3b4a50d-dfea-43eb-9fca-557ea53771fd",
"method": "DELETE"
},
"checkStatus": {
"href": "/segment/jobs/d3b4a50d-dfea-43eb-9fca-557ea53771fd",
"method": "GET"
}
},
"updateTime": 1579304339000,
"creationTime": 1579304260897,
"updateEpoch": 1579304339
}
屬性 | 說明 |
---|---|
id |
段作業的系統生成的只讀標識符。 |
status |
段任務的當前狀態。 狀態的潛在值包括「NEW」、「PROCESSING」、「CANCELLED」、「CANCELLED」、「FAILED」和「SUCCEEDED」。 |
segments |
包含有關在段作業中返回的段定義的資訊的對象。 |
segments.segment.id |
段定義的ID。 |
segments.segment.expression |
包含有關段定義表達式的資訊的對象,用PQL編寫。 |
metrics |
包含有關段作業的診斷資訊的對象。 |
您可以通過向以下對象發出POST請求來檢索有關多個段作業的詳細資訊: /segment/jobs/bulk-get
端點和提供 id
請求正文中段作業的值。
API格式
POST /segment/jobs/bulk-get
要求
curl -X POST https://platform.adobe.io/data/core/ups/segment/jobs/bulk-get \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"ids": [
{
"id": "cc3419d3-0389-47f1-b174-fead6b3c830d"
},
{
"id": "c527dc3f-07fe-4b96-be4e-23f38e734ff8"
}
]
}'
回應
成功的響應將返回HTTP狀態207,並返回請求的段作業。
以下響應已被截斷,僅顯示每個段作業的部分詳細資訊。 完整響應將列出請求的段作業的完整詳細資訊。
{
"results": {
"cc3419d3-0389-47f1-b174-fead6b3c830d": {
"id": "cc3419d3-0389-47f1-b174-fead6b3c830d",
"imsOrgId": "{ORG_ID}",
"status": "SUCCEEDED",
"segments": [
{
"segmentId": "30230300-ccf1-48ad-8012-c5563a007069",
"segment": {
"id": "30230300-ccf1-48ad-8012-c5563a007069",
"expression": {
"type": "PQL",
"format": "pql/json",
"value": "{PQL_EXPRESSION}"
},
"mergePolicyId": "b83185bb-0bc6-489c-9363-0075eb30b4c8",
"mergePolicy": {
"id": "b83185bb-0bc6-489c-9363-0075eb30b4c8",
"version": 1
}
}
}
],
"updateTime": 1573204395000,
"creationTime": 1573203600535,
"updateEpoch": 1573204395
},
"c527dc3f-07fe-4b96-be4e-23f38e734ff8": {
"id": "c527dc3f-07fe-4b96-be4e-23f38e734ff8",
"imsOrgId": "{ORG_ID}",
"status": "SUCCEEDED",
"segments": [
{
"segmentId": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
"segment": {
"id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
"expression": {
"type": "PQL",
"format": "pql/json",
"value": "{PQL_EXPRESSION}"
},
"mergePolicyId": "b83185bb-0bc6-489c-9363-0075eb30b4c8",
"mergePolicy": {
"id": "b83185bb-0bc6-489c-9363-0075eb30b4c8",
"version": 1
}
}
}
],
"updateTime": 1573204395000,
"creationTime": 1573203600535,
"updateEpoch": 1573204395
}
}
}
屬性 | 說明 |
---|---|
id |
段作業的系統生成的只讀標識符。 |
status |
段任務的當前狀態。 狀態的潛在值包括「NEW」、「PROCESSING」、「CANCELLED」、「CANCELLED」、「FAILED」和「SUCCEEDED」。 |
segments |
包含有關在段作業中返回的段定義的資訊的對象。 |
segments.segment.id |
段定義的ID。 |
segments.segment.expression |
包含有關段定義表達式的資訊的對象,用PQL編寫。 |
您可以通過向DELETE請求刪除特定段作業 /segment/jobs
端點,並提供要在請求路徑中刪除的段作業的ID。
對刪除請求的API響應是立即的。 但是,實際刪除段作業是非同步的。 換句話說,在對段作業發出刪除請求和應用刪除請求之間存在時間差。
API格式
DELETE /segment/jobs/{SEGMENT_JOB_ID}
屬性 | 說明 |
---|---|
{SEGMENT_JOB_ID} |
的 id 要刪除的段作業的值。 |
要求
curl -X DELETE https://platform.adobe.io/data/core/ups/segment/jobs/d3b4a50d-dfea-43eb-9fca-557ea53771fd \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
回應
成功響應返回HTTP狀態204,並返回以下資訊。
{
"status": true,
"message": "Segment job with id 'd3b4a50d-dfea-43eb-9fca-557ea53771fd' has been marked for cancelling"
}
閱讀本指南後,您現在對細分工作的工作方式有了更深入的瞭解。