Política KeyValueMapOperations

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

Ícone de operações do mapa de chave-valor na interface do Edge

O que

Oferece acesso com base em políticas a um armazenamento de mapa de chave-valor (KVM) disponível na 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.

Video Descrição
Por que usar os mapas de chave-valor? Saiba por que você precisa de KVMs e como eles funcionam.
Criar o KVM usando a IU e recuperá-lo no ambiente de execução Crie um KVM, recupere seu valor usando uma política de KVM e injete o valor na solicitação de API usando variáveis de fluxo.
Criar e atualizar um KVM no ambiente de execução da API Crie um KVM no ambiente de execução da API usando uma política de KVM.
Armazenar o KVM em cache para melhorar o desempenho Melhore o desempenho da política de KVM por meio do armazenamento em cache dos dados.
Armazenar o KVM criptografado Armazene informações confidenciais no KVM em um formato criptografado e recupere o valor no ambiente de execução usando a política de KVM e as variáveis particulares.
Gerenciar o acesso usando o escopo do KVM Restrinja o KVM à organização, ao ambiente, ao proxy de API ou à revisão de proxy de API usando o atributo de escopo da política de KVM.
Excluir entradas do KVM no ambiente de execução da API Exclua entradas do KVM no ambiente de execução da API usando a operação DELETE da política de KVM.

Amostras

PUT KVM com um literal

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

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

PUT KVM com uma variável

Um exemplo simples de um mapa de chave-valor útil é um serviço de encurtamento de URL. O mapa de chave-valor pode ser configurado para armazenar URLs encurtados com os URLs completos correspondentes.

Este exemplo de política cria um mapa de chave-valor. A política PUT insere uma chave com dois valores associados em um mapa de chave-valor 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

A entrada e o mapa de chave-valor a seguir seriam gerados no armazenamento de chave-valor do Edge e no escopo do proxy de 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 instâncias do Edge que estão executando a nuvem.

GET KVM de uma variável

Um exemplo simples de um mapa de chave-valor útil é um serviço de "encurtamento de URL". O mapa de chave-valor pode ser configurado para armazenar URLs encurtados com os URLs completos correspondentes.

Para recuperar o valor da entrada do mapa de chave-valor, como o abordado na guia PUT de KeyValueMapOperations, configure uma política para executar GET no mapa de chave-valor:

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

Valor criptografado GET do KVM

Se um mapa de chave-valor for criptografado, recupere valores usando o prefixo "private." no valor do atributo assignTo. Neste exemplo, a variável private.encryptedVar contém o valor descriptografado da chave foo do mapa de chave-valor. Para informações sobre como criar mapas de chave-valor criptografados, consulte os tópicos "criar" da API Key/Value Maps Management.

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


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

Atributo Descrição Padrão Presença
mapIdentifier

Especifica um identificador a ser usado ao acessar um mapa criado por essa política ou na IU de gerenciamento.

O nome da KVM diferencia maiúsculas de minúsculas com o Apigee Edge para nuvem pública. Por exemplo, foobar é diferente de FooBar.

Se você excluir esse atributo, será usado um KVM chamado kvmap.

Em um escopo de organização/ambiente/proxy de API, use o atributo mapIdentifier para especificar seu próprio nome de mapa.

N/A Opcional

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

Atributo Descrição Padrão Presença
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.

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.

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

Presença Opcional
Tipo String

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>
Padrão N/A
Presença Obrigatório se <Get> ou <Put> não estiver presente.
Tipo N/A

Elemento <Entry>

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

Para o 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>
Padrão N/A
Presença 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 qual o Edge atualiza o valor armazenado em cache da 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>
Padrão 300 (5 minutos)
Presença 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, o Edge tem um mecanismo integrado para armazenar chaves/valores de KVM em cache 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.

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

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.

Chave Valor
top_movies Princess Bride,The Godfather,Citizen Kane
Citizen Kane Orson Welles
Princess Bride Rob Reiner
The Godfather Francis Ford Coppola

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 as seguintes 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>:

Atributo Descrição Padrão Presença
assignTo

A variável a que o valor recuperado será atribuído.

Se o mapa de chave-valor estiver criptografado, inicie o nome "assignTo" com "private.". Por exemplo:

<Get assignTo="private.myvar">

A política gerará um erro se você tentar recuperar um mapa de chave-valor criptografado sem usar o prefixo. O prefixo, que é necessário para fins básicos de segurança durante a depuração, oculta os valores criptografados das sessões de trace e depuração do proxy de API.

Para informações sobre como criar mapas de chave-valor criptografados, consulte os tópicos "criar" da API Key/Value Maps management e Como criar e editar mapas de chave-valor de ambiente.

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 do KVM" em Amostras.

N/A Opcional

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 para o Edge para o estado privado. O valor da KVM é limitado a 2 KB.

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

Padrão N/A
Presença Opcional
Tipo N/A

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 para a API Public Cloud e a API Private Cloud para mais informações.

Padrão N/A
Presença Opcional
Tipo N/A

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.

Padrão N/A
Presença Obrigatório
Tipo String

Atributos

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

Atributo Descrição Padrão Presença
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. Proibido se um valor literal for fornecido.

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>
Padrão N/A
Presença Obrigatório se <Get> ou <Delete> não estiver presente.
Tipo N/A

Atributos

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

Atributo Descrição Padrão Presença
override

Se definido como true, o valor de uma chave será modificado.

false Opcional

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>
Padrão environment
Presença 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
Presença Obrigatório
Tipo String

Atributos

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

Atributo Descrição Padrão Presença
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

Os erros retornados das políticas do Edge 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.

Código de falha Status HTTP Causa Corrigir
steps.keyvaluemapoperations.SetVariableFailed 500

Este erro ocorre se você tentar recuperar um valor de um mapa de valores de chave criptografado e definir o valor como uma variável que não tenha o prefixo private. O prefixo, que é necessário para fins básicos de segurança durante a depuração, oculta os valores criptografados das sessões de trace e depuração do proxy de API.

steps.keyvaluemapoperations.UnsupportedOperationException 500

Esse erro ocorrerá se o atributo mapIdentifier estiver definido como string vazia na política de operações do mapa de valor de chave.

Erros de implantação

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

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

Esquemas

Observações sobre 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.

Veja um exemplo de como usar mapas de chave-valor. Suponha que você precise armazenar uma lista de endereços IP associados a vários ambientes de back-end. É 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 armazenamento de endereços IP que pode ser usado pelas políticas no momento da execução para aplicar a lista de permissões ou de bloqueio de IP, para 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 mapas de chave-valor podem ser manipulados pela política KeyValueMapOperations ou diretamente pela API de gerenciamento do Apigee Edge. 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