작업 끝점 내보내기

Real-time Customer Profile 속성 데이터와 동작 데이터를 모두 포함하여 여러 소스에서 데이터를 결합하여 개별 고객에 대한 단일 뷰를 작성할 수 있습니다. 그런 다음 추가적인 처리를 위해 프로필 데이터를 데이터 세트에 내보낼 수 있습니다. 예를 들어 Profile 데이터의 대상 세그먼트를 활성화하도록 내보낼 수 있으며, 프로필 속성을 내보내서 보고할 수 있습니다.

이 문서에서는 프로필 API를 사용하여 내보내기 작업을 만들고 관리하는 단계별 지침을 제공합니다.

노트

이 안내서에서는 Profile API에서 내보내기 작업의 사용에 대해 다룹니다. Adobe Experience Platform 세그멘테이션 서비스의 내보내기 작업을 관리하는 방법에 대한 자세한 내용은 세그멘테이션 API🔗에서 작업 내보내기에 대한 안내서를 참조하십시오.

내보내기 작업을 만드는 것 외에도 "Profile Access"라고도 하는 /entities 종단점을 사용하여 Profile 데이터에 액세스할 수도 있습니다. 자세한 내용은 엔티티 엔드포인트 가이드를 참조하십시오. UI를 사용하여 Profile 데이터에 액세스하는 방법에 대한 단계는 사용 안내서를 참조하십시오.

시작하기

이 안내서에 사용된 API 엔드포인트는 Real-time Customer Profile API의 일부입니다. 계속하기 전에 시작 안내서에서 관련 설명서에 대한 링크, 이 문서에서 샘플 API 호출을 읽는 방법에 대한 안내서 및 Experience Platform API를 성공적으로 호출하는 데 필요한 필수 헤더에 대한 중요한 정보를 검토하십시오.

내보내기 작업 만들기

Profile 데이터를 내보내려면 먼저 데이터를 내보낼 데이터 세트를 만든 다음 새 내보내기 작업을 시작해야 합니다. 두 단계 모두 Experience Platform API를 사용하여 카탈로그 서비스 API를 사용하고 나머지 단계는 실시간 고객 프로필 API를 사용하여 수행할 수 있습니다. 각 단계를 완료하기 위한 자세한 지침은 다음에 나오는 섹션에 요약되어 있습니다.

대상 데이터 세트 만들기

Profile 데이터를 내보낼 때 먼저 대상 데이터 세트를 만들어야 합니다. 내보내기가 성공하도록 데이터 세트를 올바르게 구성해야 합니다.

주요 고려 사항 중 하나는 데이터 세트가 기반으로 하는 스키마( 아래 API 샘플 요청에서schemaRef.id)입니다. 프로필 데이터를 내보내려면 데이터 세트에 XDM Individual Profile 결합 스키마(https://ns.adobe.com/xdm/context/profile__union)를 기반으로 해야 합니다. 결합 스키마는 동일한 클래스를 공유하는 스키마의 필드를 집계하는 시스템에서 생성한 읽기 전용 스키마입니다. 이 경우 XDM Individual Profile 클래스입니다. 결합 보기 스키마에 대한 자세한 내용은 스키마 구성 안내서🔗의 기본 사항에서 결합 섹션을 참조하십시오.

이 자습서에서 수행하는 단계는 Catalog API를 사용하여 XDM Individual Profile 결합 스키마를 참조하는 데이터 세트를 만드는 방법에 대해 설명합니다. 또한 Platform 사용자 인터페이스를 사용하여 결합 스키마를 참조하는 데이터 세트를 만들 수도 있습니다. UI 사용 단계는 세그먼트 내보내기🔗에 대한 이 UI 자습서에 요약되어 있지만, 여기에 적용할 수도 있습니다. 완료되면 이 자습서로 돌아가서 새 내보내기 작업을 시작하는 단계를 진행할 수 있습니다.

이미 호환되는 데이터 세트가 있고 해당 ID를 알고 있는 경우 새 내보내기 작업을 시작하는 단계로 직접 진행할 수 있습니다.

API 형식

POST /dataSets

요청

다음 요청은 페이로드에 구성 매개 변수를 제공하는 새 데이터 세트를 만듭니다.

curl -X POST \
  https://platform.adobe.io/data/foundation/catalog/dataSets \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "name": "Profile Data Export",
        "schemaRef": {
          "id": "https://ns.adobe.com/xdm/context/profile__union",
          "contentType": "application/vnd.adobe.xed+json;version=1"
        }
      }'
속성 설명
name 데이터 세트에 대한 수사적 이름입니다.
schemaRef.id 데이터 집합과 연결할 결합 보기(스키마)의 ID입니다.

응답

