Criterio KeyValueMapOperations

Questa pagina si applica a Apigee e Apigee ibridi.

Visualizza documentazione di Apigee Edge.

Icona Key Value Map Operations dalla UI di Apigee

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 Criteri KeyValueMapOperations che specificano PUT, GET o rispettivamente DELETE. (Almeno uno dei operazioni devono essere eseguite dal criterio.

Questo criterio è una norma estendibile e il suo utilizzo potrebbe comportare costi o di utilizzo delle applicazioni, a seconda della licenza Apigee. Per informazioni sui tipi di norme e le implicazioni per l'utilizzo, consulta 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, crea quindi una chiave denominata FooKey_1 con due valori impostati con stringhe letterali foo e bar (non impostato con valori estratti dalle variabili). Quando Usa GET la chiave nel prossimo esempio, 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 vedere il KVM nella UI in API > Configurazione dell'ambiente > Mappe chiave-valore. Le KVM mostrati in quella pagina hanno tutti l'ambito nell'ambiente selezionato.

OTTIENI KVM da un valore letterale

Questo criterio esamina la mappa FooKVM dell'esempio precedente, ottiene il valore secondo valore (index="2") dalla chiave FooKey_1 e lo archivia in una variabile chiamato 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 di una variabile di flusso. L'elemento ottiene l'identificatore KVM dalla variabile di flusso. Tieni presente che mapIdentifier omesso; non puoi usare <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. KVM potrebbe essere configurata per archiviare URL abbreviati insieme ai corrispondenti URL completi.

Questo esempio di criteri crea una KVM. Il criterio utilizza il comando PUT per inserire un 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 una variabile personalizzata. L'URL della richiesta con hash viene generato tramite codice (JavaScript o Java, esempio) e quindi archiviati in questa variabile, dove il criterio KeyValueMapOperations può accedere li annotino.

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 questi: che segue:

  • 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 la seguente KVM e voce con ambito 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 dell'archivio chiave/valore sono distribuite tra di Apigee che eseguono il cloud.

Recupera KVM da una variabile

Un semplice esempio di KVM utile è un servizio di abbreviazione di URL. KVM potrebbe essere configurata per archiviare URL abbreviati insieme ai corrispondenti URL completi.

Per recuperare il valore della voce KVM, come 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 dell'attributo La variabile urlencoding.requesturl.hashed è ed24e12820f2f900ae383b7cc4f2b31c402db1be, quindi la variabile personalizzata denominata Verrà impostato urlencoding.shorturl con il valore http://tinyurl.com/38lwmlr.

Ora che i dati sono stati recuperati, altri criteri e codice possono accedervi estraendo il valore di queste variabili.

Recupera valore da KVM

Utilizza l'attributo private. con tutte le variabili quando accedi a una KVM con GET per nascondere le informazioni KVM in una sessione di debug. Se L'attributo private. non è utilizzato, la KVM è ancora criptata. mentre la KVM le informazioni verranno decriptate nella sessione di debug e non verranno generate eccezioni.

In questo esempio, la variabile private.encryptedVar contiene il valore decriptato della console KVM Chiave foo.

<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 di quella variabile.

&lt;KeyValueMapOperations&gt;

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>

&lt;KeyValueMapOperations&gt; attributi

L'esempio seguente mostra gli attributi del <KeyValueMapOperations> elemento:

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="Key-Value-Map-Operations-1" mapIdentifier="map_name">

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

Attributo Descrizione Predefinito Presenza
mapIdentifier

Specifica un identificatore che indica al criterio a quale KVM deve accedere.

Se mancano entrambi questo identificatore e <MapName>, viene utilizzata una KVM denominata 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:

 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

Questa sezione descrive gli elementi e gli attributi di KeyValueMapOperations norme:

&lt;Delete&gt; elemento

Elimina la coppia chiave/valore specificata. Almeno uno di <Get>, È necessario utilizzare <Put> o <Delete>.

Assicurati di specificare il nome della 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

&lt;Entry&gt; elemento

I valori seed per le KVM, che vengono completati nella KVM quando è inizializzato. 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

<ExclusiveCache> elemento

Deprecato. Usa invece l'elemento <Scope>.

<ExpiryTimeInSecs> elemento

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 significa che il valore predefinito di 300 secondi è in uso. 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 una KVM in fase di runtime può rallentare le prestazioni del proxy. Per migliorare le prestazioni di Apigee dispongono 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 utilizzate nel criterio vengono archiviate nella cache prima di essere nuovamente aggiornate dalla KVM. Tuttavia, ci sono alcune differenze nel modo in cui le operazioni GET e PUT influiscono sulla scadenza della cache.

GET - La primissima volta che viene eseguita un'operazione KVM GET, il processo dalla KVM (il cui nome è specificato nella cartella principale mapIdentifier del criterio) o l'elemento <MapName>) vengono caricati nella cache, dove rimangono per le successive operazioni di GET fino a quando si verifica quanto segue:

  • Scadenza del numero di secondi specificato in <ExpiryTimeInSecs>.
    o
  • 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 nella Elemento <ExpiryTimeInSecs>. Tuttavia, se usi PUT, la cache verrà aggiornata 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

  1. Un'operazione GET recupera il valore di "rating" che aggiunge il valore "10" da memorizzare nella cache. La <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 <ExpiryTimeInSecs> nel criterio PUT ha 20. La cache viene immediatamente aggiornato con il nuovo valore, che ora è impostato per rimanere nella cache per 20 secondi. (Se PUT non fosse successo, la cache originariamente popolata dai primi GET esisterebbe ancora 30 secondi, restanti dai 60 secondi originali).
  4. 15 secondi dopo, un altro GET viene eseguito e recupera il valore 8.

