Utiliser des mappages clé-valeur

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur 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 Ajoutez 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 URL d'appel de service) dans un test et une autre URL cible dans un environnement de production. Au lieu de coder en dur les URL dans votre proxy, vous pouvez le configurer pour qu'il détecte l'environnement dans lequel il se trouve, exécute la clé stratégie Opérations de mappage de valeurs et récupérez l'URL cible correcte de l'une des KVM que vous créé. 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 de proxy n'est requis.
  • Vous souhaitez stocker des identifiants, des clés privées ou des jetons, tels que des jetons les identifiants requis pour générer des jetons OAuth ou des clés privées utilisé dans Java Calls, JavaScript pour le chiffrement ou la signature des 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 une KVM, vous pouvez créer la KVM au niveau 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.

<ph type="x-smartling-placeholder">

À 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. Pour en savoir plus sur la création de KVM chiffrées, consultez la page Gérer et utiliser des KVM.

Interface utilisateur périphérique

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

API de gestion

Dans l'API de gestion, les valeurs chiffrées sont renvoyées de manière masquée. Voici un exemple de gestion Réponse de l'API lors d'un appel KVM chiffré:

{
  "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 valeurs clés pour récupérer les valeurs KVM chiffrées, vous indiquez le nom d'une variable permettant de stocker le . Pour obtenir une valeur chiffrée, vous devez ajouter "private." au préfixe qui empêche les clés-valeurs KVM d'apparaître dans les sessions de trace et de débogage.

Limites

Dans les organisations avec Noyau Services de persistance (CPS) activés:

  • Le nom/l'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 for 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 données des VM 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 des options pour créer, puis récupérer des KVM chiffrés et non chiffrés.

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 sur les opérations de mappage de valeurs clés (aucun chiffrement)

    Pour créer et mettre à jour les KVM de l'environnement d'exécution par vos proxys d'API, utilisez la classe Règle sur les opérations de mappage de valeurs clés. (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 de travailler avec les KVM en tant qu'administrateur plutôt que pendant l'exécution dans vos mandataires d'API. Par exemple, vous pouvez avoir un script interne qui utilise le gestionnaire API pour supprimer et recréer des KVM dans un environnement de test, ou réinitialiser la valeur d'une clé dans une KVM pour que tous les proxys puissent les récupérer. (Pour manipuler les KVM pendant l'exécution, utilisez la Règlement sur les opérations de mappage de valeurs clés dans vos mandataires).

    API de gestion des cartes clé-valeur vous permet de créer, mettre à jour et supprimer des KVM et des clés-valeurs chiffrées tous les niveaux 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 créez de l'IA générative. Vous ne pouvez pas chiffrer une KVM existante.

  • 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 les seules s'affiche dans l'interface utilisateur. L'UI de gestion est un bon moyen d'administrer manuellement les données KVM pour l'API proxys au moment de l'exécution. Consultez Créer et modifier des mappages clé-valeur d'environnement. pour en savoir plus.

Récupérer des mappages clé-valeur

Vous récupérez les mappages de clé-valeur chiffrés et non chiffrés de la même manière, avec une légère variation lors de la récupération à l'aide de la stratégie d'opérations de mappage de valeurs clés.

  • Règle: utilisez l'élément <Get> dans le Règlement sur les opérations de mappage de valeurs clés pour récupérer des KVM chiffrées et non chiffrées. La seule différence est Récupération des valeurs chiffrées avec la stratégie, où vous devez ajouter un "private." au nom de la variable qui contiendra la valeur récupérée, comme décrit dans le Obtenir la section des opérations du sujet de référence. Ce préfixe masque la valeur de Trace et de débogage des sessions pendant que vous déboguez les proxys d'API.
  • API Management: à des fins de gestion administrative, vous pouvez utiliser l'API Créer et modifier des mappages clé-valeur pour l'environnement pour obtenir des KVM et des clé-valeurs. Par exemple, si vous souhaitez sauvegarder les KVM en obtenant et en stockant les définitions JSON, utilisez l'API de gestion. Attention, ces 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 le tableau de bord en accédant à API > Configuration de l'environnement > Cartes de clés-valeurs (Edge classique) ou Admin > Environnements > Key Value Maps (New Edge).

Exemple de KVM

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