Esta página se aplica a Apigee y Apigee Hybrid.
Consulta la documentación de
Apigee Edge.
En esta sección se explica cómo usar los mapas de clave-valor (KVMs).
Información general
Hay ocasiones en las que quieres almacenar datos para recuperarlos en el tiempo de ejecución. Se trata de datos que no caducan y que no deben estar codificados en la lógica de tu proxy de API. Los mapas de pares clave-valor (KVMs) son ideales para ello. Un KVM es una colección personalizada de pares de cadenas clave/valor cifrados.
A continuación, se enumeran tres casos prácticos generales para almacenar datos en KVMs:
- Datos de sesión de usuario: datos que solo crea y elimina el tiempo de ejecución. No puedes ver ni gestionar entradas de KVM fuera del tiempo de ejecución. Por ejemplo, el contenido del carrito de la compra.
- Configuración (como reglas de enrutamiento y tablas de consulta): datos que normalmente se crean fuera del tiempo de ejecución, pero que el tiempo de ejecución lee. Estos datos se configuran mediante la interfaz de usuario o la API y, a continuación, se ponen a disposición de la pasarela (como variables o contenido de solo lectura).
Por ejemplo, tienes un proxy de API que necesita llamar a una URL de destino (o de llamada de servicio) en un entorno de prueba y a otra URL de destino en un entorno de producción. En lugar de codificar URLs de forma rígida en tu proxy de API, puedes hacer que detecte en qué entorno se encuentra, ejecute la política KeyValueMapOperations relacionada y recupere la URL de destino correcta del KVM adecuado.
Más adelante, si cambia uno de los dos objetivos o ambos, solo tienes que actualizar los KVMs con las nuevas URLs. El proxy de la API adoptará los nuevos valores y no será necesario volver a implementarlo.
- Credenciales: almacena credenciales, claves privadas o tokens, como tokens de servicios externos, credenciales necesarias para generar tokens de OAuth o claves privadas usadas en políticas JavaCallout o JavaScript para cifrar o firmar tokens web JSON (JWT). En lugar de transferir credenciales, claves o tokens en la solicitud, o de codificarlos de forma rígida en la lógica de tu proxy, puedes almacenarlos en un KVM y recuperarlos de forma dinámica en las llamadas a los destinos que los requieran.
Descubrirás otras situaciones en las que es útil almacenar pares de cadenas clave-valor. En general, te recomendamos usar KVMs en los siguientes casos:
- Secciones específicas de tu código requieren valores diferentes en el tiempo de ejecución.
- Los datos sensibles deben transferirse sin codificarlos de forma rígida.
- Quieres almacenar valores que no caduquen, como podría ocurrir con una caché.
En algunos casos, los conjuntos de propiedades son una buena alternativa a los KVMs, ya que pueden ser más fáciles de usar. Para obtener más información, consulta Usar conjuntos de propiedades.
Acerca del ámbito de KVM
El ámbito define dónde está disponible un KVM. Los KVMs se pueden crear en los siguientes ámbitos:
| Ámbito | Descripción |
|---|---|
| proxy de API | Solo el proxy de API puede acceder al KVM. |
| Entorno | Todos los proxies de API de un entorno específico pueden acceder al KVM. Por ejemplo, puede que quieras que los proxies de API desplegados en el entorno prod no tengan acceso a los KVMs del entorno test. Si quieres que las mismas claves de KVM estén disponibles en producción, crea un KVM paralelo con el ámbito del entorno prod. |
| Organización | Todos los proxies de API de todos los entornos pueden acceder al KVM. |
Acerca del cifrado de KVM
En Apigee, todas las entradas de KVM de los ámbitos de proxy de API, organización y entorno están protegidas mediante la clave de Cloud KMS
proporcionada cuando se aprovisiona una organización de Apigee (consulta el campo runtimeDatabaseEncryptionKey del recurso Organization
).
Apigee usa AES256 como estándar de cifrado.
En Apigee hybrid, puedes proporcionar claves de cifrado independientes para todas las entradas de KVM de los ámbitos de proxy de API, organización y entorno. Apigee acepta tamaños de cifrado AES128, AES196 o AES256 como estándar de cifrado.
Crear KVMs
Crea KVMs como se describe en las siguientes secciones.
Apigee en la consola de Cloud
Para crear un KVM vacío o ver una lista de KVMs, sigue estos pasos:
En la Google Cloud consola, ve a la página Gestión > Entornos.
- Selecciona el entorno que quieras editar de la lista de entornos disponibles.
- En la página Detalles del entorno, haga clic en la pestaña Mapas de clave-valor.
En la página Mapas de pares clave-valor se muestra una lista de KVMs. Si no has creado ningún KVM, la lista estará vacía.
- Para crear un KVM vacío, haz clic en + Crear mapa de valores clave.
Se abrirá el cuadro de diálogo Crear mapa de clave-valor.
- Introduce un nombre para el KVM en el campo Nombre del mapa de valores de clave.
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.
El nuevo KVM se muestra en la lista.
UI clásica de Apigee
Para crear un KVM vacío o ver una lista de KVMs, sigue estos pasos:
- Inicia sesión en la interfaz de usuario de Apigee.
- Seleccione Administrar > Entornos > Mapas de valores clave.
- En la lista desplegable de entornos, selecciona el entorno para el que quieras crear un KVM.
En la página Mapas de clave-valor se muestra una lista de los KVMs. Si no has creado ningún KVM, la lista estará vacía.
- Para crear un KVM vacío, haz clic en +Mapa de pares clave-valor.
Se abrirá el cuadro de diálogo Añadir mapa de valores de clave.
- Escribe un nombre para el 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 - Haz clic en Añadir.
El nuevo KVM se muestra en la lista.
API de Apigee
Usa las APIs de Apigee para crear, enumerar y eliminar KVMs de los siguientes ámbitos:
Política de KVM
Para crear KVMs en tiempo de ejecución y actualizarlos en tus proxies de API, usa la
política KeyValueMapOperations. En la política, especifica el nombre de la KVM en el atributo mapIdentifier del elemento superior.
El elemento <InitialEntries> te permite crear y rellenar un conjunto de entradas de referencia en un nuevo KVM en cuanto guardes la política en la interfaz de usuario o despliegues el proxy de API (si lo has desarrollado sin conexión). Si los valores cambian en la política, los valores actuales se sobrescriben. Los nuevos pares clave-valor se añaden al KVM junto con los pares clave-valor que ya había.
El elemento <Put> crea un nuevo KVM si aún no existe y crea una clave con uno o varios valores. Si el KVM ya existe, se añaden los 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 KeyValueMapOperations para recuperar valores de KVM cifrados, proporcionas el nombre de una variable en la que se almacenará el valor. Como todos los valores de KVM están cifrados, debe añadir el prefijo private. al nombre de la variable para evitar que los pares clave-valor de KVM aparezcan en las sesiones de depuración.
Obtener KVMs
Recupera KVMs mediante el elemento <Get> de la política KeyValueMapOperations.
Como todos los valores de KVM están cifrados, añade el prefijo private. al nombre de la variable que contendrá el valor recuperado.
Este prefijo oculta el valor de las sesiones de depuración mientras depuras proxies de API. Para obtener más información, consulta el elemento <Get>.
Eliminar KVMs
Elimina los KVMs como se describe en las siguientes secciones.
Apigee en la consola de Cloud
Para eliminar un KVM:
En la Google Cloud consola, ve a la página Gestión > Entornos.
- En la lista de entornos disponibles, selecciona el nombre del entorno que quieras editar.
- En la página Detalles del entorno, haga clic en la pestaña Mapas de clave-valor.
En la página Mapas de pares clave-valor se muestra una lista de KVMs.
- Busca la fila del KVM que quieras eliminar.
- En la columna Acciones, haga clic en delete.
- En el cuadro de diálogo, haz clic en Eliminar mapa de clave-valor para confirmar la operación.
El KVM se elimina y se quita de la lista.
UI clásica de Apigee
Para eliminar un KVM:
- Inicia sesión en la interfaz de usuario de Apigee.
- Seleccione Administrar > Entornos > Mapas de valores clave.
- En la lista desplegable de entornos, selecciona el entorno del que quieras eliminar un KVM.
En la página Mapas de clave-valor se muestra una lista de los KVMs.
- Coloca el cursor sobre el KVM que quieras eliminar.
- Haz clic en delete Eliminar.
- Haz clic en Eliminar para confirmar la operación.
El KVM se elimina y se quita de la lista.
API de Apigee
Usa una de las siguientes APIs de Apigee para eliminar un KVM en función de su ámbito: