KeyValueMapOperations-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Symbol "Key Value Map Operations" über die Apigee-Benutzeroberfläche

Was

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

Diese Richtlinie ist eine erweiterbare Richtlinie, deren Verwendung je nach Apigee-Lizenz Auswirkungen auf die Kosten oder die Nutzung haben kann. Informationen zu Richtlinientypen und Auswirkungen auf die Nutzung finden Sie unter Richtlinientypen.

Video: Das folgende Video bietet eine allgemeine Einführung in KVMs.

Beispiele

KVM mit einem Literal setzen

Wenn die folgende Richtlinie ausgeführt wird, wird eine verschlüsselte KVM mit dem Namen FooKVM erstellt. Dann wird ein Schlüssel namens FooKey_1 mit zwei Werten erstellt, die mit Literalstrings foo und bar festgelegt werden (nicht festgelegt, wenn Werte aus Variablen extrahiert werden). Wenn Sie den Schlüssel GET im nächsten Beispiel abrufen, geben Sie eine Indexnummer an, um den gewünschten Wert abzurufen.

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

Der Bereich ist environment. Das bedeutet, dass Sie die KVM in der Verwaltungsoberfläche unter APIs > Umgebungskonfiguration > Schlüssel/Wert-Paar-Zuordnungen sehen können. Die auf dieser Seite angezeigten KVMs sind alle auf die ausgewählte Umgebung beschränkt.

KVM aus einem Literal abrufen

Diese Richtlinie behandelt die FooKVM-Zuordnung aus dem vorherigen Beispiel und holt den zweiten Wert (index="2") aus dem FooKey_1-Schlüssel und speichert ihn in einer Variablen namens foo_variable, um die Option zu aktivieren. 

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

Auf eine KVM dynamisch zugreifen

Diese Richtlinie verwendet das Element <MapName>, um mit einer Ablaufvariablen dynamisch auf eine KVM zu verweisen. Das Element erhält die KVM-Kennung aus der Ablaufvariable. Das Attribut mapIdentifier wird nicht angegeben. Sie können <MapName> nicht mit dem Attribut mapIdentifier verwenden.

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

KVM mit einer Variablen setzen

Ein einfaches Beispiel für eine praktische KVM ist ein URL-Kürzungsdienst. Die KVM könnte so konfiguriert werden, dass gekürzte URLs zusammen mit den entsprechenden vollständigen URLs gespeichert werden.

In diesem Beispielbeispiel wird eine KVM erstellt. Die Richtlinie verwendet den Befehl PUT, um einen Schlüssel mit zwei verknüpften Werten in einer KVM mit dem Namen urlMapper zu platzieren.

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

Der Schlüssel in diesem Beispiel, urlencoding.requesturl.hashed, ist ein Beispiel für eine benutzerdefinierte Variable. Die gehashte Anfrage-URL wird dann nach Code (z. B. JavaScript oder Java) generiert und in dieser Variablen gespeichert. Danach kann über die Richtlinie "KeyValueMapOperations" darauf zugegriffen werden.

Für jeden Schlüssel, requesturl.hashed, werden zwei Werte gespeichert:

  • Inhalt der benutzerdefinierten Variablen mit dem Namen urlencoding.longurl.encoded
  • Der Inhalt der vordefinierten Variable request.queryparam.url

Wenn die Richtlinie zur Laufzeit ausgeführt wird, können die Variablen beispielsweise so aussehen:

  • urlencoding.requesturl.hashed: ed24e12820f2f900ae383b7cc4f2b31c402db1be
  • urlencoding.longurl.encoded: http://tinyurl.com/38lwmlr
  • request.queryparam.url: http://apigee.com

Die folgende KVM und der folgende Eintrag werden im Schlüssel/Wert-Speicher von Apigee generiert und dem API-Proxy zugeordnet, dem die Richtlinie zugeordnet ist:

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

Der Eintrag bleibt bestehen, bis er gelöscht wird. Schlüssel/Wert-Paar-Speichereinträge werden auf Instanzen von Apigee verteilt, die die Cloud ausführen.

KVM aus einer Variablen abrufen

Ein einfaches Beispiel für eine praktische KVM ist ein URL-Kürzungsdienst. Die KVM könnte so konfiguriert werden, dass gekürzte URLs zusammen mit den entsprechenden vollständigen URLs gespeichert werden.

Wenn Sie den Wert des KVM-Eintrags abrufen möchten, z. B. den Eintrag, der auf dem Tab „KeyValueMapOperations“ PUT behandelt wird, konfigurieren Sie eine Richtlinie für GET der KVM:

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

Wenn diese Richtlinie ausgeführt wird und der Wert der Variable urlencoding.requesturl.hashed ed24e12820f2f900ae383b7cc4f2b31c402db1be lautet, wird die benutzerdefinierte Variable namens urlencoding.shorturl mit dem Wert http://tinyurl.com/38lwmlr eingestellt.

Nachdem die Daten abgerufen wurden, können weitere Richtlinien und Code auf die Daten zugreifen, indem sie den Wert aus diesen Variablen extrahieren.

Wert von KVM abrufen

Verwenden Sie das Attribut private. mit allen Variablen, wenn Sie mit dem Befehl GET auf eine KVM zugreifen, um die KVM-Informationen in einer Debug-Sitzung auszublenden. Wenn das Attribut private. nicht verwendet wird, ist die KVM weiterhin verschlüsselt. Allerdings werden die KVM-Informationen in der Debug-Sitzung entschlüsselt und es wird keine Ausnahme ausgelöst.

In diesem Beispiel enthält die Variable private.encryptedVar den entschlüsselten Wert des foo-Schlüssels der KVM.

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

Nachdem die Daten abgerufen wurden, können andere Richtlinien und Code auf sie zugreifen, indem sie den Wert aus dieser Variablen extrahieren.

<KeyValueMapOperations>

Bietet richtlinienbasierten Zugriff auf eine Schlüssel/Wert-Zuordnung (KVM).

Syntax

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

Attribute <KeyValueMapOperations>

Das folgende Beispiel zeigt die Attribute des Elements <KeyValueMapOperations>:

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

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

Attribut Beschreibung Standard Presence
mapIdentifier

Gibt eine Kennung an, über die der Richtlinie mitgeteilt wird, auf welche KVM sie zugreifen soll.

Wenn sowohl diese Kennung als auch <MapName> fehlen, wird eine KVM mit dem Namen kvmap verwendet. Sie können dieses Attribut nicht verwenden, wenn Sie das Element <MapName> angeben.

 – Optional

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

Attribut Beschreibung Standard Presence
name

Der interne Name der Richtlinie. Der Wert des Attributs name kann Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche und Punkte enthalten. Dieser Wert darf 255 Zeichen nicht überschreiten.

Optional können Sie das Element <DisplayName> verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

 – Erforderlich
continueOnError

Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten.

Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird. Siehe auch:

 false Optional
enabled

Setzen Sie den Wert auf true, um die Richtlinie zu erzwingen.

Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht erzwungen, selbst wenn sie mit einem Ablauf verknüpft ist.

 true Optional
async

Dieses Attribut wurde verworfen.

 false Verworfen

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

–

Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs name der Richtlinie verwendet.
Presence Optional
Typ String

Untergeordnete Elemente

In diesem Abschnitt werden die Elemente und Attribute der KeyValueMapOperations-Richtlinie beschrieben:

<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 im Stammelement oder mit dem Element <MapName> angeben. Beispiel:

<Delete>
   <Key>
      <Parameter>KEY_NAME_LITERAL</Parameter>
   </Key>
</Delete>
Standard –
Presence Erforderlich, wenn <Get> oder <Put> nicht vorhanden sind.
Typ –

<Entry>-Element

Seed-Werte für KVMs, die bei der Initialisierung in der KVM ausgefüllt werden. Bei Apigee ist die Schlüsselgröße auf 2 KB begrenzt.

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>
Standard –
Presence Optional
Typ –

<ExcludeCache>-Element

Verworfen. Verwenden Sie stattdessen das Element <Scope>.

<ExpiryTimeInSecs>-Element

Gibt die Dauer in Sekunden an, nach der Apigee seinen im Cache gespeicherten Wert von 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>
Standard 300 (5 Minuten)
Presence Optional
Typ Ganzzahl

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. Apigee bietet einen integrierten Mechanismus zum Zwischenspeichern von KVM-Schlüsseln und-Werten im Speicher während der Laufzeit, um die Leistung zu verbessern. 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 jedoch einige Unterschiede zwischen den Auswirkungen von GET- und PUT-Vorgängen auf den Cache-Ablauf.

