Política de operaciones de mapas de clave-valor

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Qué

Proporciona acceso basado en políticas a un almacén de mapas de clave-valor (KVM) disponible en Apigee. Los pares clave-valor se pueden almacenar, recuperar y borrar de mapas existentes con nombres mediante políticas KeyValueMapOperations que especifican operaciones PUT, GET o DELETE, respectivamente. (La política debe realizar al menos una de estas operaciones).

Esta política es una política extensible, y el uso de esta política puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.

Nota: a partir de la versión 1.4.0 de Apigee Hybrid, Apigee encripta todas las KVM de forma predeterminada. Usa el atributo private. con todas las variables cuando accedas a un KVM con el comando GET para ocultar la información del KVM en una sesión de Debug. Si no se usa el atributo private., el KVM aún está encriptado. Sin embargo, la información de KVM aparecerá desencriptada en la sesión de Debug y no se lanzará ninguna excepción.

Video: En el siguiente video, se proporciona una introducción de alto nivel a KVM.

Ejemplos

KVM de PUT con un literal

Cuando se ejecuta la siguiente política, se crea una KVM encriptada llamada FooKVM y, luego, se crea una clave llamada FooKey_1 con dos valores establecidos con strings literales foo y bar (no configurados con valores extraídos de las variables). Cuando realices la operación GET en la clave del siguiente ejemplo, debes especificar un número de índice para recuperar el valor que deseas.

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

Observa que el permiso es environment. Esto significa que puedes ver la KVM en la IU de administración en API > Configuración del entorno > Mapas clave-valor. Las KVM que se muestran en esa página tienen alcance en el entorno seleccionado.

KVM de GET a partir de un literal

Esta política analiza el mapa FooKVM del ejemplo anterior, obtiene el segundo valor (index="2") de la clave FooKey_1 y lo almacena en una variable llamada 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>

Accede a un KVM de forma dinámica

Esta política usa el elemento <MapName> para hacer referencia a un KVM de forma dinámica con una variable de flujo. El elemento obtiene el identificador de KVM de la variable de flujo. Ten en cuenta que se omite el atributo mapIdentifier. No puedes usar <MapName> con el atributo 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>

KVM de PUT con una variable

Un ejemplo simple de un KVM útil es un servicio de acortamiento de URL. La KVM podría configurarse para almacenar URL abreviadas junto con las URL completas correspondientes.

En esta muestra de política, se crea un KVM. La política usa el comando PUT para colocar una clave con dos valores asociados en una KVM llamada 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>

La clave en este ejemplo, urlencoding.requesturl.hashed, es un ejemplo de una variable personalizada. La URL de solicitud con hash se generaría con código (JavaScript o Java, por ejemplo) y, luego, se almacena en esta variable, en la que la política KeyValueMapOperations puede acceder a ella.

Para cada clave, requesturl.hashed, se almacenan estos dos valores:

• Los contenidos de la variable personalizada llamada urlencoding.longurl.encoded
• Los contenidos de la variable predefinida request.queryparam.url

Por ejemplo, cuando la política se ejecuta en el entorno de ejecución, los valores de las variables pueden ser de la siguiente manera:

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

La siguiente entrada y KVM se generarían en el almacén de clave-valor de Apigee y su alcance al proxy de API al que se adjunta la política:

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

La entrada permanecerá hasta que se borre. Las entradas de almacenamiento de clave-valor se distribuyen entre las instancias de Apigee que ejecutan la nube.

KVM de GET desde una variable

Un ejemplo simple de un KVM útil es un servicio de acortamiento de URL. La KVM podría configurarse para almacenar URL abreviadas junto con las URL completas correspondientes.

Para recuperar el valor de entrada de KVM, como el que se cubre en KeyValueMapOperations PUT establece una política para GET KVM:

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

Cuando se ejecuta esta política, si el valor de la variable urlencoding.requesturl.hashed es ed24e12820f2f900ae383b7cc4f2b31c402db1be, la variable personalizada llamada urlencoding.shorturl se establecerá con el valor http://tinyurl.com/38lwmlr.

