文档Experience Platform体验数据模型 (XDM) 指南

使用架构注册表API将特定字段添加到架构

Last update: Fri Apr 04 2025 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 主题：

创建对象：

  • 开发人员

体验数据模型(XDM)架构由一个基类组成，通过使用由Adobe定义的标准字段组和由您的组织定义的自定义字段组，包含其他字段。

构建架构时，您可能要使用给定字段组中的某些字段，而排除同一组中您不需要的其他字段。 本教程将演示如何使用架构注册表API将字段组中的各个字段添加到架构中。

NOTE
有关如何在Adobe Experience Platform UI中添加和删除各个架构字段的信息，请参阅有关基于字段的工作流的指南（当前为测试版）。

先决条件

本教程涉及调用架构注册表API。 开始之前，请查看开发人员指南以了解成功调用API所需了解的重要信息，包括您的{TENANT_ID}、容器的概念以及发出请求所需的标头。

了解meta:refProperty字段

对于任何给定架构，构成其结构的类和字段组在其allOf数组下引用。 每个组件都表示为一个对象，其中包含引用组件的URI $id的$ref属性。

以下JSON表示使用单个类(experienceevent)和字段组(experienceevent-all)的简化架构：

{
  "title": "My Sample Schema",
  "description": "My Sample Description",
  "type": "object",
  "allOf": [
    {
      "$ref": "https://ns.adobe.com/xdm/context/experienceevent"
    },
    {
      "$ref": "https://ns.adobe.com/experience/campaign/experienceevent-all"
    }
  ]
}

对于allOf数组中引用字段组的任何对象，可以添加同级meta:refProperty字段以指定组中应包含哪些字段到架构中。

NOTE
每个字段都使用JSON指针字符串指定，该字符串表示其相应字段组中的字段路径。 字符串必须以前导斜杠(/)开头，并且不应包含任何properties命名空间。 例如： /_experience/campaign/message/id。

当作为字符串包含时，meta:refProperty可以引用组中的单个字段。 通过在具有不同meta:refProperty值的另一个对象中使用相同的$ref值，可以包含来自同一组的其他字段。

{
  "title": "My Sample Schema",
  "description": "An example schema that uses the XDM ExperienceEvent class.",
  "type": "object",
  "allOf": [
    {
      "$ref": "https://ns.adobe.com/xdm/context/experienceevent"
    },
    {
      "$ref": "https://ns.adobe.com/experience/campaign/experienceevent-all",
      "meta:refProperty": "/_experience/campaign/message/id"
    },
    {
      "$ref": "https://ns.adobe.com/experience/campaign/experienceevent-all",
      "meta:refProperty": "/_experience/campaign/message/size"
    }
  ]
}

或者，也可以将meta:refProperty作为数组提供，从而允许您在单个allOf列表项中指定要包含来自给定组的多个字段：

{
  "title": "My Sample Schema",
  "description": "An example schema that uses the XDM ExperienceEvent class.",
  "type": "object",
  "allOf": [
    {
      "$ref": "https://ns.adobe.com/xdm/context/experienceevent"
    },
    {
      "$ref": "https://ns.adobe.com/experience/campaign/experienceevent-all",
      "meta:refProperty": [
        "/_experience/campaign/message/id",
        "/_experience/campaign/message/size",
        "/_experience/campaign/message/variant"
      ]
    }
  ]
}

使用PUT操作添加字段

您可以使用PUT请求重写整个架构，并配置要包含在allOf下的字段。

API格式

PUT /tenant/schemas/{SCHEMA_ID}
参数
描述
{SCHEMA_ID}
要重写的架构的meta:altId或URL编码的$id。

请求

以下请求更新allOf数组下字段组中包含的特定字段。

curl -X PUT \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67 \
  -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 '{
        "title": "My Sample Schema",
        "description": "My Sample Description",
        "type": "object",
        "allOf": [
          {
            "$ref": "https://ns.adobe.com/xdm/context/experienceevent"
          },
          {
            "$ref": "https://ns.adobe.com/experience/campaign/experienceevent-all",
            "meta:refProperty": [
              "/_experience/campaign/message/id",
              "/_experience/campaign/message/size",
              "/_experience/campaign/message/variant"
            ]
          }
        ]
      }'

响应

成功的响应将返回已更新架构的详细信息。

