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.
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 PUT
KeyValueMapOperations, 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>
:
Atributo | Descrição | Predefinição | Presença |
---|---|---|---|
mapIdentifier |
Especifica um identificador que indica à política a KVM à qual deve aceder. Se este identificador e |
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 Opcionalmente, use o elemento |
N/A | Obrigatória |
continueOnError |
Definido como Definido como |
falso | Opcional |
enabled |
Defina como Defina como |
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 |
---|---|
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
- Uma operação
GET
obtém o valor de "rating", que adiciona o valor "10" à cache. O<ExpiryTimeInSecs>
na política é de 60. - 30 segundos depois, a política
GET
é executada novamente e obtém10
da cache. - 5 segundos depois, uma política
PUT
atualiza o valor derating
para8
e o<ExpiryTimeInSecs>
na políticaPUT
é 20. A cache é atualizada imediatamente com o novo valor, que agora está definido para permanecer na cache durante 20 segundos. (Se o eventoPUT
não tivesse ocorrido, a cache originalmente preenchida pelo primeiro eventoGET
continuaria a existir durante mais 30 segundos, que restaram dos 60 segundos originais.) - 15 segundos depois, outra
GET
é executada e obtém um valor de8
.
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.
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 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.
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.
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
<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 |
Atributos
A tabela seguinte descreve os atributos do elemento <Put>
:
Atributo | Descrição | Predefinição | Presença |
---|---|---|---|
substituir |
Se estiver definido como
|
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 |
|
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 valoresv1,v2
- Chave
k2
com valoresv3,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 valoresbar,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
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.
Código de falha | Status HTTP | Causa | Corrigir |
---|---|---|---|
steps.keyvaluemapoperations.UnsupportedOperationException |
500 |
Esse erro ocorrerá se o atributo |
build |
Erros na implantação
Esses erros podem ocorrer quando você implanta um proxy que contém esta política.
Nome do erro | 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.
|
build |
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 .
|
build |
ValueIsMissing |
Esse erro ocorrerá se o elemento <Value> estiver ausente do elemento <Entry> do elemento <InitialEntries> da política KeyValueMapOperations . |
build |
Esquemas
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
.
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"/>
.
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