성공적인 응답은 새로 생성된 데이터 세트의 읽기 전용, 시스템 생성 및 고유 ID가 포함된 배열을 반환합니다. 프로필 데이터를 성공적으로 내보내려면 올바르게 구성된 데이터 세트 ID가 필요합니다.

[
  "@/datasets/5b020a27e7040801dedba61b"
] 

내보내기 작업 시작

조합 유지 데이터 세트가 있는 경우 실시간 고객 프로필 API에서 /export/jobs 종단점에 POST 요청을 하고 요청 본문에 내보내려는 데이터의 세부 사항을 제공하여 프로필 데이터를 데이터 세트에 유지하는 내보내기 작업을 만들 수 있습니다.

API 형식

POST /export/jobs

요청

다음 요청은 페이로드에 구성 매개 변수를 제공하여 새 내보내기 작업을 만듭니다.

curl -X POST \
  https://platform.adobe.io/data/core/ups/export/jobs \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
    "fields": "identities.id,personalEmail.address",
    "mergePolicy": {
      "id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
      "version": 1
    },
    "additionalFields" : {
      "eventList": {
        "fields": "environment.browserDetails.name,environment.browserDetails.version",
        "filter": {
          "fromIngestTimestamp": "2018-10-25T13:22:04-07:00"
        }
      }
    }
    "destination": {
      "datasetId": "5b020a27e7040801dedba61b",
      "segmentPerBatch": false
    },
    "schema": {
      "name": "_xdm.context.profile"
    }
  }' 
속성 설명
fields (선택 사항) 내보내기에 포함할 데이터 필드를 이 매개 변수에 제공된 필드로만 제한합니다. 이 값을 생략하면 내보낸 데이터에 모든 필드가 포함됩니다.
mergePolicy (선택 사항) 내보낸 데이터를 제어할 병합 정책을 지정합니다. 내보낼 세그먼트가 여러 개 있는 경우 이 매개 변수를 포함하십시오.
mergePolicy.id 병합 정책의 ID입니다.
mergePolicy.version 사용할 병합 정책의 특정 버전입니다. 이 값을 생략하면 기본적으로 최신 버전으로 설정됩니다.
additionalFields.eventList (선택 사항) 다음 설정 중 하나 이상을 제공하여 하위 객체 또는 관련 객체에 대해 내보낸 시계열 이벤트 필드를 제어합니다.
  • eventList.fields: 내보낼 필드를 제어합니다.
  • eventList.filter: 연관된 객체에서 포함된 결과를 제한하는 기준을 지정합니다. 내보내기에 필요한 최소값(일반적으로 날짜)이 필요합니다.
  • eventList.filter.fromIngestTimestamp: 시계열 이벤트를 제공된 타임스탬프 이후에 수집된 이벤트로 필터링합니다. 이벤트 시간 자체가 아니라 이벤트의 수집 시간입니다.
destination (필수) 내보낸 데이터에 대한 대상 정보:
  • destination.datasetId: (필수) 데이터를 내보낼 데이터 세트의 ID입니다.
  • destination.segmentPerBatch: (선택 사항) 제공되지 않을 경우 기본값이 로 설정되는 부울 값입니다 false. false 값을 지정하면 모든 세그먼트 ID를 단일 배치 ID로 내보냅니다. true 값은 하나의 세그먼트 ID를 하나의 배치 ID로 내보냅니다. 값을 true으로 설정하면 배치 내보내기 성능에 영향을 줄 수 있습니다.
schema.name (필수) 데이터를 내보낼 데이터 세트와 연결된 스키마의 이름입니다.
노트

프로필 데이터만 내보내고 관련 시계열 데이터를 포함하지 않으려면 요청에서 "additionalFields" 개체를 제거합니다.

응답

성공적인 응답은 요청에 지정된 대로 프로필 데이터로 채워진 데이터 세트를 반환합니다.

{
    "profileInstanceId": "ups",
    "jobType": "BATCH",
    "id": 24115,
    "schema": {
        "name": "_xdm.context.profile"
    },
    "mergePolicy": {
        "id": "0bf16e61-90e9-4204-b8fa-ad250360957b",
        "version": 1
    },
    "status": "NEW",
    "requestId": "IwkVcD4RupdSmX376OBVORvcvTdA4ypN",
    "computeGatewayJobId": {},
    "metrics": {
        "totalTime": {
            "startTimeInMs": 1559674261657
        }
    },
    "destination": {
      "dataSetId" : "5cf6bcf79ecc7c14530fe436",
      "segmentPerBatch": false,
      "batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
    },
    "updateTime": 1559674261868,
    "imsOrgId": "{IMS_ORG}",
    "creationTime": 1559674261657
}

모든 내보내기 작업 나열

