Schema Registry API快速入門

Schema Registry API可讓您建立和管理各種Experience Data Model(XDM)資源。 本檔案提供您在嘗試呼叫Schema Registry API之前,需要瞭解的核心概念的簡介。

先決條件

使用開發人員指南需要對下列Adobe Experience Platform元件有良好的認識:

  • Experience Data Model (XDM) System:組織客戶體驗資 Experience Platform 料的標準化架構。
  • Real-time Customer Profile:根據來自多個來源的匯整資料,提供統一、即時的消費者個人檔案。
  • Sandboxes: Experience Platform 提供虛擬沙盒,可將單一執行個體分 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: {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

瞭解您的TENANT_ID

在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時傳回內容的說明。

Accept 說明
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 解析。包括描述符。
注意

平台目前僅支援每個架構(1)的一個主要版本。 因此,在執行查找請求時,version的值必須始終為1,以返回方案的最新次要版本。 有關方案版本化的詳細資訊,請參閱以下子部分。

方案版本控制

架構版本由架構註冊表API的Accept標題和下游平台服務API負載的schemaRef.contentType屬性中的標題引用。

目前,平台僅支援每個架構的單一主要版本(1)。 根據模式演化規則,對模式的每次更新都必須是非破壞性的,這表示模式的新次要版本(1.21.3等) 始終向後相容以前的次要版本。 因此,在指定version=1時,架構註冊表始終返回架構的​最新​主版本1 ,這表示不返回以前的次版本。

注意

只有在資料集引用了模式且以下情況之一成立後,才會強制執行模式演化的非破壞性要求:

  • 資料已收錄至資料集。
  • 資料集已啟用,可用於即時客戶個人檔案(即使未收錄任何資料)。

如果模式尚未與符合上述條件之一的資料集建立關聯,則可對其進行任何變更。 但是,在所有情況下,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說明欄位和有關欄位資料的相關資訊。 它應以完整的句子編寫,使用清楚的語言,讓任何存取架構的人都能瞭解欄位的意圖。

如需如何定義API中不同欄位類型的詳細資訊,請參閱欄位限制上的檔案。

後續步驟

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

本頁內容

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now