區段定義端點

Adobe Experience Platform可讓您建立區段,從一組描述檔中定義一組特定屬性或行為。 段定義是一個對象,用於封裝寫入Profile Query Language (PQL)中的查詢。 此對象也稱為PQL謂語。 PQL謂語根據與您提供給Real-time Customer Profile的任何記錄或時間系列資料相關的條件定義段規則。 有關編寫PQL查詢的詳細資訊,請參見 PQL指南

本指南提供相關資訊,以協助您進一步瞭解區段定義,並包含使用API執行基本動作的範例API呼叫。

快速入門

本指南中使用的端點是Adobe Experience Platform Segmentation Service API的一部分。 在繼續之前,請參閱快速入門手冊,以取得成功呼叫API所需的重要資訊,包括必要的標題和如何讀取範例API呼叫。

擷取區段定義清單

您可以向/segment/definitions端點提出GET請求,以擷取IMS組織的所有區段定義清單。

API格式

/segment/definitions端點支援數個查詢參數,以協助篩選結果。 雖然這些參數是可選的,但強烈建議使用這些參數以幫助降低昂貴的開銷。 在沒有參數的情況下呼叫此端點將會擷取組織所有可用的區段定義。 可以包括多個參數,用&符號(&)分隔。

GET /segment/definitions
GET /segment/definitions?{QUERY_PARAMETERS}

查詢參數

參數 說明 範例
start 指定傳回之區段定義的起始偏移。 start=4
limit 指定每頁傳回的區段定義數。 limit=20
page 指定區段定義結果將從哪個頁面開始。 page=5
sort 指定要按哪個欄位對結果排序。 以下列格式編寫:[attributeName]:[desc|asc] sort=updateTime:desc
evaluationInfo.continuous.enabled 指定區段定義是否啟用串流。 evaluationInfo.continuous.enabled=true

要求

下列請求將擷取IMS組織中張貼的最後兩個區段定義。

curl -X GET https://platform.adobe.io/data/core/ups/segment/definitions?limit=2 \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

回應

成功的回應會傳回HTTP狀態200,其中包含指定IMS組織的區段定義清單為JSON。

{
    "segments": [
        {
            "id": "3da8bad9-29fb-40e0-b39e-f80322e964de",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "ttlInDays": 30,
            "imsOrgId": "{IMS_ORG}",
            "sandbox": {
                "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
                "sandboxName": "prod",
                "type": "production",
                "default": true
            },
            "name": "segment",
            "description": "",
            "expression": {
                "type": "PQL",
                "format": "pql/json",
                "value": "{PQL_EXPRESSION}"
            },
            "mergePolicyId": "b83185bb-0bc6-489c-9363-0075eb30b4c8",
            "evaluationInfo": {
                "batch": {
                    "enabled": true
                },
                "continuous": {
                    "enabled": false
                },
                "synchronous": {
                    "enabled": false
                }
            },
            "dataGovernancePolicy": {
                "excludeOptOut": true
            },
            "creationTime": 1573253640000,
            "baselineTime": 1574327114,
            "updateEpoch": 1575588309,
            "updateTime": 1575588309000
        },
        {
            "id": "ca763983-5572-4ea4-809c-b7dff7e0d79b",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "ttlInDays": 30,
            "imsOrgId": "{IMS_ORG}",
            "name": "test segment",
            "description": "",
            "expression": {
                "type": "PQL",
                "format": "pql/json",
                "value": "{PQL_EXPRESSION}"
            },
            "mergePolicyId": "b83185bb-0bc6-489c-9363-0075eb30b4c8",
            "evaluationInfo": {
                "batch": {
                    "enabled": true
                },
                "continuous": {
                    "enabled": false
                },
                "synchronous": {
                    "enabled": false
                }
            },
            "dataGovernancePolicy": {
                "excludeOptOut": true
            },
            "creationTime": 1561073779000,
            "baselineTime": 1574327114,
            "updateEpoch": 1574327114,
            "updateTime": 1574327114000
        }
    ],
    "page": {
        "totalCount": 2,
        "totalPages": 1,
        "sortField": "creationTime",
        "sort": "desc",
        "pageSize": 2,
        "limit": 100
    },
    "link": {}
}

建立新的區段定義

您可以向/segment/definitions端點發出POST請求,以建立新段定義。

API格式

POST /segment/definitions

要求

curl -X POST https://platform.adobe.io/data/core/ups/segment/definitions
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'
 -d '{
        "name": "People who ordered in the last 30 days",
        "profileInstanceId": "ups",
        "description": "Last 30 days",
        "expression": {
            "type": "PQL",
            "format": "pql/text",
            "value": "workAddress.country = \"US\""
        },
        "schema": {
            "name": "_xdm.context.profile"
        },
        "payloadSchema": "string",
        "ttlInDays": 60
    }'
屬性 說明
name 必填。 參考區段的唯一名稱。
schema 必填。 與區段中的實體關聯的架構。包含idname欄位。
expression 必填。 包含區段定義之欄位資訊的實體。
expression.type 指定表達式類型。 目前僅支援「PQL」。
expression.format 指示值中表達式的結構。 目前支援下列格式:
  • pql/text:根據發佈的PQL語法對段定義的文本表示。例如 workAddress.stateProvince = homeAddress.stateProvince
expression.value 符合expression.format中指示類型的表達式。
description 定義的人類可讀描述。
注意

段定義表達式也可以引用計算的屬性。 若要瞭解更多資訊,請參閱計算屬性API端點指南

計算屬性功能為alpha,並非所有使用者皆可使用。 檔案和功能可能會有所變更。

回應

成功的回應會傳回HTTP狀態200,並包含您新建立之區段定義的詳細資訊。

{
    "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "ttlInDays": 60,
    "profileInstanceId": "ups",
    "imsOrgId": "{IMS_ORG}",
    "sandbox": {
        "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
        "sandboxName": "prod",
        "type": "production",
        "default": true
    },
    "name": "People who ordered in the last 30 days",
    "description": "Last 30 days",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "workAddress.country = \"US\""
    },
    "evaluationInfo": {
        "batch": {
            "enabled": true
        },
        "continuous": {
            "enabled": false
        },
        "synchronous": {
            "enabled": false
        }
    },
    "dataGovernancePolicy": {
        "excludeOptOut": true
    },
    "creationTime": 0,
    "updateEpoch": 1579292094,
    "updateTime": 1579292094000
}
屬性 說明
id 系統產生的新建區段定義的ID。
evaluationInfo 系統產生的物件,可告知區段定義將進行何種評估。 它可以是批次、連續(也稱為串流)或同步分段。

檢索特定段定義

您可以向/segment/definitions端點提出GET請求,並在請求路徑中提供您要檢索的段定義ID,以檢索有關特定段定義的詳細資訊。

API格式

GET /segment/definitions/{SEGMENT_ID}
參數 說明
{SEGMENT_ID} 要檢索的段定義的id值。

要求

curl -X GET https://platform.adobe.io/data/core/ups/segment/definitions/4afe34ae-8c98-4513-8a1d-67ccaa54bc05 \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

回應

成功的回應會傳回HTTP狀態200,其中包含指定區段定義的詳細資訊。

{
    "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "ttlInDays": 60,
    "profileInstanceId": "ups",
    "imsOrgId": "{IMS_ORG}",
    "sandbox": {
        "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
        "sandboxName": "prod",
        "type": "production",
        "default": true
    },
    "name": "People who ordered in the last 30 days",
    "description": "Last 30 days",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "workAddress.country = \"US\""
    },
    "evaluationInfo": {
        "batch": {
            "enabled": true
        },
        "continuous": {
            "enabled": false
        },
        "synchronous": {
            "enabled": false
        }
    },
    "dataGovernancePolicy": {
        "excludeOptOut": true
    },
    "creationTime": 0,
    "updateEpoch": 1579292094,
    "updateTime": 1579292094000
}
屬性 說明
id 系統產生的區段定義唯讀ID。
name 參考區段的唯一名稱。
schema 與區段中的實體關聯的架構。 包含idname欄位。
expression 包含區段定義之欄位資訊的實體。
expression.type 指定表達式類型。 目前僅支援「PQL」。
expression.format 指示值中表達式的結構。 目前支援下列格式:
  • pql/text:根據發佈的PQL語法對段定義的文本表示。例如 workAddress.stateProvince = homeAddress.stateProvince
