Política KeyValueMapOperations

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

Confira a documentação da Apigee Edge.

O que

Fornece acesso baseado em políticas a um armazenamento de mapa de chave-valor (KVM) disponível na Apigee. Os pares de chave-valor podem ser armazenados, recuperados e excluídos de mapas existentes com a configuração de políticas KeyValueMapOperations, que especificam as operações PUT, GET ou DELETE, respectivamente. É preciso que pelo menos uma dessas operações seja executada pela política.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

Observação: a partir da versão 1.4.0 da Apigee híbrida, a Apigee criptografa todos os KVMs por padrão. Use o atributo private. com todas as variáveis ao acessar um KVM com o comando GET para ocultar as informações do KVM em uma sessão de depuração. Se o atributo private. não for usado, o KVM ainda será criptografado. No entanto, as informações do KVM aparecerão descriptografadas na sessão de depuração e nenhuma exceção será gerada.

Vídeo: apresenta uma introdução geral aos KVMs.

Amostras

PUT KVM com um literal

Quando a política a seguir é executada, ela cria um KVM criptografado chamado FooKVM e, em seguida, uma chave chamada FooKey_1 com dois valores definidos com strings literais foo e bar (não com valores extraídos das variáveis). Ao GET a chave no próximo exemplo, você especifica um número de índice para recuperar o valor desejado.

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="FooKVM" mapIdentifier="FooKVM">
  <DisplayName>FooKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Put>
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
    <Value>foo</Value>
    <Value>bar</Value>
  </Put>
</KeyValueMapOperations>

Observe que o escopo é environment. Isso significa que é possível ver o KVM na IU de gerenciamento em APIs > Configuração do ambiente > Mapas de chave-valor. Todos os KVMs mostrados nessa página estão no escopo do ambiente selecionado.

GET KVM de um literal

Essa política analisa o mapa FooKVM do exemplo anterior, usa o segundo valor (índice="2") da chave FooKey_1 e armazena-o em uma variável chamada foo_variable.

<KeyValueMapOperations mapIdentifier="FooKVM" async="false" continueOnError="false" enabled="true" name="GetKVM">
  <DisplayName>GetKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Get assignTo="foo_variable" index="2">
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

Acessar um KVM dinamicamente

Esta política usa o elemento <MapName> para referenciar um KVM dinamicamente com uma variável de fluxo. O elemento recebe o identificador KVM da variável de fluxo. Observe que o atributo mapIdentifier é omitido; não é possível usar <MapName> com o atributo mapIdentifier.

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="GetKVM">
  <DisplayName>GetKVM</DisplayName>
  <MapName ref="flow.variable"/>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Get assignTo="foo_variable" index="2">
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

PUT KVM com uma variável

Um exemplo simples de um KVM útil é o serviço de encurtamento de URL. O KVM pode ser configurado para armazenar URLs encurtados junto como os respectivos URLs completos.

Este exemplo de política cria um KVM. A política usa o comando PUT para inserir uma chave com dois valores associados em um KVM chamado urlMapper.

<KeyValueMapOperations name="putUrl" mapIdentifier="urlMapper">
  <Scope>apiproxy</Scope>
  <Put override="true">
    <Key>
      <Parameter ref="urlencoding.requesturl.hashed"/>
    </Key>
    <Value ref="urlencoding.longurl.encoded"/>
    <Value ref="request.queryparam.url"/>
  </Put>
</KeyValueMapOperations>

Neste caso, a chave urlencoding.requesturl.hashed é um exemplo de uma variável personalizada. O URL da solicitação com hash seria gerado pelo código (JavaScript ou Java, por exemplo) e, em seguida, armazenado nessa variável, em que a política KeyValueMapOperations pode acessá-lo.

Para cada chave, requesturl.hashed, dois valores são armazenados:

• O conteúdo da variável personalizada chamada urlencoding.longurl.encoded
• O conteúdo da variável predefinida request.queryparam.url

Por exemplo, quando a política é executada no ambiente de execução, os valores das variáveis podem ser os seguintes:

• urlencoding.requesturl.hashed: ed24e12820f2f900ae383b7cc4f2b31c402db1be
• urlencoding.longurl.encoded: http://tinyurl.com/38lwmlr
• request.queryparam.url: http://apigee.com

