本文档中概述的计算属性功能当前位于alpha中,并非所有用户都可用。 文档和功能可能会发生变化。
计算属性是用于将事件级别数据聚合到配置文件级别属性中的函数。 这些函数会自动计算,以便在分段、激活和个性化期间使用。 本指南包含使用执行基本CRUD操作的示例API调用 /computedAttributes
端点。
要了解有关计算属性的更多信息,请首先阅读 计算属性概述.
本指南中使用的API端点是 实时客户资料API.
在继续之前,请查看 配置文件API快速入门指南 有关推荐文档的链接,请参阅本文档中显示的示例API调用指南,以及有关成功调用任何Experience PlatformAPI所需标头的重要信息。
要创建计算属性,您首先需要在架构中标识将包含计算属性值的字段。
请参阅 配置计算属性 有关在架构中创建计算属性字段的完整端到端指南。
要继续阅读API指南,您必须配置一个计算属性字段。
现在,通过在启用配置文件的架构中定义计算属性字段,可以配置计算属性。 如果您尚未执行此操作,请按照 配置计算属性 文档。
要创建计算属性,请首先向 /config/computedAttributes
终结点,其请求正文包含您要创建的计算属性的详细信息。
API格式
POST /config/computedAttributes
请求
curl -X POST \
https://platform.adobe.io/data/core/ups/config/computedAttributes \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}'\
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "birthdayCurrentMonth",
"path": "_{TENANT_ID}",
"description": "Computed attribute to capture if the customer birthday is in the current month.",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "person.birthDate.getMonth() = currentMonth()"
},
"schema":
{
"name":"_xdm.context.profile"
}
}'
属性 | 描述 |
---|---|
name |
作为字符串的计算属性字段的名称。 |
path |
包含计算属性的字段的路径。 此路径可在 properties 属性,且不应在路径中包含字段名称。 写入路径时,请忽略 properties 属性。 |
{TENANT_ID} |
如果您不熟悉租户ID,请参阅 架构注册开发人员指南. |
description |
计算属性的描述。 在定义了多个计算属性后,此功能特别有用,因为它将帮助IMS组织内的其他人确定要使用的正确计算属性。 |
expression.value |
有效 Profile Query Language (PQL)表达式。 计算属性当前支持以下函数:sum、count、min、max和boolean。 有关示例表达式的列表,请参阅 示例PQL表达式 文档。 |
schema.name |
包含计算属性字段的架构所基于的类。 示例: _xdm.context.experienceevent ,用于基于XDM ExperienceEvent类的架构。 |
响应
成功创建的计算属性会返回HTTP状态200(确定)和包含新创建计算属性详细信息的响应主体。 这些详细信息包括系统生成的唯一只读 id
,可用于在其他API操作期间引用计算属性。
{
"id": "2afcf410-450e-4a39-984d-2de99ab58877",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "{SANDBOX_ID}",
"sandboxName": "prod",
"type": "production",
"default": true
},
"name": "birthdayCurrentMonth",
"path": "_{TENANT_ID}",
"positionPath": [
"_{TENANT_ID}"
],
"description": "Computed attribute to capture if the customer birthday is in the current month.",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "person.birthDate.getMonth() = currentMonth()"
},
"schema": {
"name": "_xdm.context.profile"
},
"returnSchema": {
"meta:xdmType": "string"
},
"definedOn": [
{
"meta:resourceType": "unions",
"meta:containerId": "tenant",
"$ref": "https://ns.adobe.com/xdm/context/profile__union"
}
],
"encodedDefinedOn":"?\b?VR)JMS?R?())(????+?KL?OJ?K???H??O??+I?(?/(?O??I??/????S?8{?E:",
"dependencies": [],
"dependents": [],
"active": true,
"type": "ComputedAttribute",
"createEpoch": 1572555223,
"updateEpoch": 1572555225
}
属性 | 描述 |
---|---|
id |
唯一的只读系统生成的ID,可用于在其他API操作期间引用计算的属性。 |
imsOrgId |
与计算属性相关的IMS组织应与请求中发送的值匹配。 |
sandbox |
沙盒对象包含在其中配置计算属性的沙盒的详细信息。 此信息来自请求中发送的沙盒标头。 有关详细信息,请参阅 沙箱概述. |
positionPath |
包含被解构的数组 path 到请求中发送的字段。 |
returnSchema.meta:xdmType |
存储计算属性的字段类型。 |
definedOn |
一个数组,用于显示已定义计算属性的并集架构。 每个并集架构包含一个对象,这意味着如果计算的属性已基于不同类添加到多个架构,则数组中可能有多个对象。 |
active |
一个布尔值,用于显示计算的属性当前是否处于活动状态。 默认情况下,该值为 true 。 |
type |
创建的资源类型,在此例中,“ComputedAttribute”是默认值。 |
createEpoch 和 updateEpoch |
分别创建和上次更新计算属性的时间。 |
也可以创建引用现有计算属性的计算属性。 为此,请首先向 /config/computedAttributes
端点。 请求正文将包含对 expression.value
字段,如以下示例中所示。
API格式
POST /config/computedAttributes
请求
在此示例中,已创建两个计算属性,将用于定义第三个属性。 现有的计算属性包括:
totalSpend
: 捕获客户已花费的总美元金额。countPurchases
: 计算客户的购买次数。以下请求引用两个现有的计算属性,使用有效的PQL进行除以计算新属性 averageSpend
计算属性。
curl -X POST \
https://platform.adobe.io/data/core/ups/config/computedAttributes \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}'\
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "averageSpend",
"path": "_{TENANT_ID}.purchaseSummary",
"description": "Computed attribute to capture the average dollar amount that a customer spends on each purchase.",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "_{TENANT_ID}.purchaseSummary.totalSpend/_{TENANT_ID}.purchaseSummary.countPurchases"
},
"schema":
{
"name":"_xdm.context.profile"
}
}'
属性 | 描述 |
---|---|
name |
作为字符串的计算属性字段的名称。 |
path |
包含计算属性的字段的路径。 此路径可在 properties 属性,且不应在路径中包含字段名称。 写入路径时,请忽略 properties 属性。 |
{TENANT_ID} |
如果您不熟悉租户ID,请参阅 架构注册开发人员指南. |
description |
计算属性的描述。 在定义了多个计算属性后,此功能特别有用,因为它将帮助IMS组织内的其他人确定要使用的正确计算属性。 |
expression.value |
有效的PQL表达式。 计算属性当前支持以下函数:sum、count、min、max和boolean。 有关示例表达式的列表,请参阅 示例PQL表达式 文档。 在此示例中,表达式引用了两个现有的计算属性。 属性使用 path 和 name 中显示的计算属性,在其中定义了计算属性的架构中。 例如, path 第一个引用的计算属性的 _{TENANT_ID}.purchaseSummary 和 name is totalSpend . |
schema.name |
包含计算属性字段的架构所基于的类。 示例: _xdm.context.experienceevent ,用于基于XDM ExperienceEvent类的架构。 |
响应
成功创建的计算属性会返回HTTP状态200(确定)和包含新创建计算属性详细信息的响应主体。 这些详细信息包括系统生成的唯一只读 id
,可用于在其他API操作期间引用计算属性。
{
"id": "2afcf410-450e-4a39-984d-2de99ab58877",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "{SANDBOX_ID}",
"sandboxName": "{SANDBOX_NAME}",
"type": "production",
"default": true
},
"name": "averageSpend",
"path": "_{TENANT_ID}.purchaseSummary",
"positionPath": [
"_{TENANT_ID}",
"purchaseSummary"
],
"description": "Computed attribute to capture the average dollar amount that a customer spends on each purchase.",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "_{TENANT_ID}.purchaseSummary.totalSpend/_{TENANT_ID}.purchaseSummary.countPurchases"
},
"schema": {
"name": "_xdm.context.profile"
},
"returnSchema": {
"meta:xdmType": "number"
},
"definedOn": [
{
"meta:resourceType": "unions",
"meta:containerId": "tenant",
"$ref": "https://ns.adobe.com/xdm/context/profile__union"
}
],
"encodedDefinedOn":"\bVR)JMSR())(+KLOJKկHO+I(/(OI/S8{E:",
"dependencies": [
"c08a92f3-2418-4a3d-89d0-96f15fda3e5d",
"4ed9e3aa-57ae-4705-9e8a-7fba9a6a7010"
],
"dependents": [],
"active": true,
"evaluationInfo": {
"batch": {
"enabled": false
},
"continuous": {
"enabled": true
},
"synchronous": {
"enabled": false
}
},
"type": "ComputedAttribute",
"createEpoch": 1613696592,
"updateEpoch": 1613696593
}
属性 | 描述 |
---|---|
id |
唯一的只读系统生成的ID,可用于在其他API操作期间引用计算的属性。 |
imsOrgId |
与计算属性相关的IMS组织应与请求中发送的值匹配。 |
sandbox |
沙盒对象包含在其中配置计算属性的沙盒的详细信息。 此信息来自请求中发送的沙盒标头。 有关详细信息,请参阅 沙箱概述. |
positionPath |
包含被解构的数组 path 到请求中发送的字段。 |
returnSchema.meta:xdmType |
存储计算属性的字段类型。 |
definedOn |
一个数组,用于显示已定义计算属性的并集架构。 每个并集架构包含一个对象,这意味着如果计算的属性已基于不同类添加到多个架构,则数组中可能有多个对象。 |
active |
一个布尔值,用于显示计算的属性当前是否处于活动状态。 默认情况下,该值为 true 。 |
type |
创建的资源类型,在此例中,“ComputedAttribute”是默认值。 |
createEpoch 和 updateEpoch |
分别创建和上次更新计算属性的时间。 |
使用API处理计算属性时,有两个选项可用于访问您的组织已定义的计算属性。 第一个是列出所有计算属性,第二个是通过其唯一性查看特定计算属性 id
.
本文档概述了两种访问模式的步骤。 选择以下选项之一开始:
您的IMS组织可以创建多个计算属性,并对 /config/computedAttributes
端点允许您列出组织的所有现有计算属性。
API格式
GET /config/computedAttributes
请求
curl -X GET \
https://platform.adobe.io/data/core/ups/config/computedAttributes/ \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
响应
成功的响应包括 _page
提供计算属性总数的属性(totalCount
)以及页面上计算属性的数量(pageSize
)。
响应还包括 children
由一个或多个对象组成的数组,每个对象包含一个计算属性的详细信息。 如果贵组织没有任何计算属性,则 totalCount
和 pageSize
将为0(零),并且 children
数组将为空。
{
"_page": {
"totalCount": 2,
"pageSize": 2
},
"children": [
{
"id": "2afcf410-450e-4a39-984d-2de99ab58877",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
"sandboxName": "prod",
"type": "production",
"default": true
},
"name": "birthdayCurrentMonth",
"path": "person._{TENANT_ID}",
"positionPath": [
"person",
"_{TENANT_ID}"
],
"description": "Computed attribute to capture if the customer birthday is in the current month.",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "person.birthDate.getMonth() = currentMonth()"
},
"schema": {
"name": "_xdm.context.profile"
},
"returnSchema": {
"meta:xdmType": "string"
},
"definedOn": [
{
"meta:resourceType": "unions",
"meta:containerId": "tenant",
"$ref": "https://ns.adobe.com/xdm/context/profile__union"
}
],
"encodedDefinedOn":"?\b?VR)JMS?R?())(????+?KL?OJ?K???H??O??+I?(?/(?O??I??/????S?8{?E:",
"dependencies": [],
"dependents": [],
"active": true,
"type": "ComputedAttribute",
"createEpoch": 1572555223,
"updateEpoch": 1572555225
},
{
"id": "ae0c6552-cf49-4725-8979-116366e8e8d3",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "",
"sandboxName": "",
"type": "production",
"default": true
},
"name": "productDownloads",
"path": "_{TENANT_ID}",
"positionPath": [
"_{TENANT_ID}"
],
"description": "Calculate total product downloads.",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "let Y = xEvent[_coresvc.event.subType = \"DOWNLOAD\"].groupBy(_coresvc.attributes[name = \"product\"].value).map({
\"downloaded\": this.head()._coresvc.attributes[name = \"product\"].head().value,
\"downloadsSum\": this.count(),
\"downloadsToday\": this[timestamp occurs today].count(),
\"downloadsPast30Days\": this[timestamp occurs < 30 days before now].count(),
\"downloadsPast60Days\": this[timestamp occurs < 60 days before now].count(),
\"downloadsPast90Days\": this[timestamp occurs < 90 days before now].count() }) in { \"uniqueProductDownloadSum\": Y.count(), \"products\": Y }"
},
"returnSchema": {
"meta:xdmType": "string"
},
"definedOn": [
{
"meta:resourceType": "unions",
"meta:containerId": "tenant",
"$ref": "https://ns.adobe.com/xdm/context/profile__union"
}
],
"schema": {
"name": "_xdm.context.profile"
},
"encodedDefinedOn": "\u001f?\b\u0000\u0000\u0000\u0000\u0000\u0000\u0000?VR)JMS?R?())(????+?KL?OJ?K???H??O??+I?(?/(?O??I??/????S?\u0005\u00008{?E:\u0000\u0000\u0000",
"dependencies": [],
"dependents": [],
"active": true,
"type": "ComputedAttribute",
"createEpoch": 1571945277,
"updateEpoch": 1571945280
}
],
"_links": {
"next": {}
}
}
属性 | 描述 |
---|---|
_page.totalCount |
由IMS组织定义的计算属性总数。 |
_page.pageSize |
在此结果页面上返回的计算属性数。 如果 pageSize 等于 totalCount ,这意味着只有一个结果页且返回了所有计算属性。 如果不等于,则可以访问其他的结果页面。 请参阅 _links.next 以了解详细信息。 |
children |
由一个或多个对象组成的数组,每个对象包含单个计算属性的详细信息。 如果尚未定义计算属性,则 children 数组为空。 |
id |
创建时自动分配给计算属性的唯一只读系统生成值。 有关计算属性对象的组件的更多信息,请参阅 创建计算属性 在本教程的前面部分。 |
_links.next |
如果返回单页计算属性, _links.next 是空对象,如上面的示例响应中所示。 如果贵组织具有许多计算属性,则会在多个页面上返回这些属性,您可以通过向发出GET请求来访问这些属性 _links.next 值。 |
您可以通过向 /config/computedAttributes
端点,并在请求路径中包含计算的属性ID。
API格式
GET /config/computedAttributes/{ATTRIBUTE_ID}
参数 | 描述 |
---|---|
{ATTRIBUTE_ID} |
要查看的计算属性的ID。 |
请求
curl -X GET \
https://platform.adobe.io/data/core/ups/config/computedAttributes/2afcf410-450e-4a39-984d-2de99ab58877 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
响应
{
"id": "2afcf410-450e-4a39-984d-2de99ab58877",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
"sandboxName": "prod",
"type": "production",
"default": true
},
"name": "birthdayCurrentMonth",
"path": "_{TENANT_ID}",
"positionPath": [
"_{TENANT_ID}"
],
"description": "Computed attribute to capture if the customer birthday is in the current month.",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "person.birthDate.getMonth() = currentMonth()"
},
"schema": {
"name": "_xdm.context.profile"
},
"returnSchema": {
"meta:xdmType": "string"
},
"definedOn": [
{
"meta:resourceType": "unions",
"meta:containerId": "tenant",
"$ref": "https://ns.adobe.com/xdm/context/profile__union"
}
],
"encodedDefinedOn":"?\b?VR)JMS?R?())(????+?KL?OJ?K???H??O??+I?(?/(?O??I??/????S?8{?E:",
"dependencies": [],
"dependents": [],
"active": true,
"type": "ComputedAttribute",
"createEpoch": 1572555223,
"updateEpoch": 1572555225
}
如果您发现需要更新现有的计算属性,可以通过向 /config/computedAttributes
端点,并包括您希望在请求路径中更新的计算归因的ID。
API格式
PATCH /config/computedAttributes/{ATTRIBUTE_ID}
参数 | 描述 |
---|---|
{ATTRIBUTE_ID} |
要更新的计算属性的ID。 |
请求
此请求使用 JSON修补程序格式 更新“expression”字段的“value”。
curl -X PATCH \
https://platform.adobe.io/data/core/ups/config/computedAttributes/ae0c6552-cf49-4725-8979-116366e8e8d3 \
-H 'Authorization: Bearer {ACCESS_TOKEN}'\
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '[
{
"op": "add",
"path": "/expression",
"value":
{
"type": "PQL",
"format": "pql/text",
"value": "{NEW_EXPRESSION_VALUE}"
}
}
]'
属性 | 描述 |
---|---|
{NEW_EXPRESSION_VALUE} |
有效 Profile Query Language (PQL)表达式。 计算属性当前支持以下函数:sum、count、min、max和boolean。 有关示例表达式的列表,请参阅 示例PQL表达式 文档。 |
响应
成功的更新会返回HTTP状态204(无内容)和空的响应正文。 如果要确认更新成功,可以执行GET请求以按其ID查看计算的属性。
也可以使用API删除计算的属性。 这是通过向 /config/computedAttributes
端点,包括您希望在请求路径中删除的计算属性的ID。
删除计算属性时请务必谨慎,因为该属性可能正在多个架构中使用,并且DELETE操作无法撤消。
API格式
DELETE /config/computedAttributes/{ATTRIBUTE_ID}
参数 | 描述 |
---|---|
{ATTRIBUTE_ID} |
要删除的计算属性的ID。 |
请求
curl -X DELETE \
https://platform.adobe.io/data/core/ups/config/computedAttributes/ae0c6552-cf49-4725-8979-116366e8e8d3 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}'
-H 'x-sandbox-name: {SANDBOX_NAME}' \
响应
成功的删除请求会返回HTTP状态200(确定)和空的响应正文。 要确认删除成功,您可以执行GET请求以按其ID查找计算的属性。 如果删除了属性,您将收到“HTTP状态404(未找到)”错误。
Adobe Experience Platform允许您从一组用户档案创建用于定义一组特定属性或行为的区段。 区段定义包括封装在PQL中写入的查询的表达式。 这些表达式还可以引用计算属性。
以下示例创建引用现有计算属性的区段定义。 要详细了解区段定义以及如何在分段服务API中使用这些定义,请参阅 区段定义API端点指南.
要开始,请向 /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": "downloadedInLast7Days",
"description": "Has product been downloaded in last 7 days?",
"schema": {
"name": "_xdm.context.profile"
},
"ttlInDays": 30,
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "_{TENANT_ID}.downloadsLast7Days > 0",
"meta": "m"
},
"dataGovernancePolicy": {
"excludeOptOut": true
},
"evaluationInfo": {
"batch": {
"enabled": false
},
"continuous": {
"enabled": true
},
"synchronous": {
"enabled": false
}
}
}'
属性 | 描述 |
---|---|
name |
区段的唯一名称,以字符串形式表示。 |
description |
定义的人类可读描述。 |
schema.name |
与区段中的实体关联的架构。 由 id 或 name 字段。 |
expression |
包含字段的对象,其中包含有关区段定义的信息。 |
expression.type |
指定表达式类型。 目前仅支持“PQL”。 |
expression.format |
指示值中表达式的结构。 目前,仅 pql/text 支持。 |
expression.value |
有效的PQL表达式,在此示例中,它包括对现有计算属性的引用。 |
有关架构定义属性的更多信息,请参阅 区段定义API端点指南.
响应
成功响应会返回HTTP状态200,其中包含新创建的区段定义的详细信息。 要了解有关区段定义响应对象的更多信息,请参阅 区段定义API端点指南.
{
"id": "add3933f-ac5c-4240-8259-3a4528ee4885",
"schema": {
"name": "_xdm.context.profile"
},
"ttlInDays": 60,
"id": "119835c3-5fab-4c18-ae01-4ccab328fc5c",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "{SANDBOX_ID}",
"sandboxName": "{SANDBOX_NAME}",
"type": "production",
"default": true
},
"name": "segment-downloadedInLast7Days",
"description": "Has product been downloaded in last 7 days?",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "_{TENANT_ID}.downloadsLast7Days > 0",
"meta": "m"
},
"evaluationInfo": {
"batch": {
"enabled": false
},
"continuous": {
"enabled": true
},
"synchronous": {
"enabled": false
}
},
"dataGovernancePolicy": {
"excludeOptOut": true
},
"creationTime": 1602016581000,
"updateEpoch": 1610609459,
"updateTime": 1610609459000,
"createEpoch": 1602016554,
"_etag": "\"8b01611a-0000-0200-0000-5ffff3330000\"",
"dependents": [
"023d46c9-a27c-4ea9-a887-2c91ba83f2d1"
],
"definedOn": [
{
"meta:resourceType": "unions",
"meta:containerId": "tenant",
"$ref": "https://ns.adobe.com/xdm/context/profile__union"
}
],
"dependencies": [
"103d46c9-a27c-4ea9-a887-2c91ba83f2d1"
],
"type": "SegmentDefinition"
}
现在,您已学习了计算属性的基础知识,接下来便可以开始为您的组织定义这些属性。