Trabaja con mapas de clave-valor

Estás viendo la documentación de Apigee Edge.
Ir a la documentación de Apigee X. info

Hay momentos en los que deseas almacenar datos para recuperarlos durante el entorno de ejecución, datos que no vencen y que no deben estar hard-coded en la lógica del proxy de API. Los mapas de clave-valor (KVM) son ideales para esto. Un KVM es una colección personalizada de pares de string de clave-valor que puede o no estar encriptado. A continuación, presentamos dos ejemplos:

Para obtener información sobre otros tipos de persistencia, consulta Agrega almacenamiento en caché y persistencia.

Situaciones de KVM

Estas son algunas situaciones en las que los KVM son útiles:

• Tienes un proxy de API que necesita llamar a una URL de destino (o texto destacado del servicio) en un entorno de prueba y otra URL de destino en un entorno de producción. En lugar de codificar URL en tu proxy, puedes hacer que el proxy detecte en qué entorno se encuentra, ejecutar la política de operaciones de mapa de valor clave relacionada y recuperar la URL de destino correcta de uno de los KVM que creaste. Más adelante, si uno o ambos de sus destinos cambian, simplemente debe actualizar los KVM con las nuevas URL. El proxy recoge los valores nuevos y no es necesario volver a implementar el proxy.
• Deseas almacenar credenciales, claves privadas o tokens, como tokens de servicios externos , credenciales necesarias para generar tokens OAuth o claves privadas usadas en textos destacados de Java o JavaScript para encriptación o firma de token web JSON (JWT). En lugar de pasar credenciales, claves o tokens en la solicitud, o codificarlos en la lógica del proxy, puedes almacenarlos en un KVM (siempre encriptado) y recuperarlos de forma dinámica en las llamadas a los destinos que los requieren.

Descubrirás otras situaciones en las que el almacenamiento de pares de string de clave-valor es útil. En general, considera usar KVM en los siguientes casos:

• Algunos lugares específicos de tu código requieren diferentes valores en el entorno de ejecución.
• Se deben pasar datos sensibles sin codificarlos.
• Deseas almacenar valores que no tengan vencimiento como una caché.

Los KVM tienen permisos

El permiso significa “dónde está disponible una KVM”. Se pueden crear KVM en los siguientes permisos: organization, environment y apiproxy.

Por ejemplo, si solo un proxy de API requiere datos en un KVM, puedes crear el KVM en el apiproxy permiso, donde solo ese proxy de API puede acceder a los datos.

O deseas que todos los proxies de API de tu entorno de prueba tengan acceso a un mapa de clave-valor. En este caso, crearías un mapa de clave-valor en el permiso del entorno. Los proxies implementados en el entorno “prod” no pueden acceder a las KVM en el permiso del entorno de “prueba”. Si quieres que las mismas claves de KVM estén disponibles en producción, crea un KVM paralelo con el alcance del entorno “prod”.

Si deseas que todos los proxies de todos los entornos accedan al mismo KVM, crea el KVM en el alcance organization

Acerca de las KVM encriptadas

Las KVM encriptadas se encriptan con una clave de texto cifrado AES-128 generada por Apigee. La clave que se usa para encriptar una KVM se almacena en el permiso de la KVM. Por ejemplo, dentro de una organización, todas las KVM encriptadas que creas en el alcance del entorno se crean con la misma clave de permiso del entorno.

Edge administra la visualización de valores encriptados de las siguientes maneras. (Consulta Administra y usa KVM para obtener información sobre cómo crear KVM encriptados).

IU de Edge

Los mapas de clave-valor encriptados muestran valores enmascarados con asteriscos en la IU (*****). Por ejemplo:

API de Management

En la API de administración, los valores encriptados se muestran enmascarados. A continuación, se muestra un ejemplo de respuesta de la API de administración en una llamada GET de un KVM encriptado:

{
  "encrypted": true,
  "entry": [
    {
      "name": "Key1",
      "value": "*****"
    },
    {
      "name": "Key2",
      "value": "*****"
    }
  ],
  "name": "secretMap"
}

Seguimiento y depuración

Cuando usas la política de operaciones de mapa de valor clave para recuperar los valores encriptados de KVM, debes proporcionar el nombre de una variable para almacenar el valor. Para obtener un valor encriptado, debes agregar el prefijo "private." al nombre de la variable, lo que evita que las claves o valores de KVM aparezcan en las sesiones de Trace y depuración.

Límites

