Usa mapas clave-valor

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

En esta sección, se analiza cómo usar mapas de clave-valor (KVM).

Descripción general

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 la API. Los mapas de clave-valor (KVM) son ideales para esto. Una KVM es una colección personalizada de pares de string de claves/valor encriptados.

A continuación, se enumeran tres casos de uso generales para almacenar datos en KVM:

Datos de la sesión del usuario: datos que crea y borra solo el entorno de ejecución. No puedes ver o administrar las entradas de KVM fuera del entorno de ejecución. Por ejemplo, el contenido de un carrito de compras.
Configuración (como reglas de enrutamiento y tablas de búsqueda): Por lo general, los datos se crean fuera del entorno de ejecución, pero el entorno de ejecución los lee. Estos datos se configuran mediante la IU o la API y, luego, se ponen a disposición de la puerta de enlace (como variables o contenido de solo lectura).
Por ejemplo: 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 el proxy de API, puedes detectar la configuración en la que se encuentra, ejecutar la política KeyValueMapOperations relacionada y recuperar la URL de destino correcta desde el KVM correspondiente.

Más adelante, si uno o ambos de tus destinos cambian, simplemente debe actualizar los KVM con las nuevas URL. El proxy de API recoge los valores nuevos y no es necesario volver a implementar el proxy.
Credenciales: Almacena 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 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:

Algunas secciones específicas 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é.

En algunos casos, los conjuntos de propiedades son una buena alternativa a KVM, ya que pueden ser más fáciles de usar. Para obtener más información, consulta Usa conjuntos de propiedades.

Acerca del permiso de KVM

El permiso define dónde está disponible una KVM. Se pueden crear KVM en los siguientes permisos:

Permiso	Descripción
proxy de API	Solo el proxy de API puede acceder a la KVM.
Entorno	Todos los proxies de API en un entorno específico pueden acceder a KVM. Por ejemplo, te recomendamos que los proxies de API implementados en el entorno `prod` no tengan acceso a las KVM en el entorno `test`. Si deseas que las mismas claves de KVM estén disponibles en producción, crea una KVM paralela con alcance al entorno `prod`.
Organización	Todos los proxies de API de todos los entornos pueden acceder a la KVM.

Acerca de la encriptación de KVM

En Apigee, todas las entradas de KVM para el proxy de API, la organización y los alcances del entorno están protegidas con la clave proporcionada en Cloud KMS cuando se aprovisiona una organización de Apigee (consulta runtimeDatabaseEncryptionKey en el recurso de Organización). Apigee usa AES256 como estándar de encriptación.

En Apigee Hybrid, puedes proporcionar claves de encriptación independientes para todas las entradas de KVM para los permisos del proxy de API, la organización y el entorno. Apigee acepta tamaños de cifrado de AES128, AES196 o AES256 como el estándar de encriptación.

Crea KVM

Crea KVM como se describe en las siguientes secciones.

Apigee en la consola de Cloud

Para crear una KVM nueva (vacía) o ver una lista de KVMs, sigue estos pasos:

Abre la IU de Apigee en la consola de Cloud en un navegador.
En el panel de navegación izquierdo, haz clic en Administración > Entornos.
Selecciona el entorno que deseas editar de la lista de entornos disponibles.
Haz clic en la pestaña Mapas clave-valor en la página Detalles del entorno.
La página Mapas de clave-valor muestra una lista de KVM existentes. Si no creaste ninguna KVM, entonces la lista estará vacía.
Para crear una KVM nueva (vacía), haz clic en + Crear mapa de pares clave-valor.
Aparecerá el cuadro de diálogo Agregar mapa de clave-valor.
Ingresa un nombre para la KVM en el campo Nombre del mapa de pares clave-valor.
El nombre solo puede contener letras, números y guiones, y no puede tener más de 255 caracteres. No puede incluir espacios ni otros caracteres especiales. Por ejemplo: my-kvm-1.
Haz clic en Crear.
La nueva KVM se muestra en la lista.

IU de Apigee

Para crear una KVM nueva (vacía) o ver una lista de KVMs, sigue estos pasos:

Accede a la IU de Apigee.
Selecciona Administrador > Entornos > Mapas de clave-valor.
En la lista desplegable del entorno, selecciona el entorno para el que desea crear una KVM.
La página Mapas de clave-valor muestra una lista de KVM existentes. Si no creaste ninguna KVM, entonces la lista estará vacía.
Para crear una KVM nueva (vacía), haz clic en +Mapa de clave-valor.
Aparecerá el cuadro de diálogo Agregar mapa de clave-valor.
Ingresa un nombre para la KVM en el campo Nombre.
El nombre solo puede contener letras, números y guiones. No puede incluir espacios ni otros caracteres especiales. Por ejemplo: my-kvm-1
Haga clic en Add.
La nueva KVM se muestra en la lista.

API de Apigee

Usa las API de Apigee a fin de crear, enumerar y borrar las KVM para los siguientes permisos:

Política de KVM

Para crear KVM en el entorno de ejecución y actualizarlas en tus proxies de API, usa la política KeyValueMapOperations. En la política, especifica el nombre de la KVM en el atributo mapIdentifier 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. Todos los pares clave-valor nuevos se agregan al KVM existente junto con los pares clave-valor existentes.

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

Depuración

Cuando usas la política de KeyValueMapOperations para recuperar los valores encriptados de KVM, debes proporcionar el nombre de una variable a fin de almacenar el valor. Debido a que todos los valores de KVM están encriptados, debes agregar el prefijo private. al nombre de la variable, lo que evita que los pares clave-valor de KVM aparezcan en las sesiones de depuración.

Recupera KVM

Recupera KVM con el elemento <Get> de la política KeyValueMapOperations. Debido a que todos los valores de KVM están encriptados, debes agregar un prefijo private. al nombre de la variable que contendrá el valor recuperado. Ese prefijo oculta el valor de las sesiones de depuración mientras depuras los proxies de API. Para obtener más información, consulta el elemento <Get>.

Borra KVM

Borra KVM como se describe en las siguientes secciones.