Norme KeyValueMapOperations

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Cosa

Fornisce l'accesso basato su criteri a uno store di mappe chiave-valore (KVM) disponibile in Apigee. Le coppie chiave/valore possono essere archiviate, recuperate ed eliminate dalle mappe esistenti con nome configurando i criteri KeyValueMapOperations che specificano rispettivamente le operazioni PUT, GET o DELETE. (Il criterio deve eseguire almeno una di queste operazioni).

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 di utilizzo, consulta Tipi di criteri.

Nota: a partire dal rilascio di Apigee versione ibrida 1.4.0, Apigee cripta tutti i KVM per impostazione predefinita. Utilizza l'attributo private. con tutte le variabili quando accedi a un KVM con il comando GET per nascondere le informazioni della KVM in una sessione di debug. Se l'attributo private. non viene utilizzato, il KVM è ancora criptato. Tuttavia, le informazioni KVM appariranno decriptate nella sessione di debug e non verranno generate eccezioni.

Video: il seguente video fornisce un'introduzione generale ai KVM.

Esempi

PUT KVM con un valore letterale

Quando viene eseguito il criterio seguente, viene creato un KVM criptato denominato FooKVM, quindi viene creata una chiave denominata FooKey_1 con due valori impostati con stringhe letterali foo e bar (non impostata con valori estratti dalle variabili). Quando GET la chiave nell'esempio successivo, specifichi un numero di indice per recuperare il valore che ti interessa.

<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 ambiente > Mappe chiave-valore. I KVM mostrati in quella pagina hanno tutti come ambito l'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>

Accesso dinamico a un KVM

Questo criterio utilizza l'elemento <MapName> per fare riferimento in modo dinamico a un KVM con una variabile di flusso. L'elemento ottiene l'identificatore KVM dalla variabile di flusso. Tieni presente che l'attributo mapIdentifier è stato 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 utile KVM è un servizio di abbreviazione di URL. KVM può essere configurato per archiviare gli URL abbreviati insieme agli URL completi corrispondenti.

Questo esempio di criterio crea un KVM. Il criterio utilizza il comando PUT per inserire una chiave con due valori associati in un KVM denominato 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 sottoposto ad hashing verrebbe 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
• I contenuti della variabile predefinita request.queryparam.url

Ad esempio, quando il criterio viene eseguito in fase di runtime, i valori delle variabili potrebbero essere i seguenti:

• urlencoding.requesturl.hashed: ed24e12820f2f900ae383b7cc4f2b31c402db1be
• urlencoding.longurl.encoded: http://tinyurl.com/38lwmlr
• request.queryparam.url: http://apigee.com

Il KVM e la voce seguenti verranno generati nell'archivio chiave/valore di Apigee e limitati al proxy API a cui è associato il criterio:

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

La voce rimarrà attiva fino a quando non verrà eliminata. Le voci dell'archivio chiave/valore sono distribuite tra le istanze di Apigee che eseguono il cloud.

Recupera KVM da una variabile

Un semplice esempio di utile KVM è un servizio di shortening dell'URL. KVM può essere configurato per archiviare gli URL abbreviati insieme agli URL completi corrispondenti.

Per recuperare il valore della voce KVM, come quello indicato nella scheda KeyValueMapOperations PUT, configura un criterio per GET il 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.

GET valore da KVM

Utilizza l'attributo private. con tutte le variabili quando accedi a un KVM con il comando GET per nascondere le informazioni KVM in una sessione di debug. Se l'attributo private. non viene utilizzato, il KVM è comunque criptato; tuttavia, le informazioni KVM verranno visualizzate come decriptate nella sessione di debug e non verranno generate eccezioni.

In questo esempio, la variabile private.encryptedVar contiene il valore decriptato della chiave foo del 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">

Nella tabella seguente vengono descritti gli attributi dell'elemento <KeyValueMapOperations>:

Nota: l'attributo mapIdentifier specifica il nome del KVM con cui vuoi interagire. Puoi anche specificare un KVM in modo dinamico con l'elemento <MapName>.

Attributo	Descrizione	Predefinito	Presenza
mapIdentifier	Specifica un identificatore che indica al criterio a quale KVM deve accedere. Se mancano sia questo identificatore sia <MapName>, viene utilizzato un KVM denominato kvmap. Non puoi utilizzare questo attributo se specifichi l'elemento <MapName>.	N/D	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 name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri. Facoltativamente, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.	N/A	Obbligatorio
continueOnError	Impostalo su false per restituire un errore in caso di errore di un criterio. Questo è il comportamento previsto per la maggior parte dei criteri. Imposta su true per fare in modo che l'esecuzione del flusso continui anche in caso di errore di un criterio. Vedi anche: Le regole di errore vengono attivate SOLO in stato di errore (informazioni su continueOnError) Gestione dei guasti all'interno del flusso di corrente	false	Facoltativo
enabled	Imposta il criterio su true per applicare il criterio. Impostala su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane associato a un flusso.	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 name del criterio.
Presenza	Facoltativo
Tipo	Stringa

Elementi secondari

In questa sezione vengono descritti gli elementi e gli attributi del criterio KeyValueMapOperations:

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 principale o con l'elemento <MapName>. Ad esempio:

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

Predefinito	N/D
Presenza	Obbligatorio se non sono presenti <Get> o <Put>.
Tipo	N/D

Elemento <Entry>

Valori di origine per KVM, che vengono compilati nel 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>

Predefinito	N/D
Presenza	Facoltativo
Tipo	N/D

Elemento <EsclusiCache>

Ritirato. Usa invece l'elemento <Scope>.

Elemento <ExpiryTimeInSecs>

Specifica la durata in secondi dopo la quale Apigee aggiorna il suo valore memorizzato nella cache dal KVM specificato.

Un valore pari a 0 o -1, o escludendo questo elemento, significa che viene utilizzato il valore predefinito di 300 secondi. Ad esempio:

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

Predefinito	300 (5 minuti)
Presenza	Facoltativo
Tipo	Numero intero

Una 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, Apigee dispone di un meccanismo integrato per la memorizzazione nella cache di chiavi/valori KVM in memoria durante il runtime. Questo criterio relativo alle operazioni KVM legge sempre dalla cache per le operazioni GET.

L'elemento <ExpiryTimeInSecs> consente di controllare per quanto tempo le chiavi/le coppie utilizzate nel criterio vengono archiviate nella cache prima di essere aggiornate di nuovo dallo 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 GET del KVM, le chiavi/i valori richiesti dal KVM (il cui nome è specificato nell'attributo mapIdentifier principale del criterio o nell'elemento <MapName>) vengono caricati nella cache, dove rimangono per le successive operazioni GET finché non si verifica uno dei seguenti casi:

• Scadenza del numero di secondi specificato in <ExpiryTimeInSecs>.
  o
• Un'operazione PUT in un criterio KVM sovrascrive i valori esistenti (spiegati di seguito).

PUT: un'operazione PUT scrive chiavi/valori sul KVM specificato. Se PUT scrive in una chiave già esistente nella cache, la cache viene aggiornata immediatamente e ora contiene il nuovo valore per il numero di secondi specificato nell'elemento <ExpiryTimeInSecs> del criterio. Tuttavia, l'utilizzo di PUT aggiornerà solo la cache 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 un KVM

1. Un'operazione GET recupera il valore di "rating", che aggiunge il valore "10" alla cache. Il valore <ExpiryTimeInSecs> nel criterio è 60.
2. 30 secondi dopo, il criterio GET viene eseguito di nuovo e recupera 10 dalla cache.
3. 5 secondi dopo, un criterio PUT aggiorna il valore di rating in 10 e il valore <ExpiryTimeInSecs> nel criterio PUT è 20. La cache viene aggiornata immediatamente con il nuovo valore, che è ora impostato per rimanere nella cache per 20 secondi. Se il PUT non fosse successo, la cache originariamente compilata dalla prima GET esisterebbe ancora per altri 30 secondi, rimasti dai 60 secondi originali.
4. 15 secondi dopo, un altro GET esegue e recupera il valore 8.

Note

• Per ottenere prestazioni ottimali, bilancia la scadenza della cache con la quantità di traffico API prevista. Ad esempio, in caso di traffico intenso, potresti voler impostare intervalli di scadenza della cache più lunghi per evitare aggiornamenti frequenti dal database.
• Non è possibile reimpostare manualmente la cache KVM. Tuttavia, puoi creare un criterio temporaneo che esegua un'operazione PUT una tantum con un valore <ExpiryTimeInSecs> breve. Questa operazione reimposterà la cache, che contiene il valore PUT, per il numero di secondi specificato.
• L'aggiornamento di un KVM con l'API o la UI di Apigee non reimposta la cache KVM.
• Puoi utilizzare più operazioni nello stesso criterio. In questo caso, il criterio esegue le operazioni nell'ordine indicato. Se utilizzi un oggetto PUT seguito da un GET nello stesso criterio con la stessa chiave, il valore PUT, durante la scrittura, reimposterà implicitamente la scadenza della cache.