&lt;Get&gt; elemento

Recupera il valore per la chiave specificata. Almeno uno di <Get>, È necessario utilizzare <Put> o <Delete>.

Apigee cripta tutti i dati archiviati nella KVM. Per maggiori dettagli, vedi Informazioni chiavi di crittografia. Quando utilizzi <Get>, Apigee decripta i dati archiviati e lo assegna a una variabile nel contesto del messaggio. Il nome della variabile viene specificato utilizzando Attributo assignTo.

Assicurati di specificare il nome della KVM con l'attributo mapIdentifier nella o con l'elemento <MapName>.

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

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

Attributi

Nella tabella seguente vengono descritti gli attributi del comando <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 basato su 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 a la variabile assignTo. Se non viene specificato alcun valore di indice, tutti i valori di tali voci vengono assegnate alla variabile come java.util.List.

Per un esempio, consulta la scheda Ottieni valore da KVM in Samples.

 N/D 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 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 nella KVM sono sensibili. Per impedire che i dati recuperati non appaia in un Sessione di debug, utilizza il prefisso private. per il nome della variabile specificato in assignTo. Se non utilizzi il prefisso private., i dati recuperati dalla KVM verranno visualizzati in qualsiasi sessione di debug che crei.

Con questa configurazione di passaggio di esempio, il criterio legge e decripta il valore associato a chiave singola nel KVM e assegna quel valore a una variabile. Il compito non verrà visualizzato 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. Inoltre, all'archiviazione di un elenco dei film più popolari di tutti i tempi, il KVM archivia il nome del regista di tutti i principali film.

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 il filmato principale corrente e il nome del suo direttore:

<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 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.

<InitialEntries> elemento

Valori seed per KVM, che vengono compilati nella KVM al momento dell'inizializzazione. Assicurati di specificare il nome della KVM con l'attributo mapIdentifier attivo l'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 in 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 creati automaticamente sulla KVM. Se i valori nelle norme sono diversi rispetto a quelli nella KVM, questi vengono sovrascritti al momento del deployment del proxy API. Qualsiasi Vengono aggiunti nuove chiavi/valori 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.

Predefinito N/D
Presenza Facoltativo
Tipo N/D

<Key> elemento

Specifica la chiave in una voce KVM. Questo elemento appare come elemento secondario di <Get>, <Put>, <Delete> oppure come elemento secondario dell'elemento <Entry> che è un figlio di <InitialEntries>. Ecco un esempio di chiave fissa:

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

Una chiave può essere composita, con elementi dinamici, nel senso che più di una chiave Puoi aggiungere <Parameter> per creare la chiave. Ad esempio, i contenuti le variabili userID e role potrebbero essere combinate per creare un chiave dinamica. Di seguito è riportato un esempio di configurazione dei passaggi che specifica un'istanza composta, chiave determinata:

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

Assicurati di vedere l'elemento <Parameter> per specifiche sull'impostazione del nome della chiave.

Le dimensioni della chiave sono limitate a 2 kB.

Predefinito N/D
Presenza Facoltativo
Tipo N/D

&lt;MapName&gt; elemento

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 offre la flessibilità di progettare un solo criterio KeyValueMapOperations che possa accedere diverse KVM, 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 si risolve in un valore vuoto, viene utilizzata la stringa letterale .

Non specificare l'attributo mapIdentifier se utilizzi <MapName> nelle tue norme. Per ulteriori informazioni, consulta gli attributi dei criteri.

Se la mappa non esiste al momento del deployment del proxy, non verrà creata e Apigee genera un quando il criterio viene eseguito. Se viene fornita la variabile di flusso, L'elemento <InitialEntries> non è consentito. Riceverai un errore di convalida durante e deployment continuo.

