Norme relative a KeyValueMapOperations

Questa pagina si applica ad Apigee e Apigee hybrid.

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 da mappe esistenti denominate configurando i criteri KeyValueMapOperations che specificano le operazioni PUT, GET o DELETE, rispettivamente. (Almeno una di queste operazioni deve essere eseguita dalla policy.)

Queste norme sono estensibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o di 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 hybrid versione 1.4.0, Apigee cripta tutte le KVM per impostazione predefinita. Utilizza l'attributo private. con tutte le variabili quando accedi a una 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 viene comunque criptato; tuttavia, le informazioni del KVM verranno visualizzate decriptate nella sessione di debug e non verrà generata alcuna eccezione.

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

Esempi

PUT KVM con un valore letterale

Quando viene eseguito il seguente criterio, viene creato un KVM criptato denominato FooKVM, quindi viene creata una chiave denominata FooKey_1 con due valori impostati con le 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 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 la KVM nell'interfaccia utente di gestione in API > Configurazione ambiente > Key-Value Map. Le KVM mostrate in quella pagina sono tutte limitate all'ambiente selezionato.

GET KVM from a literal

Questa policy 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>

Accedere dinamicamente a una KVM

Queste norme utilizzano l'elemento <MapName> per fare riferimento a un 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 è un servizio di abbreviazione degli URL. Il KVM potrebbe essere configurato per memorizzare gli URL abbreviati insieme agli URL completi corrispondenti.

Questo esempio di policy 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 con hash verrà generato dal codice (ad esempio JavaScript o Java) e poi memorizzato in questa variabile, a cui può accedere il criterio KeyValueMapOperations.

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

In Apigee vengono generati i seguenti KVM e voce nell'archivio chiave/valore e con ambito il proxy API a cui è collegato il criterio:

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

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

GET KVM from a variable

Un semplice esempio di KVM utile è un servizio di accorciamento degli URL. Il KVM potrebbe essere configurato per memorizzare gli URL abbreviati insieme agli URL completi corrispondenti.

Per recuperare il valore della voce KVM, ad esempio quella trattata nella scheda KeyValueMapOperations PUT, configura una policy 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 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, altre norme e altri codici possono accedervi estraendo il valore da queste variabili.

GET value from KVM

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

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, altre norme e codice possono accedervi estraendo il valore da questa 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 tabella seguente descrive gli attributi dell'elemento <KeyValueMapOperations>:

Nota:l'attributo mapIdentifier specifica il nome della 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 che <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	Presence
name	Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri. Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.	N/D	Obbligatorio
continueOnError	Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche: Le regole di errore vengono attivate SOLO in uno stato di errore (informazioni su continueOnError) Gestione degli errori all'interno del flusso corrente	falso	Facoltativo
enabled	Imposta su true per applicare il criterio. Imposta su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.	true	Facoltativo
async	Questo attributo è stato ritirato.	falso	Deprecato

Elemento <DisplayName>

Da utilizzare insieme 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/D Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.
Presence	Facoltativo
Tipo	Stringa

Elementi secondari

Questa sezione descrive gli elementi e gli attributi del criterio KeyValueMapOperations:

Elemento <Delete>

Elimina la coppia chiave/valore specificata. Deve essere utilizzato almeno uno dei seguenti valori: <Get>, <Put> o <Delete>.

Assicurati di specificare il nome del KVM con l'attributo mapIdentifier nell'elemento radice o con l'elemento <MapName>. Ad esempio:

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

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

Elemento <Entry>

Valori iniziali per le KVM, che vengono inseriti 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>

Predefinito	N/D
Presenza	Facoltativo
Tipo	N/D

Elemento <ExclusiveCache>

Deprecato. Utilizza invece l'elemento <Scope>.

Elemento <ExpiryTimeInSecs>

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

Un valore pari a 0 o -1 oppure l'esclusione di questo elemento comporta l'utilizzo del 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, Apigee dispone di un meccanismo integrato per memorizzare nella cache le chiavi/i valori KVM in memoria durante l'esecuzione. Questo criterio per le operazioni KVM legge sempre dalla cache per le operazioni GET.

