Usa mapas clave-valor

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. Un KVM es una colección personalizada de pares de string de clave-valor que puede o no estar encriptado. Estos son dos ejemplos:

Los KVM tienen tres casos prácticos generales (esta lista es solo una guía para mostrar algunas maneras diferentes en las que se usan losKVM):

  • Datos de la sesión del usuario: Datos que crea y borra el entorno de ejecución. Las entradas de KVM se pueden encriptar o borrar, sin capacidad para ver o administrar las entradas 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. La IU o la API proporcionan estos datos y, luego, se ponen a disposición de la puerta de enlace (como variables y 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 tu proxy, puedes hacer que el proxy detecte en qué entorno se encuentra, ejecutar la política KeyValueMapOperations relacionada y recuperar la URL de destino correcta de uno de los KVM que creaste.

    Más adelante, si uno o ambos de sus destinos cambian, simplemente debe actualizar los KVM con las nuevas URL. El proxy 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 (siempre encriptado) 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:

  • Algunos lugares específicos 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 Almacenamiento en caché.

Acerca del permiso de KVM

El permiso significa “dónde está disponible una KVM”. Se pueden crear KVM en los siguientes permisos: organization, environment y apiproxy.

Por ejemplo, si los pares clave-valor se deben usar para todas las API de una organización, crea un KVM a nivel de la organización. O si solo un proxy de API específico debe tener acceso a las claves y los valores, crea el KVM en el alcance de apiproxy donde solo ese proxy de API puede acceder a los datos.

O deseas que todos los proxies de API de tu entorno de prueba tengan acceso a un mapa de clave-valor. En este caso, crearías un mapa de clave-valor en el permiso del entorno. Los proxies implementados en el entorno “prod” no pueden acceder a las KVM en el permiso del entorno de “prueba”. Si quieres que las mismas claves de KVM estén disponibles en producción, crea un KVM paralelo con el alcance del entorno “prod”.

Si deseas que todos los proxies de todos los entornos accedan al mismo KVM, crea el KVM en el alcance organization.

Usa KVM

Puedes crear y actualizar KVM de las siguientes maneras:

Usa KVM con la IU de Apigee

Puedes usar la IU de Apigee para realizar las siguientes tareas relacionadas con los KVM:

  • Ver una lista de KVM en un entorno
  • Crear un KVM nuevo (vacío)

Ten en cuenta que el KVM en la IU solo se orienta a un entorno.

Actualmente, no puedes agregar datos a KVM (incluso aquellos que crees en la IU), borrar KVM o ver datos en KVM mediante la IU de Apigee. Debes usar las políticas de KVM para agregar datos a KVM.

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

  1. Abre la IU de Apigee en un navegador.
  2. Selecciona Administrador > Entornos > Mapas de clave-valor.
  3. En la lista desplegable del entorno, selecciona el entorno que deseas.

    La vista Mapas de clave-valor muestra una lista de KVM existentes. Si no creaste ningún KVM, entonces la lista de KVM está vacía.

  4. Para crear un nuevo KVM (vacío), haz clic en el botón +Key value map en la esquina superior derecha.

    Aparece el cuadro de diálogo Agregar mapa de clave-valor (Add key value map):

    Agrega KVM en la IU

  5. En el campo Nombre (Name), ingresa un nombre para el KVM.

    El nombre solo puede contener letras, números y guiones. No puede incluir espacios ni otros caracteres especiales. Por ejemplo, ingresa "my-kvm-1".

  6. (Obligatorio) Selecciona la casilla de verificación Encriptado. Para obtener más información, consulta Acerca de KVM encriptados.
  7. Haga clic en Add.

    Apigee crea el nuevo KVM. No puedes editar el nuevo KVM ni agregarle datos.

Usa KVM con la API de Apigee

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

La API de Apigee /keyvaluemaps te permite crear y borrar KVM en todos los permisos (organización, entorno y apiproxy). No puedes agregar ni actualizar datos de KVM mediante la API.

Para crear un KVM encriptado con la API de Apigee, agrega "encrypted":"true" a la carga útil JSON. Solo puedes encriptar KVM cuando los creas. No puedes encriptar un KVM existente.

Utiliza KVM con la política KeyValueMapOperations

Para que los proxies de tu API creen y actualicen KVM de entornos de ejecución, usa la política KeyValueMapOperations (en la política, especifica el nombre del 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. Todas las claves/valores nuevas se agregan al KVM existente junto con las claves/valores existentes.

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 claves o valores (o se actualizan si la clave ya existe). Puedes usar varios elementos <Put> en una política de KVM.

Seguimiento y 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. Para obtener un valor encriptado, debes agregar el prefijo private. al nombre de la variable, lo que evita que las claves o valores de KVM aparezcan en las sesiones de Trace y depuración.

Recupera KVM

Recupera mapas de clave-valor encriptados y no encriptados con la política de KeyValueMapOperations. Usa el elemento <Get> de la política para recuperar KVM encriptados y no encriptados. Para recuperar valores encriptados con la política, agrega un prefijo private. al nombre de la variable que contendrá el valor recuperado, como se describe en el tema de referencia Obtener sección de operaciones. Ese prefijo oculta el valor de las sesiones de seguimiento y depuración mientras depuras los proxies de API.

Acerca de los KVM encriptados

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

Apigee administra la visualización de valores encriptados de las siguientes maneras. (Consulta Usa KVM para obtener información sobre cómo crear KVM encriptados).

En la API de Apigee, los valores encriptados se muestran enmascarados. A continuación, se muestra un ejemplo de respuesta de la API de Apigee en una llamada GET de un KVM encriptado:

{
  "encrypted": true,
  "entry": [
    {
      "name": "Key1",
      "value": "*****"
    },
    {
      "name": "Key2",
      "value": "*****"
    }
  ],
  "name": "secretMap"
}