KeyValueMapOperations-Richtlinie

<ph type="x-smartling-placeholder"></ph> Sie sehen die Dokumentation zu Apigee Edge.
Gehen Sie zur Apigee X-Dokumentation.
Weitere Informationen

Symbol für Schlüsselwertzuordnungsoperationen auf der Edge-Benutzeroberfläche

Was

Bietet richtlinienbasierten Zugriff auf einen in Apigee Edge verfügbaren KVM-Speicher (Key Value Map). 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.

Video Beschreibung
Warum Zuordnung von Schlüssel/Wert-Paaren? Erfahren Sie, warum Sie KVMs benötigen und wie sie funktionieren.
KVM über die Benutzeroberfläche erstellen und KVM zur Laufzeit abrufen Erstellen Sie eine KVM, rufen Sie ihren Wert mit einer KVM-Richtlinie ab und fügen Sie den Wert mithilfe von Ablaufvariablen in die API-Anfrage ein.
KVM in der API-Laufzeit erstellen und aktualisieren Erstellen Sie eine KVM in der API-Laufzeit mithilfe einer KVM-Richtlinie.
Cache-KVM speichern, um die Leistung zu steigern Verbessern Sie die Leistung der KVM-Richtlinie, indem Sie die Daten im Cache speichern.
Verschlüsselte KVM speichern Speichern Sie vertrauliche Informationen in KVM in einem verschlüsselten Format und rufen Sie den Wert zur Laufzeit mithilfe der KVM-Richtlinie und privaten Variablen ab.
Zugriff mithilfe des KVM-Bereichs verwalten Beschränken Sie KVM auf Organisation, Umgebung, API-Proxy oder API-Proxy-Revision, indem Sie das KVM-Richtlinienbereichsattribut verwenden.
KVM-Einträge in der API-Laufzeit löschen Löschen Sie KVM-Einträge in der API-Laufzeit mithilfe des DELETE-Vorgangs der KVM-Richtlinie.

Beispiele

KVM mit einem Literal setzen

Wenn die folgende Richtlinie ausgeführt wird, wird eine verschlüsselte KVM mit dem Namen FooKVM und erstellt dann einen Schlüssel namens FooKey_1 mit zwei Werte mit den Literalstrings foo und bar (nicht bei Werten festgelegt, die aus Variablen extrahiert wurden). Wenn Sie GET ist der Schlüssel. Im nächsten Beispiel 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>

Beachten Sie, dass der Bereich "Umgebung" ist. 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>

KVM mit einer Variablen setzen

Ein einfaches Beispiel für eine nützliche Schlüsselwertzuordnung ist ein URL-Kürzungsdienst. Schlüssel/Wert-Zuordnung kann so konfiguriert werden, dass gekürzte URLs zusammen mit den entsprechenden vollständigen URLs gespeichert werden.

Mit diesem Beispielbeispiel wird eine Schlüssel/Wert-Paar-Zuordnung erstellt. Die Richtlinie stellt einen Schlüssel mit zwei verknüpften Werten in einer Schlüssel/Wert-Paar-Zuordnung namens "urlMapper" dar.

<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 Schlüssel/Wert-Zuordnung und der folgende Eintrag würden im Schlüssel/Wert-Speicher von Edge generiert und ist auf den API-Proxy beschränkt, an den die Richtlinie angehängt ist:

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

Der Eintrag bleibt bestehen, bis er gelöscht wird. Speichereinträge für Schlüssel/Wert-Paare sind Instanzen von Edge, die in der Cloud ausgeführt werden.

KVM aus einer Variablen abrufen

Ein einfaches Beispiel für eine nützliche Schlüssel/Wert-Zuordnung ist ein URL-Kürzungsdienst. Schlüssel/Wert-Zuordnung kann so konfiguriert werden, dass gekürzte URLs zusammen mit den entsprechenden vollständigen URLs gespeichert werden.

Wenn Sie den Wert des Schlüssel/Wert-Paareintrags abrufen möchten, z. B. den Eintrag auf dem Tab "KeyValueMapOperations PUT", konfigurieren Sie eine Richtlinie zum Abrufen der Schlüssel/Wert-Zuordnung:

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

Verschlüsselten Wert von KVM abrufen

Wenn eine Schlüssel/Wert-Zuordnung verschlüsselt ist, können Sie Werte mit dem Präfix "private." im Attributwert assignToabrufen. In diesem Beispiel enthält die Variable private.encryptedVar den entschlüsselten Wert des Schlüssels foo der Schlüssel/Wert-Zuordnung. Informationen zum Erstellen verschlüsselter Schlüssel/Wert-Zuordnungen finden Sie in der der Schlüssel/Wert-Zuordnungen Management API.

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


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:

Attribut Beschreibung Standard Präsenz
mapIdentifier

Gibt eine Kennung an, die beim Zugriff auf eine von diesem erstellte Karte verwendet werden soll. oder auf der Verwaltungsoberfläche.

Bei Apigee Edge for Public Cloud wird beim KVM-Namen die Groß-/Kleinschreibung beachtet. Beispielsweise unterscheidet sich foobar von FooBar.

Wenn Sie dieses Attribut ausschließen, wird eine KVM mit dem Namen kvmap verwendet.

Innerhalb des Bereichs von organization/environment/apiproxy können Sie das Attribut mapIdentifier verwenden, um Ihren eigenen Kartennamen anzugeben.

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

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 Veraltet

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

Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs name der Richtlinie verwendet.

Präsenz Optional
Typ String

