在API中管理建议值

上次更新: 2023-05-25
  • 主题:
  • Schemas
    查看有关此主题的更多信息
  • 创建对象:
  • Developer
    User
    Admin
    Leader

对于体验数据模型(XDM)中的任何字符串字段,您可以定义 枚举 该参数会限制字段可以摄取到预定义集合的值。 如果您尝试将数据摄取到枚举字段,并且该值与其配置中定义的任何值都不匹配,则将拒绝摄取。

与枚举相反,添加 建议值 字符串字段不会限制它可以摄取的值。 相反,建议值会影响中提供的预定义值 分段UI 将字符串字段包含为属性时。

注意

字段的更新建议值大约会延迟5分钟,以便反映在分段UI中。

本指南介绍如何使用管理建议值 架构注册表API. 有关如何在Adobe Experience Platform用户界面中执行此操作的步骤,请参阅 有关枚举和建议值的UI指南.

先决条件

本指南假定您熟悉XDM中架构组合的元素以及如何使用架构注册表API创建和编辑XDM资源。 如果您需要获取简介,请参阅以下文档:

此外,还强烈建议您查看 枚举和建议值的演化规则 如果您正在更新现有字段。 如果您正在管理参与合并的架构的建议值,请参阅 合并枚举和建议值的规则.

合成

在API中, 枚举 字段由 enum 数组,而 meta:enum 对象为以下值提供友好的显示名称:

"exampleStringField": {
  "type": "string",
  "enum": [
    "value1",
    "value2",
    "value3"
  ],
  "meta:enum": {
    "value1": "Value 1",
    "value2": "Value 2",
    "value3": "Value 3"
  },
  "default": "value1"
}

对于枚举字段,架构注册表不允许 meta:enum 将扩展到 enum,因为尝试在这些约束之外引入字符串值将不会通过验证。

或者,您可以定义一个不包含 enum 数组,并且仅使用 meta:enum 要表示的对象 建议值

"exampleStringField": {
  "type": "string",
  "meta:enum": {
    "value1": "Value 1",
    "value2": "Value 2",
    "value3": "Value 3"
  },
  "default": "value1"
}

由于该字符串没有 enum 数组,用于定义约束 meta:enum 属性可以扩展以包含新值。

将建议值添加到标准字段

要扩展 meta:enum 对于标准字符串字段,您可以创建 友好名称描述符 用于特定架构中相关字段。

注意

字符串字段的建议值只能在架构级别添加。 换句话说,扩展 meta:enum 一个架构中某个标准字段的设置不会影响使用同一标准字段的其他架构。

以下请求将建议值添加到标准 eventType 字段(由 XDM ExperienceEvent类)下ID为的架构 sourceSchema

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:alternateDisplayInfo",
        "sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "sourceProperty": "/eventType",
        "title": {
            "en_us": "Enum Event Type"
        },
        "description": {
            "en_us": "Event type field with soft enum values"
        },
        "meta:enum": {
          "eventA": {
            "en_us": "Event Type A"
          },
          "eventB": {
            "en_us": "Event Type B"
          }
        }
      }'

应用描述符后,架构注册表在检索架构时使用以下内容进行响应(响应因空间而被截断):

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "title": "Example Schema",
  "properties": {
    "eventType": {
      "type":"string",
      "title": "Enum Event Type",
      "description": "Event type field with soft enum values.",
      "meta:enum": {
        "customEventA": "Custom Event Type A",
        "customEventB": "Custom Event Type B"
      }
    }
  }
}
注意

如果标准字段已包含下列值 meta:enum时,描述符中的新值不会覆盖现有字段,而是添加到上:

"standardField": {
   "type":"string",
   "title": "Example standard enum field",
   "description": "Standard field with existing enum values.",
   "meta:enum": {
       "standardEventA": "Standard Event Type A",
       "standardEventB": "Standard Event Type B",
       "customEventA": "Custom Event Type A",
       "customEventB": "Custom Event Type B"
   }
}

管理自定义字段的建议值

要管理 meta:enum 对于自定义字段,您可以通过PATCH请求更新该字段的父类、字段组或数据类型。

警告

与标准字段相反,它将 meta:enum 影响使用该字段的所有其他架构。 如果不希望更改在架构之间传播,请考虑改为创建新的自定义资源:

以下请求将更新 meta:enum 由自定义数据类型提供的“忠诚度级别”字段的读者群:

curl -X PATCH \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes/_{TENANT_ID}.datatypes.8779fd45d6e4eb074300023a439862bbba359b60d451627a \
  -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": "replace",
          "path": "/loyaltyLevel/meta:enum",
          "value": {
            "ultra-platinum": "Ultra Platinum",
            "platinum": "Platinum",
            "gold": "Gold",
            "silver": "Silver",
            "bronze": "Bronze"
          }
        }
      ]'

应用更改后,架构注册表在检索架构时使用以下内容进行响应(响应因空间而被截断):

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "title": "Example Schema",
  "properties": {
    "loyaltyLevel": {
      "type":"string",
      "title": "Loyalty Level",
      "description": "The loyalty program tier that this customer qualifies for.",
      "meta:enum": {
        "ultra-platinum": "Ultra Platinum",
        "platinum": "Platinum",
        "gold": "Gold",
        "silver": "Silver",
        "bronze": "Bronze"
      }
    }
  }
}

后续步骤

本指南介绍了如何管理架构注册表API中字符串字段的建议值。 请参阅指南,网址为 在API中定义自定义字段 有关如何创建不同字段类型的更多信息。

在此页面上