文档Experience PlatformSegmentation Service 指南

外部受众端点

Last update: Thu Jul 31 2025 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 主题：

创建对象：

  • 用户

外部受众允许您将外部源中的配置文件数据上传到Adobe Experience Platform。 您可以使用分段服务API中的/external-audience端点将外部受众摄取到Experience Platform、查看详细信息和更新外部受众，以及删除外部受众。

快速入门

IMPORTANT
本指南中的端点使用/core/ais作为前缀，而不是/core/ups。

要使用Experience Platform API，您必须已完成身份验证教程。 完成身份验证教程将为Experience Platform API调用中的每个所需标头提供值，如下所示：

  • 授权： Bearer {ACCESS_TOKEN}
  • x-api-key： {API_KEY}
  • x-gw-ims-org-id： {ORG_ID}

Experience Platform中的所有资源都被隔离到特定的虚拟沙盒中。 对Experience Platform API的所有请求都需要一个标头，用于指定将在其中执行操作的沙盒的名称：

  • x-sandbox-name： {SANDBOX_NAME}
NOTE
有关在Experience Platform中使用沙盒的更多信息，请参阅沙盒概述文档。

创建外部受众 create-audience

您可以通过向/external-audience/端点发出POST请求来创建外部受众。

API格式

POST /external-audience/

请求

创建外部受众的示例请求。
code language-shell 
curl -X POST https://platform.adobe.io/data/core/ais/external-audience/ \
 -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": "Sample external audience",
        "description": "A sample version of an external audience",
        "fields": [
            {
                "name": "ppid",
                "type": "string",
                "identityNs": "email"
            },
            {
                "name": "list_id",
                "type": "string",
                "labels": ["core/C2", "custom/deep"]
            },
            {
                "name": "delete",
                "type": "number"
            },
            {
                "name": "process_consent",
                "type": "string"
            }
        ],
        "sourceSpec": {
            "params": {
                "path": "activation/sample-source/example.csv",
                "type": "file",
                "sourceType": "Cloud Storage",
                "baseConnectionId": "1d1d4bc5-b527-46a3-9863-530246a61b2b"
            }
        },
        "ttlInDays": "40",
        "labels": ["core/C1"],
        "audienceType": "people",
        "originName": "CUSTOM_UPLOAD"
    }'
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
属性 类型 描述
name 字符串 外部受众的名称。
description 字符串 外部受众的可选描述。
customAudienceId 字符串 外部受众的可选标识符。
fields 对象数组

字段及其数据类型的列表。 创建字段列表时，可以添加以下项目：

  • name： 必需 ​作为外部受众规范一部分的字段的名称。
  • type： 必需 ​进入字段的数据类型。 支持的值包括string、number、long、integer、date (2025-05-13)、datetime (2025-05-23T20:19:00+00:00)和boolean。
  • identityNs： 身份字段必需 ​身份字段使用的命名空间。 支持的值包括所有有效的命名空间，如ECID或email。
  • labels： 可选 ​字段的访问控制标签数组。 有关可用访问控制标签的详细信息，请参阅数据使用标签术语表。
sourceSpec 对象

包含外部受众所在信息的对象。 使用此对象时，您​ 必须 ​包括以下信息：

  • path： 必需：外部受众或源中包含外部受众的文件夹的位置。
  • type： 必需 ​您要从源检索的对象类型。 此值可以是file或folder。
  • sourceType： 可选 ​您要从中检索的源类型。 当前，唯一支持的值为Cloud Storage。
  • cloudType： 可选 ​云存储的类型，基于源类型。 支持的值包括S3、DLZ、GCS和SFTP。
  • baseConnectionId：基本连接的ID，由源提供程序提供。 如果使用​ 、 ​或cloudType的S3值，则此值为GCS必需SFTP。 有关详细信息，请阅读源连接器概述
ttlInDays 整数 外部受众的数据过期时间（天）。 此值可以设置为1到90。 默认情况下，数据到期设置为30天。
audienceType 字符串 外部受众的受众类型。 当前仅支持people。
originName 字符串 必需 ​受众的来源。 它指明了受众的来源。 对于外部受众，您应使用CUSTOM_UPLOAD。
namespace 字符串 受众的命名空间。 默认情况下，此值设置为CustomerAudienceUpload。
labels 字符串数组 应用于外部受众的访问控制标签。 有关可用访问控制标签的详细信息，请参阅数据使用标签术语表。
tags 字符串数组 要应用于外部受众的标记。 有关标记的详细信息，请参阅管理标记指南。

