Show Menu
화제×

API를 사용하여 Adobe의 실시간 고객 데이터 플랫폼에서 스트리밍 대상에 연결하고 데이터 활성화

Adobe Real-time CDP의 Amazon Kinesis 대상 및 Azure Event Hubs 대상은 현재 베타 버전입니다. 설명서 및 기능은 변경될 수 있습니다.
이 자습서에서는 API 호출을 사용하여 Adobe Experience Platform 데이터에 연결하고, 스트리밍 클라우드 스토리지 대상에 대한 연결( Amazon Kinesis 또는 Azure 이벤트 허브 )을 만들고, 새로 만든 대상에 데이터 흐름을 만들고, 새로 만든 대상에 데이터를 활성화하는 방법을 설명합니다.
이 자습서는 모든 예에서 Amazon Kinesis 대상을 사용하지만 단계는 동일합니다 Azure Event Hubs.
Adobe의 실시간 CDP에서 사용자 인터페이스를 사용하여 대상에 연결하고 데이터를 활성화하려면 대상 연결 및 대상 에 프로필 및 세그먼트 활성화를 대상에 프로필 및 세그먼트 활성화 참조하십시오.

시작하기

이 가이드에서는 Adobe Experience Platform의 다음 구성 요소에 대해 작업해야 합니다.
  • XDM(Experience Data Model) 시스템 : 고객 경험 데이터를 구성하는 표준 프레임워크
  • 카탈로그 서비스 : Catalog는 Experience Platform 내의 데이터 위치 및 계열에 대한 기록 시스템입니다.
  • 샌드박스 : 경험 플랫폼은 디지털 경험 애플리케이션을 개발하고 발전시키는 데 도움이 되도록 단일 플랫폼 인스턴스를 별도의 가상 환경으로 분할하는 가상 샌드박스를 제공합니다.
다음 섹션에서는 Adobe Real-time CDP에서 스트리밍 대상으로 데이터를 활성화하기 위해 알아야 할 추가 정보를 제공합니다.

필요한 자격 증명 수집

이 자습서의 단계를 완료하려면 연결 및 활성화 중인 대상 유형에 따라 다음 자격 증명이 준비되어야 합니다.
  • 연결 Amazon Kinesis : accessKeyId , secretKey``region 또는 connectionUrl
  • 연결 Azure Event Hubs : sasKeyName , sasKey , namespace

샘플 API 호출 읽기

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

필수 및 선택적 헤더에 대한 값 수집

플랫폼 API를 호출하려면 먼저 인증 자습서를 완료해야 합니다 . 인증 자습서를 완료하면 아래와 같이 모든 경험 플랫폼 API 호출에서 각 필수 헤더에 대한 값을 제공합니다.
  • 인증: 무기명 {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}
경험 플랫폼의 리소스는 특정 가상 샌드박스로 분리할 수 있습니다. 플랫폼 API에 대한 요청에서 작업을 수행할 샌드박스의 이름과 ID를 지정할 수 있습니다. 선택적 매개 변수입니다.
  • x-sandbox-name: {SANDBOX_NAME}
페이로드(POST, PUT, PATCH)가 포함된 모든 요청에는 추가 미디어 유형 헤더가 필요합니다.
  • 컨텐츠 유형: application/json

Swagger 설명서

이 자습서에서는 Swagger에서 모든 API 호출에 대한 참조 설명서를 찾을 수 있습니다. https://platform.adobe.io/data/foundation/flowservice/swagger#/을 참조하십시오. 이 자습서와 Swagger 설명서 페이지를 동시에 사용하는 것이 좋습니다.

사용 가능한 스트리밍 대상 목록 보기

첫 번째 단계에서는 데이터를 활성화할 스트리밍 대상을 결정해야 합니다. 먼저 세그먼트를 연결하고 활성화할 수 있는 사용 가능한 대상 목록을 요청하는 호출을 수행하십시오. 사용 가능한 대상 목록을 connectionSpecs 반환하려면 끝점에 다음 GET 요청을 수행하십시오.
API 형식
GET /connectionSpecs

요청
curl --location --request GET 'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs' \
--header 'accept: application/json' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