<Parameter> elemento

Specifica un componente di una chiave in una coppia chiave/valore. Questo elemento specifica il nome durante la creazione, l'aggiornamento recuperare o eliminare la 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>

Quando l'elemento <Key> include più elementi <Parameter>, il valore la stringa di chiave efficace è concatenazione dei valori di ogni parametro, uniti da un doppio trattino basso. Ad esempio, nel nell'esempio precedente, se la variabile apiproxy.name ha il valore abc1, la variabile la chiave effettiva sarà targeturl__abc1__weight.

Che tu stia recuperando, aggiornando o eliminando una voce chiave/valore, il nome della chiave deve corrispondere nome della chiave nella KVM. Consulta la sezione Specificazione e recupero dei nomi delle chiavi per le linee guida.

Predefinito N/D
Presenza Obbligatorio
Tipo Stringa

Attributi

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

Attributo Descrizione Predefinito Presenza
riferimento Specifica il nome di una variabile il cui valore contiene il nome esatto della chiave che creare, recuperare o eliminare. N/D Obbligatorio se non viene specificato alcun valore letterale tra l'apertura e tag di chiusura.

&lt;Put&gt; elemento

Scrive una coppia chiave/valore in una KVM. Se la KVM specificata nell'attributo mapIdentifier nella sezione l'elemento principale non esiste e se l'elemento <MapName> non viene utilizzato, la mappa viene creata automaticamente. Se il valore-chiave mappa già esistente, viene aggiunta la chiave-valore.

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

<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

Attributi

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

Attributo Descrizione Predefinito Presenza
eseguire l'override

Se impostato su true, sostituisce il valore di una chiave.

<Put override="false"> scriverà solo se non sono presenti attualmente persistente nell'archivio KVM per quella chiave.

true Facoltativo

<Scope> elemento

Definisce il limite di accessibilità per le KVM. L'ambito predefinito è environment, vale a dire che, per impostazione predefinita, le voci di Maps sono condivise da tutti i proxy API in esecuzione in un ambiente (ad es. test o prod). Se imposti l'ambito su apiproxy, le voci nel campo Le 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 di mappa, devi specificare lo stesso valore di ambito utilizzato quando è stata creata la mappa. Ad esempio, se la mappa è stata creata con un ambito apiproxy, devi utilizzare l'ambito apiproxy quando recuperi i relativi valori, l'inserimento 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)

&lt;Value&gt; elemento

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 una suddivisione in più parti valore. I valori vengono combinati in fase di esecuzione.

Nell'esempio seguente, vengono aggiunte due chiavi alla 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 l'organizzazione il nome è foo_org, il nome del proxy API è bar e l'ambiente è 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 per iniziare. N/D Obbligatorio se non viene specificato alcun valore letterale tra l'apertura e tag di 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 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.

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.

Schemi

Note sull'utilizzo

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

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

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 qualsiasi 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 memorizzata come voce in una chiave mappa dei valori. Una KVM può archiviare molte voci.

Ad esempio, supponi di dover archiviare un elenco di indirizzi IP associati a vari backend ambienti cloud-native. Potresti creare una KVM denominata ipAddresses che contiene un 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 utilizzabili dai criteri in fase di runtime, per applicare la lista consentita/denylisting degli IP, per selezionare in modo dinamico una destinazione del backend un indirizzo IP e così via. Tipicamente, 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 per Ad esempio, carica set di dati di grandi dimensioni nell'archivio chiavi-valore oppure crea script per gestire le coppie chiave-valore. le voci della mappa. Dovrai creare una KVM con l'API prima di accedervi con la criterio KeyValueMapOperations.

Specifica e recupera i nomi delle chiavi

Con gli elementi <Parameter> e <Value>, puoi specifica un valore letterale (dove il valore è compreso tra i tag di apertura e chiusura) oppure usa 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 e 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 di KEY_NAME_LITERAL viene archiviato nella KVM come chiave . Nella seconda istanza, qualsiasi valore presente nel key.name.variable diventa il nome della chiave nella KVM. Ad esempio, se key.name.variable conteneva i foo, la chiave verrà denominata foo.

Per recuperare la chiave e un valore della chiave con un'operazione GET (o da rimuovere con un DELETE), il valore dell'elemento <Parameter> deve corrispondere alla chiave nella KVM. Ad esempio, se il nome della chiave nella KVM è my_key, puoi specifica il valore letterale con <Parameter>my_key</Parameter> o specifica contenente il valore esatto mny_key, come segue: <Parameter ref="variable.containing.foo"/>.

Argomenti correlati

Per ulteriori informazioni sulle KVM, consulta i seguenti argomenti: