使用定义两个架构之间的关系 Schema Registry API
能够了解客户之间的关系以及客户在不同渠道中与您的品牌的互动是Adobe Experience Platform的重要组成部分。 在的结构中定义这些关系 Experience Data Model (XDM)架构允许您对客户数据获得复杂的见解。
虽然可以通过使用合并架构和来推断架构关系 Real-Time Customer Profile,这仅适用于共享相同类的架构。 要在属于不同类的两个架构之间建立关系,必须将专用关系字段添加到 源架构,指示单独的身份 引用模式.
此文档提供了一个教程,用于定义贵组织使用的两个架构之间的一对一关系。 Schema Registry API.
快速入门
本教程需要您实际了解 Experience Data Model (XDM)和 XDM System. 在开始本教程之前,请查看以下文档:
- Experience Platform中的XDM系统:XDM及其在中的实施概述 Experience Platform.
- 模式组合基础:XDM架构的构建块简介。
- Real-Time Customer Profile:根据来自多个来源的汇总数据提供统一的实时使用者个人资料。
- 沙盒: Experience Platform 提供对单个进行分区的虚拟沙盒 Platform 将实例安装到单独的虚拟环境中,以帮助开发和改进数字体验应用程序。
在开始本教程之前,请查看 开发人员指南 如需了解成功调用 Schema Registry API。 这包括您的 {TENANT_ID}
、“容器”的概念以及发出请求所需的标头(请特别注意 Accept 标头及其可能值)。
定义源和引用架构 define-schemas
您应已创建将在关系中定义的两个架构。 本教程在组织当前的忠诚度计划(在“Loyalty Members”架构)和他们最喜爱的酒店(在“Hotels”架构)。
架构关系由表示 源架构 有一个字段引用中的另一个字段 引用模式. 在接下来的步骤中, ”Loyalty Members“ ”将是源架构,而“Hotels”将用作参考模式。
要定义两个架构之间的关系,您必须先获取 $id
两个架构的值。 如果您知道显示名称(title
),您可以找到它们的 $id
值,方法是向发出一个GET请求 /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'
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”没有要用作引用的专用字段 hotelId
,因此需要创建一个自定义字段组,才能向架构中添加新字段: favoriteHotel
.
创建新字段组
要向架构添加新字段,必须首先在字段组中定义它。 您可以通过向以下对象发出POST请求来创建新的字段组: /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
记录 $id
字段组的URI,将在将字段组添加到源架构的下一个步骤中使用。
将字段组添加到源架构
创建字段组后,您可以通过向以下对象发出PATCH请求来将其添加到源架构: /tenant/schemas/{SCHEMA_ID}
端点。
API格式
PATCH /tenant/schemas/{SCHEMA_ID}
{SCHEMA_ID}
$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
add
操作。path
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="
}
}
创建引用身份描述符 reference-identity
如果架构字段用作对关系中其他架构的引用,则必须应用引用身份描述符。 由于 favoriteHotel
”中的字段Loyalty Members”将指 hotelId
”中的字段Hotels“, favoriteHotel
必须为指定引用身份描述符。
通过对以下对象发出POST请求,为源架构创建引用描述符: /tenant/descriptors
端点。
API格式
POST /tenant/descriptors
请求
以下请求为创建引用描述符 favoriteHotel
字段”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: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
关系描述符在源架构和引用架构之间建立一对一的关系。 一旦为源架构中的相应字段定义了引用身份描述符,就可以通过向以下对象发出POST请求来创建新的关系描述符: /tenant/descriptors
端点。
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,请参见 Schema Registry开发人员指南. 有关如何在UI中定义架构关系的步骤,请参阅关于的教程 使用架构编辑器定义架构关系.