응답
성공적인 응답에는 사용 가능한 대상 및 고유한 식별자( id )가 포함됩니다. 추가 단계에서 필요하므로 사용할 대상의 값을 저장합니다. 예를 들어 세그먼트를 연결해서 Amazon Kinesis 또는 Azure Event Hubs에 제공하려는 경우 응답에서 다음 조각을 찾습니다.
{
    "id": "86043421-563b-46ec-8e6c-e23184711bf6",
  "name": "Amazon Kinesis",
  ...
  ...
}

{
    "id": "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
  "name": "Azure Event Hubs",
  ...
  ...
}

경험 플랫폼 데이터에 연결

다음으로 프로필 데이터를 내보내고 원하는 대상에서 활성화할 수 있도록 경험 플랫폼 데이터에 연결해야 합니다. 이것은 아래에 설명된 두 가지 하위 단계로 구성됩니다.
  1. 먼저 기본 연결을 설정하여 경험 플랫폼에서 데이터에 대한 액세스를 인증하는 호출을 수행해야 합니다.
  2. 그런 다음 기본 연결 ID를 사용하여 소스 연결을 만들고 경험 플랫폼 데이터에 대한 연결을 설정하는 다른 호출을 만듭니다.

경험 플랫폼에서 데이터에 대한 액세스 권한 부여

API 형식
POST /connections

요청
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME} \
--header 'Content-Type: application/json' \
--data-raw '{
            "name": "Base connection to Experience Platform",
            "description": "This call establishes the connection to Experience Platform data",
            "connectionSpec": {
                "id": "{CONNECTION_SPEC_ID}",
                "version": "1.0"
            }
}'

  • {CONNECTION_SPEC_ID} : 통합 프로필 서비스에 연결 사양 ID를 사용하십시오 - 8a9c3494-9708-43d7-ae3f-cda01e5030e1 .
응답
성공적인 응답에는 기본 연결의 고유 식별자( id )가 포함됩니다. 소스 연결을 만들기 위해 다음 단계에서 필요에 따라 이 값을 저장합니다.
{
    "id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}

경험 플랫폼 데이터에 연결

API 형식
POST /sourceConnections

요청
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
            "name": "Connecting to Unified Profile Service",
            "description": "Optional",
            "connectionSpec": {
                "id": "{CONNECTION_SPEC_ID}",
                "version": "1.0"
            },
            "baseConnectionId": "{BASE_CONNECTION_ID}",
            "data": {
                "format": "json"
            },
            "params" : {}
}'

  • {BASE_CONNECTION_ID} : 이전 단계에서 얻은 ID를 사용합니다.
  • {CONNECTION_SPEC_ID} : 통합 프로필 서비스에 연결 사양 ID를 사용하십시오 - 8a9c3494-9708-43d7-ae3f-cda01e5030e1 .
응답
성공적인 응답은 새로 만든 통합 프로필 서비스에 대한 소스 연결에 대한 고유 식별자( id )를 반환합니다. 경험 플랫폼 데이터에 성공적으로 연결되었음을 확인합니다. 이 값은 이후 단계에서 필요에 따라 저장합니다.
{
    "id": "ed48ae9b-c774-4b6e-88ae-9bc7748b6e97"
}

스트리밍 대상에 연결

이 단계에서는 원하는 스트리밍 대상에 대한 연결을 설정합니다. 이것은 아래에 설명된 두 가지 하위 단계로 구성됩니다.
  1. 먼저 기본 연결을 설정하여 스트리밍 대상에 대한 액세스를 인증하는 호출을 수행해야 합니다.
  2. 그런 다음 기본 연결 ID를 사용하여 대상 연결을 만드는 다른 호출을 수행합니다. 이 호출은 내보낸 데이터가 배달될 저장소 계정의 위치와 내보낼 데이터의 형식을 지정합니다.

스트리밍 대상에 대한 액세스 권한 부여

API 형식
POST /connections

