Diese Seite gilt für Apigee und Apigee Hybrid.
Apigee Edge-Dokumentation aufrufen
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 | Präsenz |
---|---|---|---|
mapIdentifier |
Gibt eine Kennung an, über die der Richtlinie mitgeteilt wird, auf welche KVM sie zugreifen soll. Wenn sowohl diese Kennung als auch |
– | Optional |
In der folgenden Tabelle werden Attribute beschrieben, die für alle übergeordneten Richtlinienelemente gelten:
Attribut | Beschreibung | Standard | Präsenz |
---|---|---|---|
name |
Der interne Name der Richtlinie. Der Wert des Attributs Optional können Sie das Element |
– | Erforderlich |
continueOnError |
Legen Sie Legen Sie |
falsch | Optional |
enabled |
Setzen Sie den Wert auf Legen Sie |
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 |
---|---|
Präsenz | 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 | – |
---|---|
Präsenz | 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 | – |
---|---|
Präsenz | 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) |
---|---|
Präsenz | 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
- 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. - 30 Sekunden später wird die Richtlinie
GET
noch einmal ausgeführt und ruft10
aus dem Cache ab. - 5 Sekunden später aktualisiert eine
PUT
-Richtlinie den Wert vonrating
auf10
und die<ExpiryTimeInSecs>
in der RichtliniePUT
ist 20. Der Cache wird sofort mit dem neuen Wert aktualisiert, der nun 20 Sekunden im Cache verbleibt. (OhnePUT
wäre der Cache, der ursprünglich mit der erstenGET
-Anfrage gefüllt wurde, 30 Sekunden lang weitere 30 Sekunden lang vorhanden.) - 15 Sekunden später wird ein anderer
GET
ausgeführt und ruft den Wert8
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 | – |
---|---|
Präsenz | Erforderlich, wenn <Put> oder <Delete> nicht vorhanden sind. |
Typ | – |
Attribute
In der folgenden Tabelle werden die Attribute des Elements <Get> beschrieben:
Attribut | Beschreibung | Standard | Präsenz |
---|---|---|---|
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 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 | – |
---|---|
Präsenz | 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 | – |
---|---|
Präsenz | 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 | – |
---|---|
Präsenz | Erforderlich |
Typ | String |
Attribute
In der folgenden Tabelle werden die Attribute des <Parameter>
-Elements beschrieben:
Attribut | Beschreibung | Standard | Präsenz |
---|---|---|---|
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:
- KVMs mit der Apigee-UI verwenden, um verschlüsselte KVMs in der Benutzeroberfläche zu erstellen
- Schlüssel/Wert-Paar-API auf Organisationsebene
- Umgebungsorientierte Schlüssel/Wert-Paar-API
- API-Proxy-API für Schlüssel/Wert-Paare zugeordnet
<Put override="false"> <Key> <Parameter ref="mykeyvar"/> </Key> <Value ref="myvalvar1"/> </Put>
Standard | – |
---|---|
Präsenz | Erforderlich, wenn <Get> oder <Delete> nicht vorhanden sind. |
Typ | – |
Attribute
In der folgenden Tabelle werden die Attribute des <Put>
-Elements beschrieben:
Attribut | Beschreibung | Standard | Präsenz |
---|---|---|---|
Überschreiben |
Bei der Einstellung
|
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 |
---|---|
Präsenz | Optional |
Typ | String |
Zulässige Werte |
|
<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 Wertenv1,v2
- Schlüssel
k2
mit den Wertenv3,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 Wertenbar,test
<Put> <Key> <Parameter ref="organization.name"/> </Key> <Value ref="apiproxy.name"/> <Value ref="environment.name"/> </Put>
Standard | – |
---|---|
Präsenz | Erforderlich |
Typ | String |
Attribute
In der folgenden Tabelle werden die Attribute des <Value>
-Elements beschrieben:
Attribut | Beschreibung | Standard | Präsenz |
---|---|---|---|
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 |
build |
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.
|
build |
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.
|
build |
ValueIsMissing |
Dieser Fehler tritt auf, wenn das Element <Value> unter dem Element <Entry> des Elements <InitialEntries> der KeyValueMapOperations -Richtlinie fehlt. |
build |
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:
- Schlüssel/Wert-Paar-API auf Organisationsebene
- Umgebungsorientierte Schlüssel/Wert-Paar-API
- API-Proxy-API für Schlüssel/Wert-Paare zugeordnet
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:
- Schlüssel/Wert-Paar-Zuordnungen verwenden
- Schlüssel/Wert-Paar-API auf Organisationsebene
- Umgebungsorientierte Schlüssel/Wert-Paar-API
- API-Proxy-API für Schlüssel/Wert-Paare zugeordnet