API를 사용하여 데이터 세트의 데이터 사용 레이블 관리

Dataset Service API을(를) 사용하면 데이터 세트에 대한 사용 레이블을 적용하고 편집할 수 있습니다. Adobe Experience Platform의 데이터 카탈로그 기능의 일부이지만 데이터 세트 메타데이터를 관리하는 Catalog Service API와 별개입니다.

이 문서에서는 Dataset Service API을(를) 사용하여 데이터 세트 및 필드의 레이블을 관리하는 방법을 다룹니다. API 호출을 사용하여 데이터 사용 레이블 자체를 관리하는 방법에 대한 단계는 Policy Service API의 레이블 끝점 안내서를 참조하십시오.

시작하기

이 안내서를 읽기 전에 카탈로그 개발자 안내서의 시작 섹션에 설명된 단계에 따라 Platform API를 호출하는 데 필요한 자격 증명을 수집합니다.

이 문서에 설명된 끝점을 호출하려면 특정 데이터 세트에 대해 고유한 id 값이 있어야 합니다. 이 값이 없으면 카탈로그 개체 나열에 대한 안내서를 참조하여 기존 데이터 세트의 ID를 찾으십시오.

데이터 세트에 대한 레이블 조회 look-up

Dataset Service API에 대한 GET 요청을 통해 기존 데이터 세트에 적용된 데이터 사용 레이블을 조회할 수 있습니다.

API 형식

GET /datasets/{DATASET_ID}/labels

요청

curl -X GET \
  'https://platform.adobe.io/data/foundation/dataset/datasets/5abd49645591445e1ba04f87/labels' \
  -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}'

응답

성공적인 응답은 데이터 세트에 적용된 데이터 사용 레이블을 반환합니다.

{
  "AEP:dataset:5abd49645591445e1ba04f87": {
    "imsOrg": "{ORG_ID}",
    "labels": [ "C1", "C2", "C3", "I1", "I2" ],
    "optionalLabels": [
      {
        "option": {
          "id": "https://ns.adobe.com/{TENANT_ID}/schemas/c6b1b09bc3f2ad2627c1ecc719826836",
          "contentType": "application/vnd.adobe.xed-full+json;version=1",
          "schemaPath": "/properties/repositoryCreatedBy"
        },
        "labels": [ "S1", "S2" ]
      }
    ]
  }
}

데이터 세트에 레이블 적용 apply

전체 데이터 세트에 대한 레이블 집합을 POST 또는 PUT 요청의 페이로드에서 Dataset Service API에 제공하여 적용할 수 있습니다. 요청 본문은 두 호출에 대해 동일합니다. 개별 데이터 세트 필드에 레이블을 추가할 수 없습니다.

API 형식

POST /datasets/{DATASET_ID}/labels
PUT /datasets/{DATASET_ID}/labels

요청

아래의 예제 POST 요청은 C1 레이블로 전체 데이터 세트를 업데이트합니다. 페이로드에 제공된 필드는 PUT 요청에 필요한 것과 동일합니다.

데이터 집합(PUT)의 기존 레이블을 업데이트하는 API를 호출할 때 데이터 집합 서비스에 있는 데이터 집합 레이블 엔터티의 현재 버전을 나타내는 If-Match 헤더를 포함해야 합니다. 데이터 충돌을 방지하기 위해 포함된 If-Match 문자열이 해당 데이터 세트에 대해 시스템에서 생성된 최신 버전 태그와 일치하는 경우에만 서비스가 데이터 세트 엔터티를 업데이트합니다.

데이터 집합 레이블 엔터티의 최신 버전을 검색하려면 /datasets/{DATASET_ID}/labels 끝점에 대해 GET 요청을 만듭니다. 현재 값은 etag 헤더 아래의 응답에서 반환됩니다. 기존 데이터 세트 레이블을 업데이트할 때 가장 좋은 방법은 후속 PUT 요청의 If-Match 헤더에서 해당 값을 사용하기 전에 최신 etag 값을 가져오기 위해 먼저 데이터 세트에 대한 조회 요청을 수행하는 것입니다.

curl -X POST \
  'https://platform.adobe.io/data/foundation/dataset/datasets/5abd49645591445e1ba04f87/labels' \
  -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 '{
        "entityId": {
          "namespace": "AEP",
          "id": "test-ds-id",
          "type": "dataset"
        },
        "labels": [
          "C1"
        ],
        "parents": []
      } '

