Utiliser des mappages clé-valeur

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

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 de mappage clé-valeur

Voici quelques situations dans lesquelles les mappages clé-valeur peuvent être 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 Opérations de mappage clé-valeur 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.
• Vous souhaitez stocker des identifiants, des clés privées ou des jetons, tels que les jetons des services externes services, 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.

Les mappages clé-valeur 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 mappage clé-valeur, vous pouvez créer le mappage clé-valeur 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.

À 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.

Edge gère l'affichage des valeurs chiffrées de la manière suivante. (Pour en savoir plus sur la création de mappages clé-valeur chiffrés, consultez Gérer et utiliser des mappages clé-valeur.)

Interface utilisateur Edge

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

API de gestion

Dans l'API de gestion, 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 Opérations de mappage clé-valeur 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 services Core Persistence Services (CPS) sont activés :

• Le nom/identifiant du mappage clé-valeur 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 le cloud privé, chaque mappage clé-valeur 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 mappages clé-valeur, vous pouvez utiliser la commande nodetool cfstats.

Les mappages clé-valeur plus volumineux peuvent entraîner une dégradation des performances. Par conséquent, vous devez diviser les mappages clé-valeur volumineux et monolithiques en mappages plus petits pour améliorer les performances.

Gérer et utiliser des mappages clé-valeur

Vous pouvez créer, gérer et utiliser des mappages clé-valeur de différentes manières. Cette section décrit différentes options pour créer, puis récupérer des mappages clé-valeur chiffrés et non chiffrés.

Créer et mettre à jour des mappages clé-valeur

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

• Règle Opérations de mappage clé-valeur (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 Opérations de mappage clé-valeur. (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 <Put> éléments dans une règle de mappage clé-valeur.

• API de gestion

  L'API de gestion permet d'utiliser des mappages clé-valeur en tant qu'administrateur plutôt que lors de 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 mappages clé-valeur dans un environnement de test, ou vous pouvez réinitialiser la valeur d'une clé dans un mappage clé-valeur pour que tous les proxys la récupèrent. (Pour manipuler les mappages clé-valeur lors de l'exécution, utilisez la règle Opérations de mappage clé-valeur dans vos proxys).

  L'API de gestion des mappages clé-valeur vous permet de créer, de mettre à jour et de supprimer des mappages clé-valeur chiffrés et des clés/valeurs à 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 mappage clé-valeur existant.

• Interface utilisateur de gestion

  Dans l'interface utilisateur de gestion Edge, vous pouvez créer et mettre à jour des mappages clé-valeur au niveau de l'environnement, qui sont les seuls mappages clé-valeur qui s'affichent dans l'interface utilisateur. L'interface utilisateur de gestion est un bon moyen d'administrer manuellement les données de mappage clé-valeur pour les proxys d'API lors 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 variation lors de la récupération avec la règle Opérations de mappage clé-valeur.

• Règle : utilisez l'élément <Get> dans la règle Opérations de mappage clé-valeur pour récupérer les mappages clé-valeur chiffrés et non chiffrés. La seule légère différence est la récupération des valeurs chiffrées avec la règle, où 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 Management : à des fins de gestion administrative, vous pouvez utiliser Créer et modifier des mappages clé-valeur d'environnement pour obtenir des mappages clé-valeur et des clés/valeurs. Par exemple, si vous souhaitez sauvegarder des mappages clé-valeur en obtenant et en stockant les définitions JSON, utilisez l'API de gestion. Sachez toutefois que les valeurs chiffrées s'affichent sous la forme ***** dans la réponse de l'API.
• Interface utilisateur de gestion : vous pouvez afficher vos mappages clé-valeur au niveau de l'environnement dans l'interface utilisateur de gestion en accédant à APIs > Environment Configuration > Key Value Maps (API > Configuration de l'environnement > Mappages clé-valeur) (Classic Edge) ou Admin > Environments > Key Value Maps (Administration > Environnements > Mappages clé-valeur) (New Edge).

Exemple de mappage clé-valeur

Pour obtenir un exemple d'utilisation d'un mappage clé-valeur pour renseigner des valeurs dans une URL, consultez Modéliser l'URL cible avec un mappage clé-valeur par environnement.