export/jobs 종단점에 대한 GET 요청을 수행하여 특정 IMS 조직에 대한 모든 내보내기 작업 목록을 반환할 수 있습니다. 이 요청은 아래와 같이 쿼리 매개 변수 limitoffset도 지원합니다.

API 형식

GET /export/jobs
GET /export/jobs?{QUERY_PARAMETERS}
매개 변수 설명
start 요청 만들기 시간에 따라 반환된 결과 페이지를 오프셋합니다. 예: start=4
limit 반환된 결과 수를 제한합니다. 예: limit=10
page 요청의 생성 시간에 따라 특정 결과 페이지를 반환합니다. 예: page=2
sort 결과를 오름차순( asc ) 또는 내림차순( desc )으로 특정 필드별로 정렬합니다. 여러 결과 페이지를 반환하는 경우 정렬 매개 변수가 작동하지 않습니다. 예: sort=updateTime:asc

요청

curl -X GET \
  https://platform.adobe.io/data/core/ups/export/jobs/ \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}'
  -H 'x-sandbox-name: {SANDBOX_NAME}' 

응답

응답에는 IMS 조직에서 만든 내보내기 작업이 포함된 records 개체가 포함되어 있습니다.

{
  "records": [
    {
      "profileInstanceId": "ups",
      "jobType": "BATCH",
      "id": 726,
      "schema": {
          "name": "_xdm.context.profile"
      },
      "mergePolicy": {
          "id": "timestampOrdered-none-mp",
          "version": 1
      },
      "status": "SUCCEEDED",
      "requestId": "d995479c-8a08-4240-903b-af469c67be1f",
      "computeGatewayJobId": {
          "exportJob": "f3058161-7349-4ca9-807d-212cee2c2e94",
          "pushJob": "feaeca05-d137-4605-aa4e-21d19d801fc6"
      },
      "metrics": {
          "totalTime": {
              "startTimeInMs": 1538615973895,
              "endTimeInMs": 1538616233239,
              "totalTimeInMs": 259344
          },
          "profileExportTime": {
              "startTimeInMs": 1538616067445,
              "endTimeInMs": 1538616139576,
              "totalTimeInMs": 72131
          },
          "aCPDatasetWriteTime": {
              "startTimeInMs": 1538616195172,
              "endTimeInMs": 1538616195715,
              "totalTimeInMs": 543
          }
      },
      "destination": {
          "datasetId": "5b7c86968f7b6501e21ba9df",
          "batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
      },
      "updateTime": 1538616233239,
      "imsOrgId": "{IMS_ORG}",
      "creationTime": 1538615973895
    },
    {
      "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": "7a93d2ff-a220-4bae-9a4e-5f3c35032be3"
            }
        ]
      },
      "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",
          "batchId": ""
      },
      "updateTime": 1538573922551,
      "imsOrgId": "{IMS_ORG}",
      "creationTime": 1538573416687
    }
  ],
  "page": {
      "sortField": "createdTime",
      "sort": "desc",
      "pageOffset": "1538573416687_722",
      "pageSize": 2
  },
  "link": {
      "next": "/export/jobs/?limit=2&offset=1538573416687_722"
  }
}

내보내기 진행 모니터링

특정 내보내기 작업의 세부 사항을 보거나 처리 시 해당 상태를 모니터링하려면 /export/jobs 종단점에 GET 요청을 수행하고 경로에 내보내기 작업의 id 을 포함할 수 있습니다. status 필드가 "SUCCEEDED" 값을 반환하면 내보내기 작업이 완료됩니다.

API 형식

GET /export/jobs/{EXPORT_JOB_ID}
매개 변수 설명
{EXPORT_JOB_ID} 액세스할 내보내기 작업의 id

요청

curl -X GET \
  https://platform.adobe.io/data/core/ups/export/jobs/24115 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

응답

{
    "profileInstanceId": "ups",
    "jobType": "BATCH",
    "id": 24115,
    "schema": {
        "name": "_xdm.context.profile"
    },
    "mergePolicy": {
        "id": "0bf16e61-90e9-4204-b8fa-ad250360957b",
        "version": 1
    },
    "status": "SUCCEEDED",
    "requestId": "YwMt1H8QbVlGT2pzyxgwFHTwzpMbHrTq",
    "computeGatewayJobId": {
      "exportJob": "305a2e5c-2cf3-4746-9b3d-3c5af0437754",
      "pushJob": "963f275e-91a3-4fa1-8417-d2ca00b16a8a"
    },
    "metrics": {
      "totalTime": {
        "startTimeInMs": 1547053539564,
        "endTimeInMs": 1547054743929,
        "totalTimeInMs": 1204365
      },
      "profileExportTime": {
        "startTimeInMs": 1547053667591,
        "endTimeInMs": 1547053778195,
        "totalTimeInMs": 110604
      },
      "aCPDatasetWriteTime": {
        "startTimeInMs": 1547054660416,
        "endTimeInMs": 1547054698918,
        "totalTimeInMs": 38502
      }
    },
    "destination": {
      "dataSetId" : "5cf6bcf79ecc7c14530fe436",
      "segmentPerBatch": false,
      "batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
    },
    "updateTime": 1559674261868,
    "imsOrgId": "{IMS_ORG}",
    "creationTime": 1559674261657
}
속성 설명
batchId 프로필 데이터를 읽을 때 조회 목적으로 사용할 성공적인 내보내기에서 생성된 일괄 처리의 식별자입니다.