Ahora que se recuperaron los datos, otras políticas y otro código pueden acceder a ellos mediante la extracción del valor de esas variables.

Valor GET de KVM

Usa el atributo private. con todas las variables cuando accedas a un KVM con el comando GET para ocultar la información del KVM en una sesión de Debug. Si no se usa el atributo private., el KVM aún está encriptado. Sin embargo, la información de KVM aparecerá desencriptada en la sesión de Debug y no se lanzará ninguna excepción.

En este ejemplo, la variable private.encryptedVar contiene el valor desencriptado de la clave foo de la KVM.

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

Ahora que se recuperaron los datos, otras políticas y código pueden acceder a ellos mediante la extracción del valor de esa variable.

<KeyValueMapOperations>

Proporciona acceso basado en políticas a un mapa de clave-valor (KVM).

Sintaxis

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

Atributos <KeyValueMapOperations>

En el siguiente ejemplo, se muestran los atributos del elemento <KeyValueMapOperations>:

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

En la siguiente tabla, se describen los atributos del elemento <KeyValueMapOperations>

Nota: El atributo mapIdentifier especifica el nombre del KVM con el que deseas interactuar. También puedes especificar un KVM de forma dinámica con el elemento <MapName>.

Atributo	Descripción	Predeterminado	Presence
mapIdentifier	Especifica un identificador que le indica a la política a la que debe acceder el KVM. Si faltan este identificador y <MapName>, se usa un KVM llamado kvmap. No puedes usar este atributo si especificas el elemento <MapName>.	N/A	Opcional

En la siguiente tabla, se describen los atributos que son comunes a todos los elementos principales de las políticas:

Atributo	Descripción	Configuración predeterminada	Presence
name	El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres. De forma opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.	N/A	Obligatorio
continueOnError	Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas. Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle. También consulta lo siguiente: Las reglas de fallas se activan SOLAMENTE en un estado de error (sobre el continueOnError) Controla fallas dentro del flujo actual	false	Opcional
enabled	Configúralo como true para aplicar la política. Configúralo como false para desactivar la política. La política no se aplicará incluso si permanece adjunta a un flujo.	true	Opcional
async	Este atributo dejó de estar disponible.	false	Obsoleto

Elemento <DisplayName>

Se usan además del atributo name para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

<DisplayName>Policy Display Name</DisplayName>

Configuración predeterminada	N/A Si omites este elemento, se usa el valor del atributo name de la política.
Presence	Opcional
Tipo	String

Elementos secundarios

En esta sección, se describen los elementos y atributos de la política KeyValueMapOperations:

Elemento <Delete>

Borra el par clave-valor especificado. Se debe usar al menos uno de los siguientes valores: <Get>, <Put> o <Delete>.

Asegúrate de especificar el nombre del KVM con el atributo mapIdentifier en el elemento raíz o con el elemento <MapName>. Por ejemplo:

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

Predeterminado	N/A
Presence	Obligatorio si <Get> o <Put> no están presentes.
Tipo	N/A

Elemento <Entry>

Valores iniciales de KVM, que se propagan en el KVM cuando se inicializa. Para Apigee, el tamaño de la clave se limita a 2 KB.

Por ejemplo:

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

Predeterminado	N/A
Presence	Opcional
Tipo	N/A

Elemento <ExclusiveCache>

Obsoleto. En su lugar, usa el elemento <Scope>.

Elemento <ExpiryTimeInSecs>

Especifica la duración en segundos a partir de la cual Apigee actualiza su valor almacenado en caché del KVM especificado.

Un valor de 0 o -1, o excluir este elemento, significa que se usa el valor predeterminado de 300 segundos. Por ejemplo:

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

Predeterminado	300 (5 minutos)
Presence	Opcional
Tipo	Entero

Un KVM es un mecanismo de persistencia a largo plazo que almacena claves y valores en una base de datos NoSQL. Debido a esto, la lectura de un KVM en el tiempo de ejecución puede ralentizar el rendimiento del proxy. A fin de mejorar el rendimiento, Apigee tiene un mecanismo integrado para almacenar en caché las claves o los valores de KVM en la memoria durante el tiempo de ejecución. Esta política de operaciones de KVM siempre lee desde la caché para las operaciones de GET.

