Schema Registry API快速入门

Schema Registry API允许您创建和管理各种Experience Data Model(XDM)资源。 本文档简要介绍在尝试调用Schema Registry API之前需要了解的核心概念。

先决条件

使用开发人员指南需要对Adobe Experience Platform的以下组件有一定的了解:

XDM使用JSON模式格式来描述和验证摄取的客户体验数据的结构。 因此,强烈建议您查看官方JSON模式文档,以更好地了解此基础技术。

读取示例API调用

Schema Registry API文档提供了示例API调用,以演示如何设置请求的格式。 这包括路径、所需标头以及格式正确的请求负载。 还提供了API响应中返回的示例JSON。 有关示例API调用文档中使用的约定的信息,请参阅Experience Platform疑难解答指南中如何阅读示例API调用一节。

收集所需标题的值

要调用Platform API,您必须先完成身份验证教程。 完成身份验证教程可为所有Experience Platform API调用中每个所需标头的值,如下所示:

  • Authorization: Bearer {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}

Experience Platform中的所有资源(包括属于Schema Registry的资源)都与特定虚拟沙箱隔离。 对Platform API的所有请求都需要一个标头来指定操作将在其中进行的沙盒的名称:

  • x-sandbox-name: {SANDBOX_NAME}
注意

有关Platform中沙箱的更多信息,请参阅沙盒文档

对Schema Registry的所有查找(GET)请求都需要一个附加的Accept标头,其值决定了API返回的信息格式。 有关更多详细信息,请参阅下面的Accept header部分。

所有包含有效负载(POST、PUT、PATCH)的请求都需要额外的标头:

  • Content-Type: application/json

知晓您的TENANT_ID

在整个API指南中,您将看到对TENANT_ID的引用。 此ID用于确保您创建的资源具有正确命名空间,并包含在您的IMS组织内。 如果您不知道自己的ID,可以通过执行以下GET请求来访问它:

API格式

GET /stats

请求

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/stats \
  -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}'

响应

成功响应会返回有关贵组织使用Schema Registry的信息。 这包括tenantId属性,其值为TENANT_ID

{
  "imsOrg":"{IMS_ORG}",
  "tenantId":"{TENANT_ID}",
  "counts": {
    "schemas": 4,
    "mixins": 3,
    "datatypes": 1,
    "classes": 2,
    "unions": 0,
  },
  "recentlyCreatedResources": [ 
    {
      "title": "Sample Field Group",
      "description": "New Sample Field Group.",
      "meta:resourceType": "mixins",
      "meta:created": "Sat Feb 02 2019 00:24:30 GMT+0000 (UTC)",
      "version": "1.1"
    },
    {
      "$id": "https://ns.adobe.com/{TENANT_ID}/classes/5bdb5582be0c0f3ebfc1c603b705764f",
      "title": "Tenant Class",
      "description": "Tenant Defined Class",
      "meta:resourceType": "classes",
      "meta:created": "Fri Feb 01 2019 22:46:21 GMT+0000 (UTC)",
      "version": "1.0"
    } 
  ],
  "recentlyUpdatedResources": [
    {
      "title": "Sample Field Group",
      "description": "New Sample Field Group.",
      "meta:resourceType": "mixins",
      "meta:updated": "Sat Feb 02 2019 00:34:06 GMT+0000 (UTC)",
      "version": "1.1"
    },
    {
      "title": "Data Schema",
      "description": "Schema for Data Information",
      "meta:resourceType": "schemas",
      "meta:updated": "Fri Feb 01 2019 23:47:43 GMT+0000 (UTC)",
      "meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/47b2189fc135e03c844b4f25139d10ab",
      "meta:classTitle": "Sample Class",
      "version": "1.1"
    }
 ],
 "classUsage": {
    "https://ns.adobe.com/{TENANT_ID}/classes/47b2189fc135e03c844b4f25139d10ab": [
      {
        "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
        "title": "Tenant Data Schema",
        "description": "Schema for tenant-specific data."
      }
    ],
    "https://ns.adobe.com/xdm/context/profile": [
      {
        "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/3ac6499f0a43618bba6b138226ae3542",
        "title": "Simple Profile",
        "description": "A simple profile schema."
      },
      {
        "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "title": "Program Schema",
        "description": "Schema for program-related data."
      },
      {
        "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/4025a705890c6d4a4a06b16f8cf6f4ca",
        "title": "Sample Schema",
        "description": "A sample schema."
      }
    ]
  }
 }

了解CONTAINER_ID

对Schema Registry API的调用需要使用CONTAINER_ID。 可以对其进行API调用的容器有两个:global容器和tenant容器。

全局容器

global容器包含所有标准Adobe和Experience Platform合作伙伴提供的类、架构字段组、数据类型和架构。 您只能对global容器执行列表和查找(GET)请求。

使用global容器的调用示例如下所示:

GET /global/classes

租户容器

tenant容器可保存由IMS组织定义的所有类、字段组、数据类型、架构和描述符,请不要与您的唯一TENANT_ID混淆。 这些IMS组织对每个组织都是唯一的,这意味着这些IMS组织不可见或无法管理。 您可以对在tenant容器中创建的资源执行所有CRUD操作(GET、POST、PUT、PATCH、DELETE)。

