Show Menu
화제×

Adobe Experience Platform을 위한 ETL 통합 개발

ETL 통합 가이드는 경험 플랫폼용 고성능의 보안 커넥터를 제작하고 데이터를 플랫폼에 인제스트하기 위한 일반적인 단계를 설명합니다.
또한 이 안내서에는 ETL 커넥터를 디자인할 때 사용할 샘플 API 호출, 각 Experience Platform 서비스에 대한 개요를 제공하는 설명서 링크 및 API의 사용에 대한 자세한 내용이 포함되어 있습니다.
샘플 통합은 Apache License 버전 2.0의 ETL 에코시스템 통합 참조 코드를 통해 GitHub에서 사용할 수 있습니다.

워크플로우

다음 워크플로우 다이어그램은 Adobe Experience Platform 구성 요소를 ETL 애플리케이션 및 커넥터와 통합하는 수준 높은 개요를 제공합니다.

Adobe Experience Platform 구성 요소

ETL 커넥터 통합과 관련된 여러 Experience Platform 구성 요소가 있습니다. 다음 목록에는 몇 가지 주요 구성 요소 및 기능이 요약되어 있습니다.
  • IMS(Adobe Identity Management System) - Adobe 서비스에 대한 인증을 위한 프레임워크를 제공합니다.
  • IMS 조직 - 제품 및 서비스를 소유하거나 라이선스를 부여하고 해당 구성원에 대한 액세스를 허용하는 기업 실체입니다.
  • IMS 사용자 - IMS 조직의 구성원. 조직 대 사용자 관계는 다대다.
  • 샌드박스 - 디지털 경험 애플리케이션을 개발하고 발전시키는 데 도움이 되는 단일 플랫폼 인스턴스인 가상 파티션입니다.
  • 데이터 검색 - 인제스트 및 변형된 데이터의 메타데이터를 경험 플랫폼에서 기록합니다.
  • 데이터 액세스 - 사용자에게 경험 플랫폼에서 데이터에 액세스할 수 있는 인터페이스를 제공합니다.
  • 데이터 통합 - 데이터 통합 API를 사용하여 데이터를 경험 플랫폼으로 푸시합니다.
  • 스키마 레지스트리 - Experience Platform에서 사용할 데이터 구조를 설명하는 스키마를 정의하고 저장합니다.

Experience Platform API 시작하기

다음 섹션에서는 Experience Platform API를 성공적으로 호출하기 위해 알아야 하거나 현재 보유하고 있는 추가 정보를 제공합니다.

샘플 API 호출 읽기

이 안내서에서는 요청의 서식을 지정하는 방법을 보여주는 예제 API 호출을 제공합니다. 여기에는 경로, 필수 헤더 및 올바른 형식의 요청 페이로드가 포함됩니다. API 응답에서 반환되는 샘플 JSON도 제공됩니다. 샘플 API 호출에 대한 설명서에 사용된 규칙에 대한 자세한 내용은 Experience Platform 문제 해결 안내서에서 API 호출 예를 읽는 방법에 대한 섹션을 참조하십시오.

필수 헤더에 대한 값 수집

플랫폼 API를 호출하려면 먼저 인증 자습서를 완료해야 합니다. 인증 튜토리얼을 완료하면 다음과 같이 모든 Experience Platform API 호출에서 각 필수 헤더에 대한 값이 제공됩니다.
  • 인증:베어러 {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}
경험 플랫폼의 모든 리소스는 특정 가상 샌드박스로 분리됩니다. 플랫폼 API에 대한 모든 요청에는 작업이 수행될 샌드박스의 이름을 지정하는 헤더가 필요합니다.
  • x-sandbox-name: {SANDBOX_NAME}
플랫폼의 샌드박스에 대한 자세한 내용은 샌드박스 개요 설명서를 참조하십시오.
페이로드(POST, PUT, PATCH)가 포함된 모든 요청에는 추가 헤더가 필요합니다.
  • 컨텐츠 유형:application/json

일반 사용자 흐름

먼저 ETL 사용자는 Experience Platform UI(사용자 인터페이스)에 로그인하여 표준 커넥터 또는 푸시 서비스 커넥터를 사용하여 인제스트할 데이터 세트를 만듭니다.
사용자는 UI에서 데이터 집합 스키마를 선택하여 출력 데이터 집합을 만듭니다. 스키마 선택은 플랫폼으로 인제스트되는 데이터 유형(레코드 또는 시간 시리즈)에 따라 달라집니다. 사용자는 UI 내의 스키마 탭을 클릭하여 스키마가 지원하는 동작 유형을 포함하여 사용 가능한 모든 스키마를 볼 수 있습니다.
ETL 도구에서 사용자는 자격 증명을 사용하여 적절한 연결을 구성한 후 매핑 변형 디자인을 시작합니다. ETL 도구는 이미 Experience Platform 커넥터를 설치했다고 가정합니다(이 통합 안내서에 정의되지 않은 프로세스).
샘플 ETL 도구 및 워크플로우에 대한 목업은 ETL 워크플로우에서 제공됩니다 . ETL 툴의 형식은 다를 수 있지만 대부분의 툴은 유사한 기능을 제공합니다.
ETL 커넥터는 데이터 및 오프셋을 인제스트할 날짜를 표시하는 타임스탬프 필터를 지정해야 합니다(즉, 데이터를 읽을 창). ETL 도구는 이 UI 또는 다른 관련 UI에서 이러한 두 매개 변수 사용을 지원해야 합니다. Adobe Experience Platform에서 이러한 매개 변수는 사용 가능한 날짜(있는 경우) 또는 데이터 세트의 일괄 처리 개체에 있는 캡처된 날짜에 매핑됩니다.

데이터 집합 목록 보기

매핑에 데이터 소스를 사용하면 카탈로그 API를 사용하여 사용 가능한 모든 데이터 집합 목록을 가져올 수 있습니다 .
단일 API 요청을 발행하여 사용 가능한 모든 데이터 집합(예:). GET /dataSets 최상의 방법은 응답의 크기를 제한하는 쿼리 매개 변수를 포함하는 것입니다.
전체 __ 데이터 세트 정보가 요청되는 경우 응답 페이로드가 3GB를 초과할 수 있으므로 전반적인 성능이 느려질 수 있습니다. 따라서 쿼리 매개 변수를 사용하여 필요한 정보만 필터링하면 카탈로그 쿼리를 보다 효율적으로 만들 수 있습니다.

목록 필터링

응답을 필터링할 때 앰퍼샌드( & )로 매개 변수를 구분하여 단일 호출에서 여러 필터를 사용할 수 있습니다. 일부 쿼리 매개 변수는 아래 샘플 요청에서 "속성" 필터와 같이 쉼표로 구분된 값 목록을 사용합니다.
카탈로그 응답은 구성된 제한에 따라 자동으로 미터됩니다. 그러나 "제한" 쿼리 매개 변수를 사용하여 제약 조건을 사용자 정의하고 반환되는 개체 수를 제한할 수 있습니다. 사전 구성된 카탈로그 응답 제한은 다음과 같습니다.
  • 제한 매개 변수를 지정하지 않으면 응답 페이로드당 최대 개체 수는 20개입니다.
  • 다른 모든 카탈로그 쿼리에 대한 전체 제한은 100개의 개체입니다.
  • 데이터 집합 쿼리의 경우 속성 쿼리 매개 변수를 사용하여 observableSchema가 요청되면 반환되는 데이터 집합의 최대 수는 20개입니다.
  • 잘못된 제한 매개 변수(포함 limit=0 )가 적절한 범위를 외곽선으로 하는 HTTP 400 오류와 일치합니다.
  • 제한이나 오프셋이 쿼리 매개 변수로 전달되면 헤더로 전달된 것보다 우선합니다.
쿼리 매개 변수는 카탈로그 서비스 개요에서 자세히 다룹니다.
API 형식
GET /catalog/dataSets
GET /catalog/dataSets?{filter1}={value1},{value2}&{filter2}={value3}

요청
curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets?limit=3&properties=name,description,schemaRef" \
  -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}"

응답
응답에는 쿼리 매개 변수에 지정된 "name", "description" 및 "schemaRef"를 표시하는 세 개의 ( limit=3 ) 데이터 집합이 포함되어 properties 있습니다.
{
    "5b95b155419ec801e6eee780": {
        "name": "Store Transactions",
        "description": "Retails Store Transactions",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    },
    "5c351fa2f5fee300000fa9e8": {
        "name": "Loyalty Members",
        "description": "Loyalty Program Members",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    },
    "5c1823b19e6f400000993885": {
        "name": "Web Traffic",
        "description": "Retail Web Traffic",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/2025a705890c6d4a4a06b16f8cf6f4ca",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    }
}

데이터 집합 스키마 보기

데이터 집합의 "schemaRef" 속성에는 데이터 집합의 기반이 되는 XDM 스키마를 참조하는 URI가 포함되어 있습니다. XDM 스키마("schemaRef")는 데이터 세트에 사용할 수 있는 모든 잠재적인 필드를 나타내며, 사용 중인 필드도 아닙니다(아래의 "observableSchema" 참조).
XDM 스키마는 작성될 수 있는 모든 필드 목록을 사용자에게 제공해야 할 때 사용하는 스키마입니다.
이전 응답 개체( https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18 )의 첫 번째 "schemaRef.id" 값은 스키마 레지스트리에서 특정 XDM 스키마를 가리키는 URI입니다. 스키마 레지스트리 API에 대한 조회(GET) 요청을 수행하여 스키마를 검색할 수 있습니다.
"schemaRef" 속성은 더 이상 사용되지 않는 "schema" 속성을 대체합니다. 데이터 세트에 "schemaRef"가 없거나 값이 없는 경우 "schema" 속성이 있는지 확인해야 합니다. 이 작업은 이전 호출의 properties 쿼리 매개 변수에서 "schemaRef"를 "schema"로 바꾸어 수행할 수 있습니다. "스키마" 속성에 대한 자세한 내용은 다음에 나오는 데이터 집합 "스키마" 속성 섹션에서 확인할 수 있습니다.
API 형식
GET /schemaregistry/tenant/schemas/{url encoded schemaRef.id}

요청
요청은 스키마의 URL 인코딩 id URI("schemaRef.id" 속성 값)를 사용하며 수락 헤더가 필요합니다.
curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/https%3A%2F%2Fns.adobe.com%2F{TENANT_ID}%2Fschemas%2F274f17bc5807ff307a046bab1489fb18 \
  -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}' \
  -H 'Accept: application/vnd.adobe.xed-full+json; version=1' \