响应

成功的响应会返回HTTP状态202以及新创建的外部受众的详细信息。

创建外部受众时的示例响应。
code language-json 
{
    "operationId": "df8cd82f-a214-4b72-b549-d6ee23f1ff1a",
    "operationDetails": {
        "name": "Sample external audience",
        "description": "A sample version of an external audience",
        "fields": [
            {
                "name": "ppid",
                "type": "string",
                "identityNs": "Email"
            },
            {
                "name": "list_id",
                "type": "string",
                "labels": ["core/C2", "custom/deep"]
            },
            {
                "name": "delete",
                "type": "number"
            },
            {
                "name": "process_consent",
                "type": "string"
            }
        ],
        "sourceSpec": {
            "params": {
                "path": "activation/sample-source/example.csv",
                "type": "file",
                "sourceType": "Cloud Storage",
                "baseConnectionId": "1d1d4bc5-b527-46a3-9863-530246a61b2b"
            }
        },
        "ttlInDays": 40,
        "labels": ["core/C1"],
        "audienceType": "people",
        "originName": "CUSTOM_UPLOAD"
    }
}
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
属性 类型 描述
operationId 字符串 操作的ID。 您随后可以使用此ID检索受众创建的状态。
operationDetails 对象 一个对象，其中包含您为创建外部受众而提交的请求的详细信息。
name 字符串 外部受众的名称。
description 字符串 外部受众的描述。
fields 对象数组 字段及其数据类型的列表。 此数组确定外部受众中所需的字段。
sourceSpec 对象 包含外部受众所在信息的对象。
ttlInDays 整数 外部受众的数据过期时间（天）。 此值可以设置为1到90。 默认情况下，数据到期设置为30天。
audienceType 字符串 外部受众的受众类型。
originName 字符串 必需 ​受众的来源。 它指明了受众的来源。
namespace 字符串 受众的命名空间。
labels 字符串数组 应用于外部受众的访问控制标签。 有关可用访问控制标签的详细信息，请参阅数据使用标签术语表。

检索受众创建状态 retrieve-status

您可以通过向/external-audiences/operations端点发出GET请求并提供从创建外部受众响应中收到的操作的ID，来检索外部受众提交状态。

API格式

GET /external-audiences/operations/{OPERATION_ID}
参数
描述
{OPERATION_ID}
要检索的操作的id值。

请求

检索外部受众操作状态的示例请求。
code language-shell 
curl -X GET https://platform.adobe.io/data/core/ais/external-audience/operations/df8cd82f-a214-4b72-b549-d6ee23f1ff1a \
 -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以及外部受众任务状态的详细信息。

检索外部受众的任务状态时的示例响应。
code language-json 
{
    "operationId": "df8cd82f-a214-4b72-b549-d6ee23f1ff1a",
    "status": "SUCCESS",
    "operationDetails": {
        "name": "Sample external audience",
        "description": "A sample version of an external audience",
        "fields": [
            {
                "name": "ppid",
                "type": "string",
                "identityNs": "Email"
            },
            {
                "name": "list_id",
                "type": "string",
                "labels": ["core/C2", "custom/deep"]
            },
            {
                "name": "delete",
                "type": "number"
            },
            {
                "name": "process_consent",
                "type": "string"
            }
        ],
        "sourceSpec": {
            "params": {
                "path": "activation/sample-source/example.csv",
                "type": "file",
                "sourceType": "Cloud Storage",
                "baseConnectionId": "1d1d4bc5-b527-46a3-9863-530246a61b2b"
            }
        },
        "ttlInDays": 40,
        "labels": ["core/C1"],
        "audienceType": "people",
        "originName": "CUSTOM_UPLOAD"
    },
    "audienceName": "Sample external audience",
    "audienceId": "60ccea95-1435-4180-97a5-58af4aa285ab",
    "createdBy": "{USER_ID}",
    "createdAt": 1749324248,
    "updatedBy": "{USER_ID}",
    "updatedAt": 1749624273
}
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
属性 类型 描述
operationId 字符串 正在检索的操作的ID。
status 字符串 操作的状态。 此值可以是以下值之一： SUCCESS、FAILED、PROCESSING。
operationDetails 对象 包含受众详细信息的对象。
audienceId 字符串 操作正在提交的外部受众的ID。
createdBy 字符串 创建外部受众的用户的ID。
createdAt 长纪元时间戳 提交创建外部受众的请求时的时间戳（以秒为单位）。
updatedBy 字符串 上次更新受众的用户的ID。
updatedAt 长纪元时间戳 上次更新受众的时间戳（以秒为单位）。

更新外部受众 update-audience

NOTE
若要使用以下端点，您需要具有外部受众的audienceId。 通过成功调用audienceId终结点，您可以获取GET /external-audiences/operations/{OPERATION_ID}。

您可以通过向/external-audience端点发出PATCH请求并在请求路径中提供受众的ID来更新外部受众的字段。

使用此端点时，您可以更新以下字段：

  • 受众描述
  • 字段级访问控制标签
  • 受众级别的访问控制标签
  • 受众的数据过期时间

使用此终结点​ 更新字段将替换 ​您请求的字段内容。

API格式

PATCH /external-audience/{AUDIENCE_ID}

请求

更新外部受众描述的示例请求。
code language-shell 
curl -X PATCH https://platform.adobe.io/data/core/ais/external-audience/60ccea95-1435-4180-97a5-58af4aa285ab\
 -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}'
 -d '{
    "description": "New sample description"
 }'
table 0-row-3 1-row-3
属性 类型 描述
description 字符串 更新了外部受众的描述。

此外，您还可以更新以下参数：

table 0-row-3 1-row-3 2-row-3 3-row-3
属性 类型 描述
labels 数组 一个数组，其中包含受众的更新访问标签列表。 有关可用访问控制标签的详细信息，请参阅数据使用标签术语表。
fields 对象数组 一个数组，其中包含外部受众的字段及其关联标签。 仅更新PATCH请求中列出的字段。 有关可用访问控制标签的详细信息，请参阅数据使用标签术语表。
ttlInDays 整数 外部受众的数据过期时间（天）。 此值可以设置为1到90。

响应

成功的响应返回HTTP状态200以及已更新外部受众的详细信息。

更新外部受众的描述时的示例响应。
code language-json 
{
    "audienceId": "60ccea95-1435-4180-97a5-58af4aa285ab",
    "audienceName": "Sample external audience",
    "description": "New sample description",
    "fields": [
        {
            "name": "ppid",
            "type": "string",
            "identityNs": "Email"
        },
        {
            "name": "list_id",
            "type": "string",
            "labels": ["core/C2", "custom/deep"]
        },
        {
            "name": "delete",
            "type": "number"
        },
        {
            "name": "process_consent",
            "type": "string"
        }
    ],
    "sourceSpec": {
        "path": "activation/sample-source/example.csv",
        "type": "file",
        "sourceType": "Cloud Storage",
        "baseConnectionId": "1d1d4bc5-b527-46a3-9863-530246a61b2b"
        },
    "ttlInDays": 40,
    "labels": ["core/C1"],
    "audienceType": "people",
    "originName": "CUSTOM_UPLOAD",
    "createdBy": "{USER_ID}",
    "createdAt": 1749324248,
    "updatedBy": "{USER_ID}",
    "updatedAt": 1749624273
}

开始受众引入 start-audience-ingestion

IMPORTANT
如果以前的受众引入已在进行中，则您​ 无法 ​为外部受众开始新的引入。
NOTE
若要使用以下端点，您需要具有外部受众的audienceId。 通过成功调用audienceId终结点，您可以获取GET /external-audiences/operations/{OPERATION_ID}。

您可以在提供受众ID的同时，通过向以下端点发出POST请求来开始受众摄取。

API格式

POST /external-audience/{AUDIENCE_ID}/runs

请求

以下请求会触发外部受众的摄取运行。

开始受众摄取的示例请求。
code language-shell 
curl -X POST https://platform.adobe.io/data/core/ais/external-audience/60ccea95-1435-4180-97a5-58af4aa285ab/runs \
 -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}'
 -d '{
    "dataFilterStartTime": 764245635
 }'
table 0-row-3 1-row-3 2-row-3
属性 类型 描述
dataFilterStartTime Epoch时间戳 必需 ​指定运行流的开始时间以选择要处理的文件的范围。
dataFilterEndTime Epoch时间戳 指定流运行的结束时间以选择要处理的文件的范围。

响应

成功的响应返回HTTP状态200，其中包含有关摄取运行的详细信息。

开始受众摄取时的示例响应。
code language-json 
{
    "audienceName": "Sample external audience",
    "audienceId": "60ccea95-1435-4180-97a5-58af4aa285ab",
    "runId": "fb342311-725d-4b48-ab7d-c6105fbc2b8b",
    "differentialIngestion": true,
    "dataFilterStartTime": 764245635,
    "dataFilterEndTime": 4565657575,
    "createdAt": 4565657575,
    "createdBy:" "{USER_ID}"
}
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
属性 类型 描述
audienceName 字符串 您正在为其开始引入运行的受众的名称。
audienceId 字符串 受众的ID。
runId 字符串 您启动的引入运行的ID。
differentialIngestion 布尔值 一个字段，可根据自上次引入或完全受众引入后的差异确定引入是部分引入还是完全引入。
dataFilterStartTime Epoch时间戳 指定流运行的开始时间，以选择已处理的文件的范围。
dataFilterEndTime Epoch时间戳 指定流运行的结束时间，以选择已处理的文件的范围。
createdAt 长纪元时间戳 提交创建外部受众的请求时的时间戳（以秒为单位）。
createdBy 字符串 创建外部受众的用户的ID。

检索特定受众摄取状态 retrieve-ingestion-status

NOTE
若要使用以下端点，您需要同时具有外部受众的audienceId和引入运行ID的runId。 您可从对audienceId端点的成功调用中获取GET /external-audiences/operations/{OPERATION_ID}，并从先前对runId端点的成功调用中获取POST /external-audience/{AUDIENCE_ID}/runs。

您可以在提供受众和运行ID的同时，通过向以下端点发出GET请求来检索受众摄取状态。

API格式

GET /external-audience/{AUDIENCE_ID}/runs/{RUN_ID}

请求

以下请求检索外部受众的摄取状态。

检索外部受众摄取状态的示例请求。
code language-shell 
curl -X GET https://platform.adobe.io/data/core/ais/external-audience/60ccea95-1435-4180-97a5-58af4aa285ab/runs/fb342311-725d-4b48-ab7d-c6105fbc2b8b \
 -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以及外部受众摄取的详细信息。

检索外部受众摄取时的示例响应。
code language-json 
{
    "audienceName": "Sample external audience",
    "audienceId": "60ccea95-1435-4180-97a5-58af4aa285ab",
    "runId": "fb342311-725d-4b48-ab7d-c6105fbc2b8b",
    "status": "SUCCESS",
    "differentialIngestion": true,
    "dataFilterStartTime": 764245635,
    "dataFilterEndTime": 3456788568,
    "createdAt": 1749324248,
    "createdBy": "{USER_ID}",
    "details": [
        {
            "stage": "DATASET_INGEST",
            "status": "SUCCESS",
            "flowRunId": "{FLOW_RUN_ID}"
        },
        {
            "stage": "PROFILE_STORE_INGEST",
            "status": "SUCCESS",
            "flowRunId": "{FLOW_RUN_ID}"
        }
    ]
}
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
属性 类型 描述
audienceName 字符串 受众的名称。
audienceId 字符串 受众的ID。
runId 字符串 摄取运行的ID。
status 字符串 摄取运行的状态。 可能的状态包括SUCCESS和FAILED。
differentialIngestion 布尔值 一个字段，可根据自上次引入或完全受众引入后的差异确定引入是部分引入还是完全引入。
dataFilterStartTime Epoch时间戳 指定流运行的开始时间，以选择已处理的文件的范围。
dataFilterEndTime Epoch时间戳 指定流运行的结束时间，以选择已处理的文件的范围。
createdAt 长纪元时间戳 提交创建外部受众的请求时的时间戳（以秒为单位）。
createdBy 字符串 创建外部受众的用户的ID。
details 对象数组