El elemento <ExpiryTimeInSecs> te permite controlar cuánto tiempo se almacenan las claves o los valores usados en la política antes de volver a actualizarse desde el KVM. Sin embargo, hay algunas diferencias entre cómo las operaciones GET y PUT afectan el vencimiento de la caché.

GET: La primera vez que se ejecuta una operación GET de KVM, las claves o los valores solicitados de la KVM (cuyo nombre se especifica en el atributo raíz mapIdentifier de la política o el elemento <MapName>), se cargan en la caché, donde permanecen para las operaciones GET posteriores hasta que ocurre lo siguiente:

• La cantidad de segundos especificada en <ExpiryTimeInSecs> vence.
  o
• Una operación PUT en una política de KVM reemplaza los valores existentes (se explica a continuación).

PUT: Una operación PUT escribe claves/valores en el KVM especificado. Si PUT escribe en una clave que ya existe en la caché, esa caché se actualiza de inmediato y ahora contiene el valor nuevo durante la cantidad de segundos especificados en el elemento <ExpiryTimeInSecs> de la política. Sin embargo, usar PUT solo actualizará la caché en el nodo de entorno de ejecución único que entrega la solicitud. Para actualizar la caché en cada nodo del entorno de ejecución distribuido, usa el elemento <ExpiryTimeInSecs> a fin de especificar intervalos de actualización para cada nodo.

Ejemplo: Almacenamiento en caché de un KVM

1. Una operación GET recupera el valor de “rating”, que agrega el valor “10” a la caché. El <ExpiryTimeInSecs> en la política es 60.
2. 30 segundos después, la política GET se ejecuta de nuevo y recupera 10 de la caché.
3. 5 segundos después, una política PUT actualiza el valor de rating a 10, y el valor de <ExpiryTimeInSecs> en la política PUT es 20. La caché se actualiza inmediatamente con el nuevo valor, que ahora está configurado para permanecer en la caché durante 20 segundos. (Si el PUT no hubiera ocurrido, la caché propagada con el primer GET seguirá existiendo durante otros 30 segundos, que se omitirán de los 60 segundos originales).
4. 15 segundos después, se ejecuta otro GET y recupera un valor de 8.

Notas

• Para obtener el mejor rendimiento, balancea el tiempo de caducidad de la caché con la cantidad de tráfico de API que esperas. Por ejemplo, con mucho tráfico, te recomendamos establecer intervalos de vencimiento de la caché más largos para evitar actualizaciones frecuentes de la base de datos.
• No hay forma de restablecer de forma manual la caché del KVM. Sin embargo, puedes crear una política temporal que ejecute una operación PUT única con un <ExpiryTimeInSecs> corto. Esta acción restablecerá la caché, que contiene el valor PUT, durante la cantidad de segundos que especifiques.
• La actualización de un KVM con la IU o la API de Apigee no restablece la caché del KVM.
• Puedes usar varias operaciones en la misma política. Si lo haces, la política ejecuta las operaciones en orden. Si usas un valor PUT seguido de uno GET en la misma política con la misma clave, el PUT, cuando escribe, restablecerá de forma implícita el vencimiento de la caché.

Elemento <Get>

Recupera el valor de la clave especificada. Se debe usar al menos uno de los siguientes valores: <Get>, <Put> o <Delete>.

Apigee encripta todos los datos almacenados en el KVM. Para obtener detalles, consulta Información sobre las claves de encriptación. Cuando usas <Get>, Apigee desencripta los datos almacenados y los asigna a una variable en el contexto del mensaje. El nombre de la variable se especifica con el atributo assignTo.

Asegúrate de especificar el nombre del KVM con el atributo mapIdentifier en el elemento raíz o con el elemento <MapName>.

Puedes incluir varios bloques Get en la política para recuperar varios elementos de un KVM.

Nota: Puedes usar varias operaciones en la misma política. Si lo haces, la política ejecuta las operaciones en orden. Si usas un valor PUT seguido de uno GET en la misma política con la misma clave, el PUT, cuando escribe, restablecerá de forma implícita el vencimiento de la caché. Consulta el elemento ExpiryTimeInSecs para obtener más información.

Predeterminado	N/A
Presence	Obligatorio si <Put> o <Delete> no están presentes.
Tipo	N/A

Atributos

La siguiente tabla describe los atributos del elemento <Get>:

Atributo	Descripción	Predeterminado	Presence
assignTo	Variable a la que se debe asignar el valor recuperado.	N/A	Obligatorio
index	El número de índice (en un índice basado en 1) del elemento que se recuperará de una clave de valores múltiples. Por ejemplo, si especificas index=1, se mostrará el primer valor y se lo asignará a la variable assignTo. Si no se especifica un valor de índice, todos los valores de esa entrada se asignan a la variable como un java.util.List. Para ver un ejemplo, consulta la pestaña Obtener valor de KVM en Ejemplos.	N/A	Opcional

Obtén un solo elemento de un KVM

Con esta configuración de pasos de ejemplo, la política lee y desencripta el valor de una sola clave en el KVM y asigna el valor desencriptado a una variable llamada myvar.

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

Excluye datos recuperados de sesiones de depuración

En algunos casos, los datos almacenados en el KVM son sensibles. Para evitar que los datos recuperados aparezcan en una sesión de depuración, usa el prefijo private. en el nombre de la variable especificado en el atributo assignTo. Si no usas el prefijo private., los datos recuperados del KVM aparecerán en texto simple en cualquier sesión de Debug que crees.

Con esta configuración de pasos de ejemplo, la política lee y desencripta el valor asociado a una sola clave en el KVM y asigna ese valor a una variable. La asignación no aparecerá en una sesión de Debug.

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

Cómo obtener varios elementos de un KVM

En el ejemplo siguiente, supón que un KVM tiene las siguientes claves y valores. Además de almacenar una lista de ejecución de las películas más populares de todos los tiempos, el KVM almacena el nombre del director de todas las películas principales.

Clave	Valor
top_movies	Princess Bride, The Godfather, Citizen Kane
Citizen Kane	Orson Welles
Princess Bride	Rob Reiner
The Godfather	Francis Ford Coppola

Notarás que el valor asociado a la clave top_movies contiene varios nombres de películas, separados por comas.

Con esta configuración de ejemplo, la política recupera la película principal actual y el nombre de su director:

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

Cuando se llama al proxy de API, Apigee crea las siguientes variables con valores correspondientes, que se pueden usar más adelante en el flujo del proxy de API:

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

El valor de top.movie.pick es solo el primer elemento de la lista separada por comas, porque el primer elemento <Get> usa un atributo index de 1. Luego, el segundo elemento <Get> usa el valor asignado a top.movie.pick como la clave para recuperar un valor en movie.director.

Elemento <InitialEntries>

Valores iniciales de KVM, que se propagan en el KVM cuando se inicializa. Asegúrate de especificar el nombre del KVM con el atributo mapIdentifier en el elemento raíz.

Nota: No se permite <InitialEntries> si se usa el elemento <MapName>.

Por ejemplo:

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

Cuando usas este elemento, cuando guardas la política en la IU de Apigee en una versión implementada del proxy de API o implementas el paquete del proxy de API que contiene la política con este elemento, las claves se crean de forma automática en el KVM (como no encriptada). Si los valores en la política son diferentes de los valores en el KVM, los valores en el KVM se reemplazan cuando se implementa el proxy de API. Todas las claves/valores nuevas se agregan al KVM existente junto con las claves/valores existentes.

Las claves y los valores propagados por este elemento deben ser literales. Por ejemplo, <Parameter ref="request.queryparam.key"> no es compatible con este elemento.

El tamaño de la clave se limita a 2 KB.

Predeterminado	N/A
Presence	Opcional
Tipo	N/A

Elemento <Key>

Especifica la clave en una entrada de KVM. Este elemento aparece como secundario de <Get>, <Put> o<Delete>, o como elemento secundario del elemento <Entry>, que es secundario de <InitialEntries>. Este es un ejemplo de una clave fija:

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

