Política de KeyValueMapOperations

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

O quê

Fornece acesso baseado em políticas a um arquivo de mapa de valores-chave (KVM) disponível no Apigee. Os pares de chave/valor podem ser armazenados, obtidos e eliminados de mapas existentes com nome através da configuração de políticas KeyValueMapOperations que especificam operações PUT, GET ou DELETE, respetivamente. (Pelo menos uma destas operações tem de ser realizada pela política.)

Esta política é uma política extensível e a utilização desta política pode ter implicações de custo ou utilização, consoante a sua licença do Apigee. Para ver informações sobre os tipos de políticas e as implicações de utilização, consulte Tipos de políticas.

Nota: a partir do lançamento da versão 1.4.0 do Apigee Hybrid, o Apigee encripta todos os KVMs por predefinição. Use o atributo private. com todas as variáveis quando aceder a um KVM com o comando GET para ocultar as informações do KVM numa sessão de depuração. Se o atributo private. não for usado, o KVM continua encriptado. No entanto, as informações do KVM aparecem desencriptadas na sessão de depuração e não é gerada nenhuma exceção.

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

Amostras

PUT KVM com um literal

Quando a seguinte política é executada, cria um KVM encriptado denominado FooKVM e, em seguida, cria uma chave denominada FooKey_1 com dois valores definidos com strings literais foo e bar (não definidos com valores extraídos de variáveis). Quando GET a chave no exemplo seguinte, especifica um número de índice para obter 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>

Repare que o âmbito é environment. Isto significa que pode ver o KVM na IU de gestão em APIs > Configuração do ambiente > Mapas de chave-valor. As KVMs apresentadas nessa página estão todas no âmbito do ambiente selecionado.

GET KVM from a literal

Esta política analisa o mapa FooKVM do exemplo anterior, obtém o segundo valor (index="2") da chave FooKey_1 e armazena-o numa variável denominada 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>

Aceda a um KVM dinamicamente

Esta política usa o elemento <MapName> para fazer referência a um KVM dinamicamente com uma variável de fluxo. O elemento obtém o identificador KVM da variável de fluxo. Tenha em atenção que o atributo mapIdentifier é omitido. Não pode 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 é um serviço de encurtamento de URLs. O KVM pode ser configurado para armazenar URLs encurtados juntamente com os URLs completos correspondentes.

Este exemplo de política cria um KVM. A política usa o comando PUT para colocar uma chave com dois valores associados num KVM denominado 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>

A chave neste exemplo, urlencoding.requesturl.hashed, é um exemplo de uma variável personalizada. O URL do pedido com hash seria gerado por código (JavaScript ou Java, por exemplo) e, em seguida, armazenado nesta variável, onde a política KeyValueMapOperations pode aceder ao mesmo.

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

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

Por exemplo, quando a política é executada no tempo 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 seguintes seriam gerados no armazenamento de chaves/valores do Apigee e limitados ao proxy de API ao qual a política está anexada:

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

A entrada vai persistir até ser eliminada. As entradas de armazenamento de chave/valor são distribuídas por instâncias do Apigee que estão a executar a nuvem.

GET KVM from a variable

Um exemplo simples de um KVM útil é um serviço de redução de URLs. O KVM pode ser configurado para armazenar URLs encurtados juntamente com os URLs completos correspondentes.

Para obter o valor da entrada KVM, como o abordado no separador PUTKeyValueMapOperations, 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 esta política é executada, se o valor da variável urlencoding.requesturl.hashed for ed24e12820f2f900ae383b7cc4f2b31c402db1be, a variável personalizada denominada urlencoding.shorturl é definida com o valor http://tinyurl.com/38lwmlr.

Agora que os dados foram obtidos, outras políticas e código podem aceder aos mesmos extraindo o valor dessas variáveis.

GET value from KVM

Use o atributo private. com todas as variáveis quando aceder a um KVM com o comando GET para ocultar as informações do KVM numa sessão de depuração. Se o atributo private. não for usado, o KVM continua encriptado. No entanto, as informações do KVM aparecem desencriptadas na sessão de depuração e não é gerada nenhuma exceção.