L'elemento <ExpiryTimeInSecs> consente di controllare per quanto tempo le chiavi/i valori utilizzati nella policy vengono memorizzati nella cache prima di essere aggiornati nuovamente 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/i valori richiesti dalla KVM (il cui nome è specificato nell'attributo radice mapIdentifier delle norme o nell'elemento <MapName>) vengono caricati nella cache, dove rimangono per le successive operazioni GET finché non si verifica uno dei seguenti eventi:

• Il numero di secondi specificato in <ExpiryTimeInSecs> scade.
  oppure
• Un'operazione PUT in una policy KVM sovrascrive i valori esistenti (spiegati di seguito).

PUT: un'operazione PUT scrive chiavi/valori nel KVM specificato. Se PUT scrive in una chiave già presente nella cache, questa 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à 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 ogni nodo.

Esempio: memorizzazione nella cache di una KVM

1. Un'operazione GET recupera il valore di "rating", che aggiunge il valore "10" alla cache. Il <ExpiryTimeInSecs> delle norme è 60.
2. 30 secondi dopo, i criteri GET vengono eseguiti di nuovo e recuperano 10 dalla cache.
3. 5 secondi dopo, un criterio PUT aggiorna il valore di rating a 8 e il <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 PUT non fosse avvenuto, la cache inizialmente compilata dal primo GET esisterebbe ancora per altri 30 secondi, rimanenti dai 60 secondi originali.)
4. 15 secondi dopo, viene eseguito un altro GET e viene recuperato un valore di 8.

Note

• Per ottenere prestazioni ottimali, bilancia il tempo di scadenza della cache con la quantità di traffico API che prevedi. In caso di traffico intenso, ad esempio, 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 una policy temporanea che esegue un'operazione PUT una tantum con un breve <ExpiryTimeInSecs>. In questo modo la cache, che contiene il valore PUT, verrà reimpostata per il numero di secondi specificato.
• L'aggiornamento di un KVM con l'API o l'interfaccia utente Apigee non reimposta la cache KVM.
• Puoi utilizzare più operazioni nella stessa norma. In questo caso, la norma esegue le operazioni in ordine. Se utilizzi un PUT seguito da un GET nella stessa policy utilizzando la stessa chiave, il PUT, quando scrive, reimposta implicitamente la scadenza della cache.

Elemento <Get>

Recupera il valore della chiave specificata. Deve essere utilizzato almeno uno dei seguenti valori: <Get>, <Put> o <Delete>.

Apigee cripta tutti i dati archiviati nel KVM. Per maggiori dettagli, vedi 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 radice o con l'elemento <MapName>.

Puoi includere più blocchi Get nella policy per recuperare più elementi da una KVM.

Nota:puoi utilizzare più operazioni nella stessa norma. In questo caso, la norma esegue le operazioni in ordine. Se utilizzi un PUT seguito da un GET nella stessa policy utilizzando la stessa chiave, il PUT, quando scrive, reimposta implicitamente la scadenza della cache. Per maggiori informazioni, consulta l'elemento ExpiryTimeInSecs.

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

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.	N/D	Obbligatorio
index	Il numero di indice (in un indice a base 1) dell'elemento da recuperare da una chiave con più valori. Ad esempio, se specifichi index=1, verrà restituito il primo valore e assegnato 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 Recupera valore da KVM in Esempi.	N/D	Facoltativo

Ottenere un singolo elemento da un KVM

Con questa configurazione del passaggio 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 nel 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 testo non crittografato in qualsiasi sessione di debug creata.

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

Ottenere più elementi da una KVM

Nell'esempio seguente, supponiamo un KVM con le seguenti chiavi e valori. Oltre a memorizzare un elenco aggiornato dei film più popolari di tutti i tempi, il KVM memorizza il nome del regista di tutti i film più importanti.

Chiave	Valore
top_movies	La storia fantastica,Il Padrino,Quarto potere
Quarto potere	Orson Welles
La principessa sposa	Rob Reiner
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, la policy recupera il film più popolare del momento 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 utilizzati 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 dell'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 iniziali per le KVM, che vengono inseriti nella KVM al momento dell'inizializzazione. Assicurati di specificare il nome del KVM con l'attributo mapIdentifier sull'elemento principale.

