使用 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及其在 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，用于将字段组添加到源架构的下一步。

将字段组添加到源架构

创建字段组后，您可以通过向 /tenant/schemas/{SCHEMA_ID} 端点。

API格式

PATCH /tenant/schemas/{SCHEMA_ID}

参数	描述
`{SCHEMA_ID}`	URL编码 `$id` URI或 `meta:altId` 源架构的URL。

请求

以下请求将“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"
}

创建关系描述符

关系描述符在源模式和目标模式之间建立一对一关系。在为目标架构定义引用描述符后，您可以通过向 /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