区段定义端点
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调用。
检索区段定义列表 list
您可以通过向/segment/definitions
端点发出GET请求来检索贵组织的所有区段定义的列表。
API格式
/segment/definitions
端点支持多个查询参数以帮助筛选结果。 虽然这些参数是可选的,但强烈建议使用这些参数以帮助减少昂贵的开销。 在不使用参数的情况下调用此端点将检索您的组织可用的所有区段定义。 可以包含多个参数,以&符号(&
)分隔。
GET /segment/definitions
GET /segment/definitions?{QUERY_PARAMETERS}
查询参数
start
start=4
limit
limit=20
page
page=5
sort
evaluationInfo.continuous.enabled
evaluationInfo.continuous.enabled=true
请求
以下请求将检索组织中发布的最后两个区段定义。
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,其中包含指定组织的区段定义列表(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": {}
}
创建新的区段定义 create
您可以通过向/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: {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\""
},
"evaluationInfo": {
"batch": {
"enabled": true
},
"continuous": {
"enabled": false
},
"synchronous": {
"enabled": false
}
},
"schema": {
"name": "_xdm.context.profile"
},
"payloadSchema": "string",
"ttlInDays": 60
}'
name
description
evaluationInfo
evaluationInfo.batch.enabled
设置为true。 如果要创建流区段,请将evaluationInfo.continuous.enabled
设置为true。 如果要创建边缘区段,请将evaluationInfo.synchronous.enabled
设置为true。 如果留空,区段定义将创建为 批次 区段。schema
id
或name
字段组成。expression
expression.type
expression.format
指示值中表达式的结构。 目前,支持以下格式:
pql/text
:区段定义的文本表示形式,根据发布的PQL语法。 例如:workAddress.stateProvince = homeAddress.stateProvince
。
expression.value
expression.format
中指示的类型的表达式。响应
成功的响应会返回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
evaluationInfo
检索特定区段定义 get
您可以通过向/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: {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
name
schema
id
或name
字段组成。expression
expression.type
expression.format
指示值中表达式的结构。 目前,支持以下格式:
pql/text
:区段定义的文本表示形式,根据发布的PQL语法。 例如:workAddress.stateProvince = homeAddress.stateProvince
。
expression.value
expression.format
中指示的类型的表达式。description
evaluationInfo
批量检索区段定义 bulk-get
通过向/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: {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
name
schema
id
或name
字段组成。expression
expression.type
expression.format
指示值中表达式的结构。 目前,支持以下格式:
pql/text
:区段定义的文本表示形式,根据发布的PQL语法。 例如:workAddress.stateProvince = homeAddress.stateProvince
。
expression.value
expression.format
中指示的类型的表达式。description
evaluationInfo
删除特定区段定义 delete
您可以通过向/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: {ORG_ID}' \
-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: {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
}
转换区段定义
您可以通过向/segment/conversion
终结点发出POST请求,将pql/text
和pql/json
或pql/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: {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\"}]}"
}
}