API での推奨値の管理
エクスペリエンスデータモデル（XDM）の任意の文字列フィールドについて、フィールドが取り込むことができる値を事前定義済みのセットに制限する enum を定義できます。 列挙フィールドにデータを取り込もうとすると、その値が設定で定義されている値と一致しない場合、取り込みは拒否されます。
列挙とは異なり、文字列フィールドに 推奨値 を追加しても、取り込むことができる値は制限されません。 代わりに、文字列フィールドを属性として含める場合、推奨値は、 セグメント化 UI で使用できる事前定義済みの値に影響を与えます。
このガイドでは、 スキーマレジストリ API を使用して推奨値を管理する方法について説明します。 Adobe Experience Platform ユーザーインターフェイスでこれを行う手順については、UI ガイドの列挙と推奨値 を参照してください。
前提条件
このガイドは、XDM でのスキーマ構成の要素と、Schema Registry API を使用して XDM リソースを作成および編集する方法について理解していることを前提としています。 説明が必要な場合は、次のドキュメントを参照してください。
既存のフィールドを更新する場合は、 列挙と推奨値の進化ルール を確認することを強くお勧めします。 結合に参加するスキーマの推奨値を管理している場合は、 列挙と推奨値の結合ルール を参照してください。
構成
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"
}
列挙フィールドの場合、スキーマレジストリでは、enum で指定された値を超えて meta: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 を拡張するには、特定のスキーマで問題となっているフィールドに わかりやすい名前記述子 を作成します。
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"
}
}
}
}
meta:enum に既に値が含まれている場合、記述子からの新しい値は既存のフィールドを上書きせず、代わりにに追加されます。| code language-json |
|---|
|
カスタムフィールドの推奨値の管理 suggested-custom
カスタムフィールドの 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"
}
}
}
}
次の手順
このガイドでは、Schema Registry API の文字列フィールドの推奨値を管理する方法について説明しました。 様々なフィールドタイプの作成方法について詳しくは、API でのカスタムフィールドの定義 に関するガイドを参照してください。