使用Schema Registry API定義兩個結構描述之間的關係

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

主題：

建立對象：

開發人員

瞭解客戶之間的關係以及他們跨不同管道與您品牌的互動，是Adobe Experience Platform的重要一環。在Experience Data Model (XDM)結構描述的結構中定義這些關係，可讓您獲得有關客戶資料的複雜見解。

雖然結構描述關聯性可透過使用聯合結構描述和Real-Time Customer Profile來推斷，但這僅適用於共用相同類別的結構描述。若要在屬於不同類別的兩個結構描述之間建立關聯性，必須將專用關聯性欄位新增到 來源結構描述，以表示個別 參考結構描述 的識別。

NOTE

結構描述登入API會將參照結構描述稱為「目的地結構描述」。請勿將這些與資料準備對應集中的目的地結構描述或目的地連線的結構描述混淆。

本檔案提供教學課程，用於定義貴組織使用Schema Registry API定義之兩個結構描述間的一對一關係。

快速入門

此教學課程需要實際瞭解Experience Data Model (XDM)和XDM System。在開始本教學課程之前，請先檢閱下列檔案：

Experience Platform🔗中的XDM系統： Experience Platform中XDM及其實作的概觀。
- 結構描述組合的基本概念： XDM結構描述的建置區塊簡介。
Real-Time Customer Profile：根據來自多個來源的彙總資料，提供統一的即時消費者設定檔。
沙箱： Experience Platform提供可將單一Platform執行個體分割成個別虛擬環境的虛擬沙箱，以利開發及改進數位體驗應用程式。

開始進行此教學課程之前，請檢閱開發人員指南以取得重要資訊，您必須瞭解這些資訊才能成功呼叫Schema Registry API。這包括您的{TENANT_ID}、「容器」的概念以及發出要求所需的標頭（特別注意Accept標頭及其可能的值）。

定義來源和參考結構描述 define-schemas

您應已建立將在關係中定義的兩個結構描述。此教學課程會建立組織目前熟客方案（定義在「Loyalty Members」結構描述中）的成員與其最愛的飯店（定義在「Hotels」結構描述中）之間的關係。

結構描述關係由 來源結構描述 表示，該結構描述具有參照 參考結構描述 內其他欄位的欄位。在接下來的步驟中，"Loyalty Members"將會是來源結構描述，而"Hotels"將會做為參考結構描述。

IMPORTANT

為了建立關聯性，兩個結構描述都必須定義主要身分並啟用Real-Time Customer Profile。如果您需要如何適當地設定結構描述的指引，請參閱結構描述建立教學課程中啟用結構描述以用於設定檔的區段。

若要定義兩個結構描述之間的關係，您必須先取得兩個結構描述的$id值。如果您知道結構描述的顯示名稱(title)，您可以向Schema Registry API中的/tenant/schemas端點發出GET要求來尋找其$id值。

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'

NOTE

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。

IMPORTANT

來源結構描述不能使用其主要身分作為參考欄位。

在本教學課程中，參考結構描述"Hotels"包含作為結構描述主要身分的hotelId欄位。然而，來源結構描述"Loyalty Members"沒有專用欄位可作為hotelId的參考，因此需要建立自訂欄位群組，才能將新欄位新增至結構描述： favoriteHotel。

NOTE

如果您的來源結構描述已有您打算用作參考欄位的專用欄位，您可以直接跳到建立參考描述項的步驟。

建立新的欄位群組

為了將新欄位新增到結構描述，必須首先在欄位群組中定義它。您可以向/tenant/fieldgroups端點發出POST要求，以建立新的欄位群組。

API格式

POST /tenant/fieldgroups

要求

以下請求會建立新的欄位群組，該群組會在其加入的任何結構描述的_{TENANT_ID}名稱空間下新增favoriteHotel欄位。

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，以用於下一步將欄位群組新增至來源結構描述中。

將欄位群組新增至來源結構描述

建立欄位群組後，您可以對/tenant/schemas/{SCHEMA_ID}端點發出PATCH要求，將其新增至來源結構描述。

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。

回應

成功的回應會傳回更新結構描述的詳細資料，現在包含新增欄位群組在其allOf陣列下的$ref值。

{
    "$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="
    }
}

建立參考身分描述項 reference-identity

如果結構描述欄位用作關係中另一個結構描述的參考，則這些結構描述欄位必須套用參考身分描述項。由於「Loyalty Members」中的favoriteHotel欄位將參考「Hotels」中的hotelId欄位，因此favoriteHotel必須被指定參考身分描述項。

藉由對/tenant/descriptors端點發出POST要求，建立來源結構描述的參考描述項。

API格式

POST /tenant/descriptors

要求

下列要求會在來源結構描述"Loyalty Members"中建立favoriteHotel欄位的參考描述項。

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/533ca5da28087c44344810891b0f03d9",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/favoriteHotel",
    "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/533ca5da28087c44344810891b0f03d9",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/favoriteHotel",
    "xdm:identityNamespace": "Hotel ID",
    "meta:containerId": "tenant",
    "@id": "53180e9f86eed731f6bf8bf42af4f59d81949ba6"
}

建立關係描述項 create-descriptor

關係描述元在來源結構描述和參考結構描述之間建立一對一的關係。一旦您在來源結構描述中定義了適當欄位的參考身分描述項，您就可以對/tenant/descriptors端點發出POST要求來建立新的關係描述項。

API格式

POST /tenant/descriptors

要求

以下請求會建立新的關係描述項，並將"Loyalty Members"當作來源結構描述，並將"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: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中定義結構描述關係的步驟，請參閱有關使用結構描述編輯器定義結構描述關係的教學課程。

recommendation-more-help

62e9ffd9-1c74-4cef-8f47-0d00af32fc07