Una clave puede ser compuesta, con elementos dinámicos, lo que significa que se puede agregar más de un <Parameter> para crearla. Por ejemplo, el contenido de las variables userID y role se puede combinar para crear una clave dinámica. A continuación, te mostramos un ejemplo de configuración de paso que especifica una clave compuesta determinada de forma dinámica:

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

Asegúrate de ver el elemento <Parameter> para obtener detalles específicos sobre cómo configurar el nombre de la clave.

El tamaño de la clave se limita a 2 KB.

Nota: El nombre ratelimit está reservado. Para obtener más información, consulta esta publicación de la comunidad de Apigee.

Predeterminado	N/A
Presence	Opcional
Tipo	N/A

Elemento <MapName>

El elemento <MapName> habilita la política para identificar qué KVM se usará dinámicamente en el entorno de ejecución. La capacidad de seleccionar KVM de forma dinámica te brinda la flexibilidad de diseñar una política KeyValueMapOperations que pueda acceder a diferentes KVM, según el contexto en el que se ejecute la política.

Estos son algunos ejemplos:

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

<MapName>literal_string</MapName>

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

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

La primera línea especifica el nombre del KVM como una string literal. La segunda línea obtiene el nombre de una variable de flujo. En la tercera línea, si la variable de flujo se resuelve como un valor vacío, se usa la string literal en su lugar.

No especifiques el atributo mapIdentifier si usas <MapName> en tu política. Consulta los atributos de la política para obtener más información.

Si el mapa no existe cuando se implementa el proxy, este no se creará y Apigee generará un error de entorno de ejecución cuando se ejecute la política. Si se proporciona la variable de flujo, no se permite el elemento <InitialEntries>. Recibirás un error de validación durante la implementación.

Elemento <Parameter>

Especifica un componente de una clave en un par clave-valor. Este elemento especifica el nombre cuando se crea, actualiza, recupera o borra el par clave-valor.

Puedes especificar el nombre mediante lo siguiente:

• Una string literal

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

• Una variable que se recuperará en el tiempo de ejecución mediante el atributo ref

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

• Una combinación de literales y referencias de variables

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

Cuando el elemento <Key> incluye varios elementos <Parameter>, la string de clave efectiva es la concatenación de los valores de cada parámetro, unidos con un guion bajo doble. Por ejemplo, en la muestra anterior, si la variable apiproxy.name tiene el valor abc1, la clave efectiva será targeturl__abc1__weight.

Ya sea que obtengas, actualices o borres una entrada de clave-valor, el nombre de la clave debe coincidir con el de la clave en el KVM. Consulta Especifica y recupera nombres de claves para conocer los lineamientos.

Predeterminado	N/A
Presence	Obligatorio
Tipo	String

Atributos

En la siguiente tabla, se describen los atributos del elemento <Parameter>:

Atributo	Descripción	Predeterminado	Presence
ref	Especifica el nombre de una variable cuyo valor contiene el nombre exacto de la clave que deseas crear, obtener o borrar.	N/A	Obligatorio si no se proporciona un valor literal entre las etiquetas de apertura y de cierre.

Elemento <Put>

Escribe un par clave-valor en un KVM. Si el KVM especificado en el atributo mapIdentifier en el elemento raíz no existe y si el elemento <MapName> no se usa, se crea el mapa automáticamente. Si el mapa de clave-valor ya existe, se le agrega la clave-valor.

Para crear un KVM mediante la IU o la API, consulta lo siguiente:

• Usa KVM con la IU de Apigee para crear KVM con alcance de entorno encriptados en la IU
• API de mapas clave-valor de la organización
• API de mapas pares clave-valor del entorno
• API de mapas pares clave-valor de proxy de API

Nota: Puedes usar varias operaciones en la misma política. Si lo haces, la política ejecuta las operaciones en orden. Si usas un valor PUT seguido de uno GET en la misma política con la misma clave, el PUT, cuando escribe, restablecerá de forma implícita el vencimiento de la caché. Consulta el elemento ExpiryTimeInSecs para obtener más información.

El tamaño de la clave se limita a 2 KB.

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

Predeterminado	N/A
Presence	Obligatorio si <Get> o <Delete> no están presentes.
Tipo	N/A

