Utiliser les mappages clé-valeur

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d' Apigee Edge.

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

Présentation

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. Une instance KVM est une collection personnalisée de paires clé-valeur chiffrées.

Voici trois cas d'utilisation généraux pour le stockage de données dans KVM :

Données de session utilisateur : données créées et supprimées uniquement par l'environnement d'exécution ; vous ne pouvez pas afficher ni gérer des entrées KVM 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 configurées à l'aide de l'UI ou de l'API, puis mises à la disposition de la passerelle (en tant que variables ou contenu en 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 d'API, vous pouvez lui demander 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 du mappage clé-valeur approprié.

Ensuite, si une de vos cibles ou les deux changent, vous mettez simplement à jour les mappages clé-valeur avec les nouvelles URL. Le proxy d'API récupère les nouvelles valeurs, et aucun redéploiement 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 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 Utiliser des ensembles de propriétés.

À propos du champ d'application KVM

Le champ d'application définit les pays où un KVM est disponible. Les KVM peuvent être créées aux niveaux suivants :

Champ d'application	Description
proxy d'API	Seul le proxy d'API peut accéder au KVM.
Environnement	Tous les proxys d'API d'un environnement spécifique peuvent accéder au KVM. Par exemple, vous pouvez souhaiter que les proxys d'API déployés dans l'environnement `prod` n'aient pas accès aux KVM de l'environnement `test`. Si vous souhaitez que les mêmes clés KVM soient disponibles en production, créez un KVM parallèle limité à l'environnement `prod`.
Organisation	Tous les proxys d'API de tous les environnements peuvent accéder au KVM.

À propos du chiffrement KVM

Dans Apigee, toutes les entrées KVM pour le champ d'application de l'environnement, de l'organisation et du proxy d'API sont protégées par la clé Cloud KMS fournie lorsqu'une organisation Apigee est provisionnée (voir le champ runtimeDatabaseEncryptionKey de la ressource Organisation). Apigee utilise AES256 comme norme de chiffrement.

Dans Apigee hybrid, vous pouvez fournir des clés de chiffrement distinctes pour toutes les entrées KVM pour les champs d'application de proxy d'API, d'organisation et d'environnement. Apigee accepte les tailles de chiffrement AES128, AES196 ou AES256 en tant que norme de chiffrement.

Créer des KVM

Créez des KVM comme décrit dans les sections suivantes.

Apigee dans la console Cloud

Pour créer un nouveau KVM (vide) ou afficher une liste des KVM :

Ouvrez l'interface utilisateur d'Apigee dans la console Cloud dans un navigateur.
Dans le volet de navigation de gauche, cliquez sur Gestion > Environnements.
Sélectionnez dans la liste des environnements disponibles celui que vous souhaitez modifier.
Cliquez sur l'onglet Mappages clé-valeur sur la page Détails de l'environnement.
La page Mappages clé-valeur affiche la liste des KVM existantes. Si vous n'avez créé aucun KVM, la liste est vide.
Pour créer un KVM (vide), cliquez sur + Créer un mappage clé-valeur.
La boîte de dialogue Ajouter un mappage clé-valeur s'affiche.
Saisissez un nom pour le KVM dans le champ Nom du mappage clé-valeur.
Ce nom ne peut contenir que des lettres, des chiffres et des traits d'union, et ne peut pas dépasser 255 caractères. Il ne peut pas inclure d'espaces ou d'autres caractères spéciaux. Par exemple : my-kvm-1
Cliquez sur Créer.
Le nouveau KVM est affiché dans la liste.

Interface utilisateur classique d'Apigee

Pour créer un nouveau KVM (vide) ou afficher une liste des KVM :

Connectez-vous à l'UI Apigee.
Sélectionnez Admin > Environnements > Mappages clé-valeur.
Dans la liste déroulante Environnement, sélectionnez l'environnement pour lequel vous souhaitez créer un KVM.
La page Mappages clé-valeur affiche la liste des KVM existantes. Si vous n'avez créé aucun KVM, la liste est vide.
Pour créer un KVM (vide), cliquez sur + Mappage clé-valeur.
La boîte de dialogue Ajouter un mappage clé-valeur s'affiche.
Saisissez un nom pour le KVM dans le champ Nom.
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 : my-kvm-1
Cliquez sur Ajouter.
Le nouveau KVM est affiché dans la liste.

API Apigee

Utilisez les API Apigee pour créer, répertorier et supprimer des KVM pour les champs d'application suivants :

Règle KVM

Pour créer des KVM au moment de l'exécution et les mettre à jour dans vos proxys d'API, utilisez la règle KeyValueMapOperations. Dans la règle, vous spécifiez le nom du KVM 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. Les nouvelles paires clé-valeur sont ajoutées au KVM existant avec les paires clé-valeur 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 KVM existe déjà, les paires clé-valeur 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.

Déboguer

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. Comme toutes les valeurs KVM sont chiffrées, vous devez ajouter le préfixe private. au nom de la variable, ce qui empêche les paires clé/valeur KVM d'apparaître dans les sessions Debug.

Récupérer des mappages clé-valeur

Récupérez les KVM à l'aide de l'élément <Get> de la règle KeyValueMapOperations. Étant donné que toutes les valeurs KVM sont chiffrées, ajoutez un préfixe private. au nom de la variable qui contiendra la valeur récupérée. Ce préfixe masque la valeur des sessions de débogage pendant le débogage des proxys d'API. Pour plus d'informations, consultez la section Élément <Get>.

Supprimer des KVM

Supprimez des KVM comme décrit dans les sections suivantes.