Como trabalhar com mapas de valores-chave

Você está lendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

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

Confira algumas situações em que os KVMs são úteis:

• Você tem um proxy de API que precisa chamar um URL de destino (ou chamada de serviço) em um ambiente de teste e outro em um ambiente de produção. Em vez de codificar URLs no seu proxy, você pode fazer com que o proxy detecte em qual ambiente ele está, execute a política de operações de mapa de chave-valor relacionada e recupere o URL de destino correto de um dos KVMs que você criou. E, mais tarde, se um ou ambos os destinos forem alterados, basta atualizar os KVMs com os novos URLs. O proxy seleciona os novos valores e não é necessário reimplantar o proxy.
• Você quer armazenar credenciais, chaves privadas ou tokens, como tokens de serviços externos, credenciais necessárias para gerar tokens OAuth, ou chaves privadas usadas em frases de destaque Java ou JavaScript para criptografia ou assinatura do token da Web JSON (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 sensíveis precisam ser transmitidos sem codificação.
• Você quer armazenar valores que não expiram como um cache.

Os 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 um KVM, você poderá criar o KVM no escopo apiproxy, em que apenas esse proxy de API poderá 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 lida com a exibição de valores criptografados das seguintes maneiras. Consulte Como gerenciar e usar KVMs para informações sobre como criar KVMs criptografados.

Interface do Edge

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

API Management

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

{
  "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 Key Value Map Operations policy para recuperar valores de KVM criptografados, forneça o nome de uma variável para armazenar o valor. Para conseguir um valor criptografado, adicione o prefixo "private." ao nome da variável. Isso impede que as chaves/valores de KVM apareçam nas sessões de rastreamento e depuração.

Limites

Em organizações com os Serviços principais de persistência (CPS, na sigla em inglês) 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 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 dos KVMs, use o comando nodetool cfstats.

KVMs maiores podem resultar em degradação de 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 KVMs de várias maneiras. Esta seção descreve diferentes opções para criar e recuperar KVMs criptografados e não criptografados.

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 a criação e atualização do KVM de ambiente de execução pelos proxies da API, use a 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 interface ou implantar o proxy de 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 <Put> elementos em uma política de KVM.

• API Management

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

  A API Key/Value Maps Management permite criar, atualizar e excluir KVMs e chaves/valores criptografados em todos os escopos (organização, ambiente e apiproxy).

  Para criar um KVM criptografada com a API Management, adicione "encrypted" : "true" ao payload JSON. Só é possível criptografar KVMs ao criar las. Não é possível criptografar um KVM existente.

• Interface de gerenciamento

  Na interface de gerenciamento do Edge, é possível criar e atualizar KVMs com escopo no 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 de 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

É possível recuperar mapas de chave-valor criptografados e não criptografados da mesma maneira, com uma pequena variação ao recuperar 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 criptografados e não criptografados. A única pequena diferença é a recuperação de valores criptografados com a política, em que é necessário adicionar um prefixo "private." ao nome da variável que conterá o valor recuperado, conforme descrito na seção sobre operação GET do tópico de referência. Esse prefixo oculta o valor das sessões de rastreamento e depuração enquanto você depura proxies da API.
• API Management: para fins de gerenciamento administrativo, é possível usar a página Como criar e editar mapas de chave-valor de ambiente para receber KVMs e chaves/valores. Por exemplo, se você quiser fazer backup de KVMs recebendo e armazenando as definições JSON, use a API Management. No entanto, os valores criptografados são mostrados como ***** na resposta da API.
• Interface de gerenciamento: é possível visualizar os KVMs com escopo no ambiente na interface de gerenciamento acessando 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 um exemplo de como usar um KVM para preencher valores em um URL, consulte Templatizar o URL de destino com KVM por ambiente.