Como trabalhar com mapas de valores-chave

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

Há momentos em que você quer armazenar dados para recuperação no ambiente de execução, sem expor dados que não devem ser codificados na lógica do proxy de API. Os mapas de chave-valor (KVMs) são ideais para isso. Um KVM é uma coleção personalizada de pares de string de chave-valor criptografados ou não criptografados. Veja dois exemplos:

Para saber mais sobre outros tipos de persistência, consulte Como adicionar armazenamento em cache e persistência.

Cenários de KVM

Aqui estão algumas situações em que as KVMs são úteis:

  • Você tem um proxy de API que precisa chamar um URL de destino (ou frase de destaque de serviço) em um ambiente de teste e outro URL de destino em um ambiente de produção. Em vez de codificar URLs no seu proxy, é possível fazer com que ele detecte o ambiente em que está, execute a política relacionada de operações de mapeamento de chave-valor e recupere o URL de destino correto de uma das KVMs criadas. Depois, se um ou ambos os destinos mudarem, basta atualizar as KVMs com os novos URLs. O proxy coleta os novos valores e não é necessária nenhuma reimplantação do proxy.
  • Você quer armazenar credenciais, chaves privadas ou tokens, como tokens para serviços externos, credenciais necessárias para gerar tokens OAuth ou chaves privadas usadas em chamadas em Java ou JavaScript para criptografia ou assinatura em JSON Web Token (JWT). Em vez de transmitir credenciais, chaves ou tokens na solicitação ou codificá-los na sua lógica de proxy, armazene-os em um KVM (sempre criptografada) e recupere-os dinamicamente em chamadas aos destinos que precisam deles.

Você descobrirá outras situações em que o armazenamento de pares de string de chave-valor é útil. Em geral, considere o uso de KVMs quando:

  • Os locais específicos do seu código exigem valores diferentes no tempo de execução.
  • Dados confidenciais precisam ser transmitidos sem codificar.
  • Você quer armazenar valores que não expiram como um cache.

As KVMs têm escopo

Escopo significa "onde um KVM está disponível". Os KVMs podem ser criados nos seguintes escopos: organization, environment e apiproxy.

Por exemplo, se apenas um proxy de API exigir dados em uma KVM, será possível criar a KVM no escopo apiproxy, em que apenas esse proxy de API pode acessar os dados.

Ou então todos os proxies de API no ambiente de teste terão acesso a um mapa de chave-valor. Nesse caso, você precisa criar um mapa de chave-valor no escopo do ambiente. Proxies implantados no ambiente "prod" não podem acessar KVMs no escopo de ambiente "test". Se você quiser que as mesmas chaves de KVM estejam disponíveis na produção, crie um KVM paralela no escopo "prod".

Se você quiser que todos os proxies em todos os ambientes acessem o mesmo KVM, crie o KVM no escopo organization.

Sobre as KVMs criptografadas

Os KVMs criptografados são criptografados com uma chave de criptografia AES-128 gerada pela Apigee. A chave usada para criptografar um KVM é armazenada no escopo do KVM. Por exemplo, em uma organização, todos os KVMs criptografados criados no escopo do ambiente são criadas usando a mesma chave com escopo no ambiente.

O Edge processa a exibição de valores criptografados das maneiras mostradas abaixo. Consulte Como gerenciar e usar KVMs para informações sobre como criar KVMs criptografadas.

interface do Edge

Os mapas de chave-valor criptografados exibem valores mascarados com asteriscos na interface (*****). Por exemplo:

API Management

Na API Management, os valores criptografados são retornados mascarados. Veja a seguir um exemplo de resposta da API de gerenciamento em uma chamada KVM criptografada:

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

Rastrear e depurar

Ao usar a política de operações de mapa de chave-valor para recuperar valores KVM criptografados, você fornece o nome de uma variável para armazenar o valor. Para receber um valor criptografado, é necessário adicionar o prefixo "private." ao nome da variável, o que impede que as chaves/valores da KVM apareçam nas sessões de rastreamento e depuração.

Limites

Em organizações com os serviços de persistência principal (CPS, na sigla em inglês) ativados:

  • O nome/identificador da KVM diferencia maiúsculas de minúsculas.
  • A chave tem um limite de 2 KB.
  • O tamanho do valor é limitado a 10 KB.

No Apigee Edge para nuvem privada, cada KVM não pode exceder 15 MB (esse é o tamanho combinado das chaves e dos valores). Se você exceder esse limite, o Apigee Edge para nuvem privada retornará um erro. Para determinar o tamanho das KVMs, use o comando nodetool cfstats.

KVMs maiores podem causar degradação do desempenho. Como resultado, divida KVMs grandes e monolíticos em menores para melhorar o desempenho.

Como gerenciar e usar KVMs

É possível criar, gerenciar e usar as KVMs de várias maneiras. Nesta seção, descrevemos diferentes opções para criar e recuperar KVMs criptografadas e não criptografadas.

Como criar e atualizar KVMs

É possível criar e atualizar KVMs das seguintes maneiras:

  • Política de operações de mapa de chave-valor (sem criptografia)

    Para criar e atualizar KVM no ambiente de execução pelos proxies de API, use a política de operações do mapa de chave-valor. Na política, especifique o nome do KVM no atributo mapIdentifier do elemento pai.

    O elemento <InitialEntries> permite que você crie e preencha um conjunto de entradas de valor de referência em um novo KVM assim que você salvar a política na IU ou implantar o proxy da API (se tiver desenvolvido off-line). Se os valores mudarem na política, os valores atuais serão substituídos. Todas as novas chaves/valores são adicionadas ao KVM existente com as chaves/valores atuais.

    O elemento <Put> cria um novo KVM, se ele ainda não existir, e cria uma chave com um ou mais valores. Se o KVM já existir, as chaves/valores serão adicionados (ou atualizados se a chave já existir). É possível usar vários elementos <Put> em uma política de KVM.

  • API Management

    A API de gerenciamento destina-se a trabalhar com KVMs como administrador, e não durante o tempo de execução em seus proxies de API. Por exemplo, você pode ter um script interno que usa a API de gerenciamento para excluir e recriar KVMs em um ambiente de teste ou você pode redefinir o valor de uma chave em uma KVM para todos os proxies coletarem. Para manipulação de KVMs no ambiente de execução, use a política de operações de mapa de chave-valor nos seus proxies.

    A API de gerenciamento de mapas de chave-valor permite criar, atualizar e excluir KVMs criptografadas e chaves/valores em todos os escopos (organização, ambiente e apiproxy).

    Para criar uma KVM criptografada com a API Management, adicione "encrypted" : "true" ao payload JSON. Só é possível criptografar KVMs quando você as cria. Não é possível criptografar uma KVM atual.

  • IU de gerenciamento

    Na interface de gerenciamento de borda, é possível criar e atualizar KVMs com escopo no ambiente, que são o único escopo da KVM que aparece na interface. A IU de gerenciamento é uma boa maneira de administrar manualmente os dados da KVM para proxies de API no ambiente de execução. Consulte Como criar e editar mapas de chave-valor de ambiente para mais informações.

Como recuperar KVMs

Os mapas de chave-valor criptografados e não criptografados são recuperados da mesma maneira, com uma pequena variação quando são recuperados com a política de operações de mapa de chave-valor.

  • Política: use o elemento <Get> na política de operações de mapa de chave-valor para recuperar KVMs criptografadas e não criptografadas. A única diferença é recuperar valores criptografados com a política, em que você precisa adicionar um prefixo "private." ao nome da variável que vai conter o valor recuperado, conforme descrito na seção "Obter operação" do tópico de referência. Esse prefixo oculta o valor das sessões de rastreamento e depuração enquanto você depura proxies de API.
  • API Management: para fins de gerenciamento administrativo, é possível usar a criação e edição de mapas de chave-valor do ambiente para receber KVMs e chaves/valores. Por exemplo, se você quiser fazer backup das KVMs conseguindo e armazenando as definições JSON, use a API de gerenciamento. No entanto, esteja ciente de que os valores criptografados são exibidos como ***** na resposta da API.
  • IU de gerenciamento: para visualizar as KVMs com escopo de ambiente na interface de gerenciamento, acesse APIs > Configuração do ambiente > Mapas de chave-valor (Edge clássico) ou Administrador > Ambientes > Mapas de chave-valor (New Edge).

Exemplo de KVM

Veja um exemplo de como usar uma KVM para preencher valores em um URL em https://community.apigee.com/questions/32727/templatize-target-url-with-kvm-by-environment.html.