Mit Schlüssel/Wert-Zuordnungen arbeiten

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

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 von Schlüssel/Wert-Stringen-Paaren, die entweder verschlüsselt oder unverschlüsselt sind. Hier sind zwei Beispiele:

Weitere Informationen zu anderen Arten von Persistenz finden Sie unter Caching und Persistenz hinzufügen.

KVM-Szenarien

Hier sind einige Situationen, in denen KVMs nützlich sind:

  • 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 Proxy hartzucodieren, können Sie festlegen, dass der Proxy erkennt, in welcher Umgebung er sich befindet, die entsprechende Richtlinie für Schlüssel/Wert-Zuordnungen ausführen und die richtige Ziel-URL von einer der von Ihnen erstellten KVMs abrufen. Und wenn sich später eines oder beide Ihrer Ziele ändern, aktualisieren Sie die KVMs einfach mit den neuen URLs. Der Proxy übernimmt die neuen Werte und es ist keine erneute Proxybereitstellung erforderlich.
  • Sie möchten Anmeldedaten, private Schlüssel oder Tokens speichern, z. B. Tokens für externe Dienste, Anmeldedaten, die zum Generieren von OAuth-Tokens erforderlich sind, oder private Schlüssel, die in Java-Callouts oder JavaScript für die Verschlüsselung oder zum Signieren von JSON Web Tokens (JWT) verwendet werden. Anstatt Anmeldedaten, Schlüssel oder Token in der Anfrage zu übergeben oder sie in Ihrer Proxy-Logik fest zu codieren, können Sie sie in einer KVM (immer verschlüsselt) 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 Stellen 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.

KVMs haben Bereich

Bereich bedeutet „Wo eine KVM verfügbar ist“. KVMs können in den folgenden Bereichen erstellt werden: organization, environment und apiproxy.

Wenn beispielsweise nur ein API-Proxy Daten in einer KVM benötigt, können Sie die KVM im Bereich apiproxy erstellen, wo nur dieser API-Proxy auf die Daten zugreifen kann.

Oder Sie möchten, dass alle API-Proxys in Ihrer Testumgebung Zugriff auf eine Schlüssel/Wert-Paar-Zuordnung haben, in dem Sie eine Schlüssel/Wert-Paar-Zuordnung im Umgebungsbereich erstellen. In der Produktionsumgebung bereitgestellte Proxys können nicht auf KVMs im Bereich „Test” zugreifen. Wenn Sie in der Produktion die gleichen KVM-Schlüssel zur Verfügung stellen möchten, erstellen Sie eine parallele KVM, die der „Prod”-Umgebung entspricht.

Wenn alle Proxys in allen Umgebungen auf dieselbe KVM zugreifen sollen, erstellen Sie die KVM im Bereich organization.

Verschlüsselte KVMs

Verschlüsselte KVMs werden mit einem von Apigee generierten AES-128-Chiffreschlüssel verschlüsselt. Der zum Verschlüsseln einer KVM verwendete Schlüssel wird im Bereich der KVM gespeichert. In einer Organisation werden alle verschlüsselten KVMs, die Sie im Umgebungsbereich erstellen, z. B. mit demselben Umgebungsschlüssel erstellt.

Edge verarbeitet die Anzeige verschlüsselter Werte auf folgende Weise. (Weitere Informationen zum Erstellen verschlüsselter KVMs finden Sie unter KVMs verwalten und verwenden.)

Edge-Benutzeroberfläche

In verschlüsselten Schlüssel/Wert-Zuordnungen werden Werte in der Benutzeroberfläche (*****) durch Sternchen maskiert. Beispiel:

Management API

In der Management API werden verschlüsselte Werte maskiert zurückgegeben. Im Folgenden finden Sie ein Beispiel für eine Verwaltungs-API-Antwort auf einen Get-verschlüsselten KVM-Aufruf:

{
  "encrypted": true,
  "entry": [
    {
      "name": "Key1",
      "value": "*****"
    },
    {
      "name": "Key2",
      "value": "*****"
    }
  ],
  "name": "secretMap"
}

Trace und Fehlerbehebung

Wenn Sie die Richtlinie für Schlüssel/Wert-Zuordnungen zum Abrufen verschlüsselter KVM-Werte verwenden, geben Sie den Namen einer Variablen an, um den Wert zu speichern. Um einen verschlüsselten Wert zu erhalten, müssen Sie dem Variablennamen das Präfix „private.“ hinzufügen. Dadurch wird verhindert, dass die KVM-Schlüssel/Werte in Trace- und Debug-Sitzungen angezeigt werden.

Einschränkungen

In Organisationen mit aktivierten Core Persistence Services (CPS):

  • Beim Namen/der KVM-ID wird zwischen Groß- und Kleinschreibung unterschieden.
  • Die Schlüsselgröße ist auf 2 KB beschränkt.
  • Die Größe des Werts ist auf 10 KB begrenzt.

Bei Apigee Edge for Private Cloud sollte jede KVM 15 MB nicht überschreiten (dies ist die kombinierte Größe der Schlüssel und Werte). Wenn Sie dieses Limit überschreiten, gibt Apigee Edge for Private Cloud einen Fehler zurück. Um die Größe Ihrer KVMs zu ermitteln, können Sie den Befehl nodetool cfstats verwenden.

Größere KVMs können zu Leistungseinbußen führen. Daher sollten Sie große, monolithische KVMs in kleinere aufteilen, um die Leistung zu verbessern.

KVMs verwalten und verwenden

Sie können KVMs auf verschiedene Arten erstellen, verwalten und verwenden. In diesem Abschnitt werden verschiedene Optionen zum Erstellen und Abrufen von verschlüsselten und unverschlüsselten KVMs beschrieben.

KVMs erstellen und aktualisieren

Sie können KVMs auf folgende Arten erstellen und aktualisieren:

  • Richtlinie für Schlüssel/Wert-Zuordnungsvorgänge (keine Verschlüsselung)

    Verwenden Sie zum Erstellen und Aktualisieren von Laufzeit-KVM durch Ihre API-Proxys die Richtlinie für Schlüsselwertzuordnungsvorgänge. (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 der 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 Schlüssel/Wert-Paare hinzugefügt (oder aktualisiert, falls der Schlüssel bereits vorhanden ist). Sie können mehrere <Put>-Elemente in einer KVM-Richtlinie verwenden.

  • Management API

    Die Verwaltungs-API dient dazu, mit KVMs als Administrator und nicht während der Laufzeit in Ihren API-Proxys zu arbeiten. Angenommen, Sie haben ein internes Skript, das die Verwaltungs-API verwendet, um KVMs in einer Testumgebung zu löschen und neu zu erstellen, oder Sie möchten den Wert eines Schlüssels in einer KVM zurücksetzen, damit alle Proxys sie abrufen können. (Verwenden Sie zur Laufzeitbearbeitung von KVMs die Richtlinie für Schlüssel/Wert-Zuordnungen in Ihren Proxys.)

    Mit der Key/Value Maps Management API können Sie verschlüsselte KVMs und Schlüssel/Werte in allen Bereichen (Organisation, Umgebung und apiproxy) erstellen, aktualisieren und löschen.

    Fügen Sie der JSON-Nutzlast "encrypted" : "true" hinzu, um eine verschlüsselte KVM mit der Verwaltungs-API zu erstellen. Sie können KVMs nur verschlüsseln, wenn Sie sie erstellen. Sie können eine vorhandene KVM nicht verschlüsseln.

  • Verwaltungs-UI

    In der Edge-Management-Benutzeroberfläche können Sie umgebungsbezogene KVMs erstellen und aktualisieren. Dies ist der einzige Bereich von KVM, der in der Benutzeroberfläche angezeigt wird. Die Verwaltungs-UI ist eine gute Möglichkeit, KVM-Daten für API-Proxys zur Laufzeit manuell zu verwalten. Weitere Informationen finden Sie unter Schlüssel/Wert-Zuordnungen für die Umgebung erstellen und bearbeiten.

KVMs abrufen

Verschlüsselte und unverschlüsselte Schlüssel/Wert-Paare werden auf die gleiche Weise abgerufen, allerdings mit einer geringfügigen Abweichung, wenn das Schlüssel/Wert-Paar mit der Richtlinie für Schlüssel/Wert-Zuordnungen abgerufen wird.

  • Richtlinie: Verwenden Sie das Element <Get> in der Richtlinie für Schlüssel/Wert-Zuordnungsvorgänge, um verschlüsselte und unverschlüsselte KVMs abzurufen. Der einzige kleine Unterschied besteht darin, dass verschlüsselte Werte mit der Richtlinie abgerufen werden. Dabei müssen Sie dem Namen der Variablen, die den abgerufenen Wert enthält, das Präfix „private.“ hinzufügen, wie im Abschnitt Get-Vorgang des Referenzthemas beschrieben. Dieses Präfix blendet den Wert in Trace- und Debug-Sitzungen aus, während Sie Fehler an API-Proxys beheben.
  • Management API: Für administrative Verwaltungszwecke können Sie KVMs und Schlüssel/Wert-Paare abrufen, indem Sie Schlüssel/Wert-Zuordnungen für die Umgebung erstellen und bearbeiten. Wenn Sie beispielsweise KVMs sichern möchten, indem Sie die JSON-Definitionen abrufen und speichern, verwenden Sie die Verwaltungs-API. Verschlüsselte Werte werden in der API-Antwort jedoch als ***** angezeigt.
  • Verwaltungsoberfläche: Sie können Ihre umgebungsbezogenen KVMs in der Verwaltungsoberfläche aufrufen. Rufen Sie dazu APIs > Umgebungskonfiguration > Schlüssel/Wert-Zuordnungen (klassisches Edge) oder Verwaltung > Umgebungen > Schlüssel/Wert-Zuordnungen (New Edge) auf.

KVM-Beispiel

Ein Beispiel für die Verwendung einer KVM zum Auffüllen von Werten in einer URL finden Sie unter https://community.apigee.com/questions/32727/templatize-target-url-with-kvm-by-environment.html.