受众端点
受众是指具有相似行为和/或特征的人群。 这些人员集合可以通过使用Adobe Experience Platform或从外部源生成。 您可以使用分段API中的/audiences端点,它允许您以编程方式检索、创建、更新和删除受众。
快速入门
本指南中使用的端点是Adobe Experience Platform Segmentation Service API的一部分。 在继续之前,请查看快速入门指南以了解成功调用API所需了解的重要信息,包括所需的标头以及如何读取示例API调用。
检索受众列表 list
您可以通过向/audiences端点发出GET请求来检索贵组织所有受众的列表。
API格式
/audiences端点支持多个查询参数以帮助筛选结果。 虽然这些参数是可选的,但强烈建议使用这些参数,以帮助在列出资源时减少昂贵的开销。 如果您在不使用参数的情况下调用此端点,则将检索对您的组织可用的所有受众。 可以包含多个参数,以&符号(&)分隔。
GET /audiences
GET /audiences?{QUERY_PARAMETERS}
property=audienceId查询参数一起使用,则将返回非活动受众****。在检索受众列表时,可以使用以下查询参数:
startstart=5limitlimit=10sortattributeName:[desc/asc]格式编写的。sort=updateTime:descpropertyproperty=格式编写的property=audienceId==test-audience-idnamename=Sampledescriptiondescription=Test DescriptionentityTypeentityType=_xdm.context.account请求
以下请求将检索在您的组织中创建的最后两个受众。
| code language-shell |
|---|
|
响应
成功的响应会返回HTTP状态200,其中包含您的组织中创建为JSON的受众列表。
| code language-json |
|---|
|
| table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3 8-row-3 9-row-3 10-row-3 11-row-3 12-row-3 13-row-3 14-row-3 15-row-3 16-row-3 17-row-3 18-row-3 | ||
|---|---|---|
| 属性 | 受众类型 | 描述 |
id |
两者 | 系统生成的受众只读标识符。 |
audienceId |
两者 | 如果该受众是平台生成的受众,则其值与id的值相同。 如果受众是外部生成的,则此值由客户端提供。 |
schema |
两者 | 受众的体验数据模型(XDM)架构。 |
imsOrgId |
两者 | 受众所属的组织的ID。 |
sandbox |
两者 | 有关受众所属的沙盒的信息。 有关沙箱的详细信息,请参阅沙箱概述。 |
name |
两者 | 受众的名称。 |
description |
两者 | 受众的描述。 |
expression |
平台生成 | 受众的Profile Query Language (PQL)表达式。 有关PQL表达式的详细信息,请参阅PQL表达式指南。 |
mergePolicyId |
平台生成 | 受众关联的合并策略的ID。 有关合并策略的详细信息,请参阅合并策略指南。 |
evaluationInfo |
平台生成 | 显示评估受众的方式。 可能的评估方法包括批处理、同步(流)或连续(边缘)。 有关评估方法的更多信息,请参阅分段概述 |
dependents |
两者 | 依赖于当前受众的受众ID数组。 如果您创建的受众是区段的区段,则会使用此字段。 |
dependencies |
两者 | 受众所依赖的受众ID数组。 如果您创建的受众是区段的区段,则会使用此字段。 |
type |
两者 | 一个系统生成的字段,用于显示受众是平台生成的还是外部生成的受众。 可能的值包括SegmentDefinition和ExternalSegment。 SegmentDefinition引用在Platform中生成的受众,而ExternalSegment引用未在Platform中生成的受众。 |
originName |
两者 | 引用受众来源名称的字段。 对于平台生成的受众,此值将为REAL_TIME_CUSTOMER_PROFILE。 对于在Audience Orchestration中生成的受众,此值将为AUDIENCE_ORCHESTRATION。 对于在Adobe Audience Manager中生成的受众,此值将为AUDIENCE_MANAGER。 对于其他外部生成的受众,此值将为CUSTOM_UPLOAD。 |
createdBy |
两者 | 创建受众的用户的ID。 |
labels |
两者 | 与受众相关的对象级别数据使用和基于属性的访问控制标签。 |
namespace |
两者 | 受众所属的命名空间。 可能的值包括AAM、AAMSegments、AAMTraits和AEPSegments。 |
linkedAudienceRef |
两者 | 包含其他受众相关系统标识符的对象。 |
创建新受众 create
您可以通过向/audiences端点发出POST请求来创建新受众。
API格式
POST /audiences
请求
| code language-shell |
|---|
|
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 | |
|---|---|
| 属性 | 描述 |
name |
受众的名称。 |
description |
受众的描述。 |
type |
一个字段,用于显示受众是平台生成的受众还是外部生成的受众。 可能的值包括SegmentDefinition和ExternalSegment。 SegmentDefinition引用在Platform中生成的受众,而ExternalSegment引用未在Platform中生成的受众。 |
expression |
受众的Profile Query Language (PQL)表达式。 有关PQL表达式的详细信息,请参阅PQL表达式指南。 |
schema |
受众的体验数据模型(XDM)架构。 |
labels |
与受众相关的对象级别数据使用和基于属性的访问控制标签。 |
响应
成功的响应返回HTTP状态200,其中包含有关新创建的受众的信息。
| code language-json |
|---|
|
查找指定受众 get
您可以查找有关特定受众的详细信息,方法是向/audiences端点发出GET请求,并在请求路径中提供要检索的受众ID。
API格式
GET /audiences/{AUDIENCE_ID}
{AUDIENCE_ID}id字段,是 而不是 audienceId字段。请求
| code language-shell |
|---|
|
响应
成功的响应返回HTTP状态200,其中包含有关指定受众的信息。
| code language-json |
|---|
|
覆盖受众 put
您可以通过向/audiences端点发出PUT请求并在请求路径中提供要更新的受众ID,来更新(覆盖)特定受众。
API格式
PUT /audiences/{AUDIENCE_ID}
{AUDIENCE_ID}id字段,是 而不是 audienceId字段。请求
| code language-shell |
|---|
|
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 9-row-2 | |
|---|---|
| 属性 | 描述 |
audienceId |
受众的ID。 对于外部生成的受众,此值可由用户提供。 |
name |
受众的名称。 |
namespace |
受众的命名空间。 |
description |
受众的描述。 |
type |
一个系统生成的字段,用于显示受众是平台生成的还是外部生成的受众。 可能的值包括SegmentDefinition和ExternalSegment。 SegmentDefinition引用在Experience Platform中生成的受众,而ExternalSegment引用未在Experience Platform中生成的受众。 |
expression |
包含受众的PQL表达式的对象。 |
lifecycleState |
受众的状态。 可能的值包括draft、published和inactive。 draft表示创建受众的时间、published表示发布受众的时间,以及inactive表示受众不再处于活动状态的时间。 |
datasetId |
可找到受众数据的数据集的ID。 |
labels |
与受众相关的对象级别数据使用和基于属性的访问控制标签。 |
响应
成功的响应返回HTTP状态200以及新更新受众的详细信息。 请注意,您的受众详细信息将有所不同,具体取决于您是Experience Platform生成的受众还是外部生成的受众。
| code language-json |
|---|
|
更新受众 patch
您可以通过向/audiences端点发出PATCH请求并在请求路径中提供要更新的受众ID来更新特定受众。
API格式
PATCH /audiences/{AUDIENCE_ID}
{AUDIENCE_ID}id字段,是 而不是 audienceId字段。请求
| code language-shell |
|---|
|
| table 0-row-2 1-row-2 2-row-2 3-row-2 | |
|---|---|
| 属性 | 描述 |
op |
所执行的PATCH操作的类型。 对于此终结点,此值是 始终 /add。 |
path |
要更新的字段的路径。 无法编辑系统生成的字段,如id、audienceId和namespace 。 |
value |
分配给path中指定的属性的新值。 |
响应
成功的响应会返回包含已更新受众的HTTP状态200。
| code language-json |
|---|
|
删除受众 delete
您可以通过向/audiences端点发出DELETE请求并在请求路径中提供要删除的受众ID来删除特定受众。
API格式
DELETE /audiences/{AUDIENCE_ID}
{AUDIENCE_ID}id字段,是 而不是 audienceId字段。请求
| code language-shell |
|---|
|
响应
成功的响应返回HTTP状态204,但不返回消息。
检索多个受众 bulk-get
您可以通过向/audiences/bulk-get端点发出POST请求并提供要检索的受众ID来检索多个受众。
API格式
POST /audiences/bulk-get
请求
| code language-shell |
|---|
|
响应
成功的响应会返回HTTP状态207,其中包含您请求的受众的信息。
| code language-json |
|---|
|
后续步骤
阅读本指南后,您现在可以更好地了解如何使用Adobe Experience Platform API创建、管理和删除受众。 有关使用UI进行受众管理的更多信息,请参阅分段UI指南。