Trabaja con mapas de clave-valor

Estás viendo la documentación de Apigee Edge.
Ve a 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. A continuación, presentamos dos ejemplos:

Para obtener más 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 necesita llamar a una URL de destino (o texto destacado de servicio) en una prueba. y otra URL de destino en un entorno de producción. En lugar de codificar las URL en puede hacer que este detecte en qué entorno se encuentra, ejecute la clave relacionada política de operaciones de mapas de valores y recuperar la URL de destino correcta de uno de los KVM que crear. Luego, si uno o ambos objetivos cambian, solo debes actualizar los KVM con las nuevas URL. El proxy detecta los valores nuevos y no es necesario volver a implementarlos.
• Quieres almacenar credenciales, claves privadas o tokens, como tokens para servicios, 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 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 permiso

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 El permiso apiproxy, en el que solo el 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 los 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 pares clave-valor encriptados muestran valores enmascarados con asteriscos en la IU (*****). Para ejemplo:

API de Management

En la API de Management, los valores encriptados se muestran enmascarados. A continuación, figura la administración de muestras. Respuesta de la API en una llamada de KVM para obtener encriptación:

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

Seguimiento y depuración

Cuando usas la política de operaciones del mapa de par clave-valor. para recuperar valores de KVM encriptados, debes proporcionar el nombre de una variable valor. Para obtener un valor encriptado, debes agregar "private." prefijo al el nombre de la variable, que evita que los pares clave-valor de KVM aparezcan en las sesiones de seguimiento y depuración.

Límites

En organizaciones con Núcleo Servicios de persistencia (CPS) habilitados:

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

En el caso de Apigee Edge para la nube privada, cada KVM no debe exceder los 15 MB (este es el tamaño combinado de las claves y los valores). Si superas este límite, Apigee Edge for Private Cloud 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 KVM monolíticos a otros más pequeños para mejorar el rendimiento.

Administra y usa KVM

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

Cómo crear y actualizar KVM

Puedes crear y actualizar KVM de las siguientes maneras:

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

  Para crear y actualizar KVM del entorno de ejecución con los proxies de tu API, usa el 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 se usa para trabajar con KVM como administrador y no durante el tiempo de ejecución en los proxies de tu API. Por ejemplo, puedes tener una secuencia de comandos interna que use API para borrar y volver a crear KVM en un entorno de pruebas, o puedes restablecer el valor de una clave en un KVM para que los recolecten todos los proxies. Para la manipulación del tiempo de ejecución de los KVM, usa el Política de operaciones del mapa de pares clave-valor en tus proxies).

  La API de administración de mapas de par clave-valor te permite crear, actualizar y borrar KVM encriptados 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 de JSON. Solo puedes encriptar KVM cuando los creas de ellos. No puedes encriptar un KVM existente.

• IU de administración

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

Recupera KVM

Los mapas de clave-valor encriptados y no encriptados se recuperan de la misma manera, con una leve variación Cuando se recuperan datos con la política de operaciones de mapas de par clave-valor.

• Política: Usa el elemento <Get> en el Política de operaciones del mapa de pares clave-valor para recuperar KVM encriptados y no encriptados. La única diferencia leve es Recuperar valores encriptados con la política, en la que debes agregar un “private.” al nombre de la variable que contendrá el valor recuperado, como se describe en Sección Obtener operación del tema de referencia. Ese prefijo oculta el valor de Trace y Debug mientras depuras los proxies de la API.
• API de Management: Para fines de gestión administrativa, puedes usar la Crea y edita mapas de pares clave-valor del entorno para obtener KVM y pares clave-valor. Por ejemplo, si quieres para crear una copia de seguridad de los KVMs obteniendo y almacenando las definiciones JSON, usa la API de Management. Atención: sin embargo, esos 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 sección IU en APIs > Configuración del entorno > Mapas de par clave-valor (Classic Edge) o Administrador > Entornos > Mapas de par clave-valor (nuevo borde).

Ejemplo de KVM

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