<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>
Standardeinstellung
Präsenz Erforderlich, wenn <Get> oder <Put> nicht vorhanden sind.
Typ

<Entry>-Element

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

Bei Edge für öffentliche Cloud 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>
Standardeinstellung
Präsenz Optional
Typ

<ExcludeCache>-Element

Veraltet. Verwenden Sie stattdessen das Element <Scope>.

<ExpiryTimeInSecs>-Element

Gibt den Zeitraum in Sekunden an, nach dem Edge seinen zwischengespeicherten Wert aus dem angegebene KVM.

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>
Standardeinstellung 300 (5 Minuten)
Präsenz Optional
Typ Integer

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 hat Edge einen integrierten Mechanismus zum Caching von KVM-Schlüsseln/Werten im Arbeitsspeicher während der Laufzeit. 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.

Standardeinstellung
Präsenz Erforderlich, wenn <Put> oder <Delete> nicht vorhanden sind.
Typ

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.

Key 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

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

Attribut Beschreibung Standard Präsenz
assignTo

Die Variable, der der abgerufene Wert zugewiesen werden soll.

Wenn die Schlüssel/Wert-Zuordnung verschlüsselt ist, beginnen Sie den Namen "assignTo" mit "private.". Hier einige Beispiele:

<Get assignTo="private.myvar">

Die Richtlinie gibt einen Fehler aus, wenn Sie versuchen, eine verschlüsselte Schlüssel/Wert-Zuordnung ohne das Präfix abzurufen. Das Präfix, das für grundlegende Sicherheitszwecke während der Fehlerbehebung erforderlich ist, blendet die verschlüsselten Werte aus API-Proxy-Trace- und Debug-Sitzungen aus.

Informationen zum Erstellen verschlüsselter Schlüssel/Wert-Zuordnungen finden Sie in den Themen "create" der Key/Value Maps Management API und Erstellen und Bearbeiten von Umgebungsschlüsselwerten.

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 Beispiele im Abschnitt "Verschlüsselten Wert von KVM abrufen".

Optional

<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 dieses Element verwenden und die Richtlinie in der Verwaltungsoberfläche einer bereitgestellten Version speichern des Proxys oder stellen Sie das API-Proxy-Bundle bereit, das die Richtlinie mit diesem Element enthält, dem bzw. den Schlüssel(n). werden automatisch in der KVM erstellt (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 auf 2 KB sowohl für Edge für die öffentliche Cloud als auch für Edge for the Private Can. Der KVM-Wert ist auf 2 KB begrenzt.

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

Standard
Präsenz Optional
Typ

<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 für öffentliche Cloud ist die Schlüsselgröße auf 2 KB begrenzt. Weitere Informationen finden Sie unter Unterschiede zwischen Edge für die Public Cloud API und die Private Cloud API.

Standardeinstellung
Präsenz Optional
Typ

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

Standardeinstellung
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. Nicht zulässig, wenn ein Literalwert angegeben wird.

<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 Weitere Informationen finden Sie unter Schlüssel/Wert-Zuordnungen für die Umgebung erstellen und bearbeiten. um in der UI verschlüsselte KVMs mit Umgebungsbezug zu erstellen.

<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 wird der Wert für einen Schlüssel überschrieben.

false Optional

<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>
Standardeinstellung environment
Präsenz 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>
Standardeinstellung
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

Von Edge-Richtlinien zurückgegebene Fehler haben ein konsistentes 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.

Fehlercode HTTP-Status Ursache Problembehebung
steps.keyvaluemapoperations.SetVariableFailed 500

Dieser Fehler tritt auf, wenn Sie versuchen, einen Wert aus einer verschlüsselten Schlüssel/Wert-Zuordnung abzurufen und den Wert auf eine Variable festzulegen, deren Name nicht das Präfix private hat. Das Präfix, das für grundlegende Sicherheitszwecke während der Fehlerbehebung erforderlich ist, blendet die verschlüsselten Werte aus API-Proxy-Trace- und Debug-Sitzungen aus.

steps.keyvaluemapoperations.UnsupportedOperationException 500

Dieser Fehler tritt auf, wenn in der Richtlinie für Schlüsselwertzuordnungen das Attribut mapIdentifier auf einen leeren String festgelegt ist.

Bereitstellungsfehler

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

Fehlername Ursache Beheben
InvalidIndex Wenn das Attribut index, das im Element <Get> der Richtlinie für die Schlüsselwertzuordnung angegeben ist, 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 vollständig fehlt oder das <Parameter>-Element im <Key>-Element unterhalb des <Entry> des <InitialEntries>-Elements der Richtlinie für Schlüssel/Wert-Zuordnungen fehlt.
ValueIsMissing Dieser Fehler tritt auf, wenn das Element <Value> unter dem Element <Entry> des Elements <InitialEntries> der Richtlinien für die Schlüsselwertzuordnung fehlt.

Schemas

Verwendungshinweise

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 die mit verschiedenen Back-Ends verknüpft sind, Umgebungen. 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önnten diese Struktur verwenden, um einen Speicher von IP-Adressen zu erstellen, die von Richtlinien verwendet werden können zur Laufzeit, um eine Zulassungs- oder Sperrliste für IP-Adressen zu erzwingen, um ein Backend-Ziel dynamisch auszuwählen und so weiter. 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 Methode Apigee Edge-Verwaltungs-API Details zur Organisationsschlüssel-/Wertzuordnungs-API finden Sie in der Referenz zur Verwaltungs-API. 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