{
  "title": "My Sample Schema",
  "description": "My Sample Description",
  "type": "object",
  "allOf": [
    {
      "$ref": "https://ns.adobe.com/xdm/context/experienceevent"
    },
    {
      "$ref": "https://ns.adobe.com/experience/campaign/experienceevent-all",
      "meta:refProperty": [
        "/_experience/campaign/message/id",
        "/_experience/campaign/message/size",
        "/_experience/campaign/message/variant"
      ]
    }
  ],
  "meta:class": "https://ns.adobe.com/xdm/context/experienceevent",
  "meta:abstract": false,
  "meta:extensible": false,
  "meta:extends": [
      "https://ns.adobe.com/xdm/context/experienceevent",
      "https://ns.adobe.com/xdm/data/time-series"
  ],
  "meta:containerId": "tenant",
  "imsOrg": "{ORG_ID}",
  "meta:altId": "_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67",
  "meta:xdmType": "object",
  "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d5cc04eb8d50190001287e4c869ebe67",
  "version": "1.0",
  "meta:resourceType": "schemas",
  "meta:registryMetadata": {
      "repo:createDate": 1552088461236,
      "repo:lastModifiedDate": 1552088470592,
      "xdm:createdClientId": "{CREATED_CLIENT}",
      "xdm:repositoryCreatedBy": "{CREATED_BY}"
  }
}
NOTE
有关架构的PUT请求的更多详细信息，请参阅架构端点指南。

使用PATCH操作添加字段

您可以使用PATCH请求将单个字段添加到架构而不覆盖其他字段。 架构注册表支持所有标准JSON修补程序操作，包括add、remove和replace。 有关JSON修补程序的详细信息，请参阅API基础指南。

API格式

PATCH /tenant/schemas/{SCHEMA_ID}
参数
描述
{SCHEMA_ID}
要重写的架构的meta:altId或URL编码的$id。

请求

以下请求将新对象添加到架构的allOf数组，指定要添加的字段。

curl -X PATCH \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67 \
  -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 '[
        {
          "op": "add",
          "path": "/allOf/-",
          "value":  {
            "$ref": "https://ns.adobe.com/experience/campaign/experienceevent-all",
            "meta:refProperty": [
              "/_experience/campaign/message/id",
              "/_experience/campaign/message/size",
              "/_experience/campaign/message/variant"
            ]
          }
        }
      ]'

响应

成功的响应将返回已更新架构的详细信息。

{
  "title": "My Sample Schema",
  "description": "My Sample Description",
  "type": "object",
  "allOf": [
    {
      "$ref": "https://ns.adobe.com/xdm/context/experienceevent"
    },
    {
      "$ref": "https://ns.adobe.com/experience/campaign/experienceevent-all",
      "meta:refProperty": [
        "/_experience/campaign/message/id",
        "/_experience/campaign/message/size",
        "/_experience/campaign/message/variant"
      ]
    }
  ],
  "meta:class": "https://ns.adobe.com/xdm/context/experienceevent",
  "meta:abstract": false,
  "meta:extensible": false,
  "meta:extends": [
      "https://ns.adobe.com/xdm/context/experienceevent",
      "https://ns.adobe.com/xdm/data/time-series"
  ],
  "meta:containerId": "tenant",
  "imsOrg": "{ORG_ID}",
  "meta:altId": "_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67",
  "meta:xdmType": "object",
  "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d5cc04eb8d50190001287e4c869ebe67",
  "version": "1.0",
  "meta:resourceType": "schemas",
  "meta:registryMetadata": {
      "repo:createDate": 1552088461236,
      "repo:lastModifiedDate": 1552088470592,
      "xdm:createdClientId": "{CREATED_CLIENT}",
      "xdm:repositoryCreatedBy": "{CREATED_BY}"
  }
}
NOTE
有关架构的PATCH请求的更多详细信息，请参阅架构端点指南。

后续步骤

本指南介绍了如何使用API调用将现有字段组中的单个字段添加到架构。 有关如何在Experience Platform UI中执行类似的基于字段的任务的详细信息，请参阅基于字段的工作流指南。

有关架构注册表API功能的详细信息，请参阅API概述，以获取完整的端点和进程列表。

recommendation-more-help
62e9ffd9-1c74-4cef-8f47-0d00af32fc07