Schlüssel/Wert-Paar-Zuordnungen verwenden

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

In diesem Abschnitt wird erläutert, wie Sie Schlüssel/Wert-Paar-Zuordnungen (Key Value Maps, KVMs) verwenden.

Übersicht

Es kann vorkommen, dass Sie Daten zum Abrufen zur Laufzeit speichern möchten – nicht ablaufende Daten, die in Ihrer API-Proxy-Logik nicht fest codiert sein sollten. Schlüssel/Wert-Paar-Zuordnungen (KVMs) sind ideal dafür. Eine KVM ist eine benutzerdefinierte Sammlung verschlüsselter Schlüssel/Wert-String-Paare.

Im Folgenden sind drei gängige Anwendungsfälle für das Speichern von Daten in KVMs dargestellt:

Nutzersitzungsdaten: Daten, die nur von der Laufzeit erstellt und gelöscht werden. Sie können KVM-Einträge außerhalb der Laufzeit weder aufrufen noch verwalten. Zum Beispiel den Inhalt eines Einkaufswagens.
Konfiguration (z. B. Routingregeln und Suchtabellen): Daten werden normalerweise außerhalb der Laufzeit erstellt, aber von der Laufzeit gelesen. Diese Daten werden über die Benutzeroberfläche oder die API konfiguriert und dann als Variablen oder schreibgeschützte Inhalte dem Gateway zur Verfügung gestellt.
Beispiel: Sie haben einen API-Proxy, der eine Ziel-URL (oder Service-Callout-URL) in einer Testumgebung und eine andere Ziel-URL in einer Produktionsumgebung aufrufen muss. Anstatt URLs in Ihrem API-Proxy fest zu codieren, können Sie ihn erkennen lassen, in welcher Umgebung er sich befindet, die zugehörige KeyValueMapOperations-Richtlinie ausführen und die richtige Ziel-URL von der entsprechenden KVM abrufen.

Wenn sich dann eines oder beide Ziele ändern, können Sie die KVMs einfach mit den neuen URLs aktualisieren. Der API-Proxy übernimmt die neuen Werte und es ist keine erneute Bereitstellung erforderlich.
Anmeldedaten: Speichern Sie Anmeldedaten, private Schlüssel oder Tokens für externe Dienste, Anmeldedaten, die zur Generierung von OAuth-Tokens erforderlich sind, oder private Schlüssel, die in Java Callouts oder JavaScript zur Verschlüsselung oder JWT-Signierung (JSON Web Token) verwendet werden. Anstatt Anmeldedaten, Schlüssel oder Tokens in der Anfrage zu übergeben oder sie in Ihrer Proxy-Logik fest zu codieren, können Sie sie in einer KVM speichern und dynamisch in Aufrufen an Ziele abrufen, die sie benötigen.

Außerdem lernen Sie andere Situationen kennen, in denen das Speichern von Schlüssel/Wert-Stringen-Paaren nützlich ist. Im Allgemeinen sollten Sie KVMs verwenden, wenn:

Bestimmte Abschnitte im Code zur Laufzeit unterschiedliche Werte erfordern.
Vertrauliche Daten ohne feste Codierung übergeben werden müssen.
Sie Werte speichern möchten, die nicht wie ein Cache ablaufen.

Attributsätze sind eine gute Alternative zu KVMs, da sie einfacher zu verwenden sind. Weitere Informationen finden Sie unter Attributsätze verwenden.

Informationen zum KVM-Bereich

Der Bereich definiert, wo eine KVM verfügbar ist. KVMs können in den folgenden Bereichen erstellt werden:

Umfang	Beschreibung
API-Proxy	Nur der API-Proxy kann auf die KVM zugreifen.
Umgebung	Alle API-Proxys in einer bestimmten Umgebung können auf die KVM zugreifen. Angenommen Sie möchten, dass API-Proxys, die in der `prod`-Umgebung bereitgestellt werden, keinen Zugriff auf KVMs in der `test`-Umgebung haben. Wenn die gleichen KVM-Schlüssel in der Produktion verfügbar sein sollen, erstellen Sie in diesem Fall eine parallele KVM, die auf die `prod`-Umgebung beschränkt ist.
Organisation	Alle API-Proxys in allen Umgebungen können auf die KVM zugreifen.

Informationen zur KVM-Verschlüsselung

In Apigee werden alle KVM-Einträge für den API-Proxy, die Organisations- und Umgebungsbereiche mit dem Cloud KMS-Schlüssel geschützt, der bei der Bereitstellung einer Apigee-Organisation angegeben wird (siehe das Feld runtimeDatabaseEncryptionKey in der Ressource Organisation). Apigee verwendet AES256 als Verschlüsselungsstandard.

In Apigee Hybrid können Sie separate Verschlüsselungsschlüssel für alle KVM-Einträge für API-Proxy-, Organisations- und Umgebungsbereiche angeben. Apigee akzeptiert Verschlüsselungsgrößen von AES128, AES196 oder AES256 als Verschlüsselungsstandard.

KVMs erstellen

Erstellen Sie KVMs wie in den folgenden Abschnitten erläutert.

