Mit Schlüssel/Wert-Zuordnungen arbeiten

<ph type="x-smartling-placeholder"></ph> Sie sehen die Dokumentation zu Apigee Edge.
Gehen Sie 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 der Persistenz finden Sie unter Caching und Persistenz hinzufügen

KVM-Szenarien

Hier sind einige Situationen, in denen KVMs von Vorteil sind:

  • Sie haben einen API-Proxy, der eine Ziel-URL (oder Service-Callout-URL) in einem Test aufrufen muss. und eine andere Ziel-URL in einer Produktionsumgebung. Anstatt URLs in können Sie festlegen, dass der Proxy erkennt, in welcher Umgebung er sich befindet, und den zugehörigen Schlüssel Wertzuordnungsoperationen und rufen Sie die richtige Ziel-URL von einer der KVMs ab, die Sie erstellt. Wenn sich eines oder beide Ziele später ändern, aktualisieren Sie die KVMs einfach mit die neuen URLs. Der Proxy übernimmt die neuen Werte und eine erneute Bereitstellung des Proxys ist nicht erforderlich.
  • Sie möchten Anmeldedaten, private Schlüssel oder Tokens wie Tokens für externe Dienste, Anmeldedaten, die zum Generieren von OAuth-Tokens oder privaten Schlüsseln erforderlich sind Wird in Java-Callouts oder JavaScript für die Verschlüsselung oder für das Signieren von JSON Web Tokens (JWT) verwendet. 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 apiproxy-Bereich, 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.

<ph type="x-smartling-placeholder">

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. (Informationen zum Erstellen verschlüsselter KVMs finden Sie unter KVMs verwalten und verwenden.)

Edge-Benutzeroberfläche

Verschlüsselte Schlüssel/Wert-Zuordnungen zeigen Werte an, die in der UI mit Sternchen (*****) maskiert sind. Für Beispiel:

Management API

In der Verwaltungs-API werden verschlüsselte Werte maskiert zurückgegeben. Nachfolgend sehen Sie Beispiele für die Verwaltung API-Antwort auf einen KVM-Aufruf zum Abrufen:

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

Trace und Fehlerbehebung

Wenn Sie die Richtlinie für Schlüsselwertzuordnungsvorgänge verwenden. Um verschlüsselte KVM-Werte abzurufen, geben Sie den Namen einer Variablen an, Wert. Um einen verschlüsselten Wert zu erhalten, müssen Sie „private.“ hinzufügen Präfix des Variablenname. Dadurch wird verhindert, dass die KVM-Schlüssel/Werte in Trace- und Debug-Sitzungen angezeigt werden.

Limits

In Organisationen mit Kern Persistence Services (CPS) aktiviert:

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

Bei Apigee Edge für Private Cloud darf eine KVM nicht größer als 15 MB sein (dies ist die Gesamtgröß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 bestimmen, können Sie den Befehl nodetool cfstats.

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

KVMs verwalten und verwenden

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

KVMs erstellen und aktualisieren

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

  • Richtlinie für Schlüssel/Wert-Zuordnungen (keine Verschlüsselung)

    Verwenden Sie zum Erstellen und Aktualisieren von KVM-Laufzeiten durch Ihre API-Proxys die Methode Richtlinie für Schlüssel/Wert-Zuordnungen. (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 der Arbeit mit KVMs als Administrator und nicht während der Laufzeit in Ihren API-Proxys. Beispiel: Sie haben ein internes Skript, das die Verwaltungs- API zum Löschen und Neuerstellen von KVMs in einer Testumgebung oder Zurücksetzen eines Schlüsselwerts in einer KVM gespeichert, die von allen Proxys abgerufen werden können. (Verwenden Sie zur Laufzeitbearbeitung von KVMs die Methode Richtlinie für Schlüssel/Wert-Zuordnungen in Ihren Proxys).

    Die Key/Value Maps Management API können Sie verschlüsselte KVMs und Schlüssel/Werte Alle Bereiche (Organisation, Umgebung und APIproxy).

    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 beim Erstellen . Sie können eine vorhandene KVM nicht verschlüsseln.

  • Verwaltungs-UI

    In der Edge-Management-Benutzeroberfläche können Sie umgebungsbezogenen KVMs. Dies ist der einzige Bereich von KVM, auf der Benutzeroberfläche angezeigt. Die Verwaltungsoberfläche ist eine gute Möglichkeit, KVM-Daten für die API manuell zu verwalten. Proxys zur Laufzeit. Siehe Schlüssel/Wert-Zuordnungen für die Umgebung erstellen und bearbeiten .

KVMs abrufen

Sie rufen verschlüsselte und unverschlüsselte Schlüsselwertzuordnungen auf die gleiche Weise ab, mit einer geringfügigen Abweichung. beim Abrufen über die Richtlinie für Schlüsselwertzuordnungsoperationen.

  • 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 Unterschied ist, Abrufen verschlüsselter Werte mit der Richtlinie, wobei „private.“ hinzugefügt werden muss vor dem Namen der Variablen ein, die den abgerufenen Wert enthält, wie in den Bereich „Vorgang abrufen“ des Referenzthemas. Dieses Präfix verbirgt den Wert in Trace und Fehlerbehebung während Sie API-Proxys debuggen.
  • Management API: Für administrative Verwaltungszwecke können Sie die Schlüssel/Wert-Zuordnungen für die Umgebung erstellen und bearbeiten um KVMs und Schlüssel/Werte zu erhalten. Wenn Sie zum Beispiel KVMs sichern, indem Sie JSON-Definitionen abrufen und speichern, verwenden Sie die Verwaltungs-API. Seien Sie achtsam, Allerdings werden diese verschlüsselten Werte in der API-Antwort als ***** angezeigt.
  • Verwaltungsoberfläche: Sie können Ihre umgebungsbezogenen KVMs in der Verwaltung ansehen. indem Sie zu APIs > Umgebungskonfiguration > Schlüssel/Wert-Paare (Classic Edge) oder Verwaltung > Umgebungen > Schlüssel/Wert-Zuordnungen (New Edge)

KVM-Beispiel

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