Trabaja con mapas de clave-valor

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Información

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:

Para obtener información sobre otros tipos de persistencia, consulta Agrega 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 debe llamar a una URL de destino (o solicitud de servicio) en un entorno de pruebas y otra URL de destino en un entorno de producción. En lugar de codificar las URL en tu proxy, puedes hacer que este detecte en qué entorno se encuentra, ejecute la política relacionada de operaciones de asignación de valores de clave y recupere la URL de destino correcta desde uno de los KVM que creaste. Luego, si uno o ambos destinos cambian, solo debes actualizar los KVM con las URLs nuevas. El proxy detecta los valores nuevos y no es necesario volver a implementar el proxy.
  • Quieres almacenar credenciales, claves privadas o tokens, como tokens de servicios externos, credenciales necesarias para generar tokens de OAuth o claves privadas que se usan en textos destacados de Java o JavaScript para la encriptación o la firma de tokens 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 alcance

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 permiso 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 controla la visualización de valores encriptados de las siguientes maneras. (Consulta Cómo administrar y usar 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 Management, los valores encriptados se muestran enmascarados. A continuación, se muestra una respuesta de la API de Management de muestra en una llamada de KVM encriptada:

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

Seguimiento y depuración

Cuando usas la política de operaciones de asignación de valores de clave para recuperar valores de KVM encriptados, debes proporcionar el nombre de una variable para almacenar el valor. Para obtener un valor encriptado, debes agregar el prefijo "private." al nombre de la variable, lo que evita que los valores o claves de KVM aparezcan en las sesiones de Trace y depuración.

Límites

En organizaciones que tienen habilitados los servicios de persistencia principales (CPS), ocurre lo siguiente:

  • El nombre o identificador de 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 el caso de Apigee Edge para nube privada, 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 la nube privada mostrará un error. Para determinar el tamaño de tus KVM, puedes usar el comando nodetool cfstats.

Los KVM más grandes pueden degradar el rendimiento. Como resultado, debes dividir los KVM grandes y monolíticos en otros más pequeños para mejorar el rendimiento.

Administrar y usar KVM

Puedes crear, administrar y usar KVM de varias maneras. En esta sección, se describen las diferentes opciones para crear y, luego, recuperar KVM encriptados y no encriptados.

Crea y actualiza KVM

Puedes crear y actualizar KVM de las siguientes maneras:

  • Política de operaciones del mapa de par clave-valor (sin encriptación)

    Para crear y actualizar KVM de entorno de ejecución mediante los proxies de API, usa la política de operaciones del mapa de pares clave-valor. (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 Management es para trabajar con KVM como administrador en lugar de durante el entorno de ejecución en tus proxies de API. Por ejemplo, puedes tener una secuencia de comandos interna que usa la API de administración para borrar y volver a crear los KVM en un entorno de pruebas, o bien puedes restablecer el valor de una clave en un KVM para que todos los proxies los registren. (Para la manipulación del entorno de ejecución de los KVM, usa la política de operaciones del mapa de par clave-valor en tus proxies).

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

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

  • IU de Management

    En la IU de administración perimetral, 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 manera de administrar manualmente los datos de KVM para los proxies de API en el tiempo de ejecución. Consulta Crea y edita mapas de pares clave-valor del entorno para obtener más información.

Recupera KVM

Los mapas de clave-valor encriptados y no encriptados de la misma manera, con una leve variación cuando los recuperas con la política de operaciones del mapa de pares clave-valor.

  • Política: Usa el elemento <Get> en la política de operaciones del mapa de par clave-valor para recuperar los KVM encriptados y no encriptados. La única diferencia es la recuperación de valores encriptados con la política, en los que debes agregar el prefijo “private.” al nombre de la variable que contendrá el valor recuperado, como se describe en la sección Obtener operación del tema de referencia. Ese prefijo oculta el valor de las sesiones de Trace y depuración mientras depuras los proxies de API.
  • API de Management: Para fines de administración, puedes usar Crea y edita mapas de pares clave-valor del entorno a fin de obtener KVM y claves/valores. Por ejemplo, si deseas crear una copia de seguridad de los KVM mediante la obtención y el almacenamiento de 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 Management: Para ver los KVM centrados en el entorno en la IU de administración, ve a APIs > Configuración del entorno > Mapas de pares clave-valor (versión clásica de Edge) o Administrador > Entornos > Mapas de pares clave-valor (Nuevo Edge).

Ejemplo de KVM

Si deseas ver un ejemplo del uso de un KVM para propagar valores en una URL, consulta https://community.apigee.com/questions/32727/templatize-target-url-with-kvm-by-environment.html.