요청
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Connection for Amazon Kinesis/ Azure Event Hubs",
    "description": "your company's holiday campaign",
    "connectionSpec": {
        "id": "{_CONNECTION_SPEC_ID}",
        "version": "1.0"
    },
    "auth": {
        "specName": "{AUTHENTICATION_CREDENTIALS}",
        "params": { // use these values for Amazon Kinesis connections
            "accessKeyId": "{ACCESS_ID}",
            "secretKey": "{SECRET_KEY}",
            "region": "{REGION}"
        },
        "params": { // use these values for Azure Event Hubs connections
            "sasKeyName": "{SAS_KEY_NAME}",
            "sasKey": "{SAS_KEY}",
            "namespace": "{EVENT_HUB_NAMESPACE}"
        }        
    }
}'

  • {CONNECTION_SPEC_ID} : 사용 가능한 대상 목록을 가져옵니다. 단계에서 얻은 연결 사양 ID를 사용하십시오 .
  • {AUTHENTICATION_CREDENTIALS} : 스트리밍 대상 이름(예: Amazon Kinesis authentication credentials 또는 Azure Event Hubs authentication credentials .
  • {ACCESS_ID} : Amazon Kinesis 연결용. Amazon Kinesis 스토리지 위치에 대한 액세스 ID.
  • {SECRET_KEY} : Amazon Kinesis 연결용. Amazon Kinesis 스토리지 위치에 대한 비밀 키
  • {REGION} : Amazon Kinesis 연결용. Adobe 실시간 CDP가 데이터를 스트리밍하는 Amazon Kinesis 계정의 영역입니다.
  • {SAS_KEY_NAME} : Azure 이벤트 허브 연결에 대해. SAS 키 이름을 입력합니다. Azure Event Hubs Microsoft 문서에서 SAS 키 로 인증하는 방법에 대해 알아보십시오 .
  • {SAS_KEY} : Azure 이벤트 허브 연결에 대해. SAS 키를 입력합니다. Azure Event Hubs Microsoft 문서에서 SAS 키 로 인증하는 방법에 대해 알아보십시오 .
  • {EVENT_HUB_NAMESPACE} : Azure 이벤트 허브 연결에 대해. Adobe 실시간 CDP가 데이터를 스트리밍하는 Azure 이벤트 허브 네임스페이스를 채웁니다. 자세한 내용은 Microsoft 문서에서 이벤트 허브 네임스페이스 만들기를 참조하십시오.
응답
성공적인 응답에는 기본 연결의 고유 식별자( id )가 포함됩니다. 다음 단계에서 필요에 따라 이 값을 저장하여 대상 연결을 만듭니다.
{
    "id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}

저장소 위치 및 데이터 형식 지정

API 형식
POST /targetConnections

요청
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Amazon Kinesis/ Azure Event Hubs target connection",
    "description": "Connection to Amazon Kinesis/ Azure Event Hubs",
    "baseConnection": "{BASE_CONNECTION_ID}",
    "connectionSpec": {
        "id": "{CONNECTION_SPEC_ID}",
        "version": "1.0"
    },
    "data": {
        "format": "json",
    },
    "params": { // use these values for Amazon Kinesis connections
        "stream": "{NAME_OF_DATA_STREAM}", 
        "region": "{REGION}"
    },
    "params": { // use these values for Azure Event Hubs connections
        "eventHubName": "{EVENT_HUB_NAME}"
    }
}'

  • {BASE_CONNECTION_ID} : 위 단계에서 얻은 기본 연결 ID를 사용하십시오.
  • {CONNECTION_SPEC_ID} : 사용 가능한 대상 목록을 가져옵니다. 단계에서 얻은 연결 사양을 사용하십시오 .
  • {NAME_OF_DATA_STREAM} : Amazon Kinesis 연결용. Amazon Kinesis 계정에서 기존 데이터 스트림의 이름을 제공합니다. Adobe 실시간 CDP는 데이터를 이 스트림으로 내보냅니다.
  • {REGION} : Amazon Kinesis 연결용. Adobe 실시간 CDP가 데이터를 스트리밍하는 Amazon Kinesis 계정의 영역입니다.
  • {EVENT_HUB_NAME} : Azure 이벤트 허브 연결에 대해. Adobe 실시간 CDP가 데이터를 스트리밍하는 Azure 이벤트 허브 이름을 입력합니다. 자세한 내용은 Microsoft 설명서에서 이벤트 허브 만들기를 참조하십시오.
응답
성공적인 응답으로 새로 만든 대상 연결에 대한 고유 식별자( id )를 스트리밍 대상에 반환합니다. 이 값은 이후 단계에서 필요에 따라 저장합니다.
{
    "id": "12ab90c7-519c-4291-bd20-d64186b62da8"
}

데이터 흐름 만들기

이전 단계에서 얻은 ID를 사용하여 이제 경험 플랫폼 데이터와 데이터를 활성화할 대상 간에 데이터 흐름을 만들 수 있습니다. 이 단계를 경험 플랫폼과 원하는 대상 간에 나중에 데이터가 흐르도록 파이프라인을 구성하는 것으로 생각해 보십시오.
데이터 흐름을 만들려면, 아래와 같이 POST 요청을 수행하고 페이로드 내에 아래 언급된 값을 제공합니다.
다음 POST 요청을 수행하여 데이터 흐름을 만듭니다.
API 형식
POST /flows

요청
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-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 'Content-Type: application/json' \
-d  '{
   
        "name": "Create dataflow to Amazon Kinesis/ Azure Event Hubs",
        "description": "This operation creates a dataflow to Amazon Kinesis/ Azure Event Hubs",
        "flowSpec": {
            "id": "{FLOW_SPEC_ID}",
            "version": "1.0"
        },
        "sourceConnectionIds": [
            "{SOURCE_CONNECTION_ID}"
        ],
        "targetConnectionIds": [
            "{TARGET_CONNECTION_ID}"
        ]
    }