Neste exemplo, a variável private.encryptedVar contém o valor descifrado 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 obtidos, outras políticas e código podem aceder aos mesmos 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 seguinte mostra os atributos do elemento <KeyValueMapOperations>:

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

A tabela seguinte descreve os atributos do elemento <KeyValueMapOperations>:

Nota: o atributo mapIdentifier especifica o nome do KVM com o qual quer interagir. Também pode especificar um KVM dinamicamente com o elemento <MapName>.

Atributo	Descrição	Predefinição	Presença
mapIdentifier	Especifica um identificador que indica à política a KVM à qual deve aceder. Se este identificador e <MapName> estiverem em falta, é usado um KVM denominado kvmap. Não pode usar este atributo se especificar o elemento <MapName>.	N/A	Opcional

A tabela seguinte descreve os atributos comuns a todos os elementos principais de políticas:

Atributo	Descrição	Predefinição	Presença
name	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres. Opcionalmente, use o elemento <DisplayName> para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.	N/A	Obrigatória
continueOnError	Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também: As regras de falhas são acionadas APENAS num estado de erro (acerca de continueOnError) Processar falhas no fluxo atual	falso	Opcional
enabled	Defina como true para aplicar a política. Defina como false para desativar a política. A política não é aplicada, mesmo que permaneça associada a um fluxo.	verdadeiro	Opcional
async	Este atributo foi descontinuado.	falso	Descontinuado

Elemento <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

Predefinição	N/A Se omitir este elemento, é usado o valor do atributo name da política.
Presença	Opcional
Tipo	String

Elementos secundários

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

Elemento <Delete>

Elimina o par de chave/valor especificado. Tem de usar, pelo menos, um dos seguintes elementos: <Get>, <Put> ou <Delete>.

Certifique-se de que especifica o nome do KVM com o atributo mapIdentifier no elemento raiz ou com o elemento <MapName>. Por exemplo:

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

Predefinição	N/A
Presença	Obrigatório se <Get> ou <Put> não estiverem presentes.
Tipo	N/A

Elemento <Entry>

Valores de seed para KVMs, que são preenchidos no KVM quando é inicializado. Para o Apigee, o tamanho da chave está limitado a 2 KB.

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>

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

Elemento <ExclusiveCache>

Descontinuado. Em alternativa, use o elemento <Scope>.

Elemento <ExpiryTimeInSecs>

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

Um valor de 0 ou -1, ou a exclusão deste elemento, significa que é usado o valor predefinido de 300 segundos. Por exemplo:

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

Predefinição	300 (5 minutos)
Presença	Opcional
Tipo	Número inteiro

Um KVM é um mecanismo de persistência a longo prazo que armazena chaves e valores numa base de dados NoSQL. Por este motivo, a leitura de um KVM em tempo de execução pode potencialmente abrandar o desempenho do proxy. Para melhorar o desempenho, o Apigee tem um mecanismo incorporado para colocar em cache chaves/valores de KVM na memória durante o tempo de execução. Esta política de operações KVM lê sempre a partir da cache para operações do GET.

O elemento <ExpiryTimeInSecs> permite-lhe controlar durante quanto tempo as chaves/valores usados na política são armazenados na cache antes de serem atualizados novamente a partir do KVM. No entanto, existem algumas diferenças entre a forma como as operações GET e PUT afetam a expiração da cache.

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

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

PUT - Uma operação PUT escreve chaves/valores no KVM especificado. Se o PUT escrever numa chave que já existe na cache, essa cache é atualizada imediatamente e passa a conter o novo valor durante o número de segundos especificado no elemento <ExpiryTimeInSecs> da política. No entanto, a utilização de PUT só atualiza a cache no nó de tempo de execução único que processa o pedido. Para atualizar a cache em cada nó de tempo de execução distribuído, use o elemento <ExpiryTimeInSecs> para especificar os intervalos de atualização de cada nó.

Exemplo: colocar em cache um KVM

