导出作业是异步进程,用于将受众段成员保留到数据集。 您可以在Adobe Experience Platform分段API中使用/export/jobs
端点,它允许您以编程方式检索、创建和取消导出作业。
本指南介绍在Segmentation API中使用导出作业。 有关如何管理Real-time Customer Profile数据的导出作业的信息,请参见用户档案API](…/…/profile/api/export-jobs.md)中有关[导出作业的指南
本指南中使用的端点是Adobe Experience Platform Segmentation Service API的一部分。 在继续之前,请查看快速入门指南,了解成功调用API所需的重要信息,包括必需的头以及如何读取示例API调用。
通过向/export/jobs
端点发出列表请求,可以检索IMS组织的所有导出作业的GET。
API格式
/export/jobs
端点支持多个查询参数以帮助筛选结果。 虽然这些参数是可选的,但强烈建议使用它们以帮助降低昂贵的开销。 调用此端点时,无参数将检索组织可用的所有导出作业。 可以包括多个参数,用和符(&
)分隔。
GET /export/jobs
GET /export/jobs?limit={LIMIT}
GET /export/jobs?offset={OFFSET}
GET /export/jobs?status={STATUS}
参数 | 描述 |
---|---|
{LIMIT} |
指定返回的导出作业数。 |
{OFFSET} |
指定结果页的偏移。 |
{STATUS} |
过滤器基于状态的结果。 支持的值为“NEW”、“SUCCEEDED”和“FAILED”。 |
请求
以下请求将检索IMS组织中最后两个导出作业。
curl -X GET https://platform.adobe.io/data/core/ups/export/jobs?limit=2 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
响应
以下响应根据请求路径中提供的列表参数返回HTTP状态200,该状态具有成功完成的导出作业的查询。
{
"records": [
{
"id": 100,
"jobType": "BATCH",
"destination": {
"datasetId": "5b7c86968f7b6501e21ba9df",
"segmentPerBatch": false,
"batchId": "da5cfb4de32c4b93a09f7e37fa53ad52",
},
"fields": "identities.id,personalEmail.address",
"schema": {
"name": "_xdm.context.profile"
},
"imsOrgId": "1BD6382559DF0C130A49422D@AdobeOrg",
"status": "SUCCEEDED",
"filter": {
"segments": [
{
"segmentId": "52c26d0d-45f2-47a2-ab30-ed06abc981ff",
"segmentNs": "ups",
"status": [
"realized"
]
}
]
},
"mergePolicy": {
"id": "timestampOrdered-none-mp",
"version": 1
},
"profileInstanceId": "ups",
"errors": [
{
"code": "0100000003",
"msg": "Error in Export Job",
"callStack": "com.adobe.aep.unifiedprofile.common.logging.Logger"
}
],
"metrics": {
"totalTime": {
"startTimeInMs": 123456789000,
"endTimeInMs": 123456799000,
"totalTimeInMs": 10000
},
"profileExportTime": {
"startTimeInMs": 123456789000,
"endTimeInMs": 123456799000,
"totalTimeInMs": 10000
},
"totalExportedProfileCounter": 20,
"exportedProfileByNamespaceCounter": {
"namespace1": 10,
"namespace2": 5
}
},
"computeGatewayJobId": {
"exportJob": "f3058161-7349-4ca9-807d-212cee2c2e94"
},
"creationTime": 1538615973895,
"updateTime": 1538616233239,
"requestId": "d995479c-8a08-4240-903b-af469c67be1f"
},
{
"profileInstanceId": "test_xdm_latest_profile_20_e2e_1538573005395",
"errors": [
{
"code": "0090000009",
"msg": "Error writing profiles to output path 'adl://va7devprofilesnapshot.azuredatalakestore.net/snapshot/722'",
"callStack": "com.adobe.aep.unifiedprofile.common.logging.Logger"
},
{
"code": "unknown",
"msg": "Job aborted.",
"callStack": "org.apache.spark.SparkException: Job aborted."
}
],
"jobType": "BATCH",
"filter": {
"segments": [
{
"segmentId": "52c26d0d-45f2-47a2-ab30-ed06abc981ff",
"segmentNs": "AAM",
"status": ["realized", "existing"]
}
]
},
"id": 722,
"schema": {
"name": "_xdm.context.profile"
},
"mergePolicy": {
"id": "7972e3d6-96ea-4ece-9627-cbfd62709c5d",
"version": 1
},
"status": "FAILED",
"requestId": "KbOAsV7HXmdg262lc4yZZhoml27UWXPZ",
"computeGatewayJobId": {
"exportJob": "15971e0f-317c-4390-9038-1a0498eb356f"
},
"metrics": {
"totalTime": {
"startTimeInMs": 1538573416687,
"endTimeInMs": 1538573922551,
"totalTimeInMs": 505864
},
"profileExportTime": {
"startTimeInMs": 1538573872211,
"endTimeInMs": 1538573918809,
"totalTimeInMs": 46598
}
},
"destination": {
"datasetId": "5bb4c46757920712f924a3eb",
"segmentPerBatch": false,
"batchId": "IWEQ6920712f9475762D"
},
"updateTime": 1538573922551,
"imsOrgId": "1BD6382559DF0C130A49422D@AdobeOrg",
"creationTime": 1538573416687
}
],
"page":{
"sortField": "createdTime",
"sort": "desc",
"pageOffset": "1540974701302_96",
"pageSize": 2
},
"link":{
"next": "/export/jobs/?limit=2&offset=1538573416687_722"
}
}
属性 | 描述 |
---|---|
destination |
导出数据的目标信息:
|
fields |
导出字段的列表,用逗号分隔。 |
schema.name |
与要导出模式的数据集关联的数据的名称。 |
filter.segments |
导出的区段。 包括以下字段:
|
mergePolicy |
合并导出数据的策略信息。 |
metrics.totalTime |
一个字段,指示导出作业运行所用的总时间。 |
metrics.profileExportTime |
一个字段,指示用户档案导出所用的时间。 |
page |
有关请求的导出作业分页的信息。 |
link.next |
指向导出作业下一页的链接。 |
可以通过向/export/jobs
端点发出POST请求来创建新的导出作业。
API格式
POST /export/jobs
请求
以下请求将创建一个新的导出作业,该作业由有效负荷中提供的参数进行配置。
curl -X POST https://platform.adobe.io/data/core/ups/export/jobs \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '
{
"fields": "identities.id,personalEmail.address",
"mergePolicy": {
"id": "timestampOrdered-none-mp",
"version": 1
},
"filter": {
"segments": [
{
"segmentId": "52c26d0d-45f2-47a2-ab30-ed06abc981ff",
"segmentNs": "ups",
"status": [
"realized"
]
}
],
"segmentQualificationTime": {
"startTime": "2018-01-01T00:00:00Z",
"endTime": "2018-02-01T00:00:00Z"
},
"fromIngestTimestamp": "2018-01-01T00:00:00Z",
"emptyProfiles": true
},
"additionalFields": {
"eventList": {
"fields": "string",
"filter": {
"fromIngestTimestamp": "2018-01-01T00:00:00Z",
"toIngestTimestamp": "2020-01-01T00:00:00Z"
}
}
},
"destination":{
"datasetId": "5b7c86968f7b6501e21ba9df",
"segmentPerBatch": false
},
"schema":{
"name": "_xdm.context.profile"
},
"evaluationInfo": {
"segmentation": true
}
}'
属性 | 描述 |
---|---|
fields |
导出字段的列表,用逗号分隔。 如果留空,则将导出所有字段。 |
mergePolicy |
指定用于管理导出数据的合并策略。 当导出多个段时,请包含此参数。 如果未提供,则导出将采用与给定段相同的合并策略。 |
filter |
一个对象,它根据以下列出的子属性,指定将按ID、资格时间或收录时间包括在导出作业中的段。 如果保留为空,则将导出所有数据。 |
filter.segments |
指定要导出的段。 忽略此值将导致导出所有用户档案的所有数据。 接受段对象的数组,每个对象都包含以下字段:
|
filter.segmentQualificationTime |
根据区段限定时间进行筛选。 可以提供开始时间和/或结束时间。 |
filter.segmentQualificationTime.startTime |
给定状态的区段ID的区段资格开始时间。 它未提供,将不会对区段ID资格的开始时间进行筛选。 时间戳必须以RFC 3339格式提供。 |
filter.segmentQualificationTime.endTime |
给定状态的区段ID的区段资格结束时间。 它未提供,在区段ID资格的结束时间上将没有过滤器。 时间戳必须以RFC 3339格式提供。 |
filter.fromIngestTimestamp |
将导出的用户档案限制为仅包含在此时间戳后已更新的数据。 时间戳必须以RFC 3339格式提供。
|
filter.emptyProfiles |
一个布尔值,指示是否过滤空用户档案。 用户档案可以包含用户档案记录和/或ExperienceEvent记录。 没有用户档案记录且只有ExperienceEvent记录的用户档案称为“emptyProfiles”。 要导出用户档案商店中的所有用户档案,包括“emptyProfiles”,请将emptyProfiles 的值设置为true 。 如果emptyProfiles 设置为false ,则只导出存储中具有用户档案记录的用户档案。 默认情况下,如果不包括emptyProfiles 属性,则只导出包含用户档案记录的用户档案。 |
additionalFields.eventList |
通过提供以下一个或多个设置,控制为子对象或关联对象导出的时间序列事件字段:
|
destination |
(必需) 有关导出数据的信息:
|
schema.name |
(必需) 与要导出数据的数据集关联的模式的名称。 |
evaluationInfo.segmentation |
(可选) 布尔值,如果未提供,则默认为 false 。值true 表示需要在导出作业上完成分段。 |
响应
成功的响应会返回HTTP状态200,其中包含您新创建的导出作业的详细信息。
{
"id": 100,
"jobType": "BATCH",
"destination": {
"datasetId": "5b7c86968f7b6501e21ba9df",
"segmentPerBatch": false,
"batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
},
"fields": "identities.id,personalEmail.address",
"schema": {
"name": "_xdm.context.profile"
},
"imsOrgId": "{IMS_ORG}",
"status": "NEW",
"filter": {
"segments": [
{
"segmentId": "52c26d0d-45f2-47a2-ab30-ed06abc981ff",
"segmentNs": "ups",
"status": [
"realized"
]
}
],
"segmentQualificationTime": {
"startTime": "2018-01-01T00:00:00Z",
"endTime": "2018-02-01T00:00:00Z"
},
"fromIngestTimestamp": "2018-01-01T00:00:00Z",
"emptyProfiles": true
},
"additionalFields": {
"eventList": {
"fields": "_id, _experience",
"filter": {
"fromIngestTimestamp": "2018-01-01T00:00:00Z"
}
}
},
"mergePolicy": {
"id": "timestampOrdered-none-mp",
"version": 1
},
"profileInstanceId": "ups",
"metrics": {
"totalTime": {
"startTimeInMs": 123456789000,
}
},
"computeGatewayJobId": {
"exportJob": ""
},
"creationTime": 1538615973895,
"updateTime": 1538616233239,
"requestId": "d995479c-8a08-4240-903b-af469c67be1f"
}
属性 | 描述 |
---|---|
id |
系统生成的只读值,标识刚刚创建的导出作业。 |
或者,如果destination.segmentPerBatch
已设置为true
,则上面的destination
对象将具有batches
数组,如下所示:
"destination": {
"dataSetId" : "{DATASET_ID}",
"segmentPerBatch": true,
"batches" : [
{
"segmentId": "segment1",
"segmentNs": "ups",
"status": ["realized"],
"batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
},
{
"segmentId": "segment2",
"segmentNs": "AdCloud",
"status": "exited",
"batchId": "df4gssdfb93a09f7e37fa53ad52"
}
]
}
您可以通过向/export/jobs
端点发出GET请求并在请求路径中提供要检索的导出作业的ID,来检索有关特定导出作业的详细信息。
API格式
GET /export/jobs/{EXPORT_JOB_ID}
参数 | 描述 |
---|---|
{EXPORT_JOB_ID} |
要访问的导出作业的id 。 |
请求
curl -X GET https://platform.adobe.io/data/core/ups/export/jobs/11037 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
响应
成功的响应返回HTTP状态200,其中包含有关指定导出作业的详细信息。
{
"id": 11037,
"jobType": "BATCH",
"destination": {
"datasetId": "5b7c86968f7b6501e21ba9df",
"segmentPerBatch": false,
"batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
},
"fields": "identities.id,personalEmail.address",
"schema": {
"name": "_xdm.context.profile"
},
"imsOrgId": "{IMS_ORG}",
"status": "SUCCEEDED",
"filter": {
"segments": [
{
"segmentId": "52c26d0d-45f2-47a2-ab30-ed06abc981ff",
"segmentNs": "ups",
"status":[
"realized"
]
}
]
},
"mergePolicy": {
"id": "timestampOrdered-none-mp",
"version": 1
},
"profileInstanceId": "ups",
"metrics": {
"totalTime": {
"startTimeInMs": 123456789000,
"endTimeInMs": 123456799000,
"totalTimeInMs": 10000
},
"profileExportTime": {
"startTimeInMs": 123456789000,
"endTimeInMs": 123456799000,
"totalTimeInMs": 10000
},
"totalExportedProfileCounter": 20,
"exportedProfileByNamespaceCounter": {
"namespace1": 10,
"namespace2": 5
}
},
"computeGatewayJobId": {
"exportJob": "f3058161-7349-4ca9-807d-212cee2c2e94"
},
"creationTime": 1538615973895,
"updateTime": 1538616233239,
"requestId": "d995479c-8a08-4240-903b-af469c67be1f"
}
属性 | 描述 |
---|---|
destination |
导出数据的目标信息:
|
fields |
导出字段的列表,用逗号分隔。 |
schema.name |
与要导出模式的数据集关联的数据的名称。 |
filter.segments |
导出的区段。 包括以下字段:
|
mergePolicy |
合并导出数据的策略信息。 |
metrics.totalTime |
一个字段,指示导出作业运行所用的总时间。 |
metrics.profileExportTime |
一个字段,指示用户档案导出所用的时间。 |
totalExportedProfileCounter |
所有批中导出的用户档案总数。 |
您可以通过向/export/jobs
端点发出DELETE请求并在请求路径中提供要删除的导出作业的ID,来请求删除指定的导出作业。
API格式
DELETE /export/jobs/{EXPORT_JOB_ID}
参数 | 描述 |
---|---|
{EXPORT_JOB_ID} |
要删除的导出作业的id 。 |
请求
curl -X DELETE https://platform.adobe.io/data/core/ups/export/jobs/{EXPORT_JOB_ID} \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
响应
成功的响应返回HTTP状态204,并显示以下消息:
{
"status": true,
"message": "Export job has been marked for cancelling"
}
阅读本指南后,您现在可以更好地了解导出作业的工作方式。