응답 형식은 요청에서 전송된 수락 헤더 유형에 따라 달라집니다. 조회 요청도 수락 헤더에 포함되어야 version 합니다. 다음 표에서는 룩업에 대한 헤더 승인 개요를 제공합니다.
수락
설명
application/vnd.adobe.xed-id+json
목록(GET) 요청, 제목, ID 및 버전
application/vnd.adobe.xed-full+json; version={major version}
$refs and allOf resolved, has titles and description
application/vnd.adobe.xed+json; version={major version}
$ref 및 allOf가 있는 Raw에는 제목 및 설명이 있습니다.
application/vnd.adobe.xed-notext+json; version={major version}
$ref 및 allOf가 포함된 Raw, 제목 또는 설명 없음
application/vnd.adobe.xed-full-notext+json; version={major version}
$refs 및 all해결된 항목, 제목 또는 설명 없음
application/vnd.adobe.xed-full-desc+json; version={major version}
$refs 및 allOf해결된 설명자가 포함됨
그리고 application/vnd.adobe.xed-id+json 가장 일반적으로 사용되는 application/vnd.adobe.xed-full+json; version={major version} 수락 헤더입니다. application/vnd.adobe.xed-id+json 는 "title", "id" 및 "version"만 반환하므로 스키마 레지스트리의 리소스를 나열하는 것이 좋습니다. application/vnd.adobe.xed-full+json; version={major version} 은 "id"로 특정 리소스를 보는 것이 좋습니다. 모든 필드("속성" 아래에 중첩된 필드)와 제목 및 설명을 반환하므로 특정 리소스를 보는 것이 좋습니다.
응답
반환되는 JSON 스키마는 구조 및 필드 수준 정보("type", "format", "minimum", "maximum" 등)를 설명합니다. JSON으로 정리되어 있는 데이터 중 하나입니다. 통합(예: Portable or Scala)에 JSON 이외의 직렬화 형식을 사용하는 경우 스키마 레지스트리 안내서에는 원하는 JSON 유형("meta:xdmType")과 해당 표현물을 다른 형식으로 보여주는 표가 포함되어 있습니다.
이 표와 함께 스키마 레지스트리 개발자 안내서에는 스키마 레지스트리 API를 사용하여 수행할 수 있는 모든 호출의 심층 예가 포함되어 있습니다.

데이터 집합 "스키마" 속성(더 이상 사용되지 않음 - EOL 2019-05-30)

데이터 세트에 이제 더 이상 사용되지 않으며 이전 버전과의 호환성을 위해 일시적으로 사용할 수 있는 "스키마" 속성이 포함될 수 있습니다. 예를 들어, 이전에 수행한 "schema"가 쿼리 매개 변수에서 "schemaRef"로 대체된 경우 목록(GET) 요청이 이전에 수행한 요청과 유사한 경우 properties 다음을 반환할 수 있습니다.
{
  "5ba9452f7de80400007fc52a": {
    "name": "Sample Dataset 1",
    "description": "Description of Sample Dataset 1.",
    "schema": "@/xdms/context/person"
  }
}

데이터 집합의 "스키마" 속성이 채워지는 경우 스키마가 더 이상 사용되지 않는 /xdms 스키마이고 지원되는 경우 ETL 커넥터는 /xdms 끝점이 있는 "스키마" 속성의 값(카탈로그 API에서 더 이상 사용되지 않는 끝점 )을 사용하여 기존 스키마를 검색해야 합니다.
API 형식
GET /catalog/{"schema" property without the "@"}

요청
curl -X GET "https://platform.adobe.io/data/foundation/catalog/xdms/context/person?expansion=xdm" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

선택적 쿼리 매개 변수 expansion=xdm 는 API에 참조된 스키마를 완전히 확장 및 인라인 수행하도록 지시합니다. 이 작업은 사용자에게 모든 잠재적 필드 목록을 표시할 때 수행할 수 있습니다.
응답
데이터 집합 스키마 #view-dataset-schema 보기 단계와 유사하게 응답에는 JSON으로 직렬화된 데이터의 구조 및 필드 수준 정보를 설명하는 JSON 스키마가 포함되어 있습니다.
"스키마" 필드가 비어 있거나 완전히 없는 경우 커넥터는 "schemaRef" 필드를 읽고 이전 단계에 표시된 대로 스키마 레지스트리 API를 사용하여 데이터 집합 스키마를 확인해야 합니다 .

"observableSchema" 속성

데이터 집합의 "observableSchema" 속성에는 XDM 스키마 JSON의 JSON 구조와 일치하는 JSON 구조가 있습니다. "observableSchema"는 들어오는 입력 파일에 있는 필드를 포함합니다. Experience Platform에 데이터를 작성할 때 사용자가 대상 스키마의 모든 필드를 사용할 필요는 없습니다. 대신 사용 중인 필드만 제공해야 합니다.
관찰 가능한 스키마는 데이터를 읽거나 읽기/매핑에 사용할 수 있는 필드 목록을 표시하는 데 사용할 스키마입니다.
{
    "598d6e81b2745f000015edcb": {
        "observableSchema": {
            "type": "object",
            "meta:xdmType": "object",
            "properties": {
                "name": {
                    "type": "string",
                },
                "age": {
                    "type": "string",
                }
            }
        }
    }
}

데이터 미리 보기

ETL 애플리케이션은 데이터를 미리 볼 수 있는 기능을 제공할 수 있습니다(ETL 워크플로우의 "그림 8" ). 데이터 액세스 API 파섹
데이터 액세스 API를 사용하여 데이터를 미리 보기 위한 단계별 지침을 비롯한 추가 정보는 데이터 액세스 자습서를 참조하십시오.

"속성" 쿼리 매개 변수를 사용하여 데이터 집합 세부 정보 가져오기

위의 단계에서 데이터 집합 목록을 보는 것처럼 "속성" 쿼리 매개 변수를 사용하여 "파일"을 요청할 수 있습니다.
데이터 집합 및 사용 가능한 응답 필터 쿼리에 대한 자세한 내용은 카탈로그 서비스 개요를 참조할 수 있습니다.
API 형식
GET /catalog/dataSets?limit={value}&properties={value}

요청
curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets?limit=1&properties=files" \
  -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}"

응답
응답에는 "파일" 속성을 표시하는 하나의 데이터 세트( limit=1 )가 포함됩니다.
{
  "5bf479a6a8c862000050e3c7": {
    "files": "@/dataSets/5bf479a6a8c862000050e3c7/views/5bf479a654f52014cfffe7f1/files"
  }
}

"files" 속성을 사용하여 데이터 세트 파일 나열

GET 요청을 사용하여 "files" 속성을 사용하여 파일 세부 사항을 가져올 수도 있습니다.
API 형식
GET /catalog/dataSets/{DATASET_ID}/views/{VIEW_ID}/files

요청
curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets/5bf479a6a8c862000050e3c7/views/5bf479a654f52014cfffe7f1/files" \
  -H "Accept: application/json" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key : {API_KEY}"

응답
응답에는 데이터 집합 파일 ID가 최상위 속성으로 포함되며 데이터 집합 파일 ID 개체 내에 파일 세부 정보가 포함됩니다.
{
    "194e89b976494c9c8113b968c27c1472-1": {
        "batchId": "194e89b976494c9c8113b968c27c1472",
        "dataSetViewId": "5bf479a654f52014cfffe7f1",
        "imsOrg": "{IMS_ORG}",
        "availableDates": {},
        "createdUser": "{USER_ID}",
        "createdClient": "{API_KEY}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1542749145828,
        "updated": 1542749145828
    },
    "14d5758c107443e1a83c714e56ca79d0-1": {
        "batchId": "14d5758c107443e1a83c714e56ca79d0",
        "dataSetViewId": "5bf479a654f52014cfffe7f1",
        "imsOrg": "{IMS_ORG}",
        "availableDates": {},
        "createdUser": "{USER_ID}",
        "createdClient": "{API_KEY}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1542752699111,
        "updated": 1542752699111
    },
    "ea40946ac03140ec8ac4f25da360620a-1": {
        "batchId": "ea40946ac03140ec8ac4f25da360620a",
        "dataSetViewId": "5bf479a654f52014cfffe7f1",
        "imsOrg": "{IMS_ORG}",
        "availableDates": {},
        "createdUser": "{USER_ID}",
        "createdClient": "{API_KEY}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1542756935535,
        "updated": 1542756935535
    }
}

파일 세부 사항 가져오기

이전 응답에서 반환되는 데이터 집합 파일 ID를 GET 요청에서 사용하여 데이터 액세스 API를 통해 추가 파일 세부 정보를 가져올 수 있습니다.
데이터 액세스 개요에는 데이터 액세스 개요 데이터 액세스 API를 사용하는 방법에 대한 세부 사항이 포함되어 있습니다.
API 형식
GET /export/files/{DATASET_FILE_ID}

요청
curl -X GET "https://platform.adobe.io/data/foundation/export/files/ea40946ac03140ec8ac4f25da360620a-1" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key : {API_KEY}"

응답
[
    {
    "name": "{FILE_NAME}.parquet",
    "length": 2576,
    "_links": {
        "self": {
            "href": "https://platform.adobe.io/data/foundation/export/files/ea40946ac03140ec8ac4f25da360620a-1?path=samplefile.parquet"
            }
        }
    }
]

파일 데이터 미리 보기

API 형식
GET /export/files/{FILE_ID}?path={FILE_NAME}.{FILE_FORMAT}

요청
curl -X GET "https://platform.adobe.io/data/foundation/export/files/ea40946ac03140ec8ac4f25da360620a-1?path=samplefile.parquet" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key : {API_KEY}"

