API での推奨値の管理

エクスペリエンスデータモデル (XDM) の任意の文字列フィールドに対して、 enum フィールドが取り込むことができる値を事前定義済みのセットに制限する データを列挙フィールドに取り込もうとしたが、その値が設定で定義された値と一致しない場合、取り込みは拒否されます。

列挙とは異なり、 推奨値 文字列フィールドに取り込み可能な値が制限されていない。 代わりに、推奨値は、 セグメント化 UI 文字列フィールドを属性として含める場合。

このガイドでは、 スキーマレジストリ API. Adobe Experience Platformユーザーインターフェイスでこれをおこなう手順については、 列挙と推奨値に関する UI ガイド.

前提条件

このガイドは、XDM のスキーマ構成の要素と、スキーマレジストリ API を使用して XDM リソースを作成および編集する方法について詳しいことを前提としています。 紹介が必要な場合は、次のドキュメントを参照してください。

• スキーマ構成の基本
• Schema Registry API ガイド

また、 列挙と推奨値の進化ルール 既存のフィールドを更新する場合。 和集合に参加するスキーマの推奨値を管理している場合は、 列挙と推奨値の結合ルール.

構成

API では、 enum フィールドは、 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 標準の文字列フィールドの わかりやすい名前記述子 特定のスキーマの問題になっているフィールドに対して。

次のリクエストでは、標準の 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"
      }
    }
  }
}

"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を使用すると、セグメント化で表示したくない値を無効にできます。 これは、 わかりやすい名前記述子 ( xdm:excludeMetaEnum プロパティ。

API 形式

POST /tenant/descriptors

リクエスト

次のリクエストでは、推奨値「Web Form Filled Out"および"Media ping」 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",
        "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
        "xdm:sourceVersion": 1,
        "xdm:sourceProperty": "/xdm:eventType",
        "xdm:excludeMetaEnum": {
          "web.formFilledOut": "Web Form Filled Out",
          "media.ping": "Media ping"
        }
      }'

応答

応答が成功すると、HTTP ステータス 201（作成済み）と、新しく作成された記述子の詳細が返されます。以下に含まれる推奨値 xdm:excludeMetaEnum がセグメント化 UI で非表示になるようになりました。

{
  "@type": "xdm:alternateDisplayInfo",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/xdm:eventType",
  "xdm:excludeMetaEnum": {
    "web.formFilledOut": "Web Form Filled Out"
  },
  "meta:containerId": "tenant",
  "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

カスタムフィールドの推奨値の管理

次の手順で meta:enum カスタムフィールドの場合は、PATCHリクエストを通じて、フィールドの親クラス、フィールドグループ、またはデータ型を更新できます。

次のリクエストは、 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 でのカスタムフィールドの定義 様々なフィールドタイプの作成方法の詳細については、を参照してください。

Business.Adobe.com リソース