Règle KeyValueMapOperations

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

Consultez la documentation d'Apigee Edge.

Événement

Fournit un accès basé sur les règles à un magasin de mappage clés-valeurs (KVM) disponible dans Apigee. Les paires clé/valeur peuvent être stockées, récupérées et supprimées des mappages existants en configurant des règles KeyValueMapOperations spécifiant les opérations PUT, GET ou DELETE, respectivement. (Au moins une de ces opérations doit être exécutée par la règle).

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

Remarque : À partir de la sortie de la version 1.4.0 d'Apigee hybrid, Apigee chiffre par défaut tous les KVM. Utilisez l'attribut private. avec toutes les variables lorsque vous accédez à un KVM avec la commande GET pour masquer les informations du KVM dans une session Debug. Si l'attribut private. n'est pas utilisé, le KVM est toujours chiffré. Toutefois, ses informations apparaissent déchiffrées dans la session de Debug et aucune exception ne sera générée.

Vidéo : la vidéo suivante offre une présentation générale des KVM.

Exemples

Mettre à jour KVM avec un littéral

Lorsque la règle suivante s'exécute, elle crée un KVM chiffré nommé FooKVM, puis une clé nommée FooKey_1 avec deux valeurs définies à l'aide des chaînes littérales foo etbar (non définies avec les valeurs extraites des variables). Lorsque vous obtenez (GET) la clé dans l'exemple suivant, vous spécifiez un numéro d'index pour récupérer la valeur souhaitée.

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="FooKVM" mapIdentifier="FooKVM">
  <DisplayName>FooKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Put>
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
    <Value>foo</Value>
    <Value>bar</Value>
  </Put>
</KeyValueMapOperations>