Elemento <Get>

Recupera il valore per la chiave specificata. Devi utilizzare almeno un elemento <Get>, <Put> o <Delete>.

Apigee cripta tutti i dati archiviati sul 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 sull'elemento principale o con l'elemento <MapName>.

Puoi includere più blocchi Get nel criterio per recuperare più elementi da un KVM.

Nota: puoi utilizzare più operazioni nello stesso criterio. In questo caso, il criterio esegue le operazioni nell'ordine indicato. Se utilizzi un oggetto PUT seguito da un GET nello stesso criterio con la stessa chiave, il valore PUT, durante la scrittura, reimposterà implicitamente la scadenza della cache. Consulta l'elemento ExpiryTimeInSecs per ulteriori informazioni.

Predefinito	N/D
Presenza	Obbligatorio se non sono presenti <Put> o <Delete>.
Tipo	N/D

Attributi

Nella tabella seguente vengono descritti gli attributi dell'elemento <Get>:

Attributo	Descrizione	Predefinito	Presenza
assignTo	La variabile a cui deve essere assegnato il valore recuperato.	N/D	Obbligatorio
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 index=1, verrà restituito il primo valore e lo assegnerai alla variabile assignTo. Se non viene specificato alcun valore di indice, tutti i valori di quella voce vengono assegnati alla variabile come java.util.List. Per un esempio, consulta la scheda Ottieni valore da KVM in Samples.	N/D	Facoltativo

Ottenere un singolo articolo da un KVM

Con questa configurazione di passaggi di esempio, il criterio legge e decripta il valore di una singola chiave nel 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 sulla KVM sono sensibili. Per impedire che i dati recuperati vengano visualizzati in una sessione di debug, utilizza il prefisso private. in corrispondenza del nome della variabile specificato nell'attributo assignTo. Se non utilizzi il prefisso private., i dati recuperati dal KVM verranno visualizzati in testo in chiaro in ogni sessione di debug creata.

Con questa configurazione di passaggio di esempio, il criterio legge e decripta il valore associato a una singola chiave nel KVM e lo assegna 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>

Recupero di più elementi da un KVM

Nell'esempio seguente, supponiamo che sia un KVM con le chiavi e i valori seguenti. Oltre ad archiviare una lista dei film più popolari di tutti i tempi, KVM include anche il nome del regista di tutti i film più importanti.

Chiave	Valore
top_movies	La principessa sposa,Il padrino,Il cittadino Kane
Il cittadino Kane	Orson Welles
Sposa principessa	Rob Reiner
Il padrino	Francesco 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 il film attualmente preferito 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, Apigee crea le seguenti variabili con i valori corrispondenti, che possono essere utilizzate in seguito nel flusso proxy API:

• top.movie.pick=Princess Bride
• movie.director=Rob Reiner

Il valore di top.movie.pick è solo il primo elemento dell'elenco separato da virgole, perché il primo elemento <Get> utilizza un attributo index pari a 1. Quindi, il secondo elemento <Get> utilizza il valore assegnato a top.movie.pick come chiave per recuperare un valore in movie.director.

Elemento <InitialEntries>

Valori di origine per KVM, che vengono inseriti nel KVM al momento dell'inizializzazione. Assicurati di specificare il nome del KVM con l'attributo mapIdentifier sull'elemento principale.

Nota: <InitialEntries> non è consentito se viene utilizzato l'elemento <MapName>.

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 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 nel KVM, questi vengono sovrascritti quando viene eseguito il deployment del proxy API. 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.

Predefinito	N/D
Presenza	Facoltativo
Tipo	N/D

Elemento <Key>

Specifica la chiave in una voce KVM. Questo elemento viene visualizzato come secondario di <Get>, <Put> o <Delete> oppure come elemento secondario dell'elemento <Entry> che è secondario 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 elemento <Parameter> per creare la chiave. Ad esempio, i contenuti delle variabili userID e role potrebbero essere combinati per creare una chiave dinamica. Ecco un passaggio di esempio di configurazione che specifica una chiave composita determinata dinamicamente:

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

Assicurati di vedere l'elemento <Parameter> per le specifiche su come impostare il nome della chiave.

La dimensione della chiave è limitata a 2 kB.

Nota: il nome ratelimit è riservato. Per ulteriori informazioni, consulta questo post della community di Apigee.

Predefinito	N/D
Presenza	Facoltativo
Tipo	N/D

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 i KVM ti offre la flessibilità di progettare un criterio KeyValueMapOperations in grado di accedere a diversi KVM, a seconda del contesto in cui il criterio viene eseguito.

Ecco 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 KVM come stringa letterale. La seconda riga prende il nome da una variabile di flusso. Nella terza riga, se la variabile di flusso si risolve in un valore vuoto, viene utilizzata la stringa letterale.

Non specificare l'attributo mapIdentifier se utilizzi <MapName> nel criterio. Per ulteriori informazioni, consulta gli attributi delle norme.

Se la mappa non esiste quando viene eseguito il deployment del proxy, 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 mediante 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 riceva, aggiorni o elimini una voce chiave/valore, il nome della chiave deve corrispondere a quello della chiave nella KVM. Per le linee guida, consulta Specifica e recupero dei nomi delle chiavi.

Predefinito	N/D
Presenza	Obbligatorio
Tipo	Stringa

Attributi

Nella tabella seguente vengono descritti 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, recuperare o eliminare.	N/D	Obbligatorio se non viene fornito un valore letterale tra il tag di apertura e quello di chiusura.

Elemento <Put>

Scrive una coppia chiave/valore su un KVM. Se il KVM specificato 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 un KVM utilizzando l'interfaccia utente o l'API, vedi:

• Utilizzo di KVM con l'UI di Apigee per creare KVM con ambito a livello di ambiente criptati nell'interfaccia utente
• API Key Value Map con ambito organizzazione
• API delle mappe coppia chiave-valore con ambito a livello di ambiente
• API delle mappe coppie chiave-valore con ambito proxy API

Nota: puoi utilizzare più operazioni nello stesso criterio. In questo caso, il criterio esegue le operazioni nell'ordine indicato. Se utilizzi un oggetto PUT seguito da un GET nello stesso criterio con la stessa chiave, il valore PUT, durante la scrittura, reimposterà implicitamente la scadenza della cache. Consulta l'elemento ExpiryTimeInSecs per ulteriori informazioni.

La dimensione della chiave è limitata a 2 kB.

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

Predefinito	N/D
Presenza	Obbligatorio se non sono presenti <Get> o <Delete>.
Tipo	N/D

Avviso: se il criterio utilizzava il comando PUT per inserire una chiave/valore in un KVM utilizzando una chiave null, la seguente chiave viene creata automaticamente: __$$_EDGE_KVM_EMPTY_KEY_$$__

Questa situazione si verifica, ad esempio, se stai compilando una chiave utilizzando un riferimento di variabile e la variabile di riferimento è nulla. Quando vengono tentati nuovi comandi PUT con chiavi null, viene utilizzata solo quella chiave, quindi i valori esistenti per quella chiave potrebbero essere sovrascritti ogni volta che viene eseguito il criterio.

Attributi

Nella tabella seguente vengono descritti gli attributi dell'elemento <Put>:

Attributo	Descrizione	Predefinito	Presenza
sostituire	Se impostato su true, sostituisce il valore di una chiave. <Put override="false"> scriverà solo se e solo se nell'archivio KVM non è presente una voce relativa a quella chiave.	true	Facoltativo

Elemento <Scope>

Definisce i confini di accessibilità per i 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 produzione). 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 voce di mappa o mappa, devi specificare lo stesso valore di ambito utilizzato al momento della creazione della mappa. Ad esempio, se la mappa è stata creata con un ambito apiproxy, devi utilizzare l'ambito apiproxy durante il recupero dei valori, l'applicazione di modifiche o l'eliminazione di voci.

<Scope>environment</Scope>

Predefinito	environment
Presenza	Facoltativo
Tipo	Stringa
Valori validi	organization environment apiproxy policy (revisione proxy API)

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 valori v1,v2
• Chiave k2 con valori 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>

Nell'esempio seguente, viene creata una chiave con due valori. Supponiamo che il nome dell'organizzazione sia foo_org, il nome del proxy API sia bar e l'ambiente sia test:

• Chiave foo_org con valori bar,test

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

Predefinito	N/D
Presenza	Obbligatorio
Tipo	Stringa

Attributi

Nella tabella seguente vengono descritti gli attributi dell'elemento <Value>:

Attributo	Descrizione	Predefinito	Presenza
ref	Specifica il nome di una variabile il cui valore contiene i valori chiave che vuoi impostare.	N/D	Obbligatorio se non viene fornito un valore letterale tra il tag di apertura e quello di chiusura. Vietato 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.

Suggerimento: hai bisogno di aiuto per risolvere un errore? Fai clic su nella colonna Correggi per informazioni dettagliate sulla risoluzione dei problemi.

Codice di errore	Stato HTTP	Causa	Correggi
steps.keyvaluemapoperations.UnsupportedOperationException	500	Questo errore si verifica se l'attributo mapIdentifier viene impostato sulla stringa vuota nel criterio KeyValueMapOperations.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

Suggerimento: hai bisogno di aiuto per risolvere un errore? Fai clic su nella colonna Correggi per informazioni dettagliate sulla risoluzione dei problemi.

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.
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.
ValueIsMissing	Questo errore si verifica se l'elemento <Value> non è presente sotto l'elemento <Entry> dell'elemento <InitialEntries> del criterio KeyValueMapOperations.

Schema

Esempio: consulta gli esempi del nostro repository GitHub per gli schemi più recenti.

Note sull'utilizzo

Per una panoramica degli KVM, consulta la sezione Utilizzo delle mappe chiave-valore.

Utilizzando l'interfaccia utente di Apigee, puoi definire i KVM solo a livello di ambiente, come descritto in Utilizzo di KVM con l'interfaccia utente di Apigee. Utilizzando l'API Apigee, puoi definire i KVM nell'ambito dell'organizzazione, dell'ambiente o del proxy API, come descritto nelle seguenti sezioni:

• API Key Value Map con ambito organizzazione
• API delle mappe coppia chiave-valore con ambito a livello di ambiente
• API delle mappe coppie chiave-valore con ambito proxy 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.

Nota: le dimensioni della chiave sono limitate a 2 kB.

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. Un KVM può archiviare molte voci.

Ad esempio, supponiamo che tu debba archiviare un elenco di indirizzi IP associati a vari ambienti di backend. Puoi creare un KVM denominato ipAddresses che contiene 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"
}

Puoi utilizzare questa struttura per creare un archivio di indirizzi IP utilizzabili dai criteri in fase di runtime per applicare l'inserimento nella lista consentita o la negazione degli IP, per selezionare dinamicamente un indirizzo di destinazione del 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.

I KVM possono essere manipolati tramite il criterio KeyValueMapOperations o direttamente tramite l'API Apigee. 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 delle coppie chiave-valore. Devi creare un KVM 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 (in cui 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.

Una menzione speciale all'elemento <Parameter> dipende dal nome della chiave che viene creata, oltre che dal 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 un nome di chiave mediante una variabile. Supponiamo che per creare chiavi in un KVM vengono utilizzati i seguenti elementi:

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

Nella prima istanza, il valore letterale di KEY_NAME_LITERAL viene archiviato nella KVM come nome della chiave. Nella seconda istanza, qualsiasi valore contenuto in key.name.variable diventerà il nome della chiave nella KVM. Ad esempio, se key.name.variable contenga il valore foo, la chiave sarà denominata foo.

Per recuperare la chiave e un valore della chiave con un'operazione GET (o per rimuoverli con un'operazione DELETE), il valore dell'elemento <Parameter> deve corrispondere al nome della chiave nel KVM. Ad esempio, se il nome della chiave nel KVM è my_key, puoi specificare il valore letterale con <Parameter>my_key</Parameter> oppure specificare una variabile contenente il valore esatto mny_key, in questo modo: <Parameter ref="variable.containing.foo"/>.

Nota: il nome ratelimit è riservato. Per ulteriori informazioni, consulta Policy quota - genera NullPointerException.

Argomenti correlati

Per ulteriori informazioni sui KVM, consulta i seguenti argomenti:

• Utilizzare le mappe chiave-valore
• API Key Value Map con ambito organizzazione
• API delle mappe coppia chiave-valore con ambito a livello di ambiente
• API delle mappe coppie chiave-valore con ambito proxy API