Utiliser des mappages clé-valeur

Vous consultez la documentation Apigee Edge.
Accédez à la documentation Apigee X.

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 :

Pour en savoir plus sur les autres types de persistance, consultez Ajouter la mise en cache et la persistance.

Scénarios KVM

Voici quelques situations dans lesquelles les KVM peuvent s'avérer utiles :

  • 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 Key-Value Map Operations associée et de récupérer l'URL cible correcte à partir de l'un des KVM que vous avez créés. Ensuite, si une ou plusieurs de vos cibles changent, vous mettez simplement à jour les KVM avec les nouvelles URL. Le proxy récupère les nouvelles valeurs, et aucun redéploiement du proxy n'est requis.
  • Vous souhaitez stocker des identifiants, des clés privées ou des jetons, tels que des jetons pour des services externes, des identifiants nécessaires pour générer des jetons OAuth ou des clés privées utilisées dans des appels Java ou JavaScript pour le chiffrement ou la signature d'un jeton Web JSON (JWT, Json 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.

Les KVM ont un champ d'application

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 un seul proxy d'API nécessite des données dans un KVM, vous pouvez créer le KVM au niveau du champ d'application apiproxy, 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.

À propos des KVM 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.

Edge 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 Gérer et utiliser des KVM.)

Interface utilisateur Edge

Les mappages de clés-valeurs chiffrés affichent des valeurs masquées avec des astérisques dans l'interface utilisateur (*****). Par exemple :

API de gestion

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

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

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.

Limites

Dans les organisations pour lesquelles les Core Persistence Services (CPS) sont activés :

  • Le nom/identifiant KVM est sensible à la casse.
  • La taille de la clé est limitée à 2 Ko.
  • La taille de la valeur est limitée à 10 Ko.

Pour Apigee Edge pour Private Cloud, chaque KVM ne doit pas dépasser 15 Mo (taille combinée des clés et des valeurs). Si vous dépassez cette limite, Apigee Edge pour le cloud privé renvoie une erreur. Pour déterminer la taille de vos KVM, vous pouvez utiliser la commande nodetool cfstats.

Les KVM plus volumineux peuvent entraîner une dégradation des performances. Par conséquent, vous devez diviser les grandes KVM monolithiques en plus petites pour améliorer les performances.

Gérer et utiliser des KVM

Vous pouvez créer, gérer et utiliser des KVM de différentes manières. Cette section décrit différentes options permettant de créer, puis de récupérer des KVM chiffrées et non chiffrées.

Créer et mettre à jour des KVM

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

  • Règle KeyValueMapOperations (sans chiffrement)

    Pour que vos proxys d'API puissent créer et mettre à jour un mappage clé-valeur dans l'environnement d'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.

  • API Management

    L'API Management permet de travailler avec les KVM en tant qu'administrateur plutôt que pendant l'exécution dans vos proxys d'API. Par exemple, vous pouvez disposer d'un script interne qui utilise l'API Management pour supprimer et recréer des KVM dans un environnement de test, ou vous pouvez vouloir réinitialiser la valeur d'une clé dans un KVM pour que tous les proxys la récupèrent. (Pour manipuler les KVM au moment de l'exécution, utilisez la règle KeyValueMapOperations dans vos proxys.)

    L'API de gestion des mappages clé-valeur vous permet de créer, de mettre à jour et de supprimer des KVM et des clés/valeurs chiffrés à tous les niveaux (organisation, environnement et proxy d'API).

    Pour créer un mappage clé-valeur chiffré avec l'API de gestion, 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 KVM existant.

  • Interface utilisateur de gestion

    Dans l'interface utilisateur de gestion Edge, vous pouvez créer et mettre à jour des KVM à l'échelle de l'environnement, qui sont les seuls KVM qui s'affichent dans l'interface utilisateur. L'interface utilisateur de gestion est un bon moyen d'administrer manuellement les données KVM pour les proxys d'API au moment de l'exécution. Pour en savoir plus, consultez Créer et modifier des mappages clé-valeur d'environnement.

Récupérer des mappages clé-valeur

Vous récupérez les mappages clé-valeur chiffrés et non chiffrés de la même manière, avec une légère différence lorsque vous les récupérez avec la règle des opérations de mappage clé-valeur.

  • Règle : utilisez l'élément <Get> dans la règle KeyValueMapOperations pour récupérer les KVM chiffrées et non chiffrées. La seule petite différence concerne la récupération des valeurs chiffrées avec la règle. Vous devez ajouter 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.
  • API de gestion : pour la gestion administrative, vous pouvez utiliser Créer et modifier des mappages clé-valeur d'environnement pour obtenir des KVM et des clés/valeurs. Par exemple, si vous souhaitez sauvegarder des KVM en obtenant et en stockant les définitions JSON, utilisez l'API Management. Toutefois, sachez que les valeurs chiffrées sont affichées sous la forme ***** dans la réponse de l'API.
  • Interface utilisateur de gestion : vous pouvez afficher vos KVM à l'échelle de l'environnement dans l'interface utilisateur de gestion en accédant à API > Configuration de l'environnement > Mappages clé-valeur (Edge classique) ou Administrateur > Environnements > Mappages clé-valeur (nouvel Edge).

Exemple de KVM

Pour obtenir un exemple d'utilisation d'un KVM pour renseigner des valeurs dans une URL, consultez Créer un modèle d'URL cible avec un KVM par environnement.