Questa pagina si applica a Apigee e Apigee ibrido.
Visualizza la documentazione di
Apigee Edge.
Cosa
Fornisce l'accesso basato su criteri a un archivio di mappe chiave-valore (KVM) disponibile in Apigee.
Le coppie chiave/valore possono essere archiviate, recuperate ed eliminate dalle mappe esistenti denominate configurando i criteri KeyValueMapOperations che specificano rispettivamente le operazioni PUT
, GET
o DELETE
. Almeno una di queste operazioni deve essere eseguita dal criterio.
Questo criterio è un criterio estendibile e il suo utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni per l'utilizzo, consulta la pagina Tipi di criteri.
Video:il seguente video offre un'introduzione generale alle KVM.
Esempi
PUT KVM con un valore letterale
Quando viene eseguito, il criterio seguente crea una KVM criptata denominata
FooKVM
, quindi crea una chiave denominata FooKey_1
con
due valori impostati con stringhe letterali foo
e bar
(non impostati 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>
Tieni presente che l'ambito è environment
. Ciò significa che puoi visualizzare il KVM nell'interfaccia utente di gestione in API > Configurazione dell'ambiente > Mappe chiave-valore. Tutte le KVM mostrate in quella pagina sono associate all'ambiente selezionato.
OTTIENI 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 archivia 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>
Accedi a una KVM in modo dinamico
Questo criterio utilizza l'elemento <MapName>
per fare riferimento a una KVM in modo dinamico con
una variabile di flusso. L'elemento ottiene l'identificatore KVM dalla variabile di flusso. Tieni presente che l'attributo
mapIdentifier
è omesso. Non puoi utilizzare <MapName>
con
l'attributo 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 con una variabile
Un semplice esempio di KVM utile è il servizio di abbreviazione di URL. La KVM potrebbe essere configurata per archiviare URL abbreviati insieme agli URL completi corrispondenti.
Questo esempio di criteri crea una KVM. Il criterio utilizza il comando PUT
per inserire una
chiave con due valori associati
in una KVM 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>
In questo esempio, la chiave urlencoding.requesturl.hashed
è un esempio di variabile personalizzata. L'URL della richiesta con hash viene generato da codice (ad esempio JavaScript o Java) e quindi archiviato in questa variabile, dove il criterio KeyValueMapOperations può accedervi.
Per ogni chiave, requesturl.hashed
, vengono archiviati due valori:
- I contenuti della variabile personalizzata denominata
urlencoding.longurl.encoded
- I 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
Nell'archivio chiave/valore di Apigee verrebbero generate le voci e le KVM seguenti, che saranno associate al proxy API a cui è associato il criterio:
{ "entry" :[ { "name" : "ed24e12820f2f900ae383b7cc4f2b31c402db1be", "value" : "http://tinyurl.com/38lwmlr,http://apigee.com" } ], "name" : "urlMapper" }
La voce verrà mantenuta fino a quando non verrà eliminata. Le voci di archivio chiave/valore sono distribuite tra le istanze di Apigee che eseguono il cloud.
Recupera KVM da una variabile
Un semplice esempio di KVM utile è un servizio di abbreviazione di URL. La KVM potrebbe essere configurata per archiviare URL abbreviati insieme agli URL completi corrispondenti.
Per recuperare il valore della voce KVM, ad esempio quello indicato nella scheda KeyValueMapOperations PUT
, configura un criterio per GET
la 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 viene eseguito questo criterio, 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.
Recupera valore da KVM
Utilizza l'attributo private.
con tutte le variabili quando accedi a una KVM con il
comando GET
per nascondere le informazioni KVM in una sessione di debug. Se l'attributo
private.
non viene utilizzato, la KVM è comunque criptata; tuttavia, le informazioni KVM
appariranno decriptate nella sessione di debug e non verranno generate eccezioni.
In questo esempio, la variabile private.encryptedVar
contiene il valore decriptato della chiave foo
della KVM.
<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.
<KeyValueMapOperations>
Fornisce l'accesso basato su criteri a una mappa chiave-valore (KVM).
Sintassi
<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>
Attributi <KeyValueMapOperations>
L'esempio seguente mostra gli attributi dell'elemento <KeyValueMapOperations>
:
<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="Key-Value-Map-Operations-1" mapIdentifier="map_name">
La seguente tabella descrive gli attributi dell'elemento
<KeyValueMapOperations>
:
Attributo | Descrizione | Predefinita | Presenza |
---|---|---|---|
mapIdentifier |
Specifica un identificatore che indica al criterio a quale KVM deve accedere. Se mancano entrambi questo identificatore e |
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 | Obbligatorio |
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 |
Elementi secondari
Questa sezione descrive gli elementi e gli attributi del criterio KeyValueMapOperations:
Elemento <Delete>
Elimina la coppia chiave/valore specificata. Devi utilizzare almeno uno dei seguenti valori: <Get>
,
<Put>
o <Delete>
.
Assicurati di specificare il nome della KVM con l'attributo mapIdentifier
nell'elemento principale o con l'elemento <MapName>
. Ad esempio:
<Delete> <Key> <Parameter>KEY_NAME_LITERAL</Parameter> </Key> </Delete>
Predefinita | N/A |
---|---|
Presenza | Obbligatorio se non sono presenti <Get> o <Put> . |
Tipo | N/A |
Elemento <Entry>
Valori seed per KVM, che vengono compilati nella KVM al momento dell'inizializzazione. Per Apigee, 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>
Predefinita | N/A |
---|---|
Presenza | Facoltativo |
Tipo | N/A |
Elemento <UniqueCache>
Ritirato. Usa invece l'elemento <Scope>
.
Elemento <ExpiryTimeInSecs>
Specifica la durata in secondi dopo la quale Apigee aggiorna il valore memorizzato nella cache dalla KVM specificata.
Un valore 0 o -1 oppure l'esclusione di questo elemento indica che viene utilizzato il valore predefinito di 300 secondi. Ad esempio:
<ExpiryTimeInSecs>600</ExpiryTimeInSecs>
Predefinita | 300 (5 minuti) |
---|---|
Presenza | Facoltativo |
Tipo | Integer |
Una KVM è un meccanismo di persistenza a lungo termine che archivia chiavi e valori in un database NoSQL.
Per questo motivo, la lettura da una KVM in fase di runtime può rallentare le prestazioni del proxy. Per migliorare le prestazioni, Apigee dispone di un meccanismo integrato per la memorizzazione nella cache di chiavi/valori KVM in memoria durante il runtime.
Questo criterio per le operazioni KVM legge sempre dalla cache per le operazioni GET
.
L'elemento <ExpiryTimeInSecs>
ti consente di controllare per quanto tempo le chiavi/valori utilizzati nel criterio vengono archiviate nella cache prima di essere aggiornate nuovamente dalla KVM. Tuttavia,
esistono alcune differenze nel modo in cui le operazioni GET
e PUT
influiscono sulla scadenza della cache.
GET
: la prima volta che viene eseguita un'operazione GET
KVM, le chiavi/valori richiesti dalla KVM (il cui nome è specificato nell'attributo mapIdentifier
principale del criterio o nell'elemento <MapName>
) vengono caricati nella cache, dove rimangono per le operazioni GET
successive finché non si verifica uno dei seguenti eventi:
- Scadenza del numero di secondi specificato in
<ExpiryTimeInSecs>
.
oppure - Un'operazione
PUT
in un criterio KVM sovrascrive i valori esistenti (come spiegato di seguito).
PUT
: un'operazione PUT
scrive chiavi/valori sulla KVM specificata. Se PUT
scrive in una chiave già esistente nella cache, questa viene aggiornata immediatamente e ora conserva
il nuovo valore per il numero di secondi specificato nell'elemento
<ExpiryTimeInSecs>
del criterio. L'uso di PUT
, però, aggiorna la cache solo
nel singolo nodo di runtime che gestisce la richiesta. Per aggiornare la cache in ogni nodo di runtime distribuito, utilizza l'elemento <ExpiryTimeInSecs>
per specificare gli intervalli di aggiornamento per ciascun nodo.
Esempio: memorizzazione nella cache di una KVM
- Un'operazione
GET
recupera il valore di "rating", che aggiunge il valore "10" alla cache. Il valore<ExpiryTimeInSecs>
nel criterio è 60. - 30 secondi dopo, il criterio
GET
viene eseguito di nuovo e recupera10
dalla cache. - 5 secondi dopo, un criterio
PUT
aggiorna il valore dirating
in10
, mentre il<ExpiryTimeInSecs>
nel criterioPUT
è 20. La cache viene aggiornata immediatamente con il nuovo valore, che ora è impostato in modo da rimanere nella cache per 20 secondi. (SePUT
non fosse successo, la cache originariamente popolata dal primoGET
esisterebbe ancora per altri 30 secondi, rimaste dai 60 secondi originali.) - 15 secondi dopo, un altro
GET
viene eseguito e recupera il valore8
.
Elemento <Get>
Recupera il valore per la chiave specificata. Devi utilizzare almeno uno dei seguenti valori: <Get>
,
<Put>
o <Delete>
.
Apigee cripta tutti i dati archiviati nella KVM. Per maggiori dettagli, consulta Informazioni sulle chiavi di crittografia. Quando utilizzi <Get>
, Apigee decripta i dati archiviati e li assegna a una variabile nel contesto del messaggio. Il nome della variabile viene specificato utilizzando
l'attributo assignTo
.
Assicurati di specificare il nome della KVM con l'attributo mapIdentifier
nell'elemento
principale o con l'elemento <MapName>
.
Puoi includere più blocchi Get
nel criterio per recuperare più elementi da una KVM.
Predefinita | N/A |
---|---|
Presenza | Obbligatorio se <Put> o <Delete> non sono
presenti. |
Tipo | N/A |
Attributi
Nella tabella seguente vengono descritti gli attributi dell'elemento <Get>:
Attributo | Descrizione | Predefinita | Presenza |
---|---|---|---|
assignTo |
La variabile a cui deve essere assegnato il valore recuperato. |
N/A | Obbligatorio |
index |
Il numero di indice (in un indice basato su 1) dell'elemento da recuperare da una chiave a più valori.
Ad esempio, se specifichi Per un esempio, consulta la scheda Ottieni un valore da KVM in Campioni. |
N/A | Facoltativo |
Recuperare un singolo articolo da una KVM
Con questa configurazione di passaggio di esempio, il criterio legge e decripta il valore di una singola chiave nella KVM e assegna il valore decriptato a una variabile denominata myvar
.
<Get assignTo="myvar" index="1"> <Key> <Parameter>key_name_literal</Parameter> </Key> </Get>
Esclusione dei dati recuperati dalle sessioni di debug
In alcuni casi, i dati archiviati nella KVM sono sensibili. Per impedire che i dati recuperati
vengano visualizzati in una
sessione di debug,
utilizza il prefisso private.
nel nome della variabile specificato nell'attributo
assignTo
. Se non utilizzi
il prefisso private.
, i dati recuperati dalla KVM verranno visualizzati
in chiaro, in ogni sessione di debug che crei.
Con questa configurazione di passaggio di esempio, il criterio legge e decripta il valore associato a una singola chiave nella KVM e assegna questo valore a una variabile. L'assegnazione non verrà visualizzata in una sessione di debug.
<Get assignTo="private.myvar" index="1"> <Key> <Parameter>key_name_literal</Parameter> </Key> </Get>
Recuperare più elementi da una KVM
Nell'esempio seguente, supponi una KVM con le chiavi e i valori seguenti. Oltre ad archiviare un elenco aggiornato dei film più popolari di tutti i tempi, il KVM memorizza il nome del regista di tutti i film principali.
Chiave | Valore |
---|---|
top_movies | Principessa sposa,Il padrino,Cittadino Kane |
Citizen Kane | Orson Welles |
Principessa sposa | Roberto Russo |
Il padrino | Francis Ford Coppola |
Noterai che il valore associato alla chiave top_movies
contiene più nomi di film, separati da virgole.
Con questa configurazione di esempio, il criterio recupera l'attuale film di punta e il nome del relativo 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, Apigee crea le seguenti variabili con i valori corrispondenti, che possono essere utilizzate in un secondo momento nel flusso del proxy API:
top.movie.pick=Princess Bride
movie.director=Rob Reiner
Il valore di top.movie.pick
è solo il primo elemento nell'elenco separato da virgole,
perché il primo elemento <Get>
utilizza un attributo index
pari a 1.
Il secondo elemento <Get>
utilizza il valore assegnato a
top.movie.pick
come chiave per recuperare un valore in movie.director
.
Elemento <InitialEntries>
Valori seed per KVM, che vengono compilati nella KVM al momento dell'inizializzazione.
Assicurati di specificare il nome della KVM con l'attributo mapIdentifier
nell'elemento principale.
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 nella UI di Apigee su una versione di cui è stato eseguito il deployment del proxy API o esegui il deployment del bundle proxy API contenente il criterio con questo elemento, le chiavi vengono create automaticamente nel KVM. Se i valori nel criterio sono diversi da quelli nella KVM, questi verranno sovrascritti quando viene eseguito il deployment del proxy API. Tutte le nuove chiavi/valori vengono aggiunti alla KVM esistente insieme alle chiavi/valori esistenti.
Le chiavi e i valori compilati da questo elemento devono essere valori letterali. Ad esempio, <Parameter
ref="request.queryparam.key">
non è supportato in questo elemento.
Le dimensioni della chiave sono limitate a 2 kB.
Predefinita | N/A |
---|---|
Presenza | Facoltativo |
Tipo | N/A |
Elemento <Key>
Specifica la chiave in una voce KVM. Questo elemento appare come elemento secondario di <Get>
,
<Put>
o <Delete>
, oppure
come elemento secondario di <Entry>
di uno di <InitialEntries>
.
Ecco un esempio di chiave fissa:
<Key> <Parameter>KEY_NAME_LITERAL</Parameter> </Key>
Una chiave può essere composita con elementi dinamici, il che significa che è possibile aggiungere più di un <Parameter>
per creare la chiave. Ad esempio, i contenuti delle
variabili userID
e role
potrebbero essere combinati per creare
una chiave dinamica. Di seguito è riportato un esempio di configurazione dei passaggi che specifica una chiave composita determinata dinamicamente:
<Key> <Parameter ref='userID'/> <Parameter ref='role'/> </Key>
Assicurati di vedere l'elemento <Parameter>
per le specifiche sull'impostazione del nome della chiave.
Le dimensioni della chiave sono limitate a 2 kB.
Predefinita | N/A |
---|---|
Presenza | Facoltativo |
Tipo | N/A |
Elemento <MapName>
L'elemento <MapName>
consente al criterio di identificare quale KVM utilizzare in modo dinamico in fase di runtime.
La possibilità di selezionare dinamicamente le KVM ti offre la flessibilità di progettare un singolo criterio KeyValueMapOperations
in grado di accedere a KVM diverse, a seconda del contesto in cui viene eseguito il criterio.
Alcuni esempi:
<!-- use one of the following forms --> <MapName>literal_string</MapName> <MapName ref="flow.variable"></MapName> <MapName ref="flow.variable">literal_string</MapName>
La prima riga specifica il nome della KVM come stringa letterale. La seconda riga prende il nome da una variabile di flusso. Nella terza riga, se la variabile di flusso viene risolta in un valore vuoto, viene utilizzata la stringa letterale.
Non specificare l'attributo mapIdentifier
se utilizzi
<MapName>
nelle norme. Per ulteriori informazioni, consulta gli attributi dei criteri.
Se la mappa non esiste quando viene eseguito il deployment del proxy, la mappa non verrà creata e Apigee genera un errore di runtime quando viene eseguito il criterio. Se viene fornita la variabile di flusso, l'elemento <InitialEntries>
non è consentito. Riceverai un errore di convalida
durante il deployment.
<Parameter>
elemento
Specifica un componente di una chiave in una coppia chiave/valore. Questo elemento specifica il nome durante la creazione, l'aggiornamento, 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 alle variabili
<Key> <Parameter>targeturl</Parameter> <Parameter ref="apiproxy.name"/> <Parameter>weight</Parameter> </Key>
Se 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
.
Che tu stia recuperando, aggiornando o eliminando una voce chiave/valore, il nome della chiave deve corrispondere al nome della chiave nella KVM. Per le linee guida, consulta Specifica e recupero dei nomi delle chiavi.
Predefinita | N/A |
---|---|
Presenza | Obbligatorio |
Tipo | String |
Attributi
Nella tabella seguente vengono descritti gli attributi dell'elemento <Parameter>
:
Attributo | Descrizione | Predefinita | Presenza |
---|---|---|---|
riferimento | 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 i tag di apertura e chiusura. |
Elemento <Put>
Scrive una coppia chiave/valore in una KVM. Se la KVM specificata nell'attributo mapIdentifier
dell'elemento
principale non esiste e se l'elemento <MapName>
non viene utilizzato, la mappa viene creata automaticamente. Se la mappa chiave-valore esiste già, la coppia chiave-valore viene aggiunta.
Per creare una KVM utilizzando la UI o l'API, consulta:
- Utilizzo delle KVM con la UI di Apigee per creare KVM criptate con ambito di ambiente nella UI
- API per le mappe chiave-valore con ambito a livello di organizzazione
- API per le mappe chiave-valore con ambito a livello di ambiente
- API per le mappe chiave-valore con ambito proxy con ambito API
<Put override="false"> <Key> <Parameter ref="mykeyvar"/> </Key> <Value ref="myvalvar1"/> </Put>
Predefinita | N/A |
---|---|
Presenza | Obbligatorio se <Get> o <Delete> non sono
presenti. |
Tipo | N/A |
Attributi
Nella tabella seguente vengono descritti gli attributi dell'elemento <Put>
:
Attributo | Descrizione | Predefinita | Presenza |
---|---|---|---|
eseguire l'override |
Se impostato su
|
true |
Facoltativo |
Elemento <Scope>
Definisce il limite di accessibilità per le KVM. 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 prod). Se imposti l'ambito su apiproxy
, le voci nella
KVM sono accessibili solo dal proxy API che scrive i valori sulla mappa.
Tieni presente che quando accedi a una mappa o a una voce della mappa, devi specificare lo stesso valore di ambito utilizzato
quando la mappa è stata creata. Ad esempio, se la mappa è stata creata con un ambito pari a
apiproxy
, devi utilizzare l'ambito apiproxy
per recuperarne i valori,
apportare modifiche o eliminare voci.
<Scope>environment</Scope>
Predefinita | environment |
---|---|
Presenza | Facoltativo |
Tipo | String |
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 alla 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, viene creata una chiave 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>
Predefinita | N/A |
---|---|
Presenza | Obbligatorio |
Tipo | String |
Attributi
Nella tabella seguente vengono descritti gli attributi dell'elemento <Value>
:
Attributo | Descrizione | Predefinita | Presenza |
---|---|---|---|
ref |
Specifica il nome di una variabile il cui valore contiene le coppie chiave-valore che vuoi impostare. | N/A | Obbligatorio se non viene fornito alcun valore letterale tra i tag di apertura e chiusura. Non consentito se viene fornito un valore letterale. |
Messaggi di errore
Questa sezione descrive i codici e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per la gestione degli 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.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 KeyValueMapOperations è
zero o un numero negativo, il deployment del proxy API non riesce. 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 KeyValueMapOperations .
|
build |
ValueIsMissing |
Questo errore si verifica se l'elemento <Value> non è presente sotto l'elemento <Entry> dell'elemento <InitialEntries> del criterio KeyValueMapOperations . |
build |
Schema
Note sull'utilizzo
Per una panoramica delle KVM, consulta Utilizzo delle mappe chiave-valore.
Utilizzando l'UI di Apigee, puoi definire le KVM solo a livello di ambiente, come descritto in Utilizzare le KVM con la UI di Apigee. Utilizzando l'API Apigee, puoi definire le KVM nell'ambito dell'organizzazione, dell'ambiente o del proxy API, come descritto nelle sezioni seguenti:
- API per le mappe chiave-valore con ambito a livello di organizzazione
- API per le mappe chiave-valore con ambito a livello di ambiente
- API per le mappe chiave-valore con ambito proxy con ambito API
Un archivio KVM 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 KVM può archiviare molte voci.
Ad esempio, supponi di dover archiviare un elenco di indirizzi IP associati a vari ambienti di backend. Potresti creare una KVM denominata ipAddresses
contenente un
elenco di coppie chiave/valore sotto forma di 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" }
Potresti utilizzare questa struttura per creare un archivio di indirizzi IP che potrebbero essere utilizzati dai criteri in fase di runtime per applicare la lista consentita/denylisting degli IP, la selezione dinamica di un indirizzo di destinazione backend e così via. In genere, il criterio KeyValueMapOperations viene utilizzato per archiviare o recuperare informazioni di lunga durata che devono essere riutilizzate in più transazioni di richiesta/risposta.
Le KVM possono essere manipolate tramite il criterio KeyValueMapOperations o direttamente tramite l'API Apigee. Ad esempio, puoi utilizzare l'API per caricare set di dati di grandi dimensioni nell'archivio chiavi-valore oppure creare script per gestire le voci della mappa delle coppie chiave-valore. Dovrai creare una KVM con l'API prima di accedervi con il criterio KeyValueMapOperations.
Specifica e recupera i nomi delle chiavi
Con gli elementi <Parameter>
e <Value>
, puoi specificare un valore letterale (in cui il valore è compreso tra i tag di apertura e chiusura) oppure utilizzare l'attributo ref
per specificare il nome di una variabile il cui valore deve essere utilizzato durante l'esecuzione.
Merita una menzione speciale per l'elemento <Parameter>
perché determina il nome della chiave che viene creata, nonché il nome della chiave che vuoi recuperare o eliminare. Di seguito sono riportati due esempi.
Il primo specifica il nome di una chiave letteralmente, mentre il secondo specifica il nome di una chiave utilizzando una variabile.
Supponiamo che vengano utilizzati i seguenti elementi per creare chiavi in una KVM:
<Parameter>KEY_NAME_LITERAL</Parameter> <Parameter ref="key.name.variable"/>
Nella prima istanza, il valore letterale KEY_NAME_LITERAL
viene archiviato nella KVM come nome della chiave. Nella seconda istanza, qualsiasi valore presente nel key.name.variable
diventa il nome della chiave nella KVM. Ad esempio, se key.name.variable
contiene il valore foo
, la chiave viene denominata foo
.
Per recuperare la chiave e un valore della chiave con un'operazione GET
(o rimuoverla con un'operazione DELETE
), il valore dell'elemento <Parameter>
deve corrispondere al nome della chiave nella KVM. Ad esempio, se il nome della chiave nella KVM è my_key
, puoi specificare il valore letterale con <Parameter>my_key</Parameter>
o specificare una variabile contenente il valore esatto mny_key
, in questo modo: <Parameter ref="variable.containing.foo"/>
.
Argomenti correlati
Per ulteriori informazioni sulle KVM, consulta i seguenti argomenti:
- Utilizzare le mappe chiave-valore
- API per le mappe chiave-valore con ambito a livello di organizzazione
- API per le mappe chiave-valore con ambito a livello di ambiente
- API per le mappe chiave-valore con ambito proxy con ambito API