KeyValueMapOperations-Richtlinie

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation weitere Informationen

Was

Bietet richtlinienbasierten Zugriff auf einen KVM-Speicher (Key Value Map), der in Apigee Edge verfügbar ist. Schlüssel/Wert-Paare können in benannten vorhandenen Karten gespeichert, abgerufen und aus diesen gelöscht werden. Dazu konfigurieren Sie Richtlinien für KeyValueMapOperations, die PUT-, GET- oder DELETE-Vorgänge angeben. Mindestens einer dieser Vorgänge muss von der Richtlinie ausgeführt werden.

Videos

In den folgenden Videos erfahren Sie mehr über KVMs.

Beispiele

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

Elementverweis

Die Elementreferenz beschreibt die Elemente und Attribute der KeyValueMapOperations-Richtlinie:

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

Attribute <KeyValueMapOperations>

Das folgende Beispiel zeigt die Attribute für das Tag <KeyValueMapOperations>:

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

In der folgenden Tabelle werden die Attribute beschrieben, die für das Tag <KeyValueMapOperations> spezifisch sind:

In der folgenden Tabelle werden Attribute beschrieben, die für alle übergeordneten Richtlinienelemente gelten:

<DisplayName>-Element

Wird zusätzlich zum Attribut name verwendet, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

<DisplayName>Policy Display Name</DisplayName>

<Delete>-Element

Löscht das angegebene Schlüssel/Wert-Paar. Es muss in jedem Fall entweder <Get>, <Put> oder <Delete> verwendet werden.

Achten Sie darauf, dass Sie den Namen der KVM mit dem Attribut mapIdentifier für das übergeordnete Element angeben. Beispiel:

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

<Entry>-Element

Ausgangswerte für Schlüssel/Wert-Zuordnungen, die bei der Initialisierung in die Schlüssel/Wert-Zuordnung eingefügt werden.

Bei Edge for Public Cloud ist die Schlüsselgröße auf 2 KB beschränkt. Beispiel:

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

<ExcludeCache>-Element

Veraltet. Verwenden Sie stattdessen das Element <Scope>.

<ExpiryTimeInSecs>-Element

Gibt die Dauer in Sekunden an, nach der Edge seinen im Cache gespeicherten Wert aus der angegebenen KVM aktualisiert.

Ein Wert von 0 oder -1 oder das Ausschließen dieses Elements bedeutet, dass der Standardwert von 300 Sekunden verwendet wird. Beispiel:

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

Eine KVM ist ein langfristiger Persistenzmechanismus, der Schlüssel und Werte in einer NoSQL-Datenbank speichert. Aus diesem Grund kann das Lesen von einer KVM zur Laufzeit die Proxy-Leistung beeinträchtigen. Zur Verbesserung der Leistung hat Edge einen integrierten Mechanismus zum Caching von KVM-Schlüsseln/Werten während der Laufzeit im Arbeitsspeicher. Diese KVM-Betriebsrichtlinie liest für GET-Vorgänge immer aus dem Cache.

Mit dem Element <ExpiryTimeInSecs> können Sie steuern, wie lange die in der Richtlinie verwendeten Schlüssel/Wert-Paare im Cache gespeichert werden, bevor sie wieder von der KVM aktualisiert werden. Es gibt einige Unterschiede zwischen dem Ablauf von GET- und PUT-Vorgängen.

GET: Wenn ein KVM-GET-Vorgang zum ersten Mal ausgeführt wird, werden die angeforderten Schlüssel/Wert-Paare von der KVM (der im Namen der Richtlinie mapIdentifier im Stammverzeichnis der Richtlinie angegeben ist) in den Cache, wo sie für nachfolgende GET-Vorgänge verbleiben, geladen, bis eines der folgenden Ereignisse eintritt:

• Die in <ExpiryTimeInSecs> angegebene Anzahl von Sekunden läuft ab.
  oder
• Ein PUT-Vorgang in einer KVM-Richtlinie überschreibt die vorhandenen Werte (siehe Erläuterung).

PUT: Ein PUT-Vorgang schreibt Schlüssel/Werte in die angegebene KVM. Wenn PUT in einen Schlüssel schreibt, der bereits im Cache vorhanden ist, wird dieser Cache sofort aktualisiert und enthält den neuen Wert für die Anzahl von Sekunden im Element <ExpiryTimeInSecs> der Richtlinie.

Beispiel: KVM im Cache speichern

1. Ein GET-Vorgang ruft den Wert "rating" ab, wodurch der Wert "10" zum Cache hinzugefügt wird. Die <ExpiryTimeInSecs> für die Richtlinie ist 60.
2. 30 Sekunden später wird die GET-Richtlinie noch einmal ausgeführt und "10" aus dem Cache abgerufen.
3. 5 Sekunden später aktualisiert eine PUT-Richtlinie den Wert von "rating" auf "8" und der <ExpiryTimeInSecs> für die PUT-Richtlinie 20. Der Cache wird sofort mit dem neuen Wert aktualisiert, der nun 20 Sekunden im Cache verbleibt. Ohne PUT wäre der Cache, der ursprünglich mit der ersten GET-Anfrage gefüllt wurde, 30 Sekunden lang weitere 30 Sekunden lang vorhanden.
4. 15 Sekunden später wird eine andere GET-Anfrage ausgeführt und ruft den Wert "8" ab.

<Get>-Element

Ruft den Wert für den angegebenen Schlüssel ab. Es muss in jedem Fall entweder <Get>, <Put> oder <Delete> verwendet werden.

Achten Sie darauf, dass Sie den Namen der KVM mit dem Attribut mapIdentifier im übergeordneten Element angeben.

Sie können mehrere Get-Blöcke in die Richtlinie aufnehmen, um mehrere Elemente von einer KVM abzurufen.

Einzelnes Element von einem KVM abrufen

<Get assignTo="myvar" index="1">         
   <Key>             
      <Parameter>key_name_literal</Parameter>         
   </Key>     
</Get>

Mehrere Elemente von einer KVM abrufen

Im folgenden Beispiel wird davon ausgegangen, dass eine KVM mit den folgenden Schlüsseln und Werten vorhanden ist. Neben der Speicherung einer Liste mit den beliebtesten Filmen aller Zeiten speichert die KVM den Regisseurnamen für alle Hauptfilme.

Hier sehen Sie eine KVM-Richtlinienkonfiguration, mit der wir den aktuell beliebtesten Film und den Namen des Regisseurs abrufen können:

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

Wenn der API-Proxy aufgerufen wird, erstellt Edge die folgenden Variablen, die Sie im API-Proxy-Ablauf verwenden können:

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

Attribute

In der folgenden Tabelle werden die Attribute des <Get> -Elements beschrieben:

<Get assignTo="private.myvar">

<InitialEntries>-Element

Ausgangswerte für Schlüssel/Wert-Zuordnungen, die bei der Initialisierung in die Schlüssel/Wert-Zuordnung übertragen werden. Achten Sie darauf, dass Sie den Namen der KVM mit dem Attribut mapIdentifier für das übergeordnete Element angeben. Zum Beispiel:

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

Wenn Sie bei Verwendung dieses Elements die Richtlinie in der Verwaltungs-UI in einer bereitgestellten Version des Proxys speichern oder mit diesem Element das API-Proxy-Bundle bereitstellen, das die Richtlinie enthält, werden die Schlüssel automatisch in der KVM erstellt (als unverschlüsselt). Wenn sich die Werte in der Richtlinie von denen in der KVM unterscheiden, werden die Werte in der KVM bei der Bereitstellung des Proxys überschrieben. Alle neuen Schlüssel/Wert-Paare werden zusammen mit den vorhandenen Schlüssel/Wert-Paaren der vorhandenen KVM hinzugefügt.

Die durch dieses Element eingegebenen Schlüssel und Werte müssen Literale sein. Beispielsweise wird <Parameter ref="request.queryparam.key"> in diesem Element nicht unterstützt.

Die Schlüsselgröße ist sowohl für Edge für die öffentliche Cloud als auch für Edge für die private Cloud auf 2 KB beschränkt. Der KVM-Wert ist auf 2 KB beschränkt.

Verwenden Sie zum Erstellen einer verschlüsselten KVM die Key/Value Maps Management API.

<Key>-Element

Gibt den Schlüssel in einem Schlüssel/Wert-Zuordnungseintrag an. Ein Schlüssel kann zusammengesetzt werden, d. h. es können mehrere Parameter angehängt werden, um den Schlüssel zu erstellen. Beispielsweise können userID und role zu einem key kombiniert werden. Beispiel:

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

Weitere Informationen zum Festlegen des Schlüsselnamens finden Sie im Element <Parameter>.

Bei Edge for Public Cloud ist die Schlüsselgröße auf 2 KB beschränkt. Weitere Informationen finden Sie unter Unterschiede zwischen Edge for Public Cloud API und Private Cloud API.

<Parameter>-Element

Gibt den Schlüssel in einem Schlüssel/Wert-Paar an. Mit diesem Element wird der Name beim Erstellen, Einfügen, Abrufen oder Löschen des Schlüssel/Wert-Paars angegeben.

Sie können den Namen mit folgendem Befehl angeben:

• Ein Literalstring

  <Key>
    <Parameter>literal</Parameter>
  </Key>
  

• Eine Variable, die zur Laufzeit abgerufen werden soll, unter Verwendung des Attributs ref

  <Key>
    <Parameter ref="variable_name"/>
  </Key>
  

• Eine Kombination aus Literalen und Variablenreferenzen

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

Wenn das Schlüsselelement mehrere Parameterelemente enthält, ist der effektive Schlüsselstring die Verkettung der Werte aller Parameter, die durch einen doppelten Unterstrich verbunden sind. Wenn die Variable apiproxy.name im Beispiel oben den Wert "abc1" hat, ist der effektive Schlüssel beispielsweise targeturl__abc1__weight.

Unabhängig davon, ob Sie ein Schlüssel/Wert-Paar abrufen, aktualisieren oder löschen, muss der Schlüsselname mit dem Namen in der Schlüsselwertzuordnung übereinstimmen. Weitere Informationen finden Sie unter Schlüsselnamen angeben.

Attribute

In der folgenden Tabelle werden die Attribute des <Parameter> -Elements beschrieben:

<Put>-Element

Schreibt ein Schlüssel/Wert-Paar in eine Schlüssel/Wert-Zuordnung, unabhängig davon, ob die Schlüsselwertzuordnung verschlüsselt oder unverschlüsselt ist. Wenn die im Attribut mapIdentifier im übergeordneten Element angegebene Schlüssel/Wert-Zuordnung nicht vorhanden ist, wird die Zuordnung automatisch (als unverschlüsselt) erstellt. Wenn die Schlüssel/Wert-Zuordnung bereits vorhanden ist, wird ihr das Schlüssel/Wert-Paar hinzugefügt.

Verwenden Sie zum Erstellen einer verschlüsselten Schlüssel/Wert-Zuordnung die Key/Value Maps Management API. Informationen zum Erstellen von verschlüsselten umgebungsbezogenen KVMs in der Benutzeroberfläche finden Sie unter Schlüssel/Wert-Zuordnungen für die Umgebung erstellen und bearbeiten.

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

Attribute

In der folgenden Tabelle werden die Attribute des <Put> -Elements beschrieben:

<Scope>-Element

Definiert die Barrierefreiheit für Schlüsselwertzuordnungen. Der Standardbereich ist environment. Das bedeutet, dass Karteneinträge standardmäßig von allen API-Proxys geteilt werden, die in einer Umgebung ausgeführt werden (z. B. Test oder Produktion). Wenn Sie den Bereich auf apiproxy festlegen, sind Einträge in der Schlüssel/Wert-Zuordnung nur vom API-Proxy verfügbar, der die Werte in die Zuordnung schreibt.

Beim Zugriff auf eine Karte oder einen Karteneintrag müssen Sie denselben Bereichswert angeben, mit dem Sie die Karte erstellt haben. Beispiel: Wenn die Karte mit einem Bereich von apiproxy erstellt wurde, müssen Sie beim Abrufen von Werten den Bereich apiproxy verwenden, Änderungen vornehmen oder Einträge löschen.

<Scope>environment</Scope>

<Value>-Element

Gibt den Wert eines Schlüssels an. Sie können den Wert entweder als Literalstring oder mit dem Attribut ref als Variable angeben, die zur Laufzeit abgerufen werden soll:

<!-- Specify a literal value -->
<Value>literal<Value>

oder:

<!-- Specify the name of variable value to be populated at run time. -->
<Value ref="variable_name"/>

Sie können auch mehrere <Value>-Elemente einfügen, um einen mehrteiligen Wert anzugeben. Die Werte werden zur Laufzeit kombiniert.

Im folgenden Beispiel werden der KVM zwei Schlüssel hinzugefügt:

• Schlüssel k1 mit den Werten v1,v2
• Schlüssel k2 mit den Werten 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>

Im folgenden Beispiel wird ein Schlüssel mit zwei Werten erstellt. Angenommen, der Name der Organisation lautet foo_org, der API-Proxy-Name bar und die Umgebung test:

• Schlüssel foo_org mit den Werten bar,test

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

Attribute

In der folgenden Tabelle werden die Attribute des <Value> -Elements beschrieben:

Fehlerreferenz

Von Edge-Richtlinien zurückgegebene Fehler folgen einem einheitlichen Format, wie in der Fehlercode-Referenz beschrieben.

In diesem Abschnitt werden die Fehlercodes und Fehlermeldungen beschrieben, die zurückgegeben werden, sowie die Fehlervariablen, die von Edge festgelegt werden, wenn diese Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Verarbeitung von Fehlern entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.

Laufzeitfehler

Diese Fehler können bei Ausführung der Richtlinie auftreten.

Bereitstellungsfehler