GET - Bei der erstmaligen Ausführung eines KVM-GET-Vorgangs werden die angeforderten Schlüssel/Werte von der KVM (ihr Name muss im Stammattribut mapIdentifier der Richtlinie oder im <MapName>-Element angegeben sein) in den Cache geladen, wo sie für nachfolgende GET-Vorgänge verbleiben, 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: Eine PUT-Operation 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 <ExpiryTimeInSecs>-Element der Richtlinie, um die Option zu aktivieren. Bei Verwendung von PUT wird der Cache jedoch nur auf dem einzelnen Laufzeitknoten aktualisiert, der die Anfrage verarbeitet. Wenn Sie den Cache in jedem verteilten Laufzeitknoten aktualisieren möchten, verwenden Sie das Element <ExpiryTimeInSecs>, um Aktualisierungsintervalle für jeden Knoten anzugeben.

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 Richtlinie GET noch einmal ausgeführt und ruft 10 aus dem Cache ab.
  3. 5 Sekunden später aktualisiert eine PUT-Richtlinie den Wert von rating auf 10 und die <ExpiryTimeInSecs> in der Richtlinie PUT ist 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 ein anderer GET 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.

Apigee verschlüsselt alle in der KVM gespeicherten Daten. Weitere Informationen finden Sie unter Verschlüsselungsschlüssel. Wenn Sie <Get> verwenden, entschlüsselt Apigee die gespeicherten Daten und weist sie einer Variablen im Nachrichtenkontext zu. Der Variablenname wird mit dem Attribut assignTo angegeben.

Geben Sie den Namen der KVM entweder mit dem Attribut mapIdentifier im Stammelement oder mit dem Element <MapName> an.

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

Standard –
Presence Erforderlich, wenn <Put> oder <Delete> nicht vorhanden sind.
Typ –

Attribute

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

Attribut Beschreibung Standard Presence
assignTo

Die Variable, der der abgerufene Wert zugewiesen werden soll.

 – Erforderlich
index

Die Indexnummer (in einem 1-basierten Index) des Elements, die von einem Schlüssel mit mehreren Werten abgerufen werden soll. Wenn Sie beispielsweise index=1 angeben, wird der erste Wert zurückgegeben und der Variable assignTo zugewiesen. Wenn kein Indexwert angegeben ist, werden alle Werte dieses Eintrags der Variable als java.util.List zugewiesen.

Ein Beispiel finden Sie auf dem Tab Wert von KVM abrufen in Beispiele.

 – Optional

Einzelnes Element von einem KVM abrufen

Bei dieser Beispielschrittkonfiguration liest und entschlüsselt die Richtlinie den Wert eines einzelnen Schlüssels in der KVM und weist den entschlüsselten Wert einer Variablen mit dem Namen myvar zu. 

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

Abgerufene Daten aus Sitzungen zur Fehlerbehebung ausschließen

In einigen Fällen sind die in der KVM gespeicherten Daten sensibel. Wenn Sie verhindern möchten, dass die abgerufenen Daten in einer Fehlerbehebungssitzung angezeigt werden, verwenden Sie das Präfix private. im Variablennamen, der im Attribut assignTo angegebenen wird. Wenn Sie das Präfix private. nicht verwenden, werden die von der KVM abgerufenen Daten in jeder von Ihnen erstellten Debug-Sitzung als Klartext angezeigt.

Bei dieser Beispielschrittkonfiguration liest und entschlüsselt die Richtlinie den Wert, der einem einzelnen Schlüssel in der KVM zugewiesen ist, und weist diesen Wert einer Variablen zu. Die Zuweisung wird in einer Debug-Sitzung nicht angezeigt.

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

Schlüssel Wert
top_movies Die Braut des Prinzen,Der Pate,Citizen Kane
Citizen Kane Orson Welles
Die Braut des Prinzen Rob Reiner
Der Pate Francis Ford Coppola

Sie sehen, dass der mit dem Schlüssel top_movies verknüpfte Wert mehrere durch Kommas getrennte Filmnamen enthält.

Bei dieser Beispielkonfiguration ruft die Richtlinie den aktuellen Top-Film und den Namen des Regisseurs ab:

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

Beim Aufruf des API-Proxys erstellt Apigee die folgenden Variablen mit entsprechenden Werten, die später im API-Proxy-Ablauf verwendet werden können:

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

Der Wert für top.movie.pick ist nur das erste Element in der kommagetrennten Liste, da für das erste <Get>-Element das index-Attribut „1“ verwendet wird. Dann verwendet das zweite <Get>-Element den top.movie.pick zugewiesenen Wert als Schlüssel zum Abrufen eines Werts in movie.director.

<InitialEntries>-Element

Seed-Werte für KVMs, die bei der Initialisierung in der KVM ausgefüllt werden. Achten Sie darauf, dass Sie den Namen der KVM mit dem Attribut mapIdentifier für das Stammelement angeben.

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 die Richtlinie in der Apigee-Benutzeroberfläche in einer bereitgestellten Version des API-Proxys speichern oder das API-Proxy-Bundle bereitstellen, das die Richtlinie mit diesem Element enthält, werden die Schlüssel automatisch in der KVM erstellt. Wenn sich die Werte in der Richtlinie von denen in der KVM unterscheiden, werden die Werte in der KVM bei der Bereitstellung des API-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 auf 2 KB begrenzt.

Standard –
Presence Optional
Typ –

<Key>-Element

Gibt den Schlüssel in einem KVM-Eintrag an. Dieses Element wird als untergeordnetes Element von <Get>, <Put> oder <Delete> angezeigt oder als untergeordnetes Element des <Entry>-Elements angezeigt, das ein untergeordnetes Element von <InitialEntries> ist. Hier ein Beispiel für einen festen Schlüssel:

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

Ein Schlüssel kann mit dynamischen Elementen zusammengesetzt werden. Dies bedeutet, dass mehrere <Parameter> angehängt werden können, um den Schlüssel zu erstellen. Beispielsweise können die Inhalte der Variablen userID und role kombiniert werden, um einen dynamischen Schlüssel zu erstellen. Hier sehen Sie eine Beispielschrittkonfiguration, in der ein zusammengesetzter, dynamisch bestimmter Schlüssel angegeben wird:

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

Informationen zum Festlegen des Schlüsselnamens finden Sie unter dem Element <Parameter>.

Die Schlüsselgröße ist auf 2 KB begrenzt.

Standard –
Presence Optional
Typ –

<MapName>-Element

Mit dem <MapName>-Element kann die Richtlinie festlegen, welche KVM zur Laufzeit dynamisch verwendet werden soll. Die Möglichkeit, KVMs dynamisch auszuwählen, bietet Ihnen die Flexibilität, eine KeyValueMapOperations-Richtlinie zu entwerfen, die je nach Kontext, in dem die Richtlinie ausgeführt wird, auf verschiedene KVMs zugreifen kann.

Einige Beispiele:

<!-- use one of the following forms -->

<MapName>literal_string</MapName>

<MapName ref="flow.variable"></MapName>

<MapName ref="flow.variable">literal_string</MapName>

Die erste Zeile gibt den KVM-Namen als Literalstring an. Die zweite Zeile erhält den Namen aus einer Ablaufvariablen. Wenn in der dritten Zeile die Ablaufvariable zu einem leeren Wert aufgelöst wird, wird stattdessen der Literalstring verwendet.

Geben Sie das Attribut mapIdentifier nicht an, wenn Sie in Ihrer Richtlinie <MapName> verwenden. Weitere Informationen finden Sie unter Richtlinienattribute.

Wenn die Zuordnung bei der Bereitstellung des Proxys nicht vorhanden ist, wird die Zuordnung nicht erstellt und Apigee gibt bei Ausführung der Richtlinie einen Laufzeitfehler aus. Wenn die Ablaufvariable angegeben wird, ist das Element <InitialEntries> nicht zulässig. Während der Bereitstellung erhalten Sie einen Validierungsfehler.

Element <Parameter>

Gibt eine Komponente eines Schlüssels in einem Schlüssel/Wert-Paar an. Mit diesem Element wird der Name beim Erstellen, Aktualisieren, 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 <Key>-Element mehrere <Parameter>-Elemente enthält, ist der effektive Schlüsselstring die Verkettung der Werte aller Parameter, die durch einen doppelten Unterstrich verbunden sind. Wenn beispielsweise im obigen Beispiel die Variable apiproxy.name den Wert abc1 enthält, ist der effektive Schlüssel 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 des Schlüssels in der KVM übereinstimmen. Weitere Informationen finden Sie unter Schlüsselnamen angeben.

Standard –
Presence Erforderlich
Typ String

Attribute

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

Attribut Beschreibung Standard Presence
ref Gibt den Namen einer Variablen an, deren Wert den genauen Namen des Schlüssels enthält, den Sie erstellen, abrufen oder löschen möchten. – Erforderlich, wenn zwischen dem öffnenden und dem schließenden Tag kein Literalwert angegeben ist.

<Put>-Element

Schreibt ein Schlüssel/Wert-Paar in eine KVM. Wenn die im Attribut mapIdentifier im Stammelement angegebene KVM nicht vorhanden ist und das Element <MapName> nicht verwendet wird, wird die Zuordnung automatisch (als nicht verschlüsselt) erstellt. Wenn die Schlüssel/Wert-Zuordnung bereits vorhanden ist, wird ihr das Schlüssel/Wert-Paar hinzugefügt.

Informationen zum Erstellen einer KVM über die Benutzeroberfläche oder API finden Sie unter:

<Put override="false">
  <Key>
    <Parameter ref="mykeyvar"/>
  </Key>
  <Value ref="myvalvar1"/>
