Como usar mapas de chave-valor

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Esta seção discute como usar mapas de chave-valor (KVMs, na sigla em inglês).

Visão geral

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 valor/chave criptografados.

Veja a seguir três casos de uso amplos para armazenar dados em KVMs:

Dados da sessão do usuário: dados criados e excluídos pelo tempo de execução. não é possível visualizar ou gerenciar entradas do KVM fora do ambiente de execução. Por exemplo, o conteúdo do carrinho de compras.
Configuração (como regras de roteamento e tabelas de pesquisa): os dados que geralmente são criados fora do ambiente de execução, mas lidos pelo ambiente de execução. Esses dados são configurados usando a IU ou a API e, em seguida, são disponibilizados para o gateway (como variáveis ou conteúdo somente leitura).
Por exemplo: 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 proxy da API, você pode detectar a existência do ambiente em que ele está, executar a política KeyValueMapOperations relacionada e recuperar o URL de destino correto do KVM apropriado.

Posteriormente, se um ou ambos os destinos forem alterados, basta atualizar os KVMs com os novos URLs. O proxy de API seleciona os novos valores e não é necessária uma reimplantação.
Credenciais: armazene 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 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:

As sessões específicas do seu código exigem valores diferentes no ambiente de execução.
Dados confidenciais precisam ser transmitidos sem codificar.
Você quer armazenar valores que não expiram como um cache.

Em alguns casos, conjuntos de propriedades são uma boa alternativa para KVMs, porque são mais fáceis de usar. Para mais informações, consulte Como usar conjuntos de propriedades.

Sobre o escopo do KVM

O escopo define onde um KVM está disponível. Os KVMs podem ser criados nos seguintes escopos:

Escopo	Descrição
Proxy de API	Somente o proxy da API pode acessar o KVM.
Ambiente	Todos os proxies de API em um ambiente específico podem acessar o KVM. Por exemplo, talvez você queira que os proxies de API implantados no ambiente `prod` não tenham acesso a KVMs no ambiente `test`. Se você quiser que as mesmas chaves KVM estejam disponíveis na produção, crie um KVM paralelo com escopo para o ambiente `prod`.
Organização	Todos os proxies de API em todos os ambientes podem acessar o KVM.

Sobre a criptografia KVM

No Apigee, todas as entradas da KVM para os escopos do proxy de API, da organização e do ambiente são protegidas usando a chave do Cloud KMS fornecida quando uma organização da Apigee é provisionada. Consulte o campo runtimeDatabaseEncryptionKey no recurso Organização. A Apigee usa o AES256 como o padrão de criptografia.

No híbrido da Apigee, é possível fornecer chaves de criptografia separadas para todas as entradas da KVM para escopos de proxy de API, organização e ambiente. A Apigee aceita tamanhos de criptografia de AES128, AES196 ou AES256 como o padrão de criptografia.

Como criar KVMs

Crie KVMs conforme descrito nas seções a seguir.

Apigee no console do Cloud

Para criar um KVM novo (vazio) ou visualizar uma lista de KVMs:

Abra a interface da Apigee no console do Cloud em um navegador.
No painel de navegação à esquerda, clique em Gerenciamento > Ambientes.
Na lista de ambientes disponíveis, selecione aquele que você quer editar.
Clique na guia Mapas de chave-valor na página Detalhes do ambiente.
A página Mapas de chave-valor exibe uma lista dos KVMs atuais. Se você não criou nenhum KVM, a lista estará vazia.
Para criar um KVM novo (vazio), clique em + Criar mapa de chave-valor.
A caixa de diálogo Adicionar mapa de chave-valor é aberta.
Insira um nome para o KVM no campo Nome do mapa de chave-valor.
O nome só pode conter letras, números e hifens e não pode ter mais de 255 caracteres. Não pode incluir espaços ou outros caracteres especiais. Exemplo: my-kvm-1
Clique em Criar.
O novo KVM é exibido na lista.

IU da Apigee

Para criar um KVM novo (vazio) ou visualizar uma lista de KVMs:

Faça login na IU da Apigee.
Selecione Administrador > Ambientes > Mapas de chave-valor.
Na lista suspensa, selecione o ambiente em que você quer criar um KVM.
A página Mapas de chave-valor exibe uma lista dos KVMs atuais. Se você não criou nenhum KVM, a lista estará vazia.
Para criar um novo KVM (vazio), clique em +Mapa de chave-valor.
A caixa de diálogo Adicionar mapa de chave-valor é aberta.
Digite um nome para o KVM no campo Nome.
O nome só pode conter letras, números e hífens. Não pode incluir espaços ou outros caracteres especiais. Exemplo: my-kvm-1
Clique em Add.
O novo KVM é exibido na lista.

API Apigee

Use as APIs da Apigee para criar, listar e excluir KVMs para os seguintes escopos:

Política da KVM

Para criar KVMs no momento da execução e atualizá-las nos proxies da API, use a política KeyValueMapOperations. 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. Todos os novos pares de chave-valor são adicionados ao KVM atual com os pares de chave-valor.

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, os pares de chave-valor serão adicionados (ou atualizados, se a chave já existir). É possível usar vários elementos <Put> em uma política de KVM.

Debug

Ao usar a política KeyValueMapOperations para recuperar valores de KVM criptografados, forneça o nome de uma variável para armazenar o valor. Como todos os valores de KVM são criptografados, você precisa adicionar o prefixo private. ao nome da variável. Isso impede que os pares de chave-valor da KVM sejam exibidos nas sessões de depuração.

Como recuperar KVMs

Recupere KVMs usando o elemento <Get> da política KeyValueMapOperations. Como todos os valores KVM são criptografados, adicione um prefixo private. ao nome da variável que conterá o valor recuperado. Esse prefixo oculta o valor das sessões de depuração enquanto você está depurando proxies da API. Para mais informações, consulte o elemento<Get>.

Como excluir KVMs

Exclua os KVMs, conforme descrito nas seções a seguir.