Utiliser les mappages clé-valeur

Vous consultez la documentation d'Apigee X.
Consultez la documentation d'Apigee Edge.

Cette section explique comment utiliser les mappages clé-valeur.

Aperçu

Vous avez parfois besoin de stocker des données pour les récupérer lors de l'exécution, à savoir des données qui n'expirent pas et qui ne devraient pas être codées en dur dans votre logique de proxy d'API. Les mappages clé-valeur sont idéaux pour cela. Un mappage clé-valeur est un ensemble personnalisé de paires de chaînes clé-valeur chiffrées ou non chiffrées. Voici deux exemples :

Les mappages clé-valeur ont trois cas d'utilisation généraux (cette liste n'est qu'un guide qui présente différentes manières d'utiliser les mappages clé-valeur) :

  • Données de session de l'utilisateur : données créées (et détruites) par l'environnement d'exécution. Les entrées de mappage clé-valeur peuvent être chiffrées ou non, sans possibilité d'afficher ou de gérer les entrées en dehors de l'environnement d'exécution, par exemple, le contenu d'un panier.
  • Configuration (telles que les règles de routage et la recherche de tables) : les données sont généralement créées en dehors de l'environnement d'exécution, mais elles sont lues par l'environnement d'exécution. Ces données sont fournies par l'UI ou l'API, puis mises à la disposition de la passerelle (en tant que variables et lecture seule).

    Prenons l'exemple suivant : vous disposez d'un proxy d'API qui doit appeler une URL cible (ou une accroche de service) dans un environnement de test et une autre URL cible dans un environnement de production. Au lieu de coder en dur les URL dans votre proxy, vous pouvez demander au proxy de détecter l'environnement dans lequel il se trouve, d'exécuter la règle KeyValueMapOperations et de récupérer l'URL cible correcte à partir de l'un des mappage clé-valeur que vous avez créés.

    Ensuite, si une ou plusieurs de vos cibles changent, vous mettez simplement à jour les mappages clé-valeur avec les nouvelles URL. Le proxy récupère les nouvelles valeurs, et aucun redéploiement du proxy n'est requis.

  • Identifiants : stockez les identifiants, les clés privées ou les jetons, tels que les jetons des services externes, les identifiants nécessaires pour générer des jetons OAuth, ou les clés privées utilisées dans les appels Java ou JavaScript pour le chiffrement ou la signature d'un jeton Web JSON (JWT, Jason Web Token). Au lieu de transmettre les identifiants, les clés ou les jetons dans la requête, ou de les coder en dur dans votre logique de proxy, vous pouvez les stocker dans un mappage clé-valeur (toujours chiffré) et les récupérer dynamiquement dans les appels aux cibles qui en ont besoin.

Vous découvrirez d'autres situations dans lesquelles le stockage de paires de chaînes clé-valeur peut être utile. En général, pensez à utiliser des mappages clé-valeur dans les cas suivants :

  • Des parties spécifiques du code nécessitent des valeurs différentes au moment de l'exécution.
  • Les données sensibles doivent être transmises sans les coder en dur.
  • Vous souhaitez stocker des valeurs qui n'expirent comme un cache le ferait.

Dans certains cas, les ensembles de propriétés constituent une bonne alternative aux mappages clé-valeur, car ils peuvent être plus faciles à utiliser. Pour en savoir plus, consultez la section Mise en cache.

À propos du champ d'application du mappage clé-valeur

Le champ d'application signifie "là où un mappage clé-valeur est disponible". Les mappages clé-valeur peuvent être créés aux niveaux suivants : organization, environment et apiproxy.

Par exemple, si des paires clé/valeur doivent être utilisées pour toutes les API d'une organisation, créez un mappage clé-valeur au niveau de l'organisation ; si seul un proxy d'API spécifique doit avoir accès à des clés/valeurs, créez le mappage clé-valeur au niveau du champ d'application du proxy d'API où seul ce proxy d'API peut accéder aux données.

Vous pouvez également souhaiter que tous les proxys d'API de votre environnement de test aient accès à un mappage clé-valeur. Dans ce cas, vous devez créer un mappage clé-valeur au niveau de l'environnement. Les proxys déployés dans l'environnement de production ne peuvent pas accéder aux mappages clé-valeur dans le champ d'application de l'environnement de test. Si vous souhaitez que les mêmes clés de mappage clé-valeur soient disponibles en production, créez un mappage clé-valeur parallèle associé à l'environnement de production.

Si vous souhaitez que tous les proxys de tous les environnements accèdent au même mappage clé-valeur, créez le mappage clé-valeur au niveau organization.

Utiliser des mappages clé-valeur

Pour créer et mettre à jour des mappages clé-valeur, vous pouvez procéder de différentes manières :

Utiliser des mappages clé-valeur avec l'UI d'Apigee

Vous pouvez utiliser l'UI d'Apigee pour effectuer les tâches suivantes liées aux mappages clé-valeur :

  • Afficher la liste des KVM dans un environnement
  • Créer une nouvelle KVM (vide)

Notez que les mappages clé-valeur de l'UI sont limitées à un environnement seulement.

