Política de operaciones de mapas de clave-valor

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X. Información

Qué

Proporciona acceso basado en políticas a un almacén de mapas de pares clave-valor (KVM) disponible en Apigee Edge. 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. (La política debe realizar al menos una de estas operaciones).

Videos

Mira los siguientes videos para obtener más información sobre los KVM.

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

Referencia del elemento

En la referencia del elemento, se describen los elementos y los atributos de la política 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>

Atributos <KeyValueMapOperations>

En el siguiente ejemplo, se muestran los atributos de la etiqueta <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 específicos de la etiqueta <KeyValueMapOperations>:

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

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>

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 superior. Por ejemplo:

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

Elemento <Entry>

Origina valores para mapas de clave-valor, que se propagan en el mapa de clave-valor cuando se inicializa.

En Edge para la nube pública, 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>

Elemento <ExclusiveCache>

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

Elemento <ExpiryTimeInSecs>

Especifica la duración en segundos después de que Edge actualiza su valor almacenado en caché desde el 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>

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, Edge tiene un mecanismo integrado para almacenar en caché claves/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 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, existen algunas diferencias entre la forma en que las operaciones GET y PUT afectan el vencimiento de la caché.

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

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

PUT: Una operación PUT escribe claves o valores en el KVM especificado. Si el PUT escribe en una clave que ya existe en la caché, esa caché se actualiza de inmediato y ahora contiene el valor nuevo para la cantidad de segundos especificada en el elemento <ExpiryTimeInSecs> de la política.

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é. La <ExpiryTimeInSecs> de la política es 60.
2. Luego de 30 segundos, la política GET se vuelve a ejecutar y recupera el valor "10" de la caché.
3. 5 segundos después, una política PUT actualiza el valor de “calificación” a “8”, y el <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 no hubiera ocurrido la PUT, la caché que propagó la primera solicitud GET seguirá existiendo durante otros 30 segundos, a partir de los 60 segundos originales).
4. 15 segundos después, otra operación GET se ejecuta y recupera un valor de "8".

Elemento <Get>

Recupera el valor de la clave especificada. 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 superior.

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

Obtén un solo elemento de un KVM

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

Aquí hay una configuración de política de KVM que podemos usar para recuperar la película más popular 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 la API, Edge crea las siguientes variables que puedes usar en el flujo del proxy de la API:

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

Atributos

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

<Get assignTo="private.myvar">

Elemento <InitialEntries>

Valores iniciales para los mapas de par clave-valor, que se propagan en el mapa de par clave-valor cuando se inicializa. Asegúrate de especificar el nombre del KVM con el atributo mapIdentifier en el elemento superior, 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 administración en una versión implementada del proxy o implementas el paquete de proxy de API que contiene la política con este elemento, las claves se crean automáticamente en el KVM (como no encriptadas). 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. 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 tanto para perímetro para la nube pública como perimetral para podría ser privada. El valor de KVM está limitado a 2 KB.

Para crear un KVM encriptado, usa la API de administración de mapas de clave-valor.

Elemento <Key>

Especifica la clave en una entrada de mapa de clave-valor. Una clave puede ser compuesta, lo que significa que se puede agregar más de un parámetro para crearla. Por ejemplo, userID y role se pueden combinar para crear una key. Por ejemplo:

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

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

Con Edge para la nube pública, el tamaño de la clave se limita a 2 KB. Consulta Diferencias entre la API de Edge for Public Cloud y la API de Private Cloud para obtener más información.

Elemento <Parameter>

Especifica la clave en un par clave-valor. Este elemento especifica el nombre cuando se crea, coloca, 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 de parámetro, la string de clave efectiva es la concatenación de los valores de cada parámetro unidos con un guion bajo doble. En el ejemplo 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 nombre de la clave en el mapa de clave-valor. Consulta Especifica y recupera nombres de claves para conocer los lineamientos.

Atributos

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

Elemento <Put>

Escribe un par clave-valor en un mapa de clave-valor, independientemente de si el mapa de clave-valor está encriptado o no encriptado. Si el mapa de par clave-valor especificado en el atributo mapIdentifier del elemento superior no existe, el mapa se crea automáticamente (sin encriptar). Si el mapa de clave-valor ya existe, se le agrega la clave-valor.

Para crear un mapa de clave-valor encriptado, usa la API de administración de mapas de clave-valor o consulta Crea y edita mapas de pares clave-valor de entorno para crear KVMs encriptados con alcance de entorno en la IU.

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

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 nuevas PUT con claves nulas, solo se usa esa clave, por lo que es posible que los valores existentes para esa clave se reemplacen cada vez que se ejecute la política.

Atributos

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

Elemento <Scope>

Define el límite de accesibilidad para los mapas de par clave-valor. El permiso predeterminado es environment, lo que significa que, de forma predeterminada, todos los proxies de API que se ejecutan en un entorno (por ejemplo, prueba o producción) comparten las entradas de mapa. Si estableces el alcance en apiproxy, solo el proxy de API que escribe los valores en el mapa podrá acceder a las entradas en el mapa de pares clave-valor.

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>

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>

Atributos

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

Referencia de errores

Los errores que muestran las políticas de Edge siguen un formato coherente, como se describe en la Referencia de códigos de error.

En esta sección, se describen los códigos y mensajes de error que se muestran y las variables de fallas que establece Edge 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 Cómo solucionar fallas.

Errores de entorno de ejecución

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

Errores en la implementación

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

Esquemas

Notas de uso

Para obtener una descripción general de los mapas de pares clave-valor, consulta Trabaja con mapas de pares clave-valor.

Un almacén de asignación de clave-valor 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.

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 mapa de par clave-valor puede almacenar muchas entradas.

Este es un ejemplo del uso de mapas de pares clave-valor. Supongamos que necesitas almacenar una lista de direcciones IP asociadas con varios entornos de backend. Puedes crear un mapa clave-valor 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 en el entorno de ejecución puedan usar para aplicar listas de IP permitidas o de bloqueo, seleccionar dinámicamente una dirección de destino de backend y así sucesivamente. 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.

Los mapas de clave-valor se pueden manipular a través de la política KeyValueMapOperations o directamente a través de la API de administración de Apigee Edge. Consulta la referencia de la API de administración para obtener detalles sobre la API de la API de mapas de clave-valor de la organización. Puedes usar la API, por ejemplo, para subir grandes conjuntos de datos al almacén de pares clave-valor o crear secuencias de comandos para administrar las entradas del mapa de pares clave-valor. Deberás crear un mapa de clave-valor 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.

El elemento Parámetro merece una mención especial, ya que determina el nombre de la clave que se crea, así como el nombre de la clave que deseas 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 el nombre de la 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 key.name.variable contenía el valor foo, la clave se llamaría “foo”.

Cuando deseas recuperar la clave y un valor de clave con una operación GET (o borrar con una operación DELETE), la configuración <Parameter> debe coincidir con el nombre de la clave en el KVM. Por ejemplo, si el nombre de la clave en el KVM es "foo", puedes especificar el valor literal con <Parameter>foo</Parameter> o especificar una variable que contenga el valor exacto "foo", como la siguiente: <Parameter ref="variable.containing.foo"/>

Temas relacionados

• API de mapas clave-valor de la organización