흐름 서비스 API를 사용하여 Data Landing Zone을(를) Adobe Experience Platform에 연결
Data Landing Zone은(는) Adobe Experience Platform으로 파일을 가져올 수 있는 안전한 클라우드 기반 파일 저장소 기능입니다. 데이터는 7일 후 Data Landing Zone에서 자동으로 삭제됩니다.
이 자습서에서는 Data Landing ZoneAPIFlow Service 를 사용하여 소스 연결을 만드는 방법에 대한 단계를 안내합니다. 이 자습서에서는 Data Landing Zone을(를) 검색하고 자격 증명을 보고 새로 고치는 방법에 대한 지침도 제공합니다.
시작
이 안내서를 사용하려면 Experience Platform의 다음 구성 요소에 대해 이해하고 있어야 합니다.
또한 이 자습서에서는 Experience Platform API 시작하기에 대한 안내서를 읽고 Experience Platform API를 인증하고 설명서에 제공된 예제 호출을 해석하는 방법을 알아봐야 합니다.
다음 절에서는 Data Landing Zone API를 사용하여 Flow Service 원본 연결을 만들기 위해 알아야 할 추가 정보를 제공합니다.
사용 가능한 랜딩 영역 검색
type=user_drop_zone 액세스 제어 권한이 있어야 합니다. 자세한 내용은 액세스 제어 개요를 읽거나 제품 관리자에게 문의하여 필요한 권한을 받으십시오.API를 사용하여 Data Landing Zone에 액세스하는 첫 번째 단계는 /landingzone을(를) 요청 헤더의 일부로 제공하는 동안 Connectors API의 type=user_drop_zone 끝점에 GET 요청을 수행하는 것입니다.
API 형식
GET /data/foundation/connectors/landingzone?type=user_drop_zone
user_drop_zoneuser_drop_zone 형식을 사용하면 API에서 랜딩 영역 컨테이너와 사용 가능한 다른 형식의 컨테이너를 구별할 수 있습니다.요청
다음 요청은 기존 랜딩 영역을 검색합니다.
curl -X GET \
'https://platform.adobe.io/data/foundation/connectors/landingzone?type=user_drop_zone' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json'
응답
공급자에 따라 성공적인 요청은 다음을 반환합니다.
| code language-json |
|---|
|
| table 0-row-2 1-row-2 2-row-2 | |
|---|---|
| 속성 | 설명 |
containerName |
검색한 랜딩 영역의 이름입니다. |
containerTTL |
랜딩 영역 내의 데이터에 적용되는 만료 시간(일)입니다. 지정된 랜딩 영역 내의 모든 항목이 7일 후에 삭제됩니다. |
| code language-json |
|---|
|
Data Landing Zone 자격 증명 검색
Data Landing Zone에 대한 자격 증명을 검색하려면 /credentials API의 Connectors 끝점에 대한 GET 요청을 만드십시오.
API 형식
GET /data/foundation/connectors/landingzone/credentials?type=user_drop_zone
요청
다음 요청 예제는 기존 랜딩 영역에 대한 자격 증명을 검색합니다.
curl -X GET \
'https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
응답
공급자에 따라 성공적인 요청은 다음을 반환합니다.
| code language-json |
|---|
|
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 | |
|---|---|
| 속성 | 설명 |
containerName |
Data Landing Zone의 이름입니다. |
SASToken |
Data Landing Zone에 대한 공유 액세스 서명 토큰입니다. 이 문자열에는 요청을 승인하는 데 필요한 모든 정보가 포함되어 있습니다. |
storageAccountName |
저장소 계정의 이름입니다. |
SASUri |
Data Landing Zone에 대한 공유 액세스 서명 URI입니다. 이 문자열은 인증 중인 Data Landing Zone에 대한 URI와 해당 SAS 토큰의 조합입니다. |
expiryDate |
SAS 토큰이 만료되는 날짜. 응용 프로그램에서 토큰을 사용하여 Data Landing Zone에 데이터를 업로드하려면 만료 날짜 전에 토큰을 새로 고쳐야 합니다. 명시된 만료 날짜 이전에 토큰을 수동으로 새로 고치지 않는 경우, GET 자격 증명 호출이 수행될 때 자동으로 새로 고침되고 새 토큰을 제공합니다. |
| code language-json |
|---|
|
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 | |
|---|---|
| 속성 | 설명 |
credentials.clientId |
AWS에서 Data Landing Zone의 클라이언트 ID입니다. |
credentials.awsAccessKeyId |
AWS Data Landing Zone의 액세스 키 ID입니다. |
credentials.awsSecretAccessKey |
AWS에서 Data Landing Zone의 비밀 액세스 키입니다. |
credentials.awsSessionToken |
AWS 세션 토큰. |
dlzPath.bucketName |
AWS 버킷의 이름입니다. |
dlzPath.dlzFolder |
액세스 중인 Data Landing Zone 폴더입니다. |
dlzProvider |
사용 중인 Data Landing Zone 공급자입니다. Amazon의 경우 Amazon S3이(가) 됩니다. |
expiryTime |
만료 시간(unix 시간)입니다. |
API를 사용하여 필수 필드 검색
토큰을 생성한 후에는 아래 요청 예제를 사용하여 필수 필드를 프로그래밍 방식으로 검색할 수 있습니다.
| code language-py |
|---|
|
| code language-java |
|---|
|
Data Landing Zone 자격 증명 업데이트
SASToken API의 /credentials 끝점에 대한 POST 요청을 수행하여 Connectors을(를) 업데이트할 수 있습니다.
API 형식
POST /data/foundation/connectors/landingzone/credentials?type=user_drop_zone&action=refresh
user_drop_zoneuser_drop_zone 형식을 사용하면 API에서 랜딩 영역 컨테이너와 사용 가능한 다른 형식의 컨테이너를 구별할 수 있습니다.refreshrefresh 동작을 사용하면 랜딩 영역 자격 증명을 재설정하고 새 SASToken을(를) 자동으로 생성할 수 있습니다.요청
다음 요청은 랜딩 영역 자격 증명을 업데이트합니다.
curl -X POST \
'https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone&action=refresh' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
응답
다음 응답은 SASToken 및 SASUri에 대해 업데이트된 값을 반환합니다.
{
"containerName": "dlz-user-container",
"SASToken": "sv=2020-04-08&si=dlz-9c4d03b8-a6ff-41be-9dcf-20123e717e99&sr=c&sp=racwdlm&sig=JbRMoDmFHQU4OWOpgrKdbZ1d%2BkvslO35%2FXTqBO%2FgbRA%3D",
"storageAccountName": "dlblobstore99hh25i3dflek",
"SASUri": "https://dlblobstore99hh25i3dflek.blob.core.windows.net/dlz-user-container?sv=2020-04-08&si=dlz-9c4d03b8-a6ff-41be-9dcf-20123e717e99&sr=c&sp=racwdlm&sig=JbRMoDmFHQU4OWOpgrKdbZ1d%2BkvslO35%2FXTqBO%2FgbRA%3D",
"expiryDate": "2024-01-06"
}
랜딩 영역 파일 구조 및 콘텐츠 탐색
connectionSpecs API의 Flow Service 끝점에 대한 GET 요청을 통해 랜딩 영역의 파일 구조 및 콘텐츠를 살펴볼 수 있습니다.
API 형식
GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=root
{CONNECTION_SPEC_ID}26f526f2-58f4-4712-961d-e41bf1ccc0e8입니다.요청
curl -X GET \
'http://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=root' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
응답
성공한 응답은 쿼리된 디렉터리 내에서 발견된 파일 및 폴더 배열을 반환합니다. 업로드할 파일의 path 속성을 기록해 두십시오. 파일의 구조를 검사하려면 다음 단계에서 해당 속성을 제공해야 합니다.
[
{
"type": "file",
"name": "account.csv",
"path": "dlz-user-container/account.csv",
"canPreview": true,
"canFetchSchema": true
},
{
"type": "file",
"name": "data8.csv",
"path": "dlz-user-container/data8.csv",
"canPreview": true,
"canFetchSchema": true
},
{
"type": "folder",
"name": "userdata1",
"path": "dlz-user-container/userdata1/",
"canPreview": false,
"canFetchSchema": false
}
]
랜딩 영역 파일 구조 및 콘텐츠 미리보기
랜딩 영역의 파일 구조를 검사하려면 파일의 경로와 유형을 쿼리 매개 변수로 제공하면서 GET 요청을 수행합니다.
API 형식
GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=file&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}
{CONNECTION_SPEC_ID}26f526f2-58f4-4712-961d-e41bf1ccc0e8입니다.{OBJECT_TYPE}file{OBJECT}dlz-user-container/data8.csv{FILE_TYPE}delimitedjsonparquet
{PREVIEW}-
true -
false
요청
curl -X GET \
'http://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=file&object=dlz-user-container/data8.csv&fileType=delimited&preview=true' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
응답
성공한 응답은 파일 이름 및 데이터 유형을 포함하여 쿼리된 파일의 구조를 반환합니다.
{
"format": "flat",
"schema": {
"columns": [
{
"name": "Id",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "FirstName",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "LastName",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "Email",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "Phone",
"type": "string",
"xdm": {
"type": "string"
}
}
]
},
"data": [
{
"Email": "rsmith@abc.com",
"FirstName": "Richard",
"Phone": "111111111",
"Id": "12345",
"LastName": "Smith"
},
{
"Email": "morgan@bac.com",
"FirstName": "Morgan",
"Phone": "22222222222",
"Id": "67890",
"LastName": "Hart"
}
]
}
determineProperties을(를) 사용하여 Data Landing Zone의 파일 속성 정보를 자동으로 검색
GET을 호출하여 소스의 내용과 구조를 탐색할 때 determineProperties 매개 변수를 사용하여 Data Landing Zone의 파일 내용에 대한 속성 정보를 자동으로 검색할 수 있습니다.
determineProperties개의 사용 사례
다음 표에서는 determineProperties 쿼리 매개 변수를 사용하거나 파일에 대한 정보를 수동으로 제공할 때 발생할 수 있는 다양한 시나리오를 간략하게 설명합니다.
determinePropertiesqueryParamsdetermineProperties이(가) 쿼리 매개 변수로 제공되면 파일 속성 검색이 발생하고 응답이 파일 형식, 압축 형식 및 열 구분 기호에 대한 정보를 포함하는 새 properties 키를 반환합니다.queryParams의 일부로 수동으로 제공되는 경우 해당 값을 사용하여 스키마를 생성하고 동일한 속성이 응답의 일부로 반환됩니다.API 형식
GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=file&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&determineProperties=true
determinePropertiestrue요청
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=file&object=dlz-user-container/garageWeek/file1&preview=true&determineProperties=true' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
응답
성공한 응답은 파일 이름 및 데이터 형식을 포함한 쿼리된 파일의 구조와 properties, fileType 및 compressionType에 대한 정보가 포함된 columnDelimiter 키를 반환합니다.
| code language-json |
|---|
|
properties.fileTypedelimited, json 및 parquet입니다.properties.compressionType쿼리된 파일에 사용된 해당 압축 유형입니다. 지원되는 압축 유형은 다음과 같습니다.
bzip2gzipzipDeflatetarGziptar
properties.columnDelimiter(,)입니다.소스 연결 만들기
소스 연결은 데이터가 수집되는 외부 소스와의 연결을 만들고 관리합니다. 소스 연결은 데이터 소스, 데이터 형식 및 데이터 흐름을 만드는 데 필요한 소스 연결 ID와 같은 정보로 구성됩니다. 소스 연결 인스턴스는 테넌트 및 조직에만 해당됩니다.
소스 연결을 만들려면 /sourceConnections API의 Flow Service 끝점에 대한 POST 요청을 만듭니다.
API 형식
POST /sourceConnections
요청
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Data Landing Zone source connection",
"data": {
"format": "delimited"
},
"params": {
"path": "dlz-user-container/data8.csv"
},
"connectionSpec": {
"id": "26f526f2-58f4-4712-961d-e41bf1ccc0e8",
"version": "1.0"
}
}'
namedata.formatparams.pathconnectionSpec.id26f526f2-58f4-4712-961d-e41bf1ccc0e8입니다.응답
성공한 응답은 새로 만든 원본 연결의 고유 식별자(id)를 반환합니다. 데이터 흐름을 만들려면 다음 자습서에서 이 ID가 필요합니다.
{
"id": "f5b46949-8c8d-4613-80cc-52c9c039e8b9",
"etag": "\"1400d460-0000-0200-0000-613be3520000\""
}
다음 단계
이 자습서에 따라 Data Landing Zone 자격 증명을 검색하고, Experience Platform으로 가져올 파일을 찾기 위해 해당 파일 구조를 탐색하고, 데이터를 Experience Platform으로 가져오기 시작할 소스 연결을 만들었습니다. 이제 다음 자습서로 이동하여 데이터 흐름을 만들어 Flow Service API를 사용하여 클라우드 저장소 데이터를 Experience Platform으로 가져오는 방법을 배울 수 있습니다.