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 Adicionar armazenamento em cache e persistência.

Cenários da 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. Depois, 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 confidenciais precisam ser transmitidos sem codificar.
• 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, crie o 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 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 de gerenciamento 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 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) 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 (tamanho combinado das chaves e valores). Se você exceder esse limite, o Apigee Edge para nuvem privada vai retornar um erro. Para determinar o tamanho das suas KVMs, use o comando nodetool cfstats.

KVMs maiores podem resultar em degradação do desempenho. Por isso, divida KVMs grandes e monolíticos em menores para melhorar a performance.

Gerenciar e usar KVMs

É possível criar, gerenciar e usar 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 do 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 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 é para trabalhar com KVMs como administrador, e não durante o tempo de execução nos 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 querer redefinir o valor de uma chave em um KVM para que todos os proxies a detectem. Para manipulação de KVMs no ambiente de execução, use a política Key Value Map Operations nos seus 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 criptografado com a API de gerenciamento, adicione "encrypted" : "true" ao payload JSON. É possível criptografar KVMs somente quando você as cria. Não é possível criptografar um KVM atual.

• Interface de gerenciamento

  Na interface de gerenciamento do Edge, é 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 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

Você recupera mapas de chave-valor criptografados e não criptografados da mesma forma, com uma pequena variação ao recuperar com a política de operações do 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 é recuperar valores criptografados com a política. Nesse caso, é necessário adicionar um prefixo "private." ao nome da variável que vai 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 trace e depuração enquanto você depura proxies de API.
• API Management: para fins de gerenciamento administrativo, use o guia Como criar e editar mapas de chave-valor de ambiente para acessar KVMs e chaves/valores. Por exemplo, se você quiser fazer backup de KVMs recebendo e armazenando as definições JSON, use a API de gerenciamento. No entanto, os valores criptografados são mostrados como ***** na resposta da API.
• IU de gerenciamento: é possível ver os KVMs com escopo de ambiente na IU 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 uso de um KVM para preencher valores em um URL, consulte Criar modelo de URL de destino com KVM por ambiente.