1. Uma operação GET obtém o valor de "rating", que adiciona o valor "10" à cache. O <ExpiryTimeInSecs> na política é de 60.
2. 30 segundos depois, a política GET é executada novamente e obtém 10 da cache.
3. 5 segundos depois, uma política PUT atualiza o valor de rating para 8 e o <ExpiryTimeInSecs> na política PUT é 20. A cache é atualizada imediatamente com o novo valor, que agora está definido para permanecer na cache durante 20 segundos. (Se o evento PUT não tivesse ocorrido, a cache originalmente preenchida pelo primeiro evento GET continuaria a existir durante mais 30 segundos, que restaram dos 60 segundos originais.)
4. 15 segundos depois, outra GET é executada e obtém um valor de 8.

Notas

• Para um melhor desempenho, equilibre o tempo de expiração da cache com a quantidade de tráfego da API que espera. Com tráfego elevado, por exemplo, pode definir intervalos de expiração da cache mais longos para evitar atualizações frequentes da base de dados.
• Não é possível repor manualmente a cache do KVM. No entanto, pode criar uma política temporária que execute uma operação PUT única com um <ExpiryTimeInSecs> curto. Esta ação repõe a cache, que contém o valor que PUT, durante o número de segundos especificado.
• A atualização de um KVM com a IU ou a API do Apigee não repõe a cache do KVM.
• Pode usar várias operações na mesma política. Se o fizer, a política executa as operações por ordem. Se usar um PUT seguido de um GET na mesma política com a mesma chave, o PUT, quando escreve, repõe implicitamente a expiração da cache.

Elemento <Get>

Obtém o valor da chave especificada. Tem de usar, pelo menos, um dos seguintes elementos: <Get>, <Put> ou <Delete>.

O Apigee encripta todos os dados armazenados no KVM. Para ver detalhes, consulte o artigo Acerca das chaves de encriptação. Quando usa o <Get>, o Apigee desencripta os dados armazenados e atribui-os a uma variável no contexto da mensagem. O nome da variável é especificado através do atributo assignTo.

Certifique-se de que especifica o nome do KVM com o atributo mapIdentifier no elemento raiz ou com o elemento <MapName>.

Pode incluir vários blocos Get na política para obter vários itens de um KVM.

Nota: pode usar várias operações na mesma política. Se o fizer, a política executa as operações por ordem. Se usar um PUT seguido de um GET na mesma política com a mesma chave, o PUT, quando escreve, repõe implicitamente a expiração da cache. Consulte o elemento ExpiryTimeInSecs para mais informações.

Predefinição	N/A
Presença	Obrigatório se <Put> ou <Delete> não estiverem presentes.
Tipo	N/A

Atributos

A tabela seguinte descreve os atributos do elemento <Get>:

Atributo	Descrição	Predefinição	Presença
assignTo	A variável à qual o valor obtido deve ser atribuído.	N/A	Obrigatória
index	O número do índice (num índice baseado em 1) do item a obter de uma chave com vários valores. Por exemplo, especificar index=1 devolve o primeiro valor e atribui-o à variável assignTo. Se não for especificado nenhum valor de índice, todos os valores dessa entrada são atribuídos à variável como um java.util.List. Para ver um exemplo, consulte o separador Get Value from KVM em Exemplos.	N/A	Opcional

Receba um único item de um KVM

Com esta configuração do passo de exemplo, a política lê e desencripta o valor de uma única chave no KVM e atribui o valor desencriptado a uma variável denominada myvar.

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

Excluir dados obtidos de sessões de depuração

Em alguns casos, os dados armazenados no KVM são confidenciais. Para impedir que os dados obtidos apareçam numa sessão de depuração, use o prefixo private. no nome da variável especificado no atributo assignTo. Se não usar o prefixo private., os dados obtidos do KVM aparecem em texto não cifrado em qualquer sessão de depuração que criar.

Com esta configuração do passo de exemplo, a política lê e desencripta o valor associado a uma única chave no KVM e atribui esse valor a uma variável. A atribuição não é apresentada numa sessão de depuração.

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

Obtenha vários itens de um KVM

No exemplo seguinte, suponha que tem um KVM com as seguintes chaves e valores. Além de armazenar uma lista contínua dos filmes mais populares de sempre, o KVM armazena o nome do realizador de todos os filmes importantes.

Chave	Valor
top_movies	A Princesa Prometida,O Padrinho,O Estranho Mundo de Kane
O Desprezo	Orson Welles
A Princesa Prometida	Rob Reiner
O Padrinho	Francis Ford Coppola

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

Com esta configuração de exemplo, a política obtém o filme mais popular atual e o nome do respetivo realizador:

<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 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 de 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 obter um valor em movie.director.

Elemento <InitialEntries>

Valores de seed para KVMs, que são preenchidos no KVM quando é inicializado. Certifique-se de que especifica o nome do KVM com o atributo mapIdentifier no elemento raiz.

Nota: o elemento <InitialEntries> não é permitido se o elemento <MapName> for usado.

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>

Quando usa este elemento, quando guarda a política na IU do Apigee numa versão implementada do proxy de API ou implementa o pacote do proxy de API que contém a política com este 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 são substituídos quando o proxy de API é implementado. Todas as novas chaves/valores são adicionados ao KVM existente juntamente com as chaves/valores existentes.

As chaves e os valores preenchidos por este elemento têm de ser literais. Por exemplo, <Parameter ref="request.queryparam.key"> não é suportado neste elemento.

O tamanho da chave está limitado a 2 KB.

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

Elemento <Key>

Especifica a chave numa entrada KVM. Este elemento aparece como elemento secundário de <Get>, <Put> ou <Delete>, ou como elemento secundário do elemento <Entry> que é um elemento secundário de <InitialEntries>. Segue-se um exemplo de uma chave fixa:

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

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

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

Certifique-se de que consulta o elemento <Parameter> para ver detalhes sobre como definir o nome da chave.

O tamanho da chave está limitado a 2 KB.

Nota: o nome ratelimit está reservado. Para mais informações, consulte esta publicação da comunidade do Apigee.

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

Elemento <MapName>

O elemento <MapName> permite que a política identifique que KVM usar dinamicamente, no momento da execução. A capacidade de selecionar KVMs dinamicamente dá-lhe a flexibilidade de criar uma política KeyValueMapOperations que pode aceder a diferentes KVMs, consoante o 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. Na terceira linha, se a variável de fluxo for resolvida para um valor vazio, é usada a string literal.

Não especifique o atributo mapIdentifier se usar <MapName> na sua política. Consulte os atributos das políticas para ver mais informações.

Se o mapa não existir quando o proxy for implementado, o mapa não é criado e o Apigee gera um erro de tempo de execução quando a política é executada. Se a variável de fluxo for fornecida, o elemento <InitialEntries> não é permitido. Recebe um erro de validação durante a implementação.

<Parameter> elemento

Especifica um componente de uma chave num par de chave/valor. Este elemento especifica o nome quando cria, atualiza, obtém ou elimina o par chave/valor.

Pode especificar o nome através de:

• Uma string literal

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

• Uma variável a ser obtida no momento da execução, através do 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 eficaz é a concatenação dos valores de cada parâmetro, unidos com um duplo sublinhado. Por exemplo, no exemplo acima, se a variável apiproxy.name tiver o valor abc1, a chave efetiva é targeturl__abc1__weight.

Quer esteja a obter, atualizar ou eliminar uma entrada de chave/valor, o nome da chave tem de corresponder ao nome da chave no KVM. Consulte o artigo Especificar e obter nomes de chaves para ver diretrizes.

Predefinição	N/A
Presença	Obrigatória
Tipo	String

Atributos

A tabela seguinte descreve os atributos do elemento <Parameter>:

Atributo	Descrição	Predefinição	Presença
ref	Especifica o nome de uma variável cujo valor contém o nome exato da chave que quer criar, obter ou eliminar.	N/A	Obrigatório se não for indicado nenhum valor literal entre as etiquetas de abertura e fecho.

Elemento <Put>

Escreve um par de chave/valor num KVM. Se o KVM especificado no atributo mapIdentifier no elemento raiz não existir e se o elemento <MapName> não for usado, o mapa é criado automaticamente. Se o mapa de valores-chave já existir, a chave/valor são adicionados ao mesmo.

Para criar um KVM através da IU ou da API, consulte:

• Usar KVMs com a IU do Apigee para criar KVMs encriptados ao nível do ambiente na IU
• API Organization-scoped key value maps
• API de mapas de valores-chave com âmbito de ambiente
• API proxy-scoped key value maps API

Nota: pode usar várias operações na mesma política. Se o fizer, a política executa as operações por ordem. Se usar um PUT seguido de um GET na mesma política com a mesma chave, o PUT, quando escreve, repõe implicitamente a expiração da cache. Consulte o elemento ExpiryTimeInSecs para mais informações.

O tamanho da chave está limitado a 2 KB.

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

Predefinição	N/A
Presença	Obrigatório se <Get> ou <Delete> não estiverem presentes.
Tipo	N/A

Aviso: se a política usou o comando PUT para colocar um par chave/valor num KVM usando uma chave nula, a seguinte chave é criada automaticamente: __$$_EDGE_KVM_EMPTY_KEY_$$__

Esta situação ocorre, por exemplo, se estiver a preencher uma chave com uma referência de variável e a variável referenciada for nula. À medida que são tentados novos comandos PUT com chaves nulas, apenas essa chave é usada, pelo que os valores existentes para essa chave são potencialmente substituídos sempre que a política é executada.

Atributos

A tabela seguinte descreve os atributos do elemento <Put>:

Atributo	Descrição	Predefinição	Presença
substituir	Se estiver definido como true, substitui o valor de uma chave. <Put override="false"> escreve se e apenas se não existir uma entrada atualmente mantida na loja KVM para essa chave.	true	Opcional

Elemento <Scope>

Define o limite de acessibilidade para KVMs. O âmbito predefinido é environment, o que significa que, por predefinição, as entradas de mapas são partilhadas por todos os proxies de API executados num ambiente (por exemplo, teste ou produção). Se definir o âmbito como apiproxy, as entradas no KVM só são acessíveis pelo proxy da API que escreve os valores no mapa.

Tenha em atenção que, quando acede a um mapa ou a uma entrada de mapa, tem de especificar o mesmo valor de âmbito que usou quando o mapa foi criado. Por exemplo, se o mapa foi criado com um âmbito de apiproxy, tem de usar o âmbito apiproxy quando obtiver os respetivos valores, fizer alterações ou eliminar entradas.

<Scope>environment</Scope>

Predefinição	environment
Presença	Opcional
Tipo	String
Valores válidos	organization environment apiproxy policy (Revisão do proxy de API)

Se precisar de usar o mesmo KVM em vários proxies, considere adicionar a sua política de KVM a um SharedFlow e usar o SharedFlow nos proxies.

Elemento <Value>

Especifica o valor de uma chave. Pode especificar o valor como uma string literal ou, usando o atributo ref, como uma variável a ser obtida no momento da 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 pode incluir vários elementos <Value> para especificar um valor de várias partes. Os valores são combinados no momento da execução.

No exemplo seguinte, são adicionadas duas chaves 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 seguinte, é criada uma chave com dois valores. Vamos supor que o nome da organização é foo_org, o nome do proxy da API é bar e o ambiente é test:

• Chave foo_org com valores bar,test

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

Predefinição	N/A
Presença	Obrigatória
Tipo	String

Atributos

A tabela seguinte descreve os atributos do elemento <Value>:

Atributo	Descrição	Predefinição	Presença
ref	Especifica o nome de uma variável cujo valor contém os valores-chave que quer definir.	N/A	Obrigatório se não for indicado nenhum valor literal entre as etiquetas de abertura e fecho. Proibido se for indicado um valor literal.

Referência de erro

Esta secção descreve os códigos de falha e as mensagens de erro devolvidas, bem como as variáveis de falha definidas pelo Apigee quando esta política aciona um erro. Estas informações são importantes para saber se estiver a desenvolver regras de falhas para processar falhas. Para saber mais, consulte os artigos O que precisa de saber sobre os erros de políticas e Processar falhas.

Erros de tempo de execução

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

Sugestão: precisa de ajuda para resolver um erro? Clique em na coluna Corrigir para ver informações detalhadas de resolução de problemas.

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

Erros de implementação

Estes erros podem ocorrer quando implementa um proxy que contém esta política.

Sugestão: precisa de ajuda para resolver um erro? Clique em na coluna Corrigir para ver informações detalhadas de resolução de problemas.

Nome do erro	Causa	Corrigir
InvalidIndex	Se o atributo index especificado no elemento <Get> da política KeyValueMapOperations for zero ou um número negativo, a implementação do proxy de API falha. O índice começa em 1, pelo que um índice de zero ou um número inteiro negativo é considerado inválido.
KeyIsMissing	Este erro ocorre se o elemento <Key> estiver completamente em falta ou se o elemento <Parameter> estiver em falta no elemento <Key> abaixo do elemento <Entry> da política de <InitialEntries>.KeyValueMapOperations
ValueIsMissing	Este erro ocorre se o elemento <Value> estiver em falta abaixo do elemento <Entry> do elemento <InitialEntries> da política KeyValueMapOperations.

Esquemas

Exemplo: consulte os exemplos do nosso repositório do GitHub para ver os esquemas mais recentes.

Notas de utilização

Para uma vista geral dos KVMs, consulte o artigo Usar mapas de chaves-valores.

Através da IU do Apigee, pode definir KVMs apenas ao nível do ambiente, conforme descrito em Usar KVMs com a IU do Apigee. Através da API Apigee, pode definir KVMs ao nível da organização, do ambiente ou do proxy de API, conforme descrito nas secções seguintes:

• API Organization-scoped key value maps
• API de mapas de valores-chave com âmbito de ambiente
• API proxy-scoped key value maps API

Um armazenamento KVM oferece um mecanismo de persistência simples para dados formatados como pares de chave/valor. Pode aceder a estes elementos em tempo de execução através de políticas ou código. Um mapa contém quaisquer dados arbitrários no formato key=value.

Nota: o tamanho da chave está 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 num mapa de chave valor. Um KVM pode armazenar muitas entradas.

Por exemplo, suponhamos que precisa de armazenar uma lista de endereços IP associados a vários ambientes de back-end. Pode criar um KVM denominado ipAddresses que contenha uma lista de pares de chave/valor como entradas. Por exemplo, este JSON pode representar um mapa deste tipo:

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

Pode usar esta estrutura para criar um repositório de endereços IP que podem ser usados pelas políticas em tempo de execução para aplicar a lista de autorizações/proibições de IPs, selecionar dinamicamente um endereço de destino de back-end, etc. Normalmente, a política KeyValueMapOperations é usada para armazenar ou obter informações de longa duração que precisam de ser reutilizadas em várias transações de pedido/resposta.

Os KVMs podem ser manipulados através da política KeyValueMapOperations ou diretamente através da API Apigee. Pode usar a API para, por exemplo, carregar grandes conjuntos de dados para o armazenamento de valores-chave ou criar scripts para gerir entradas de mapas de valores-chave. Tem de criar um KVM com a API antes de aceder ao mesmo com a política KeyValueMapOperations.

Especificar e obter nomes de chaves

Com os elementos <Parameter> e <Value>, pode especificar um valor literal (em que o valor está entre as etiquetas de abertura e fecho) ou usar o atributo ref para especificar o nome de uma variável cujo valor deve ser usado no tempo de execução.

O elemento <Parameter> merece uma menção especial, porque determina o nome da chave que é criada, bem como o nome da chave que quer obter ou eliminar. Seguem-se dois exemplos. O primeiro especifica literalmente um nome da chave e o segundo especifica um nome da chave através de uma variável. Vamos assumir que são usados os seguintes elementos para criar chaves num KVM:

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

No primeiro caso, o valor literal de KEY_NAME_LITERAL é armazenado no KVM como o nome da chave. No segundo caso, qualquer valor que esteja em key.name.variable torna-se o nome da chave no KVM. Por exemplo, se o key.name.variable contivesse o valor foo, a chave teria o nome foo.

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

Nota: o nome ratelimit está reservado. Para mais informações, consulte o artigo Política de quotas: gera NullPointerException.

Tópicos relacionados

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

• Usar mapas de chave-valor
• API Organization-scoped key value maps
• API de mapas de valores-chave com âmbito de ambiente
• API proxy-scoped key value maps API