응답
성공적인 응답은 새로 만든 데이터 흐름 및 id ID를 반환합니다 etag . 두 값을 모두 적어 둡니다. 를 클릭하여 세그먼트를 활성화합니다.
{
    "id": "8256cfb4-17e6-432c-a469-6aedafb16cd5",
    "etag": "8256cfb4-17e6-432c-a469-6aedafb16cd5"
}

새 대상에 데이터 활성화

모든 연결과 데이터 흐름을 만들었으므로 이제 스트리밍 플랫폼에 프로필 데이터를 활성화할 수 있습니다. 이 단계에서는 대상으로 보내는 세그먼트 및 프로필 속성을 선택하고 데이터를 예약하고 대상에 보낼 수 있습니다.
세그먼트를 새 대상에 활성화하려면 아래 예와 유사한 JSON 패치 작업을 수행해야 합니다. 한 번의 호출에서 여러 세그먼트 및 프로필 속성을 활성화할 수 있습니다. JSON 패치에 대한 자세한 내용은 RFC 사양을 참조하십시오 .
API 형식
PATCH /flows

요청
curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'If-Match: "{ETAG}"' \
--data-raw '[
    {
        "op": "add",
        "path": "/transformations/0/params/segmentSelectors/selectors/-",
        "value": {
            "type": "PLATFORM_SEGMENT",
            "value": {
                "name": "Name of the segment that you are activating",
                "description": "Description of the segment that you are activating",
                "id": "{SEGMENT_ID}"
            }
        }
    },
        {
        "op": "add",
        "path": "/transformations/0/params/segmentSelectors/selectors/-",
        "value": {
            "type": "PLATFORM_SEGMENT",
            "value": {
                "name": "Name of the segment that you are activating",
                "description": "Description of the segment that you are activating",
                "id": "{SEGMENT_ID}"
            }
        }
    },
        {
        "op": "add",
        "path": "/transformations/0/params/profileSelectors/selectors/-",
        "value": {
            "type": "JSON_PATH",
            "value": {
                "operator": "EXISTS",
                "path": "{PROFILE_ATTRIBUTE}"
            }
        }
    },
        },
        {
        "op": "add",
        "path": "/transformations/0/params/profileSelectors/selectors/-",
        "value": {
            "type": "JSON_PATH",
            "value": {
                "operator": "EXISTS",
                "path": "{PROFILE_ATTRIBUTE}"
            }
        }
    }
]

  • {DATAFLOW_ID} : 이전 단계에서 얻은 데이터 흐름을 사용합니다.
  • {ETAG} : 이전 단계에서 얻은 태그를 사용합니다.
  • {SEGMENT_ID} : 이 대상으로 내보낼 세그먼트 ID를 제공합니다. 활성화할 세그먼트의 세그먼트 ID를 검색하려면 https://www.adobe.io/apis/experienceplatform/home/api-reference.html#/으로 이동하고 왼쪽 탐색 메뉴에서 세그멘테이션 서비스 API 를 선택한 다음 작업을 GET /segment/jobs 찾습니다.
  • {PROFILE_ATTRIBUTE} : 예: personalEmail.address 또는 person.lastName
응답
202 OK 응답을 찾아보십시오. 응답 본문이 반환되지 않습니다. 요청이 올바른지 확인하려면 다음 단계인 데이터 흐름 유효성 검사를 참조하십시오.

데이터 흐름 유효성 확인

튜토리얼의 마지막 단계에서는 세그먼트와 프로필 속성이 실제로 데이터 흐름에 올바르게 매핑되었는지 확인해야 합니다.
유효성을 확인하려면 다음 GET 요청을 수행하십시오.
API 형식
GET /flows

요청
curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: prod' \
--header 'If-Match: "{ETAG}"' 

  • {DATAFLOW_ID} : 이전 단계의 데이터 흐름을 사용합니다.
  • {ETAG} : 이전 단계의 태그를 사용합니다.
응답
반환된 응답에는 이전 단계에서 제출한 세그먼트 및 프로필 속성이 transformations 매개 변수에 포함되어야 합니다. 응답의 샘플 transformations 매개 변수는 다음과 같습니다.
"transformations": [
    {
        "name": "GeneralTransform",
        "params": {
            "profileSelectors": {
                        "selectors": [
                            {
                                "type": "JSON_PATH",
                                "value": {
                                    "path": "personalEmail.address",
                                    "operator": "EXISTS"
                                }
                            },
                            {
                                "type": "JSON_PATH",
                                "value": {
                                    "path": "person.lastname",
                                    "operator": "EXISTS"
                                }
                            }
                        ]
                    },
            "segmentSelectors": {
                "selectors": [
                    {
                        "type": "PLATFORM_SEGMENT",
                        "value": {
                            "name": "Men over 50",
                            "description": "",
                            "id": "72ddd79b-6b0a-4e97-a8d2-112ccd81bd02"
                        }
                    }
                ]
            }
        }
    }
],

내보낸 데이터
새 대상에 대한 데이터 활성화 단계의 프로필 속성 및 세그먼트 외에도 AWS Kinesis 및 Azure 이벤트 허브의 내보낸 데이터에는 ID 맵에 대한 정보도 포함됩니다. 내보낸 프로필의 ID를 나타냅니다(예: ECID , 모바일 ID, Google ID, 이메일 주소 등). 아래 예를 참조하십시오.
{
  "person": {
    "email": "yourstruly@adobe.con"
  },
  "segmentMembership": {
    "ups": {
      "72ddd79b-6b0a-4e97-a8d2-112ccd81bd02": {
        "lastQualificationTime": "2020-03-03T21:24:39Z",
        "status": "exited"
      },
      "7841ba61-23c1-4bb3-a495-00d695fe1e93": {
        "lastQualificationTime": "2020-03-04T23:37:33Z",
        "status": "existing"
      }
    }
  },
  "identityMap": {
    "ecid": [
      {
        "id": "14575006536349286404619648085736425115"
      },
      {
        "id": "66478888669296734530114754794777368480"
      }
    ],
    "email_lc_sha256": [
      {
        "id": "655332b5fa2aea4498bf7a290cff017cb4"
      },
      {
        "id": "66baf76ef9de8b42df8903f00e0e3dc0b7"
      }
    ]
  }
}

다음 단계

이 튜토리얼을 통해 Real-time CDP를 선호하는 스트리밍 대상 중 하나에 성공적으로 연결하여 각 대상에 대한 데이터 흐름을 설정합니다. 이제 고객 분석 또는 수행하고자 하는 기타 데이터 작업을 위한 대상에서 나가는 데이터를 사용할 수 있습니다. 자세한 내용은 다음 페이지를 참조하십시오.