Como trabalhar com mapas de valores-chave

Esta é a documentação do Apigee Edge.
Acesse 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 chamada de serviço) em um teste e outro URL de destino em um ambiente de produção. Em vez de codificar URLs seu proxy, faça com que o proxy detecte em qual ambiente está, execute a solicitação de política de operações do mapa de valor e recupere o URL de destino correto de uma das KVMs que você criados. E mais tarde, 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 de acesso externo serviços, credenciais necessárias para gerar tokens OAuth ou chaves privadas usado em chamadas Java ou JavaScript para criptografia ou assinatura 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 precisar de dados em uma KVM, é possível criar a KVM 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 seguintes maneiras. Consulte Como gerenciar e usar KVMs para ver informações sobre como criar KVMs criptografadas.

interface do Edge

Os mapas de chave-valor criptografados exibem valores mascarados com asteriscos na interface do usuário (*****). Para exemplo:

API Management

Na API de gerenciamento, os valores criptografados são retornados mascarados. Confira a seguir exemplos de gerenciamento Resposta da API em uma chamada "Receber KVM criptografada":

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

Rastrear e depurar

Quando você usa a política de operações de mapa de chave-valor para recuperar valores de KVM criptografados, forneça o nome de uma variável para armazenar o . Para receber um valor criptografado, adicione "private." para o prefixo o que impede que as chaves/valores da KVM apareçam no Trace e nas sessões de depuração.

Limites

Em organizações Principal Serviços de persistência (CPS) ativados:

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

No caso do Apigee Edge para nuvem privada, cada KVM não pode exceder 15 MB, que é 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 suas KVMs, use o comando nodetool cfstats.

KVMs maiores podem resultar em degradação do desempenho. Como resultado, você deve dividir KVMs monolíticas em conjuntos menores para melhorar o desempenho.

Como gerenciar e usar KVMs

É possível criar, gerenciar e usar KVMs de várias maneiras. Esta seção descreve 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 a KVM do ambiente de execução pelos proxies de API, use o Política de operações de 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 é usada para trabalhar com KVMs como administrador, e não durante a execução nos proxies das APIs. Por exemplo, você pode ter um script interno que usa o API para excluir e recriar KVMs em um ambiente de teste ou talvez você queira redefinir o valor de uma chave em uma KVM para que todos os proxies sejam usados. (Para manipulação de tempo de execução de KVMs, use o Política de operações de mapa de chave-valor em seus proxies).

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

    Para criar uma KVM criptografada com a API de gerenciamento, adicione "encrypted" : "true" ao payload JSON. Só é possível criptografar KVMs ao criar para resolvê-los com rapidez. Não é possível criptografar uma KVM atual.

  • IU de gerenciamento

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

Como recuperar KVMs

Os mapeamentos de chaves-valor criptografados e não criptografados são recuperados da mesma maneira, com uma pequena variação ao fazer a recuperação com a política de operações de mapeamento 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 é que, recuperação de valores criptografados com a política, em que é necessário adicionar um "private.". prefixo do nome da variável que conterá o valor recuperado, conforme descrito no Seção da operação de obtenção do tópico de referência. Esse prefixo oculta o valor do Trace e faz a depuração durante a depuração de proxies de API.
  • API de gerenciamento: para fins de gerenciamento administrativo, você pode usar o Como criar e editar mapas de chave-valor do ambiente para conseguir KVMs e chaves/valores. Por exemplo, se você quiser fazer backup de KVMs obtendo e armazenando as definições JSON, use a API de gerenciamento. Atenção: no entanto, os valores criptografados são exibidos como ***** na resposta da API.
  • IU de gerenciamento: é possível visualizar suas KVMs com escopo de ambiente no interface em APIs > Configuração do ambiente > Mapas de chave-valor (Edge clássico) ou Administrador > Ambientes > Mapas de chave-valor (novo Edge).

Exemplo de KVM

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