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 clássica 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 Adicionar.
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.
Depuração
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.
Apigee no console do Cloud
Para excluir um KVM:
- 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.
- Localize a linha do KVM que você quer excluir.
- Clique em delete na coluna Ações.
- Clique em Excluir mapa de chave-valor na caixa de diálogo para confirmar a operação.
O KVM será excluído e removido da lista.
IU clássica da Apigee
Para excluir um KVM:
- Faça login na IU da Apigee.
- Selecione Administrador > Ambientes > Mapas de chave-valor.
- Na lista suspensa, selecione o ambiente em que você quer excluir um KVM.
A página Mapas de chave-valor exibe uma lista dos KVMs atuais.
- Posicione o cursor sobre o KVM que você quer excluir.
- Clique em deleteExcluir
- Clique em Excluir para confirmar a operação.
O KVM será excluído e removido da lista.
API Apigee
Use uma das seguintes APIs da Apigee para excluir um KVM com base no escopo: