Política de KeyValueMapOperations

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 eliminar de mapas con nombre ya creados configurando políticas KeyValueMapOperations que especifiquen 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 su uso puede tener implicaciones en cuanto a costes o utilización, en función de tu licencia de Apigee. Para obtener información sobre los tipos de políticas y las implicaciones de uso, consulta Tipos de políticas.

Ejemplos

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

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

<KeyValueMapOperations>

Proporciona acceso basado en políticas a un mapa de valores de clave (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 de <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>:

En la siguiente tabla se describen los atributos que son comunes a todos los elementos superiores de la política:

Elemento <DisplayName>

Úsalo junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.

<DisplayName>Policy Display Name</DisplayName>

Elementos secundarios

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

Elemento <Delete>

Elimina el par clave-valor especificado. Debe usarse 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>

Elemento <Entry>

Valores de inicialización de KVMs, que se rellenan en el KVM cuando se inicializa. En Apigee, el tamaño de la clave está limitado 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>

Elemento <ExclusiveCache>

Obsoleto. Usa el elemento <Scope> en su lugar.

Elemento <ExpiryTimeInSecs>

Especifica la duración en segundos tras la cual Apigee actualiza el valor almacenado en caché del KVM especificado.

Si se asigna el valor 0 o -1, o si se excluye este elemento, se usará el valor predeterminado de 300 segundos. Por ejemplo:

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

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

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

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

• El número de segundos especificado en <ExpiryTimeInSecs> caduca.
  o
• Una operación PUT en una política de KVM sobrescribe los valores existentes (se explica a continuación).

PUT: una operación PUT escribe claves o valores en el KVM especificado. Si PUT escribe en una clave que ya existe en la caché, esa caché se actualiza inmediatamente y ahora contiene el nuevo valor durante el número de segundos especificado en el elemento <ExpiryTimeInSecs> de la política. Sin embargo, al usar PUT, solo se actualizará la caché en el nodo de tiempo de ejecución único que atiende la solicitud. Para actualizar la caché en cada nodo de tiempo de ejecución distribuido, usa el elemento <ExpiryTimeInSecs> para especificar los intervalos de actualización de cada nodo.

Ejemplo: almacenamiento en caché de un KVM

1. Una operación GET obtiene el valor de "rating", que añade el valor "10" a la caché. El <ExpiryTimeInSecs> de la política es 60.
2. Treinta segundos después, la política GET se vuelve a ejecutar y obtiene 10 de la caché.
3. Cinco segundos después, una política PUT actualiza el valor de rating a 8 y el <ExpiryTimeInSecs> de la política PUT es 20. La caché se actualiza inmediatamente con el nuevo valor, que ahora se ha configurado para que permanezca en la caché durante 20 segundos. Si no se hubiera producido el PUT, la caché rellenada originalmente por el primer GET seguiría existiendo durante otros 30 segundos, que son los que quedaban de los 60 segundos originales.
4. Quince segundos después, se ejecuta otro GET y obtiene el valor 8.

Elemento <Get>

Obtiene el valor de la clave especificada. Debe usarse al menos uno de los siguientes valores: <Get>, <Put> o <Delete>.

Apigee cifra todos los datos almacenados en el KVM. Para obtener más información, consulta el artículo Acerca de las claves de cifrado. Cuando se usa <Get>, Apigee descifra los datos almacenados y los asigna a una variable en el contexto del mensaje. El nombre de la variable se especifica mediante 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>.

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

Atributos

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

Obtener un solo elemento de un KVM

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

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

Excluir datos obtenidos de sesiones de depuración

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

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

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

Obtener varios elementos de un KVM

En el siguiente ejemplo, supongamos que hay un KVM con las siguientes claves y valores. Además de almacenar una lista actualizada de las películas más populares de todos los tiempos, el KVM almacena el nombre del director de todas las películas importantes.

Verá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 obtiene la película más popular 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 los 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, ya que el primer elemento <Get> usa un atributo index de 1. A continuación, el segundo elemento <Get> usa el valor asignado a top.movie.pick como clave para obtener un valor en movie.director.

Elemento <InitialEntries>

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

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 se usa este elemento y se guarda la política en la interfaz de usuario de Apigee en una versión implementada del proxy de API, o bien se implementa el paquete del proxy de API que contiene la política con este elemento, las claves se crean automáticamente en el KVM. Si los valores de la política son diferentes de los valores del KVM, los valores del KVM se sobrescriben cuando se implementa el proxy de API. Las nuevas claves o valores se añaden al KVM junto con los que ya había.

Las claves y los valores rellenados por este elemento deben ser literales. Por ejemplo, <Parameter ref="request.queryparam.key"> no se admite en este elemento.

El tamaño de la clave está limitado a 2 KB.

Elemento <Key>

Especifica la clave de una entrada KVM. Este elemento aparece como elemento secundario de <Get>, <Put> o <Delete>, o bien como elemento secundario del elemento <Entry>, que es un elemento secundario de <InitialEntries>. A continuación, se muestra un ejemplo de clave fija:

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

Una clave puede ser compuesta y tener elementos dinámicos, lo que significa que se puede añadir más de un <Parameter> para crear la clave. Por ejemplo, el contenido de las variables userID y role se puede combinar para crear una clave dinámica. A continuación, se muestra un ejemplo de configuración de un paso que especifica una clave compuesta determinada dinámicamente:

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

Consulte el elemento <Parameter> para obtener información específica sobre cómo definir el nombre de la clave.

El tamaño de la clave está limitado a 2 KB.

Elemento <MapName>

El elemento <MapName> permite que la política identifique qué KVM se debe usar de forma dinámica en el tiempo de ejecución. La posibilidad de seleccionar KVMs de forma dinámica te ofrece la flexibilidad de diseñar una política KeyValueMapOperations que pueda acceder a diferentes KVMs en función del contexto en el que se ejecute la política.

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 de KVM como una cadena 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 en un valor vacío, se usa la cadena literal en su lugar.

No especifique el atributo mapIdentifier si utiliza <MapName> en su 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, no se creará y Apigee generará un error de tiempo 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 al crear, actualizar, obtener o eliminar el par clave-valor.

Puedes especificar el nombre de las siguientes formas:

• Una cadena literal

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

• 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 cadena de clave efectiva es la concatenación de los valores de cada parámetro, unidos con dos guiones bajos. Por ejemplo, en el ejemplo anterior, si la variable apiproxy.name tiene el valor abc1, la clave efectiva será targeturl__abc1__weight.

Tanto si obtienes, actualizas o eliminas una entrada de clave/valor, el nombre de la clave debe coincidir con el nombre de la clave del KVM. Consulta las directrices en el artículo Especificar y recuperar nombres de claves.

Atributos

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

Elemento <Put>

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

Para crear un KVM mediante la interfaz de usuario o la API, consulta lo siguiente:

• Usar KVMs con la interfaz de usuario de Apigee para crear KVMs cifrados con ámbito de entorno en la interfaz de usuario
• API de mapas de valores clave con ámbito de organización
• API de mapas de valores clave con ámbito de entorno
• API de mapas de valores clave con ámbito de proxy de API

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

Atributos

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

Elemento <Scope>

Define el límite de accesibilidad de los KVMs. El ámbito predeterminado es environment, lo que significa que, de forma predeterminada, todas las entradas de los mapas se comparten entre todos los proxies de API que se ejecutan en un entorno (por ejemplo, de prueba o de producción). Si asignas el valor apiproxy al ámbito, solo podrá acceder a las entradas del KVM el proxy de API que escriba los valores en el mapa.

Ten en cuenta que, para acceder a un mapa o a una entrada de un mapa, debes especificar el mismo valor de ámbito que usaste al crear el mapa. Por ejemplo, si el mapa se ha creado con el ámbito apiproxy, debe usar el ámbito apiproxy al recuperar sus valores, hacer cambios o eliminar entradas.

<Scope>environment</Scope>

Elemento <Value>

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

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

También puedes hacerlo de esta otra forma, si lo prefieres:

<!-- 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 añaden 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, el nombre del proxy de API es bar y 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>

Atributos

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

Referencia de errores

En esta sección se describen los códigos de error y los mensajes de error que se devuelven, así como las variables de error que define Apigee cuando esta política activa un error. Es importante que conozcas esta información si vas a desarrollar reglas de errores para gestionarlos. Para obtener más información, consulta Qué debes saber sobre los errores de las políticas y Cómo gestionar los fallos.

Errores de tiempo de ejecución

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

Errores de implementación

Estos errores pueden producirse al implementar un proxy que contenga esta política.

Esquemas

Notas de uso

Para obtener una descripción general de los mapas de clave-valor, consulte el artículo Usar mapas de clave-valor.

Con la interfaz de usuario de Apigee, solo puedes definir KVMs en el ámbito del entorno, tal como se describe en el artículo Usar KVMs con la interfaz de usuario de Apigee. Con la API de Apigee, puedes definir KVMs en el ámbito de la organización, el entorno o el proxy de API, tal como se describe en las siguientes secciones:

• API de mapas de valores clave con ámbito de organización
• API de mapas de valores clave con ámbito de entorno
• API de mapas de valores clave con ámbito de proxy de API

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

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 valores de clave. Un KVM puede almacenar muchas entradas.

Por ejemplo, supongamos que necesitas almacenar una lista de direcciones IP asociadas a varios entornos de backend. Puedes crear un KVM llamado ipAddresses que contenga una lista de pares clave/valor como entradas. Por ejemplo, este JSON puede representar un mapa de este tipo:

{
  "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 tiempo de ejecución para aplicar listas de permitidas o denegadas de IPs, seleccionar dinámicamente una dirección de destino de backend, etc. Normalmente, la política KeyValueMapOperations se usa para almacenar o recuperar información duradera que se debe reutilizar en varias transacciones de solicitud/respuesta.

Los KVMs se pueden manipular mediante la política KeyValueMapOperations o directamente a través de la API de Apigee. Puede usar la API para, por ejemplo, subir grandes conjuntos de datos al almacén de clave/valor o crear secuencias de comandos para gestionar 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.

Especificar y obtener nombres de clave

Con los elementos <Parameter> y <Value>, puede especificar un valor literal (donde el valor se encuentra 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 tiempo de ejecución.

El elemento <Parameter> merece una mención especial, ya que determina el nombre de la clave que se crea, así como el nombre de la clave que quieres recuperar o eliminar. A continuación, se muestran dos ejemplos. La primera especifica un nombre de clave literalmente y la segunda especifica un nombre de clave mediante una variable. Supongamos que se usan los siguientes elementos para crear claves en un KVM:

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

En el primer caso, el valor literal de KEY_NAME_LITERAL se almacena en el KVM como nombre de clave. En el segundo caso, el valor que haya en key.name.variable se convierte en el nombre de la clave del KVM. Por ejemplo, si key.name.variable contiene el valor foo, la clave se llamará foo.

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

Temas relacionados

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

• Usar mapas de clave-valor
• API de mapas de valores clave con ámbito de organización
• API de mapas de valores clave con ámbito de entorno
• API de mapas de valores clave con ámbito de proxy de API