描述符端点

架构定义了数据实体的静态视图，但未提供基于这些架构（例如数据集）的数据如何相互关联的特定详细信息。 Adobe Experience Platform允许您使用描述符描述这些关系以及有关架构的其他解释性元数据。

架构描述符是租户级别的元数据，这意味着它们对于您的组织是唯一的，并且所有描述符操作都在租户容器中进行。

每个架构可以应用一个或多个架构描述符实体。 每个架构描述符实体包括一个描述符 @type 和 sourceSchema 适用于此项。 应用后，这些描述符将应用于使用该架构创建的所有数据集。

此 /descriptors 中的端点 Schema Registry API允许您以编程方式管理体验应用程序中的描述符。

快速入门

本指南中使用的端点是 Schema Registry API. 在继续之前，请查看 快速入门指南 有关相关文档的链接，请参阅本文档中的示例API调用指南，以及有关成功调用任何Experience PlatformAPI所需的所需标头的重要信息。

检索描述符列表

您可以通过向以下用户发出GET请求来列出您的组织已定义的所有描述符： /tenant/descriptors.

API格式

GET /tenant/descriptors

请求

curl -X GET \
  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 'Accept: application/vnd.adobe.xdm-link+json'

响应格式取决于 Accept 标头在请求中发送。 请注意 /descriptors 端点使用 Accept 标头与中的所有其他端点不同 Schema Registry API。

响应

响应包括已定义描述符的每个描述符类型的数组。 换言之，如果没有特定的 @type 定义，注册表将不会返回该描述符类型的空数组。

使用时 link Accept 标头，每个描述符在格式中显示为一个数组项 /{CONTAINER}/descriptors/{DESCRIPTOR_ID}

{
  "xdm:alternateDisplayInfo": [
    "/tenant/descriptors/85dc1bc8b91516ac41163365318e38a9f1e4f351",
    "/tenant/descriptors/49bd5abb5a1310ee80ebc1848eb508d383a462cf",
    "/tenant/descriptors/b3b3e548f1c653326bcf5459ceac4140fc0b9e08"
  ],
  "xdm:descriptorIdentity": [
    "/tenant/descriptors/f7a4bc25429496c4740f8f9a7a49ba96862c5379"
  ],
  "xdm:descriptorOneToOne": [
    "/tenant/descriptors/cb509fd6f8ab6304e346905441a34b58a0cd481a"
  ]
}

查找描述符

如果要查看特定描述符的详细信息，可以使用其查找(GET)单个描述符 @id.

API格式

GET /tenant/descriptors/{DESCRIPTOR_ID}

请求

以下请求通过以下项检索描述符： @id 值。 描述符未进行版本控制，因此无 Accept 查找请求中需要标头。

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

响应

成功响应将返回描述符的详细信息，包括其 @type 和 sourceSchema以及因描述符类型而异的其他信息。 返回的 @id 应该匹配描述符 @id 在请求中提供。

{
  "@type": "xdm:descriptorIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/personalEmail/address",
  "xdm:namespace": "Email",
  "xdm:property": "xdm:code",
  "xdm:isPrimary": false,
  "createdUser": "{CREATED_USER}",
  "imsOrg": "{ORG_ID}",
  "createdClient": "{CREATED_CLIENT}",
  "updatedUser": "{UPDATED_USER}",
  "created": 1548899346989,
  "updated": 1548899346989,
  "meta:containerId": "tenant",
  "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

创建描述符

您可以通过向以下对象发出POST请求来创建新的描述符： /tenant/descriptors 端点。

API格式

POST /tenant/descriptors

请求

以下请求在示例架构中的“电子邮件地址”字段中定义一个身份描述符。 这说明 Experience Platform 将电子邮件地址用作标识符以帮助拼接有关个人的信息。

curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
  -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 '
      {
        "@type": "xdm:descriptorIdentity",
        "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "xdm:sourceVersion": 1,
        "xdm:sourceProperty": "/personalEmail/address",
        "xdm:namespace": "Email",
        "xdm:property": "xdm:code",
        "xdm:isPrimary": false
      }'

响应

成功的响应返回HTTP状态201（已创建）以及新创建的描述符的详细信息，包括其 @id. 此 @id 是由分配的只读字段 Schema Registry 和用于引用API中的描述符。

{
  "@type": "xdm:descriptorIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/personalEmail/address",
  "xdm:namespace": "Email",
  "xdm:property": "xdm:code",
  "xdm:isPrimary": false,
  "meta:containerId": "tenant",
  "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

更新描述符

您可以通过包含描述符的属性来更新描述符 @id 在PUT请求的路径中。

API格式

PUT /tenant/descriptors/{DESCRIPTOR_ID}

请求

此请求实际上会重写描述符，因此请求正文必须包含定义该类型的描述符所需的所有字段。 换句话说，用于更新(PUT)描述符的请求有效负载与请求有效负载相同 创建(POST)描述符 类型相同。

以下示例将标识描述符更新为引用其他 xdm:sourceProperty (mobile phone)并更改 xdm:namespace 到 Phone.

curl -X PUT \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/f3a1dfa38a4871cf4442a33074c1f9406a593407 \
  -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 '{
        "@type": "xdm:descriptorIdentity",
        "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "xdm:sourceVersion": 1,
        "xdm:sourceProperty": "/mobilePhone/number",
        "xdm:namespace": "Phone",
        "xdm:property": "xdm:code",
        "xdm:isPrimary": false
      }'

响应

成功的响应返回HTTP状态201 （已创建），并且 @id 的已更新描述符(应当匹配 @id （在请求中发送）。

{
    "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

执行 查找(GET)请求 要查看描述符，将显示字段现已更新以反映PUT请求中发送的更改。

删除描述符

有时，您可能需要从删除已定义的描述符 Schema Registry. DELETE这是通过发出引用 @id 要移除的描述符的ID。

API格式

DELETE /tenant/descriptors/{DESCRIPTOR_ID}

请求

curl -X DELETE \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/ca921946fb5281cbdb8ba5e07087486ce531a1f2  \
  -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}'

响应

成功的响应返回HTTP状态204（无内容）和一个空白正文。

要确认描述符已被删除，您可以执行 查找请求 针对描述符 @id. 响应返回HTTP状态404 （未找到），因为描述符已从 Schema Registry.

附录

以下部分提供有关使用中的描述符的其他信息 Schema Registry API。

定义描述符

以下部分概述了可用的描述符类型，包括用于定义每种类型的描述符的必填字段。

身份描述符

身份描述符表示“sourceproperty“（属于）”sourceschema“ ”是一个 Identity 字段，如所述 Adobe Experience Platform Identity服务.

{
  "@type": "xdm:descriptorIdentity",
  "xdm:sourceSchema":
    "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/personalEmail/address",
  "xdm:namespace": "Email",
  "xdm:property": "xdm:code",
  "xdm:isPrimary": false
}

友好名称描述符

友好名称描述符允许用户修改 title， description、和 meta:enum 核心库架构字段的值。 在使用“eVar”和您希望标记为包含特定于您的组织的信息的其他“通用”字段时特别有用。 UI可以使用这些显示更友好的名称或仅显示具有友好名称的字段。

{
  "@type": "xdm:alternateDisplayInfo",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/xdm:eventType",
  "xdm:title": {
    "en_us": "Event Type"
  },
  "xdm:description": {
    "en_us": "The type of experience event detected by the system."
  },
  "meta:enum": {
    "click": "Mouse Click",
    "addCart": "Add to Cart",
    "checkout": "Cart Checkout"
  },
  "xdm:excludeMetaEnum": {
    "web.formFilledOut": "Web Form Filled Out",
    "media.ping": "Media ping"
  }
}

关系描述符

关系描述符描述两个不同架构之间的关系，它们基于中所述的属性 sourceProperty 和 destinationProperty. 请参阅上的教程 定义两个架构之间的关系 了解更多信息。

{
  "@type": "xdm:descriptorOneToOne",
  "xdm:sourceSchema":
    "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/parentField/subField",
  "xdm:destinationSchema":
    "https://ns.adobe.com/{TENANT_ID}/schemas/78bab6346b9c5102b60591e15e75d254",
  "xdm:destinationVersion": 1,
  "xdm:destinationProperty": "/parentField/subField"
}

引用身份描述符

引用身份描述符为架构字段的主要身份提供引用上下文，允许其他架构中的字段引用它。 引用架构必须先定义主标识字段，其他架构才能通过此描述符引用该字段。

{
  "@type": "xdm:descriptorReferenceIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/78bab6346b9c5102b60591e15e75d254",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/parentField/subField",
  "xdm:identityNamespace": "Email"
}

已弃用的字段描述符

您可以 弃用自定义XDM资源中的字段 通过添加 meta:status 属性设置为 deprecated 到有问题的领域。 但是，如果要弃用由架构中的标准XDM资源提供的字段，可向相关架构分配已弃用的字段描述符，以获得相同的效果。 使用 正确 Accept 标头后，您可以在API中查找架构时，查看该架构已弃用的标准字段。

{
  "@type": "xdm:descriptorDeprecated",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/c65ddf08cf2d4a2fe94bd06113bf4bc4c855e12a936410d5",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/faxPhone"
}

Business.Adobe.com 资源

Website Optimization Asset Collections Content Management System Data Connectors Advertising Analytics Attribution