实体端点(配置文件访问)
Adobe Experience Platform允许您使用RESTful API或用户界面访问Real-Time Customer Profile数据。 本指南概述了如何使用API访问实体(通常称为“用户档案”)。 有关使用Experience Platform UI访问配置文件的详细信息,请参阅配置文件用户指南。
快速入门
本指南中使用的API终结点是Real-Time Customer Profile API的一部分。 在继续之前,请查看快速入门指南,以获取相关文档的链接、此文档中示例API调用的阅读指南,以及有关成功调用任何Experience Platform API所需的所需标头的重要信息。
实体分辨率
作为架构升级的一部分,Adobe将引入针对客户和商机的实体解决方案,使用基于最新数据的确定性ID匹配。 实体解析作业在批量分段期间每天运行,然后再评估具有B2B属性的多实体受众。
此增强功能使Experience Platform能够识别和统一表示同一实体的多个记录,从而提高数据一致性并实现更准确的受众分段。
以前,“帐户”和“机会”依赖于基于身份图的解决方案,该解决方案将身份(包括所有历史引入)关联起来。 在新的实体解析方法中,标识仅根据最新数据进行链接
实体解析如何工作?
- 在 之前:如果将数据通用编号系统(DUNS)编号用作附加标识,并且在源系统(如CRM)中更新了帐户的DUNS编号,则帐户ID将同时链接到旧和新的DUNS编号。
- After:如果将DUNS编号用作附加标识,并且在源系统(如CRM)中更新了帐户的DUNS编号,则帐户ID将仅链接到新的DUNS编号,从而更准确地反映帐户的当前状态。
作为本次更新的结果,Profile Access API现在会在实体解析作业周期完成后反映最新的合并配置文件视图。 此外,一致数据提供了分段、激活和分析等用例,提高了数据准确性和一致性。
检索实体 retrieve-entity
您可以通过向/access/entities
端点发出GET请求以及所需的查询参数来检索配置文件实体。
API格式
code language-http |
---|
|
请求路径中提供的查询参数指定要访问的数据。 您可以包含多个参数,以&分隔。
要访问配置文件实体,您 必须 提供以下查询参数:
schema.name
:实体的XDM架构的名称。 在此使用案例中,schema.name=_xdm.context.profile
。entityId
:您尝试检索的实体的ID。entityIdNS
:您尝试检索的实体的命名空间。 如果entityId
是 而不是 XID,则必须提供此值。
附录的查询参数部分提供了有效参数的完整列表。
请求
以下请求使用标识检索客户的电子邮件和名称。
accordion | ||
---|---|---|
使用标识检索实体的示例请求 | ||
|
响应
成功的响应会返回包含所请求实体的HTTP状态200。
accordion | ||
---|---|---|
包含所请求实体的示例响应 | ||
|
note note |
---|
NOTE |
如果相关图形链接超过50个身份,此服务将返回HTTP状态422和消息“相关身份过多”。 如果收到此错误,请考虑添加更多查询参数以缩小搜索范围。 |
API格式
code language-http |
---|
|
请求路径中提供的查询参数指定要访问的数据。 您可以包含多个参数,以&分隔。
要访问B2B帐户数据,您 必须 提供以下查询参数:
schema.name
:实体的XDM架构的名称。 在此用例中,值为schema.name=_xdm.context.account
。entityId
:您尝试检索的实体的ID。entityIdNS
:您尝试检索的实体的命名空间。 如果entityId
是 而不是 XID,则必须提供此值。
附录的查询参数部分提供了有效参数的完整列表。
请求
accordion | ||
---|---|---|
检索B2B帐户的示例请求 | ||
|
响应
成功的响应会返回包含所请求实体的HTTP状态200。
accordion | ||
---|---|---|
包含所请求实体的示例响应 | ||
|
API格式
code language-http |
---|
|
请求路径中提供的查询参数指定要访问的数据。 您可以包含多个参数,以&分隔。
要访问B2B Opportunity实体,您 必须 提供以下查询参数:
schema.name
:实体的XDM架构的名称。 在此使用案例中,schema.name=_xdm.context.opportunity
。entityId
:您尝试检索的实体的ID。entityIdNS
:您尝试检索的实体的命名空间。 如果entityId
是 而不是 XID,则必须提供此值。
附录的查询参数部分提供了有效参数的完整列表。
请求
accordion | ||
---|---|---|
检索B2B Opportunity实体的示例请求 | ||
|
响应
成功的响应会返回包含所请求实体的HTTP状态200。
accordion | ||
---|---|---|
包含所请求实体的示例响应 | ||
|
检索多个实体 retrieve-entities
您可以通过向/access/entities
端点发出POST请求并在有效负载中提供标识来检索多个配置文件实体。
API格式
code language-http |
---|
|
请求
以下请求按身份列表检索多个客户的名称和电子邮件地址。
accordion | |||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
检索多个实体的示例请求 | |||||||||||||||||||||||||||||||||||
|
响应
成功的响应返回HTTP状态200,请求正文中指定了实体的请求字段。
accordion | ||
---|---|---|
包含所请求实体的示例响应 | ||
|
API格式
code language-http |
---|
|
请求
以下请求将检索请求的B2B帐户。
accordion | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
检索多个实体的示例请求 | ||||||||||||||||||||
|
响应
成功的响应会返回包含所请求实体的HTTP状态200。
accordion | ||
---|---|---|
包含所请求实体的示例响应 | ||
|
API格式
code language-http |
---|
|
请求
以下请求将检索请求的B2B机会。
accordion | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
检索多个实体的示例请求 | ||||||||||||||||||||
|
响应
成功的响应会返回包含所请求实体的HTTP状态200。
accordion | ||
---|---|---|
包含所请求实体的示例响应 | ||
|
访问结果的后续页面
检索时序事件时,结果将分页。 如果有后续结果页,则_page.next
属性将包含ID。 此外,_links.next.href
属性还提供用于检索下一页的请求URI。 要检索结果,请对/access/entities
端点发出另一个GET请求,并使用提供的URI的值替换/entities
。
/entities/
。 它只应出现一次,如/access/entities?start=...
API格式
GET /access/{NEXT_URI}
{NEXT_URI}
_links.next.href
。请求
以下请求通过使用_links.next.href
URI作为请求路径来检索结果的下一页。
code language-shell |
---|
|
响应
成功的响应将返回结果的下一页。 此响应没有后续结果页,如_page.next
和_links.next.href
的空字符串值所指示。
code language-json |
---|
|
删除实体 delete-entity
- 帐户
- 帐户 — 人员关系
- 机会
- 机会 — 人员关系
- Campaign
- 营销活动成员
- 营销列表
- 营销列表成员
通过向/access/entities
端点发出DELETE请求以及必需的查询参数,可以从配置文件存储中删除实体。
API格式
DELETE /access/entities?{QUERY_PARAMETERS}
请求路径中提供的查询参数指定要访问的数据。 您可以包含多个参数,以&分隔。
要删除实体,您 必须 提供以下查询参数:
schema.name
:实体的XDM架构的名称。 在此使用案例中,您 只能 使用schema.name=_xdm.context.profile
。entityId
:您尝试检索的实体的ID。entityIdNS
:您尝试检索的实体的命名空间。 如果entityId
是 而不是 XID,则必须提供此值。mergePolicyId
:实体的合并策略ID。 合并策略包含有关身份拼接和键值XDM对象合并的信息。 如果未提供此值,则将使用默认合并策略。
请求
以下请求删除指定的实体。
code language-shell |
---|
|
响应
成功的响应返回带有空响应正文的HTTP状态202。
后续步骤
按照本指南,您已成功访问Real-Time Customer Profile数据字段、配置文件和时序数据。 要了解如何访问存储在Experience Platform中的其他数据资源,请参阅数据访问概述。
附录 appendix
以下部分提供有关使用API访问Profile数据的补充信息。
查询参数 query-parameters
在/access/entities
终结点的GET请求的路径中使用了以下参数。 它们用于标识要访问的配置文件实体,并筛选响应中返回的数据。 必填参数标有标签,其余参数为可选参数。
schema.name
schema.name=_xdm.context.profile
relatedSchema.name
schema.name
是_xdm.context.experienceevent
,则此值 必须 为时间序列事件相关的配置文件实体指定架构。relatedSchema.name=_xdm.context.profile
entityId
entityIdNS
)。entityId=janedoe@example.com
entityIdNS
entityId
作为XID提供,则字段 必须 指定标识命名空间。entityIdNS=email
relatedEntityId
schema.name
是_xdm.context.experienceevent
,则此值 必须 指定相关配置文件实体的ID。 此值遵循与entityId
相同的规则。relatedEntityId=69935279872410346619186588147492736556
relatedEntityIdNS
schema.name
是“_xdm.context.experienceevent”,此值必须为relatedEntityId
中指定的实体指定身份命名空间。relatedEntityIdNS=CRMID
fields
fields=personalEmail,person.name,person.gender
mergePolicyId
mergePolicyId=5aa6885fcf70a301dabdfa4a
orderBy
(+/-)timestamp
,默认值为+timestamp
。orderby=-timestamp
startTime
startTime=1539838505
endTime
endTime=1539838510
limit
limit=100
property
property=webPageDetails.isHomepage=true&property=localTime<="2020-07-20"