Notez que le champ d'application est environment. Cela signifie que vous pouvez voir le KVM dans l'interface utilisateur de gestion sous APIs > Environment Configuration > Key Value Maps (API > Configuration de l'environnement > Mappages clé-valeur). Le champ d'application de tous les KVM affichés sur cette page correspond à l'environnement sélectionné.

Obtenir (GET) un KVM à partir d'un littéral

Cette règle tient compte du mappage FooKVM de l'exemple précédent, obtient la deuxième valeur (index = "2") de la clé FooKey_1 et la stocke dans une variable appelée foo_variable.

<KeyValueMapOperations mapIdentifier="FooKVM" async="false" continueOnError="false" enabled="true" name="GetKVM">
  <DisplayName>GetKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Get assignTo="foo_variable" index="2">
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

Accéder à un KVM de manière dynamique

Cette règle utilise l'élément <MapName> pour référencer dynamiquement un KVM avec une variable de flux. L'élément obtient l'identifiant KVM à partir de la variable de flux. Notez que l'attribut mapIdentifier est omis. Vous ne pouvez pas utiliser <MapName> avec l'attribut mapIdentifier.

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="GetKVM">
  <DisplayName>GetKVM</DisplayName>
  <MapName ref="flow.variable"/>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Get assignTo="foo_variable" index="2">
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

Mettre à jour KVM avec une variable

Un exemple simple de KVM utile est un service de raccourcissement d'URL. Le KVM peut être configuré pour stocker des URL raccourcies ainsi que les URL complètes correspondantes.

Cet exemple de règle crée un KVM. La règle utilise la commande PUT pour insérer une clé à deux valeurs dans un KVM nommé urlMapper.

<KeyValueMapOperations name="putUrl" mapIdentifier="urlMapper">
  <Scope>apiproxy</Scope>
  <Put override="true">
    <Key>
      <Parameter ref="urlencoding.requesturl.hashed"/>
    </Key>
    <Value ref="urlencoding.longurl.encoded"/>
    <Value ref="request.queryparam.url"/>
  </Put>
</KeyValueMapOperations>

Dans cet exemple, la clé urlencoding.requesturl.hashed est un exemple de variable personnalisée. L'URL de requête hachée est générée par le code (JavaScript ou Java, par exemple), puis stockée dans cette variable, via laquelle la règle KeyValueMapOperations peut y accéder.

Pour chaque clé, requesturl.hashed, deux valeurs sont stockées :

• Le contenu de la variable personnalisée nommée urlencoding.longurl.encoded
• Le contenu de la variable prédéfinie nommée request.queryparam.url

Par exemple, lorsque la règle s'exécute au moment de l'exécution, les valeurs des variables peuvent être comme suit :

• urlencoding.requesturl.hashed: ed24e12820f2f900ae383b7cc4f2b31c402db1be
• urlencoding.longurl.encoded: http://tinyurl.com/38lwmlr
• request.queryparam.url: http://apigee.com

Le KVM et l'entrée suivants sont générés dans le magasin de clés-valeurs d'Apigee et appliqués au proxy d'API auquel la règle est associée :

{
    "entry" :[
        {
            "name" : "ed24e12820f2f900ae383b7cc4f2b31c402db1be",
            "value" : "http://tinyurl.com/38lwmlr,http://apigee.com"
        }
    ],
    "name" : "urlMapper"
}

L'entrée est conservée jusqu'à ce qu'elle soit supprimée. Les entrées du magasin de clés-valeurs sont réparties sur des instances Apigee qui exécutent le cloud.

Obtenir KVM à partir d'une variable

Un exemple simple de KVM utile est un service de raccourcissement d'URL. Le KVM peut être configuré pour stocker des URL raccourcies ainsi que les URL complètes correspondantes.

Pour récupérer la valeur de l'entrée KVM telle que celle décrite dans l'onglet PUTde KeyValueMapOperations, configurez une règle pour obtenir (GET) le KVM :

<KeyValueMapOperations name="getUrl" mapIdentifier="urlMapper">
  <Scope>apiproxy</Scope>
  <Get assignTo="urlencoding.shorturl" index='1'>
    <Key>
      <Parameter ref="urlencoding.requesturl.hashed"/>
    </Key>
  </Get>
</KeyValueMapOperations>

Lorsque cette règle est exécutée, si la valeur de la variable urlencoding.requesturl.hashed est ed24e12820f2f900ae383b7cc4f2b31c402db1be, la variable personnalisée nommée urlencoding.shorturl prend la valeur http://tinyurl.com/38lwmlr.

Maintenant que les données ont été récupérées, d'autres règles et code peuvent y accéder en extrayant la valeur de ces variables.

Valeur GET à partir d'un KVM

Utilisez l'attribut private. avec toutes les variables lorsque vous accédez à un KVM avec la commande GET pour masquer les informations du KVM dans une session Debug. Si l'attribut private. n'est pas utilisé, le KVM est toujours chiffré. Toutefois, ses informations apparaissent déchiffrées dans la session Debug et aucune exception ne sera générée.

Dans cet exemple, la variable private.encryptedVar contient la valeur déchiffrée de la clé foo du KVM.

<KeyValueMapOperations name="getEncrypted" mapIdentifier="encrypted_map">
  <Scope>apiproxy</Scope>
  <Get assignTo="private.encryptedVar" index='1'>
    <Key>
      <Parameter>foo</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

Maintenant que les données ont été récupérées, d'autres règles et code peuvent y accéder en extrayant la valeur de cette variable.

<KeyValueMapOperations>

Fournit un accès basé sur des règles à un mappage clés-valeurs (KVM).

Syntaxe

<KeyValueMapOperations async="false" continueOnError="false"
    enabled="true" name="Key-Value-Map-Operations-1"
    mapIdentifier="urlMapper" >
  <DisplayName>Key Value Map Operations 1</DisplayName>
  <Scope>environment</Scope>
  <ExpiryTimeInSecs>300</ExpiryTimeInSecs>
  <InitialEntries>
    <Entry>
      <Key>
        <Parameter>KEY_NAME_LITERAL</Parameter>
      </Key>
      <Value>VALUE_LITERAL</Value>
    </Entry>
    <Entry>
      <Key>
         <Parameter>KEY_NAME_LITERAL</Parameter>
      </Key>
      <Value>VALUE_LITERAL</Value>
      <Value>VALUE_LITERAL</Value>
    </Entry>
  </InitialEntries>
  <Put override="BOOLEAN">
    <Key>
       <Parameter>KEY_NAME_LITERAL</Parameter>
    </Key>
  </Put>
  <Get assignTo="VARIABLE_NAME" index="INDEX_NUMBER">
    <Key>
       <Parameter>KEY_NAME_LITERAL</Parameter>
    </Key>
  </Get>
  <Delete>
    <Key>
       <Parameter>KEY_NAME_LITERAL</Parameter>
    </Key>
  </Delete>
</KeyValueMapOperations>

Attributs <KeyValueMapOperations>

L'exemple suivant montre les attributs de l'élément <KeyValueMapOperations> :

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="Key-Value-Map-Operations-1" mapIdentifier="map_name">

Le tableau suivant décrit les attributs de l'élément <KeyValueMapOperations> :

Remarque : L'attribut mapIdentifier spécifie le nom du KVM avec lequel vous souhaitez interagir. Vous pouvez également spécifier un KVM de manière dynamique avec l'élément <MapName>.

Attribut	Description	Par défaut	Présence
mapIdentifier	Spécifie un identifiant qui indique à la règle à quel KVM elle doit accéder. Si cet identifiant et <MapName> sont tous deux manquants, un KVM nommé kvmap est utilisé. Vous ne pouvez pas utiliser cet attribut si vous spécifiez l'élément <MapName>.	N/A	Facultatif

Le tableau suivant décrit les attributs communs à tous les éléments parents des règles :

Attribut	Description	Par défaut	Présence
name	Nom interne de la règle. La valeur de l'attribut name peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères. Vous pouvez également utiliser l'élément <DisplayName> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion, en utilisant un nom différent, en langage naturel.	N/A	Obligatoire
continueOnError	Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles. Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir également : Les règles d'erreur sont déclenchées UNIQUEMENT en état d'erreur (à propos de continueOnError) Gérer les pannes dans le flux actuel	faux	Facultatif
enabled	Définissez sur true pour appliquer la règle. Définissez sur false pour désactiver la règle. La stratégie ne sera pas appliquée, même si elle reste associée à un flux.	vrai	Facultatif
async	Cet attribut est obsolète.	faux	Obsolète

Élément <DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent, en langage naturel.

<DisplayName>Policy Display Name</DisplayName>

Par défaut	N/A Si vous omettez cet élément, la valeur de l'attribut name de la règle est utilisée.
Présence	Facultatif
Type	Chaîne

Éléments enfants

Cette section décrit les éléments et les attributs de la règle KeyValueMapOperations :

Élément <Delete>

Supprime la paire clé/valeur spécifiée. Vous devez utiliser au moins l'une des options <Get>, <Put> ou <Delete>.

Veillez à spécifier le nom du KVM avec l'attribut mapIdentifier sur l'élément racine ou avec l'élément <MapName>. Exemple :

<Delete>
   <Key>
      <Parameter>KEY_NAME_LITERAL</Parameter>
   </Key>
</Delete>

Par défaut	N/A
Présence	Obligatoire si <Get> ou <Put> ne sont pas présents.
Type	N/A

Élément <Entry>

Valeurs sources des KVM insérées dans le KVM lors de son initialisation. Pour Apigee, la taille de la clé est limitée à 2 Ko.

Exemple :

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>KEY_NAME_LITERAL</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>key_name_variable</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

Par défaut	N/A
Présence	Facultatif
Type	N/A

Élément <ExclusiveCache>

Obsolète. Utilisez plutôt l'élément <Scope>.

Élément <ExpiryTimeInSecs>

Spécifie la durée, en secondes, après laquelle Apigee actualise sa valeur mise en cache à partir du KVM spécifié.

Une valeur de 0 ou -1, ou excluant cet élément, signifie que la valeur par défaut de 300 secondes est utilisée. Exemple :

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

Par défaut	300 (5 minutes)
Présence	Facultatif
Type	Entier

Un KVM est un mécanisme de persistance à long terme qui stocke des clés et des valeurs dans une base de données NoSQL. De ce fait, la lecture à partir d'un KVM au moment de l'exécution peut ralentir les performances du proxy. Pour améliorer les performances, Apigee dispose d'un mécanisme intégré permettant de mettre en cache les clés-valeurs du KVM en mémoire pendant l'exécution. Cette règle d'opération KVM lit toujours à partir du cache dans le cas d'opérations GET.

L'élément <ExpiryTimeInSecs> vous permet de contrôler la durée pendant laquelle les clés-valeurs utilisées dans la règle sont stockées dans le cache avant d'être actualisées à partir du KVM. Cependant, il existe certaines différences dans la manière dont les opérations GET et PUT affectent l'expiration du cache.

GET – La première fois qu'une opération GET de KVM s'exécute, les clés/valeurs demandées à partir du KVM (dont le nom est spécifié dans l'attribut mapIdentifier à la racine de la règle ou par l'élément <MapName>) sont chargées dans le cache, où elles demeurent lors des opérations GET suivantes, jusqu'à ce que l'un des événements suivants se produise :

• Le nombre de secondes spécifié dans <ExpiryTimeInSecs> expire.
  ou
• Une opération PUT dans une règle KVM écrase les valeurs existantes (expliquées ci-dessous).

PUT : une opération PUT écrit des clés-valeurs sur le KVM spécifié. Si l'objet PUT écrit dans une clé déjà présente dans le cache, ce cache est immédiatement actualisé et conserve la nouvelle valeur durant le nombre de secondes spécifié dans l'élément <ExpiryTimeInSecs> de la règle. Toutefois, l'utilisation de PUT permet d'actualiser uniquement le cache dans le nœud d'exécution unique qui traite la requête. Pour actualiser le cache dans chaque nœud d'exécution distribué, utilisez l'élément <ExpiryTimeInSecs> afin de spécifier des intervalles d'actualisation pour chaque nœud.

Exemple – Mise en cache d'un KVM

1. Une opération GET récupère la valeur de "rating", qui ajoute la valeur "10" au cache. La valeur <ExpiryTimeInSecs> de la règle est de 60.
2. 30 secondes plus tard, la règle GET s'exécute à nouveau et récupère 10 à partir du cache.
3. 5 secondes plus tard, une règle PUT remplace la valeur de rating par 10, et la valeur <ExpiryTimeInSecs> de la règle PUT est définie sur 20. Le cache est immédiatement actualisé avec la nouvelle valeur, qui est maintenant définie pour rester dans le cache pendant 20 secondes. (Si l'opération PUT n'avait pas eu lieu, le cache initialement inséré par la première opération GET existerait pendant 30 secondes supplémentaires, quantité restante des 60 secondes d'origine.)
4. 15 secondes plus tard, un autre GET s'exécute et récupère la valeur 8.

Remarques

• Pour des performances optimales, équilibrez le délai d'expiration du cache avec le volume de trafic de l'API attendu. En cas de trafic important, par exemple, vous pouvez définir des intervalles d'expiration de cache plus longs pour éviter les actualisations fréquentes de la base de données.
• Il est impossible de réinitialiser manuellement le cache KVM. Toutefois, vous pouvez créer une règle temporaire qui exécute une opération PUT unique dotée d'un <ExpiryTimeInSecs> bref. Cette action réinitialisera le cache, qui contient la valeur PUT, après le nombre de secondes spécifié.
• La mise à jour d'un KVM avec l'interface utilisateur ou l'API Apigee ne réinitialise pas le cache KVM.
• Vous pouvez utiliser plusieurs opérations dans la même règle. Dans ce cas, la règle exécute les opérations dans l'ordre. Si vous utilisez un PUT suivi de GET dans la même règle à l'aide de la même clé, l'opération PUT, lorsqu'elle écrit, réinitialise implicitement le délai d'expiration du cache.

Élément <Get>

Récupère la valeur de la clé spécifiée. Vous devez utiliser au moins l'une des options <Get>, <Put> ou <Delete>.

Apigee chiffre toutes les données stockées dans le KVM. Pour en savoir plus, consultez la page À propos des clés de chiffrement. Lorsque vous utilisez <Get>, Apigee déchiffre les données stockées et les attribue à une variable dans le contexte du message. Le nom de la variable est spécifié à l'aide de l'attribut assignTo.

Veillez à spécifier le nom du KVM avec l'attribut mapIdentifier sur l'élément racine ou avec l'élément <MapName>.

Vous pouvez inclure plusieurs blocs Get dans la règle pour récupérer plusieurs éléments à partir d'un KVM.

Remarque : Vous pouvez utiliser plusieurs opérations dans la même règle. Dans ce cas, la règle exécute les opérations dans l'ordre. Si vous utilisez un PUT suivi de GET dans la même règle à l'aide de la même clé, l'opération PUT, lorsqu'elle écrit, réinitialise implicitement le délai d'expiration du cache. Pour en savoir plus, consultez la section qui traite de l'élément ExpiryTimeInSecs.

Par défaut	N/A
Présence	Obligatoire si <Put> ou <Delete> ne sont pas présents.
Type	N/A

Attributs

Le tableau suivant décrit les attributs de l'élément <Get> :

Attribut	Description	Par défaut	Présence
assignTo	La variable à laquelle la valeur récupérée doit être attribuée.	N/A	Obligatoire
index	Numéro d'index (dans un index basé sur 1) de l'élément à récupérer à partir d'une clé à valeurs multiples. Par exemple, si vous spécifiez index=1, vous obtenez la première valeur, qui est ensuite attribuée à la variable assignTo. Si aucune valeur d'index n'est spécifiée, toutes les valeurs de cette entrée sont attribuées à la variable sous forme de java.util.List. Vous trouverez un exemple sous l'onglet Obtenir une valeur à partir d'un KVM de la section Exemples.	N/A	Facultatif

Obtenir un seul élément à partir d'un KVM

Avec cet exemple de configuration d'étape, la règle lit et déchiffre la valeur d'une seule clé dans le KVM et attribue la valeur déchiffrée à une variable nommée myvar.

<Get assignTo="myvar" index="1">
  <Key>
    <Parameter>key_name_literal</Parameter>
  </Key>
</Get>

Exclure les données récupérées des sessions de débogage

Dans certains cas, les données stockées dans le KVM sont sensibles. Pour empêcher l'affichage des données récupérées dans une session de débogage, utilisez le préfixe private. dans le nom de la variable spécifié dans l'attribut assignTo. Si vous n'utilisez pas le préfixe private., les données extraites du KVM apparaissent en texte clair dans les sessions de débogage que vous créez.

Avec cet exemple de configuration d'étape, la règle lit et déchiffre la valeur associée à une seule clé dans le KVM et attribue cette valeur à une variable. L'attribution n'apparaîtra pas dans une session de débogage.

<Get assignTo="private.myvar" index="1">
  <Key>
    <Parameter>key_name_literal</Parameter>
  </Key>
</Get>

Obtenir plusieurs éléments à partir d'un KVM

Dans l'exemple suivant, supposons qu'un KVM dispose des clés et des valeurs suivantes. En plus de stocker une liste de diffusion des films les plus populaires de tous les temps, le KVM stocke le nom du réalisateur de tous les films majeurs.

Clé	Value
top_movies	Princess Bride, Le Parrain, Citizen Kane
Citizen Kane	Orson Welles
Princess Bride	Rob Reiner
Le Parrain	Francis Ford Coppola

Vous remarquerez que la valeur associée à la clé top_movies contient plusieurs noms de films, séparés par une virgule.

Avec cet exemple de configuration, la règle récupère le meilleur film actuel et le nom de son réalisateur :

<Get assignTo="top.movie.pick" index="1">
  <Key>
    <Parameter>top_movies</Parameter>
  </Key>
</Get>
<Get assignTo="movie.director">
  <Key>
    <Parameter ref="top.movie.pick"/>
  </Key>
</Get>

Lorsque le proxy d'API est appelé, Apigee crée les variables suivantes avec les valeurs correspondantes, qui peuvent être utilisées ultérieurement dans le flux de proxy d'API :

• top.movie.pick=Princess Bride
• movie.director=Rob Reiner

La valeur de top.movie.pick n'est que le premier élément de la liste d'éléments séparés par une virgule, car le premier élément <Get> utilise un attribut index de 1. Ensuite, le deuxième élément <Get> utilise la valeur attribuée à top.movie.pick comme clé pour récupérer une valeur dans movie.director.

Élément <InitialEntries>

Valeurs sources des KVM insérées dans le KVM lors de son initialisation. Veillez à spécifier le nom du KVM avec l'attribut mapIdentifier sur l'élément racine.

Remarque : L'élément <InitialEntries> n'est pas autorisé si l'élément <MapName> est utilisé.

Exemple :

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>KEY_NAME_LITERAL</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>KEY_NAME_VARIABLE</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

En utilisant cet élément, lorsque vous enregistrez la règle dans l'interface utilisateur d'Apigee sur une version déployée du proxy d'API ou que vous déployez le package du proxy d'API contenant la règle avec cet élément, la ou les clés sont automatiquement créées dans le KVM. Si les valeurs de la règle sont différentes de celles du KVM, les valeurs du KVM sont écrasées lors du déploiement du proxy d'API. Toutes les nouvelles clés-valeurs sont ajoutées au KVM existant, avec les clés-valeurs existantes.

Les clés et les valeurs renseignées par cet élément doivent être des littéraux. Par exemple, <Parameter ref="request.queryparam.key"> n'est pas accepté dans cet élément.

La taille de la clé est limitée à 2 Ko.

Par défaut	N/A
Présence	Facultatif
Type	N/A

Élément <Key>

Spécifie la clé dans une entrée KVM. Cet élément apparaît en tant qu'enfant de l'élément <Get>, <Put>, <Delete> ou <Entry> qui est un enfant de l'élément <InitialEntries>. Voici un exemple de clé fixe :

<Key>
  <Parameter>KEY_NAME_LITERAL</Parameter>
</Key>

Une clé peut être composite et dotée d'éléments dynamiques, ce qui signifie que plusieurs éléments <Parameter> peuvent être ajoutés afin de créer la clé. Par exemple, le contenu des variables userID et role peut être combiné pour créer une clé dynamique. Voici un exemple de configuration d'étape qui spécifie une clé composite déterminée de manière dynamique :

<Key>
  <Parameter ref='userID'/>
  <Parameter ref='role'/>
</Key>

Pour plus d'informations sur la définition du nom de la clé, consultez l'élément <Parameter>.

La taille de la clé est limitée à 2 Ko.

Remarque : Le nom ratelimit est réservé. Pour plus d'informations, consultez ce post destiné à la communauté Apigee.

Par défaut	N/A
Présence	Facultatif
Type	N/A

Élément <MapName>

L'élément <MapName> permet à la règle d'identifier le KVM à utiliser de manière dynamique, au moment de l'exécution. La sélection dynamique de KVM vous permet de concevoir une règle KeyValueMapOperations pouvant accéder à différents KVM, en fonction du contexte dans lequel la règle s'exécute.

Voici quelques exemples :

<!-- use one of the following forms -->

<MapName>literal_string</MapName>

<MapName ref="flow.variable"></MapName>

<MapName ref="flow.variable">literal_string</MapName>

La première ligne spécifie le nom du KVM sous forme de chaîne littérale. La deuxième ligne prend le nom d'une variable de flux. Dans la troisième ligne, si la variable de flux équivaut à une valeur vide, la chaîne littérale est utilisée à la place.

Ne spécifiez pas l'attribut mapIdentifier si vous utilisez <MapName> dans votre stratégie. Pour en savoir plus, consultez la section Attributs de stratégie.

Si la carte n'existe pas lors du déploiement du proxy, elle ne sera pas créée et Apigee génère une erreur d'exécution lors de l'exécution de la règle. Si la variable de flux est fournie, l'élément <InitialEntries> n'est pas autorisé. Vous obtiendrez une erreur de validation lors du déploiement.

Élément <Parameter>

Spécifie le composant d'une clé dans une paire clé/valeur. Cet élément spécifie le nom lors de la création, de la mise à jour, de la récupération ou de la suppression de la paire clé/valeur.

Vous pouvez en spécifier le nom en utilisant :

• Une chaîne littérale

  <Key>
    <Parameter>literal</Parameter>
  </Key>

• Une variable à récupérer au moment de l'exécution via l'attribut ref

  <Key>
    <Parameter ref="variable_name"/>
  </Key>

• Une combinaison de littéraux et de références de variables

  <Key>
    <Parameter>targeturl</Parameter>
    <Parameter ref="apiproxy.name"/>
    <Parameter>weight</Parameter>
  </Key>

Lorsque l'élément <Key> inclut plusieurs éléments <Parameter>, la chaîne de clé effective correspond à la concaténation des valeurs de chaque paramètre, associées à deux traits de soulignement. Par exemple, dans l'exemple ci-dessus, si la variable apiproxy.name a pour valeur abc1, la clé en vigueur est targeturl__abc1__weight.

Le nom de la clé doit correspondre au nom de la clé du KVM si vous obtenez, mettez à jour ou supprimez une entrée clé-valeur. Pour obtenir des instructions, consultez la section Spécifier et récupérer des noms de clés.

Par défaut	N/A
Présence	Requis
Type	Chaîne

Attributs

Le tableau suivant décrit les attributs de l'élément <Parameter> :

Attribut	Description	Par défaut	Présence
ref	Spécifie le nom d'une variable dont la valeur contient le nom exact de la clé que vous souhaitez créer, obtenir ou supprimer.	N/A	Obligatoire si aucune valeur littérale n'est fournie entre les tags d'ouverture et de fermeture.

Élément <Put>

Écrit une paire clé/valeur sur un KVM. Si le KVM spécifié dans l'attribut mapIdentifier de l'élément racine n'existe pas et si l'élément <MapName> n'est pas utilisé, le mappage est automatiquement créé. Si le mappage clé-valeur existe déjà, la clé-valeur y est ajoutée.

Pour créer un KVM à l'aide de l'interface utilisateur ou de l'API, consultez les pages suivantes :

• Utiliser des KVM avec l'interface utilisateur d'Apigee pour créer des KVM chiffrés au niveau de l'environnement dans l'interface utilisateur
• API de mappage de clés-valeurs au niveau de l'organisation
• API de mappage de clés-valeurs au niveau de l'environnement
• API de mappage de clés-valeurs au niveau du proxy d'API

Remarque : Vous pouvez utiliser plusieurs opérations dans la même règle. Dans ce cas, la règle exécute les opérations dans l'ordre. Si vous utilisez un PUT suivi de GET dans la même règle à l'aide de la même clé, l'opération PUT, lorsqu'elle écrit, réinitialise implicitement le délai d'expiration du cache. Pour en savoir plus, consultez la section qui traite de l'élément ExpiryTimeInSecs.

La taille de la clé est limitée à 2 Ko.

<Put override="false">
  <Key>
    <Parameter ref="mykeyvar"/>
  </Key>
  <Value ref="myvalvar1"/>
</Put>

Par défaut	N/A
Présence	Obligatoire si <Get> ou <Delete> ne sont pas présents.
Type	N/A

Avertissement : Si la règle a utilisé la commande PUT pour insérer une clé-valeur dans un KVM à l'aide d'une clé nulle, la clé suivante est créée automatiquement : __$$_EDGE_KVM_EMPTY_KEY_$$__

Cette situation se produit, par exemple, si vous insérez une clé à l'aide d'une référence de variable et que la variable référencée est nulle. Lors de l'exécution de nouvelles opérations PUT contenant des clés nulles, seule cette clé est utilisée. Les valeurs existantes de cette clé sont donc potentiellement écrasées à chaque exécution de la règle.

Attributs

Le tableau suivant décrit les attributs de l'élément <Put> :

Attribut	Description	Par défaut	Présence
override	Si la valeur définie est true, elle remplace la valeur d'une clé. <Put override="false"> n'écrira qu'à la condition qu'aucune entrée n'est actuellement conservée dans le magasin de KVM pour cette clé.	true	Facultatif

Élément <Scope>

Définit la limite d'accessibilité des KVM. Le champ d'application par défaut est environment. Par défaut, les entrées de mappage sont partagées par tous les proxys d'API exécutés dans un environnement (par exemple, test ou prod). Si vous définissez le champ d'application sur apiproxy, les entrées du KVM ne sont accessibles que par le proxy d'API qui écrit les valeurs dans le mappage.

Notez que lorsque vous accédez à un mappage ou à une entrée de mappage, vous devez spécifier la même valeur de champ d'application que celle utilisée lors de la création du mappage. Par exemple, si le mappage a été créé avec un champ d'application de apiproxy, vous devez utiliser le champ d'application apiproxy pour récupérer ses valeurs, apporter des modifications ou supprimer des entrées.

<Scope>environment</Scope>

Par défaut	environment
Présence	Facultatif
Type	Chaîne
Valeurs valides	organization environment apiproxy policy (révision de proxy d'API)

Élément <Value>

Spécifie la valeur d'une clé. Vous pouvez spécifier la valeur en tant que chaîne littérale ou, en utilisant l'attribut ref, en tant que variable à récupérer au moment de l'exécution :

<!-- Specify a literal value -->
<Value>literal<Value>

ou :

<!-- Specify the name of variable value to be populated at run time. -->
<Value ref="variable_name"/>

Vous pouvez également inclure plusieurs éléments <Value> pour spécifier une valeur en plusieurs parties. Les valeurs sont combinées au moment de l'exécution.

Dans l'exemple suivant, deux clés sont ajoutées au KVM :

• Clé k1 avec les valeurs v1,v2
• Clé k2 avec les valeurs v3,v4

<InitialEntries>
  <Entry>
    <Key>
      <Parameter>k1</Parameter>
    </Key>
    <Value>v1</Value>
    <Value>v2</Value>
  </Entry>
  <Entry>
    <Key>
      <Parameter>k2</Parameter>
    </Key>
    <Value>v3</Value>
    <Value>v4</Value>
  </Entry>
</InitialEntries>

Dans l'exemple suivant, une clé est créée avec deux valeurs. Supposons que le nom de l'organisation soit foo_org, que le nom du proxy d'API soit bar et que l'environnement soit test :

• Clé foo_org avec les valeurs bar,test

<Put>
  <Key>
    <Parameter ref="organization.name"/>
  </Key>
  <Value ref="apiproxy.name"/>
  <Value ref="environment.name"/>
</Put>

Par défaut	N/A
Présence	Requis
Type	Chaîne

Attributs

Le tableau suivant décrit les attributs de l'élément <Value> :

Attribut	Description	Par défaut	Présence
ref	Spécifie le nom d'une variable dont la valeur contient la ou les clés-valeurs que vous souhaitez définir.	N/A	Obligatoire si aucune valeur littérale n'est fournie entre les tags d'ouverture et de fermeture. Utilisation interdite si une valeur littérale est spécifiée.

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés et les variables d'erreur définies par Apigee lorsque cette règle déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Conseil : Vous avez besoin d'aide pour résoudre une erreur ? Cliquez sur dans la colonne "Corriger" pour obtenir des informations de dépannage détaillées.

Code d'erreur	État HTTP	Cause	Corriger
steps.keyvaluemapoperations.UnsupportedOperationException	500	Cette erreur se produit si l'attribut mapIdentifier est défini sur une chaîne vide dans la règle KeyValueMapOperations.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Conseil : Vous avez besoin d'aide pour résoudre une erreur ? Cliquez sur dans la colonne "Corriger" pour obtenir des informations de dépannage détaillées.

Nom de l'erreur	Cause	Corriger
InvalidIndex	Si l'attribut index spécifié dans l'élément <Get> de la règle KeyValueMapOperations est égal à zéro ou à un nombre négatif, le déploiement du proxy d'API échoue. L'index commence à partir de 1. Un index égal à zéro ou à un entier négatif est donc considéré comme non valide.
KeyIsMissing	Cette erreur se produit si l'élément <Key> est complètement manquant ou si l'élément <Parameter> est manquant dans l'élément <Key> sous l'élément <Entry> de l'élément <InitialEntries> de la règle KeyValueMapOperations.
ValueIsMissing	Cette erreur se produit si l'élément <Value> est manquant sous l'élément <Entry> de l'élément <InitialEntries> de la règle KeyValueMapOperations.

Schémas

Exemple : consultez les exemples de dépôt GitHub pour visualiser les schémas les plus récents.

Remarques sur l'utilisation

Pour une présentation des KVM, consultez la section Utiliser des mappages clé-valeur.

À l'aide de l'interface utilisateur d'Apigee, vous pouvez définir les KVM au niveau de l'environnement, comme expliqué dans la section Utilisation des KVM avec l'interface utilisateur d'Apigee. À l'aide de l'API Apigee, vous pouvez définir des KVM au niveau du champ d'application de l'organisation, de l'environnement ou du proxy d'API, comme décrit dans les sections suivantes :

• API de mappage de clés-valeurs au niveau de l'organisation
• API de mappage de clés-valeurs au niveau de l'environnement
• API de mappage de clés-valeurs au niveau du proxy d'API

Un magasin de KVM fournit un mécanisme de persistance léger pour les données sous forme de paires clé/valeur. Vous pouvez y accéder lors de l'exécution, via des règles ou du code. Un mappage contient toutes les données arbitraires au format key=value.

Remarque : La taille de la clé est limitée à 2 Ko.

Par exemple, localhost=127.0.0.1, zip_code=94110 ou first_name=felix. Dans le premier exemple, localhost est une clé et 127.0.0.1 est une valeur. Chaque paire clé/valeur est stockée sous la forme d'une entrée dans un mappage clé/valeur. Un KVM peut stocker de nombreuses entrées.

Par exemple, supposons que vous deviez stocker une liste d'adresses IP associées à différents environnements de backend. Vous pouvez créer une instance KVM appelée ipAddresses, qui contient une liste de paires clé/valeur sous forme d'entrées. Par exemple, ce JSON peut représenter ce type de mappage :

{
  "entry" : [ {
    "name" : "Development",
    "value" : "65.87.18.18"
  }, {
    "name" : "Staging",
    "value" : "65.87.18.22"
  } ],
  "name" : "ipAddresses"
}

Vous pouvez utiliser cette structure pour créer un magasin d'adresses IP pouvant être utilisé par des règles au moment de l'exécution pour appliquer la liste d'autorisation/la liste de blocage d'adresses IP, pour sélectionner une adresse cible de backend de manière dynamique, etc. En général, la règle KeyValueMapOperations permet de stocker ou de récupérer des informations de longue durée ayant besoin d'être réutilisées pour plusieurs transactions de requête/réponse.

Les KVM peuvent être manipulées via la règle KeyValueMapOperations ou directement via l'API Apigee. L'API vous permet, par exemple, d'importer des ensembles de données volumineux dans le magasin de clés-valeurs, ou de créer des scripts pour gérer les entrées de mappage clés-valeurs. Vous devrez créer un KVM avec l'API avant d'y accéder via la règle KeyValueMapOperations.

Spécifier et récupérer des noms de clé

Avec les éléments <Parameter> et <Value>, vous pouvez spécifier une valeur littérale (où la valeur est comprise entre les balises d'ouverture et de fermeture) ou utiliser l'attribut ref pour spécifier le nom d'une variable dont la valeur doit être utilisée au moment de l'exécution.

L'élément <Parameter> mérite une mention particulière, car il détermine le nom de la clé créée, ainsi que le nom de la clé que vous souhaitez récupérer ou supprimer. Voici deux exemples. Le premier spécifie un nom de clé à l'aide d'un littéral, et le second spécifie un nom de clé à l'aide d'une variable. Supposons que les éléments suivants soient utilisés pour créer les clés dans un KVM :

<Parameter>KEY_NAME_LITERAL</Parameter>
<Parameter ref="key.name.variable"/>

Dans la première instance, la valeur littérale de KEY_NAME_LITERAL est stockée dans le KVM sous forme de nom de clé. Dans la deuxième instance, n'importe quelle valeur figurant dans key.name.variable devient le nom de la clé dans le KVM. Par exemple, si key.name.variable contient la valeur foo, la clé est nommée foo.

Pour récupérer la clé et une valeur de clé avec une opération GET (ou la supprimer avec une opération DELETE), la valeur de l'élément <Parameter> doit correspondre au nom de la clé dans le KVM. Par exemple, si le nom de clé dans le KVM est my_key, vous pouvez spécifier la valeur littérale avec <Parameter>my_key</Parameter> ou spécifier une variable contenant la valeur exacte mny_key, comme ceci : <Parameter ref="variable.containing.foo"/>.

Remarque : Le nom ratelimit est réservé. Pour en savoir plus, consultez la page Règles de quota – Génère une valeur NullPointerException.

Articles associés

Pour en savoir plus sur les KVM, reportez-vous aux rubriques suivantes :

• Utiliser les mappages clé-valeur
• API de mappage de clés-valeurs au niveau de l'organisation
• API de mappage de clés-valeurs au niveau de l'environnement
• API de mappage de clés-valeurs au niveau du proxy d'API