使用 Schema Registry API

瞭解客戶之間的關係以及客戶與品牌之間通過各種渠道進行的互動是Adobe Experience Platform的重要部分。在結構中定義這些關係 Experience Data Model (XDM)架構使您能夠對客戶資料獲得複雜的見解。

而架構關係可通過使用聯合架構和 Real-time Customer Profile，這僅適用於共用同一類的方案。要在屬於不同類的兩個架構之間建立關係，必須將專用關係欄位添加到引用目標架構標識的源架構中。

本文檔提供了一個教程，用於定義由您的組織使用 Schema Registry API。

快速入門

本教程要求您對 Experience Data Model (XDM)和 XDM System。在開始本教程之前，請查看以下文檔：

XDM系統在Experience Platform:XDM及其在XDM中的應用 Experience Platform。
- 架構組合的基礎:介紹了XDM模式的構件。
Real-time Customer Profile:基於來自多個源的聚合資料提供統一、即時的用戶配置檔案。
沙箱: Experience Platform 提供虛擬沙箱，將單個沙箱 Platform 實例到獨立的虛擬環境，以幫助開發和發展數字型驗應用程式。

在開始本教程之前，請複習開發者指南獲取您需要瞭解的重要資訊，以便成功撥打 Schema Registry API。這包括您 {TENANT_ID}、"容器"的概念以及提出請求所需的標題(特別注意 Accept 標題及其可能值)。

定義源和目標架構

預期您已經建立了將在關係中定義的兩個架構。本教程在組織的當前會員計畫（在「」中定義）的成員之間建立關係Loyalty Members"架構及其最喜愛的酒店(在「Hotels"架構)。

架構關係由 源架構 有一個欄位，該欄位引用 目標架構。在後續步驟中， "Loyalty Members"將是源架構，而"Hotels"將用作目標架構。

重要

要建立關係，兩個方案必須都定義了主標識並且都為 Real-time Customer Profile。請參閱啟用在配置檔案中使用的架構在架構建立教程中，如果您需要有關如何相應地配置架構的指導。

要定義兩個方案之間的關係，必須首先獲取 $id 兩個方案的值。如果您知道顯示名稱(title)，您可以找到 $id 值，方法是向 /tenant/schemas 端點 Schema Registry API。

API格式

GET /tenant/schemas

要求

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas \
  -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 'Accept: application/vnd.adobe.xed-id+json'

注意

的 Accept 標題 application/vnd.adobe.xed-id+json 僅返回結果架構的標題、ID和版本。

回應

成功的響應返回由組織定義的方案清單，包括其 name。 $id。 meta:altId, version。

{
    "results": [
        {
            "title": "Newsletter Subscriptions",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/192a66930afad02408429174c311ae73",
            "meta:altId": "_{TENANT_ID}.schemas.192a66930afad02408429174c311ae73",
            "version": "1.2"
        },
        {
            "title": "Loyalty Members",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/2c66c3a4323128d3701289df4468e8a6",
            "meta:altId": "_{TENANT_ID}.schemas.2c66c3a4323128d3701289df4468e8a6",
            "version": "1.5"
        },
        {
            "title": "Hotels",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
            "meta:altId": "_{TENANT_ID}.schemas.d4ad4b8463a67f6755f2aabbeb9e02c7",
            "version": "1.0"
        }
    ],
    "_page": {
        "orderby": "updated",
        "next": null,
        "count": 3
    },
    "_links": {
        "next": null,
        "global_schemas": {
            "href": "https://platform-stage.adobe.io/data/foundation/schemaregistry/global/schemas"
        }
    }
}

錄制 $id 要定義之間關係的兩個方案的值。這些值將在後續步驟中使用。

定義源方案的引用欄位

在 Schema Registry，關係描述符在關係資料庫表中的工作與外鍵類似：源架構中的欄位用作對目標架構的主標識欄位的引用。如果源架構沒有用於此目的的欄位，則可能需要使用新欄位建立架構欄位組並將其添加到架構中。此新欄位必須具有 type 值"string。

重要

與目標架構不同，源架構不能將其主標識用作引用欄位。

在本教程中，目標架構「」Hotels"包含 hotelId 作為架構主標識的欄位，因此也將用作其引用欄位。但是，源架構"Loyalty Members"沒有要用作引用的專用欄位，並且必須給它一個新的欄位組，該欄位組將新欄位添加到架構中： favoriteHotel。

注意

如果源架構已有一個您計畫用作引用欄位的專用欄位，則可以跳到上的步驟建立引用描述符。

建立新欄位組

要向架構添加新欄位，必須先在欄位組中定義該欄位。您可以通過向 /tenant/fieldgroups 端點。

API格式

POST /tenant/fieldgroups

要求

以下請求將建立一個新欄位組， favoriteHotel 欄位 _{TENANT_ID} 添加到的任何架構的命名空間。

curl -X POST\
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/fieldgroups \
  -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 '{
        "type": "object",
        "title": "Favorite Hotel",
        "meta:intendedToExtend": ["https://ns.adobe.com/xdm/context/profile"],
        "description": "Favorite hotel field group for the Loyalty Members schema.",
        "definitions": {
            "favoriteHotel": {
              "properties": {
                "_{TENANT_ID}": {
                  "type":"object",
                  "properties": {
                    "favoriteHotel": {
                      "title": "Favorite Hotel",
                      "type": "string",
                      "description": "Favorite hotel for a Loyalty Member."
                    }
                  }
                }
              }
            }
        },
        "allOf": [
            {
              "$ref": "#/definitions/favoriteHotel"
            }
        ]
      }'

回應

成功的響應將返回新建立的欄位組的詳細資訊。

{
    "$id": "https://ns.adobe.com/{TENANT_ID}/mixins/3387945212ad76ee59b6d2b964afb220",
    "meta:altId": "_{TENANT_ID}.mixins.3387945212ad76ee59b6d2b964afb220",
    "meta:resourceType": "mixins",
    "version": "1.0",
    "type": "object",
    "title": "Favorite Hotel",
    "meta:intendedToExtend": [
        "https://ns.adobe.com/xdm/context/profile"
    ],
    "description": "Favorite hotel field group for the Loyalty Members schema.",
    "definitions": {
        "favoriteHotel": {
            "properties": {
                "_{TENANT_ID}": {
                    "type": "object",
                    "properties": {
                        "favoriteHotel": {
                            "title": "Favorite Hotel",
                            "type": "string",
                            "description": "Favorite hotel for a Loyalty Member.",
                            "meta:xdmType": "string"
                        }
                    },
                    "meta:xdmType": "object"
                }
            },
            "type": "object",
            "meta:xdmType": "object"
        }
    },
    "allOf": [
        {
            "$ref": "#/definitions/favoriteHotel"
        }
    ],
    "meta:xdmType": "object",
    "meta:abstract": true,
    "meta:extensible": true,
    "meta:containerId": "tenant",
    "meta:tenantNamespace": "_{TENANT_ID}",
    "meta:registryMetadata": {
        "eTag": "quM2aMPyb2NkkEiZHNCs/MG34E4=",
        "palm:sandboxName": "prod"
    }
}

屬性	說明
`$id`	只讀，系統生成了新欄位組的唯一標識符。以URI的形式。

錄制 $id 將欄位組添加到源架構的下一步中使用的欄位組的URI。

將欄位組添加到源架構

建立欄位組後，可以通過向PATCH請求將其添加到源架構 /tenant/schemas/{SCHEMA_ID} 端點。

API格式

PATCH /tenant/schemas/{SCHEMA_ID}

參數	說明
`{SCHEMA_ID}`	URL編碼 `$id` URI或 `meta:altId` 源架構。

要求

以下請求將添加「Favorite Hotel"欄位組到"Loyalty Members"架構。

curl -X PATCH \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.533ca5da28087c44344810891b0f03d9 \
  -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 '[
    {
      "op": "add",
      "path": "/allOf/-",
      "value":  {
        "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/3387945212ad76ee59b6d2b964afb220"
      }
    }
  ]'

屬性	說明
`op`	要執行的PATCH操作。此請求使用 `add` 的下界。
`path`	將添加新資源的架構欄位的路徑。將欄位組添加到架構時，值必須為「/allOf/ — 」。
`value.$ref`	的 `$id` 的子菜單。

回應

成功的響應返回更新的架構的詳細資訊，現在包括 $ref 其下添加的欄位組的值 allOf 陣列。

{
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/2c66c3a4323128d3701289df4468e8a6",
    "meta:altId": "_{TENANT_ID}.schemas.2c66c3a4323128d3701289df4468e8a6",
    "meta:resourceType": "schemas",
    "version": "1.1",
    "type": "object",
    "title": "Loyalty Members",
    "description": "",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-personal-details"
        },
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/ec16dfa484358f80478b75cde8c430d3"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/identitymap"
        },
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/3387945212ad76ee59b6d2b964afb220"
        }
    ],
    "meta:containerId": "tenant",
    "meta:class": "https://ns.adobe.com/xdm/context/profile",
    "meta:abstract": false,
    "meta:extensible": false,
    "meta:tenantNamespace": "_{TENANT_ID}",
    "imsOrg": "{ORG_ID}",
    "meta:extends": [
        "https://ns.adobe.com/xdm/context/profile",
        "https://ns.adobe.com/xdm/data/record",
        "https://ns.adobe.com/xdm/context/identitymap",
        "https://ns.adobe.com/xdm/common/extensible",
        "https://ns.adobe.com/xdm/common/auditable",
        "https://ns.adobe.com/xdm/context/profile-person-details",
        "https://ns.adobe.com/xdm/context/profile-personal-details",
        "https://ns.adobe.com/{TENANT_ID}/mixins/ec16dfa484358f80478b75cde8c430d3",
        "https://ns.adobe.com/{TENANT_ID}/mixins/61969bc646b66a6230a7e8840f4a4d33"
    ],
    "meta:xdmType": "object",
    "meta:registryMetadata": {
        "repo:createdDate": 1557525483804,
        "repo:lastModifiedDate": 1566419670915,
        "xdm:createdClientId": "{API_KEY}",
        "xdm:lastModifiedClientId": "{CLIENT_ID}",
        "eTag": "ITNzu8BVTO5pw9wfCtTTpk6U4WY="
    }
}

