Trabaja con mapas de clave-valor

Estás viendo la documentación de Apigee Edge.
Ir a la documentación de Apigee X. info

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. A continuación, presentamos dos ejemplos:

Para obtener más información sobre otros tipos de persistencia, consulta Cómo agregar almacenamiento en caché y persistencia.

Situaciones de KVM

Estas son algunas situaciones en las que los KVM son útiles:

• 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 URLs 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 tus destinos cambian, simplemente debes actualizar los KVM con las nuevas URLs. El proxy recoge los valores nuevos y no es necesario volver a implementar el proxy.
• Deseas almacenar credenciales, claves privadas o tokens, como tokens para 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é.

Los KVM tienen permisos

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

Por ejemplo, si solo un proxy de API requiere datos en un KVM, puedes crear 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.

Acerca de las KVM encriptadas

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.

Edge administra la visualización de valores encriptados de las siguientes maneras. (Consulta Administra y usa KVM para obtener información sobre cómo crear KVM encriptados).

IU de Edge

Los mapas de clave-valor encriptados muestran valores enmascarados con asteriscos en la IU (*****). Por ejemplo:

API de Management

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

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

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.

Límites

En las organizaciones con los Servicios de persistencia principales (CPS) habilitados, sucede lo siguiente:

• El nombre o identificador del KVM distingue mayúsculas de minúsculas.
• El tamaño de la clave se limita a 2 KB.
• El tamaño del valor se limita a 10 KB.

En Apigee Edge para Private Cloud, cada KVM no debe superar los 15 MB (este es el tamaño combinado de las claves y los valores). Si superas este límite, Apigee Edge para nubes privadas mostrará un error. Para determinar el tamaño de tus KVM, puedes usar el comando nodetool cfstats.

Los KVM más grandes pueden provocar una degradación del rendimiento. Como resultado, debes dividir las KVM monolíticas grandes en otras más pequeñas para mejorar el rendimiento.

Administra y usa KVM

Puedes crear, administrar y usar KVM de varias maneras. En esta sección, se describen diferentes opciones para crear y, luego, recuperar KVM encriptadas y sin encriptar.

Crea y actualiza KVM

Puedes crear y actualizar KVM de las siguientes maneras:

• Política de operaciones de mapas de clave-valor (sin encriptación)

  Para que los proxies de tu API creen y actualicen KVM de entornos de ejecución, usa la política Key Value Map Operations. (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.

• API de Management

  La API de administración sirve para trabajar con KVM como administrador, en lugar de hacerlo durante el tiempo de ejecución en tus proxies de API. Por ejemplo, es posible que tengas una secuencia de comandos interna que use la API de administración para borrar y volver a crear KVM en un entorno de prueba, o bien que desees restablecer el valor de una clave en un KVM para que todos los proxies la detecten. (Para manipular KVM en el entorno de ejecución, usa la política Key Value Map Operations en tus proxies).

  La API de administración de mapas de clave-valor te permite crear, actualizar y borrar KVM y claves/valores encriptados en todos los permisos (organización, entorno y apiproxy).

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

• IU de administración

  En la IU de administración de Edge, puedes crear y actualizar KVM con alcance de entorno, que son el único alcance de KVM que aparece en la IU. La IU de administración es una buena forma de administrar manualmente los datos de KVM para los proxies de API en el tiempo de ejecución. Consulta Crea y edita mapas de clave-valor del entorno para obtener más información.

Recupera KVM

Recuperas mapas de clave-valor encriptados y no encriptados de la misma manera, con una pequeña variación cuando recuperas con la política de Key Value Map Operations.

• Política: Usa el elemento <Get> en la política Key Value Map Operations para recuperar KVM encriptados y no encriptados. La única diferencia leve es la recuperación de valores encriptados con la política, en la que debes agregar un prefijo "private." al nombre de la variable que contendrá el valor recuperado, como se describe en la sección de la operación Get del tema de referencia. Ese prefijo oculta el valor de las sesiones de seguimiento y depuración mientras depuras los proxies de API.
• API de administración: Para fines de administración, puedes usar la Creación y edición de mapas de clave-valor del entorno para obtener KVM y claves/valores. Por ejemplo, si deseas crear copias de seguridad de las KVM obteniendo y almacenando las definiciones de JSON, usa la API de administración. Sin embargo, ten en cuenta que los valores encriptados se muestran como ***** en la respuesta de la API.
• IU de administración: Puedes ver tus KVM con alcance de entorno en la IU de administración. Para ello, ve a APIs > Configuración del entorno > Mapas de clave-valor (Edge clásico) o Administrador > Entornos > Mapas de clave-valor (Edge nuevo).

Ejemplo de KVM

Para ver un ejemplo del uso de un KVM para propagar valores en una URL, consulta Crea una plantilla de la URL de destino con un KVM por entorno.