Advertencia: Si la política usó el comando PUT para colocar una clave/valor en un KVM con una clave nula, se crea automáticamente la siguiente clave: __$$_EDGE_KVM_EMPTY_KEY_$$__

Esta situación ocurriría, por ejemplo, si propagas una clave con una referencia de variable y la variable a la que se hace referencia es nula. A medida que se intentan nuevos comandos PUT con claves nulas, solo se usa esa clave, por lo que los valores existentes para esa clave se pueden reemplazar cada vez que se ejecute la política.

Atributos

En la siguiente tabla, se describen los atributos del elemento <Put>:

Atributo	Descripción	Predeterminado	Presence
anulación	Si se configura como true, anula el valor de una clave. <Put override="false"> escribirá solo si no hay ninguna entrada conservada en el almacén de KVM para esa clave.	true	Opcional

Elemento <Scope>

Define el límite de accesibilidad para los KVM. El permiso predeterminado es environment, lo que significa que, de forma predeterminada, las entradas de mapa se comparten entre todos los proxies de API que se ejecutan en un entorno (por ejemplo, de prueba o producción). Si estableces el permiso en apiproxy, solo el proxy de la API que escribe los valores en el mapa puede acceder a las entradas en el KVM.

Ten en cuenta que, al acceder a un mapa o a una entrada de mapa, debes especificar el mismo valor de permiso que utilizaste cuando creaste el mapa. Por ejemplo, si el mapa se creó con un permiso de apiproxy, debes usar el permiso apiproxy para recuperar sus valores, realizar cambios o borrar entradas.

<Scope>environment</Scope>

Predeterminado	environment
Presence	Opcional
Tipo	String
Valores válidos	organization environment apiproxy policy (revisión del proxy de API)

Elemento <Value>

Especifica el valor de una clave. Puedes especificar el valor como una string literal o, con el atributo ref, como una variable que se recuperará en el tiempo de ejecución:

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

o:

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

También puedes incluir varios elementos <Value> para especificar un valor de varias partes. Los valores se combinan en el tiempo de ejecución.

En el siguiente ejemplo, se agregan dos claves al KVM:

• Clave k1 con valores v1,v2
• Clave k2 con valores 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>

En el siguiente ejemplo, se crea una clave con dos valores. Supongamos que el nombre de la organización es foo_org, que el nombre del proxy de API es bar y que el entorno es test:

• Clave foo_org con valores bar,test

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

Predeterminado	N/A
Presence	Obligatorio
Tipo	String

Atributos

En la siguiente tabla, se describen los atributos del elemento <Value>:

Atributo	Descripción	Predeterminado	Presence
ref	Especifica el nombre de una variable cuyo valor contiene los valores de clave que deseas establecer.	N/A	Obligatorio si no se proporciona un valor literal entre las etiquetas de apertura y de cierre. Se prohíbe si se proporciona un valor literal.

Referencia de errores

En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Soluciona fallas.

Errores de entorno de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Sugerencia: ¿Necesitas ayuda para resolver un error? Haz clic en en la columna Corregir para obtener información detallada sobre la solución de problemas.

Código de falla	Estado de HTTP	Causa	Corregir
steps.keyvaluemapoperations.UnsupportedOperationException	500	Este error se produce si el atributo mapIdentifier se configuró como una string vacía en la política KeyValueMapOperations.

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.

Sugerencia: ¿Necesitas ayuda para resolver un error? Haz clic en en la columna Corregir para obtener información detallada sobre la solución de problemas.

Nombre del error	Causa	Corregir
InvalidIndex	Si el atributo index especificado en el elemento <Get> de la política KeyValueMapOperations es cero o un número negativo, entonces, la implementación del proxy de API falla. El índice comienza desde 1, por lo que un índice de cero o un número entero negativo se considera no válido.
KeyIsMissing	Este error ocurre si falta el elemento <Key> o falta el elemento <Parameter> dentro del elemento <Key> debajo del <Entry> del elemento <InitialEntries> de la política KeyValueMapOperations.
ValueIsMissing	Este error ocurre si el elemento <Value> falta debajo del elemento <Entry> del elemento <InitialEntries> de la política KeyValueMapOperations.

