Esta página aplica-se ao Apigee e ao Apigee Hybrid.
Veja a documentação do
Apigee Edge.
Esta secção aborda a utilização de mapas de chave-valor (KVMs).
Vista geral
Há alturas em que quer armazenar dados para obtenção no tempo de execução, ou seja, dados que não expiram e que não devem ser codificados na lógica do proxy da API. Os mapas de chaves-valores (KVMs) são ideais para este fim. Um KVM é uma coleção personalizada de pares de strings de chave/valor encriptados.
Seguem-se três exemplos de utilização gerais para armazenar dados em KVMs:
- Dados da sessão do utilizador: dados que são criados e eliminados apenas pelo tempo de execução; não pode ver nem gerir entradas KVM fora do tempo de execução. Por exemplo, o conteúdo do carrinho de compras.
- Configuração (como regras de encaminhamento e tabelas de consulta): dados que são normalmente criados fora do tempo de execução, mas que são lidos pelo tempo de execução. Estes dados são configurados através da IU ou da API
e, em seguida, disponibilizados à gateway (como variáveis ou conteúdo só de leitura).
Por exemplo: tem um proxy de API que precisa de chamar um URL de destino (ou um Service Callout) num ambiente de teste e outro URL de destino num ambiente de produção. Em vez de codificar URLs no proxy da API, pode fazer com que este detete em que ambiente se encontra, execute a política KeyValueMapOperations relacionada e obtenha o URL de destino correto do KVM adequado.
Posteriormente, se um ou ambos os seus alvos mudarem, basta atualizar os KVMs com os novos URLs. O proxy da API recolhe os novos valores. Não é necessário uma nova implementação.
- Credenciais: armazene credenciais, chaves privadas ou tokens, como tokens para serviços externos, credenciais necessárias para gerar tokens OAuth ou chaves privadas usadas em políticas JavaCallout ou JavaScript para encriptação ou assinatura de tokens da Web JSON (JWT). Em vez de transmitir credenciais, chaves ou tokens no pedido, ou codificá-los na lógica do proxy, pode armazená-los num KVM e recuperá-los dinamicamente em chamadas para alvos que os exijam.
Vai descobrir outras situações em que o armazenamento de pares de strings de chave/valor é útil. Em geral, considere usar KVMs quando:
- Secções específicas no seu código requerem valores diferentes no tempo de execução.
- Os dados confidenciais têm de ser transmitidos sem codificação rígida.
- Quer armazenar valores que não expiram, como uma cache.
Em alguns casos, os conjuntos de propriedades são uma boa alternativa aos KVMs, uma vez que podem ser mais fáceis de usar. Para mais informações, consulte o artigo Usar conjuntos de propriedades.
Acerca do âmbito do KVM
O âmbito define onde um KVM está disponível. Os KVMs podem ser criados nos seguintes âmbitos:
| Âmbito | Descrição |
|---|---|
| proxy de API | Apenas o proxy de API pode aceder ao KVM. |
| Ambiente | Todos os proxies de API num ambiente específico podem aceder ao KVM. Por exemplo, pode querer que os proxies de API implementados no ambiente prod não tenham acesso a KVMs no ambiente test. Se quiser que as mesmas chaves KVM
estejam disponíveis na produção, crie um KVM paralelo com âmbito no ambiente prod. |
| Organização | Todos os proxies de API em todos os ambientes podem aceder ao KVM. |
Acerca da encriptação KVM
No Apigee, todas as entradas de KVM para âmbitos de proxy de API, organização e ambiente estão protegidas através da chave do Cloud KMS
fornecida quando uma organização do Apigee é aprovisionada (consulte o campo runtimeDatabaseEncryptionKey no recurso
Organization
).
O Apigee usa o AES256 como norma de encriptação.
No Apigee hybrid, pode fornecer chaves de encriptação separadas para todas as entradas de KVM para âmbitos de proxy de API, organização e ambiente. O Apigee aceita tamanhos de cifras de AES128, AES196 ou AES256 como a norma de encriptação.
Criar KVMs
Crie KVMs conforme descrito nas secções seguintes.
Apigee na Cloud Console
Para criar uma nova KVM (vazia) ou ver uma lista de KVMs:
Na Google Cloud consola, aceda à página Gestão > Ambientes.
- Selecione o ambiente que quer editar na lista de ambientes disponíveis.
- Clique no separador Mapeamentos de valores-chave na página Detalhes do ambiente.
A página Mapeamentos de chaves-valores apresenta uma lista de KVMs existentes. Se não tiver criado nenhuma MVQ, a lista está vazia.
- Para criar um novo KVM (vazio), clique em + Criar mapa de chave-valor.
É apresentada a caixa de diálogo Criar mapa de valores-chave.
- Introduza um nome para o KVM no campo Nome do mapa de valores-chave.
O nome só pode conter letras, números e hífenes, e não pode ter mais de 255 carateres. Não pode incluir espaços nem outros carateres especiais. Por exemplo:
my-kvm-1 - Clique em Criar.
O novo KVM é apresentado na lista.
IU do Apigee Classic
Para criar uma nova KVM (vazia) ou ver uma lista de KVMs:
- Inicie sessão na IU do Apigee.
- Selecione Administração > Ambientes > Mapas de valores-chave.
- Na lista pendente de ambientes, selecione o ambiente para o qual quer criar um KVM.
A página Mapas de chaves-valores apresenta uma lista de KVMs existentes. Se não tiver criado nenhuma KVM, a lista está vazia.
- Para criar um KVM novo (vazio), clique em + Mapa de chave-valor.
É apresentada a caixa de diálogo Adicionar mapa de chaves-valores.
- Introduza um nome para o KVM no campo Nome.
O nome só pode conter letras, números e hífenes. Não pode incluir espaços nem outros carateres especiais. Por exemplo:
my-kvm-1 - Clique em Adicionar.
O novo KVM é apresentado na lista.
API Apigee
Use as APIs Apigee para criar, listar e eliminar KVMs para os seguintes âmbitos:
Política de KVM
Para criar KVMs em tempo de execução e atualizá-los nos seus proxies de API, use a
política KeyValueMapOperations. Na política, especifica o nome do KVM no atributo mapIdentifier no elemento principal.
O elemento <InitialEntries> permite-lhe criar e preencher um conjunto de entradas de base num novo KVM assim que guardar a política na IU ou implementar o proxy de API (se o tiver desenvolvido offline). Se os valores forem alterados na política, os valores existentes são substituídos. Todos os novos pares de chave/valor são adicionados ao KVM existente juntamente com os pares de chave/valor existentes.
O elemento <Put> cria um novo KVM se ainda não existir e cria uma chave com um ou mais valores. Se o KVM já existir, os pares de chave/valor são adicionados (ou atualizados se a chave já existir). Pode usar vários elementos <Put> numa política de KVM.
Depurar
Quando usa a política KeyValueMapOperations
para obter valores de KVM encriptados, fornece o nome de uma variável para armazenar o
valor. Uma vez que todos os valores de KVM estão encriptados, tem de adicionar o prefixo private. ao nome da variável, o que impede que os pares de chave/valor de KVM apareçam nas sessões de depuração.
A obter KVMs
Recupere KVMs através do elemento <Get> da política KeyValueMapOperations.
Uma vez que todos os valores de KVM estão encriptados,
adicione um prefixo private. ao nome da variável que vai conter o valor obtido.
Esse prefixo oculta o valor das sessões de depuração enquanto depura proxies de API. Para mais informações, consulte o
elemento<Get>.
Eliminar KVMs
Elimine KVMs conforme descrito nas secções seguintes.
Apigee na Cloud Console
Para eliminar um KVM:
Na Google Cloud consola, aceda à página Gestão > Ambientes.
- Selecione o nome do ambiente que quer editar na lista de ambientes disponíveis.
- Clique no separador Mapeamentos de valores-chave na página Detalhes do ambiente.
A página Mapeamentos de chaves-valores apresenta uma lista de KVMs existentes.
- Localize a linha do KVM que quer eliminar.
- Clique em delete na coluna Ações.
- Clique em Eliminar mapa de valores-chave na caixa de diálogo para confirmar a operação.
O KVM é eliminado e removido da lista.
IU do Apigee Classic
Para eliminar um KVM:
- Inicie sessão na IU do Apigee.
- Selecione Administração > Ambientes > Mapas de valores-chave.
- Na lista pendente do ambiente, selecione o ambiente para o qual quer eliminar um KVM.
A página Mapas de chaves-valores apresenta uma lista de KVMs existentes.
- Posicione o cursor sobre o KVM que quer eliminar.
- Clique em delete Eliminar.
- Clique em Eliminar para confirmar a operação.
O KVM é eliminado e removido da lista.
API Apigee
Use uma das seguintes APIs Apigee para eliminar um KVM com base no respetivo âmbito: