文件Experience Platform體驗資料模型 (XDM) 指南

管理API中的建議值

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 主題：

建立對象：

  • 開發人員

對於體驗資料模型(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"
      }
    }
  }
}

後續步驟

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

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