Utiliser des mappages clé-valeur

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X. en savoir plus

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 la section Ajouter la mise en cache et la persistance.

Scénarios KVM

Voici quelques situations dans lesquelles les KVM s'avèrent utiles:

  • Vous disposez d'un proxy d'API qui doit appeler une URL cible (ou d'appel 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 faire en sorte que celui-ci détecte son environnement, exécute la stratégie d'opérations de mappage de clés-valeurs associée et récupère l'URL cible appropriée à partir de l'une des KVM que vous avez créées. Par la suite, si l'une de vos cibles ou les deux changent, il vous suffit de mettre à jour les KVM avec les nouvelles URL. Le proxy récupère les nouvelles valeurs, et aucun redéploiement du proxy n'est nécessaire.
  • Vous souhaitez stocker des identifiants, des clés privées ou des jetons, tels que des jetons pour des services externes, des identifiants requis pour générer des jetons OAuth, ou des clés privées utilisées dans Java appels ou JavaScript pour le chiffrement ou la signature de jetons Web JSON (JWT). 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 la manière suivante. (Consultez la section Gérer et utiliser des KVM pour en savoir plus sur la création de KVM chiffrées.)

Interface utilisateur périphérique

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

API de gestion

Dans l'API de gestion, les valeurs chiffrées sont renvoyées et masquées. Voici un exemple de réponse de l'API de gestion pour un appel KVM "Obtenir le chiffrement" :

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

Trace et débogage

Lorsque vous utilisez la règle Opérations de mappage de clés-valeurs pour récupérer des valeurs KVM chiffrées, vous devez fournir le nom d'une variable qui la stockera. Pour obtenir une valeur chiffrée, vous devez ajouter le préfixe "private." au nom de la variable, ce qui empêche les clés/valeurs KVM d'apparaître dans les sessions de trace et de débogage.

Limites

Dans les organisations où les services de persistance principaux (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 (il s'agit de la taille combinée des clés et des valeurs). Si vous dépassez cette limite, Apigee Edge for Private Cloud renvoie une erreur. Pour déterminer la taille de vos KVM, vous pouvez utiliser la commande nodetool cfstats.

Des KVM plus volumineuses peuvent entraîner une dégradation des performances. Par conséquent, vous devez diviser les KVM volumineuses et monolithiques en plusieurs petites VM 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 et 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 concernant les opérations de mappage de clés-valeurs (pas de chiffrement)

    Pour créer et mettre à jour le KVM au moment de l'exécution par vos proxys d'API, utilisez la règle Opérations sur le mappage de clés-valeurs. (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 de gestion permet d'utiliser des 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 de gestion pour supprimer et recréer des KVM dans un environnement de test, ou vous pouvez avoir besoin de réinitialiser la valeur d'une clé dans un KVM pour que tous les proxys soient récupérés. (Pour manipuler des KVM lors de l'exécution, utilisez la règle Opérations de mappage de clés-valeurs dans vos proxys.)

    L'API de gestion des cartes clés/valeurs vous permet de créer, mettre à jour et supprimer des KVM et des clés/valeurs chiffrées, quel que soit le niveau d'accès (organisation, environnement et apiproxy).

    Pour créer une KVM chiffrée avec l'API de gestion, ajoutez "encrypted" : "true" à la charge utile JSON. Vous ne pouvez chiffrer les KVM que lorsque vous les créez. Vous ne pouvez pas chiffrer un KVM existant.

  • UI 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 le seul champ d'application de KVM qui apparaît 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 la section Créer et modifier des mappages de clé-valeur d'environnement.

Récupérer des mappages clé-valeur

Les mappages de clé-valeur chiffrés et non chiffrés sont effectués de la même manière, avec une légère variation lorsque vous effectuez une récupération à l'aide de la règle Opérations de mappage de clés-valeurs.

  • Règle: utilisez l'élément <Get> de la règle Opérations de mappage de clés-valeurs pour récupérer les KVM chiffrées et non chiffrées. La seule différence réside dans la récupération des valeurs chiffrées avec la règle. Vous devez ajouter le préfixe "private." au nom de la variable qui contiendra la valeur récupérée, comme décrit dans la section Opération "Obtenir" 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 des proxys d'API.
  • API Management: à des fins de gestion administrative, vous pouvez utiliser la page Créer et modifier des mappages de clé-valeur d'environnement pour obtenir les KVM et les clés/valeurs. Par exemple, si vous souhaitez sauvegarder des KVM en obtenant et en stockant les définitions JSON, utilisez l'API de gestion. Sachez toutefois que les valeurs chiffrées sont affichées sous la forme ***** dans la réponse de l'API.
  • UI de gestion: vous pouvez afficher vos KVM à l'échelle de l'environnement dans l'interface utilisateur de gestion en accédant à API > Environment Configuration > Key Value Maps (API > Configuration de l'environnement > Cartes clés-valeurs) ou Admin > Environments > Key Value Maps (Administration > Environnements > Cartes clés-valeurs) (New Edge).

Exemple KVM

Pour obtenir un exemple d'utilisation d'un KVM pour renseigner des valeurs dans une URL, consultez https://community.apigee.com/questions/32727/templatize-target-url-with-kvm-by-environment.html.