내보내기 작업 끝점
내보내기 작업은 대상 세그먼트 구성원을 데이터 세트로 유지하는 데 사용되는 비동기 프로세스입니다. 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 종단점에 GET 요청을 함으로써 IMS 조직에 대한 모든 내보내기 작업 목록을 가져올 수 있습니다.
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", "SUCCESS" 및 "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"
}
다음 단계
이 안내서를 읽고 나면 이제 내보내기 작업이 작동하는 방식을 더 잘 이해할 수 있습니다.