스키마 엔드포인트
스키마는 Adobe Experience Platform에 수집하려는 데이터에 대한 블루프린트로 간주할 수 있습니다. 각 스키마는 클래스와 0개 이상의 스키마 필드 그룹으로 구성됩니다. Schema Registry API의 /schemas
끝점을 사용하면 경험 응용 프로그램 내에서 스키마를 프로그래밍 방식으로 관리할 수 있습니다.
시작하기
이 가이드에 사용된 API 끝점은 Schema Registry API의 일부입니다. 계속하기 전에 시작 안내서를 검토하여 관련 문서에 대한 링크, 이 문서의 샘플 API 호출 읽기 지침 및 Experience Platform API를 성공적으로 호출하는 데 필요한 필수 헤더에 대한 중요 정보를 확인하십시오.
스키마 목록 검색 list
/global/schemas
또는 /tenant/schemas
에 각각 GET 요청을 하여 global
또는 tenant
컨테이너 아래에 모든 스키마를 나열할 수 있습니다.
API 형식
GET /{CONTAINER_ID}/schemas?{QUERY_PARAMS}
{CONTAINER_ID}
global
, 조직에서 소유한 스키마의 경우 tenant
입니다.{QUERY_PARAMS}
요청
다음 요청은 orderby
쿼리 매개 변수를 사용하여 title
특성별로 결과를 정렬하여 tenant
컨테이너에서 스키마 목록을 검색합니다.
curl -X GET \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas?orderby=title \
-H 'Accept: application/vnd.adobe.xed-id+json' \
-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}'
응답 형식은 요청에서 보낸 Accept
헤더에 따라 다릅니다. 스키마를 나열하는 데 다음 Accept
헤더를 사용할 수 있습니다.
Accept
헤더application/vnd.adobe.xed-id+json
application/vnd.adobe.xed+json
$ref
및 allOf
이(가) 포함된 각 리소스에 대해 전체 JSON 스키마를 반환합니다. (제한: 300)응답
위의 요청에서 application/vnd.adobe.xed-id+json
Accept
헤더를 사용했으므로 응답에는 각 스키마에 대한 title
, $id
, meta:altId
및 version
특성만 포함됩니다. 다른 Accept
헤더(application/vnd.adobe.xed+json
)를 사용하면 각 스키마의 모든 특성이 반환됩니다. 응답에 필요한 정보에 따라 적절한 Accept
헤더를 선택합니다.
{
"results": [
{
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/0238be93d3e7a06aec5e0655955901ec",
"meta:altId": "_{TENANT_ID}.schemas.0238be93d3e7a06aec5e0655955901ec",
"version": "1.4",
"title": "Hotels"
},
{
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/0ef4ce0d390f0809fad490802f53d30b",
"meta:altId": "_{TENANT_ID}.schemas.0ef4ce0d390f0809fad490802f53d30b",
"version": "1.0",
"title": "Loyalty Members"
}
],
"_page": {
"orderby": "title",
"next": null,
"count": 2
},
"_links": {
"next": null,
"global_schemas": {
"href": "https://platform.adobe.io/data/foundation/schemaregistry/global/schemas"
}
}
}
스키마 조회 lookup
경로에 스키마 ID를 포함하는 GET 요청을 수행하여 특정 스키마를 조회할 수 있습니다.
API 형식
GET /{CONTAINER_ID}/schemas/{SCHEMA_ID}
{CONTAINER_ID}
global
, 조직에서 소유한 스키마의 경우 tenant
.{SCHEMA_ID}
meta:altId
또는 URL로 인코딩된 $id
입니다.요청
다음 요청은 경로의 meta:altId
값으로 지정된 스키마를 검색합니다.
curl -X GET \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.f579a0b5f992c69458ea408ec36571f7da9de15901bab116 \
-H 'Accept: application/vnd.adobe.xed+json' \
-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}'
응답 형식은 요청에서 보낸 Accept
헤더에 따라 다릅니다. 모든 조회 요청에는 Accept
헤더에 version
이(가) 포함되어야 합니다. 다음 Accept
헤더를 사용할 수 있습니다.
Accept
헤더application/vnd.adobe.xed+json; version=1
$ref
및 allOf
이(가) 있는 Raw에 제목 및 설명이 있습니다.application/vnd.adobe.xed-full+json; version=1
$ref
및 allOf
이(가) 확인되었으며 제목 및 설명이 있습니다.application/vnd.adobe.xed-notext+json; version=1
$ref
및 allOf
이(가) 포함된 원시 버전이며 제목 또는 설명이 없습니다.application/vnd.adobe.xed-full-notext+json; version=1
$ref
및 allOf
이(가) 해결되었습니다. 제목 또는 설명이 없습니다.application/vnd.adobe.xed-full-desc+json; version=1
$ref
및 allOf
해결됨, 설명자가 포함됨.application/vnd.adobe.xed-deprecatefield+json; version=1
$ref
및 allOf
이(가) 확인되었으며 제목 및 설명이 있습니다. 사용되지 않는 필드는 deprecated
의 meta:status
특성으로 표시됩니다.응답
성공적인 응답은 스키마의 세부 정보를 반환합니다. 반환되는 필드는 요청에서 보낸 Accept
헤더에 따라 다릅니다. 다른 Accept
헤더를 실험하여 응답을 비교하고 사용 사례에 가장 적합한 헤더를 확인합니다.
{
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/20af3f1d4b175f27ba59529d1b51a0c79fc25df454117c80",
"meta:altId": "_{TENANT_ID}.schemas.20af3f1d4b175f27ba59529d1b51a0c79fc25df454117c80",
"meta:resourceType": "schemas",
"version": "1.1",
"title": "Example schema",
"type": "object",
"description": "An example schema created within the tenant container.",
"allOf": [
{
"$ref": "https://ns.adobe.com/xdm/context/profile",
"type": "object",
"meta:xdmType": "object"
},
{
"$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/443fe51457047d958f4a97853e64e0eca93ef34d7990583b",
"type": "object",
"meta:xdmType": "object"
}
],
"imsOrg": "{ORG_ID}",
"meta:extensible": false,
"meta:abstract": false,
"meta:extends": [
"https://ns.adobe.com/{TENANT_ID}/mixins/443fe51457047d958f4a97853e64e0eca93ef34d7990583b",
"https://ns.adobe.com/xdm/common/auditable",
"https://ns.adobe.com/xdm/data/record",
"https://ns.adobe.com/xdm/context/profile"
],
"meta:xdmType": "object",
"meta:registryMetadata": {
"repo:createdDate": 1602872911226,
"repo:lastModifiedDate": 1603381419889,
"xdm:createdClientId": "{CLIENT_ID}",
"xdm:lastModifiedClientId": "{CLIENT_ID}",
"xdm:createdUserId": "{USER_ID}",
"xdm:lastModifiedUserId": "{USER_ID}",
"eTag": "84b4da79b7445a4bf1c59269e718065effddb983c492f48e223d49c049c6d589",
"meta:globalLibVersion": "1.15.4"
},
"meta:class": "https://ns.adobe.com/xdm/context/profile",
"meta:containerId": "tenant",
"meta:sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
"meta:sandboxType": "production",
"meta:tenantNamespace": "_{TENANT_ID}"
}
스키마 만들기 create
스키마 작성 프로세스는 클래스를 할당함으로써 시작됩니다. 클래스는 데이터(레코드 또는 시계열)의 주요 행동 측면과 수집할 데이터를 설명하는 데 필요한 최소 필드를 정의합니다.
API 형식
POST /tenant/schemas
요청
요청의 $id
을(를) 참조하는 allOf
특성이 포함되어 있어야 합니다. 이 속성은 스키마가 구현할 "기본 클래스"를 정의합니다. 이 예제에서 기본 클래스는 이전에 만든 "Property Information" 클래스입니다.
curl -X POST \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas \
-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 '{
"title":"Property Information",
"description": "Property-related information.",
"type": "object",
"allOf": [
{
"$ref": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590"
}
]
}'
allOf
$id
을(를) 나타내는 값을 가진 단일 속성($ref
)이 있습니다. 추가 필드 그룹이 0개 이상인 하나의 클래스를 제공해야 합니다. 위의 예에서 allOf
배열의 단일 개체는 스키마의 클래스입니다.응답
성공한 응답은 HTTP 상태 201(생성됨)과 $id
, meta:altId
및 version
을(를) 포함하여 새로 생성된 스키마의 세부 정보가 포함된 페이로드를 반환합니다. 이 값은 읽기 전용이며 Schema Registry에 의해 할당됩니다.
{
"title": "Property Information",
"description": "Property-related information.",
"type": "object",
"allOf": [
{
"$ref": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590"
}
],
"meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
"meta:abstract": false,
"meta:extensible": false,
"meta:extends": [
"https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
"https://ns.adobe.com/xdm/data/record"
],
"meta:containerId": "tenant",
"imsOrg": "{ORG_ID}",
"meta:altId": "_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67",
"meta:xdmType": "object",
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d5cc04eb8d50190001287e4c869ebe67",
"version": "1.0",
"meta:resourceType": "schemas",
"meta:registryMetadata": {
"repo:createDate": 1552088461236,
"repo:lastModifiedDate": 1552088461236,
"xdm:createdClientId": "{CREATED_CLIENT}",
"xdm:repositoryCreatedBy": "{CREATED_BY}"
}
}
이제 테넌트 컨테이너에 모든 스키마를 나열하는 GET 요청을 수행하면 새 스키마가 포함됩니다. URL로 인코딩된 $id
URI를 사용하여 조회(GET) 요청을 수행하여 새 스키마를 직접 볼 수 있습니다.
스키마에 필드를 추가하려면 PATCH 작업을 수행하여 스키마의 allOf
및 meta:extends
배열에 필드 그룹을 추가할 수 있습니다.
스키마 업데이트 put
PUT 작업을 통해 전체 스키마를 바꿀 수 있으며, 기본적으로 리소스를 다시 작성할 수 있습니다. PUT 요청을 통해 스키마를 업데이트할 때 본문에는 POST 요청에 새 스키마를 만들 때에 필요한 모든 필드가 포함되어야 합니다.
API 형식
PUT /tenant/schemas/{SCHEMA_ID}
{SCHEMA_ID}
meta:altId
또는 URL로 인코딩된 $id
입니다.요청
다음 요청은 기존 스키마를 대체하여 title
, description
및 allOf
특성을 변경합니다.
curl -X PUT \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67 \
-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 '{
"title":"Commercial Property Information",
"description": "Information related to commercial properties.",
"type": "object",
"allOf": [
{
"$ref": "https://ns.adobe.com/{TENANT_ID}/classes/01b7b1745e8ac4ed1e8784ec91b6afa7"
}
]
}'
응답
성공한 응답은 업데이트된 스키마의 세부 정보를 반환합니다.
{
"title":"Commercial Property Information",
"description": "Information related to commercial properties.",
"type": "object",
"allOf": [
{
"$ref": "https://ns.adobe.com/{TENANT_ID}/classes/01b7b1745e8ac4ed1e8784ec91b6afa7"
}
],
"meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/01b7b1745e8ac4ed1e8784ec91b6afa7",
"meta:abstract": false,
"meta:extensible": false,
"meta:extends": [
"https://ns.adobe.com/{TENANT_ID}/classes/01b7b1745e8ac4ed1e8784ec91b6afa7",
"https://ns.adobe.com/xdm/data/record"
],
"meta:containerId": "tenant",
"imsOrg": "{ORG_ID}",
"meta:altId": "_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67",
"meta:xdmType": "object",
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d5cc04eb8d50190001287e4c869ebe67",
"version": "1.0",
"meta:resourceType": "schemas",
"meta:registryMetadata": {
"repo:createDate": 1552088461236,
"repo:lastModifiedDate": 1552088470592,
"xdm:createdClientId": "{CREATED_CLIENT}",
"xdm:repositoryCreatedBy": "{CREATED_BY}"
}
}
스키마의 일부 업데이트 patch
PATCH 요청을 사용하여 스키마의 일부를 업데이트할 수 있습니다. Schema Registry은(는) add
, remove
및 replace
을(를) 포함한 모든 표준 JSON 패치 작업을 지원합니다. JSON 패치에 대한 자세한 내용은 API 기본 사항 안내서를 참조하십시오.
가장 일반적인 PATCH 작업 중 하나는 아래 예제에서 알 수 있듯이 이전에 정의한 필드 그룹을 스키마에 추가하는 것입니다.
API 형식
PATCH /tenant/schemas/{SCHEMA_ID}
{SCHEMA_ID}
$id
URI 또는 meta:altId
입니다.요청
아래 예제 요청에서는 해당 필드 그룹의 $id
값을 meta:extends
및 allOf
배열 모두에 추가하여 스키마에 새 필드 그룹을 추가합니다.
요청 본문은 배열 형식을 취하며, 나열된 각 객체는 개별 필드에 대한 특정 변경 사항을 나타냅니다. 각 개체에는 수행할 작업(op
), 작업을 수행할 필드(path
) 및 해당 작업에 포함할 정보(value
)가 포함됩니다.
curl -X PATCH\
https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67 \
-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 '[
{
"op": "add",
"path": "/meta:extends/-",
"value": "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
},
{
"op": "add",
"path": "/allOf/-",
"value": {
"$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
}
}
]'
응답
응답은 두 작업이 모두 성공적으로 수행되었음을 보여 줍니다. 필드 그룹 $id
이(가) meta:extends
배열에 추가되었으며 필드 그룹 $id
에 대한 참조($ref
)가 이제 allOf
배열에 나타납니다.
{
"title": "Property Information",
"description": "Property-related information.",
"type": "object",
"allOf": [
{
"$ref": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590"
},
{
"$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
}
],
"meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
"meta:abstract": false,
"meta:extensible": false,
"meta:extends": [
"https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
"https://ns.adobe.com/xdm/data/record",
"https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
],
"meta:containerId": "tenant",
"imsOrg": "{ORG_ID}",
"meta:altId": "_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67",
"meta:xdmType": "object",
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d5cc04eb8d50190001287e4c869ebe67",
"version": "1.1",
"meta:resourceType": "schemas",
"meta:registryMetadata": {
"repo:createDate": 1552088461236,
"repo:lastModifiedDate": 1552088649634,
"xdm:createdClientId": "{CREATED_CLIENT}",
"xdm:repositoryCreatedBy": "{CREATED_BY}"
}
}
실시간 고객 프로필에서 사용할 스키마 활성화 union
스키마가 실시간 고객 프로필에 참여하려면 스키마의 meta:immutableTags
배열에 union
태그를 추가해야 합니다. 해당 스키마에 대한 PATCH 요청을 수행하면 이를 수행할 수 있습니다.
API 형식
PATCH /tenant/schemas/{SCHEMA_ID}
{SCHEMA_ID}
$id
URI 또는 활성화할 스키마의 meta:altId
입니다.요청
아래 예제 요청에서는 기존 스키마에 meta:immutableTags
배열을 추가하여 배열에 union
의 단일 문자열 값을 제공하여 프로필에서 사용할 수 있도록 합니다.
curl -X PATCH\
https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67 \
-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 '[
{
"op": "add",
"path": "/meta:immutableTags",
"value": ["union"]
}
]'
응답
성공한 응답은 업데이트된 스키마의 세부 정보를 반환하여 meta:immutableTags
배열이 추가되었음을 나타냅니다.
{
"title": "Property Information",
"description": "Property-related information.",
"type": "object",
"allOf": [
{
"$ref": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590"
},
{
"$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
}
],
"meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
"meta:abstract": false,
"meta:extensible": false,
"meta:extends": [
"https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
"https://ns.adobe.com/xdm/data/record",
"https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
],
"meta:containerId": "tenant",
"imsOrg": "{ORG_ID}",
"meta:altId": "_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67",
"meta:xdmType": "object",
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d5cc04eb8d50190001287e4c869ebe67",
"version": "1.1",
"meta:resourceType": "schemas",
"meta:registryMetadata": {
"repo:createDate": 1552088461236,
"repo:lastModifiedDate": 1552088649634,
"xdm:createdClientId": "{CREATED_CLIENT}",
"xdm:repositoryCreatedBy": "{CREATED_BY}"
},
"meta:immutableTags": [
"union"
]
}
이제 이 스키마의 클래스에 대한 유니온을 보고 스키마의 필드가 표시되는지 확인할 수 있습니다. 자세한 내용은 유니온 끝점 안내서를 참조하십시오.
스키마 삭제 delete
스키마 레지스트리에서 스키마를 제거해야 하는 경우가 있습니다. 이 작업은 경로에 제공된 스키마 ID로 DELETE 요청을 수행함으로써 수행됩니다.
API 형식
DELETE /tenant/schemas/{SCHEMA_ID}
{SCHEMA_ID}
$id
URI 또는 meta:altId
입니다.요청
curl -X DELETE \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67 \
-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(콘텐츠 없음) 및 빈 본문을 반환합니다.
스키마에 조회(GET) 요청을 시도하여 삭제를 확인할 수 있습니다. Accept
헤더를 요청에 포함해야 하지만 스키마가 스키마 레지스트리에서 제거되었기 때문에 HTTP 상태 404(찾을 수 없음)를 수신해야 합니다.