Usar mapas de clave-valor

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 API recogerá 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 KVM, 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 implementados 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 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.

Acerca del enmascaramiento de KVM

De forma predeterminada, los valores de KVM se muestran como texto sin formato. Puede activar el enmascaramiento de KVM para enmascarar los valores con asteriscos (*****). Para activar o desactivar el enmascaramiento de KVM, utilice el ajuste Enmascarar valores en la interfaz de usuario o la marca maskedValues en su solicitud de API.

Los valores se ocultan a nivel de KVM. No puedes enmascarar entradas de KVM individuales; o bien se enmascaran todos los valores de un KVM, o bien ninguno.

Nota: La función de enmascaramiento de KVM no se activará automáticamente en los KVMs que ya tengas. Deberás actualizar explícitamente los KVMs que ya tengas para usar el enmascaramiento de KVMs.

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:

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

    Ir a Entornos

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

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

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

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

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

Usa las APIs de Apigee para obtener KVMs de los siguientes ámbitos:

Por ejemplo, para obtener un KVM con ámbito de proxy de API, introduce una solicitud GET en la siguiente URL:

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

Actualizar KVMs

Usa las APIs de Apigee para actualizar los KVMs de los siguientes ámbitos:

Por ejemplo, para obtener un KVM con ámbito de proxy de API, introduce una solicitud GET en la siguiente URL:

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

Gestionar valores de KVM

Puede gestionar los valores de KVM mediante la API o la política KeyValueMapOperations, como se describe en las siguientes secciones.

Gestionar valores de KVM con la API

Usa las APIs de Apigee para gestionar los valores de KVM de los siguientes ámbitos:

Gestionar valores de KVM con la política KeyValueMapOperations

Usa la política KeyValueMapOperations para añadir, obtener o eliminar valores de KVMs.

Añade claves y valores de KVM mediante el elemento <Put> de la política KeyValueMapOperations. El elemento <Put> crea un 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. Para obtener más información, consulta el elemento<Put>.

Obtén los valores de KVM 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>.

Elimina valores de KVM mediante el elemento <Delete> de la política KeyValueMapOperations. Para obtener más información, consulta el artículo sobre el elemento<Delete>.

Eliminar KVMs

Elimina los KVMs como se describe en las siguientes secciones.

Apigee en la consola de Cloud

Para eliminar un KVM, sigue estos pasos:

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

    Ir a Entornos

  2. En la lista de entornos disponibles, selecciona el nombre del entorno que quieras editar.
  3. 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.

  4. Busca la fila del KVM que quieras eliminar.
  5. En la columna Acciones, haz clic en .
  6. 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, sigue estos pasos:

  1. Inicia sesión en la interfaz de usuario de Apigee.
  2. Seleccione Administrar > Entornos > Mapas de valores clave.
  3. 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.

  4. Coloca el cursor sobre el KVM que quieras eliminar.
  5. Haz clic en Eliminar.
  6. 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: