Schema Registry API 시작

Schema Registry API를 사용하면 다양한 XDM(Experience Data Model) 리소스를 만들고 관리할 수 있습니다. 이 문서에서는 Schema Registry API를 호출하기 전에 알아야 하는 핵심 개념에 대해 소개합니다.

전제 조건

개발자 안내서를 사용하려면 Adobe Experience Platform의 다음 구성 요소에 대한 작업 이해가 필요합니다.

XDM은 JSON 스키마 형식을 사용하여 수집된 고객 경험 데이터의 구조를 설명하고 유효성을 검사합니다. 따라서 이 기본 기술을 더 잘 이해하려면 공식 JSON 스키마 설명서를 검토하는 것이 좋습니다.

샘플 API 호출 읽기

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

필수 헤더에 대한 값 수집

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

Schema Registry에 속하는 리소스를 포함한 Experience Platform의 모든 리소스는 특정 가상 샌드박스로 격리됩니다. Platform API에 대한 모든 요청에는 작업이 수행될 샌드박스의 이름을 지정하는 헤더가 필요합니다.

Schema Registry에 대한 모든 조회(GET) 요청에는 API에서 반환되는 정보의 형식을 결정하는 추가 Accept 헤더가 필요합니다. 자세한 내용은 아래의 Accept 헤더 섹션을 참조하십시오.

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

테넌트 ID 확인 know-your-tenant_id

API 안내서 전체에서 TENANT_ID에 대한 참조를 볼 수 있습니다. 이 ID는 사용자가 만드는 리소스의 이름 간격이 제대로 지정되고 조직 내에 포함되어 있는지 확인하는 데 사용됩니다. ID를 모를 경우 다음 GET 요청을 수행하여 액세스할 수 있습니다.

API 형식

GET /stats

요청

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

응답

응답이 성공하면 조직에서 Schema Registry을(를) 사용하는 것과 관련된 정보가 반환됩니다. 여기에는 tenantId 특성이 포함되며, 이 값은 TENANT_ID입니다.

{
  "imsOrg":"{ORG_ID}",
  "tenantId":"{TENANT_ID}",
  "counts": {
    "schemas": 4,
    "mixins": 3,
    "datatypes": 1,
    "classes": 2,
    "unions": 0,
  },
  "recentlyCreatedResources": [
    {
      "title": "Sample Field Group",
      "description": "New Sample Field Group.",
      "meta:resourceType": "mixins",
      "meta:created": "Sat Feb 02 2019 00:24:30 GMT+0000 (UTC)",
      "version": "1.1"
    },
    {
      "$id": "https://ns.adobe.com/{TENANT_ID}/classes/5bdb5582be0c0f3ebfc1c603b705764f",
      "title": "Tenant Class",
      "description": "Tenant Defined Class",
      "meta:resourceType": "classes",
      "meta:created": "Fri Feb 01 2019 22:46:21 GMT+0000 (UTC)",
      "version": "1.0"
    }
  ],
  "recentlyUpdatedResources": [
    {
      "title": "Sample Field Group",
      "description": "New Sample Field Group.",
      "meta:resourceType": "mixins",
      "meta:updated": "Sat Feb 02 2019 00:34:06 GMT+0000 (UTC)",
      "version": "1.1"
    },
    {
      "title": "Data Schema",
      "description": "Schema for Data Information",
      "meta:resourceType": "schemas",
      "meta:updated": "Fri Feb 01 2019 23:47:43 GMT+0000 (UTC)",
      "meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/47b2189fc135e03c844b4f25139d10ab",
      "meta:classTitle": "Sample Class",
      "version": "1.1"
    }
 ],
 "classUsage": {
    "https://ns.adobe.com/{TENANT_ID}/classes/47b2189fc135e03c844b4f25139d10ab": [
      {
        "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
        "title": "Tenant Data Schema",
        "description": "Schema for tenant-specific data."
      }
    ],
    "https://ns.adobe.com/xdm/context/profile": [
      {
        "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/3ac6499f0a43618bba6b138226ae3542",
        "title": "Simple Profile",
        "description": "A simple profile schema."
      },
      {
        "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "title": "Program Schema",
        "description": "Schema for program-related data."
      },
      {
        "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/4025a705890c6d4a4a06b16f8cf6f4ca",
        "title": "Sample Schema",
        "description": "A sample schema."
      }
    ]
  }
 }

CONTAINER_ID 이해 container

Schema Registry API를 호출하려면 CONTAINER_ID을(를) 사용해야 합니다. API 호출을 수행할 수 있는 컨테이너는 두 개입니다. global 컨테이너와 tenant 컨테이너입니다.

전역 컨테이너

global 컨테이너에는 모든 표준 Adobe과 Experience Platform 파트너가 제공한 클래스, 스키마 필드 그룹, 데이터 형식 및 스키마가 들어 있습니다. global 컨테이너에 대해서만 목록 및 조회(GET) 요청을 수행할 수 있습니다.

global 컨테이너를 사용하는 호출의 예는 다음과 같습니다.

GET /global/classes

임차인 컨테이너

고유한 TENANT_ID과(와) 혼동하지 않도록 tenant 컨테이너에는 조직에서 정의한 모든 클래스, 필드 그룹, 데이터 형식, 스키마 및 설명자가 있습니다. 이는 각 조직에 고유하며, 다른 조직에서 표시하거나 관리할 수 없음을 의미합니다. tenant 컨테이너에서 만든 리소스에 대해 모든 CRUD 작업(GET, POST, PUT, PATCH, DELETE)을 수행할 수 있습니다.

tenant 컨테이너를 사용하는 호출의 예는 다음과 같습니다.

POST /tenant/fieldgroups

tenant 컨테이너에서 클래스, 필드 그룹, 스키마 또는 데이터 형식을 만들면 Schema Registry에 저장되고 TENANT_ID을(를) 포함하는 $id URI가 할당됩니다. 이 $id은(는) API 전체에서 특정 리소스를 참조하는 데 사용됩니다. $id 값의 예는 다음 섹션에 제공됩니다.

리소스 식별 resource-identification

XDM 리소스는 다음 예제와 같이 URI 형식으로 $id 특성으로 식별됩니다.

URI를 보다 REST 친화적으로 만들기 위해 스키마에는 meta:altId 속성에서 URI의 점 표기법 인코딩도 있습니다.

Schema Registry API 호출은 URL로 인코딩된 $id URI 또는 meta:altId(점 표기법 형식)을 지원합니다. 가장 좋은 방법은 다음과 같이 API에 대한 REST 호출을 수행할 때 URL로 인코딩된 $id URI를 사용하는 것입니다.

Accept 헤더 accept

Schema Registry API에서 목록 및 조회(GET) 작업을 수행할 때 API에서 반환되는 데이터의 형식을 결정하려면 Accept 헤더가 필요합니다. 특정 리소스를 조회할 때 버전 번호도 Accept 헤더에 포함되어야 합니다.

다음 표에는 버전 번호가 포함된 호환 가능한 Accept 헤더 값과 API가 사용될 때 반환되는 값에 대한 설명이 나와 있습니다.

스키마 버전 관리 versioning

스키마 버전은 스키마 레지스트리 API의 Accept 헤더와 다운스트림 플랫폼 서비스 API 페이로드의 schemaRef.contentType 속성에서 참조됩니다.

현재 Platform에서는 각 스키마에 대해 하나의 주 버전(1)만 지원합니다. 스키마 진화의 규칙에 따라 스키마에 대한 각 업데이트는 비파괴적이어야 합니다. 즉, 스키마의 새 부 버전(1.2, 1.3 등)이 는 항상 이전 부 버전과 역으로 호환됩니다. 따라서 version=1을(를) 지정하면 스키마 레지스트리는 항상 스키마의 최신 주 버전 1을(를) 반환합니다. 즉, 이전의 부 버전은 반환되지 않습니다.

XDM 필드 제한 및 우수 사례

스키마의 필드가 properties 개체 내에 나열됩니다. 각 필드는 그 자체로 하나의 객체로, 필드에 포함될 수 있는 데이터를 설명하고 제한하는 속성을 포함합니다. 코드 샘플 및 가장 일반적으로 사용되는 데이터 형식에 대한 선택적 제약 조건의 경우 API에서 사용자 지정 필드 정의에 대한 안내서를 참조하세요.

다음 샘플 필드는 아래에 제공된 이름 지정 제한 및 우수 사례에 대한 자세한 내용과 함께 올바른 형식의 XDM 필드를 보여줍니다. 이러한 사례는 유사한 속성을 포함하는 다른 리소스를 정의할 때도 적용할 수 있습니다.

"fieldName": {
    "title": "Field Name",
    "type": "string",
    "format": "date-time",
    "examples": [
        "2004-10-23T12:00:00-06:00"
    ],
    "description": "Full sentence describing the field, using proper grammar and punctuation.",
}

다음 단계

Schema Registry API를 사용하여 호출을 시작하려면 사용 가능한 끝점 가이드 중 하나를 선택하십시오.