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

了解客戶之間的關係,以及客戶在不同管道與品牌互動的能力,是Adobe Experience Platform的重要一環。 在Experience Data Model (XDM)結構內定義這些關係,可讓您對客戶資料獲得複雜的深入分析。

雖然可透過使用聯合架構和Real-time Customer Profile來推斷架構關係,但這隻適用於共用相同類別的架構。 要在屬於不同類的兩個架構之間建立關係,必須將專用的關係欄位添加到源架構中,該源架構引用目標架構的標識。

本檔案提供教學課程,說明如何使用Schema Registry API來定義貴組織所定義的兩個結構之間的一對一關係。

快速入門

本教學課程需要妥善了解Experience Data Model (XDM)和XDM System。 開始本教學課程之前,請檢閱下列檔案:

開始本教學課程之前,請檢閱開發人員指南,以取得您需要了解的重要資訊,以便成功呼叫Schema Registry API。 這包括您的{TENANT_ID}、「容器」的概念,以及提出請求所需的標題(請特別注意Accept標題及其可能的值)。

定義源和目標架構

您應已建立將在關係中定義的兩個結構。 本教學課程會在組織的目前忠誠計畫(在「Loyalty Members」架構中定義)的成員與其最喜愛的酒店(在「Hotels」架構中定義)之間建立關係。

架構關係由​源架構​表示,該源架構具有引用​目標架構​內另一欄位的欄位。 在後續步驟中,「Loyalty Members」將是源架構,而「Hotels」將充當目標架構。

重要

若要建立關係,兩個結構都必須定義主要身分,並且必須為Real-time Customer Profile啟用。 如果您需要如何據以設定結構的指引,請參閱架構建立教學課程中啟用結構以用於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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Accept: application/vnd.adobe.xed-id+json'
注意

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

回應

成功的回應會傳回您的組織所定義的結構清單,包括其name$idmeta:altIdversion

{
    "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端點提出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: {IMS_ORG}' \
  -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: {IMS_ORG}' \
  -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": "{IMS_ORG}",
    "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="
    }
}

建立引用標識描述符

如果方案欄位用作關係中其他方案的引用,則必須將引用標識描述符應用到它們。 由於「Loyalty Members」中的favoriteHotel欄位將引用「Hotels」中的hotelId欄位,因此hotelId必須獲得引用標識描述符。

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

API格式

POST /tenant/descriptors

要求

以下請求為目標架構「Hotels」中的hotelId欄位建立引用描述符。

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: {IMS_ORG}' \
  -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"
}

建立關係描述符

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

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: {IMS_ORG}' \
  -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的描述符的詳細資訊,請參閱Schema Registry開發者指南。 有關如何在UI中定義架構關係的步驟,請參閱有關使用架構編輯器🔗定義架構關係的教程。

本頁內容