Usa mapas clave-valor

Estás viendo la documentación de Apigee X.
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

Las KVM 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.

Los valores encriptados se muestran enmascarados:

  • Mediante la IU de Apigee, se proporciona un ejemplo de información encriptada:

    Extracto de IU que muestra datos encriptados.

  • Mediante la API de Apigee, se proporciona un ejemplo de información encriptada en la respuesta:
    {
      "encrypted": true,
      "entry": [
        {
          "name": "Key1",
          "value": "*****"
        },
        {
          "name": "Key2",
          "value": "*****"
        }
      ],
      "name": "secretMap"
    }
    

Crea KVM

Crea KVM como se describe en las siguientes secciones.

IU de Apigee

Para crear un KVM nuevo (vacío) o ver una lista de KVM, sigue estos pasos:

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

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

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

  6. 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 de 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.

IU de Apigee

Para borrar una KVM, sigue estos pasos:

  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: