API를 사용하여 데이터 집합 Data Access 쿼리

이 문서에서는 Adobe Experience Platform의 Data Access API를 사용하여 데이터 세트 내에 저장된 데이터를 찾고, 액세스하고, 다운로드하는 방법을 다루는 단계별 자습서를 제공합니다. 페이징이나 부분 다운로드 등 API의 일부 고유한 기능에도 소개됩니다. Data Access

시작하기

이 자습서에서는 데이터 세트를 만들고 채우는 방법에 대해 자세히 알아야 합니다. 자세한 내용은 데이터 세트 작성 자습서를 참조하십시오.

다음 섹션에서는 플랫폼 API를 성공적으로 호출하기 위해 알아야 할 추가 정보를 제공합니다.

샘플 API 호출 읽기

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

필수 헤더에 대한 값 수집

API를 호출하려면 Platform 먼저 인증 자습서를 완료해야 합니다. 인증 자습서를 완료하면 아래와 같이 모든 Experience Platform API 호출에서 각 필수 헤더에 대한 값을 제공합니다.

  • 인증:무기명 {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}

의 모든 리소스 Experience Platform 는 특정 가상 샌드박스와 분리됩니다. API에 대한 모든 Platform 요청에는 작업이 수행할 샌드박스의 이름을 지정하는 헤더가 필요합니다.

  • x-sandbox-name: {SANDBOX_NAME}
NOTE

의 샌드박스에 대한 자세한 내용 Platform은 샌드박스 개요 설명서를 참조하십시오.

페이로드(POST, PUT, PATCH)이 포함된 모든 요청에는 추가 헤더가 필요합니다.

  • 컨텐츠 유형:application/json

시퀀스 다이어그램

이 자습서는 아래 시퀀스 다이어그램에 나와 있는 단계에 따라 Data Access API의 핵심 기능을 강조 표시합니다.

API를 Catalog 사용하면 배치 및 파일에 대한 정보를 검색할 수 있습니다. API를 통해 파일 크기에 따라 HTTP를 통해 이러한 파일을 전체 또는 부분 다운로드로 액세스하고 다운로드할 수 있습니다. Data Access

데이터 찾기

API를 사용하기 전에 Data Access 액세스하려는 데이터의 위치를 식별해야 합니다. API에는 조직의 메타데이터를 검색하고 액세스하려는 일괄 처리 또는 파일의 ID를 검색하는 데 사용할 수 있는 두 개의 끝점이 있습니다. Catalog

  • GET /batches:조직 아래의 배치 목록을 반환합니다.
  • GET /dataSetFiles:조직의 파일 목록을 반환합니다.

API의 포괄적인 엔드포인트 목록은 Catalog API 참조를 참조하십시오 .

IMS 조직 아래에서 배치 목록 검색

API를 Catalog 사용하여 조직에서 배치 목록을 반환할 수 있습니다.

API 형식

GET /batches

요청

curl -X GET 'https://platform.adobe.io/data/foundation/catalog/batches/' \
  -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 조직과 관련된 모든 배치를 나열하는 객체를 포함하며 각 최상위 값은 배치를 나타냅니다. 개별 배치 객체에는 해당 특정 배치에 대한 세부 사항이 포함됩니다. 우주에서는 아래 응답이 최소화되었습니다.

{
    "{BATCH_ID_1}": {
        "imsOrg": "{IMS_ORG}",
        "created": 1516640135526,
        "createdClient": "{CREATED_CLIENT}",
        "createdUser": "{CREATED_BY}",
        "updatedUser": "{CREATED_BY}",
        "updated": 1516640135526,
        "status": "processing",
        "version": "1.0.0",
        "availableDates": {}
    },
    "{BATCH_ID_2}": {
    ...
    }
}

배치 목록 필터링

필터는 특정 사용 사례에 대한 관련 데이터를 검색하기 위해 특정 배치를 찾는 데 필요한 경우가 많습니다. 반환된 응답을 필터링하기 위해 매개 변수를 GET /batches 요청에 추가할 수 있습니다. 아래 요청은 특정 데이터 세트 내에서 지정된 시간 이후에 만들어진 모든 배치를 언제 만들었는지 기준으로 정렬하여 반환합니다.

API 형식

GET /batches?createdAfter={START_TIMESTAMP}&dataSet={DATASET_ID}&sort={SORT_BY}
속성 설명
{START_TIMESTAMP} 시작 타임스탬프(밀리초)입니다(예: 151483679900).
{DATASET_ID} 데이터 집합 식별자입니다.
{SORT_BY} 제공된 값별로 응답을 정렬합니다. 예를 들어 작성 날짜별로 개체를 내림차순으로 정렬합니다. desc:created

요청

curl -X GET 'https://platform.adobe.io/data/foundation/catalog/batches?createdAfter=1521053542579&dataSet=5cd9146b21dae914b71f654f&orderBy=desc:created' \
  -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}'

응답

{   "{BATCH_ID_3}": {
        "imsOrg": "{IMS_ORG}",
        "relatedObjects": [
            {
                "id": "5c01a91863540f14cd3d0439",
                "type": "dataSet"
            },
            {
                "id": "00998255b4a148a2bfd4804c2f327324",
                "type": "batch"
            }
        ],
        "status": "success",
        "metrics": {
            "recordsFailed": 0,
            "recordsWritten": 2,
            "startTime": 1550791835809,
            "endTime": 1550791994636
        },
        "errors": [],
        "created": 1550791457173,
        "createdClient": "{CLIENT_CREATED}",
        "createdUser": "{CREATED_BY}",
        "updatedUser": "{CREATED_BY}",
        "updated": 1550792060301,
        "version": "1.0.116"
    },
    "{BATCH_ID_4}": {
        "imsOrg": "{IMS_ORG}",
        "status": "success",
        "relatedObjects": [
            {
                "type": "batch",
                "id": "00aff31a9ae84a169d69b886cc63c063"
            },
            {
                "type": "dataSet",
                "id": "5bfde8c5905c5a000082857d"
            }
        ],
        "metrics": {
            "startTime": 1544571333876,
            "endTime": 1544571358291,
            "recordsRead": 4,
            "recordsWritten": 4
        },
        "errors": [],
        "created": 1544571077325,
        "createdClient": "{CLIENT_CREATED}",
        "createdUser": "{CREATED_BY}",
        "updatedUser": "{CREATED_BY}",
        "updated": 1544571368776,
        "version": "1.0.3"
    }
}

매개 변수 및 필터의 전체 목록은 카탈로그 API 참조에서 찾을 수 있습니다.

특정 배치에 속하는 모든 파일 목록 검색

액세스하려는 일괄 처리 ID가 있으므로 Data Access API를 사용하여 해당 일괄 처리에 속하는 파일 목록을 가져올 수 있습니다.

API 형식

GET /batches/{BATCH_ID}/files
속성 설명
{BATCH_ID} 액세스하려는 일괄 처리의 일괄 처리 식별자입니다.

요청

curl -X GET 'https://platform.adobe.io/data/foundation/export/batches/5c6f332168966814cd81d3d3/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}'

응답

{
    "data": [
        {
            "dataSetFileId": "8dcedb36-1cb2-4496-9a38-7b2041114b56-1",
            "dataSetViewId": "5cc6a9b60d4a5914b7940a7f",
            "version": "1.0.0",
            "created": "1558522305708",
            "updated": "1558522305708",
            "isValid": false,
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io:443/data/foundation/export/files/8dcedb36-1cb2-4496-9a38-7b2041114b56-1"
                }
            }
        }
    ],
    "_page": {
        "limit": 100,
        "count": 1
    }
}
}
속성 설명
data._links.self.href 이 파일에 액세스할 수 있는 URL.

응답에는 지정된 일괄 처리 내의 모든 파일을 나열하는 데이터 배열이 포함됩니다. 파일은 해당 파일 ID로 참조되며 이 ID는 dataSetFileId 필드 아래에 있습니다.

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

고유한 파일 ID가 있는 경우 Data Access API를 사용하여 파일 이름, 크기(바이트), 다운로드 링크 등 파일의 특정 세부 정보에 액세스할 수 있습니다.

API 형식

GET /files/{FILE_ID}
속성 설명
{FILE_ID} 액세스할 파일의 식별자입니다.

요청

curl -X GET 'https://platform.adobe.io/data/foundation/export/files/8dcedb36-1cb2-4496-9a38-7b2041114b56-1' \
  -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가 개별 파일을 가리키는지 또는 디렉토리를 가리키는지에 따라, 반환된 데이터 배열에 해당 디렉토리에 속하는 파일 목록이나 단일 항목이 포함될 수 있습니다. 각 파일 요소에는 파일 이름, 크기(바이트), 파일 다운로드 링크 등의 세부 사항이 포함됩니다.

사례 1:파일 ID가 단일 파일을 가리킵니다.

응답

{
    "data": [
        {
            "name": "{FILE_NAME}.parquet",
            "length": "249058",
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io/data/foundation/export/files/{FILE_ID_1}?path={FILE_NAME_1}.parquet"
                }
            }
        }
    ],
    "_page": {
        "limit": 100,
        "count": 1
    }
}
속성 설명
{FILE_NAME}.parquet 파일의 이름입니다.
_links.self.href 파일을 다운로드할 URL입니다.

사례 2:파일 ID가 디렉토리를 가리킵니다.

응답

{
    "data": [
        {
            "dataSetFileId": "{FILE_ID_2}",
            "dataSetViewId": "460590b01ba38afd1",
            "version": "1.0.0",
            "created": "150151267347",
            "updated": "150151267347",
            "isValid": true,
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io/data/foundation/export/files/{FILE_ID_2}"
                }
            }
        },
        {
            "dataSetFileId": "{FILE_ID_3}",
            "dataSetViewId": "460590b01ba38afd1",
            "version": "1.0.0",
            "created": "150151267685",
            "updated": "150151267685",
            "isValid": true,
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io/data/foundation/export/files/{FILE_ID_3}"
                }
            }
        }
    ],
    "_page": {
        "limit": 100,
        "count": 2
    }
}
속성 설명
data._links.self.href 연결된 파일을 다운로드할 URL입니다.

이 응답은 ID와 ID가 있는 두 개의 개별 파일이 포함된 디렉토리 {FILE_ID_2} 를 반환합니다 {FILE_ID_3}. 이 시나리오에서 파일에 액세스하려면 각 파일의 URL을 따라야 합니다.

파일의 메타데이터 검색

HEAD 요청을 수행하여 파일의 메타데이터를 검색할 수 있습니다. 파일의 크기와 바이트 및 파일 형식을 포함하여 파일의 메타데이터 헤더를 반환합니다.

API 형식

HEAD /files/{FILE_ID}?path={FILE_NAME}
속성 설명
{FILE_ID} 파일의 식별자입니다.
{FILE_NAME} 파일 이름(예: profiles.partiquoted)

요청

curl -I 'https://platform.adobe.io/data/foundation/export/files/8dcedb36-1cb2-4496-9a38-7b2041114b56-1?path=profiles.parquet' \
  -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}'

응답

응답 헤더에는 다음과 같이 쿼리된 파일의 메타데이터가 포함됩니다.

  • Content-Length:페이로드 크기(바이트)를 나타냅니다.
  • Content-Type:파일 유형을 나타냅니다.

파일 내용 액세스

또한 Data Access API를 사용하여 파일의 내용에 액세스할 수도 있습니다.

API 형식

GET /files/{FILE_ID}?path={FILE_NAME}
속성 설명
{FILE_ID} 파일의 식별자입니다.
{FILE_NAME} 파일 이름(예: profiles.partional).

요청

curl -X GET 'https://platform.adobe.io/data/foundation/export/files/8dcedb36-1cb2-4496-9a38-7b2041114b56-1?path=profiles.parquet' \
  -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}'

응답

성공적인 응답은 파일의 내용을 반환합니다.

파일의 일부 내용 다운로드

API를 통해 파일을 청크 단위로 다운로드할 수 있습니다. Data Access 파일에서 특정 바이트 범위를 다운로드하도록 GET /files/{FILE_ID} 요청하는 동안 범위 헤더를 지정할 수 있습니다. 범위를 지정하지 않으면 기본적으로 API가 전체 파일을 다운로드합니다.

이전 섹션의 HEAD 예제에서는 특정 파일의 크기를 바이트 단위로 보여 줍니다.

API 형식

GET /files/{FILE_ID}?path={FILE_NAME}
속성 설명
{FILE_ID} 파일의 식별자입니다.
{FILE_NAME} 파일 이름(예: profiles.partiquoted)

요청

curl -X GET 'https://platform.adobe.io/data/foundation/export/files/8dcedb36-1cb2-4496-9a38-7b2041114b56-1?path=profiles.parquet' \
  -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 'Range: bytes=0-99'
속성 설명
Range: bytes=0-99 다운로드할 바이트 범위를 지정합니다. 지정하지 않으면 API에서 전체 파일을 다운로드합니다. 이 예에서 처음 100바이트는 다운로드됩니다.

응답

응답 본문에는 HTTP 상태 206(부분 컨텐츠)과 함께 파일의 처음 100바이트(요청의 "범위" 헤더에 의해 지정됨)가 포함됩니다. 응답에는 다음 헤더도 포함됩니다.

  • 컨텐츠 길이:100(반환된 바이트 수)
  • 컨텐츠 유형:응용 프로그램/쪽모이 세공됨(쪽모이 세공된 파일이 요청되었으므로 응답 컨텐츠 유형은 쪽모이 세공된 경우)
  • 컨텐츠 범위:바이트 0-99/249058(요청된 범위(0-99)가 총 바이트 수(249058) 중)

API 응답 페이지 매김 구성

API 내의 응답에 Data Access 페이지가 매겨집니다. 기본적으로 페이지당 최대 항목 수는 100개입니다. 페이징 매개 변수를 사용하여 기본 동작을 수정할 수 있습니다.

  • limit:"limit" 매개 변수를 사용하여 요구 사항에 따라 페이지당 항목 수를 지정할 수 있습니다.
  • start:오프셋을 "시작" 쿼리 매개 변수로 설정할 수 있습니다.
  • &:앰퍼샌드를 사용하여 단일 호출에서 여러 매개 변수를 결합할 수 있습니다.

API 형식

GET /batches/{BATCH_ID}/files?start={OFFSET}
GET /batches/{BATCH_ID}/files?limit={LIMIT}
GET /batches/{BATCH_ID}/files?start={OFFSET}&limit={LIMIT}
속성 설명
{BATCH_ID} 액세스하려는 일괄 처리의 일괄 처리 식별자입니다.
{OFFSET} 결과 배열을 시작할 지정된 인덱스(예: start=0)
{LIMIT} 결과 배열에서 반환되는 결과 수를 제어합니다(예: limit=1).

요청

curl -X GET 'https://platform.adobe.io/data/foundation/export/batches/5c102cac7c7ebc14cd6b098e/files?start=0&limit=1' \
  -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}'

응답:

응답에는 요청 매개 변수로 지정된 단일 요소가 있는 "data" 배열이 포함됩니다 limit=1. 이 요소는 요청의 매개 변수에 의해 지정된 첫 번째 사용 가능한 파일의 세부 사항을 포함하는 개체입니다(0부터 번호를 매기는 경우 첫 번째 요소는 "0"임). start=0

_links.next.href 값에는 다음 응답 페이지에 대한 링크가 포함되어 있습니다. 이 링크를 통해 start 매개 변수가 고급 응답 페이지로 이동하는 것을 확인할 수 start=1있습니다.

{
    "data": [
        {
            "dataSetFileId": "{FILE_ID_1}",
            "dataSetViewId": "5a9f264c2aa0cf01da4d82fa",
            "version": "1.0.0",
            "created": "1521053793635",
            "updated": "1521053793635",
            "isValid": false,
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io/data/foundation/export/files/{FILE_ID_1}"
                }
            }
        }
    ],
    "_page": {
        "limit": 1,
        "count": 6
    },
    "_links": {
        "next": {
            "href": "https://platform.adobe.io/data/foundation/export/batches/5c102cac7c7ebc14cd6b098e/files?start=1&limit=1"
        },
        "page": {
            "href": "https://platform.adobe.io/data/foundation/export/batches/5c102cac7c7ebc14cd6b098e/files?start=0&limit=1",
            "templated": true
        }
    }
}

이 페이지에서는