Mit Schlüssel/Wert-Zuordnungen arbeiten

Sie lesen gerade die Dokumentation zu Apigee Edge.
Apigee X-Dokumentation aufrufen. info

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 der Persistenz finden Sie unter Caching und Persistenz hinzufügen.

KVM-Szenarien

Hier 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 fest zu codieren, können Sie den Proxy erkennen lassen, in welcher Umgebung er sich befindet, die zugehörige KeyValueMapOperations-Richtlinie ausführen und die richtige Ziel-URL von einer der von Ihnen erstellten KVMs abrufen. Wenn sich dann eines oder beide Ziele ändern, können Sie die KVMs einfach mit den neuen URLs aktualisieren. Der Proxy übernimmt die neuen Werte und es ist keine erneute Proxy-Bereitstellung erforderlich.
  • Sie möchten 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 JSON Web Token (JWT)-Signierung verwendet werden, speichern. 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 einen 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 apiproxy-Bereich erstellen, in dem 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 Darstellung verschlüsselter Werte so: (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 mit Sternchen (*****) maskiert. Beispiel:

Management API

In der Management API werden verschlüsselte Werte maskiert zurückgegeben. Im Folgenden sehen Sie ein Beispiel für eine Management-API-Antwort bei einem 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üsselwertzuordnungsvorgänge 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/-Wert-Paare in Trace- und Debug-Sitzungen erscheinen.

Limits

In Organisationen, in denen Core Persistence Services (CPS) aktiviert sind:

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

In Apigee Edge for Private Cloud darf jede KVM 15 MB nicht überschreiten (das 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. Mit dem Befehl nodetool cfstats können Sie die Größe Ihrer KVMs ermitteln.

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 die Schlüssel/Wert-Zuordnung (keine Verschlüsselung)

    Verwenden Sie zum Erstellen und Aktualisieren einer Laufzeit-KVM durch Ihre API-Proxys die KeyValueMapOperations-Richtlinie. (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 Management API ist für die Arbeit mit KVMs als Administrator und nicht zur Laufzeit in Ihren API-Proxys vorgesehen. Sie haben beispielsweise ein internes Script, das die Management 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 für alle Proxys zurücksetzen. (Verwenden Sie für die Laufzeitbearbeitung von KVMs die Richtlinie für Schlüsselwertzuordnungsvorgänge 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 API-Proxy) erstellen, aktualisieren und löschen.

    Zum Erstellen einer verschlüsselten KVM mit der Management API fügen Sie der JSON-Nutzlast "encrypted" : "true" hinzu. Sie können nur dann VMs verschlüsseln, wenn Sie sie erstellen. Sie können eine vorhandene KVM nicht verschlüsseln.

  • Verwaltungs-UI

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

KVMs abrufen

Verschlüsselte und unverschlüsselte Schlüssel/Wert-Paare werden auf dieselbe Weise abgerufen. Es gibt nur eine geringfügige Abweichung, wenn Sie die KeyValueMapOperations-Richtlinie verwenden.

  • Richtlinie: Verwenden Sie das Element <Get> in der KeyValueMapOperations-Richtlinie, um verschlüsselte und unverschlüsselte KVMs abzurufen. Der einzige kleine Unterschied besteht darin, dass Sie beim Abrufen verschlüsselter Werte mit der Richtlinie dem Namen der Variablen, die den abgerufenen Wert enthält, das Präfix „private.“ hinzufügen müssen, wie im Abschnitt „Get-Operation“ des Referenzthemas beschrieben. Mit diesem Präfix wird der Wert von Trace- und Debugging-Sitzungen ausgeblendet, während Sie API-Proxys debuggen.
  • Management API: Für administrative Verwaltungszwecke können Sie Umgebungsschlüssel/Wert-Zuordnungen erstellen und bearbeiten verwenden, um KVMs und Schlüssel/Werte abzurufen. Wenn Sie beispielsweise KVMs sichern möchten, indem Sie die JSON-Definitionen abrufen und speichern, verwenden Sie die Management API. Beachten Sie jedoch, dass verschlüsselte Werte in der API-Antwort als ***** angezeigt werden.
  • Verwaltungsoberfläche: Sie können Ihre KVMs mit Umgebungsbereich in der Verwaltungsoberfläche unter APIs > Umgebungskonfiguration > Schlüssel/Wert-Paarzuordnungen (Classic Edge) oder Administrator > Umgebungen > Schlüssel/Wert-Paarzuordnungen (New Edge) aufrufen.

KVM-Beispiel

Ein Beispiel für die Verwendung einer KVM zum Einfügen von Werten in eine URL finden Sie unter Ziel-URL mit KVM nach Umgebung als Vorlage erstellen.