包含摄取运行详细信息的对象。

  • stage：引入运行的阶段。 这可以是DATASET_INGEST或PROFILE_STORE_INGEST，它们表示数据湖摄取和配置文件摄取。
  • status：阶段中的摄取状态。 可能的状态包括SUCCESS和FAILED。
  • flowRunId：阶段的摄取流运行的ID。

列出受众摄取运行 list-ingestion-runs

NOTE
若要使用以下端点，您需要具有外部受众的audienceId。 通过成功调用audienceId终结点，您可以获取GET /external-audiences/operations/{OPERATION_ID}。

您可以在提供受众ID的同时向以下端点发出GET请求，以检索所选外部受众的所有摄取运行。 可以包含多个参数，以&符号(&)分隔。

API格式

GET /external-audience/{AUDIENCE_ID}/runs

请求

以下请求检索为外部受众运行的所有摄取。

获取受众摄取运行列表的示例请求。
code language-shell 
curl -X GET https://platform.adobe.io/data/core/ais/external-audience/60ccea95-1435-4180-97a5-58af4aa285ab/runs \
 -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，其中包含指定外部受众的摄取运行列表。

检索受众摄取列表时运行的示例响应。
code language-json 
{
    "runs": [
        {
            "audienceName": "Sample external audience",
            "audienceId": "60ccea95-1435-4180-97a5-58af4aa285ab",
            "runId": "fb342311-725d-4b48-ab7d-c6105fbc2b8b",
            "status": "SUCCESS",
            "differentialIngestion": true,
            "dataFilterStartTime": 764245635,
            "dataFilterEndTime": 3456788568,
            "createdAt": 1785678909,
            "createdBy": "{USER_NAME}"
        },
        {
            "audienceName": "Sample external audience 2",
            "audienceId": "60ccea95-1435-4180-97a5-58af4aa285ab",
            "runId": "406e38e4-fbd5-43e1-8d0c-01ccb3f9ad10",
            "status": "SUCCESS",
            "differentialIngestion": true,
            "dataFilterStartTime": 764245635,
            "dataFilterEndTime": 3456788568,
            "createdAt": 1749324248,
            "createdBy": "{USER_ID}"
        }
    ]
}
table 0-row-3 1-row-3
属性 类型 描述
runs 对象 一个对象，其中包含属于该受众的摄取运行列表。 有关此对象的详细信息，请参阅检索摄取状态部分。

删除外部受众 delete-audience

NOTE
若要使用以下端点，您需要具有外部受众的audienceId。 通过成功调用audienceId终结点，您可以获取GET /external-audiences/operations/{OPERATION_ID}。

您可以在提供受众ID的同时，通过向以下端点发出DELETE请求来删除外部受众。

API格式

DELETE /external-audience/{AUDIENCE_ID}

请求

以下请求删除指定的外部受众。

删除外部受众的示例请求。
code language-shell 
curl -X DELETE https://platform.adobe.io/data/core/ais/external-audience/60ccea95-1435-4180-97a5-58af4aa285ab/ \
 -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状态204。

后续步骤 next-steps

阅读本指南后，您现在可以更好地了解如何使用Experience Platform API创建、管理和删除外部受众。 要了解如何通过Experience Platform UI使用外部受众，请阅读受众门户文档。

附录 appendix

以下部分列出了使用外部受众API时可用的错误代码。

平台错误代码
状态代码
消息
描述
100910-400
400
BAD_REQUEST
由于验证请求时出现错误，因此发生了错误请求。
100911-400
400
BAD_REQUEST
提供了无效的令牌。
100920-401
401
UNAUTHORIZED
缺少标头。
100921-401
401
UNAUTHORIZED
提供了无效的imsOrgId。
100922-401
401
UNAUTHORIZED
您无权使用外部受众API。
100940-404
404
NOT_FOUND
未找到所请求的受众。
100950-409
409
DUPLICATE_RESOURCE
受众已存在。
100960-422
422
UNPROCESSABLE_ENTITY
请求结构有效，但由于逻辑或语义错误而无法处理。
100970-500
500
INTERNAL_SERVER_ERROR
在系统中处理请求时出现问题。
100970-502
502
BAD_GATEWAY
存在下游依赖关系问题。
recommendation-more-help
770bc05d-534a-48a7-9f07-017ec1e14871