Nota:l'elemento <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 Apigee in una versione di deployment del proxy API o esegui il deployment del bundle del proxy API contenente il criterio con questo elemento, le chiavi vengono create automaticamente nel KVM. Se i valori nel criterio sono diversi dai valori nel KVM, questi ultimi vengono sovrascritti quando viene eseguito il deployment del proxy API. Le nuove chiavi/valori vengono aggiunti alla KVM esistente insieme a quelli esistenti.

Le chiavi e i valori compilati 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 elemento secondario di <Get>, <Put> o <Delete> oppure come elemento secondario dell'elemento <Entry> che è un elemento 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 accodare 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. Ecco un esempio di configurazione del passaggio che specifica una chiave composita determinata dinamicamente:

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

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

La dimensione della chiave è limitata a 2 KB.

Nota:il nome ratelimit è riservato. Per saperne di più, consulta questo post della community Apigee.

Predefinito	N/D
Presenza	Facoltativo
Tipo	N/D

Elemento <MapName>

L'elemento <MapName> consente al criterio di identificare dinamicamente quale KVM utilizzare in fase di runtime. La possibilità di selezionare dinamicamente le KVM ti offre la flessibilità di progettare una policy KeyValueMapOperations che può accedere a KVM diverse, a seconda del contesto in cui viene eseguita la policy.

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 recupera il nome da una variabile di flusso. Nella terza riga, se la variabile di flusso restituisce un valore vuoto, viene utilizzata la stringa letterale invece.

Non specificare l'attributo mapIdentifier se utilizzi <MapName> nella tua policy. Per saperne di più, consulta gli attributi delle norme.

Se la mappa non esiste al momento del deployment del proxy, non verrà creata e Apigee genera un errore di runtime durante l'esecuzione della policy. Se viene fornita la variabile di flusso, l'elemento <InitialEntries> non è consentito. Riceverai un errore di convalida durante il deployment.

Elemento <Parameter>

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 runtime, 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 di chiavi effettiva è la concatenazione dei valori di ogni 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 nel KVM. Per le linee guida, vedi Specificare e recuperare i nomi delle chiavi.

Predefinito	N/D
Presenza	Obbligatorio
Tipo	Stringa

Attributi

La tabella seguente descrive gli attributi dell'elemento <Parameter>:

Attributo	Descrizione	Predefinito	Presenza
ref	Specifica il nome di una variabile il cui valore contiene il nome esatto della chiave che vuoi creare, ottenere o eliminare.	N/D	Obbligatorio se non viene fornito alcun valore letterale tra i tag di apertura e chiusura.

Elemento <Put>

Scrive una coppia chiave/valore in un KVM. Se la KVM specificata nell'attributo mapIdentifier dell'elemento radice non esiste e se l'elemento <MapName> non viene utilizzato, la mappa viene creata automaticamente. Se la mappa chiave-valore esiste già, la chiave/il valore vengono aggiunti.

Per creare una KVM utilizzando la UI o l'API, consulta:

• Utilizzo di KVM con la UI di Apigee per creare KVM criptate con ambito ambiente nella UI
• API per le mappe chiave-valore con ambito organizzazione
• API per le mappe chiave-valore con ambito ambiente
• API API proxy-scoped key value maps

Nota:puoi utilizzare più operazioni nella stessa norma. In questo caso, la norma esegue le operazioni in ordine. Se utilizzi un PUT seguito da un GET nella stessa policy utilizzando la stessa chiave, il PUT, quando scrive, reimposta implicitamente la scadenza della cache. Per maggiori informazioni, consulta l'elemento ExpiryTimeInSecs.

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 <Get> o <Delete> non sono presenti.
Tipo	N/D

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

Questa situazione si verifica, ad esempio, se compili una chiave utilizzando un riferimento a una variabile e la variabile a cui viene fatto riferimento è null. Quando vengono tentati nuovi comandi PUT con chiavi null, viene utilizzata solo quella chiave, quindi i valori esistenti per quella chiave vengono potenzialmente sovrascritti ogni volta che viene eseguito il criterio.

Attributi

La tabella seguente descrive gli attributi dell'elemento <Put>:

Attributo	Descrizione	Predefinito	Presenza
override	Se impostato su true, sostituisce il valore di una chiave. <Put override="false"> scrive se e solo se non è presente alcuna voce attualmente salvata nello store KVM per quella chiave.	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 produzione). Se imposti l'ambito su apiproxy, le voci nella KVM sono accessibili solo dal proxy API che scrive i valori nella mappa.

Tieni presente che quando accedi a una mappa o a una voce della 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 di apiproxy, devi utilizzare l'ambito apiproxy quando recuperi i relativi valori, inserisci modifiche o elimina voci.

<Scope>environment</Scope>

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

Se devi utilizzare la stessa KVM in più proxy, valuta la possibilità di aggiungere la policy KVM a un SharedFlow e di utilizzare quest'ultimo nei proxy.

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 runtime:

<!-- 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 in più parti. I valori vengono combinati in fase di runtime.

Nel seguente esempio, 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

La tabella seguente descrive gli attributi dell'elemento <Value>:

Attributo	Descrizione	Predefinito	Presenza
ref	Specifica il nome di una variabile il cui valore contiene i valori delle chiavi che vuoi impostare.	N/D	Obbligatorio se non viene fornito alcun valore letterale tra i tag di apertura e chiusura. Vietato se viene fornito un valore letterale.

Messaggi di errore

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Fault code	HTTP status	Cause	Fix
steps.keyvaluemapoperations.UnsupportedOperationException	500	This error occurs if the mapIdentifier attribute is set to empty string in the KeyValueMapOperations policy.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Error name	Cause	Fix
InvalidIndex	If the index attribute specified in the <Get> element of KeyValueMapOperations policy is zero or a negative number, then the deployment of the API proxy fails. The index starts from 1, so an index of zero or negative integer is considered as invalid.
KeyIsMissing	This error occurs if the <Key> element is completely missing or <Parameter> element is missing within <Key> element underneath the <Entry> of the <InitialEntries> element of the KeyValueMapOperations policy.
ValueIsMissing	This error occurs if the <Value> element is missing underneath the <Entry> element of the <InitialEntries> element of the KeyValueMapOperations policy.

Schemi

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

Note sull'utilizzo

Per una panoramica delle mappe chiave-valore, vedi Utilizzo delle mappe chiave-valore.

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

• API per le mappe chiave-valore con ambito organizzazione
• API per le mappe chiave-valore con ambito ambiente
• API API proxy-scoped key value maps

Un archivio KVM fornisce un meccanismo di persistenza leggero per i dati formattati come coppie chiave/valore. Puoi accedervi in fase di runtime tramite policy o codice. Una mappa contiene dati arbitrari nel formato key=value.

Nota: la dimensione della chiave è limitata 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ò memorizzare molte voci.

Ad esempio, supponiamo che tu debba archiviare un elenco di indirizzi IP associati a vari ambienti di backend. Potresti creare un KVM chiamato ipAddresses che contenga 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 possono essere utilizzati dalle policy in fase di runtime per applicare l'inserimento/la rimozione dinamica degli indirizzi IP, per selezionare dinamicamente un indirizzo di destinazione di backend e così via. In genere, il criterio KeyValueMapOperations viene utilizzato per memorizzare 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 chiave/valore o creare script per gestire le voci della mappa 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 si trova tra i tag di apertura e chiusura) o utilizzare l'attributo ref per specificare il nome di una variabile il cui valore deve essere utilizzato in runtime.

L'elemento <Parameter> merita una menzione speciale, 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. La prima specifica un nome di chiave letteralmente, mentre la seconda specifica un nome di chiave utilizzando una variabile. Supponiamo che per creare le chiavi in un KVM vengano utilizzati i seguenti valori:

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

Nella prima istanza, il valore letterale di KEY_NAME_LITERAL viene memorizzato 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 conteneva il valore foo, la chiave si chiamerebbe foo.

Per recuperare la chiave e un valore chiave con un'operazione GET (o rimuovere 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> o una variabile che contiene il valore esatto mny_key, in questo modo: <Parameter ref="variable.containing.foo"/>.

Nota:il nome ratelimit è riservato. Per ulteriori informazioni, consulta le norme relative alle quote - Genera NullPointerException.

Argomenti correlati

Per saperne di più sui KVM, consulta i seguenti argomenti:

• Utilizzo delle mappe chiave-valore
• API per le mappe chiave-valore con ambito organizzazione
• API per le mappe chiave-valore con ambito ambiente
• API API proxy-scoped key value maps