建立引用標識描述符

如果將架構欄位用作關係中其他架構的引用，則必須將引用標識描述符應用於它們。自 favoriteHotel 欄位「」Loyalty Members」將引用 hotelId 欄位「」Hotels" hotelId 必須給出引用標識描述符。

通過向目標架構發出POST請求，為目標架構建立引用描述符 /tenant/descriptors 端點。

API格式

POST /tenant/descriptors

要求

以下請求為 hotelId 目標架構「」中的欄位Hotels。

curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
  -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 '{
    "@type": "xdm:descriptorReferenceIdentity",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/hotelId",
    "xdm:identityNamespace": "Hotel ID"
  }'

參數	說明
`@type`	正在定義的描述符的類型。對於引用描述符，值必須為"xdm:descriptorReferenceIdentity"。
`xdm:sourceSchema`	的 `$id` 目標架構的URL。
`xdm:sourceVersion`	目標架構的版本號。
`sourceProperty`	目標架構的主標識欄位的路徑。
`xdm:identityNamespace`	引用欄位的標識名稱空間。此名稱空間必須與將欄位定義為架構的主標識時使用的名稱空間相同。查看標識命名空間概述的子菜單。

回應

成功的響應返回新建立的目標架構的引用描述符的詳細資訊。

{
    "@type": "xdm:descriptorReferenceIdentity",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/hotelId",
    "xdm:identityNamespace": "Hotel ID",
    "meta:containerId": "tenant",
    "@id": "53180e9f86eed731f6bf8bf42af4f59d81949ba6"
}

建立關係描述符

關係描述符在源模式和目標模式之間建立一對一關係。在為目標架構定義了引用描述符後，可以通過向目標架構發出POST請求來建立新的關係描述符 /tenant/descriptors 端點。

API格式

POST /tenant/descriptors

要求

以下請求將建立新的關係描述符，其中包含「Loyalty Members"作為源架構和"Legacy Loyalty Members"作為目標架構。

curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
  -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 '{
    "@type": "xdm:descriptorOneToOne",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/2c66c3a4323128d3701289df4468e8a6",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/favoriteHotel",
    "xdm:destinationSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
    "xdm:destinationVersion": 1,
    "xdm:destinationProperty": "/_{TENANT_ID}/hotelId"
  }'

參數	說明
`@type`	要建立的描述符的類型。的 `@type` 關係描述符的值為"xdm:descriptorOneToOne"。
`xdm:sourceSchema`	的 `$id` 源架構的URL。
`xdm:sourceVersion`	源架構的版本號。
`xdm:sourceProperty`	源架構中引用欄位的路徑。
`xdm:destinationSchema`	的 `$id` 目標架構的URL。
`xdm:destinationVersion`	目標架構的版本號。
`xdm:destinationProperty`	目標架構中引用欄位的路徑。

回應

成功的響應將返回新建立的關係描述符的詳細資訊。

{
    "@type": "xdm:descriptorOneToOne",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/2c66c3a4323128d3701289df4468e8a6",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/favoriteHotel",
    "xdm:destinationSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
    "xdm:destinationVersion": 1,
    "xdm:destinationProperty": "/_{TENANT_ID}/hotelId",
    "meta:containerId": "tenant",
    "@id": "76f6cc7105f4eaab7eb4a5e1cb4804cadc741669"
}

後續步驟

按照本教程，您已成功在兩個架構之間建立了一對一關係。有關使用描述符的詳細資訊 Schema Registry API，請參見架構註冊表開發人員指南。有關如何在UI中定義架構關係的步驟，請參見上的教程使用架構編輯器定義架構關係。

adobe.com 上的資源

Ab Multivariate Testing Recommendation Engine Content Management Third Party Integrations Voice Analytics Display Advertising

全新的改善搜尋

使用 Schema Registry API

快速入門

定義源和目標架構

定義源方案的引用欄位

建立新欄位組

將欄位組添加到源架構

建立引用標識描述符

建立關係描述符

回應

後續步驟

adobe.com 上的資源

本頁內容

檢視下一個:

學習

說明文件

社群

技術支援

資源

Adobe 帳戶

Adobe