O KVM e a entrada a seguir seriam gerados no armazenamento de chave-valor da Apigee e com escopo definido para o proxy da API a que a política está anexada:

{
    "entry" :[
        {
            "name" : "ed24e12820f2f900ae383b7cc4f2b31c402db1be",
            "value" : "http://tinyurl.com/38lwmlr,http://apigee.com"
        }
    ],
    "name" : "urlMapper"
}

A entrada permanecerá até que ela seja excluída. As entradas de armazenamento de chave-valor são distribuídas entre as instâncias da Apigee que executam a nuvem.

GET KVM de uma variável

Um exemplo simples de um KVM útil é o serviço de encurtamento de URL. O KVM pode ser configurado para armazenar URLs encurtados junto como os respectivos URLs completos.

Para recuperar o valor da entrada do KVM, como a coberta na guia KeyValueMapOperations PUT, configure uma política para GET o KVM:

<KeyValueMapOperations name="getUrl" mapIdentifier="urlMapper">
  <Scope>apiproxy</Scope>
  <Get assignTo="urlencoding.shorturl" index='1'>
    <Key>
      <Parameter ref="urlencoding.requesturl.hashed"/>
    </Key>
  </Get>
</KeyValueMapOperations>

Quando essa política for executada, se o valor da variável urlencoding.requesturl.hashed for ed24e12820f2f900ae383b7cc4f2b31c402db1be, a variável personalizada chamada urlencoding.shorturl será definida com o valor http://tinyurl.com/38lwmlr.

Agora que os dados foram recuperados, outras políticas e códigos podem acessá-los extraindo o valor dessas variáveis.

GET valor do KVM

Use o atributo private. com todas as variáveis ao acessar um KVM com o comando GET para ocultar as informações do KVM em uma sessão de depuração. Se o atributo private. não for usado, o KVM ainda será criptografado. No entanto, as informações do KVM aparecerão descriptografadas na sessão de depuração e nenhuma exceção será gerada.

Neste exemplo, a variável private.encryptedVar mantém o valor descriptografado da chave foo do KVM.

<KeyValueMapOperations name="getEncrypted" mapIdentifier="encrypted_map">
  <Scope>apiproxy</Scope>
  <Get assignTo="private.encryptedVar" index='1'>
    <Key>
      <Parameter>foo</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

Agora que os dados foram recuperados, outras políticas e códigos podem acessá-los extraindo o valor dessa variável.

<KeyValueMapOperations>

Fornece acesso baseado em políticas a um mapa de chave-valor (KVM).

Sintaxe

<KeyValueMapOperations async="false" continueOnError="false"
    enabled="true" name="Key-Value-Map-Operations-1"
    mapIdentifier="urlMapper" >
  <DisplayName>Key Value Map Operations 1</DisplayName>
  <Scope>environment</Scope>
  <ExpiryTimeInSecs>300</ExpiryTimeInSecs>
  <InitialEntries>
    <Entry>
      <Key>
        <Parameter>KEY_NAME_LITERAL</Parameter>
      </Key>
      <Value>VALUE_LITERAL</Value>
    </Entry>
    <Entry>
      <Key>
         <Parameter>KEY_NAME_LITERAL</Parameter>
      </Key>
      <Value>VALUE_LITERAL</Value>
      <Value>VALUE_LITERAL</Value>
    </Entry>
  </InitialEntries>
  <Put override="BOOLEAN">
    <Key>
       <Parameter>KEY_NAME_LITERAL</Parameter>
    </Key>
  </Put>
  <Get assignTo="VARIABLE_NAME" index="INDEX_NUMBER">
    <Key>
       <Parameter>KEY_NAME_LITERAL</Parameter>
    </Key>
  </Get>
  <Delete>
    <Key>
       <Parameter>KEY_NAME_LITERAL</Parameter>
    </Key>
  </Delete>
</KeyValueMapOperations>

Atributos <KeyValueMapOperations>

O exemplo a seguir mostra os atributos do elemento <KeyValueMapOperations>:

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="Key-Value-Map-Operations-1" mapIdentifier="map_name">

A tabela a seguir descreve os atributos do elemento <KeyValueMapOperations>:

Observação: o atributo mapIdentifier especifica o nome do KVM com que você quer interagir. Também é possível especificar um KVM dinamicamente com o elemento <MapName>.

Atributo	Descrição	Padrão	Presence
mapIdentifier	Especifica um identificador que informa à política que KVM ele precisa acessar. Se esse identificador e <MapName> não estiverem presentes, um KVM chamado kvmap será usada. Não será possível usar esse atributo se você especificar o elemento <MapName>.	N/A	Opcional

A tabela a seguir descreve atributos comuns a todos os elementos pai de políticas:

Atributo	Descrição	Padrão	Presence
name	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres. Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.	N/A	Obrigatório
continueOnError	Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas. Defina como true para que a execução do fluxo continue mesmo depois que uma política falhar. Consulte também: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual	false	Opcional
enabled	Defina como true para aplicar a política. Defina como false para desativar a política. A política não será aplicada mesmo se ela permanecer anexada a um fluxo.	true	Opcional
async	Esse atributo está obsoleto.	false	Descontinuado

Elemento <DisplayName>

Use em conjunto com o atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.

<DisplayName>Policy Display Name</DisplayName>

Padrão	N/A Se você omitir esse elemento, será usado o valor do atributo name da política.
Presence	Opcional
Tipo	String

Elementos filhos

Esta seção descreve os elementos e atributos da política KeyValueMapOperations:

Elemento <Delete>

Exclui o par de chave-valor especificado. Pelo menos um entre <Get>, <Put> ou <Delete> precisa ser usado.

Especifique o nome do KVM com o atributo mapIdentifier no elemento raiz ou com o elemento <MapName>. Exemplo:

<Delete>
   <Key>
      <Parameter>KEY_NAME_LITERAL</Parameter>
   </Key>
</Delete>

Padrão	N/A
Presence	Obrigatório se <Get> ou <Put> não estiver presente.
Tipo	N/A

Elemento <Entry>

Valores de semente para KVMs, que são preenchidas no KVM quando ele é inicializado. Para a Apigee, o tamanho da chave é limitado a 2 KB.

Exemplo:

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>KEY_NAME_LITERAL</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>key_name_variable</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

Padrão	N/A
Presence	Opcional
Tipo	N/A

Elemento <ExclusiveCache>

Obsoleto. Em vez dele, use o elemento <Scope>.

Elemento <ExpiryTimeInSecs>

Especifica a duração em segundos após a Apigee atualizar o valor em cache do KVM especificado.

Um valor de 0 ou -1, ou a exclusão desse elemento, significa que o valor padrão de 300 segundos é usado. Exemplo:

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

Padrão	300 (5 minutos)
Presence	Opcional
Tipo	Número inteiro

Um KVM é um mecanismo de persistência de longo prazo que armazena chaves e valores em um banco de dados NoSQL. Por isso, a leitura de um KVM no ambiente de execução pode diminuir o desempenho do proxy. Para melhorar o desempenho, a Apigee tem um mecanismo integrado para armazenar em cache as chaves/valores do KVM na memória durante o tempo de execução. Essa política de operações do KVM sempre lê o cache para operações GET.

O elemento <ExpiryTimeInSecs> permite controlar por quanto tempo as chaves/valores usadas na política são armazenadas em cache antes de serem atualizadas novamente do KVM. No entanto, há algumas diferenças entre como as operações GET e PUT afetam a expiração do cache.

GET - Na primeira vez que uma operação GET do KVM é executada, os valores/chaves solicitados do KVM (com nome especificado no atributo raiz mapIdentifier da política ou o elemento <MapName>) são carregados no cache, onde permanecem para as operações GET subsequentes até que uma das seguintes situações ocorra:

• O número de segundos especificado em <ExpiryTimeInSecs> expira.
  ou
• Uma operação PUT em uma política de KVM substitui os valores existentes (explicado a seguir).

PUT: uma operação PUT grava chaves/valores no KVM especificado. Se o PUT fizer a gravação em uma chave que já existe no cache, ele será atualizado imediatamente e passará a manter o novo valor pelo número de segundos especificado no elemento <ExpiryTimeInSecs> da política. No entanto, o uso de PUT atualizará apenas o cache no nó de ambiente de execução único que atende à solicitação. Para atualizar o cache em cada nó de ambiente de execução distribuído, use o elemento <ExpiryTimeInSecs> para especificar intervalos de atualização para cada nó.

Exemplo: como armazenar um KVM em cache

1. Uma operação GET recupera o valor de "classificação", que adiciona o valor "10" ao cache. O <ExpiryTimeInSecs> na política é 60.
2. Trinta segundos depois, a política GET é executada novamente e recupera 10 do cache.
3. Cinco segundos depois, uma política PUT atualiza o valor de rating para 10, e o <ExpiryTimeInSecs> na política PUT é 20. O cache é atualizado imediatamente com o novo valor, que agora está configurado para permanecer no cache por 20 segundos. Se o PUT não tivesse ocorrido, o cache preenchido originalmente pelo primeiro GET ainda existiria por mais 30 segundos, tempo restante dos 60 segundos originais.
4. Quinze segundos depois, outro GET executa e recupera um valor de 8.

Observações

• Para ter o melhor desempenho, equilibre o tempo de expiração do cache com a quantidade de tráfego de API esperado. Com tráfego intenso, por exemplo, convém definir intervalos de expiração de cache mais longos para evitar atualizações frequentes do banco de dados.
• Não há como redefinir manualmente o cache do KVM. No entanto, você pode criar uma política temporária que executa uma operação PUT única com um <ExpiryTimeInSecs> curto. Isso redefinirá o cache, que contém o valor PUT, durante o número de segundos especificado.
• Atualizar um KVM com a interface ou API da Apigee não redefine o cache do KVM.
• É possível usar várias operações na mesma política. Se você fizer isso, a política executará as operações em ordem. Se você usar um PUT seguido por um GET na mesma política usando a mesma chave, o PUT, quando for gravado, redefinirá implicitamente a expiração do cache.

Elemento <Get>

Recupera o valor da chave especificada. Pelo menos um entre <Get>, <Put> ou <Delete> precisa ser usado.

A Apigee criptografa todos os dados armazenados no KVM. Para mais detalhes, consulte Sobre chaves de criptografia. Ao usar <Get>, a Apigee descriptografa os dados armazenados e os atribui a uma variável no contexto da mensagem. O nome da variável é especificado usando o atributo assignTo.

Especifique o nome do KVM com o atributo mapIdentifier no elemento raiz ou com o elemento <MapName>.

É possível incluir vários blocos Get na política para recuperar vários itens de um KVM.

Observação: é possível usar várias operações na mesma política. Se você fizer isso, a política executará as operações em ordem. Se você usar um PUT seguido por um GET na mesma política usando a mesma chave, o PUT, quando for gravado, redefinirá implicitamente a expiração do cache. Consulte o elemento ExpiryTimeInSecs para mais informações.

Padrão	N/A
Presence	Obrigatório se <Put> ou <Delete> não estiver presente.
Tipo	N/A

Atributos

A tabela a seguir descreve os atributos do elemento <Get>:

Atributo	Descrição	Padrão	Presence
assignTo	A variável a que o valor recuperado será atribuído.	N/A	Obrigatório
index	O número do índice (em um índice baseado em 1) do item a ser buscado em uma chave com vários valores. Por exemplo, especificar index=1 retornará o primeiro valor e o atribuirá à variável assignTo. Se nenhum valor de índice for especificado, todos os valores dessa entrada serão atribuídos à variável como um java.util.List. Por exemplo, consulte a guia Receber valor criptografado de KVM em Amostras.	N/A	Opcional

Receber um único item de um KVM

Com esse exemplo de configuração de etapa, a política lê e descriptografa o valor de uma única chave no KVM e atribui o valor descriptografado a uma variável chamada myvar.

<Get assignTo="myvar" index="1">
  <Key>
    <Parameter>key_name_literal</Parameter>
  </Key>
</Get>

Como excluir dados recuperados de sessões de depuração

Em alguns casos, os dados armazenados no KVM são confidenciais. Para evitar que os dados recuperados apareçam em uma sessão de depuração, use o prefixo private. no nome da variável especificado no atributo assignTo. , Se você não usar o prefixo private., os dados recuperados do KVM aparecerão em texto não criptografado em qualquer sessão de depuração que você criar.

Com esse exemplo de configuração de etapa, a política lê e descriptografa o valor associado a uma única chave no KVM e atribui esse valor a uma variável. A atribuição não aparecerá em uma sessão de depuração.

<Get assignTo="private.myvar" index="1">
  <Key>
    <Parameter>key_name_literal</Parameter>
  </Key>
</Get>

Acessar vários itens de um KVM

No exemplo a seguir, considere um KVM com as chaves e os valores a seguir. Além de armazenar uma lista de execução dos filmes mais famosos de todos os tempos, o KVM armazena o nome do diretor de todos os grandes filmes.

Chave	Valor
top_movies	Princess Bride,The Godfather,Citizen Kane
Citizen Kane	Orson Welles
Princess Bride	Rob Reiner
O Poderoso Chefão	Francis Ford Coppola

Observe que o valor associado à chave top_movies contém vários nomes de filmes, separados por vírgulas.

Com este exemplo de configuração, a política recupera o principal filme atual e o nome do diretor:

<Get assignTo="top.movie.pick" index="1">
  <Key>
    <Parameter>top_movies</Parameter>
  </Key>
</Get>
<Get assignTo="movie.director">
  <Key>
    <Parameter ref="top.movie.pick"/>
  </Key>
</Get>

Quando o proxy de API é chamado, a Apigee cria as seguintes variáveis com valores correspondentes, que podem ser usadas posteriormente no fluxo do proxy de API:

• top.movie.pick=Princess Bride
• movie.director=Rob Reiner

O valor para top.movie.pick é apenas o primeiro item na lista separada por vírgulas, porque o primeiro elemento <Get> usa um atributo index de 1. Em seguida, o segundo elemento <Get> usa o valor atribuído a top.movie.pick como a chave para recuperar um valor em movie.director.

Elemento <InitialEntries>

Valores de semente para KVMs, que são preenchidas no KVM quando ele é inicializado. Especifique o nome do KVM com o atributo mapIdentifier no elemento raiz.

Observação: o <InitialEntries> não será permitido se o elemento <MapName> for usado.

Exemplo:

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>KEY_NAME_LITERAL</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>KEY_NAME_VARIABLE</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

Ao usar esse elemento, quando você salva a política na IU da Apigee em uma versão implantada do proxy de API, ou implanta o pacote de proxy da API que contém a política com esse elemento, as chaves são criadas automaticamente no KVM. Se os valores na política forem diferentes dos valores no KVM, os valores no KVM serão substituídos quando o proxy de API for implantado. Todas as novas chaves/valores são adicionadas ao KVM existente com as chaves/valores atuais.

As chaves e os valores preenchidos por esse elemento precisam ser literais. Por exemplo, <Parameter ref="request.queryparam.key"> não é compatível com esse elemento.

O tamanho da chave é limitado a 2 KB.

Padrão	N/A
Presence	Opcional
Tipo	N/A

Elemento <Key>

Especifica a chave em uma entrada do KVM. Este elemento aparece como filho de<Get> , <Put> ou<Delete> ou como filha de<Entry> que é filho de<InitialEntries> , Veja um exemplo de chave fixa:

<Key>
  <Parameter>KEY_NAME_LITERAL</Parameter>
</Key>

Uma chave pode ser composta, com elementos dinâmicos, o que significa que mais de uma <Parameter> pode ser anexada para criar a chave. Por exemplo, o conteúdo das variáveis userID e role pode ser combinado para criar uma chave dinâmica. Este é um exemplo de configuração de etapa que especifica uma chave composta e determinada dinamicamente:

<Key>
  <Parameter ref='userID'/>
  <Parameter ref='role'/>
</Key>

Consulte o elemento <Parameter> para ver detalhes sobre como definir o nome da chave.

O tamanho da chave é limitado a 2 KB.

Observação: o nome ratelimit é reservado. Para mais informações, consulte esta postagem da comunidade da Apigee.

Padrão	N/A
Presence	Opcional
Tipo	N/A

Elemento <MapName>

O elemento <MapName> permite que a política identifique qual KVM usar dinamicamente, no ambiente de execução. A capacidade de selecionar KVMs dinamicamente oferece a flexibilidade de projetar uma política KeyValueMapOperations que pode acessar diferentes KVMs, dependendo do contexto em que a política é executada.

Alguns exemplos:

<!-- use one of the following forms -->

<MapName>literal_string</MapName>

<MapName ref="flow.variable"></MapName>

<MapName ref="flow.variable">literal_string</MapName>

A primeira linha especifica o nome do KVM como uma string literal. A segunda linha recebe o nome de uma variável de fluxo. No terceiro caso, se a variável de fluxo for resolvida como um valor vazio, a string literal será usada.

Não especifique o atributo mapIdentifier se você usar <MapName> na política. Consulte os atributos de política para mais informações.

Se o mapa não existir quando o proxy estiver implantado, o mapa não será criado e a Apigee emitirá um erro de ambiente de execução quando a política for executada. Se a variável de fluxo for fornecida, o elemento <InitialEntries> não será permitido. Você receberá um erro de validação durante a implantação.

Elemento <Parameter>

Especifica um componente de uma chave em um par de chave-valor. Esse elemento especifica o nome ao criar, atualizar, recuperar ou excluir o par de chave-valor.

É possível especificar o nome usando:

• uma string literal;

  <Key>
    <Parameter>literal</Parameter>
  </Key>

• uma variável a ser recuperada no ambiente de execução, usando o atributo ref;

  <Key>
    <Parameter ref="variable_name"/>
  </Key>

• uma combinação de literais e referências de variáveis.

  <Key>
    <Parameter>targeturl</Parameter>
    <Parameter ref="apiproxy.name"/>
    <Parameter>weight</Parameter>
  </Key>

Quando o elemento <Key> inclui vários elementos <Parameter>, a string de chave efetiva é a concatenação dos valores de cada parâmetro, unidos por um sublinhado duplo. No exemplo acima, se a variável apiproxy.name tiver o valor abc1, a chave efetiva será targeturl__abc1__weight.

Se você está recebendo, atualizando ou excluindo uma entrada de chave-valor, o nome da chave precisa ser igual ao nome que ela tem no KVM. Consulte Como especificar e recuperar nomes de chaves para ver as diretrizes.

Padrão	N/A
Presence	Obrigatório
Tipo	String

Atributos

A tabela a seguir descreve os atributos do elemento <Parameter>:

Atributo	Descrição	Padrão	Presence
ref	Especifica o nome de uma variável com valor que contém o nome exato da chave que você quer criar, receber ou excluir.	N/A	Obrigatório se nenhum valor literal for fornecido entre as tags de abertura e de fechamento.

Elemento <Put>

Grava um par de chave-valor em um KVM. Se o KVM especificado no atributo mapIdentifier do elemento raiz não existir e se o elemento <MapName> não for usado, o mapa será criado automaticamente. Se o mapa de chave-valor já existir, a chave/valor será adicionada a ele.

Para criar um KVM usando a IU ou a API, consulte:

• Como usar KVMs com a interface da Apigee para criar KVMs criptografados com escopo do ambiente na interface
• API de mapas de chave-valor da organização
• API de mapas de chave-valor do ambiente
• API de mapas de chave-valor do proxy de API

Observação: é possível usar várias operações na mesma política. Se você fizer isso, a política executará as operações em ordem. Se você usar um PUT seguido por um GET na mesma política usando a mesma chave, o PUT, quando for gravado, redefinirá implicitamente a expiração do cache. Consulte o elemento ExpiryTimeInSecs para mais informações.

O tamanho da chave é limitado a 2 KB.

<Put override="false">
  <Key>
    <Parameter ref="mykeyvar"/>
  </Key>
  <Value ref="myvalvar1"/>
</Put>

Padrão	N/A
Presence	Obrigatório se <Get> ou <Delete> não estiver presente.
Tipo	N/A

Aviso: se a política usar o comando PUT para inserir uma chave-valor em um KVM usando uma chave nula, a seguinte chave será criada automaticamente: __$$_EDGE_KVM_EMPTY_KEY_$$__

Essa situação acontecerá, por exemplo, se você estiver preenchendo uma chave usando uma referência de variável nula. Como há novas tentativas com comandos PUT usando chaves nulas, somente essa chave é usada. Portanto, os valores atuais para essa chave poderão ser substituídos sempre que a política for executada.

Atributos

A tabela a seguir descreve os atributos do elemento <Put>:

Atributo	Descrição	Padrão	Presence
substituir	Se definido como true, o valor de uma chave será modificado. <Put override="false"> fará a gravação apenas se, no momento, não houver entrada persistente no repositório do KVM para essa chave.	true	Opcional

