Gestion des valeurs suggérées dans l’API
Pour tout champ de chaîne dans le modèle de données d’expérience (XDM), vous pouvez définir une énumération qui limite les valeurs que le champ peut ingérer à un ensemble prédéfini. Si vous tentez d’ingérer des données dans un champ d’énumération et que la valeur ne correspond à aucune de celles définies dans sa configuration, l’ingestion sera refusée.
Contrairement aux énumérations, l’ajout de valeurs suggérées à un champ de chaîne ne limite pas les valeurs qu’il peut ingérer. Au lieu de cela, les valeurs suggérées affectent les valeurs prédéfinies disponibles dans l’ interface utilisateur de segmentation lors de l’inclusion du champ de chaîne en tant qu’attribut.
Ce guide explique comment gérer les valeurs suggérées à l’aide de l’ API Schema Registry. Pour savoir comment procéder dans l’interface utilisateur de Adobe Experience Platform, consultez le guide de l’interface utilisateur sur les énumérations et les valeurs suggérées.
Conditions préalables
Ce guide suppose que vous connaissez les éléments de la composition des schémas dans XDM et que vous savez utiliser l’API Schema Registry pour créer et modifier des ressources XDM. Si vous avez besoin d’une introduction, reportez-vous à la documentation suivante :
Il est également vivement recommandé de consulter les règles d’évolution pour les énumérations et les valeurs suggérées si vous mettez à jour des champs existants. Si vous gérez des valeurs suggérées pour les schémas qui participent à une union, consultez les règles de fusion des énumérations et des valeurs suggérées.
Composition
Dans l’API, les valeurs contraintes d’un champ enum sont représentées par un tableau enum, tandis qu’un objet meta:enum fournit des noms d’affichage conviviaux pour ces valeurs :
"exampleStringField": {
"type": "string",
"enum": [
"value1",
"value2",
"value3"
],
"meta:enum": {
"value1": "Value 1",
"value2": "Value 2",
"value3": "Value 3"
},
"default": "value1"
}
Pour les champs d’énumération, le registre des schémas ne permet pas d’étendre meta:enum au-delà des valeurs fournies sous enum, car toute tentative d’ingestion de valeurs de chaîne en dehors de ces contraintes ne serait pas validée.
Vous pouvez également définir un champ de chaîne qui ne contient pas de tableau enum et n’utilise que l’objet meta:enum pour représenter les valeurs suggérées :
"exampleStringField": {
"type": "string",
"meta:enum": {
"value1": "Value 1",
"value2": "Value 2",
"value3": "Value 3"
},
"default": "value1"
}
Comme la chaîne ne dispose pas d’un tableau enum pour définir des contraintes, sa propriété meta:enum peut être étendue pour inclure de nouvelles valeurs.
Ajout de valeurs suggérées à un champ standard add-suggested-standard
Pour étendre le meta:enum d’un champ de chaîne standard, vous pouvez créer un descripteur de nom convivial pour le champ en question dans un schéma particulier.
meta:enum d’un champ standard dans un schéma n’affecte pas les autres schémas qui utilisent le même champ standard.La requête suivante ajoute des valeurs suggérées au champ eventType standard (fourni par la classe XDM ExperienceEvent) pour le schéma identifié sous 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"
}
}
}'
Après l’application du descripteur, le registre des schémas répond avec ce qui suit lors de la récupération du schéma (réponse tronquée pour l’espace) :
{
"$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, les nouvelles valeurs du descripteur ne remplacent pas les champs existants et sont ajoutées à la place :| code language-json |
|---|
|
Gestion des valeurs proposées pour un champ personnalisé suggested-custom
Pour gérer l’ meta:enum d’un champ personnalisé, vous pouvez mettre à jour la classe parent, le groupe de champs ou le type de données du champ par le biais d’une requête de PATCH.
meta:enum d’un champ personnalisé affecte tous les autres schémas qui utilisent ce champ. Si vous ne souhaitez pas que les modifications se propagent entre les schémas, envisagez plutôt de créer une ressource personnalisée :La requête suivante met à jour le meta:enum d’un champ "niveau de fidélité" fourni par un type de données personnalisé :
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"
}
}
]'
Après avoir appliqué la modification, le registre des schémas répond avec ce qui suit lors de la récupération du schéma (réponse tronquée pour l’espace) :
{
"$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"
}
}
}
}
Étapes suivantes
Ce guide explique comment gérer les valeurs suggérées pour les champs de chaîne dans l’API Schema Registry. Pour plus d’informations sur la création de différents types de champs, consultez le guide sur la définition de champs personnalisés dans l’API .