Plug-ins verwenden

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.

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:

1. Edge Microgateway beenden.
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

4. 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
   

5. Speichere die Datei.
6. 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.

1. Melden Sie sich in Ihrem Apigee Edge-Organisationskonto an.
2. Ö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.
   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.
      
      

3. Klicken Sie auf Speichern.
4. 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
...

quotas:
 bufferSize:
  minute: 500
  default: 10000
 useDebugMpId: true
 failOpen: true

edgemicro:
...
quotas:
  isHTTPStatusTooManyRequestEnabled: true

edgemicro:
...
quotas:
  failOpen: true

edgemicro:
...
quotas:
  useDebugMpId: true
...

{
    "allowed": 20,
    "used": 3,
    "exceeded": 0,
    "available": 17,
    "expiryTime": 1570748640000,
    "timestamp": 1570748580323,
    "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a"
}

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: true

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.