Schema Registry API可讓您建立和管理各種Experience Data Model(XDM)資源。 本檔案提供您在嘗試呼叫Schema Registry API之前,需要瞭解的核心概念的簡介。
使用開發人員指南需要瞭解Adobe Experience Platform的下列元件:
XDM使用JSON結構描述格式來說明並驗證所擷取客戶體驗資料的結構。 因此,強烈建議您檢閱官方JSON結構描述檔案,以進一步瞭解此基礎技術。
Schema Registry API檔案提供範例API呼叫,以示範如何格式化您的請求。 這些包括路徑、必要標題和正確格式化的請求負載。 也提供API回應中傳回的範例JSON。 如需範例API呼叫檔案中所用慣例的詳細資訊,請參閱Experience Platform疑難排解指南中如何讀取範例API呼叫一節。
若要呼叫Platform API,您必須先完成驗證教學課程。 完成驗證教學課程後,所有Experience Platform API呼叫中每個所需標題的值都會顯示在下面:
Authorization: Bearer {ACCESS_TOKEN}
x-api-key: {API_KEY}
x-gw-ims-org-id: {IMS_ORG}
Experience Platform中的所有資源(包括屬於Schema Registry的資源)都與特定虛擬沙盒隔離。 對Platform API的所有請求都需要一個標題,該標題指定要在中執行操作的沙盒的名稱:
x-sandbox-name: {SANDBOX_NAME}
如需Platform中沙盒的詳細資訊,請參閱沙盒檔案。
所有對Schema Registry的查閱(GET)請求都需要額外的Accept
標題,其值會決定API傳回的資訊格式。 如需詳細資訊,請參閱下方的接受標題一節。
所有包含裝載(POST、PUT、PATCH)的請求都需要額外的標題:
Content-Type: application/json
在API指南中,您會看到TENANT_ID
的參考。 此ID可用來確保您建立的資源已正確命名並包含在IMS組織中。 如果您不知道您的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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
回應
成功的回應會傳回有關您組織使用Schema Registry的資訊。 這包括tenantId
屬性,其值為TENANT_ID
。
{
"imsOrg":"{IMS_ORG}",
"tenantId":"{TENANT_ID}",
"counts": {
"schemas": 4,
"mixins": 3,
"datatypes": 1,
"classes": 2,
"unions": 0,
},
"recentlyCreatedResources": [
{
"title": "Sample Mixin",
"description": "New Sample Mixin.",
"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 Mixin",
"description": "New Sample Mixin.",
"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
對Schema Registry API的呼叫需要使用CONTAINER_ID
。 有兩個容器可對其進行API呼叫:global
容器和tenant
容器。
global
容器包含所有標準Adobe和[!DNL Experience Platform]合作夥伴提供的類別、混合、資料類型和結構。 您只能對global
容器執行清單和查閱(GET)請求。
使用global
容器的呼叫範例如下:
GET /global/classes
不要與您的唯一TENANT_ID
混淆,tenant
容器包含由IMS組織定義的所有類、混合、資料類型、方案和描述符。 這是每個組織所獨有的,也就是說,其他IMS組織無法看到或管理。 您可以對在tenant
容器中建立的資源執行所有CRUD操作(GET、POST、PUT、PATCH、DELETE)。
使用tenant
容器的呼叫範例如下:
POST /tenant/mixins
在tenant
容器中建立類、混音、模式或資料類型時,該類將保存到Schema Registry,並為其分配一個包含TENANT_ID
的$id
URI。 此$id
用於整個API中以參考特定資源。 $id
值的範例將在下一節中提供。
XDM資源以URI形式使用$id
屬性進行標識,例如:
https://ns.adobe.com/xdm/context/profile
https://ns.adobe.com/{TENANT_ID}/schemas/7442343-abs2343-21232421
為了使URI更適合REST,架構在名為meta:altId
的屬性中也具有URI的點標籤編碼:
_xdm.context.profile
_{TENANT_ID}.schemas.7442343-abs2343-21232421
對Schema Registry API的呼叫將支援URL編碼的$id
URI或meta:altId
(點符號格式)。 最佳實務是在對API進行REST呼叫時使用URL編碼的$id
URI,如下:
https%3A%2F%2Fns.adobe.com%2Fxdm%2Fcontext%2Fprofile
https%3A%2F%2Fns.adobe.com%2F{TENANT_ID}%2Fschemas%2F7442343-abs2343-21232421
在Schema Registry API中執行清單和查閱(GET)作業時,需要Accept
標題來判斷API傳回的資料格式。 查找特定資源時,Accept
標題中還必須包含版本號。
下表列出相容的Accept
標題值,包括具有版本號碼的值,以及使用API時傳回內容的說明。
接受 | 說明 |
---|---|
application/vnd.adobe.xed-id+json |
僅傳回ID清單。 這最常用於列出資源。 |
application/vnd.adobe.xed+json |
傳回包含原始$ref 和allOf 的完整JSON結構描述清單。 這可用來傳回完整資源清單。 |
application/vnd.adobe.xed+json; version={MAJOR_VERSION} |
具有$ref 和allOf 的原始XDM。 有標題和說明。 |
application/vnd.adobe.xed-full+json; version={MAJOR_VERSION} |
$ref 屬性並 allOf 解析。有標題和說明。 |
application/vnd.adobe.xed-notext+json; version={MAJOR_VERSION} |
具有$ref 和allOf 的原始XDM。 無標題或說明。 |
application/vnd.adobe.xed-full-notext+json; version={MAJOR_VERSION} |
$ref 屬性並 allOf 解析。無標題或說明。 |
application/vnd.adobe.xed-full-desc+json; version={MAJOR_VERSION} |
$ref 屬性並 allOf 解析。包括描述符。 |
如果僅提供主版本(如1、2、3),則註冊表將返回最新的次版本(如.1、.2、.3)。
方案的欄位列在其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.",
}
fieldName
、 field_name2
、 Field-Name
、 field-name_3
_fieldName
fieldName
title
,寫在「標題大小寫」中。 範例: Field Name
type
。
format
。examples
添加為陣列。description
說明欄位和有關欄位資料的相關資訊。 它應以完整的句子編寫,使用清楚的語言,讓任何存取架構的人都能瞭解欄位的意圖。如需如何定義API中不同欄位類型的詳細資訊,請參閱欄位限制上的檔案。
若要開始使用Schema Registry API進行呼叫,請選取其中一個可用的端點指南。