Plug-ins verwenden

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

Edge Microgateway Version 2.4.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 Kontingent-Plug-ins ausführlich behandelt (beide sind in der Installation enthalten). Entwickler, die neue Plug-ins entwickeln möchten, finden 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 hinzufügt. Plug-in-Module folgen einem einheitlichen Muster und werden an einem Speicherort 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

Mehrere vorhandene Plug-ins werden bei der Installation mit Edge Microgateway bereitgestellt. Dazu gehören:

Plug-in Standardmäßig aktiviert Beschreibung
Analytics Ja Sendet Analysedaten von Edge Microgateway an Apigee Edge.
oauth Ja Fügt Edge Microgateway die OAuth-Token- und API-Schlüsselvalidierung hinzu. Weitere Informationen finden Sie unter Edge Microgateway einrichten und konfigurieren.
Kontingent Nein Erzwingt ein Kontingent für Anfragen an Edge Microgateway. Verwendet Apigee Edge zum Speichern und Verwalten der Kontingente. Weitere Informationen finden Sie unter Kontingent-Plug-in verwenden.
Spitze Nein Schützt vor Trafficspitzen und DoS-Angriffen. Weitere Informationen finden Sie unter 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.
Antwort akkumulieren Nein Speichert Antwortdaten in einem einzelnen Objekt, 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 Antwortinhaltsobjekt arbeiten 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 und wandelt Anfrage- oder Antwortdaten in Großbuchstaben um. Es kann jedoch einfach für andere Transformationen wie XML in JSON angepasst werden.
json2xm Nein Transformiert Anfrage- oder Antwortdaten anhand von Akzeptanz- oder Inhaltstyp-Headern. Weitere Informationen finden Sie in der Plug-in-Dokumentation in GitHub.
quota-memory Nein Erzwingt ein Kontingent für Anfragen an Edge Microgateway. Speichert und verwaltet Kontingente im lokalen Arbeitsspeicher.
healthcheck Nein Gibt Informationen zum Edge Microgateway-Prozess zurück, z. B. Arbeitsspeicher- und CPU-Nutzung. Rufen Sie zur Verwendung des Plug-ins die URL /healthcheck auf Ihrer Edge Microgateway-Instanz auf. Dieses Plug-in ist als Beispiel gedacht, mit dem Sie Ihr eigenes Plug-in für die Systemdiagnose implementieren können.

Wo finde ich vorhandene Plug-ins?

Vorhandene Plug-ins, die mit Edge Microgateway gebündelt sind, befinden sich hier, wobei [prefix] das Präfixverzeichnis npm ist. Weitere Informationen finden Sie unter 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:

  1. Beenden Sie Edge Microgateway.
  2. Öffnen Sie eine Edge Microgateway-Konfigurationsdatei. Weitere Informationen zu den Optionen finden Sie unter Konfigurationsänderungen vornehmen.
  3. 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
  1. 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
  1. Speichere die Datei.
  2. Starten Sie Edge Microgateway neu oder laden Sie es neu, je nachdem, welche Konfigurationsdatei Sie bearbeitet haben, wie unter Konfigurationsänderungen vornehmen erläutert.

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. Weitere Informationen finden Sie unter 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

In diesem Abschnitt wird das Spike Arrest-Plug-in erläutert.

Informationen zum Spike Arrest

Spike Arrest schützt vor Verkehrsspitzen. Sie drosselt die Anzahl der Anfragen, die von einer Edge Microgateway-Instanz verarbeitet werden. Weitere Informationen finden Sie unter Wie funktioniert Spike Arrest?. Siehe auch Was ist der Unterschied zwischen Spike Arrest und Kontingent?.

Spike Arrest-Plug-in hinzufügen

Die grundlegenden Schritte für jedes Plug-in 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: Gibt an, wie oft das Ausführungsfenster des Spike Arrests zurückgesetzt wird. Gültige Werte sind Sekunde und Minute.
  • allow: Die maximale Anzahl von Anfragen, die während der timeUnit zulässig sind.
  • bufferSize: (optional, Standard = 0) Wenn bufferSize > 0 ist, speichert der Spike Arrest diese Anzahl von Anfragen in einem Zwischenspeicher. 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 den „Spitzen Arrest“ generell als Schutz vor Traffic-Spitzen vor und nicht als eine Möglichkeit, den Traffic auf eine bestimmte Anzahl von Anfragen zu begrenzen. 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 beim Festsetzen von Laufzeitspitzen unterscheidet sich von dem, was Sie möglicherweise bei den Literalwerten pro Minute oder pro Sekunde sehen, die Sie eingeben.

