APIでの推奨値の管理
Experience Data Model （XDM）の任意の文字列フィールドに対して、フィールドが事前定義されたセットに取り込むことができる値を制限する enum を定義できます。 列挙フィールドにデータを取り込もうとし、値がその設定で定義されているどれにも一致しない場合、取り込みは拒否されます。
列挙とは対照的に、文字列フィールドに 推奨値 を追加しても、取り込み可能な値は制限されません。 代わりに、推奨される値は、文字列フィールドを属性として含める場合、 セグメント化UIで使用できる定義済みの値に影響します。
このガイドでは、Schema Registry 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"
}
列挙フィールドの場合、これらの制約の外の文字列値を取り込もうとしても検証を渡さないため、スキーマレジストリでは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を拡張するには、特定のスキーマで対象となるフィールドのわかりやすい名前の記述子を作成できます。
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未満の値が含まれている場合、記述子の新しい値は既存のフィールドを上書きせず、代わりに次の場所に追加されます。| 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でのカスタムフィールドの定義に関するガイドを参照してください。