위의 요청에 대한 응답에는 파일 내용의 미리 보기가 포함됩니다.
자세한 요청 및 응답을 비롯한 데이터 액세스 API에 대한 자세한 내용은 데이터 액세스 개요를 참조하십시오.

데이터 세트에서 "fileDescription" 가져오기

변형된 데이터의 출력으로 대상 구성 요소인 데이터 엔지니어는 출력 데이터 세트(ETL 워크플로우에서 "그림 12" )를 선택합니다. XDM 스키마는 출력 데이터 집합과 연결됩니다. 쓸 데이터는 데이터 검색 API에서 데이터 집합 엔티티의 "fileDescription" 속성으로 식별됩니다. 이 정보는 데이터 집합 ID( {DATASET_ID} )를 사용하여 가져올 수 있습니다. JSON 응답의 "fileDescription" 속성은 요청된 정보를 제공합니다.
API 형식
GET /catalog/dataSets/{DATASET_ID}

속성
설명
{DATASET_ID}
액세스하려는 데이터 집합의 id 값입니다.
요청
curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets/59c93f3da7d0c00000798f68" \
-H "accept: application/json" \
-H "x-gw-ims-org-id: {IMS_ORG}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key : {API_KEY}"

응답
{
  "59c93f3da7d0c00000798f68": {
    "version": "1.0.4",
    "fileDescription": {
        "persisted": false,
        "format": "parquet"
    }
  }
}

데이터는 데이터 통합 API를 사용하여 경험 플랫폼에 기록됩니다 . 데이터 쓰기는 비동기 프로세스입니다. 데이터가 Adobe Experience Platform에 기록되면 데이터가 완전히 작성된 후에만 일괄 처리가 만들어지고 성공으로 표시됩니다.
Adobe Experience Platform의 데이터는 쪽모이 세공 마루 파일 형태로 작성해야 합니다.

실행 단계

실행이 시작되면 커넥터(소스 구성 요소에 정의되어 있음)는 데이터 액세스 API를 사용하여 경험 플랫폼의 데이터를 읽습니다 . 변환 프로세스는 특정 시간 범위의 데이터를 읽습니다. 내부적으로 소스 데이터 세트를 쿼리합니다. 쿼리 중에 매개 변수화된(시간 시리즈 데이터 또는 증분 데이터의 경우 롤링) 시작 날짜 및 목록 데이터 집합 파일을 사용하여 이러한 데이터 집합 파일에 대한 데이터를 요청하기 시작합니다.

변형 예

샘플 ETL 변환 문서에는 ID 처리 및 데이터 형식 매핑을 비롯한 다양한 변형 예가 포함되어 있습니다. 이러한 변형을 참조용으로 사용하십시오.

경험 플랫폼에서 데이터 읽기

카탈로그 API를 사용하면 지정된 시작 시간과 종료 시간 사이에 있는 모든 배치를 가져와서 배치가 만들어진 순서대로 정렬할 수 있습니다.
요청
curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches?dataSet=DATASETID&createdAfter=START_TIMESTAMP&createdBefore=END_TIMESTAMP&sort=desc:created" \
  -H "Accept: 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}"

배치 필터링에 대한 자세한 내용은 데이터 액세스 자습서를 참조하십시오.

일괄 처리

원하는 일괄 처리에 대한 ID가 있으면 ( {BATCH_ID} ) 데이터 액세스 API를 통해 특정 일괄 처리에 속하는 파일 목록을 검색할 수 있습니다 . 자세한 내용은 데이터 액세스 자습서를 참조하십시오.
요청
curl -X GET "https://platform.adobe.io/data/foundation/export/batches/{BATCH_ID}/files" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key : {API_KEY}"

파일 ID를 사용하여 파일에 액세스

