Sie sehen die Apigee Edge-Dokumentation.
Rufen Sie die Apigee X-Dokumentation auf. weitere Informationen
Edge Microgateway Version 3.3.x
Zielgruppe
Dieses Thema richtet sich an Edge Microgateway-Operatoren, die vorhandene Plug-ins verwenden möchten, die mit dem Microgateway installiert werden. Außerdem werden der Spike Arrest und die Kontingent-Plug-ins im Detail behandelt (beide sind in der Installation enthalten). Wenn Sie Entwickler sind und neue Plug-ins entwickeln möchten, finden Sie weitere Informationen unter Benutzerdefinierte Plug-ins entwickeln.
Was ist ein Edge Microgateway-Plug-in?
Ein Plug-in ist ein Node.js-Modul, das Edge Microgateway-Funktionen erweitert. Plug-in-Module folgen einem einheitlichen Muster und werden an einem Ort gespeichert, der Edge Microgateway bekannt ist, damit das Mikrogateway sie automatisch erkennen und laden kann. Edge Microgateway enthält mehrere vorhandene Plug-ins. Sie können auch benutzerdefinierte Plug-ins erstellen, wie unter Benutzerdefinierte Plug-ins entwickeln beschrieben.
Vorhandene mit Edge Microgateway gebündelte Plug-ins
Bei der Installation wird eine Reihe von Plug-ins mit Edge Microgateway bereitgestellt. In der folgenden Tabelle werden einige der am häufigsten verwendeten Plug-ins beschrieben.
Plug-in | Standardmäßig aktiviert | Beschreibung |
---|---|---|
Analytics | Ja | Sendet Analysedaten von Edge Microgateway an Apigee Edge. |
oauth | Ja | Fügt die Validierung von OAuth-Tokens und API-Schlüsseln zu Edge Microgateway hinzu. Weitere Informationen finden Sie unter Edge Microgateway einrichten und konfigurieren. |
Kontingent | Nein | Erzwingt Kontingente für Anfragen an Edge Microgateway. Verwendet Apigee Edge zum Speichern und Verwalten der Kontingente. Weitere Informationen finden Sie unter Kontingent-Plug-in verwenden. |
Spitzenhalter | Nein | Schützt vor Trafficspitzen und DoS-Angriffen. Siehe Spitzen-Arrest-Plug-in verwenden. |
Header-Großbuchstaben | Nein | Ein kommentierter Beispiel-Proxy, der als Leitfaden für Entwickler beim Schreiben benutzerdefinierter Plug-ins dient Siehe Beispiel-Plug-in für Edge Microgateway. |
Sammelanfrage | Nein | Fasst Anfragedaten in einem einzelnen Objekt zusammen, bevor die Daten an den nächsten Handler in der Plug-in-Kette übergeben werden. Nützlich zum Schreiben von Transformations-Plug-ins, die mit einem einzelnen, angesammelten Anfrageinhaltsobjekt arbeiten müssen. |
Akkumulieren-Antwort | Nein | Fasst Antwortdaten in einem einzelnen Objekt zusammen, bevor die Daten an den nächsten Handler in der Plug-in-Kette übergeben werden. Nützlich zum Schreiben von Transformations-Plug-ins, die mit einem einzelnen, kumulierten Antwortinhaltsobjekt ausgeführt werden müssen. |
Großbuchstaben umwandeln | Nein | Transformiert Anfrage- oder Antwortdaten. Dieses Plug-in stellt eine Best Practice-Implementierung eines Transformations-Plug-ins dar. Das Beispiel-Plug-in führt eine einfache Transformation aus (konvertiert Anfrage- oder Antwortdaten in Großbuchstaben). Es kann jedoch leicht für andere Transformationen wie XML in JSON angepasst werden. |
json2xm | Nein | Transformiert Anfrage- oder Antwortdaten basierend auf Akzeptanz- oder Inhaltstyp-Headern. Weitere Informationen finden Sie in der Plug-in-Dokumentation in GitHub. |
quota-memory | Nein | Erzwingt Kontingente für Anfragen an Edge Microgateway. Speichert und verwaltet Kontingente im lokalen Arbeitsspeicher. |
Systemdiagnose | Nein | Gibt Informationen zum Edge Microgateway-Prozess zurück, z. B. Arbeitsspeichernutzung, CPU-Auslastung usw. Rufen Sie auf Ihrer Edge Microgateway-Instanz die URL /healthcheck auf, um das Plug-in zu verwenden. Dieses Plug-in dient als Beispiel, mit dem Sie Ihr eigenes Systemdiagnose-Plug-in implementieren können. |
Vorhandene Plug-ins finden
Vorhandene mit Edge Microgateway gebündelte Plug-ins befinden sich hier, wobei [prefix]
das Präfixverzeichnis npm
ist. Wenn Sie dieses Verzeichnis nicht finden können, lesen Sie den Abschnitt
Wo ist Edge Microgateway installiert?.
[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins
Plug-ins hinzufügen und konfigurieren
Folgen Sie diesem Muster, um Plug-ins hinzuzufügen und zu konfigurieren:
- Edge Microgateway beenden.
- Öffnen Sie eine Edge Microgateway-Konfigurationsdatei. Weitere Informationen zu den Optionen finden Sie unter Konfigurationsänderungen vornehmen.
- Fügen Sie das Plug-in dem
plugins:sequence
-Element der Konfigurationsdatei hinzu: Plug-ins werden in der Reihenfolge ausgeführt, in der sie in dieser Liste aufgeführt sind.
edgemicro: home: ../gateway port: 8000 max_connections: -1 max_connections_hard: -1 logging: level: info dir: /var/tmp stats_log_interval: 60 plugins: dir: ../plugins sequence: - oauth - plugin-name
- Konfigurieren Sie das Plug-in. Einige Plug-ins haben optionale Parameter, die Sie in der Konfigurationsdatei konfigurieren können. Sie können beispielsweise die folgende Stanza hinzufügen, um das Spike Arrest-Plug-in zu konfigurieren. Weitere Informationen finden Sie unter Spitzen-Arrest-Plug-in verwenden.
edgemicro: home: ../gateway port: 8000 max_connections: -1 max_connections_hard: -1 logging: level: info dir: /var/tmp stats_log_interval: 60 plugins: dir: ../plugins sequence: - oauth - spikearrest spikearrest: timeUnit: minute allow: 10
- Speichere die Datei.
- Starten Sie Edge Microgateway neu oder laden Sie es neu, je nachdem, welche Konfigurationsdatei Sie bearbeitet haben.
Plug-in-spezifische Konfiguration
Sie können die in der Konfigurationsdatei angegebenen Plug-in-Parameter überschreiben, indem Sie in diesem Verzeichnis eine Plug-in-spezifische Konfiguration erstellen:
[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins/config
Dabei ist [prefix]
das Präfixverzeichnis npm
. Wenn Sie dieses Verzeichnis nicht finden können, lesen Sie den Abschnitt
Wo ist Edge Microgateway installiert?.
plugins/<plugin_name>/config/default.yaml
. Wenn Sie diesen Block beispielsweise in plugins/spikearrest/config/default.yaml
einfügen, werden alle anderen Konfigurationseinstellungen überschrieben.
spikearrest: timeUnit: hour allow: 10000 buffersize: 0
Spitzen-Arrest-Plug-in verwenden
Das Spike Arrest-Plug-in schützt vor Trafficspitzen. Sie drosselt die Anzahl der Anfragen, die von einer Edge Microgateway-Instanz verarbeitet werden.
Plug-in für Spike Arrest hinzufügen
Weitere Informationen finden Sie unter Plug-ins hinzufügen und konfigurieren.
Beispielkonfiguration für Spike Arrest
edgemicro: home: ../gateway port: 8000 max_connections: -1 max_connections_hard: -1 logging: level: info dir: /var/tmp stats_log_interval: 60 plugins: dir: ../plugins sequence: - oauth - spikearrest spikearrest: timeUnit: minute allow: 10 bufferSize: 5
Konfigurationsoptionen für Spike Arrest
- timeUnit: Wie oft das Spitzenarrest-Ausführungsfenster zurückgesetzt wird. Gültige Werte sind „second“ und „minute“.
- allow: Die maximale Anzahl von Anfragen, die während einer timeUnit zulässig sind. Weitere Informationen finden Sie unter Wenn Sie mehrere Edge Micro-Prozesse ausführen.
- bufferSize: (optional, Standard = 0) Wenn bufferSize > 0 ist, speichert Spike Arrest diese Anzahl von Anfragen in einem Puffer. Sobald das nächste Ausführungsfenster auftritt, werden die zwischengespeicherten Anfragen zuerst verarbeitet. Weitere Informationen finden Sie unter Puffer hinzufügen.
Wie funktioniert Spike Arrest?
Stellen Sie sich Spike Arrest als eine Art Schutz vor Traffic-Spitzen im Allgemeinen vor und nicht als eine Möglichkeit, den Traffic auf eine bestimmte Anzahl von Anfragen zu beschränken. Ihre APIs und Ihr Back-End können eine bestimmte Menge an Traffic verarbeiten. Mit der Spike Arrest-Richtlinie können Sie den Traffic auf das gewünschte allgemeine Maß glätten.
Das Verhalten der Laufzeit-Spitzen-Arretierung unterscheidet sich von dem, was Sie möglicherweise von den eingegebenen Literal-pro-Minute- oder -Sekunden-Werten erwarten.
Angenommen, Sie geben wie folgt eine Rate von 30 Anfragen pro Minute an:
spikearrest: timeUnit: minute allow: 30
Beim Testen könnten Sie davon ausgehen, dass Sie 30 Anfragen in einer Sekunde senden können, solange diese innerhalb einer Minute eingehen. Aber so wird die Einstellung nicht durch die Richtlinie erzwungen. 30 Anfragen innerhalb eines 1-sekündigen Zeitraums können in einigen Umgebungen als Mini-Spitzen angesehen werden.
Was geschieht dann tatsächlich? Damit Spitzen-ähnliches Verhalten vermieden werden kann, glättet Spike Arrest den zulässigen Traffic. Dazu werden die Einstellungen wie folgt in kleinere Intervalle unterteilt:
Minutentarife
Minutenraten werden in zulässige Intervalle von Sekunden für Anfragen geglättet. So werden beispielsweise 30 Anfragen pro Minute geglättet:
60 Sekunden (1 Minute) ÷ 30 = 2-Sekunden-Intervalle oder etwa eine Anfrage alle 2 Sekunden zulässig. Eine zweite Anfrage innerhalb von 2 Sekunden schlägt fehl. Außerdem schlägt eine 31. Anfrage innerhalb einer Minute fehl.
Sekundengenaue Raten
Sekundengenaue Raten werden in Anfragen geglättet, die in Millisekundenintervallen zulässig sind. Beispiel: 10 Anfragen pro Sekunde werden so geglättet:
1.000 Millisekunden (1 Sekunde) / 10 = 100-Millisekunden-Intervalle oder etwa eine Anfrage alle 100 Millisekunden zulässig Eine zweite Anfrage innerhalb von 100ms schlägt fehl. Außerdem schlägt eine elfte Anfrage innerhalb einer Sekunde fehl.
Wenn das Limit überschritten wird
Wenn die Anzahl der Anfragen das Limit innerhalb des angegebenen Zeitintervalls überschreitet, gibt der Spike Arrest diese Fehlermeldung mit dem HTTP 503-Status zurück:
{"error": "spike arrest policy violated"}
Puffer hinzufügen
Sie haben die Möglichkeit, der Richtlinie einen Puffer hinzuzufügen. Angenommen, Sie stellen den Puffer auf 10 ein. Sie werden feststellen, dass die API nicht sofort einen Fehler zurückgibt, wenn Sie das Spike Arrest-Limit überschreiten. Stattdessen werden Anfragen (bis zur angegebenen Anzahl) zwischengespeichert und die zwischengespeicherten Anfragen verarbeitet, sobald das nächste entsprechende Ausführungsfenster verfügbar ist. Der Standardwert für bufferSize ist 0.
Wenn Sie mehrere Edge Micro-Prozesse ausführen
Die Anzahl der zulässigen Anfragen hängt von der Anzahl der ausgeführten Edge Micro-Worker-Prozesse ab. Spike Arrest berechnet die zulässige Anzahl von Anfragen pro Worker-Prozess. Standardmäßig entspricht die Anzahl der Edge Micro-Prozesse der Anzahl der CPUs auf der Maschine, auf der Edge Micro installiert ist. Sie können jedoch die Anzahl der Worker-Prozesse beim Starten von Edge Micro mit der Option --processes
im Befehl start
konfigurieren. Wenn Sie beispielsweise möchten, dass ein Spike Arrest bei 100 Anfragen in einem bestimmten Zeitraum ausgelöst wird und Sie Edge Microgateway mit der Option --processes 4
starten, legen Sie allow: 25
in der Konfiguration für den Spike Arrest fest. Als Faustregel gilt: Legen Sie als Faustregel für den Konfigurationsparameter allow
den Wert "Gewünschte Spike Arrest-Anzahl / Anzahl der Prozesse" fest.
Kontingent-Plug-in verwenden
Ein Kontingent gibt die Anzahl der Anfragenachrichten an, die eine Anwendung im Laufe einer Stunde, eines Tages, einer Woche oder eines Monats an eine API senden darf. Wenn eine Anwendung ihr Kontingentlimit erreicht, werden nachfolgende API-Aufrufe abgelehnt. Siehe auch Was ist der Unterschied zwischen Spike Arrest und Kontingent?
Kontingent-Plug-in hinzufügen
Weitere Informationen finden Sie unter Plug-ins hinzufügen und konfigurieren.
Produktkonfiguration in Apigee Edge
Kontingente werden in der Apigee Edge-Benutzeroberfläche konfiguriert, auf der Sie API-Produkte konfigurieren. Sie müssen wissen, welches Produkt den Microgateway-fähigen Proxy enthält, den Sie mit einem Kontingent begrenzen möchten. Dieses Produkt muss einer Entwickler-App hinzugefügt werden. Wenn Sie API-Aufrufe ausführen, die mithilfe von Schlüsseln in der Entwickler-App authentifiziert werden, wird das Kontingent auf diese API-Aufrufe angewendet.
- Melden Sie sich in Ihrem Apigee Edge-Organisationskonto an.
- Öffnen Sie in der Edge-Benutzeroberfläche das Produkt, das mit dem Microgateway-fähigen Proxy verknüpft ist, auf den Sie das Kontingent anwenden möchten.
- Wählen Sie in der Benutzeroberfläche im Menü "Veröffentlichen" die Option Produkte aus.
- Öffnen Sie das Produkt mit der API, auf die Sie das Kontingent anwenden möchten.
- Klicken Sie auf Bearbeiten.
- Geben Sie im Feld „Kontingent“ das Kontingentintervall an. Beispiel: 100 Anfragen pro Minute. Oder 50.000 Anfragen alle 2 Stunden.
- Klicken Sie auf Speichern.
- Achten Sie darauf, dass das Produkt einer Entwickler-App hinzugefügt wurde. Sie benötigen die Schlüssel aus dieser App, um authentifizierte API-Aufrufe durchzuführen.
Beispielkonfiguration für Kontingent
edgemicro: home: ../gateway port: 8000 max_connections: -1 max_connections_hard: -1 logging: level: info dir: /var/tmp stats_log_interval: 60 plugins: dir: ../plugins sequence: - oauth - quota
Konfigurationsoptionen für Kontingente
Zum Konfigurieren des Kontingent-Plug-ins fügen Sie Ihrer Konfigurationsdatei das Element quotas
hinzu, wie im folgenden Beispiel gezeigt:
edgemicro: home: ../gateway port: 8000 max_connections: -1 max_connections_hard: -1 logging: level: info dir: /var/tmp stats_log_interval: 60 plugins: dir: ../plugins sequence: - oauth - quota quotas: bufferSize: hour: 20000 minute: 500 month: 1 default: 10000 useDebugMpId: true failOpen: true isHTTPStatusTooManyRequestEnabled: true ...
Option | Beschreibung |
---|---|
bufferSize |
(Ganzzahl) Mit der Konfiguration quotas: bufferSize: minute: 500 default: 10000 useDebugMpId: true failOpen: true Standardmäßig synchronisiert das Mikrogateway seinen Kontingentzähler alle 5 Sekunden mit Apigee Edge, wenn das Kontingentintervall auf „Minute“ festgelegt ist. Die obige Konfiguration besagt, dass, wenn das Kontingentintervall im API-Produkt auf „Minute“ festgelegt ist, Edge Microgateway mit Edge synchronisiert wird, um die aktuelle Kontingentzahl nach 500 Anfragen oder nach 5 Sekunden zu erhalten, je nachdem, was zuerst eintritt. Weitere Informationen finden Sie unter Informationen zur Zählung von Kontingenten.
Zulässige Zeiteinheiten sind |
isHTTPStatusTooManyRequestEnabled |
Konfiguriert das Kontingent-Plug-in so, dass es bei einem Kontingentverstoß den Antwortstatus HTTP 429 anstelle des Status 403 zurückgibt.
Standardeinstellung:
Wenn das Flag auf
Verwenden Sie die folgende Konfiguration, um den standardmäßigen HTTP-Rückgabestatus in edgemicro: ... quotas: isHTTPStatusTooManyRequestEnabled: true... |
failOpen |
Wenn diese Funktion aktiviert ist und ein Fehler bei der Kontingentverarbeitung auftritt oder wenn die Anforderung zum Anwenden von Kontingenten an Edge Remote-Kontingentzähler nicht aktualisieren kann, wird das Kontingent nur auf der Grundlage lokaler Zählungen verarbeitet, bis die nächste erfolgreiche Remote-Kontingentsynchronisierung erfolgt. In beiden Fällen wird im Anfrageobjekt das Flag quota-failed-open festgelegt.
Legen Sie die folgende Konfiguration fest, um die Kontingent-Funktion „Fail-Open“ zu aktivieren: edgemicro: ... quotas: failOpen: true... |
useDebugMpId |
Setzen Sie dieses Flag auf true , um das Logging der MP-ID (Message processor) in Kontingentantworten zu aktivieren.
Wenn Sie dieses Feature verwenden möchten, müssen Sie die folgende Konfiguration festlegen: edgemicro: ... quotas: useDebugMpId: true ...
Wenn { "allowed": 20, "used": 3, "exceeded": 0, "available": 17, "expiryTime": 1570748640000, "timestamp": 1570748580323, "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a" } |
useRedis |
Wenn true festgelegt ist, verwendet das Plug-in Redis für den Kontingentsicherungsspeicher.
Weitere Informationen finden Sie unter Redis-Sicherungsspeicher für Kontingente verwenden. |
Informationen zur Zählung von Kontingenten
Standardmäßig synchronisiert das Mikrogateway seinen Kontingentzähler alle 5 Sekunden mit Apigee Edge, wenn das Kontingentintervall auf „Minute“ festgelegt ist. Ist das Intervall auf einen Wert festgelegt, der über „Minute“ liegt, z. B. „Woche“ oder „Monat“, beträgt der standardmäßige Aktualisierungszeitraum 1 Minute.
Beachten Sie, dass Sie Kontingentintervalle in den API-Produkten angeben, die in Apigee Edge definiert sind. Kontingentintervalle geben an, wie viele Anfragen pro Minute, Stunde, Tag, Woche oder Monat zulässig sind. Beispiel: Produkt A hat ein Kontingentintervall von 100 Anfragen pro Minute und Produkt B kann ein Kontingentintervall von 10.000 Anfragen pro Stunde haben.
Die YAML-Konfiguration des Edge Microgateway-quota
-Plug-ins legt nicht das Kontingentintervall fest. Sie bietet stattdessen eine Möglichkeit, die Häufigkeit anzupassen, mit der eine lokale Edge Microgateway-Instanz ihre Kontingentzahl mit Apigee Edge synchronisiert.
Angenommen, in Apigee Edge sind drei API-Produkte mit den folgenden Kontingentintervallen definiert:
- Produkt A hat ein Kontingent von 100 Anfragen pro Minute.
- Produkt B hat ein Kontingent von 5.000 Anfragen pro Stunde
- Produkt C hat ein Kontingent von 1.000.000 Anfragen pro Monat
Wie sollte unter Berücksichtigung dieser Kontingenteinstellungen das Edge Microgateway-Plug-in quota
konfiguriert werden? Die Best Practice besteht darin, Edge Microgateway mit Synchronisierungsintervallen zu konfigurieren, die unter den in den API-Produkten definierten Kontingentintervallen liegen. Beispiel:
quotas: bufferSize: hour: 2000 minute: 50 month: 1 default: 10000
Diese Konfiguration definiert die folgenden Synchronisierungsintervalle für die zuvor beschriebenen API-Produkte:
- Für Produkt A ist das Intervall „Minute“ festgelegt. Edge Microgateway synchronisiert nach jeder 50. Anfrage oder nach 5 Sekunden mit Edge, je nachdem, was zuerst eintritt.
- Für Produkt B wird das Intervall "Stunde" verwendet. Edge Microgateway wird nach jeder 2.000. Anfrage oder nach 1 Minute mit Edge synchronisiert, je nachdem, was zuerst eintritt.
- Für Produkt C ist das Intervall „Monat“ festgelegt. Edge Microgateway synchronisiert nach jeder einzelnen Anfrage oder nach 1 Minute mit Edge, je nachdem, was zuerst eintritt.
Bei jeder Synchronisierung einer Mikrogateway-Instanz mit Edge wird die Kontingentanzahl des Mikrogateways auf die abgerufene Kontingentzahl festgelegt.
Mit den Einstellungen für bufferSize
können Sie anpassen, wie der Kontingentzähler mit Edge synchronisiert wird. Bei hohem Traffic-Aufkommen ermöglichen die bufferSize
-Einstellungen, dass der Pufferzähler synchronisiert wird, bevor die standardmäßige zeitbasierte Synchronisierung ausgelöst wird.
Informationen zum Kontingentumfang
Die Kontingentanzahl wird auf eine Umgebung in einer Organisation beschränkt. Um diesen Bereich zu erreichen, erstellt Edge Microgateway eine Kontingentkennung, die eine Kombination aus „org + env + appName + productName“ ist.
Redis-Sicherungsspeicher für Kontingente verwenden
Wenn Sie einen Redis-Sicherungsspeicher für Kontingente verwenden möchten, verwenden Sie dieselbe Konfiguration wie für die Synchronizer-Funktion. Für die Verwendung von Redis als Speicherkontingent ist die folgende grundlegende Konfiguration erforderlich:
edgemicro: redisHost: localhost redisPort: 6379 redisDb: 2 redisPassword: codemaster quotas: useRedis: trueWeitere Informationen zu den
edgemicro.redis*
-Parametern finden Sie unter Synchronisierer verwenden.
Kontingent-Plug-in testen
Wenn das Kontingent überschritten wird, wird der HTTP 403-Status zusammen mit der folgenden Meldung an den Client zurückgegeben:
{"error": "exceeded quota"}
Was ist der Unterschied zwischen Spike Arrest und Kontingent?
Es ist wichtig, das richtige Tool für die jeweilige Aufgabe auszuwählen. Kontingentrichtlinien konfigurieren die Anzahl der Anfragenachrichten, die eine Clientanwendung im Laufe einer Stunde, eines Tages, einer Woche oder eines Monats an eine API senden darf. Die Kontingentrichtlinie erzwingt Nutzungslimits für Clientanwendungen, indem sie einen verteilten Zähler verwaltet, der eingehende Anfragen zählt.
Kontingentrichtlinien verwenden, um Geschäftsverträge oder SLAs mit Entwicklern und Partnern durchzusetzen, statt für die Verwaltung des operativen Traffics. Ein Kontingent kann beispielsweise verwendet werden, um den Traffic für einen kostenlosen Dienst zu begrenzen, während zahlende Kunden vollen Zugriff ermöglichen.
Verwenden Sie Spike Arrest zum Schutz vor plötzlichen Spitzen im API-Traffic. In der Regel wird Spike Arrest verwendet, um mögliche DDoS- oder andere schädliche Angriffe abzuwehren.