使用API定义两个模式之间的关 Schema Registry 系

了解不同渠道客户之间的关系及其与您品牌的互动是Adobe Experience Platform的重要部分。在(XDM)模式结构中定 Experience Data Model 义这些关系，使您能够对客户数据获得复杂的洞察。

虽然模式关系可以通过使用合并模式来推断， Real-time Customer Profile但这仅适用于共享同一类的模式。要在属于不同类的两个模式之间建立关系，必须向源模式添加专用关系字段，该字段引用目标模式的标识。

本文档提供了一个教程，用于定义组织使用定义的两个模式之间的一对一关系 Schema Registry API。

入门指南

本教程需要对(XDM) Experience Data Model 和进行有效的了解 XDM System。在开始本教程之前，请查阅以下文档：

Experience Platform中的XDM系统:XDM及其实施概述 Experience Platform。
- 模式合成基础:介绍XDM模式的构件。
Real-time Customer Profile:基于来自多个来源的聚集数据提供统一、实时的消费者用户档案。
沙箱: Experience Platform 提供将单个实例分为单独的虚 Platform 拟环境的虚拟沙箱，以帮助开发和发展数字体验应用程序。

在开始本教程之前，请查看开发人员指南，了解成功调用API所需了解的重要 Schema Registry 信息。这包括您 {TENANT_ID}的、“容器”的概念以及发出请求所需的标题(尤其要注意标题及 Accept 其可能的值)。

定义源和目标模式

您应已创建将在关系中定义的两个模式。本教程在组织的当前忠诚度项目(在“”模式中定义)的成员与其喜爱的酒店(在“”模式中定义)之Loyalty Members间创建了Hotels一种关系。

模式关系由源 模式表示 ，该源具有引用目标模式内的另 一个字段。在接下来的步骤中，Loyalty Members“”将是源模式，而“Hotels”将充当目标模式。

重要

要建立关系，两个模式必须定义主身份并启用 Real-time Customer Profile。如果您需要有关如何相应配置模式的指导，请参阅模式创建教程中有关启用模式以在用户档案中使用的部分。

要定义两个模式之间的关系，您必须首先获取两个 $id 模式的值。如果您知道模式的显title示名称()，则可以通过 $id 在API中向端点发出GET请求 /tenant/schemas 来查找其 Schema Registry 值。

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包括 $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.

注意

如果您的源模式已经有一个您计划用作引用字段的专用字段，则可以跳到创建引用描述符的步骤。

创建新混音

要向模式添加新字段，必须先在混音中定义该字段。可以通过向端点发出POST请求来创建新混 /tenant/mixins 音。

API格式

POST /tenant/mixins

请求

以下请求将创建一个新的混音，该混音 favoriteHotel 将在其 _{TENANT_ID} 添加到的任何命名空间的模式下添加一个字段。

curl -X POST\
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/mixins \
  -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 mixin 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 mixin 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` 源模式的URI。

请求

以下请求将“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` 添加的混音。

响应

成功的响应会返回更新模式的详细信息，该现在 $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": "{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="
    }
}

创建引用标识描述符

如果模式字段用作关系中其他模式的引用，则必须对其应用引用标识描述符。由于“ favoriteHotel ”中的字Loyalty Members段将引用“”中的字段，因 hotelId 此必须HotelshotelId 为其提供引用标识描述符。

通过向端点发出模式请求，为目标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: {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"
}

创建关系描述符

关系描述符建立源模式和目标模式之间的一对一关系。为目标模式定义引用描述符后，可以通过向端点发出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: {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"
}

后续步骤

通过遵循本教程，您成功地创建了两个模式之间的一对一关系。有关使用API使用描述符的更 Schema Registry 多信息，请参阅模式注册开发人员指南。有关如何在UI中定义模式关系的步骤，请参阅使用模式编辑器定义模式关系的教程。

adobe.com 上的资源

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

使用API定义两个模式之间的关 Schema Registry 系

入门指南

定义源和目标模式

为源模式定义引用字段

创建新混音

将混音添加到源模式

创建引用标识描述符

创建关系描述符

响应

后续步骤

adobe.com 上的资源

在此页面上

查看下一个：