Il n'est actuellement pas possible d'ajouter des données aux mappages clé-valeur (même ceux créés dans l'UI), de supprimer des mappages clé-valeur ni d'afficher des données dans des mappages clé-valeur à l'aide de l'UI d'Apigee. Vous devez utiliser les règles de mappage clé-valeur pour ajouter des données aux mappages clé-valeur.

Pour créer une nouvelle KVM (vide) ou afficher une liste de KVM :

  1. Ouvrez l'interface utilisateur Apigee dans un navigateur.
  2. Sélectionnez Admin > Environnements > Mappages clé-valeur.
  3. Dans la liste déroulante de l'environnement, sélectionnez l'environnement souhaité.

    La vue Key Value Maps (Mappages clé-valeur) affiche la liste des KVM existantes. Si vous n'avez pas créé de KVM, la liste des KVM est vide.

  4. Pour créer une KVM (vide), cliquez sur le bouton +Mappage clé-valeur dans l'angle supérieur droit.

    La boîte de dialogue Ajouter un mappage clé-valeur s'affiche :

    Ajouter un mappage clé-valeur dans l'UI

  5. Dans le champ Nom, saisissez un nom pour la KVM.

    Le nom ne peut contenir que des lettres, des chiffres et des traits d'union. Il ne peut pas inclure d'espaces ou d'autres caractères spéciaux. Par exemple, saisissez "my-kvm-1".

  6. (Obligatoire) Cochez la case Chiffré. Pour en savoir plus, consultez la section À propos des KVM chiffrées.
  7. Cliquez sur Ajouter.

    Apigee crée le nouveau mappage clé-valeur. Vous ne pouvez pas modifier la nouvelle KVM ni lui ajouter des données.

Utiliser des mappages clé-valeur avec les API Apigee

Vous pouvez utiliser les API Apigee pour créer, répertorier et supprimer des mappages clé-valeur pour les champs d'application suivants :

L'API Apigee /keyvaluemaps vous permet de créer et de supprimer des mappages clé-valeur à tous les champs d'application (organisation, environnement et proxy d'API). Vous ne pouvez pas ajouter de données ni mettre à jour des données de mappage clé-valeur à l'aide de l'API.

Pour créer un mappage clé-valeur chiffré avec l'API Apigee, ajoutez "encrypted":"true" à la charge utile JSON. Vous ne pouvez chiffrer les mappages clé-valeur que lorsque vous les créez. Vous ne pouvez pas chiffrer un mappage clé-valeur existant.

Utiliser des KVM avec la règle KeyValueMapOperations

Pour que vos proxys d'API puissent créer et mettre à jour un mappage clé-valeur dans l'environnement l'exécution, utilisez la règle KeyValueMapOperations (dans la règle, vous spécifiez le nom du mappage clé-valeur dans l'attribut mapIdentifier de l'élément parent).

L'élément <InitialEntries> permet de créer et de remplir un ensemble d'entrées de base dans un nouveau mappage clé-valeur dès que vous enregistrez la règle dans l'UI ou que vous déployez le proxy d'API (si vous l'avez développé hors connexion). Si les valeurs changent dans la règle, les valeurs existantes sont écrasées. Toutes les nouvelles clés-valeurs sont ajoutées au mappage clé-valeur existant, avec les clés-valeurs existantes.

L'élément <Put> crée un mappage clé-valeur s'il n'existe pas déjà et crée une clé avec une ou plusieurs valeurs. Si le mappage clé-valeur existe déjà, les clé-valeurs sont ajoutées (ou mises à jour si la clé existe déjà). Vous pouvez utiliser plusieurs éléments <Put> dans une règle de mappage clé-valeur.

Trace et débogage

Lorsque vous utilisez la règle KeyValueMapOperations pour récupérer des valeurs de mappage clé-valeur chiffrées, vous devez spécifier le nom d'une variable pour stocker la valeur. Pour obtenir une valeur chiffrée, vous devez ajouter le préfixe private. au nom de la variable. Ainsi, les clés/valeurs des mappages clé-valeur n'apparaissent pas dans les sessions Trace et débogage.

Récupérer des KVM

Pour récupérer des mappages clé-valeur chiffrés et non chiffrés, vous devez utiliser la règle KeyValueMapOperations. Utilisez l'élément <Get> de la règle pour récupérer les mappages clé-valeur chiffrés et non chiffrés. Pour récupérer des valeurs chiffrées avec la règle, ajoutez un préfixe private. au nom de la variable qui contiendra la valeur récupérée, comme décrit dans la section Élément "Get" du sujet de référence. Ce préfixe masque la valeur des sessions de trace et de débogage pendant que vous déboguez les proxys d'API.

À propos des mappages clé-valeur chiffrés

Les mappages clé-valeur chiffrés sont chiffrés par une clé de chiffrement AES-128 générée par Apigee. La clé utilisée pour chiffrer un mappage clé-valeur est stockée dans le champ d'application de celui-ci. Par exemple, dans une organisation, tous les mappages clé-valeur chiffrés que vous créez au niveau de l'environnement sont créés à l'aide de la même clé au niveau de l'environnement.

Apigee gère l'affichage des valeurs chiffrées de différentes manières (Pour en savoir plus sur la création de KVM chiffrées, consultez la page Utiliser des KVM.)

Dans l'API Apigee, les valeurs chiffrées sont renvoyées masquées. Voici un exemple de réponse d'API Apigee à un appel de mappage clé-valeur chiffré "Get" :

{
  "encrypted": true,
  "entry": [
    {
      "name": "Key1",
      "value": "*****"
    },
    {
      "name": "Key2",
      "value": "*****"
    }
  ],
  "name": "secretMap"
}