응답

성공적인 응답은 데이터 세트에 대해 업데이트된 레이블 세트를 반환합니다.

{
  "parents": [
      {
        "id": "_ddgduleint.schemas.4a95cdba7d560e3bca7d8c5c7b58f00ca543e2bb1e4137d6",
        "type": "schema",
        "namespace": "AEP"
      }
  ],
  "optionalLabels": [],
  "labels": [
      "C1"
  ],
  "code": "PES-201",
  "message": "POST Successful"
}

데이터 세트에서 레이블 제거 remove

기존 필드 레이블의 하위 집합으로 기존 optionalLabels 값을 업데이트하거나, 빈 목록을 업데이트하여 완전히 제거하여 이전에 적용된 모든 필드 레이블을 제거할 수 있습니다. Dataset Service API에 PUT 요청을 하여 이전에 적용된 레이블을 업데이트하거나 제거합니다.

API 형식

PUT /datasets/{DATASET_ID}/labels

요청

PUT 작업이 적용되는 아래 데이터 세트에는 속성/개인/속성/주소 필드의 C1 optionalLabel과 /properties/person/properties/name/properties/fullName 필드의 C1, C2 optionalLabels가 있습니다. put 작업 후, 첫 번째 필드에는 레이블이 없고(C1 레이블이 제거됨) 두 번째 필드에는 C1 레이블만 있습니다(C2 레이블이 제거됨)

아래 예제 시나리오에서는 개별 필드에 추가된 레이블을 제거하는 데 PUT 요청을 사용합니다. 요청이 이루어지기 전에 fullName 필드에 C1 및 C2 레이블이 적용되었으며 address 필드에 이미 C1 레이블이 적용되었습니다. PUT 요청은 optionalLabels.labels 매개 변수를 사용하여 C1 레이블이 있는 fullName 필드의 기존 레이블 C1, C2 레이블을 재정의합니다. 또한 이 요청은 필드 레이블 집합이 비어 있는 address 필드의 C1 레이블을 재정의합니다.

curl -X PUT \
  'https://platform.adobe.io/data/foundation/dataset/datasets/5abd49645591445e1ba04f87/labels' \
  -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' \
  -H 'If-Match: 8f00d38e-0000-0200-0000-5ef4fc6d0000' \
  -d '{
        "entityId": {
          "namespace": "AEP",
          "id": "646b814d52e1691c07b41032",
          "type": "dataset"
        },
        "labels": [
          "C1"
        ],
        "parents": [
          {
            "id": "_xdm.context.identity-graph-flattened-export",
            "type": "schema",
            "namespace": "AEP"
          }
        ],
        "optionalLabels": [
          {
            "option": {
              "id": "https://ns.adobe.com/xdm/context/identity-graph-flattened-export",
              "contentType": "application/vnd.adobe.xed-full+json;version=1",
              "schemaPath": "/properties/person/properties/name/properties/fullName"
            },
            "labels": [
              "C1"
            ]
          },
          {
            "option": {
              "id": "https://ns.adobe.com/xdm/context/identity-graph-flattened-export",
              "contentType": "application/vnd.adobe.xed-full+json;version=1",
              "schemaPath": "/properties/person/properties/address"
            },
            "labels": []
          }
        ]
      }'

응답

성공적인 응답은 데이터 세트에 대해 업데이트된 레이블 세트를 반환합니다.

{
  "parents": [
      {
        "id": "_xdm.context.identity-graph-flattened-export",
        "type": "schema",
        "namespace": "AEP"
      }
  ],
  "optionalLabels": [],
  "labels": [
      "C1"
  ],
  "code": "PES-200",
  "message": "PUT Successful"
}

다음 단계

이 문서를 읽고 Dataset Service API를 사용하여 데이터 세트 및 필드의 데이터 사용 레이블을 관리하는 방법을 배웠습니다. 이제 적용한 레이블을 기반으로 데이터 사용 정책 및 액세스 제어 정책을(를) 정의할 수 있습니다.

Experience Platform의 데이터 세트 관리에 대한 자세한 내용은 데이터 세트 개요를 참조하십시오.