Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Cosa
Fornisce l'accesso basato su criteri a un archivio KVM (Key Value Map) disponibile in Apigee Edge. Le coppie chiave/valore possono essere archiviate, recuperate ed eliminate dalle mappe esistenti denominate configurando i criteri KeyValueMapOperations che specificano le operazioni PUT, GET o DELETE. (Almeno una di queste operazioni deve essere eseguita dal criterio).
Video
Guarda i video che seguono per scoprire di più sui KVM.
Video | Descrizione |
---|---|
Perché le mappe chiave-valore? | Scopri perché sono necessari i KVM e come funzionano. |
Crea un KVM utilizzando l'interfaccia utente e recupera il KVM in fase di runtime | Crea un KVM, recupera il suo valore utilizzando un criterio KVM e inserisci il valore nella richiesta API utilizzando variabili di flusso. |
Crea e aggiorna un KVM nel runtime API | Crea un KVM durante il runtime API utilizzando un criterio KVM. |
Memorizza nella cache il KVM per aumentare le prestazioni | Migliora le prestazioni del criterio KVM memorizzando nella cache i dati. |
Archivia KVM criptato | Archivia le informazioni sensibili su KVM in un formato criptato e recupera il valore in fase di runtime utilizzando il criterio KVM e le variabili private. |
Gestione dell'accesso utilizzando l'ambito KVM | Limita KVM a organizzazione, ambiente, proxy API o proxy API utilizzando l'attributo ambito dei criteri KVM. |
Elimina le voci KVM al runtime delle API | Elimina le voci KVM durante il runtime API utilizzando l'operazione DELETE del criterio KVM. |
Samples
PUT KVM con un valore letterale
Quando viene eseguito il criterio seguente, viene creato un KVM criptato denominato FooKVM
, quindi crea una chiave denominata FooKey_1
con due valori impostati con stringhe letterali foo
e bar
(non impostate con valori estratti dalle variabili). Quando GET
la chiave nell'esempio successivo, specifichi un numero di indice per recuperare il valore desiderato.
<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>
Nota che l'ambito è "ambiente". Ciò significa che puoi vedere il KVM nell'interfaccia utente di gestione in API > Configurazione ambiente > Mappe chiave-valore. I KVM mostrati in questa pagina hanno tutti l'ambito dell'ambiente selezionato.
Recupera KVM da un valore letterale
Questo criterio esamina la mappa FooKVM
dell'esempio precedente, recupera il secondo valore (index="2") dalla chiave FooKey_1
e lo memorizza in una variabile denominata 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 con una variabile
Un semplice esempio di utile mappa chiave-valore è un servizio di abbreviazione degli URL. La mappa chiave-valore può essere configurata in modo da archiviare gli URL abbreviati insieme agli URL completi corrispondenti.
Questo esempio di criterio crea una mappa chiave-valore. Il criterio inserisce una chiave con due valori associati in una mappa chiave/valore denominata "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>
La chiave in questo esempio, urlencoding.requesturl.hashed
, è un esempio di variabile personalizzata. L'URL della richiesta sottoposta ad hashing viene generato dal codice (ad esempio JavaScript o Java) e poi archiviato in questa variabile, dove il criterio KeyValueMapOperations può accedervi.
Per ogni chiave, requesturl.hashed
, vengono memorizzati due valori:
- I contenuti della variabile personalizzata denominata
urlencoding.longurl.encoded
- Contenuti della variabile predefinita
request.queryparam.url
Ad esempio, quando il criterio viene eseguito in fase di runtime, i valori delle variabili possono essere i seguenti:
urlencoding.requesturl.hashed: ed24e12820f2f900ae383b7cc4f2b31c402db1be
urlencoding.longurl.encoded: http://tinyurl.com/38lwmlr
request.queryparam.url: http://apigee.com
La seguente mappa e voce chiave/valore verranno generate nell'archivio chiave/valore di Edge e saranno limitate all'ambito del proxy API a cui è associato il criterio:
{ "entry" :[ { "name" : "ed24e12820f2f900ae383b7cc4f2b31c402db1be", "value" : "http://tinyurl.com/38lwmlr,http://apigee.com" } ], "name" : "urlMapper" }
La voce verrà conservata finché non verrà eliminata. Le voci di archivio chiave/valore sono distribuite tra le istanze di Edge che eseguono il cloud.
Recupera KVM da una variabile
Un semplice esempio di utile mappa chiave-valore è un servizio di "accorciamento" di URL. La mappa chiave-valore può essere configurata in modo da archiviare gli URL abbreviati insieme agli URL completi corrispondenti.
Per recuperare il valore della voce della mappa chiave/valore, ad esempio quello riportato nella scheda KeyValueMapOperations PUT, configura un criterio per GET alla mappa valori chiave:
<KeyValueMapOperations name="getUrl" mapIdentifier="urlMapper"> <Scope>apiproxy</Scope> <Get assignTo="urlencoding.shorturl" index='1'> <Key> <Parameter ref="urlencoding.requesturl.hashed"/> </Key> </Get> </KeyValueMapOperations>
Quando questo criterio viene eseguito, se il valore della variabile urlencoding.requesturl.hashed
è ed24e12820f2f900ae383b7cc4f2b31c402db1be
, la variabile personalizzata denominata urlencoding.shorturl
verrà impostata con il valore http://tinyurl.com/38lwmlr
.
Ora che i dati sono stati recuperati, altri criteri e codice possono accedervi estraendo il valore da queste variabili.
GET valore criptato da KVM
Se una mappa chiave-valore è criptata, recupera i valori utilizzando il prefisso "private.
" nel valore dell'attributo assignTo
. In questo esempio, la variabile private.encryptedVar
contiene il valore decriptato della chiave foo
della mappa chiavi-valore. Per informazioni sulla creazione di mappe chiave-valore criptate, consulta gli argomenti relativi alla "creazione" dell'API di gestione delle mappe chiave/valori.
<KeyValueMapOperations name="getEncrypted" mapIdentifier="encrypted_map"> <Scope>apiproxy</Scope> <Get assignTo="private.encryptedVar" index='1'> <Key> <Parameter>foo</Parameter> </Key> </Get> </KeyValueMapOperations>
Ora che i dati sono stati recuperati, altri criteri e codice possono accedervi estraendo il valore da quella variabile.
Riferimento elemento
Il riferimento agli elementi descrive gli elementi e gli attributi del criterio 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>
Attributi <KeyValueMapOperations>
L'esempio seguente mostra gli attributi nel tag <KeyValueMapOperations>
:
<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="Key-Value-Map-Operations-1" mapIdentifier="map_name">
Nella tabella seguente vengono descritti gli attributi specifici del tag <KeyValueMapOperations>
:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
mapIdentifier |
Specifica un identificatore da utilizzare per accedere a una mappa creata da questo criterio o nell'interfaccia utente di gestione. Il nome del KVM è sensibile alle maiuscole con Apigee Edge per il cloud pubblico.
Ad esempio, Se escludi questo attributo, viene utilizzato un KVM denominato All'interno di un ambito organizzazione/ambiente/apiproxy, puoi utilizzare l'attributo |
N/A | Facoltativo |
La tabella seguente descrive gli attributi comuni a tutti gli elementi principali dei criteri:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
name |
Il nome interno della norma. Il valore dell'attributo Facoltativamente, utilizza l'elemento |
N/A | Obbligatorie |
continueOnError |
Impostalo su Imposta su |
false | Facoltativo |
enabled |
Imposta il criterio su Impostala su |
true | Facoltativo |
async |
Questo attributo è obsoleto. |
false | Deprecata |
Elemento <DisplayName>
Utilizzalo in aggiunta all'attributo name
per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.
<DisplayName>Policy Display Name</DisplayName>
Predefinito |
N/A Se ometti questo elemento, viene utilizzato il valore dell'attributo |
---|---|
Presenza | Facoltativo |
Tipo | Stringa |
Elemento <Delete>
Elimina la coppia chiave/valore specificata. Devi utilizzare almeno un elemento <Get>
,
<Put>
o <Delete>
.
Assicurati di specificare il nome del KVM con l'attributo mapIdentifier
sull'elemento padre. Ad esempio:
<Delete> <Key> <Parameter>key_name_literal</Parameter> </Key> </Delete>
Predefinito | N/A |
---|---|
Presenza | Obbligatorio se non sono presenti <Get> o <Put> . |
Tipo | N/A |
Elemento <Entry>
Valori seed per le mappe chiave-valore, che vengono inseriti nella mappa chiave-valore al momento dell'inizializzazione.
Per Edge per il cloud pubblico, la dimensione della chiave è limitata a 2 kB. Ad esempio:
<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>
Predefinito | N/A |
---|---|
Presenza | Facoltativo |
Tipo | N/A |
Elemento <EsclusivaCache>
Deprecato. Usa l'elemento <Scope>
.
Elemento <ExpiryTimeInSecs>
Specifica la durata in secondi dopo la quale Edge aggiorna il valore memorizzato nella cache dal KVM specificato.
Se il valore è 0 o -1 o se si esclude questo elemento, viene utilizzato il valore predefinito di 300 secondi. Ad esempio:
<ExpiryTimeInSecs>600</ExpiryTimeInSecs>
Predefinito | 300 (5 minuti) |
---|---|
Presenza | Facoltativo |
Tipo | Numero intero |
Un KVM è un meccanismo di persistenza a lungo termine che archivia chiavi e valori in un database NoSQL. Per questo motivo, la lettura da un KVM in fase di runtime può potenzialmente rallentare le prestazioni del proxy. Per migliorare le prestazioni, Edge dispone di un meccanismo integrato per la memorizzazione nella cache di chiavi/valori KVM in memoria durante il runtime. Questo criterio operazioni KVM legge sempre dalla cache per le operazioni GET.
L'elemento <ExpiryTimeInSecs>
consente di controllare per quanto tempo le chiavi/valore utilizzate nel criterio vengono archiviate nella cache prima di essere aggiornate di nuovo dal KVM. Tuttavia, esistono alcune differenze tra il modo in cui le operazioni GET e PUT influiscono sulla scadenza della cache.
GET: la prima volta che viene eseguita un'operazione KVM GET, le chiavi/valori richiesti dal KVM (il cui nome è specificato nell'attributo radice mapIdentifier
del criterio) vengono caricate nella cache, dove rimangono per le successive operazioni GET finché non si verifica uno dei seguenti casi:
- Il numero di secondi specificato in
<ExpiryTimeInSecs>
scade.
o - Un'operazione PUT in un criterio KVM sovrascrive i valori esistenti (come spiegato di seguito).
PUT: un'operazione PUT scrive chiavi/valori sul KVM specificato. Se PUT scrive in una chiave già presente nella cache, la cache viene immediatamente aggiornata e ora contiene il nuovo valore per il numero di secondi specificato nell'elemento <ExpiryTimeInSecs>
del criterio.
Esempio - Memorizzazione nella cache di un KVM
- Un'operazione GET recupera il valore di "rating", che aggiunge il valore "10" alla cache. Il valore
<ExpiryTimeInSecs>
del criterio è 60. - 30 secondi dopo, il criterio GET viene eseguito di nuovo e recupera "10" dalla cache.
- 5 secondi dopo, un criterio PUT aggiorna il valore di "rating" su "8" e il
<ExpiryTimeInSecs>
sul criterio PUT è 20. La cache viene immediatamente aggiornata con il nuovo valore, che ora è impostato per rimanere nella cache per 20 secondi. (Se il PUT non fosse stato eseguito, la cache originariamente compilata dal primo GET esisterebbe ancora per altri 30 secondi, rimasti dai 60 secondi originali.) - 15 secondi dopo, un altro GET viene eseguito e recupera il valore "8".
Elemento <Get>
Recupera il valore della chiave specificata. Devi utilizzare almeno un elemento <Get>
,
<Put>
o <Delete>
.
Assicurati di specificare il nome del KVM con l'attributo mapIdentifier
sull'elemento padre.
È possibile includere più blocchi Get
nel criterio per recuperare più elementi da un KVM.
Predefinito | N/A |
---|---|
Presenza | Obbligatorio se non sono presenti <Put> o <Delete> . |
Tipo | N/A |
Ricevere un singolo articolo da un KVM
<Get assignTo="myvar" index="1"> <Key> <Parameter>key_name_literal</Parameter> </Key> </Get>
Recupero di più elementi da un KVM
Nell'esempio seguente, ipotizza un KVM con le chiavi e i valori seguenti. Oltre a una lista dei film più popolari di tutti i tempi, KVM include anche il nome del regista di tutti i principali film.
Chiave | Valore |
---|---|
top_movies | La sposa principessa,Il padrino,Il cittadino Kane |
Il cittadino Kane | Orson Welles |
Sposa principessa | Rob Reiner |
Il padrino | Francis Ford Coppola |
Ecco una configurazione dei criteri KVM che possiamo utilizzare per recuperare il film più popolare attuale e il nome del suo regista:
<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 viene chiamato il proxy API, Edge crea le seguenti variabili che puoi utilizzare nel flusso proxy API:
top.movie.pick=Princess Bride
movie.director=Rob Reiner
Attributi
La tabella seguente descrive gli attributi dell'elemento <Get>
:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
assignTo |
La variabile a cui deve essere assegnato il valore recuperato. Se la mappa chiave-valore è criptata, inizia il nome assignTo con
" <Get assignTo="private.myvar"> Il criterio genera un errore se cerchi di recuperare una mappa chiave-valore criptata senza utilizzare il prefisso. Il prefisso, obbligatorio per motivi di sicurezza di base durante il debug, nasconde i valori criptati dalle sessioni di traccia e debug del proxy API. Per informazioni sulla creazione di mappe chiave-valore criptate, consulta gli argomenti relativi alla creazione dell'API di gestione delle mappe chiave/valore e alla creazione e modifica di mappe chiave-valore di ambiente. |
N/A | Obbligatorie |
index |
Il numero di indice (in un indice a base 1) dell'elemento da recuperare da una chiave a più valori.
Ad esempio, se specifichi Per un esempio, vedi la scheda "Recupera valore criptato da KVM" in Esempi. |
N/A | Facoltativo |
Elemento <InitialEntries>
Valori iniziali per le mappe chiave-valore, che vengono inseriti nella mappa chiave-valore al momento dell'inizializzazione.
Assicurati di specificare il nome del KVM con l'attributo mapIdentifier
sull'elemento padre, ad esempio:
<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 utilizzi questo elemento, quando salvi il criterio nell'interfaccia utente di gestione su una versione di cui è stato eseguito il deployment del proxy o esegui il deployment del bundle proxy API contenente il criterio con questo elemento, le chiavi vengono create automaticamente nel KVM (non criptate). Se i valori nel criterio sono diversi da quelli nel KVM, i valori nel KVM vengono sovrascritti al momento del deployment del proxy. Eventuali nuove chiavi/valori vengono aggiunte al KVM esistente insieme a quelle esistenti.
Le chiavi e i valori inseriti da questo elemento devono essere valori letterali. Ad esempio, <Parameter
ref="request.queryparam.key">
non è supportato all'interno di questo elemento.
La dimensione della chiave è limitata a 2 kB per Edge per il cloud pubblico e Edge per il cloud privato. Il valore KVM è limitato a 2 kB.
Per creare un KVM criptato, utilizza l'API di gestione delle mappe di valori/chiave.
Predefinito | N/A |
---|---|
Presenza | Facoltativo |
Tipo | N/A |
Elemento <Key>
Specifica la chiave in una voce della mappa chiave/valore. Una chiave può essere composita, il che significa che è possibile aggiungere più di un parametro per creare la chiave. Ad esempio, userID
e
role
potrebbero essere combinati per creare un key
. Ad esempio:
<Key> <Parameter>key_name_literal</Parameter> </Key>
Assicurati di visualizzare l'elemento <Parameter> per le specifiche su come impostare il nome della chiave.
Con Edge per il cloud pubblico, la dimensione della chiave è limitata a 2 kB. Per saperne di più, consulta le Differenze tra l'API Edge for Public Cloud e l'API Private Cloud.
Predefinito | N/A |
---|---|
Presenza | Facoltativo |
Tipo | N/A |
Elemento <Parameter>
Specifica la chiave in una coppia chiave-valore. Questo elemento specifica il nome durante la creazione, l'inserimento, il recupero o l'eliminazione della coppia chiave-valore.
Puoi specificare il nome utilizzando:
-
Una stringa letterale
<Key> <Parameter>literal</Parameter> </Key>
-
Una variabile da recuperare in fase di esecuzione utilizzando l'attributo
ref
<Key> <Parameter ref="variable_name"/> </Key>
-
Una combinazione di valori letterali e riferimenti a variabili
<Key> <Parameter>targeturl</Parameter> <Parameter ref="apiproxy.name"/> <Parameter>weight</Parameter> </Key>
Quando l'elemento Key include più elementi Parameter, la stringa chiave effettiva è la
concatenazione dei valori di ciascun parametro, uniti da un doppio trattino basso. Ad esempio, nell'esempio precedente, se la variabile apiproxy.name
ha il valore "abc1", la chiave effettiva sarà targeturl__abc1__weight
.
A prescindere dal fatto che tu stia ricevendo, aggiornando o eliminando una voce di chiave/valore, il nome della chiave deve corrispondere a quello della chiave nella mappa chiave-valore. Consulta le linee guida per specificare e recuperare i nomi delle chiavi.
Predefinito | N/A |
---|---|
Presenza | Obbligatorie |
Tipo | Stringa |
Attributi
La tabella seguente descrive gli attributi dell'elemento <Parameter>
:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
rif | Specifica il nome di una variabile il cui valore contiene il nome esatto della chiave che vuoi creare, ottenere o eliminare. | N/A | Obbligatorio se non viene fornito alcun valore letterale tra il tag di apertura e quello di chiusura. Vietato se viene fornito un valore letterale. |
Elemento <Put>
Scrive una coppia chiave/valore in una mappa chiave-valore, indipendentemente dal fatto che la mappa sia criptata o non criptata. Se la mappa chiave-valore specificata nell'attributo mapIdentifier
dell'elemento
principale non esiste, la mappa viene creata automaticamente (in quanto non criptata). Se la mappa chiave-valore esiste già, le coppie chiave-valore vengono aggiunte.
Per creare una mappa chiave-valore criptata, utilizza l'API di gestione delle mappe chiave/valore oppure consulta Creazione e modifica di mappe chiave-valore di ambiente per creare KVM con ambito di ambiente criptati nell'interfaccia utente.
<Put override="false"> <Key> <Parameter ref="mykeyvar"/> </Key> <Value ref="myvalvar1"/> </Put>
Predefinito | N/A |
---|---|
Presenza | Obbligatorio se non sono presenti <Get> o <Delete> . |
Tipo | N/A |
Attributi
La tabella seguente descrive gli attributi dell'elemento <Put>
:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
override |
Se impostato su |
false |
Facoltativo |
Elemento <Scope>
Definisce i limiti di accessibilità per le mappe chiave-valore. L'ambito predefinito è
environment
, il che significa che, per impostazione predefinita, le voci delle mappe sono condivise da tutti i proxy API
in esecuzione in un ambiente (ad esempio, test o produzione). Se imposti l'ambito su apiproxy
, le voci nella mappa chiave-valore sono accessibili solo al proxy API che scrive i valori nella mappa.
Tieni presente che quando accedi a una mappa o voce di una mappa, devi specificare lo stesso valore di ambito che hai utilizzato al momento della creazione della mappa. Ad esempio, se la mappa è stata creata con un ambito apiproxy
, devi utilizzare l'ambito apiproxy
quando hai recuperato i valori, apporti modifiche o elimini voci.
<Scope>environment</Scope>
Predefinito | environment |
---|---|
Presenza | Facoltativo |
Tipo | Stringa |
Valori validi: |
|
Elemento <Value>
Specifica il valore di una chiave. Puoi specificare il valore come stringa letterale o, utilizzando
l'attributo ref
, come variabile da recuperare in fase di esecuzione:
<!-- Specify a literal value --> <Value>literal<Value>
oppure:
<!-- Specify the name of variable value to be populated at run time. --> <Value ref="variable_name"/>
Puoi anche includere più elementi <Value>
per specificare un valore composto da più parti. I valori vengono combinati in fase di esecuzione.
Nell'esempio seguente, vengono aggiunte due chiavi al KVM:
- Chiave
k1
con valoriv1,v2
- Chiave
k2
con valoriv3,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>
Nell'esempio seguente, una chiave viene creata con due valori. Supponiamo che il nome dell'organizzazione sia foo_org
, che il nome del proxy API sia bar
e che l'ambiente sia test
:
- Chiave
foo_org
con valoribar,test
<Put> <Key> <Parameter ref="organization.name"/> </Key> <Value ref="apiproxy.name"/> <Value ref="environment.name"/> </Put>
Predefinito | N/A |
---|---|
Presenza | Obbligatorie |
Tipo | Stringa |
Attributi
La tabella seguente descrive gli attributi dell'elemento <Value>
:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
rif | Specifica il nome di una variabile il cui valore contiene i valori chiave che vuoi impostare. | N/A | Obbligatorio se non viene fornito alcun valore letterale tra il tag di apertura e quello di chiusura. Vietato se viene fornito un valore letterale. |
Messaggi di errore
Gli errori restituiti dai criteri perimetrali seguono un formato coerente, come descritto in Riferimento ai codici di errore.
Questa sezione descrive i codici e i messaggi di errore restituiti e le variabili di errore impostate da Edge quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.
Errori di runtime
Questi errori possono verificarsi quando il criterio viene eseguito.
Codice di errore | Stato HTTP | Causa | Correggi |
---|---|---|---|
steps.keyvaluemapoperations.SetVariableFailed |
500 |
Questo errore si verifica se tenti di recuperare un valore da una mappa chiave-valore criptata e imposti il valore su una variabile il cui nome non ha il prefisso |
build |
steps.keyvaluemapoperations.UnsupportedOperationException |
500 |
Questo errore si verifica se l'attributo |
build |
Errori di deployment
Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.
Nome errore | Causa | Correggi |
---|---|---|
InvalidIndex |
Se l'attributo index specificato nell'elemento <Get> del criterio Operazioni mappa chiave-valore è
zero o un numero negativo, il deployment del proxy API non va a buon fine. L'indice inizia da 1 , pertanto un indice pari a zero o un numero intero negativo viene considerato non valido.
|
build |
KeyIsMissing |
Questo errore si verifica se l'elemento <Key> è completamente mancante o se manca
l'elemento <Parameter> all'interno dell'elemento <Key> sotto <Entry> dell'elemento <InitialEntries>
del criterio Key Value Map Operations.
|
build |
ValueIsMissing |
Questo errore si verifica se l'elemento <Value> non è presente sotto l'elemento <Entry> dell'elemento <InitialEntries> del criterio Key Value Map Operations. |
build |
Schemi
Note sull'utilizzo
Per una panoramica delle mappe chiave-valore, consulta la sezione Utilizzo delle mappe chiave-valore.
Un archivio di mappe chiave-valore fornisce un meccanismo di persistenza leggero per i dati formattati come coppie chiave/valore. Puoi accedervi in fase di runtime tramite criteri o codice. Una mappa contiene dati arbitrari nel formato key=value
.
Ad esempio localhost=127.0.0.1
, zip_code=94110
o first_name=felix
. Nel primo esempio, localhost
è una chiave e 127.0.0.1
è un valore. Ogni coppia chiave/valore viene archiviata come voce in una mappa chiave-valore. Una mappa chiave-valore può memorizzare molte voci.
Ecco un esempio di utilizzo delle mappe chiave-valore. Supponi di dover archiviare un elenco di indirizzi IP associati a vari ambienti di backend. Potresti creare una mappa chiave-valore denominata ipAddresses
che contiene un elenco di coppie chiave/valore come voci. Ad esempio, questo JSON può rappresentare una mappa di questo tipo:
{ "entry" : [ { "name" : "Development", "value" : "65.87.18.18" }, { "name" : "Staging", "value" : "65.87.18.22" } ], "name" : "ipAddresses" }
Puoi utilizzare questa struttura per creare un archivio di indirizzi IP che potrebbero essere utilizzati dai criteri in fase di runtime per applicare l'inserimento in una lista consentita o una lista bloccata di IP, per selezionare dinamicamente un indirizzo di destinazione del backend e così via. In genere, il criterio KeyValueMapOperations viene utilizzato per archiviare o recuperare le informazioni di lunga durata che devono essere riutilizzate per più transazioni di richiesta/risposta.
Le mappe chiave/valore possono essere manipolate tramite il criterio KeyValueMapOperations o direttamente tramite l'API di gestione Apigee Edge. Per maggiori dettagli sull'API API per le mappe chiave/valore dell'organizzazione, consulta il riferimento dell'API di gestione. Puoi utilizzare l'API, ad esempio, per caricare set di dati di grandi dimensioni nell'archivio chiavi/valore o per creare script per gestire le voci della mappa chiave/valore. Dovrai creare una mappa chiave/valore con l'API prima di accedervi con il criterio KeyValueMapOperations.
Specificare e recuperare i nomi delle chiavi
Con gli elementi <Parameter>
e <Value>
, puoi specificare un valore letterale (dove il valore è compreso tra il tag di apertura e quello di chiusura) oppure utilizzare l'attributo ref
per specificare il nome di una variabile il cui valore deve essere utilizzato durante il runtime.
Un elemento Parameter merita una menzione speciale, perché determina il nome della chiave che viene creata, oltre al nome della chiave che si vuole recuperare o eliminare. Di seguito sono riportati due esempi. Il primo specifica un nome di chiave letteralmente, mentre il secondo specifica un nome di chiave utilizzando una variabile. Supponiamo che per creare chiavi in un KVM vengono utilizzati i seguenti comandi:
<Parameter>key_name_literal</Parameter> <Parameter ref="key.name.variable"/>
Nella prima istanza, il valore letterale di "key_name_literal" viene archiviato nel KVM come nome della chiave. Nella seconda istanza, qualsiasi valore presente in key.name.variable
diventa il nome della chiave nel KVM. Ad esempio, se key.name.variable
contiene il valore foo
, la chiave sarà denominata "foo".
Quando vuoi recuperare la chiave e un valore della chiave con un'operazione GET (o di eliminazione con un'operazione DELETE), l'impostazione <Parameter> deve corrispondere al nome della chiave nel KVM. Ad esempio, se il nome della chiave nel KVM è "foo", puoi specificare il valore letterale con <Parameter>foo</Parameter>
oppure specificare una variabile contenente il valore esatto "foo", in questo modo: <Parameter ref="variable.containing.foo"/>
.