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).

Informações gerais

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 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 políticas JavaCallout 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.

Sobre o mascaramento de KVM

Por padrão, os valores de KVM são mostrados como texto simples. É possível ativar o mascaramento de KVM para mascarar valores com asteriscos (*****). Para ativar ou desativar o mascaramento de KVM, use a configuração Mascarar valores na UI ou a flag maskedValues na solicitação de API.

Os valores são mascarados no nível do KVM. Não é possível mascarar entradas individuais de KVM. Todos os valores em um KVM são mascarados ou nenhum deles é.

Observação:a máscara KVM não será ativada automaticamente para KMVs atuais. É necessário atualizar explicitamente os KVMs atuais para usar a máscara de KVM.

Criar KVMs

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

IU da Apigee

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

  1. No console do Google Cloud , acesse a página Apigee > Gerenciamento > Ambientes.

    Acessar "Ambientes"

  2. Na lista de ambientes disponíveis, selecione aquele que você quer editar.
  3. Clique na guia Mapas de chave-valor na página Detalhes do ambiente.

    A página Mapas de chave-valor mostra uma lista de KVMs atuais. Se você não criou nenhum KVM, a lista estará vazia.

  4. Para criar um KVM novo (vazio), clique em + Criar mapa de chave-valor.

    A caixa de diálogo Criar mapa de chave-valor é aberta.

  5. 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. Por exemplo: my-kvm-1

  6. Clique em Mascarar valores para mascarar todos os valores. Se não estiver selecionada, os valores de KVM serão mostrados em texto simples. Consulte Sobre a mascaramento de KVM para mais informações.
  7. Clique em Criar.

    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.

Receber KVMs

IU da Apigee

Para conferir uma lista de KVMs e os detalhes delas na IU da Apigee:

  1. Acesse a lista de KVMs do seu ambiente (consulte Criar KVMs).
  2. A página Mapas de chave-valor mostra uma lista de KVMs atuais.
  3. Selecione o nome de um KVM para ver as entradas e configurações dele.

API Apigee

Use as APIs da Apigee para receber KVMs para os seguintes escopos:

Por exemplo, para receber um KVM no escopo do proxy de API, insira uma solicitação GET para o seguinte URL:

https://apigee.googleapis.com/v1/organizations/ORG/apis/API/keyvaluemaps/KVM

Atualizar KVMs

IU da Apigee

Para atualizar a configuração Valores de máscara de uma KVM na IU da Apigee:

  1. Acesse a lista de KVMs do seu ambiente (consulte Criar KVMs).
  2. Selecione o nome do KVM para abrir a página de detalhes.
  3. Ative ou desative a configuração Mascarar valores.
  4. Clique em Salvar.

API Apigee

Use as APIs da Apigee para atualizar KVMs nos seguintes escopos:

Por exemplo, para atualizar um KVM no escopo de um proxy de API, insira uma solicitação PUT para o seguinte URL:

https://apigee.googleapis.com/v1/organizations/ORG/apis/API/keyvaluemaps/KVM

Gerenciar valores de KVM

É possível gerenciar valores de KVM usando os seguintes métodos:

IU da Apigee

Para gerenciar entradas de KVM na IU da Apigee:

  1. Acesse a lista de KVMs do seu ambiente (consulte Criar KVMs).
  2. Selecione o nome do KVM para abrir a página de detalhes.
  3. Para gerenciar entradas:
    • Adicionar uma entrada: clique em + Adicionar. Preencha os campos Chave e Valor e clique em Adicionar.
    • Editar uma entrada: clique em Editar ao lado de uma entrada. Atualize o Valor e clique em Salvar.
    • Excluir uma entrada: clique em Excluir ao lado de uma entrada. Clique em Copiar na caixa de diálogo de confirmação.

API Apigee

Use as APIs da Apigee para gerenciar valores de KVM nos seguintes escopos:

Política KeyValueMapOperations

Use a política KeyValueMapOperations para adicionar, receber ou excluir valores de KVMs.

Adicione chaves e valores de KVM usando o elemento <Put> da política KeyValueMapOperations. 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. Para mais informações, consulte o elemento<Put>.

Receba valores de KVM 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 vai 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>.

Exclua valores de KVM usando o elemento <Delete> da política KeyValueMapOperations. Para mais informações, consulte o elemento<Delete>.

Excluir KVMs

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

IU da Apigee

Para excluir um KVM:

  1. No console do Google Cloud , acesse a página Apigee > Gerenciamento > Ambientes.

    Acessar "Ambientes"

  2. Na lista de ambientes disponíveis, selecione aquele que você quer editar.
  3. Clique na guia Mapas de chave-valor na página Detalhes do ambiente.

    A página Mapas de chave-valor mostra uma lista de KVMs atuais.

  4. Localize a linha do KVM que você quer excluir.
  5. Clique em Excluir na coluna Ações.
  6. 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.

API Apigee

Use uma das seguintes APIs da Apigee para excluir um KVM com base no escopo: