Criterio KeyValueMapOperations

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

Cosa

Fornisce l'accesso basato su criteri a un archivio Key Value Map (KVM) disponibile in Apigee Edge. Le coppie chiave/valore possono essere archiviate, recuperate ed eliminate dalle mappe esistenti denominate configurando Criteri KeyValueMapOperations che specificano le operazioni PUT, GET o DELETE. (Almeno uno dei operazioni devono essere eseguite dal criterio.

Video

Guarda i video riportati di seguito per scoprire di più sulle KVM.

Esempi

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

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

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

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

<KeyValueMapOperations name="getUrl" mapIdentifier="urlMapper">
   <Scope>apiproxy</Scope>
   <Get assignTo="urlencoding.shorturl" index='1'>
      <Key>
         <Parameter ref="urlencoding.requesturl.hashed"/> 
      </Key>
   </Get>
</KeyValueMapOperations>

<KeyValueMapOperations name="getEncrypted" mapIdentifier="encrypted_map">
   <Scope>apiproxy</Scope>
   <Get assignTo="private.encryptedVar" index='1'>
      <Key>
         <Parameter>foo</Parameter> 
      </Key>
   </Get>
</KeyValueMapOperations>

Riferimento elemento

Il riferimento agli elementi descrive gli elementi e gli attributi di KeyValueMapOperations norme:

<KeyValueMapOperations async="false" continueOnError="false" 
    enabled="true" name="Key-Value-Map-Operations-1" 
    mapIdentifier="urlMapper" >
   <DisplayName>Key Value Map Operations 1</DisplayName>
   <Scope>environment</Scope>
   <ExpiryTimeInSecs>300</ExpiryTimeInSecs>
   <InitialEntries>
      <Entry>
         <Key>
            <Parameter>key_name_literal</Parameter>
         </Key>
         <Value>value_literal</Value>
      </Entry>
      <Entry>
         <Key>
            <Parameter>variable_name</Parameter>
         </Key>
         <Value>value_1_literal</Value>
         <Value>value_2_literal</Value>
      </Entry>
   </InitialEntries>
   <Put override="false">
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value ref="variable_name"/>
   </Put>
   <Get assignTo="myvar" index="1">
      <Key>
         <Parameter ref="variable_name"/>
      </Key>
   </Get>
   <Delete>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
   </Delete>
</KeyValueMapOperations>

<KeyValueMapOperations> attributi

L'esempio seguente mostra gli attributi nel tag <KeyValueMapOperations>:

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

Nella tabella seguente vengono descritti gli attributi specifici del tag <KeyValueMapOperations>:

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali del criterio:

<DisplayName> elemento

Da utilizzare in aggiunta all'attributo name per etichettare il criterio in editor proxy della UI di gestione con un nome diverso e in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>

<Delete> 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. Ad esempio:

<Delete>
   <Key>
      <Parameter>key_name_literal</Parameter>
   </Key>
</Delete>

<Entry> elemento

I valori originale per le mappe chiave-valore, che vengono completati nella mappa chiave-valore quando è inizializzato.

Per Edge per il cloud pubblico, la dimensione della chiave è limitata a 2 kB. Ad esempio:

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>key_name_variable</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

<ExclusiveCache> elemento

Deprecato. Usa invece l'elemento <Scope>.

<ExpiryTimeInSecs> elemento

Specifica la durata in secondi dopo la quale Edge 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>

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 delle prestazioni, Edge è dotato 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 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 KVM, dalla KVM (il cui nome è specificato nella cartella principale mapIdentifier del criterio) ) vengono caricati nella cache, dove rimangono per le successive operazioni 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 nella KVM specificata. Se il comando 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>.

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. Dopo 30 secondi, il criterio GET viene eseguito di nuovo e recupera "10" dalla cache.
3. Dopo 5 secondi, un criterio PUT aggiorna il valore di "rating" a "8" e <ExpiryTimeInSecs> nel criterio PUT è 20. La cache viene immediatamente aggiornato con il nuovo valore, che ora è impostato per rimanere nella cache per 20 secondi. (Se il modello PUT se non fosse successo, la cache originariamente popolata dal primo GET esisterebbe ancora 30 secondi, restanti dai 60 secondi originali).
4. Dopo 15 secondi, viene eseguito un altro GET che recupera il valore "8".

<Get> elemento

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

Assicurati di specificare il nome della KVM con l'attributo mapIdentifier nella elemento principale.

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

Recuperare un singolo articolo da una KVM

<Get assignTo="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.

Ecco una configurazione dei criteri KVM che possiamo utilizzare per recuperare il film attualmente più popolare 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, Edge crea quanto segue che puoi utilizzare nel flusso proxy API:

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

Attributi

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

<Get assignTo="private.myvar">

<InitialEntries> elemento

Valori originali per le mappe chiave-valore, che vengono completati nella mappa chiave-valore 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 gestione su una versione di cui è stato eseguito il deployment del proxy o esegui il deployment del bundle proxy API contenente il criterio con questo elemento, le chiavi vengono creati automaticamente nella KVM (come non criptati). Se i valori nelle norme sono diversi rispetto a quelli nella KVM, questi vengono sovrascritti al momento del deployment del proxy. 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 sia per Edge per il cloud pubblico che Google Edge for the Private potrebbe. Il valore KVM è limitato a 2 kB.

Per creare una KVM criptata, utilizza l'API di gestione delle mappe chiave/valore.

<Key> elemento

Specifica la chiave in una voce della mappa chiave/valore. Una chiave può essere composita, il che significa che più di può essere aggiunto un parametro per creare la chiave. Ad esempio, userID e role potrebbe essere combinato per creare un key. Ad esempio:

<Key>
    <Parameter>key_name_literal</Parameter>
</Key>

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

Con Edge per il cloud pubblico, la dimensione della chiave è limitata a 2 kB. Per saperne di più, consulta Differenze tra l'API Edge for Public Cloud e l'API Private Cloud.

<Parameter> elemento

Specifica la chiave in una coppia chiave/valore. Questo elemento specifica il nome quando crea, inserisce 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 chiave include più elementi Parameter, la stringa chiave effettiva è 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 al valore nome della chiave nella mappa chiave-valore. Consulta la sezione Specificazione e recupero dei nomi delle chiavi per le linee guida.

Attributi

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

<Put> elemento

Scrive una coppia chiave/valore in una mappa chiave-valore, sia che quest'ultima sia criptata o non criptato. Se la mappa chiave-valore specificata nell'attributo mapIdentifier nella l'elemento principale non esiste, la mappa viene creata automaticamente (come non criptata). Se il valore-chiave mappa già esistente, viene aggiunta la chiave-valore.

Per creare una mappa chiave-valore criptata, utilizza l'API di gestione delle mappe chiave/valore; oppure consulta Creare e modificare le mappe chiave-valore degli ambienti per creare KVM criptate con ambito di ambiente nell'interfaccia utente.

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

Attributi

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

<Scope> elemento

Definisce il limite di accessibilità per le mappe chiave-valore. L'ambito predefinito è environment: per impostazione predefinita, le voci di Maps sono condivise da tutti i proxy API in esecuzione in un ambiente (ad esempio, test o prod). Se imposti l'ambito su apiproxy, le voci nella mappa chiave-valore sono accessibili solo dal proxy API che scrive i valori sulla 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>

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

Attributi

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

Messaggi di errore

Gli errori restituiti dai criteri di Edge seguono un formato coerente, come descritto nella pagina Riferimento al codice di errore.

Questa sezione descrive i codici e i messaggi di errore restituiti e le variabili di errore impostate da Edge quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

Errori di deployment

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

Schemi

Note sull'utilizzo

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

Un archivio di mappe dei valori chiave 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 mappa chiave-valore può memorizzare molte voci.

Di seguito è riportato un esempio di utilizzo delle mappe chiave-valore. Supponiamo di dover archiviare un elenco di indirizzi IP associati a vari backend ambienti cloud-native. Potresti creare una mappa chiave-valore denominata ipAddresses contenente una 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 o la lista bloccata 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.

Le mappe chiave/valore possono essere manipolate tramite il criterio KeyValueMapOperations o direttamente tramite API di gestione Apigee Edge. Per maggiori dettagli sull'API API Organization Key/value Maps, consulta il riferimento dell'API di gestione. Puoi utilizzare l'API per Ad esempio, caricare set di dati di grandi dimensioni nell'archivio chiave-valore o creare script per gestire le coppie chiave-valore. le voci della mappa. Dovrai creare una mappa chiave/valore 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" è archiviata sulla KVM come chiave nome. 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 viene denominata "foo".

Quando vuoi recuperare la chiave e il valore della chiave con un'operazione GET (o eliminarli con un operazione DELETE), il parametro <Parameter> deve corrispondere al nome della chiave nella KVM. Per Ad esempio, se il nome della chiave nella KVM è "foo", puoi specificare il valore letterale con <Parameter>foo</Parameter> o specifica una variabile contenente l'espressione esatta valore "foo", in questo modo: <Parameter ref="variable.containing.foo"/>.

Argomenti correlati

• API per le mappe chiave/valore dell'organizzazione