En organizaciones con Core Persistence Services (CPS) habilitado:

• El nombre o identificador de KVM distingue mayúsculas de minúsculas.
• El tamaño de la clave se limita a 2 KB.
• El tamaño del valor se limita a 10 KB.

En Apigee Edge para la nube privada, cada KVM no debe exceder los 15 MB (este es el tamaño combinado de las claves y los valores). Si superas este límite, Apigee Edge para la nube privada muestra un error. Para determinar el tamaño de tus KVM, puedes usar el comando nodetool cfstats.

Los KVM más grandes pueden provocar una degradación del rendimiento. Como resultado, debes dividir los KVM grandes y monolíticos en otros más pequeños para mejorar el rendimiento.

Administra y usa KVM

Puedes crear, administrar y usar KVM de varias maneras. En esta sección, se describen diferentes opciones para crear y, luego, recuperar KVM encriptados y no encriptados.

Crea y actualiza KVM

Puedes crear y actualizar KVM de las siguientes maneras:

• Política de operaciones de mapa de valor clave (sin encriptación)

  Para que los proxies de tu API creen y actualicen KVM de entornos de ejecución, usa la política de operaciones de mapa de valor clave. (en la política, especifica el nombre del KVM en el mapIdentifier atributo en el elemento superior ).

  El elemento <InitialEntries> te permite crear y propagar un conjunto de entradas de referencia en un KVM nuevo en cuanto guardes la política en la IU o implementes el proxy de API (si la desarrollas sin conexión). Si los valores cambian en la política, los valores existentes se reemplazan. Todas las claves/valores nuevas se agregan al KVM existente junto con las claves/valores existentes.

  El elemento <Put> crea una KVM nueva si aún no existe y crea una clave con uno o más valores. Si el KVM ya existe, se agregan claves o valores (o se actualizan si la clave ya existe). Puedes usar varios <Put> elementos en una política de KVM.

• API de Management

  La API de administración es para trabajar con KVM como administrador en lugar de durante el entorno de ejecución en tus proxies de API. Por ejemplo, es posible que tengas una secuencia de comandos interna que use la API de administración para borrar y volver a crear KVM en un entorno de prueba, o que desees restablecer el valor de una clave en un KVM para que todos los proxies la recuperen. (Para la manipulación en el entorno de ejecución de KVM, usa la política de operaciones de mapa de valor clave en tus proxies).

  La API de administración de mapas de clave-valor te permite crear, actualizar y borrar KVM y claves o valores encriptados en todos los permisos (organización, entorno y apiproxy).

  Para crear un KVM encriptado con la API de administración, agrega "encrypted" : "true" a la carga útil JSON. Solo puedes encriptar KVM cuando los creas them. No puedes encriptar un KVM existente.

• IU de administración

  En la IU de administración de Edge, puedes crear y actualizar KVM con alcance de entorno, que son el único alcance de KVM que aparece en la IU. La IU de administración es una buena manera de administrar manualmente los datos de KVM para los proxies de API en el entorno de ejecución. Consulta Crea y edita mapas de clave-valor del entorno para obtener más información.

Recupera KVM

Recuperas mapas de clave-valor encriptados y no encriptados de la misma manera, con una pequeña variación cuando recuperas con la política de operaciones de mapa de valor clave.

• Política: Usa el elemento <Get> en la política de operaciones de mapa de valor clave para recuperar KVM encriptados y no encriptados. La única diferencia es recuperar valores encriptados con la política, en la que debes agregar un prefijo "private." al nombre de la variable que contendrá el valor recuperado, como se describe en el Obtener sección de operaciones del tema de referencia. Ese prefijo oculta el valor de las sesiones de Trace y depuración mientras depuras los proxies de API.
• API de Management: Para fines de administración, puedes usar Crea y edita mapas de clave-valor del entorno para obtener KVM y claves o valores. Por ejemplo, si deseas hacer una copia de seguridad de los KVM obteniendo y almacenando las definiciones de JSON, usa la API de administración. Sin embargo, ten en cuenta que los valores encriptados se muestran como ***** en la respuesta de la API.
• IU de administración: Para ver tus KVM con alcance de entorno en la IU de administración, ve a APIs > Environment Configuration > Key Value Maps (Edge clásico) o Admin > Environments > Key Value Maps (Edge nuevo).

Ejemplo de KVM

Para ver un ejemplo del uso de un KVM para propagar valores en una URL, consulta URL de destino de plantilla con KVM por entorno.