설명자 엔드포인트

스키마는 데이터 엔티티의 정적 보기를 정의하지만 이러한 스키마를 기반으로 하는 데이터(예: 데이터 세트)가 서로 관련될 수 있는 방법에 대한 특정 세부 정보는 제공하지 않습니다. Adobe Experience Platform에서는 설명자를 사용하여 스키마에 대한 이러한 관계와 기타 해석적인 메타데이터를 설명할 수 있습니다.

스키마 설명자는 테넌트 수준의 메타데이터입니다. 즉, 조직에 고유하며 모든 설명자 작업이 테넌트 컨테이너에서 수행됩니다.

각 스키마에는 하나 이상의 스키마 설명자 엔티티가 적용될 수 있습니다. 각 스키마 설명자 엔터티에는 설명자 @type 및 이 설명자가 적용되는 sourceSchema이(가) 포함되어 있습니다. 이 설명자가 적용되면 스키마를 사용하여 만든 모든 데이터 세트에 적용됩니다.

Schema Registry API의 /descriptors 끝점을 사용하면 경험 응용 프로그램 내의 설명자를 프로그래밍 방식으로 관리할 수 있습니다.

시작하기

이 가이드에 사용된 끝점은 Schema Registry API의 일부입니다. 계속하기 전에 시작 안내서를 검토하여 관련 문서에 대한 링크, 이 문서의 샘플 API 호출 읽기 지침 및 Experience Platform API를 성공적으로 호출하는 데 필요한 필수 헤더에 대한 중요 정보를 확인하십시오.

설명자 목록 검색 list

/tenant/descriptors에 GET 요청을 하여 조직에서 정의한 모든 설명자를 나열할 수 있습니다.

API 형식

GET /tenant/descriptors

요청

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
  -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 'Accept: application/vnd.adobe.xdm-link+json'

응답 형식은 요청에서 보낸 Accept 헤더에 따라 다릅니다. /descriptors 끝점은 Schema Registry API의 다른 모든 끝점과 다른 Accept 헤더를 사용합니다.

응답

응답에는 설명자가 정의된 각 설명자 유형에 대한 배열이 포함됩니다. 즉, 정의된 특정 @type의 설명자가 없으면 레지스트리는 해당 설명자 유형에 대해 빈 배열을 반환하지 않습니다.

link Accept 헤더를 사용할 때 각 설명자가 /{CONTAINER}/descriptors/{DESCRIPTOR_ID} 형식의 배열 항목으로 표시됩니다.

{
  "xdm:alternateDisplayInfo": [
    "/tenant/descriptors/85dc1bc8b91516ac41163365318e38a9f1e4f351",
    "/tenant/descriptors/49bd5abb5a1310ee80ebc1848eb508d383a462cf",
    "/tenant/descriptors/b3b3e548f1c653326bcf5459ceac4140fc0b9e08"
  ],
  "xdm:descriptorIdentity": [
    "/tenant/descriptors/f7a4bc25429496c4740f8f9a7a49ba96862c5379"
  ],
  "xdm:descriptorOneToOne": [
    "/tenant/descriptors/cb509fd6f8ab6304e346905441a34b58a0cd481a"
  ]
}

설명자 조회 lookup

특정 설명자에 대한 세부 정보를 보려면 해당 @id을(를) 사용하여 개별 설명자를 조회(GET)할 수 있습니다.

API 형식

GET /tenant/descriptors/{DESCRIPTOR_ID}

요청

다음 요청은 @id 값으로 설명자를 검색합니다. 설명자의 버전이 없으므로 조회 요청에는 Accept 헤더가 필요하지 않습니다.

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/f3a1dfa38a4871cf4442a33074c1f9406a593407 \
  -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}'

응답

성공적인 응답은 설명자 유형에 따라 달라지는 추가 정보와 해당 @type 및 sourceSchema을(를) 포함하여 설명자의 세부 정보를 반환합니다. 반환된 @id은(는) 요청에 제공된 설명자 @id과(와) 일치해야 합니다.

{
  "@type": "xdm:descriptorIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/personalEmail/address",
  "xdm:namespace": "Email",
  "xdm:property": "xdm:code",
  "xdm:isPrimary": false,
  "createdUser": "{CREATED_USER}",
  "imsOrg": "{ORG_ID}",
  "createdClient": "{CREATED_CLIENT}",
  "updatedUser": "{UPDATED_USER}",
  "created": 1548899346989,
  "updated": 1548899346989,
  "meta:containerId": "tenant",
  "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

설명자 만들기 create

/tenant/descriptors 끝점에 대한 POST 요청을 수행하여 새 설명자를 만들 수 있습니다.

API 형식

POST /tenant/descriptors

요청

다음 요청은 샘플 스키마의 "이메일 주소" 필드에 ID 설명자를 정의합니다. 이에 따라 Experience Platform이(가) 전자 메일 주소를 식별자로 사용하여 개인에 대한 정보를 결합하도록 합니다.

curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '
      {
        "@type": "xdm:descriptorIdentity",
        "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "xdm:sourceVersion": 1,
        "xdm:sourceProperty": "/personalEmail/address",
        "xdm:namespace": "Email",
        "xdm:property": "xdm:code",
        "xdm:isPrimary": false
      }'

응답

성공적인 응답은 HTTP 상태 201(생성됨) 및 해당 @id을(를) 포함하여 새로 생성된 설명자의 세부 정보를 반환합니다. @id은(는) Schema Registry에 의해 할당되고 API의 설명자를 참조하는 데 사용되는 읽기 전용 필드입니다.

{
  "@type": "xdm:descriptorIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/personalEmail/address",
  "xdm:namespace": "Email",
  "xdm:property": "xdm:code",
  "xdm:isPrimary": false,
  "meta:containerId": "tenant",
  "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

설명자 업데이트 put

PUT 요청의 경로에 해당 @id을(를) 포함하여 설명자를 업데이트할 수 있습니다.

API 형식

PUT /tenant/descriptors/{DESCRIPTOR_ID}

요청

이 요청은 본질적으로 설명자를 재작성하므로 요청 본문에는 해당 유형의 설명자를 정의하는 데 필요한 모든 필드가 포함되어야 합니다. 즉, 설명자를 업데이트(PUT)하기 위한 요청 페이로드는 같은 유형의 설명자를 생성(POST)하기 위한 페이로드와 동일합니다.

다음 예제에서는 다른 xdm:sourceProperty(mobile phone)을(를) 참조하도록 ID 설명자를 업데이트하고 xdm:namespace을(를) Phone(으)로 변경합니다.

curl -X PUT \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/f3a1dfa38a4871cf4442a33074c1f9406a593407 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "@type": "xdm:descriptorIdentity",
        "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "xdm:sourceVersion": 1,
        "xdm:sourceProperty": "/mobilePhone/number",
        "xdm:namespace": "Phone",
        "xdm:property": "xdm:code",
        "xdm:isPrimary": false
      }'

응답

성공적인 응답은 HTTP 상태 201(생성됨) 및 업데이트된 설명자의 @id(요청에서 전송된 @id과(와) 일치해야 함)을 반환합니다.

{
    "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

설명자를 보기 위해 조회(GET) 요청을 수행하면 PUT 요청에 전송된 변경 사항을 반영하도록 필드가 업데이트되었음을 알 수 있습니다.

설명자 삭제 delete

Schema Registry에서 정의한 설명자를 제거해야 하는 경우가 있습니다. 이 작업은 제거할 설명자의 @id을(를) 참조하는 DELETE 요청을 통해 수행됩니다.

API 형식

DELETE /tenant/descriptors/{DESCRIPTOR_ID}

요청

curl -X DELETE \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/ca921946fb5281cbdb8ba5e07087486ce531a1f2  \
  -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}'

응답

성공적인 응답은 HTTP 상태 204(콘텐츠 없음) 및 빈 본문을 반환합니다.

설명자가 삭제되었는지 확인하기 위해 설명자 @id에 대해 조회 요청을 수행할 수 있습니다. 설명자가 Schema Registry에서 제거되었으므로 응답에서 HTTP 상태 404(찾을 수 없음)를 반환합니다.

부록

다음 섹션에서는 Schema Registry API의 설명자 작업에 대한 추가 정보를 제공합니다.

설명자 정의 defining-descriptors

다음 섹션에서는 각 유형의 설명자를 정의하는 데 필요한 필드를 포함하여 사용 가능한 설명자 유형에 대한 개요를 제공합니다.

ID 설명자

ID 설명자는 "sourceSchema"의 "sourceProperty"이(가) Adobe Experience Platform Identity Service에 설명된 Identity 필드임을 알립니다.

{
  "@type": "xdm:descriptorIdentity",
  "xdm:sourceSchema":
    "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/personalEmail/address",
  "xdm:namespace": "Email",
  "xdm:property": "xdm:code",
  "xdm:isPrimary": false
}

설명자에 대한 알기 쉬운 이름 friendly-name

사용자가 알기 쉬운 이름 설명자를 사용하여 코어 라이브러리 스키마 필드의 title, description 및 meta:enum 값을 수정할 수 있습니다. 특히 조직에 관련된 정보를 포함하는 것으로 레이블을 지정하려는 "eVar" 및 기타 "일반" 필드로 작업할 때 유용합니다. UI는 이러한 매개 변수를 사용하여 보다 친숙한 이름을 표시하거나 친숙한 이름이 있는 필드만 표시할 수 있습니다.

{
  "@type": "xdm:alternateDisplayInfo",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/xdm:eventType",
  "xdm:title": {
    "en_us": "Event Type"
  },
  "xdm:description": {
    "en_us": "The type of experience event detected by the system."
  },
  "meta:enum": {
    "click": "Mouse Click",
    "addCart": "Add to Cart",
    "checkout": "Cart Checkout"
  },
  "xdm:excludeMetaEnum": {
    "web.formFilledOut": "Web Form Filled Out",
    "media.ping": "Media ping"
  }
}

관계 설명자

관계 설명자는 sourceProperty 및 destinationProperty에 설명된 속성을 기준으로 서로 다른 두 스키마 간의 관계를 설명합니다. 자세한 내용은 두 스키마 간의 관계 정의에 대한 자습서를 참조하십시오.

{
  "@type": "xdm:descriptorOneToOne",
  "xdm:sourceSchema":
    "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/parentField/subField",
  "xdm:destinationSchema":
    "https://ns.adobe.com/{TENANT_ID}/schemas/78bab6346b9c5102b60591e15e75d254",
  "xdm:destinationVersion": 1,
  "xdm:destinationProperty": "/parentField/subField"
}

참조 ID 설명자

참조 ID 설명자는 스키마 필드의 기본 ID에 대한 참조 컨텍스트를 제공하여 다른 스키마의 필드에서 참조할 수 있도록 합니다. 참조 스키마에는 이미 기본 ID 필드가 정의되어 있어야 해당 설명자를 통해 다른 스키마에서 참조할 수 있습니다.

{
  "@type": "xdm:descriptorReferenceIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/78bab6346b9c5102b60591e15e75d254",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/parentField/subField",
  "xdm:identityNamespace": "Email"
}

사용되지 않는 필드 설명자

해당 필드에 deprecated(으)로 설정된 meta:status 특성을 추가하여 사용자 지정 XDM 리소스 내의 필드를 사용하지 않을 수 있습니다. 그러나 스키마의 표준 XDM 리소스에서 제공하는 필드를 사용하지 않으려면 해당 스키마에 더 이상 사용되지 않는 필드 설명자를 할당하여 동일한 효과를 얻을 수 있습니다. 올바른 Accept 헤더를 사용하면 API에서 조회할 때 스키마에 대해 더 이상 사용되지 않는 표준 필드를 볼 수 있습니다.

{
  "@type": "xdm:descriptorDeprecated",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/c65ddf08cf2d4a2fe94bd06113bf4bc4c855e12a936410d5",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/faxPhone"
}