Angenommen, Sie geben eine Rate von 30 Anfragen pro Minute an:

spikearrest:
   timeUnit: minute
   allow: 30

Beim Testen könnten Sie denken, dass Sie 30 Anfragen in einer Sekunde senden könnten, solange sie innerhalb einer Minute eingehen. Aber auf diese Weise wird die Einstellung nicht durch die Richtlinie erzwungen. Wenn Sie einmal darüber nachdenken, können 30 Anfragen innerhalb eines 1-Sekunden-Zeitraums in einigen Umgebungen als Mini-Spitze angesehen werden.

Was geschieht dann tatsächlich? Um Spitzen-ähnliches Verhalten zu vermeiden, glättet der Spike Arrest den zulässigen Traffic, indem die Einstellungen in kleinere Intervalle unterteilt werden:

Preise pro Minute

Minutenraten werden in zulässige Intervalle von Sekunden für Anfragen geglättet. Beispielsweise werden 30 Anfragen pro Minute so geglättet:

60 Sekunden (1 Minute) ÷ 30 = 2-Sekunden-Intervalle, also etwa eine Anfrage alle 2 Sekunden. Eine zweite Anfrage innerhalb von 2 Sekunden schlägt fehl. Außerdem schlägt eine 31. Anfrage innerhalb einer Minute fehl.

Sekundentakten

Die Raten pro Sekunde werden in Anfragen geglättet, die in Millisekundenintervallen zulässig sind. Beispielsweise wird 10 Anfragen pro Sekunde so geglättet:

1.000 Millisekunden (1 Sekunde) ÷ 10 = Intervalle von 100 Millisekunden, also etwa eine Anfrage alle 100 Millisekunden 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 die Spitzenbenachrichtigung diese Fehlermeldung mit einem 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 zwischengespeichert (bis zur angegebenen Anzahl) und die zwischengespeicherten Anfragen verarbeitet, sobald das nächste passende Ausführungsfenster verfügbar ist. Der Standardwert für bufferSize ist 0.

Kontingent-Plug-in verwenden

In diesem Abschnitt wird das Kontingent-Plug-in erläutert.

Informationen zum Kontingent-Plug-in

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

Die grundlegenden Schritte für jedes Plug-in finden Sie unter Plug-ins hinzufügen und konfigurieren.

Produktkonfiguration in Apigee Edge

Kontingente werden in der Apigee Edge-Benutzeroberfläche konfiguriert, in 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 mit Schlüsseln in der Entwickler-App authentifiziert werden, wird das Kontingent auf diese API-Aufrufe angewendet.

  1. Melden Sie sich in Ihrem Apigee Edge-Organisationskonto an.
  2. Öffnen Sie in der Edge-Benutzeroberfläche das Produkt, das dem Microgateway-fähigen Proxy zugeordnet ist, auf den Sie das Kontingent anwenden möchten.
    1. Wählen Sie in der Benutzeroberfläche im Menü „Veröffentlichen“ die Option Produkte aus.
    2. Öffnen Sie das Produkt mit der API, auf die Sie das Kontingent anwenden möchten.
    3. Klicken Sie auf Bearbeiten.
    4. Geben Sie im Feld Kontingent das Kontingentintervall an. Beispiel: 100 Anfragen pro Minute. Oder 50.000 Anfragen alle 2 Stunden.

  1. Klicken Sie auf Speichern.
  2. Achten Sie darauf, dass das Produkt einer Entwickler-App hinzugefügt wurde. Sie benötigen die Schlüssel aus dieser App für authentifizierte API-Aufrufe.

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

Für das Kontingent-Plug-in gibt es keine zusätzlichen Konfigurationsoptionen.

Kontingent-Plug-in testen

Bei Überschreitung des Kontingents 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 Werkzeug für Ihre 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 Verbrauchslimits für Clientanwendungen, indem ein verteilter Zähler verwaltet wird, der eingehende Anfragen zählt.

Verwenden Sie eine Kontingentrichtlinie, um Geschäftsverträge oder SLAs mit Entwicklern und Partnern durchzusetzen, anstatt für die Verwaltung des operativen Traffics. Beispielsweise kann ein Kontingent verwendet werden, um den Traffic für einen kostenlosen Dienst zu begrenzen, während zahlenden Kunden vollen Zugriff gewährt wird. Weitere Informationen finden Sie unter Kontingent-Plug-in verwenden.

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.