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 enum qui limite les valeurs que le champ peut ingérer à un jeu 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 la variable 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 la méthode API Schema Registry. Pour savoir comment procéder dans l’interface utilisateur de Adobe Experience Platform, reportez-vous à la section 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 la section 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, reportez-vous à la section règles de fusion des énumérations et des valeurs proposées.
Composition
Dans l’API, les valeurs contraintes d’une enum est représenté par une enum tableau, lorsqu’un 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 n’autorise pas meta:enum à étendre au-delà des valeurs fournies sous enum, puisque 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 enum et utilise uniquement la variable meta:enum objet à indiquer valeurs suggérées:
"exampleStringField": {
"type": "string",
"meta:enum": {
"value1": "Value 1",
"value2": "Value 2",
"value3": "Value 3"
},
"default": "value1"
}
Puisque la chaîne n’a pas de enum tableau pour définir des contraintes, son meta:enum peut être étendue pour inclure de nouvelles valeurs.
Ajout de valeurs suggérées à un champ standard add-suggested-standard
Pour étendre la variable meta:enum d’un champ de chaîne standard, vous pouvez créer une 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 les valeurs suggérées à la norme eventType (fourni par la fonction 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 la variable 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 la variable 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. Consultez le guide sur la définition de champs personnalisés dans l’API pour plus d’informations sur la création de différents types de champ.