Apigee in der Cloud Console

So erstellen Sie eine neue, leere VM oder rufen eine Liste der KVMs auf:

Öffnen Sie die Apigee-UI in der Cloud Console in einem Browser.
Klicken Sie im linken Navigationsbereich auf Verwaltung > Umgebungen.
Wählen Sie in der Liste der verfügbaren Umgebungen die Umgebung aus, die Sie bearbeiten möchten.
Klicken Sie auf der Seite Umgebungsdetails auf den Tab Schlüssel/Wert-Paar-Zuordnungen.
Auf der Seite Schlüssel/Wert-Paar-Zuordnungen wird eine Liste der vorhandenen KVMs angezeigt. Wenn Sie noch keine KVMs erstellt haben, ist die Liste leer.
Klicken Sie zum Erstellen einer neuen (leeren) KVM auf +Schlüssel/Wert-Zuordnung.
Das Dialogfeld Schlüssel/Wertpaar-Zuordnung hinzufügen wird angezeigt:
Geben Sie im Feld Name der Schlüssel/Wert-Zuordnung einen Namen für die KVM ein.
Der Name darf nur Buchstaben, Zahlen und Bindestriche enthalten und darf nicht länger als 255 Zeichen sein. Er darf keine Leerzeichen oder andere Sonderzeichen enthalten. Beispiel: my-kvm-1
Klicken Sie auf Erstellen.
Die neue KVM wird in der Liste angezeigt.

Klassische Apigee-UI

So erstellen Sie eine neue, leere VM oder rufen eine Liste der KVMs auf:

Melden Sie sich bei der Apigee-UI an.
Wählen Sie Admin > Umgebungen > Schlüssel/Wert-Paarzuordnungen aus.
Wählen Sie in der Drop-down-Liste "Umgebung" die Umgebung aus, für die Sie eine KVM erstellen möchten.
Auf der Seite Schlüssel/Wert-Paar-Zuordnungen wird eine Liste der vorhandenen KVMs angezeigt. Wenn Sie noch keine KVMs erstellt haben, ist die Liste leer.
Klicken Sie zum Erstellen einer neuen (leeren) KVM auf +Schlüssel/Wert-Zuordnung.
Das Dialogfeld Schlüssel/Wertpaar-Zuordnung hinzufügen wird angezeigt:
Geben Sie im Feld Name einen Namen für das Frontend ein.
Der Name darf nur Buchstaben, Zahlen und Bindestriche enthalten. Er darf keine Leerzeichen oder andere Sonderzeichen enthalten. Beispiel: my-kvm-1
Klicken Sie auf Hinzufügen.
Die neue KVM wird in der Liste angezeigt.

Apigee API

Mit den Apigee APIs können Sie KVMs für die folgenden Bereiche erstellen, auflisten und löschen:

KVM-Richtlinie

Um KVMs zur Laufzeit zu erstellen und in Ihren API-Proxys zu aktualisieren, verwenden Sie die Richtlinie KeyValueMapOperations. In der Richtlinie geben Sie den Namen der KVM im Attribut mapIdentifier des übergeordneten Elements an.

Mit dem Element <InitialEntries> können Sie einen neuen Satz von Einträgen in einer neuen KVM erstellen und Werte dafür festlegen, sobald Sie die Richtlinie in der UI speichern, oder den API-Proxy bereitstellen, wenn Sie diese offline entwickelt haben. Wenn sich die Werte in der Richtlinie ändern, werden die vorhandenen Werte überschrieben. Alle neuen Schlüssel/Wert-Paare werden zusammen mit den vorhandenen Schlüssel/Wert-Paaren zur vorhandenen KVM hinzugefügt.

Das Element <Put> erstellt eine neue KVM, falls noch keine vorhanden ist, und erstellt einen Schlüssel mit einem oder mehreren Werten. Wenn die KVM bereits vorhanden ist, werden deren Schlüssel/Wert-Paare hinzugefügt oder diese aktualisiert, wenn der Schlüssel schon verfügbar ist. Sie können mehrere <Put>-Elemente in einer KVM-Richtlinie verwenden.

Fehlerbehebung

Wenn Sie die KeyValueMapOperations-Richtlinie zum Abrufen verschlüsselter KVM-Werte verwenden, geben Sie den Namen einer Variablen an, um den Wert zu speichern. Da alle KVM-Werte verschlüsselt sind, müssen Sie dem Variablennamen das Präfix private. hinzufügen. Das verhindert, dass die Schlüssel-Wert-Paare in Debug-Sitzungen angezeigt werden.

KVMs abrufen

Rufen Sie KVMs mithilfe des Elements <Get> der Richtlinie KeyValueMapOperations ab. Da alle KVM-Werte verschlüsselt sind, müssen Sie dem Namen der Variablen, die den abgerufenen Wert enthält, das Präfix private. hinzufügen. Durch dieses Präfix wird der Wert bei Debug-Sitzungen für API-Proxys ausgeblendet. Weitere Informationen finden Sie unter <Get>-Element.

KVMs löschen

Sie können KVMs löschen, wie in den folgenden Abschnitten erläutert.