expression.value 符合expression.format中指示類型的表達式。
description 定義的人類可讀描述。
evaluationInfo 系統產生的物件,會告訴區段定義將會經歷何種評估、批次、連續(也稱為串流)或同步。

批量檢索段定義

您可以向/segment/definitions/bulk-get端點發出POST請求,並在請求主體中提供段定義的id值,以檢索有關多個指定段定義的詳細資訊。

API格式

POST /segment/definitions/bulk-get

要求

curl -X POST https://platform.adobe.io/data/core/ups/segment/definitions/bulk-get \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "ids": [
            {
                "id": "54669488-03ab-4e0d-a694-37fe49e32be8"
            },
            {
                "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05"
            }
        ]
    }'

回應

成功的回應會傳回HTTP狀態207,並包含請求的區段定義。

{
    "results": {
        "54669488-03ab-4e0d-a694-37fe49e32be8": {
            "id": "54669488-03ab-4e0d-a694-37fe49e32be8",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "ttlInDays": 60,
            "profileInstanceId": "ups",
            "imsOrgId": "{IMS_ORG}",
            "sandbox": {
                "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
                "sandboxName": "prod",
                "type": "production",
                "default": true
            },
            "name": "People who ordered in the last 30 days",
            "description": "Last 30 days",
            "expression": {
                "type": "PQL",
                "format": "pql/text",
                "value": "workAddress.country = \"US\""
            },
            "evaluationInfo": {
                "batch": {
                    "enabled": true
                },
                "continuous": {
                    "enabled": false
                },
                "synchronous": {
                    "enabled": false
                }
            },
            "dataGovernancePolicy": {
                "excludeOptOut": true
            },
            "creationTime": 0,
            "updateEpoch": 1579292094,
            "updateTime": 1579292094000
        },
        "4afe34ae-8c98-4513-8a1d-67ccaa54bc05": {
            "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "ttlInDays": 60,
            "profileInstanceId": "ups",
            "imsOrgId": "{IMS_ORG}",
            "sandbox": {
                "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
                "sandboxName": "prod",
                "type": "production",
                "default": true
            },
            "name": "People who ordered in the last 30 days",
            "description": "Last 30 days",
            "expression": {
                "type": "PQL",
                "format": "pql/text",
                "value": "workAddress.country = \"US\""
            },
            "evaluationInfo": {
                "batch": {
                    "enabled": true
                },
                "continuous": {
                    "enabled": false
                },
                "synchronous": {
                    "enabled": false
                }
            },
            "dataGovernancePolicy": {
                "excludeOptOut": true
            },
            "creationTime": 0,
            "updateEpoch": 1579292094,
            "updateTime": 1579292094000
        }

    }
}
屬性 說明
id 系統產生的區段定義唯讀ID。
name 參考區段的唯一名稱。
schema 與區段中的實體關聯的架構。 包含idname欄位。
expression 包含區段定義之欄位資訊的實體。
expression.type 指定表達式類型。 目前僅支援「PQL」。
expression.format 指示值中表達式的結構。 目前支援下列格式:
  • pql/text:根據發佈的PQL語法對段定義的文本表示。例如 workAddress.stateProvince = homeAddress.stateProvince
expression.value 符合expression.format中指示類型的表達式。
description 定義的人類可讀描述。
evaluationInfo 系統產生的物件,會告訴區段定義將會經歷何種評估、批次、連續(也稱為串流)或同步。

刪除特定的段定義

您可以向/segment/definitions端點提出DELETE請求,並在請求路徑中提供您要刪除的區段定義ID,以請求刪除特定的區段定義。

API格式

DELETE /segment/definitions/{SEGMENT_ID}
參數 說明
{SEGMENT_ID} 要刪除的區段定義的id值。

要求

curl -X DELETE https://platform.adobe.io/data/core/ups/segment/definitions/4afe34ae-8c98-4513-8a1d-67ccaa54bc05 \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

回應

成功的回應會傳回HTTP狀態200,但無訊息。

更新特定區段定義

您可以更新特定區段定義,方法是向/segment/definitions端點提出PATCH請求,並在請求路徑中提供您要更新的區段定義ID。

API格式

PATCH /segment/definitions/{SEGMENT_ID}
參數 說明
{SEGMENT_ID} 您要更新的區段定義的id值。

要求

下列要求會將工作地址國家/地區從美國更新至加拿大。

curl -X PATCH https://platform.adobe.io/data/core/ups/segment/definitions/4afe34ae-8c98-4513-8a1d-67ccaa54bc05 \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -d '
{
    "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
    "name": "Updated people who ordered in the last 30 days",
    "profileInstanceId": "ups",
    "description": "Last 30 days",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "workAddress.country = \"CA\""
    },
    "schema": {
        "name": "_xdm.context.profile"
    },
    "payloadSchema": "string",
    "ttlInDays": 60,
    "creationTime": 0,
    "updateTime": 0,
    "updateEpoch": 0
}'

回應

成功的回應會傳回HTTP狀態200,並包含您最近更新的區段定義的詳細資訊。 請注意,工作地址國家/地區如何從美國(美國)更新至加拿大(CA)。

{
    "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "ttlInDays": 60,
    "profileInstanceId": "ups",
    "imsOrgId": "{IMS_ORG}",
    "sandbox": {
        "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
        "sandboxName": "prod",
        "type": "production",
        "default": true
    },
    "name": "Updated people who ordered in the last 30 days",
    "description": "Last 30 days",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "workAddress.country = \"CA\""
    },
    "evaluationInfo": {
        "batch": {
            "enabled": true
        },
        "continuous": {
            "enabled": false
        },
        "synchronous": {
            "enabled": false
        }
    },
    "dataGovernancePolicy": {
        "excludeOptOut": true
    },
    "creationTime": 0,
    "updateEpoch": 1579295340,
    "updateTime": 1579295340000
}

轉換區段定義

您可以向/segment/conversion端點發出POST請求,將pql/textpql/jsonpql/json之間的段定義轉換為pql/text

API格式

POST /segment/conversion

要求

下列請求會將區段定義的格式從pql/text變更為pql/json

curl -X POST https://platform.adobe.io/data/core/ups/segment/conversion \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'
 -d '{
        "name": "People who ordered in the last 30 days",
        "profileInstanceId": "ups",
        "description": "Last 30 days",
        "expression": {
            "type": "PQL",
            "format": "pql/text",
            "value": "workAddress.country = \"US\""
        },
        "schema": {
            "name": "_xdm.context.profile"
        },
        "payloadSchema": "string",
        "ttlInDays": 60
    }'

回應

成功的回應會傳回HTTP狀態200,並包含您新轉換的區段定義的詳細資訊。

{
    "ttlInDays": 60,
    "imsOrgId": "6A29340459CA8D350A49413A@AdobeOrg",
    "sandbox": {
        "sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
        "sandboxName": "prod",
        "type": "production",
        "default": true
    },
    "description": "Last 30 days",
    "expression": {
        "type": "PQL",
        "format": "pql/json",
        "value": "{\"nodeType\":\"fnApply\",\"fnName\":\"=\",\"params\":[{\"nodeType\":\"fieldLookup\",\"fieldName\":\"country\",\"object\":{\"nodeType\":\"fieldLookup\",\"fieldName\":\"workAddress\",\"object\":{\"nodeType\":\"parameterReference\",\"position\":1}}},{\"nodeType\":\"literal\",\"literalType\":\"String\",\"value\":\"US\"}]}"
    }
}

後續步驟

閱讀本指南後,您現在可以進一步瞭解區段定義的運作方式。 如需建立區段的詳細資訊,請參閱建立區段教學課程。

本頁內容

Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now