Règle KeyValueMapOperations

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X. En savoir plus

Quoi

Fournit un accès basé sur des règles à un magasin KVM (Key Value Map) disponible dans Apigee Edge. 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. (Au moins une de ces opérations doit être exécutée par la règle).

Vidéos

Regardez les vidéos suivantes pour en savoir plus sur les KVM.

Exemples

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

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

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

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

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

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

Documentation de référence des éléments

La documentation de référence des éléments décrit les éléments et les attributs de la règle KeyValueMapOperations :

<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>variable_name</Parameter>
         </Key>
         <Value>value_1_literal</Value>
         <Value>value_2_literal</Value>
      </Entry>
   </InitialEntries>
   <Put override="false">
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value ref="variable_name"/>
   </Put>
   <Get assignTo="myvar" index="1">
      <Key>
         <Parameter ref="variable_name"/>
      </Key>
   </Get>
   <Delete>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
   </Delete>
</KeyValueMapOperations>

Attributs <KeyValueMapOperations>

L'exemple suivant montre les attributs du tag <KeyValueMapOperations> :

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

Le tableau suivant décrit les attributs spécifiques au tag <KeyValueMapOperations> :

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

É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>

Élément <Delete>

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

Assurez-vous de spécifier le nom du KVM avec l'attribut mapIdentifier sur l'élément parent. Exemple :

<Delete>
   <Key>
      <Parameter>key_name_literal</Parameter>
   </Key>
</Delete>

Élément <Entry>

Valeurs sources pour les mappages clé-valeur, qui sont insérés dans le mappage clé-valeur lors de l'initialisation.

Pour Edge pour Public Cloud, la taille de 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>

É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 Edge actualise sa valeur mise en cache à partir du KVM spécifiée.

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>

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 Performance Max, Edge dispose d'un mécanisme intégré pour mettre en cache les clés/valeurs KVM en mémoire pendant l'exécution. Cette stratégie d'opérations KVM lit toujours les opérations GET à partir du cache.

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, les opérations GET et PUT affectent l'expiration du cache de différentes manières.

GET : la première fois qu'une opération GET KVM s'exécute, les clés-valeurs demandées du KVM (dont le nom est spécifié dans l'attribut mapIdentifier racine de la règle) sont chargées. dans le cache, où elles restent pour les opérations GET ultérieures 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'opération PUT écrit dans une clé qui existe déjà dans le cache, ce cache est immédiatement actualisé et contient alors la nouvelle valeur pour le nombre de secondes spécifié dans l'élément <ExpiryTimeInSecs> de la règle.

Exemple – Mise en cache d'un KVM

1. Une opération GET récupère la valeur de « rating », qui ajoute la valeur "10" à mettre en cache. La <ExpiryTimeInSecs> sur la règle est de 60.
2. Trente secondes plus tard, la règle GET s'exécute à nouveau et récupère "10" du cache.
3. Cinq secondes plus tard, une règle PUT met à jour la valeur "rating" par "8" et la valeur <ExpiryTimeInSecs> de la règle PUT est de 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. Quinze secondes plus tard, une autre opération GET s'exécute et récupère la valeur "8".

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

Assurez-vous de spécifier le nom du KVM avec l'attribut mapIdentifier sur l'élément parent.

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

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

<Get assignTo="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.

Voici une configuration de règle KVM que nous pouvons utiliser pour récupérer le film le plus populaire 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é, Edge crée les éléments suivants que vous pouvez utiliser dans le flux de proxy d'API:

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

Attributs

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

<Get assignTo="private.myvar">

Élément <InitialEntries>

Valeurs sources pour les mappages clé-valeur, qui sont insérés dans le mappage clé-valeur lors de l'initialisation. Assurez-vous de spécifier le nom du KVM avec l'attribut mapIdentifier sur l'élément parent. Par 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 de gestion sur une version déployée du proxy 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 (non chiffrées). 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. 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 clé est limitée à 2 Ko pour Edge pour le cloud public et Edge for the Private pourrait. La valeur de la KVM est limitée à 2 Ko.

Pour créer une KVM chiffrée, utilisez l'API de gestion des cartes clé-valeur.

Élément <Key>

Spécifie la clé dans une entrée de mappage clé-valeur. Une clé peut être composite, ce qui signifie que plusieurs paramètres peuvent être ajoutés afin de créer la clé. Par exemple, userID et role peuvent être combinés pour créer une key. Exemple :

<Key>
    <Parameter>key_name_literal</Parameter>
</Key>

Veillez à consulter l'élément <Parameter> pour en savoir plus sur la méthode visant à définir le nom de la clé.

Avec Edge pour Public Cloud, la taille de la clé est limitée à 2 Ko. Voir Différences entre l'API Edge for Public Cloud et l'API Private Cloud pour plus d'informations.

Élément <Parameter>

Spécifie la clé dans une paire clé/valeur. Cet élément spécifie le nom lors de la création, de la la récupération ou 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 de paramètre, 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 possède la valeur "abc1", la clé effective sera targeturl__abc1__weight.

Que vous obteniez, mettiez à jour ou supprimiez une entrée clé-valeur, le nom de la clé doit correspondre au nom de la clé dans le mappage de clé-valeur. Pour obtenir des instructions, consultez la section Spécifier et récupérer des noms de clés.

Attributs

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

Élément <Put>

Écrit une paire clé/valeur sur un mappage clé-valeur, que celui-ci soit chiffré ou non. Si le mappage clé-valeur spécifié dans l'attribut mapIdentifier sur l'élément parent n'existe pas, le mappage est automatiquement créé (en tant que non chiffré). Si le mappage clé-valeur existe déjà, la clé-valeur y est ajoutée.

Pour créer un mappage clé-valeur chiffré, utilisez l'API de gestion des mappages clé-valeur ou consultez la section Créer et modifier des mappages clé-valeur d'environnement pour créer des KVM chiffrés à l'échelle de l'environnement dans l'interface utilisateur.

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

Attributs

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

Élément <Scope>

Définit la limite d'accessibilité des mappages clé-valeur. 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 mappage clé-valeur 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>

É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>

Attributs

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

Informations de référence sur les erreurs

Les erreurs renvoyées par les stratégies Edge suivent un format cohérent, comme décrit dans la documentation de référence sur le code d'erreur.

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés, ainsi que les variables d'erreur définies par Edge lorsque cette stratégie 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.

Erreurs de déploiement

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

Schémas

Remarques sur l'utilisation

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

Un magasin de mappages clé-valeur fournit un mécanisme de persistance léger pour les données formatées en tant que 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.

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 mappage de clé-valeur peut stocker de nombreuses entrées.

Voici un exemple d'utilisation de mappages clé-valeur. Supposons que vous deviez stocker une liste d'adresses IP associés à différents systèmes de l'infrastructure. Vous pouvez créer un mappage clé-valeur appelé 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 qui pourraient être utilisées par les stratégies au moment de l'exécution pour appliquer une liste d'autorisation ou de refus d'adresses IP, pour sélectionner dynamiquement une cible backend l'adresse e-mail, 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 mappages de clé-valeur peuvent être manipulés via la règle KeyValueMapOperations ou directement via la API de gestion Apigee Edge. Reportez-vous à la documentation de référence de l'API de gestion pour plus de détails sur l'API d'organisation de mappages clé-valeur. L'API vous permet, par exemple, d'importer des ensembles de données volumineux dans le magasin clé-valeur, ou de créer des scripts pour gérer les entrées de mappage clé-valeur. Vous devez créer un mappage clé-valeur avec l'API avant de pouvoir y accéder à l'aide de 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 spéciale, car il détermine le nom de la clé ainsi que le nom de la clé que vous voulez 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 en tant que 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".

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

Articles associés

• API d'organisation de mappages clé-valeur