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 políticas de JavaCallout 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:

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

Acerca del enmascaramiento de KVM

De forma predeterminada, los valores de KVM se muestran como texto sin formato. Puedes activar el enmascaramiento de KVM para enmascarar valores con asteriscos (*****). Para activar o desactivar el enmascaramiento de KVM, usa el parámetro de configuración Mask values en la IU o la marca maskedValues en tu solicitud a la API.

Los valores se enmascaran a nivel del KVM. No puedes enmascarar entradas de KVM individuales; todos los valores dentro de un KVM están enmascarados o ninguno lo está.

Nota: El enmascaramiento de KVM no se activará automáticamente para los KVM existentes. Deberás actualizar de forma explícita los KVM existentes para usar el enmascaramiento de KVM.

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:

  1. En la consola de Google Cloud , ve a la página Administración > Entornos.

    Ir a Entornos

  2. Selecciona el entorno que deseas editar de la lista de entornos disponibles.
  3. 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.

  4. Para crear una KVM nueva (vacía), haz clic en + Crear mapa de pares clave-valor.

    Se abrirá el diálogo Crear mapa de clave-valor.

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

  6. Haz clic en Enmascarar valores para enmascarar todos los valores. Si no se selecciona, los valores de KVM se muestran en texto sin formato. Consulta Acerca del enmascaramiento de KVM para obtener más información.
  7. Haz clic en Crear.

    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.

Depurar

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.

Obtén KVM

Usa las APIs de Apigee para obtener KVM para los siguientes permisos:

Por ejemplo, para obtener un KVM con alcance de proxy de API, ingresa una solicitud GET a la siguiente URL:

https://apigee.googleapis.com/v1/organizations/ORG/apis/API/keyvaluemaps/KVM

Actualiza KVM

Usa las APIs de Apigee para actualizar los KVM para los siguientes permisos:

Por ejemplo, para obtener un KVM con alcance de proxy de API, ingresa una solicitud GET a la siguiente URL:

https://apigee.googleapis.com/v1/organizations/ORG/apis/API/keyvaluemaps/KVM

Administra los valores de KVM

Puedes administrar los valores de KVM con la API o la política KeyValueMapOperations, como se describe en las siguientes secciones.

Administra valores de KVM con la API

Usa las APIs de Apigee para administrar los valores de KVM para los siguientes permisos:

Administra los valores de KVM con la política KeyValueMapOperations

Usa la política KeyValueMapOperations para agregar, obtener o borrar valores de KVMs.

Agrega claves y valores de KVM con el elemento <Put> de la política KeyValueMapOperations. 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 los pares clave-valor (o se actualizan si la clave ya existe). Puedes usar varios elementos <Put> en una política de KVM. Para obtener más información, consulta el elemento<Put>.

Obtén valores de 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 los valores de KVM con el elemento <Delete> de la política KeyValueMapOperations. Para obtener más información, consulta el elemento<Delete>.

Borra KVM

Borra KVM como se describe en las siguientes secciones.

Apigee en la consola de Cloud

Para borrar una KVM, haz lo siguiente:

  1. En la consola de Google Cloud , ve a la página Administración > Entornos.

    Ir a Entornos

  2. Selecciona el nombre del entorno que deseas editar de la lista de entornos disponibles.
  3. 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.

  4. Busca la fila de la KVM que deseas borrar.
  5. Haz clic en en la columna Acciones.
  6. Haz clic en Borrar mapa de pares clave-valor en el cuadro de diálogo para confirmar la operación.

    El KVM se borra y se quita de la lista.

IU clásica de Apigee

Para borrar una KVM, haz lo siguiente:

  1. Accede a la IU de Apigee.
  2. Selecciona Administrador > Entornos > Mapas de clave-valor.
  3. En la lista desplegable del entorno, selecciona el entorno en el que quieres borrar una KVM.

    La página Mapas de clave-valor muestra una lista de KVM existentes.

  4. Coloca el cursor sobre la KVM que deseas borrar.
  5. Haz clic en Borrar.
  6. Haz clic en Borrar para confirmar la operación.

    El KVM se borra y se quita de la lista.

API de Apigee

Usa una de las siguientes API de Apigee para borrar una KVM según su permiso: