在API中管理建议值

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

与枚举相反,向字符串字段添加​ 建议值 ​不会限制它可以摄取的值。 建议值反而会影响分段UI中哪些预定义值在将该字符串字段作为属性包含时可用。

NOTE
字段的更新建议值大约有五分钟的延迟才能反映在分段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属性以包含新值。

向标准字段添加建议值 add-suggested-standard

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

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

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

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"
      }
    }
  }
}
NOTE
如果标准字段已包含meta:enum下的值,则描述符中的新值不会覆盖现有字段,而是会添加到上:
code language-json
"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"
   }
}

管理自定义字段的建议值 suggested-custom

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

WARNING
与标准字段相反,更新自定义字段的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中定义自定义字段的指南

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