내보내기 작업 취소

Experience Platform을 사용하면 기존 내보내기 작업을 취소할 수 있습니다. 내보내기 작업이 완료되지 않았거나 처리 단계에서 멈춘 경우를 포함하여 여러 가지 이유로 유용할 수 있습니다. 내보내기 작업을 취소하려면 /export/jobs 종단점에 대한 DELETE 요청을 수행하고 요청 경로에 취소할 내보내기 작업의 id 을 포함할 수 있습니다.

API 형식

DELETE /export/jobs/{EXPORT_JOB_ID}
매개 변수 설명
{EXPORT_JOB_ID} 액세스할 내보내기 작업의 id

요청

curl -X POST \
  https://platform.adobe.io/data/core/ups/export/jobs/726 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

응답

삭제 요청이 성공하면 HTTP 상태 204(콘텐츠 없음) 및 빈 응답 본문을 반환하여 취소 작업이 성공적으로 수행되었음을 나타냅니다.

다음 단계

내보내기가 성공적으로 완료되면 Experience Platform의 Data Lake 내에서 데이터를 사용할 수 있습니다. 그런 다음 데이터 액세스 API를 사용하여 내보내기와 연결된 batchId를 사용하여 데이터에 액세스할 수 있습니다. 내보내기 크기에 따라 데이터가 청크 단위일 수 있으며 배치는 여러 파일로 구성될 수 있습니다.

데이터 액세스 API를 사용하여 배치 파일에 액세스하고 다운로드하는 방법에 대한 단계별 지침은 데이터 액세스 자습서를 따르십시오.

Adobe Experience Platform 쿼리 서비스를 사용하여 실시간 고객 프로필 데이터를 성공적으로 내보낼 수도 있습니다. UI 또는 RESTful API를 사용하는 쿼리 서비스를 사용하여 데이터 레이크 내의 데이터에 대한 쿼리를 작성, 유효성 검사 및 실행할 수 있습니다.

대상 데이터를 쿼리하는 방법에 대한 자세한 내용은 쿼리 서비스 설명서를 검토하십시오.

부록

다음 섹션에는 프로필 API의 내보내기 작업에 대한 추가 정보가 포함되어 있습니다.

추가 내보내기 페이로드 예

내보내기 작업을 시작하는 의 섹션에 표시된 API 호출 예에서는 프로필(레코드)과 이벤트(시계열) 데이터를 모두 포함하는 작업을 만듭니다. 이 섹션에서는 내보내기를 한 데이터 유형 또는 다른 데이터 유형을 포함하도록 제한하는 추가적인 요청 페이로드 예를 제공합니다.

다음 페이로드는 프로필 데이터(이벤트 없음)만 포함하는 내보내기 작업을 만듭니다.

{
    "fields": "identities.id,personalEmail.address",
    "mergePolicy": {
      "id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
      "version": 1
    },
    "destination": {
      "datasetId": "5b020a27e7040801dedba61b",
      "segmentPerBatch": false
    },
    "schema": {
      "name": "_xdm.context.profile"
    }
  }

이벤트 데이터(프로필 속성 없음)만 포함하는 내보내기 작업을 만들려면 페이로드가 다음과 유사할 수 있습니다.

{
    "fields": "identityMap",
    "mergePolicy": {
      "id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
      "version": 1
    },
    "additionalFields" : {
      "eventList": {
        "fields": "environment.browserDetails.name,environment.browserDetails.version",
        "filter": {
          "fromIngestTimestamp": "2018-10-25T13:22:04-07:00"
        }
      }
    },
    "destination": {
      "datasetId": "5b020a27e7040801dedba61b",
      "segmentPerBatch": false
    },
    "schema": {
      "name": "_xdm.context.profile"
    }
  }

세그먼트 내보내기

내보내기 작업 종단점을 사용하여 Profile 데이터 대신 대상 세그먼트를 내보낼 수도 있습니다. 자세한 내용은 세그멘테이션 API🔗에서 작업 내보내기 의 안내서를 참조하십시오.

이 페이지에서는