Elemento <Scope>

Define o limite de acessibilidade de KVMs. O escopo padrão é environment, o que significa que, por padrão, as entradas de mapas são compartilhadas por todos os proxies de API em execução em um ambiente (por exemplo, teste ou produção). Se você definir o escopo como apiproxy, as entradas no KVM poderão ser acessadas pelo proxy de API que grava os valores no mapa.

Observe que, ao acessar um mapa ou uma entrada do mapa, é preciso especificar o mesmo valor de escopo usado quando o mapa foi criado. Por exemplo, se o mapa foi criado com um escopo de apiproxy, use o escopo apiproxy ao recuperar os valores, inserir alterações ou excluir entradas.

<Scope>environment</Scope>

Padrão	environment
Presence	Opcional
Tipo	String
Valores válidos	organization environment apiproxy policy (revisão do proxy de API)

Elemento <Value>

Especifica o valor de uma chave. Você pode especificar o valor como uma string literal ou, usando o atributo ref, como uma variável a ser recuperada no tempo de execução:

<!-- Specify a literal value -->
<Value>literal<Value>

ou

<!-- Specify the name of variable value to be populated at run time. -->
<Value ref="variable_name"/>

Também é possível incluir vários elementos <Value> para especificar um valor de várias partes. Os valores são combinados no tempo de execução.

No exemplo a seguir, duas chaves foram adicionadas ao KVM:

• Chave k1 com valores v1,v2
• Chave k2 com valores v3,v4

<InitialEntries>
  <Entry>
    <Key>
      <Parameter>k1</Parameter>
    </Key>
    <Value>v1</Value>
    <Value>v2</Value>
  </Entry>
  <Entry>
    <Key>
      <Parameter>k2</Parameter>
    </Key>
    <Value>v3</Value>
    <Value>v4</Value>
  </Entry>
</InitialEntries>

No exemplo a seguir, uma chave foi criada com dois valores. Vamos supor que o nome da organização seja foo_org, o nome do proxy de API seja bar e o ambiente seja test:

• Chave foo_org com valores bar,test

<Put>
  <Key>
    <Parameter ref="organization.name"/>
  </Key>
  <Value ref="apiproxy.name"/>
  <Value ref="environment.name"/>
</Put>

Padrão	N/A
Presence	Obrigatório
Tipo	String

Atributos

A tabela a seguir descreve os atributos do elemento <Value>:

Atributo	Descrição	Padrão	Presence
ref	Especifica o nome de uma variável com valor que contém os valores de chave que você quer definir.	N/A	Obrigatório se nenhum valor literal for fornecido entre as tags de abertura e de fechamento. Proibido se um valor literal for fornecido.

Referência de erros

Nesta seção, descrevemos os códigos de falha e as mensagens de erro retornadas e as variáveis com falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

Esses erros podem ocorrer quando a política é executada.

Dica: precisa de ajuda para resolver um erro? Clique em na coluna "Correção" para ver informações detalhadas sobre solução de problemas.

Código de falha	Status HTTP	Causa	Corrigir
steps.keyvaluemapoperations.UnsupportedOperationException	500	Esse erro ocorrerá se o atributo mapIdentifier estiver definido como uma string vazia na política KeyValueMapOperations.

Erros na implantação

Esses erros podem ocorrer quando você implanta um proxy que contém esta política.

Dica: precisa de ajuda para resolver um erro? Clique em na coluna "Corrigir" para informações detalhadas sobre a solução de problemas.

Erro de nome	Causa	Correção
InvalidIndex	Se o atributo index especificado no elemento <Get> da política KeyValueMapOperations for zero ou um número negativo, a implantação do proxy da API falhará. O índice começa em 1, portanto, um índice de zero ou inteiro negativo é considerado inválido.
KeyIsMissing	Esse erro ocorrerá se o elemento <Key> estiver completamente ausente ou o elemento <Parameter> estiver ausente no elemento <Key> abaixo do <Entry> do elemento <InitialEntries> de KeyValueMapOperations.
ValueIsMissing	Esse erro ocorrerá se o elemento <Value> estiver ausente do elemento <Entry> do elemento <InitialEntries> da política KeyValueMapOperations.

Esquemas

Amostra: veja nossas amostras de repositório do GitHub para os esquemas mais recentes.

Observações sobre uso

Para uma visão geral dos KVMs, consulte Como usar mapas de chave-valor.

Usando a IU da Apigee, é possível definir KVMs somente no escopo do ambiente, conforme descrito em Como usar KVMs com a IU da Apigee. Usando a API da Apigee, é possível definir KVMs no escopo da organização, do ambiente ou do proxy de API, conforme descrito nas seguintes seções:

• API de mapas de chave-valor da organização
• API de mapas de chave-valor do ambiente
• API de mapas de chave-valor do proxy de API

Um armazenamento do KVM fornece um mecanismo de persistência leve para dados formatados como pares de chave-valor. Você pode acessá-los no ambiente de execução por meio de políticas ou códigos. Um mapa contém todos os dados arbitrários no formato key=value.

Observação: o tamanho da chave é limitado a 2 KB.

Por exemplo, localhost=127.0.0.1, zip_code=94110 ou first_name=felix. No primeiro exemplo, localhost é uma chave e 127.0.0.1 é um valor. Cada par de chave-valor é armazenado como uma entrada em um mapa de chave-valor. Um KVM pode armazenar muitas entradas.

Por exemplo, digamos que você precise armazenar uma lista de endereços IP associados a vários ambientes de back-end. É possível criar um KVM chamado ipAddresses que contenha uma lista de pares de chave-valor como entradas. Por exemplo, este JSON pode representar esse mapa:

{
  "entry" : [ {
    "name" : "Development",
    "value" : "65.87.18.18"
  }, {
    "name" : "Staging",
    "value" : "65.87.18.22"
  } ],
  "name" : "ipAddresses"
}

Você pode usar essa estrutura para criar um armazenamento de endereços IP que poderia ser usado por políticas no ambiente de execução para aplicar uma lista de permissões/negações de IP, selecionar dinamicamente um endereço de destino de back-end e assim por diante. Normalmente, a política KeyValueMapOperations é usada para armazenar ou recuperar informações de longa duração que precisam ser reutilizadas em várias transações de solicitação/resposta.

Os KVMs podem ser manipulados por meio da política KeyValueMapOperations ou diretamente por meio da API Apigee. Use a API para, por exemplo, fazer upload de grandes conjuntos de dados no armazenamento de chave/valor ou criar scripts para gerenciar as entradas do mapa de chave-valor. Você precisará criar um KVM com a API antes de acessá-lo com a política KeyValueMapOperations.

Como especificar e recuperar nomes de chaves

Com os elementos <Parameter> e <Value>, é possível especificar um valor literal (com o valor entre as tags de abertura e fechamento) ou usar o atributo ref para especificar o nome de uma variável com o valor que precisa ser usado no ambiente de execução.

O elemento <Parameter> merece uma menção especial porque determina o nome da chave criada e da que você quer recuperar ou excluir. Veja a seguir dois exemplos. O primeiro especifica um nome de chave literalmente, e o segundo especifica um nome de chave usando uma variável. Vamos supor que os itens a seguir sejam usados para criar chaves em um KVM:

<Parameter>KEY_NAME_LITERAL</Parameter>
<Parameter ref="key.name.variable"/>

Na primeira instância, o valor literal de KEY_NAME_LITERAL é armazenado no KVM como o nome da chave. Na segunda instância, qualquer valor em key.name.variable se torna o nome da chave no KVM. Por exemplo, se key.name.variable continha o valor foo, a chave será chamada foo.

Para recuperar a chave e um valor de chave com uma operação GET (ou remover com uma operação DELETE), o valor do elemento <Parameter> precisa corresponder ao nome da chave no KVM. Por exemplo, se o nome da chave no KVM for my_key, será possível especificar o valor literal com <Parameter>my_key</Parameter> ou especificar uma variável que contenha o valor exato mny_key, da seguinte maneira: <Parameter ref="variable.containing.foo"/>.

Observação: o nome ratelimit é reservado. Para saber mais, consulte Política de cotas: NullPointerException.

Temas relacionados

Consulte os tópicos a seguir para mais informações sobre KVMs:

• Como usar mapas de chave-valor
• API de mapas de chave-valor da organização
• API de mapas de chave-valor do ambiente
• API de mapas de chave-valor do proxy de API