段定義終結點

Adobe Experience Platform允許您建立段,從一組配置檔案中定義一組特定屬性或行為。 段定義是封裝寫入的查詢的對象 Profile Query Language (PQL)。 此對象也稱為PQL謂詞。 PQL謂語基於與提供給的任何記錄或時間序列資料相關的條件,定義段的規則 Real-time Customer Profile。 查看 PQL指南 的子菜單。

本指南提供資訊以幫助您更好地瞭解段定義,並包括使用API執行基本操作的示例API調用。

快速入門

本指南中使用的端點是 Adobe Experience Platform Segmentation Service API。 在繼續之前,請查看 入門指南 要成功調用API,您需要瞭解的重要資訊,包括必需的標頭以及如何讀取示例API調用。

檢索段定義清單

通過向IMS組織發出GET請求,您可以檢索IMS組織的所有段定義的清單 /segment/definitions 端點。

API格式

/segment/definitions 終結點支援多個查詢參數以幫助篩選結果。 雖然這些參數是可選的,但強烈建議使用它們以幫助降低昂貴的開銷。 調用此終結點時不使用任何參數將檢索組織可用的所有段定義。 可以包括多個參數,用和符號分隔(&)。

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

查詢參數

參數 說明 範例
start 指定返回的段定義的起始偏移。 start=4
limit 指定每頁返回的段定義數。 limit=20
page 指定段定義結果將從哪個頁開始。 page=5
sort 指定要按哪個欄位對結果排序。 以下格式寫入: `[attributeName]:[desc asc]`。
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: {ORG_ID}' \
 -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": "{ORG_ID}",
            "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": "{ORG_ID}",
            "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": {}
}

建立新段定義

可通過向Web站點發出POST請求來建立新段定義 /segment/definitions 端點。

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: {ORG_ID}' \
 -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": "{ORG_ID}",
    "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 系統生成的對象,它告訴段定義將進行的評估類型。 它可以是批處理、連續(也稱為流)或同步分段。

檢索特定段定義

可通過向Web站點發出GET請求來檢索有關特定段定義的詳細資訊 /segment/definitions 端點,並提供要在請求路徑中檢索的段定義的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: {ORG_ID}' \
 -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": "{ORG_ID}",
    "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 系統生成的對象,它告訴段定義將經歷的評估類型、批處理、連續(也稱為流)或同步。

批量檢索段定義

可通過向以下對象發出POST請求來檢索有關多個指定段定義的詳細資訊 /segment/definitions/bulk-get 端點和提供 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: {ORG_ID}' \
  -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": "{ORG_ID}",
            "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": "{ORG_ID}",
            "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 端點,並提供要在請求路徑中刪除的段定義的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: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

回應

成功的響應返回HTTP狀態200,無消息。

更新特定段定義

您可以通過向以下對象發出PATCH請求來更新特定段定義 /segment/definitions 端點,並提供要在請求路徑中更新的段定義的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: {ORG_ID}' \
 -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": "{ORG_ID}",
    "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
}

轉換段定義

可以在以下時間之間轉換段定義 pql/textpql/jsonpql/jsonpql/text 通過向POST /segment/conversion 端點。

API格式

POST /segment/conversion

要求

以下請求將更改段定義的格式 pql/textpql/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: {ORG_ID}' \
 -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\"}]}"
    }
}

後續步驟

閱讀本指南後,您現在對段定義的工作方式有了更好的瞭解。 有關建立段的詳細資訊,請閱讀 建立段 教程。

本頁內容