Diese Fehler können auftreten, wenn Sie einen Proxy bereitstellen, der diese Richtlinie enthält.

Schemas

Hinweise zur Verwendung

Eine Übersicht über Schlüssel/Wert-Paare finden Sie unter Mit Schlüssel/Wert-Zuordnungen arbeiten.

Ein Schlüssel/Wert-Paarspeicher bietet einen einfachen Persistenzmechanismus für Daten, die als Schlüssel/Wert-Paare formatiert sind. Sie können zur Laufzeit über Richtlinien oder Code auf die Dateien zugreifen. Eine Zuordnung enthält beliebige Daten im Format key=value.

Beispiel: localhost=127.0.0.1, zip_code=94110 oder first_name=felix. Im ersten Beispiel ist localhost ein Schlüssel und 127.0.0.1 ein Wert. Jedes Schlüssel/Wert-Paar wird als Eintrag in einer Schlüssel/Wert-Zuordnung gespeichert. Mit einer Schlüssel/Wert-Zuordnung können viele Einträge gespeichert werden.

Hier ist ein Beispiel für die Verwendung von Schlüssel/Wert-Zuordnungen. Angenommen, Sie müssen eine Liste von IP-Adressen speichern, die mit verschiedenen Back-End-Umgebungen verknüpft sind. Sie können eine Schlüssel/Wert-Paar-Zuordnung ipAddresses erstellen, die eine Liste von Schlüssel/Wert-Paaren als Einträge enthält. Beispielsweise kann dieses JSON eine solche Karte darstellen:

{
  "entry" : [ {
    "name" : "Development",
    "value" : "65.87.18.18"
  }, {
    "name" : "Staging",
    "value" : "65.87.18.22"
  } ],
  "name" : "ipAddresses"
}

Sie können diese Struktur verwenden, um einen Speicher von IP-Adressen zu erstellen, der von Richtlinien zur Laufzeit verwendet werden kann, um das Erzwingen von IP-Zulassungs- oder Sperrlisten zu erzwingen, um eine Back-End-Zieladresse dynamisch auszuwählen usw. Die Richtlinie "KeyValueMapOperations" wird in der Regel verwendet, um langlebige Informationen zu speichern oder abzurufen, die über mehrere Anfrage-/Antworttransaktionen wiederverwendet werden müssen.

Schlüssel/Wert-Zuordnungen können über die Richtlinie „KeyValueMapOperations“ oder direkt über die Apigee Edge Management API bearbeitet werden. Weitere Informationen zur Organization Key/Value Maps API finden Sie in der Management API-Referenz. Sie können die API verwenden, um beispielsweise große Datensätze in den Schlüssel/Wert-Speicher hochzuladen oder Skripts zum Verwalten von Schlüssel/Wert-Zuordnungen zu erstellen. Sie müssen eine Schlüssel/Wert-Zuordnung mit der API erstellen, bevor Sie mit der Richtlinie "KeyValueMapOperations" darauf zugreifen können.

Schlüsselnamen festlegen und abrufen

Mit den Elementen <Parameter> und <Value> können Sie entweder einen Literalwert (d. h. zwischen dem öffnenden und dem schließenden Tag) oder das ref-Attribut angeben, um den Namen einer Variablen anzugeben, deren Wert zur Laufzeit verwendet werden soll.

Das Parameter-Element hat eine besondere Erwähnung, da es den Namen des erstellten Schlüssels sowie den Schlüsselnamen bestimmt, den Sie abrufen oder löschen möchten. Im Folgenden finden Sie zwei Beispiele: Das erste gibt einen Schlüsselnamen an, das zweite einen Schlüsselnamen mit einer Variablen. Gehen wir davon aus, dass zur Erstellung von Schlüsseln in einer KVM Folgendes verwendet wird:

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

In der ersten Instanz wird der Literalwert "key_name_literal" in der KVM als Schlüsselnamen gespeichert. In der zweiten Instanz wird jeder Wert in key.name.variable als Name des Schlüssels in der KVM. Wenn beispielsweise key.name.variable den Wert foo enthält, hat der Schlüssel den Namen "foo".

Wenn Sie den Schlüssel und einen Schlüsselwert mit einem GET-Vorgang abrufen (oder mit einem DELETE-Vorgang löschen möchten), muss die Einstellung <Parameter> mit dem Schlüsselnamen in der KVM übereinstimmen. Wenn der Schlüsselname in der KVM beispielsweise "foo" ist, können Sie entweder den Literalwert mit <Parameter>foo</Parameter> angeben oder eine Variable angeben, die den genauen Wert "foo" enthält, z. B.: <Parameter ref="variable.containing.foo"/>.

Weitere Informationen

• API für Organisations-Schlüssel/Wert-Paare