Política de operaciones de mapas de clave-valor

Estás viendo la documentación de Apigee Edge.
Ve a la Documentación de Apigee X. información

Qué

Proporciona acceso basado en políticas a un almacén de mapa de 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 luego de la cual Edge actualizará su valor almacenado en caché desde la 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. Para mejorar 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 de 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 cómo 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 (lo que se explica a continuación).

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

Ejemplo: Almacenamiento en caché de un KVM

1. Una operación GET recupera el valor de “rating”, lo que suma el valor "10" en 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". en "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 el comando PUT no hubiera ocurrido, la caché que propagó originalmente el primer GET seguirá existiendo para otro 30 segundos restantes respecto 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 API, Edge crea los siguientes variables que puedes usar en el flujo del proxy de 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 de 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 de KVM con el atributo mapIdentifier activado 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, guardas la política en la IU de administración en una versión implementada del proxy o implementa el paquete del proxy de API que contiene la política con este elemento, las claves se crean automáticamente en el KVM (como sin encriptar). 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 está limitado a 2 KB para Edge para la nube pública y Periférico para lo privado. El valor de KVM está limitado a 2 KB.

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

Elemento <Key>

Especifica la clave en una entrada de mapa de par 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 &lt;Parameter&gt; para obtener información específica sobre cómo establecer 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 perimetral para la nube pública y la API de nube privada 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 recuperar o borrar 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 clave incluye varios elementos de parámetro, la cadena de clave vigente es concatenación de los valores de cada parámetro, unida con un guion bajo doble. Por ejemplo, en En el ejemplo anterior, si la variable apiproxy.name tiene el valor "abc1", el la clave efectiva será targeturl__abc1__weight.

Ya sea que desees obtener, actualizar o borrar una entrada de par clave-valor, el nombre de la clave debe coincidir con la nombre de la clave en el mapa de par 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, ya sea que el mapa de clave-valor esté encriptado o y sin encriptar. Si el mapa de par clave-valor especificado en el atributo mapIdentifier de la 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 par clave-valor encriptado, usa la API de administración de mapas de par clave-valor o consulta Crea y edita mapas de pares clave-valor del entorno. para crear KVM con alcance de entorno encriptado en la IU.

<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 para los mapas de pares clave-valor. El permiso predeterminado es environment: Esto significa que, de forma predeterminada, todos los proxies de API comparten las entradas de Maps que se ejecutan en un entorno (por ejemplo, prueba o producción). Si estableces el alcance en apiproxy, solo podrá acceder a las entradas en el mapa de par clave-valor el proxy de API que escribe los valores en el mapa.

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 tienen un formato coherente, como se describe en la Referencia de código 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 par clave-valor, consulta Cómo trabajar con mapas de par clave-valor.

Un almacén de mapas de par clave-valor proporciona un mecanismo de persistencia ligero para datos formateados como 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.

A continuación, se muestra un ejemplo del uso de mapas de pares clave-valor. Supongamos que necesitas almacenar una lista de direcciones IP asociados a varias infraestructuras entornos de prueba. Podrías crear un mapa de par clave-valor llamado ipAddresses que contenga un 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"
}

Podrías usar esta estructura para crear un almacén de direcciones IP que las políticas podrían usar en el entorno de ejecución para aplicar de manera forzosa la lista de entidades permitidas o las listas de bloqueo de IP para seleccionar dinámicamente un destino de backend dirección, 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.

Los mapas clave-valor pueden manipularse con 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 mapas clave-valor de la organización. Puedes usar la API para Por ejemplo, subir grandes conjuntos de datos al almacén de pares clave-valor o crear secuencias de comandos para administrar pares clave-valor entradas de mapa. Deberás crear un mapa de par clave-valor con la API antes de acceder a él con el 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 del parámetro merece una mención especial, ya que determina el nombre de la clave que y el nombre de la clave 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 la clave de la fuente de datos. En la segunda instancia, cualquier valor que esté en key.name.variable se convierte en nombre de la clave en el KVM. Por ejemplo, si key.name.variable incluyera la 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