管理API中的建議值

上次更新: 2023-05-25
  • 主題:
  • Schemas
    檢視有關此主題的更多資訊
  • 建立對象:
  • Developer
    User
    Admin
    Leader

對於Experience Data Model (XDM)中的任何字串欄位,您可以定義 列舉 會限制欄位可擷取至預先定義集的值。 如果您嘗試將資料內嵌至列舉欄位,但值不符合其設定中定義的任何值,則會拒絕內嵌。

相較於列舉,新增 建議值 至字串欄位不會限制其可擷取的值。 建議值反而會影響中可用的預先定義值 區段UI 將字串欄位納入為屬性時。

注意

欄位更新的建議值大約會延遲5分鐘,才會反映在分段UI中。

本指南說明如何使用管理建議值 結構描述登入API. 如需在Adobe Experience Platform使用者介面中執行此動作的步驟,請參閱 有關列舉和建議值的UI指南.

先決條件

本指南假設您熟悉XDM中結構描述構成的元素,以及如何使用結構描述登入API來建立和編輯XDM資源。 如需簡介,請參閱下列檔案:

此外,強烈建議您檢閱 列舉和建議值的演化規則 如果您要更新現有欄位。 如果您正在管理參與聯合的結構描述建議值,請參閱 合併列舉和建議值的規則.

組合

在API中, 列舉 欄位以 enum 陣列,而 meta:enum object為這些值提供好記的顯示名稱:

"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類別)中,為下所識別的結構描述而設的 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"
          }
        }
      ]'

套用變更後,Schema Registry在擷取結構描述時提供以下回應(回應因空間而被截斷):

{
  "$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"
      }
    }
  }
}

後續步驟

本指南說明如何管理Schema Registry API中字串欄位的建議值。 請參閱指南: 在API中定義自訂欄位 有關如何建立不同欄位型別的詳細資訊。

本頁內容