Plug-ins verwenden

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

Edge Microgateway Version 3.2.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 erläutert.

Vorhandene mit Edge Microgateway gebündelte Plug-ins

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

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

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.

Spike Arrest-Plug-in hinzufügen

Siehe 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. Weitere Informationen finden Sie unter Wenn Sie mehrere Edge Micro-Prozesse ausführen.
• 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. Siehe auch 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 den Grenzwert innerhalb des angegebenen Zeitintervalls überschreitet, gibt Spike Arrest diese Fehlermeldung mit dem HTTP-Status 503 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.

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 dem Computer, auf dem 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 wenn Sie Edge Microgateway mit der Option --processes 4 starten, legen Sie allow: 25 in der Spike Arrest-Konfiguration fest. Die Faustregel lautet also, den Konfigurationsparameter allow auf den Wert "Gewünschte Spitzenarrest-Anzahl / Anzahl der Prozesse" festzulegen.

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

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

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

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

quotas:
 bufferSize:
  minute: 500
  default: 10000
 useDebugMpId: true
 failOpen: 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. Wenn für das Intervall ein höherer Wert als „Minute“ festgelegt ist, 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 kann ein Kontingentintervall von 100 Anfragen pro Minute und Produkt B 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 die 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:

• Für Produkt A gilt 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 das Edge Microgateway-Plug-in quota unter Berücksichtigung dieser Kontingenteinstellungen konfiguriert werden? Die Best Practice besteht darin, Edge Microgateway mit Synchronisierungsintervallen zu konfigurieren, die kleiner als die in den API-Produkten definierten Kontingentintervalle sind. Beispiel:

quotas:
    bufferSize:
      hour: 2000
      minute: 50
      month: 1
      default: 10000

Diese Konfiguration definiert die folgenden Synchronisierungsintervalle für die zuvor beschriebenen API-Produkte:

• Produkt A ist auf das Intervall „Minute“ eingestellt. Edge Microgateway synchronisiert sich nach jeder 50. Anfrage oder nach 5 Sekunden mit Edge, je nachdem, was zuerst eintritt.
• Für Produkt B ist das Stundenintervall eingestellt. Edge Microgateway synchronisiert nach jeder 2.000. Anfrage oder nach 1 Minute mit Edge, 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.

Jedes Mal, wenn eine Mikrogateway-Instanz mit Edge synchronisiert wird, wird die Kontingentzahl 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 erlauben die bufferSize-Einstellungen dem Pufferzähler die Synchronisierung, bevor die standardmäßige zeitbasierte Synchronisierung ausgelöst wird.

Informationen zum Kontingentumfang

Die Kontingentzahl bezieht sich auf eine Umgebung in einer Organisation. Dazu 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 das Kontingent verwenden möchten, verwenden Sie dieselbe Konfiguration wie für die Synchronizer-Funktion. Die folgende Grundkonfiguration ist erforderlich, um Redis als Kontingentspeicher zu verwenden:

edgemicro:
  redisHost: localhost
  redisPort: 6379
  redisDb: 2
  redisPassword: codemaster

quotas:
  useRedis: true

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.

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.