파일의 고유 ID( {FILE_ID )를 사용하여 데이터 액세스 API를 사용하여 파일 이름, 크기(바이트), 다운로드 링크 등 파일의 특정 세부 정보에 액세스할 수 있습니다.
요청
curl -X GET "https://platform.adobe.io/data/foundation/export/files/{FILE_ID}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "x-api-key : {API_KEY}"

응답은 단일 파일 또는 디렉토리를 가리킬 수 있습니다. 각 항목에 대한 세부 사항은 데이터 액세스 자습서에서 확인할 수 있습니다.

파일 컨텐츠 액세스

데이터 액세스 API를 사용하여 특정 파일의 컨텐츠에 액세스할 수 있습니다. 내용을 가져오기 위해 파일 ID를 사용하여 파일에 액세스할 _links.self.href 때 반환되는 값을 사용하여 GET 요청이 수행됩니다.
요청
curl -X GET "https://platform.adobe.io/data/foundation/export/files/{DATASET_FILE_ID}?path=filename1.csv" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "x-api-key: {API_KEY}"

이 요청에 대한 응답에는 파일의 내용이 포함되어 있습니다. 응답 페이지 매김에 대한 자세한 내용을 포함한 자세한 내용은 데이터 액세스 API 를 통한 데이터 쿼리 방법 자습서를 참조하십시오.

스키마 준수 레코드 유효성 확인

데이터를 작성할 때 사용자는 XDM 스키마에 정의된 유효성 검사 규칙에 따라 데이터의 유효성을 검사하도록 선택할 수 있습니다. 스키마 유효성 검사에 대한 자세한 내용은 GitHub의 ETL 에코시스템 통합 참조 코드에 나와 있습니다 .
GitHub에 있는 참조 구현을 사용 중인 경우 시스템 속성을 사용하여 이 구현에서 스키마 유효성 검사를 활성화할 수 -DenableSchemaValidation=true 있습니다.
논리 XDM 유형에 대해 문자열 minLength maxlength 문자열 등의 속성을 minimum 사용하고 정수에 대한 유효성 검사를 수행할 maximum 수 있습니다. 스키마 레지스트리 API 개발자 안내서에는 XDM 유형과 유효성 검사에 사용할 수 있는 속성에 대한 개요를 설명하는 표가 포함되어 있습니다.
다양한 integer 유형에 대해 제공된 최소값과 최대값은 해당 유형이 지원할 수 있는 MIN 및 MAX 값이지만 이러한 값은 선택한 최소값과 최대값으로 제한할 수 있습니다.

일괄 처리 만들기

데이터가 처리되면 ETL 도구는 배치 통합 API를 사용하여 데이터를 다시 경험 플랫폼에 기록합니다 . 데이터를 데이터 세트에 추가하려면 먼저 묶음에 연결되어 있어야 하며, 나중에 특정 데이터 세트에 업로드됩니다.
요청
curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
  -H "accept: application/json" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}" \
  -d '{
        "datasetId":"{DATASET_ID}"
      }'

샘플 요청 및 응답을 포함한 일괄 처리 만들기에 대한 세부 사항은 일괄 처리 통합 개요를 참조하십시오.

데이터 세트에 쓰기

새 일괄 처리를 성공적으로 만든 후 파일을 특정 데이터 세트에 업로드할 수 있습니다. 여러 파일을 홍보할 때까지 일괄 게시할 수 있습니다. 작은 파일 업로드 API를 사용하여 파일을 업로드할 수 있습니다 .그러나 파일이 너무 크고 게이트웨이 제한이 초과된 경우 대용량 파일 업로드 API를 사용할 수 있습니다 . 대용량 파일 업로드와 작은 파일 업로드에 대한 자세한 내용은 일괄 처리 통합 개요를 참조하십시오.
요청
Adobe Experience Platform의 데이터는 쪽모이 세공 마루 파일 형태로 작성해야 합니다.
curl -X PUT "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/dataSets/{DATASET_ID}/files/{FILE_NAME}.parquet" \
  -H "accept: application/json" \
  -H "x-gw-ims-org-id:{IMS_ORG}" \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -H "x-api-key: API_KEY" \
  -H "content-type: application/octet-stream" \
  --data-binary "@{FILE_PATH_AND_NAME}.parquet"

일괄 업로드 완료 표시

모든 파일이 일괄 처리에 업로드되면 일괄 처리를 완료하도록 신호를 보낼 수 있습니다. 이렇게 하면 완료된 파일에 대해 카탈로그 "DataSetFile" 항목이 만들어지며 생성 배치와 연결됩니다. 그런 다음 카탈로그 일괄 처리가 성공적으로 표시되어 다운스트림 흐름을 트리거하여 사용 가능한 데이터를 인제스트합니다.
데이터는 먼저 Adobe Experience Platform의 스테이징 위치에 도착한 후 카탈로그 작성 및 유효성 검사 후 최종 위치로 이동됩니다. 모든 데이터가 영구 위치로 이동되면 일괄 처리는 성공적인 것으로 표시됩니다.
요청
curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization:Bearer {ACCESS_TOKEN}" \
  -H "x-api-key : {API_KEY}"

성공하면 HTTP 상태 200 OK가 반환되고 응답 본문이 비어 있게 됩니다.
ETL 도구는 데이터를 읽을 때 소스 데이터 집합의 타임스탬프를 기록합니다.
일정 또는 이벤트 호출에 의한 다음 변환 실행에서 ETL은 이전에 저장한 타임스탬프와 앞으로의 모든 데이터에서 데이터 요청을 시작합니다.

마지막 일괄 처리 상태 가져오기

ETL 도구에서 새 작업을 실행하기 전에 마지막 배치가 성공적으로 완료되었는지 확인해야 합니다. 카탈로그 서비스 API는 관련 배치의 세부 정보를 제공하는 배치별 옵션을 제공합니다.
요청
curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches?limit=1&sort=desc:created" \
  -H "Accept: application/json" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

응답
이전 배치 "status" 값이 아래와 같이 "success"인 경우 새 작업을 예약할 수 있습니다.
"{BATCH_ID}": {
    "imsOrg": "{IMS_ORG}",
    "created": 1494349962314,
    "createdClient": "{API_KEY}",
    "createdUser": "CLIENT_USER_ID@AdobeID",
    "updatedUser": "CLIENT_USER_ID@AdobeID",
    "updated": 1494349963467,
    "status": "success",
    "errors": [],
    "version": "1.0.1",
    "availableDates": {}
}

ID로 마지막 배치 상태 가져오기

Catalog Service API를 통해 GET 요청을 실행하여 개별 배치 상태를 검색할 수 {BATCH_ID} 있습니다. 사용된 {BATCH_ID} ID는 일괄 처리가 생성될 때 반환되는 ID와 같습니다.
요청
curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches/{BATCH_ID}" \
  -H "Accept: application/json" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

응답 - 성공
다음 응답에는 "성공"이 표시됩니다.
"{BATCH_ID}": {
    "imsOrg": "{IMS_ORG}",
    "created": 1494349962314,
    "createdClient": "{API_KEY}",
    "createdUser": "{CREATED_USER}",
    "updatedUser": "{UPDATED_USER}",
    "updated": 1494349962314,
    "status": "success",
    "errors": [],
    "version": "1.0.1",
    "availableDates": {}
}

응답 - 실패
오류가 발생하는 경우 응답에서 "오류"를 추출하여 ETL 도구에서 오류 메시지로 표시할 수 있습니다.
"{BATCH_ID}": {
    "imsOrg": "{IMS_ORG}",
    "created": 1494349962314,
    "createdClient": "{API_KEY}",
    "createdUser": "{CREATED_USER}",
    "updatedUser": "{UPDATED_USER}",
    "updated": 1494349962314,
    "status": "failure",
    "errors": [
        {
            "code": "200",
            "description": "Error in validating schema for file: 'adl://dataLake.azuredatalakestore.net/connectors-dev/stage/BATCHID/dataSetId/contact.csv' with errorMessage=adl://dataLake.azuredatalakestore.net/connectors-dev/stage/BATCHID/dataSetId/contact.csv is not a Parquet file. expected magic number at tail [80, 65, 82, 49] but found [57, 98, 55, 10] and errorType=java.lang.RuntimeException",
            "rows": []
        }
    ],
    "version": "1.0.1",
    "availableDates": {}
}

증분 데이터와 스냅샷 데이터 및 이벤트와 프로필 비교

데이터는 다음과 같이 2x2로 나타낼 수 있습니다.
증분 이벤트
증분 프로필
스냅샷 이벤트(발생 가능성이 낮음)
스냅샷 프로필
이벤트 데이터는 일반적으로 각 행에 인덱스 타임스탬프 열이 있을 때 발생합니다.
프로필 데이터는 일반적으로 데이터에 타임스탬프가 없고 각 행을 기본/복합 키로 식별할 수 있는 경우에 사용됩니다.
증분 데이터는 새 데이터/업데이트된 데이터만 시스템에 와서 데이터 세트의 현재 데이터에 추가됩니다.
스냅샷 데이터는 모든 데이터가 시스템에 들어와 데이터 세트에 있는 이전 데이터의 일부 또는 전체를 교체하는 경우입니다.
증분 이벤트의 경우 ETL 도구는 사용 가능한 날짜/배치 엔티티의 만들기 날짜를 사용해야 합니다. 푸시 서비스의 경우 사용 가능한 날짜가 없으므로 일괄 작성/업데이트된 날짜를 사용하여 증분을 표시합니다. 모든 증분 이벤트를 처리해야 합니다.
증분 프로파일의 경우 ETL 도구는 배치 엔티티의 생성/업데이트된 날짜를 사용합니다. 일반적으로 모든 증분 프로필 데이터 일괄 처리가 필요합니다.
스냅샷 이벤트는 데이터의 크기 때문에 발생할 가능성이 매우 낮습니다. 하지만 이 작업이 필요한 경우 ETL 도구는 처리를 위해 마지막 일괄 처리만 선택해야 합니다.
스냅샷 프로필을 사용하면 ETL 툴에서 시스템에 도착한 데이터의 마지막 일괄 처리를 선택해야 합니다. 그러나 변경 사항의 버전을 추적하는 것이 필요한 경우, 모든 배치를 처리해야 합니다. ETL 프로세스 내에서 중복 제거 처리를 수행하면 스토리지 비용을 절감할 수 있습니다.

일괄 재생 및 데이터 재처리

클라이언트가 지난 'n'일 동안 처리 중인 ETL 데이터가 예상대로 발생하지 않았거나 소스 데이터 자체가 올바르지 않았을 수 있음을 발견한 경우 일괄 재생 및 데이터 재처리가 필요할 수 있습니다.
이를 위해 클라이언트의 데이터 관리자는 플랫폼 UI를 사용하여 손상된 데이터가 포함된 배치를 제거합니다. 그런 다음 ETL을 다시 실행해야 하므로 올바른 데이터로 다시 채울 수 있습니다. 소스 자체에 데이터가 손상된 경우 데이터 엔지니어/관리자는 소스 배치를 수정하고 데이터를 다시 인제스트해야 합니다(Adobe Experience Platform 또는 ETL 커넥터를 통해).
생성되는 데이터의 유형을 기반으로, 데이터 엔지니어는 특정 데이터 세트에서 단일 배치 또는 모든 배치를 제거할 수 있습니다. Experience Platform 가이드라인에 따라 데이터가 제거/보관됩니다.
ETL 기능을 사용하여 데이터를 삭제하는 것이 중요할 가능성이 있습니다.
제거가 완료되면 클라이언트 관리자는 Adobe Experience Platform을 다시 구성하여 일괄 처리가 삭제될 때부터 핵심 서비스에 대한 처리를 다시 시작해야 합니다.

동시 배치 처리

클라이언트의 재량에 따라 데이터 관리자/엔지니어는 특정 데이터 세트의 특성에 따라 순차적 방식 또는 동시 방식으로 데이터를 추출, 변형 및 로드할 수 있습니다. 이것은 또한 클라이언트가 변형된 데이터로 타깃팅하는 사용 사례를 기반으로 합니다.
예를 들어 클라이언트가 업데이트할 수 있는 지속성 저장소에 대해 지속되고 있고 이벤트의 시퀀스 또는 순서가 중요한 경우 클라이언트는 순차적 ETL 변형을 사용하여 작업을 엄격히 처리해야 할 수 있습니다.
다른 경우에는 지정된 타임스탬프를 사용하여 내부적으로 정렬되는 다운스트림 애플리케이션/프로세스에서 순서가 잘못된 데이터를 처리할 수 있습니다. 이러한 경우 병렬 ETL 변형을 사용하면 처리 시간을 단축할 수 있습니다.
소스 배치의 경우 클라이언트 환경 설정 및 소비자 제한에 따라 다시 달라집니다. 행의 리젠시/순서에 관계없이 소스 데이터를 병렬로 선택할 수 있는 경우 변환 프로세스는 병렬 처리 정도가 높은 프로세스 배치를 생성할 수 있습니다(주문 외 처리를 기반으로 최적화). 그러나 변형이 타임스탬프 또는 변경 우선 순위 순서를 따라야 하는 경우 데이터 액세스 API 또는 ETL 도구 스케줄러/호출은 가능한 한 일괄 처리가 제대로 처리되지 않도록 해야 합니다.

Deferral

기본값은 입력 데이터가 아직 다운스트림 프로세스로 전송하기에 충분하지 않지만 향후 사용할 수 있는 프로세스입니다. 클라이언트는 향후 일치에 대한 데이터 창에 대한 개별 허용치를 결정하고, 데이터를 보관하고 다음 변환 실행에 재처리한다는 결정을 알리기 위해 처리 비용을 결정합니다. 향후 보존 기간 내에 데이터를 농축하고 조정/통합할 수 있을 것입니다. 이 순환은 행이 충분히 처리되거나 투자를 계속하기에는 너무 오래된 것으로 간주될 때까지 계속됩니다. 모든 반복은 이전 반복에서 지연된 모든 데이터의 상위 집합인 지연된 데이터를 생성합니다.
Adobe Experience Platform은 현재 지연된 데이터를 식별하지 않으므로 클라이언트 구현은 ETL 및 데이터 세트 수동 구성을 사용하여 지연된 데이터를 유지하는 데 사용할 수 있는 소스 데이터 세트를 미러링하는 플랫폼에서 다른 데이터 세트를 만들어야 합니다. 이 경우 지연된 데이터는 스냅샷 데이터와 비슷합니다. ETL 변환을 실행할 때마다 소스 데이터가 지연된 데이터와 통합되고 처리를 위해 전송됩니다.

Changelog

날짜
작업
설명
2019-01-19
데이터 세트에서 "필드" 속성을 제거했습니다.
이전에는 데이터 세트에 스키마 복사본이 포함된 "필드" 속성이 포함되었습니다. 이 기능은 더 이상 사용할 수 없습니다. "fields" 속성이 있으면 이 속성은 무시되어야 하며 대신 "observedSchema" 또는 "schemaRef"가 사용됩니다.
2019-03-15
데이터 집합에 추가된 "schemaRef" 속성
데이터 집합의 "schemaRef" 속성에는 데이터 집합이 기반으로 하는 XDM 스키마를 참조하는 URI가 포함되어 있으며 데이터 세트에 사용할 수 있는 모든 잠재적 필드를 나타냅니다.
2019-03-15
모든 최종 사용자 식별자는 "identityMap" 속성에 매핑됩니다.
"identityMap"은 CRM ID, ECID 또는 충성도 프로그램 ID와 같은 주체의 모든 고유 식별자를 캡슐화합니다. 이 맵은 Identity Service에서 제목에 대해 알려진 모든 ID와 익명 ID를 해결하기 위해 사용되며 각 최종 사용자에 대해 단일 ID 그래프가 생성됩니다.
2019-05-30
데이터 세트에서 EOL 및 "스키마" 속성 제거
데이터 집합 "스키마" 속성은 카탈로그 API에서 더 이상 사용되지 않는 /xdms 끝점을 사용하여 스키마에 대한 참조 링크를 제공했습니다. 새 스키마 레지스트리 API에서 참조되는 대로 스키마의 "id", "version" 및 "contentType"을 제공하는 "schemaRef"로 대체되었습니다.