Política de operaciones de mapas de clave-valor

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

Ícono de operaciones de mapas de par clave-valor de la IU de Edge

Qué

Proporciona acceso basado en políticas a un almacén de mapas de par 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 las KVM.

Para videos Descripción
¿Por qué mapas de claves-valor? Aprende por qué necesitas KVM y cómo funcionan.
Crea KVM con la IU y recupera KVM en el tiempo de ejecución Crea un KVM, recupera su valor con una política de KVM y, luego, incorpora el valor en la solicitud a la API con las variables de flujo.
Crea y actualiza un KVM en el entorno de ejecución de la API Crea un KVM en el entorno de ejecución de la API con una política de KVM
Almacena KVM en caché para aumentar el rendimiento Almacena en caché los datos para mejorar el rendimiento de la política de KVM.
Almacena un KVM encriptado Almacena información sensible en KVM en un formato encriptado y recupera el valor en el entorno de ejecución mediante la política de KVM y las variables privadas.
Administra el acceso con el permiso de KVM Restringe KVM a la organización, el entorno, el proxy de API o la revisión del proxy de API con el atributo de permiso de la política de KVM.
Borra entradas de KVM en el entorno de ejecución de la API Borrar entradas de KVM en el entorno de ejecución de API mediante la operación DELETE de la política de 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 configurados con strings de literales foo y bar (sin establecer con valores extraídos de las variables). Cuando GET la clave del siguiente ejemplo, especificas 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>

Tenga en cuenta que el alcance es "entorno". Eso significa que puedes ver la KVM en la IU de administración en API > Configuración del entorno > Mapas de pares 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>

KVM de PUT con una variable

Un ejemplo simple de un mapa de par clave-valor útil es un servicio de abreviación de URL. El mapa de par clave-valor podría configurarse para almacenar URLs acortadas junto con las URLs completas correspondientes.

Esta muestra de política crea un mapa de par clave-valor. La política pone una clave con dos valores asociados en un mapa de clave-valor llamado "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

El siguiente mapa y clave de clave-valor se generará en el almacén de clave-valor de Edge y se definirá en función del 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 almacén de clave-valor se distribuyen en instancias de Edge que ejecutan la nube.

KVM de GET desde una variable

Un ejemplo simple de un mapa de par clave-valor útil es un servicio de "acortamiento" de URL. El mapa de par clave-valor podría configurarse para almacenar URLs acortadas junto con las URLs completas correspondientes.

Para recuperar el valor de una entrada del mapa de clave-valor, como el que se muestra en la pestaña de PUT de KeyValueMapOperations, configura una política para realizar una operación GET en el mapa de clave-valor:

<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 encriptado de GET de KVM

Si un mapa de par clave-valor está encriptado, recupera valores mediante el prefijo “private.” en el valor del atributo assignTo. En este ejemplo, la variable private.encryptedVar contiene el valor desencriptado de la clave foo del mapa de valores clave. Para obtener información sobre cómo crear mapas de clave-valor encriptados, consulta los temas de creación de la API de administración de mapas de claves/valor.

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


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

Atributo Descripción Predeterminada Presencia
mapIdentifier

Especifica un identificador que se usará para acceder a un mapa creado por esta política o en la IU de administración.

El nombre de KVM distingue mayúsculas de minúsculas con Apigee Edge para la nube pública. Por ejemplo, foobar es diferente de FooBar.

Si excluyes este atributo, se usará una KVM llamada kvmap.

Dentro de un permiso de organización/entorno/apiproxy, puedes usar el atributo mapIdentifier para especificar tu propio nombre de mapa.

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

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

verdadero Opcional
async

Este atributo dejó de estar disponible.

falso Funciones obsoletas

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

N/A

Si omites este elemento, se usa el valor del atributo name de la política.

Presencia Opcional
Tipo Cadena

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>
Predeterminada N/A
Presencia Obligatorio si <Get> o <Put> no están presentes.
Tipo N/A

Elemento <Entry>

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

En el caso de 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>
Predeterminada N/A
Presencia Opcional
Tipo N/A

Elemento <ExclusiveCache>

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

Elemento <ExpiryTimeInSecs>

Especifica la duración en segundos después de la que Edge actualiza el 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>
Predeterminada 300 (5 minutos)
Presencia Opcional
Tipo Número 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, Edge tiene un mecanismo integrado para almacenar en caché los pares clave-valor 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 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 (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 para la cantidad de segundos especificados 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é. El <ExpiryTimeInSecs> en la política es 60.
  2. 30 segundos después, la política GET se vuelve a ejecutar y recupera "10" de la caché.
  3. 5 segundos después, una política PUT actualiza el valor de "rating" 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 PUT no hubiera ocurrido, la caché propagada originalmente por el primer GET seguiría existiendo durante otros 30 segundos, sobrante 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.

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

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.

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

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

Atributo Descripción Predeterminada Presencia
assignTo

Variable a la que se debe asignar el valor recuperado.

Si el mapa de clave-valor está encriptado, comienza el nombre assignTo con "private.". Por ejemplo:

<Get assignTo="private.myvar">

La política arroja un error si intentas recuperar un mapa de clave-valor encriptado sin usar el prefijo. El prefijo, que es necesario para fines de seguridad básicos durante la depuración, oculta los valores encriptados de las sesiones de depuración y de seguimiento del proxy de API.

Si deseas obtener información sobre cómo crear mapas de clave-valor encriptados, consulta los temas "crear" de la API de administración de mapas de clave-valor y Crea y edita mapas de clave-valor del entorno.

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 “Obtén un valor encriptado de KVM” en Muestras.

N/A Opcional

Elemento <InitialEntries>

Valores iniciales para los mapas de clave-valor, que se propagan en el mapa de pares clave-valor cuando se inicializa. Asegúrate de especificar el nombre de la 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 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 se limita a 2 KB en Edge para la nube pública y en Edge para la operación Private. El valor de KVM se limita a 2 KB.

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

Predeterminada N/A
Presencia Opcional
Tipo N/A

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 consultar 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. Si deseas obtener más información, consulta Diferencias entre las API de Edge para la nube pública y de nube privada.

Predeterminada N/A
Presencia Opcional
Tipo N/A

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 Parameter, la string de clave eficaz es la concatenación de los valores de cada parámetro, unidos a un guion bajo doble. Por ejemplo, en el ejemplo anterior, si la variable apiproxy.name tiene el valor "abc1", la clave vigente 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 correspondiente. Consulta Especifica y recupera nombres de claves para conocer los lineamientos.

Predeterminada N/A
Presencia Obligatorio
Tipo Cadena

Atributos

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

Atributo Descripción Predeterminada Presencia
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. Se prohíbe si se proporciona un valor literal.

Elemento <Put>

Escribe un par clave-valor en un mapa de par clave-valor, ya sea que esté encriptado o no. Si el mapa de clave-valor especificado en el atributo mapIdentifier del elemento superior no existe, el mapa se crea automáticamente (como 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 claves/valor o consulta Crea y edita mapas de par clave-valor del entorno a fin de crear KVM con permiso para el entorno encriptado en la IU.

<Put override="false">         
   <Key>             
      <Parameter ref="mykeyvar"/>         
   </Key>         
   <Value ref="myvalvar1"/>     
</Put>
Predeterminada N/A
Presencia Obligatorio si <Get> o <Delete> no están presentes.
Tipo N/A

Atributos

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

Atributo Descripción Predeterminada Presencia
Anulación

Si se configura como true, anula el valor de una clave.

false Opcional

Elemento <Scope>

Define el límite de accesibilidad para mapas de valores clave. 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 configuras el permiso en apiproxy, solo el proxy de API que escribe los valores en el mapa podrá acceder a las entradas del 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>
Predeterminada environment
Presencia Opcional
Tipo Cadena
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>
Predeterminada N/A
Presencia Obligatorio
Tipo Cadena

Atributos

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

Atributo Descripción Predeterminada Presencia
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

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

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

Código de falla Estado de HTTP Causa Corregir
steps.keyvaluemapoperations.SetVariableFailed 500

Este error ocurre si intentas recuperar un valor de un mapa de clave-valor encriptado y establecer el valor en una variable cuyo nombre no tiene el prefijo private. El prefijo, que es necesario para fines de seguridad básicos durante la depuración, oculta los valores encriptados de las sesiones de depuración y de seguimiento del proxy de API.

steps.keyvaluemapoperations.UnsupportedOperationException 500

Este error ocurre si el atributo mapIdentifier se establece como una string vacía en la política de operaciones de mapas de pares clave-valor.

Errores en la implementación

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

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

Esquemas

Notas de uso

Para obtener una descripción general de los mapas de clave-valor, consulta Cómo trabajar con mapas de par clave-valor.

Un almacén de mapas 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 de cómo usar los mapas de clave-valor. Supongamos que necesitas almacenar una lista de direcciones IP asociadas con varios entornos de backend. Puedes crear un mapa de par 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 pueden usar las políticas en el entorno de ejecución para aplicar la lista de IP permitidas o de bloqueo, seleccionar una dirección de destino de backend de forma dinámica, 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 de clave-valor se pueden manipular mediante 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 clave-valor de la organización. Puedes usar la API para, por ejemplo, subir conjuntos de datos grandes al almacén de clave-valor o crear secuencias de comandos a fin de administrar las entradas de mapas 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 Parameter merece una mención especial, ya que determina el nombre de la clave que se crea, así como el nombre de 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 la KVM como 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 KVM. Por ejemplo, si la key.name.variable contiene el valor foo, la clave se llamará “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