</Put>
Standard –
Presence Erforderlich, wenn <Get> oder <Delete> nicht vorhanden sind.
Typ –

Attribute

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

Attribut Beschreibung Standard Presence
Überschreiben

Bei der Einstellung true wird der Wert für einen Schlüssel überschrieben.

<Put override="false"> schreibt nur dann, wenn im KVM-Speicher für diesen Schlüssel derzeit kein Eintrag vorhanden ist.

true Optional

<Scope>-Element

Definiert die Barrierefreiheit für KVMs. Der Standardbereich ist environment. Das bedeutet, dass Zuordnungseinträ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 KVM nur für den 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>
Standard environment
Presence Optional
Typ String
Zulässige Werte
  • organization
  • environment
  • apiproxy
  • policy (API Proxy-Revision)

<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>
Standard –
Presence Erforderlich
Typ String

Attribute

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

Attribut Beschreibung Standard Presence
ref Gibt den Namen einer Variable an, deren Wert die Schlüsselwerte enthält, die Sie festlegen möchten. – Erforderlich, wenn zwischen dem öffnenden und dem schließenden Tag kein Literalwert angegeben ist. Nicht zulässig, wenn ein Literalwert angegeben wird.

Fehlerreferenz

In diesem Abschnitt werden die zurückgegebenen Fehlercodes und Fehlermeldungen beschrieben, die von Apigee festgelegt werden, wenn die Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Behebung 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.

Fehlercode HTTP-Status Ursache Diverse Fehlerkorrekturen
steps.keyvaluemapoperations.UnsupportedOperationException 500

Dieser Fehler tritt auf, wenn das mapIdentifier-Attribut auf einen leeren String in derKeyValueMapOperations-Richtlinie festgelegt ist.

Bereitstellungsfehler

Diese Fehler können auftreten, wenn Sie einen Proxy mit dieser Richtlinie bereitstellen.

Fehlername Ursache Diverse Fehlerkorrekturen
InvalidIndex Wenn das im Element <Get> der KeyValueMapOperations-Richtlinie angegebene Attribut index null oder eine negative Zahl ist, schlägt die Bereitstellung des API-Proxys fehl. Der Index beginnt bei 1, sodass ein Index mit null oder einer negativen Ganzzahl als ungültig angesehen wird.
KeyIsMissing Dieser Fehler tritt auf, wenn das <Key>-Element komplett fehlt oder das <Parameter>-Element im <Key>-Element unterhalb des <Entry> des <InitialEntries>-Elements der KeyValueMapOperations-Richtlinie fehlt.
ValueIsMissing Dieser Fehler tritt auf, wenn das Element <Value> unter dem Element <Entry> des Elements <InitialEntries> der KeyValueMapOperations-Richtlinie fehlt.

Schemas

Verwendungshinweise

Eine Übersicht über KVMs finden Sie unter Schlüssel/Wert-Zuordnungen verwenden.

Mit der Apigee-UI können Sie KVMs nur im Umgebungsbereich definieren, wie unter KVMs mit der Apigee-UI verwenden beschrieben. Mit der Apigee API können Sie KVMs auf Organisations-, Umgebungs- oder API-Proxy-Ebene definieren, wie in den folgenden Abschnitten beschrieben:

Ein KVM-Speicher bietet einen unkomplizierten 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. Eine KVM kann viele Einträge speichern.

Angenommen, Sie müssen eine Liste von IP-Adressen speichern, die mit verschiedenen Back-End-Umgebungen verknüpft sind. Sie können eine KVM mit dem Namen 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, die von Richtlinien zur Laufzeit verwendet werden können, um z. B. IP allowlisting/denylisting zu erzwingen, 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.

KVMs können über die Richtlinie „KeyValueMapOperations“ oder direkt über die Apigee API bearbeitet werden. 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 KVM 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) angeben oder das ref-Attribut verwenden, um den Namen einer Variablen anzugeben, deren Wert zur Laufzeit verwendet werden soll.

Das <Parameter>-Element hat eine besondere Erwähnung verdient, 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 entfernen) möchten, muss der Wert des <Parameter>-Elements mit dem Schlüsselnamen in der KVM übereinstimmen. Wenn der Schlüsselname in der KVM beispielsweise my_key ist, können Sie entweder den Literalwert mit <Parameter>my_key</Parameter> angeben oder eine Variable angeben, die den genauen Wert mny_key enthält, zum Beispiel <Parameter ref="variable.containing.foo"/>.

Weitere Informationen

Weitere Informationen zu KVMs finden Sie unter den folgenden Themen: