Gérer les valeurs suggérées dans l’API

Pour tout champ de chaîne du 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 à aucun de ceux définis dans sa configuration, l’ingestion est 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 comme attribut.

Ce guide explique comment gérer les valeurs suggérées à l’aide de l’API Schema Registry. Pour savoir comment le faire 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 composition de schémas dans XDM et que vous savez comment utiliser l’API Schema Registry pour créer et modifier des ressources XDM. Reportez-vous à la documentation suivante si vous avez besoin d’une introduction :

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 les 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 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 les 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 passerait pas la validation.

Vous pouvez également définir un champ de chaîne qui ne contient pas de tableau enum et qui utilise uniquement l’objet meta:enum pour indiquer les valeurs suggérées :

"exampleStringField": {
  "type": "string",
  "meta:enum": {
    "value1": "Value 1",
    "value2": "Value 2",
    "value3": "Value 3"
  },
  "default": "value1"
}

Étant donné que 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.

Ajouter les valeurs suggérées à un champ standard add-suggested-standard

Pour étendre la 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.

La requête suivante ajoute les valeurs suggérées au champ de 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 les éléments suivants lors de la récupération du schéma (réponse tronquée pour des raisons d’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"
      }
    }
  }
}

"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"
   }
}

Gestion des valeurs suggérées pour un champ personnalisé suggested-custom

Pour gérer la meta:enum d’un champ personnalisé, vous pouvez mettre à jour la classe parente, le groupe de champs ou le type de données du champ par le biais d’une requête PATCH.

La requête suivante met à jour la 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 application de la modification, le registre des schémas répond avec les éléments suivants lors de la récupération du schéma (réponse tronquée pour des raisons d’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).