Esquemas

Muestra: Consulta nuestros repositorios de GitHub para ver los esquemas más recientes.

Notas de uso

Para obtener una descripción general de KVM, consulta Usa mapas clave-valor.

Con la IU de Apigee, puedes definir los KVM solo dentro del permiso del entorno, como se describe en Usa KVM con la IU de Apigee. Con las API de Apigee, puedes definir KVM a nivel de la organización, el entorno o el proxy de API, como se describe en las siguientes secciones:

• API de mapas clave-valor de la organización
• API de mapas pares clave-valor del entorno
• API de mapas pares clave-valor de proxy de API

Un almacén de KVM proporciona un mecanismo de persistencia liviano para datos con formato de pares clave-valor. Puedes acceder a ellas en el entorno de ejecución a través de políticas o código. Un mapa contiene los datos arbitrarios en el formato key=value.

Nota: El tamaño de la clave se limita a 2 KB.

Por ejemplo: localhost=127.0.0.1, zip_code=94110 o first_name=felix. En el primer ejemplo, localhost es una clave y 127.0.0.1 es un valor. Cada par clave-valor se almacena como una entrada en un mapa de clave-valor. Un KVM puede almacenar muchas entradas.

Por ejemplo, supongamos que necesitas almacenar una lista de direcciones IP asociadas con varios entornos de backend. Podrías crear un KVM llamado ipAddresses que contenga una lista de pares clave-valor como entradas. Por ejemplo, este archivo JSON puede representar ese mapa:

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

Puedes usar esta estructura para crear un almacén de direcciones IP que las políticas puedan usar en el entorno de ejecución a fin de habilitar o inhabilitar el bloqueo de IP, seleccionar de forma dinámica una dirección de destino de backend, etcétera. Por lo general, la política KeyValueMapOperations se usa para almacenar o recuperar información de larga duración que se debe reutilizar en varias transacciones de solicitud o respuesta.

Las VM se pueden manipular a través de la política KeyValueMapOperations o directamente a través de la API de Apigee. Puedes usar la API para, por ejemplo, subir grandes conjuntos de datos al almacén clave-valor o crear secuencias de comandos para administrar las entradas de mapas de clave-valor. Deberás crear un KVM con la API antes de acceder a él con la política KeyValueMapOperations.

Especifica y recupera nombres de claves

Con los elementos <Parameter> y <Value>, puedes especificar un valor literal (en el que el valor está entre las etiquetas de apertura y cierre) o usar el atributo ref para especificar el nombre de una variable cuyo valor se debe usar en el entorno de ejecución.

Vale la pena mencionar el elemento <Parameter> porque determina el nombre de la clave que se creará y el nombre que quieres recuperar o borrar. A continuación, se presentan dos ejemplos. El primero especifica un nombre de clave literalmente y el segundo especifica un nombre de clave mediante una variable. Supongamos que se usan las siguientes opciones para crear claves en un KVM:

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

En la primera instancia, el valor literal de KEY_NAME_LITERAL se almacena en el KVM como nombre de clave. En la segunda instancia, cualquier valor que esté en key.name.variable se convierte en el nombre de la clave en el KVM. Por ejemplo, si el key.name.variable contiene el valor foo, la clave se llamaría foo.

Para recuperar la clave y un valor de clave con una operación GET (o quitar con una operación DELETE), el valor del elemento <Parameter> debe coincidir con el nombre de la clave en el KVM. Por ejemplo, si el nombre de la clave en el KVM es my_key, puedes especificar el valor literal con <Parameter>my_key</Parameter> o especificar una variable que contenga el valor exacto mny_key, como este: <Parameter ref="variable.containing.foo"/>.

Nota: El nombre ratelimit está reservado. Para obtener más información, consulta Política de cuota - Arroja NullPointerException.

Temas relacionados

Consulta los siguientes temas para obtener más información sobre los KVM:

• Usa mapas clave-valor
• API de mapas clave-valor de la organización
• API de mapas pares clave-valor del entorno
• API de mapas pares clave-valor de proxy de API