Règle KeyValueMapOperations

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X.
en savoir plus

Icône Opérations de mappage de valeurs clés de l'interface utilisateur Edge

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.

Vidéo Description
Pourquoi les mappages clé-valeur ? Découvrez pourquoi vous avez besoin de KVM et comment ils fonctionnent.
Créer un KVM à l'aide de l'interface utilisateur et récupérer le KVM au moment de l'exécution Créez un KVM, récupérez sa valeur à l'aide d'une règle KVM et injectez la valeur dans la requête API à l'aide de variables de flux.
Créer et mettre à jour un KVM au moment de l'exécution de l'API Créez un KVM au moment de l'exécution de l'API à l'aide d'une règle KVM.
Mettre en cache le KVM pour augmenter les performances Améliorer les performances d'une règle KVM en mettant en cache les données.
Stocker un KVM chiffré Stockez les informations sensibles dans le KVM au format chiffré et récupérez la valeur au moment de l'exécution à l'aide de la règle KVM et des variables privées.
Gérer les accès à l'aide du champ d'application KVM Limitez le KVM à une organisation, un environnement, un proxy d'API ou une révision de proxy d'API à l'aide de l'attribut de champ d'application de la règle KVM.
Supprimer les entrées KVM au moment de l'exécution de l'API Supprimez les entrées KVM lors de l'exécution de l'API à l'aide de l'opération de règle DELETE.

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 crée une clé nommée FooKey_1 avec deux valeurs définies avec les chaînes littérales foo et bar (non définie avec des valeurs extraites des variables). Lorsque vous utilisez GET pour 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 la portée correspond à "environment". Cela signifie que vous pouvez voir la VM KVM dans l'interface utilisateur de gestion sous APIs > Environment Configuration > Key Value Maps (API > Configuration de l'environnement > Cartes clés-valeurs). 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, affiche 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>

Mettre à jour (PUT) un KVM avec une variable

Un exemple simple de mappage clé-valeur est un service de raccourcissement d'URL. Le mappage clé-valeur peut être configuré pour stocker des URL raccourcies avec les URL complètes correspondantes.

Cet exemple de règle crée un mappage clé-valeur. La règle met à jour (PUT) une clé à deux valeurs associées dans un mappage clé-valeur 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 mappage de clés/valeurs et l'entrée suivants seraient générés dans le magasin clé-valeur d'Edge et limités au proxy d'API auquel la stratégie 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 entre les instances Edge qui exécutent le cloud.

Obtenir KVM à partir d'une variable

Un exemple simple de mappage clé-valeur est un service de "raccourcissement" d'URL. Le mappage clé-valeur peut être configuré pour stocker des URL raccourcies avec les URL complètes correspondantes.

Pour récupérer la valeur d'une entrée de mappage clé-valeur, telle que celle décrite dans l'onglet PUT KeyValueMapOperations, configurez une règle pour afficher (GET) le mappage clé-valeur :

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

Afficher (GET) une valeur chiffrée à partir d'un KVM

Si un mappage clé-valeur est chiffré, récupérez les valeurs à l'aide du préfixe "private." dans la valeur de l'attribut assignTo. Dans cet exemple, la variable private.encryptedVar contient la valeur déchiffrée de la clé foo du mappage clé-valeur. Pour en savoir plus sur la création de mappages clé-valeur chiffrés, consultez les rubriques "Créer" de l'API de gestion des mappages clé-valeur.

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


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

Attribut Description Par défaut Présence
mapIdentifier

Spécifie un identifiant à utiliser pour accéder à un mappage créé par cette règle ou dans l'interface utilisateur de gestion.

Avec Apigee Edge pour le cloud public, le nom KVM est sensible à la casse. Par exemple, foobar est différent de FooBar.

Si vous excluez cet attribut, un KVM nommé kvmap est utilisé.

Dans un champ d'application d'organisation, d'environnement ou de proxy d'API, vous pouvez utiliser l'attribut mapIdentifier pour spécifier votre propre nom de mappage.

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.

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

true Facultatif
async

