Política KeyValueMapOperations

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

O que

Dá acesso com base em políticas a um armazenamento de mapa de chave-valor (KVM, na sigla em inglês) disponível no Apigee Edge. 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. É preciso que pelo menos uma dessas operações seja executada pela política.

Vídeos

Assista aos vídeos a seguir para saber mais sobre KVMs.

Amostras

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

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

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

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

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

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

Referência de elemento

A referência de elemento descreve os elementos e atributos da política KeyValueMapOperations:

<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>variable_name</Parameter>
         </Key>
         <Value>value_1_literal</Value>
         <Value>value_2_literal</Value>
      </Entry>
   </InitialEntries>
   <Put override="false">
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value ref="variable_name"/>
   </Put>
   <Get assignTo="myvar" index="1">
      <Key>
         <Parameter ref="variable_name"/>
      </Key>
   </Get>
   <Delete>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
   </Delete>
</KeyValueMapOperations>

Atributos <KeyValueMapOperations>

O exemplo a seguir mostra os atributos na tag <KeyValueMapOperations>:

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

A tabela a seguir descreve os atributos específicos à tag <KeyValueMapOperations>:

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

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>

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 pai. Exemplo:

<Delete>
   <Key>
      <Parameter>key_name_literal</Parameter>
   </Key>
</Delete>

Elemento <Entry>

Valores de propagação para mapas de chave-valor, que são preenchidos no mapa quando ele é inicializado.

No Edge para nuvem pública, 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>

Elemento <ExclusiveCache>

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

Elemento <ExpiryTimeInSecs>

Especifica a duração em segundos após a qual o Edge atualiza seu valor em cache do KVM especificada.

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>

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 desempenho, o Edge tem um mecanismo integrado para armazenar em cache chaves/valores da 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 KVM GET é executada, as chaves/valores solicitadas do KVM (com nome especificado no atributo raiz mapIdentifier da política) são carregadas 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 (explicados a seguir).

PUT: uma operação PUT grava as chaves/valores no KVM especificado. Se o PUT gravar em uma chave que já exista no cache, esse cache será atualizado imediatamente e agora conterá o novo valor do número de segundos especificado no elemento <ExpiryTimeInSecs> da política.

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 "classificação" para "8" 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, como restante dos 60 segundos originais.
4. Quinze segundos depois, outro GET é executado e recupera um valor de "8".

Elemento <Get>

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

Certifique-se de especificar o nome do KVM com o atributo mapIdentifier no elemento pai.

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

Receber um único item de um KVM

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

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

Veja uma configuração de política do KVM que podemos usar para recuperar o filme mais conhecido 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, o Edge cria o seguinte variáveis que podem ser usadas no fluxo do proxy de API:

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

Atributos

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

<Get assignTo="private.myvar">

Elemento <InitialEntries>

Valores de propagação para mapas de chave-valor, que são preenchidos no mapa quando ele é inicializado. Especifique o nome do KVM com o atributo mapIdentifier no elemento pai. Por 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 de gerenciamento em uma versão implantada do proxy ou implanta o pacote de proxy de API que contém a política com esse elemento, as chaves são criadas automaticamente no KVM (não criptografado). Se os valores na política forem diferentes dos valores no KVM, os valores no KVM serão substituídos quando o proxy 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 para o Edge para a nuvem pública e Borda para a via privada. O valor da KVM é limitado a 2 KB.

Para criar uma KVM criptografada, use a API de gerenciamento de chave-valor do Maps.

Elemento <Key>

Especifica a chave em uma entrada do mapa de chave/valor. Uma chave pode ser composta, o que significa que mais de um parâmetro pode ser anexado para criá-la. Por exemplo, userID e role podem ser combinadas para criar uma key. Exemplo:

<Key>
    <Parameter>key_name_literal</Parameter>
</Key>

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

Com o Edge para nuvem pública, o tamanho da chave é limitado a 2 KB. Consulte Diferenças entre o Edge for Public Cloud API e a API Private Cloud para saber mais.

Elemento <Parameter>

Especifica a chave em um par de chave-valor. Esse elemento especifica o nome ao criar, colocar, 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. Por exemplo, no exemplo acima, se a variável apiproxy.name tiver o valor "abc1", a chave efetiva será targeturl__abc1__weight.

Se você estiver recebendo, atualizando ou excluindo uma entrada de chave-valor, o nome da chave precisará corresponder ao nome da chave no mapa de chave-valor. Consulte Como especificar e recuperar nomes de chaves para ver as diretrizes.

Atributos

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

Elemento <Put>

Grava um par de chave-valor em um mapa de chave-valor, seja o mapa de chave-valor criptografado ou não. Se o mapa de chave-valor especificado no atributo mapIdentifier do elemento pai não existir, o mapa será criado automaticamente (não criptografado). Se o mapa de chave-valor já existir, a chave/valor será adicionada a ele.

Para criar um mapa de chave-valor criptografado, use a API Key/Value Maps management ou consulte Como criar e editar mapas de chave-valor de ambiente para criar KVMs criptografados com escopo de ambiente na IU.

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

Atributos

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

Elemento <Scope>

Define o limite de acessibilidade para os mapas de chave-valor. 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 mapa de chave-valor poderão ser acessadas apenas 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>

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>

Atributos

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

Referência de erros

Os erros retornados pelas políticas de borda seguem um formato consistente, conforme descrito na Referência do código de erro.

Nesta seção, descrevemos os códigos e as mensagens de erro retornados, além das variáveis de falha definidas pelo Edge quando esta 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.

Erros de implantação

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

Esquemas

Notas de uso

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

Um armazenamento de mapa de chave-valor 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.

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 mapa de chave-valor pode armazenar muitas entradas.

Este é um exemplo de uso de mapas de chave-valor. Suponha que você precise armazenar uma lista de endereços IP associadas a vários back-ends e ambientes de teste. É possível criar um mapa de chave-valor 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"
}

É possível usar essa estrutura para criar um repositório de endereços IP que podem ser usados por políticas durante a execução para aplicar a lista de bloqueio ou a lista de permissões de IP para selecionar dinamicamente um destino de back-end endereço 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 mapas de chave-valor podem ser manipulados por meio da política KeyValueMapOperations ou diretamente pelo API Apigee Edge Management. Consulte a referência da API Management para ver detalhes sobre a API Organization Key/Value Maps. 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 mapa de chave/valor 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 ele determina o nome da chave que é criada e o nome da chave 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 é denominada "foo".

Quando você quer recuperar a chave e um valor de chave com uma operação GET (ou excluir com uma operação DELETE), a configuração <Parameter> precisa corresponder ao nome da chave no KVM. Por exemplo, se o nome da chave no KVM for "foo", você poderá especificar o valor literal com <Parameter>foo</Parameter> ou especificar uma variável que contenha o valor exato "foo", como: <Parameter ref="variable.containing.foo"/>.

Temas relacionados

• API Organization Key/Value Maps