使用tenant容器的调用示例如下所示:

POST /tenant/fieldgroups

tenant容器中创建类、字段组、架构或数据类型时,该类型会保存到Schema Registry中,并分配一个$id URI,其中包含您的TENANT_ID。 此$id用于整个API中以引用特定资源。 $id值的示例在下一节中提供。

资源标识

XDM资源以URI形式使用$id属性进行标识,例如以下示例:

  • https://ns.adobe.com/xdm/context/profile
  • https://ns.adobe.com/{TENANT_ID}/schemas/7442343-abs2343-21232421

为了使URI对REST更友好,架构在名为meta:altId的属性中还具有URI的点表示法编码:

  • _xdm.context.profile
  • _{TENANT_ID}.schemas.7442343-abs2343-21232421

对Schema Registry API的调用将支持URL编码的$id URI或meta:altId(点表示法格式)。 最佳实践是在对API进行REST调用时使用URL编码的$id URI,如下所示:

  • https%3A%2F%2Fns.adobe.com%2Fxdm%2Fcontext%2Fprofile
  • https%3A%2F%2Fns.adobe.com%2F{TENANT_ID}%2Fschemas%2F7442343-abs2343-21232421

接受标头

在Schema Registry API中执行列表和查找(GET)操作时,需要Accept标头来确定API返回的数据格式。 查找特定资源时,Accept标头中还必须包含版本号。

下表列出了兼容的Accept标头值,包括具有版本号的值,以及API在使用时返回的内容描述。

Accept 描述
application/vnd.adobe.xed-id+json 仅返回ID列表。 这最常用于列出资源。
application/vnd.adobe.xed+json 返回包含原始$refallOf的完整JSON架构列表。 用于返回完整资源列表。
application/vnd.adobe.xed+json; version=1 具有$refallOf的原始XDM。 具有标题和描述。
application/vnd.adobe.xed-full+json; version=1 $ref 属性和已 allOf 解析。具有标题和描述。
application/vnd.adobe.xed-notext+json; version=1 具有$refallOf的原始XDM。 无标题或描述。
application/vnd.adobe.xed-full-notext+json; version=1 $ref 属性和已 allOf 解析。无标题或描述。
application/vnd.adobe.xed-full-desc+json; version=1 $ref 属性和已 allOf 解析。包含描述符。
注意

平台当前仅支持每个架构的一个主要版本(1)。 因此,执行查找请求时,version的值必须始终为1,才能返回架构的最新次要版本。 有关架构版本控制的详细信息,请参阅下面的子部分。

架构版本控制

架构版本由架构注册表API中的Accept标头和下游平台服务API负载中的schemaRef.contentType属性中的标头引用。

目前,平台仅支持每个架构的单个主版本(1)。 根据架构演变的规则,对架构的每次更新都必须是无损的,这意味着架构的新次要版本(1.21.3等) 始终向后兼容以前的次要版本。 因此,在指定version=1时,架构注册表始终返回架构的​最新​主版本1 ,这意味着不会返回以前的次版本。

注意

仅当数据集引用了架构,并且满足以下任一情况后,才会执行架构演变的无损要求:

  • 已将数据摄取到数据集中。
  • 该数据集已启用,可在“实时客户资料”中使用(即使未摄取任何数据)。

如果架构尚未与满足上述任一条件的数据集关联,则可以对其进行任何更改。 但是,在所有情况下,version组件仍保持在1

XDM字段约束和最佳实践

架构的字段列在其properties对象中。 每个字段本身就是一个对象,其中包含用于描述和约束字段可包含的数据的属性。

有关在API中定义字段类型的更多信息,请参阅本指南的字段约束指南,包括代码示例和最常用数据类型的可选约束。

以下示例字段说明了格式正确的XDM字段,并提供了有关命名约束和最佳实践的更多详细信息。 在定义包含相似属性的其他资源时,也可以应用这些实践。

"fieldName": {
    "title": "Field Name",
    "type": "string",
    "format": "date-time",
    "examples": [
        "2004-10-23T12:00:00-06:00"
    ],
    "description": "Full sentence describing the field, using proper grammar and punctuation.",
}
  • 字段对象的名称可以包含字母数字、短划线或下划线字符,但​不能​以下划线开头。
    • 正确: fieldNamefield_name2Field-Namefield-name_3
    • 错误: _fieldName
  • 字段对象的名称首选使用camelCase。 示例:fieldName
  • 该字段应包含title,在标题大小写中写入。 示例:Field Name
  • 字段需要type
    • 定义某些类型可能需要可选的format
    • 如果需要特定的数据格式,可以将examples添加为数组。
    • 也可使用注册表中的任何数据类型来定义字段类型。 有关更多信息,请参阅数据类型端点指南中关于创建数据类型🔗的部分。
  • description说明字段及有关字段数据的相关信息。 它应以完整的句子编写,并且使用清晰的语言,以便访问该模式的任何人都能够理解该字段的意图。

有关如何在API中定义不同字段类型的更多信息,请参阅字段约束的文档。

后续步骤

要开始使用Schema Registry API进行调用,请选择一个可用的端点指南。

在此页面上