開始使用Schema Registry API

Schema Registry API可讓您建立和管理各種Experience Data Model (XDM)資源。 本檔案提供嘗試呼叫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 呼叫中每個必要標頭的值,如下所示:

  • Authorization: Bearer {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {ORG_ID}

Experience Platform中的所有資源(包括屬於Schema Registry的資源)都與特定的虛擬沙箱隔離。 對Platform API的所有請求都需要標頭,以指定將在其中執行作業的沙箱名稱:

  • x-sandbox-name: {SANDBOX_NAME}
NOTE
如需Platform中沙箱的詳細資訊,請參閱沙箱檔案

對Schema Registry的所有查詢(GET)請求都需要額外的Accept標頭,其值會決定API傳回的資訊格式。 如需詳細資訊,請參閱下方的接受標頭區段。

所有包含承載 (POST、PUT、PATCH) 的請求都需有額外的標頭:

  • Content-Type: application/json

知道您的TENANT_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容器包含所有由組織定義的類別、欄位群組、資料型別、結構描述和描述項,切勿與您的唯一TENANT_ID混淆。 這些對於每個組織都是獨一無二的,這表示其他組織看不到或無法管理這些值。 您可以針對您在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屬性來識別,例如以下範例:

  • 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

Accept標題 accept

在Schema Registry API中執行清單和查詢(GET)作業時,需要Accept標頭來決定API傳回的資料格式。 查詢特定資源時,Accept標頭中也必須包含版本號碼。

下表列出相容的Accept標頭值,包括版本號碼的值,以及使用API時傳回的描述。

接受
說明
application/vnd.adobe.xed-id+json
只傳回ID清單。 這最常用於列出資源。
application/vnd.adobe.xed+json
傳回包含原始$refallOf的完整JSON結構描述清單。 這可用來傳回完整資源的清單。
application/vnd.adobe.xed+json; version=1
含有$refallOf的原始XDM。 有標題和說明。
application/vnd.adobe.xed-full+json; version=1
已解決$ref屬性和allOf。 有標題和說明。
application/vnd.adobe.xed-notext+json; version=1
含有$refallOf的原始XDM。 無標題或說明。
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
$refallOf已解決,有標題和說明。 已棄用的欄位以deprecatedmeta:status屬性表示。
NOTE
平台目前僅支援每個結構描述(1)的一個主要版本。 因此,在執行查詢要求時,version的值必須一律為1,才能傳回結構描述的最新次要版本。 請參閱以下小節,以取得架構版本設定的詳細資訊。

方案版本設定 versioning

結構描述版本由結構描述登入API中的Accept標頭以及下游平台服務API裝載中的schemaRef.contentType屬性參考。

目前,Platform僅支援每個結構描述的單一主要版本(1)。 根據結構描述演化🔗的規則,結構描述的每次更新都必須是非破壞性的,這表示結構描述的新次要版本(1.21.3等) 始終與先前的次要版本回溯相容。 因此,在指定version=1時,結構描述登入一律會傳回結構描述的​ latest ​主要版本1,這表示不會傳回先前的次要版本。

NOTE
只有在資料集參考結構描述且下列其中一個情況為真時,才會強制執行結構描述演化的非破壞性需求:
  • 資料已內嵌到資料集中。
  • 此資料集已啟用用於即時客戶個人檔案(即使未擷取任何資料)。
如果結構描述尚未與符合上述其中一項條件的資料集建立關聯,則可以對資料集進行任何變更。 但是,在所有情況下,version元件仍保持在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.",
}
  • 欄位物件的名稱可能包含英數、破折號或底線字元,但​ 不能 ​以底線開頭。

    • 正確: fieldNamefield_name2Field-Namefield-name_3
    • 不正確: _fieldName
  • 欄位名稱不區分大小寫,且結構描述中的相同層級必須有不同的名稱。

  • 欄位物件的名稱偏好使用camelCase。 範例:fieldName

  • 欄位應包含以字首大寫寫寫的title。 範例:Field Name

  • 欄位需要type

    • 定義某些型別可能需要選擇性的format
    • 在需要特定格式化的資料時,可以將examples新增為陣列。
    • 也可以使用登入中的任何資料型別來定義欄位型別。 如需詳細資訊,請參閱資料型別端點指南中有關建立資料型別的章節。
  • description說明欄位和欄位資料的相關資訊。 應以完整的句子撰寫並加上清晰的語言,讓存取結構描述的任何人都能瞭解此欄位的意圖。

後續步驟

若要開始使用Schema Registry API進行呼叫,請選取其中一個可用的端點指南。

recommendation-more-help
62e9ffd9-1c74-4cef-8f47-0d00af32fc07