Cet attribut est obsolète.

false 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é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>
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 pour les mappages clé-valeur, qui sont insérés dans le mappage clé-valeur lors de l'initialisation.

Pour Edge for Public Cloud, 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 Edge 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, Edge dispose d'un mécanisme intégré permettant de mettre en cache les clés/valeurs KVM en mémoire pendant l'exécution. Cette règle d'opérations KVM lit toujours le cache pour les 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, 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" à la mise en cache. La valeur <ExpiryTimeInSecs> de 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.

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

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.

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

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 variables suivantes 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> :

Attribut Description Par défaut Présence
assignTo

La variable à laquelle la valeur récupérée doit être attribuée.

Si le mappage clé-valeur est chiffré, commencez par le nom assignTo, suivi de "private.". Par exemple :

<Get assignTo="private.myvar">

La règle génère une erreur si vous essayez de récupérer un mappage clé-valeur chiffré sans utiliser le préfixe. Le préfixe, requis pour des raisons de sécurité élémentaires lors du débogage, masque les valeurs chiffrées des sessions de débogage et de suivi du proxy d'API.

Pour en savoir plus sur la création de mappages clé-valeur chiffrés, consultez les rubriques "Créer" de l'API de gestion des mappages clé-valeur et Créer et modifier des mappages clé-valeur d'environnement.

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.

Pour obtenir un exemple, consultez l'onglet "Afficher (GET) une valeur chiffrée à partir d'un KVM" dans Exemples.

N/A Facultatif

É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 la clé est limitée à 2 Ko pour le cloud public et Edge pour le cloud privé. La valeur KVM est limitée à 2 Ko.

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

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

É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 for Public Cloud, la taille de la clé est limitée à 2 Ko. Consultez la section Différences entre l'API Edge for Public Cloud et l'API Private Cloud pour en savoir plus.

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

Élément <Parameter>

Spécifie la clé dans une paire clé/valeur. Cet élément spécifie le nom lors de la création, du placement, 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 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, mettez à jour ou supprimez une entrée clé/valeur, le nom de la clé doit correspondre à celui de la clé indiquée dans le mappage de 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 Obligatoire
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, afficher ou supprimer. 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.

É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>
Par défaut N/A
Présence Obligatoire si <Get> ou <Delete> ne sont pas présents.
Type N/A

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

false Facultatif

É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>
Par défaut environment
Présence Facultatif
Type Chaîne
Valeurs correctes :
  • 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 Obligatoire
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

Les erreurs renvoyées par les stratégies Edge suivent un format cohérent, comme décrit dans la référence du 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.

Code d'erreur État HTTP Cause Solution
steps.keyvaluemapoperations.SetVariableFailed 500

Cette erreur se produit si vous tentez de récupérer une valeur à partir d'un mappage clé-valeur chiffré et de la définir sur une variable dont le nom ne comporte pas le préfixe private. Le préfixe, requis pour des raisons de sécurité élémentaires lors du débogage, masque les valeurs chiffrées des sessions de débogage et de suivi du proxy d'API.

steps.keyvaluemapoperations.UnsupportedOperationException 500

Cette erreur se produit si l'attribut mapIdentifier est défini sur une chaîne vide dans la règle des opérations de mappage clé-valeur.

Erreurs de déploiement

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

Nom de l'erreur Cause Corriger
InvalidIndex Si l'attribut index spécifié dans l'élément <Get> de la règle des opérations de mappage clé-valeur est égal à zéro ou à un nombre négatif, le déploiement du proxy 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 "Opérations de mappage de clés-valeurs".
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 des opérations de mappage clé-valeur.

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 ayez besoin de stocker une liste d'adresses IP associées à différents environnements de backend. 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 pouvant être utilisées par les règles au moment de l'exécution pour appliquer une liste d'autorisation ou de blocage d'adresses IP, pour sélectionner dynamiquement une adresse cible de backend, 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és/valeurs peuvent être manipulés via la règle KeyValueMapOperations ou directement via l'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é créée, ainsi que le nom de 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 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