Norme relative a KeyValueMapOperations

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Cosa

Fornisce l'accesso basato su policy a un archivio di mappe chiave-valore (KVM) disponibile in Apigee Edge. 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. (Almeno una di queste operazioni deve essere eseguita dalla policy.)

Video

Guarda i seguenti video per saperne di più sui 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 all'elemento descrive gli elementi e gli attributi del criterio KeyValueMapOperations:

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

Attributi <KeyValueMapOperations>

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

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

La tabella seguente descrive gli attributi specifici del tag <KeyValueMapOperations>:

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

&lt;DisplayName&gt; 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>

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 della KVM con l'attributo mapIdentifier nell'elemento principale. Ad esempio:

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

Elemento <Entry>

Valori iniziali per le mappe chiave-valore, che vengono inseriti nella mappa chiave-valore quando viene inizializzata.

Per Edge for Public Cloud, 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>

Elemento <ExclusiveCache>

Deprecato. Utilizza invece l'elemento <Scope>.

Elemento <ExpiryTimeInSecs>

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 comporta l'utilizzo del valore predefinito di 300 secondi. Ad esempio:

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

Un 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ò potenzialmente rallentare le prestazioni del proxy. Per migliorare le prestazioni, Edge dispone di un meccanismo integrato per memorizzare nella cache le chiavi/i valori KVM in memoria durante l'esecuzione. Questo criterio KVM Operations 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 GET KVM, le chiavi/i valori richiesti dalla KVM (il cui nome è specificato nell'attributo mapIdentifier della radice della policy) vengono caricati nella cache, dove rimangono per le successive operazioni GET finché non si verifica una delle seguenti condizioni:

• 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 l'operazione 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.

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, la policy GET viene eseguita di nuovo e recupera "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 il PUT non fosse avvenuto, la cache originariamente 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".

Elemento <Get>

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

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

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

Ottenere un singolo elemento da un KVM

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

Ecco una configurazione dei criteri KVM che possiamo utilizzare per recuperare 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, Edge crea le seguenti variabili che puoi utilizzare nel flusso del proxy API:

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

Attributi

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

<Get assignTo="private.myvar">

Elemento <InitialEntries>

Valori iniziali per le mappe chiave-valore, che vengono inseriti nella mappa chiave-valore quando viene inizializzata. Assicurati di specificare il nome della KVM con l'attributo mapIdentifier sull'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 nell'interfaccia utente di gestione in una versione di cui è stato eseguito il deployment del proxy o esegui il deployment del bundle del proxy API contenente il criterio con questo elemento, le chiavi vengono create automaticamente nel KVM (senza crittografia). Se i valori nel criterio sono diversi dai valori nel KVM, questi ultimi vengono sovrascritti quando viene eseguito il deployment del proxy. 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 sia per Edge for the Public Cloud sia per Edge for the Private Cloud. Il valore KVM è limitato a 2 kB.

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

Elemento <Key>

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

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

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

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

Elemento <Parameter>

Specifica la chiave in una coppia chiave/valore. Questo elemento specifica il nome durante la creazione, l'inserimento, 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 alle variabili

  <Key>
    <Parameter>targeturl</Parameter>
    <Parameter ref="apiproxy.name"/>
    <Parameter>weight</Parameter>
  </Key>

Quando l'elemento Key include più elementi Parameter, la stringa della chiave 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 nella mappa di coppie chiave-valore. Per le linee guida, vedi Specifica e recupero dei nomi delle chiavi.

Attributi

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

Elemento <Put>

Scrive una coppia chiave/valore in una mappa di coppie chiave-valore, indipendentemente dal fatto che sia criptata o non criptata. Se la mappa delle coppie chiave-valore specificata nell'attributo mapIdentifier dell'elemento principale non esiste, viene creata automaticamente (senza crittografia). Se la mappa delle coppie chiave-valore esiste già, la chiave/il valore vengono aggiunti.

Per creare una mappa di coppie chiave-valore criptata, utilizza l'API di gestione delle mappe chiave/valore; oppure consulta la sezione Creazione e modifica delle mappe chiave-valore dell'ambiente per creare mappe chiave-valore criptate con ambito ambiente nell'interfaccia utente.

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

Attributi

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

Elemento <Scope>

Definisce il limite di accessibilità per le mappe chiave-valore. L'ambito predefinito è environment, il che significa che, per impostazione predefinita, le voci della mappa 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 mappa di coppie chiave-valore 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 elimini voci.

<Scope>environment</Scope>

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>

Attributi

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

Messaggi di errore

Gli errori restituiti dalle policy Edge seguono un formato coerente, come descritto in Riferimento ai codici 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 chiave-valore fornisce un meccanismo di persistenza leggero per i dati formattati come coppie chiave/valore. Puoi accedervi in fase di runtime tramite norme o codice. Una mappa contiene dati arbitrari nel formato key=value.

Ad esempio localhost=127.0.0.1, zip_code=94110 o first_name=felix. Nel primo esempio, localhost è una chiave e 127.0.0.1 è un valore. Ogni coppia chiave/valore viene archiviata come voce in una mappa chiave-valore. Una mappa di coppie chiave-valore può memorizzare molte voci.

Ecco un esempio di utilizzo delle mappe chiave-valore. Supponiamo di dover memorizzare un elenco di indirizzi IP associati a vari ambienti di backend. Potresti creare una mappa di coppie chiave-valore chiamata ipAddresses che contiene 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 in lista consentita o bloccata degli IP, per selezionare dinamicamente un indirizzo di destinazione 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.

Le mappe chiave/valore possono essere manipolate tramite il criterio KeyValueMapOperations o direttamente tramite l'API di gestione Apigee Edge. Per informazioni dettagliate sull'API Mappe chiave/valore dell'organizzazione, consulta il riferimento API di gestione. Puoi utilizzare l'API, ad esempio, per caricare set di dati di grandi dimensioni nel datastore chiave/valore o per creare script per gestire le voci della mappa chiave/valore. Prima di accedervi con il criterio KeyValueMapOperations, devi creare una mappa chiave/valore con l'API.

Specificare e recuperare i nomi delle chiavi

Con gli elementi <Parameter> e <Value>, puoi specificare un valore letterale (dove il valore è compreso 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".

Quando vuoi recuperare la chiave e un valore della chiave con un'operazione GET (o eliminare con un'operazione DELETE), l'impostazione <Parameter> deve corrispondere al nome della chiave nel KVM. Ad esempio, se il nome della chiave nel KVM è "foo", puoi specificare il valore letterale con <Parameter>foo</Parameter> o una variabile che contiene il valore esatto "foo", come in questo esempio: <Parameter ref="variable.containing.foo"/>.

Argomenti correlati

• API per le mappe chiave/valore dell'organizzazione