Plug-ins verwenden

Sie lesen gerade die Dokumentation zu Apigee Edge.
Apigee X-Dokumentation aufrufen info

Edge Microgateway v. 3.2.x

Zielgruppe

Dieses Thema richtet sich an Edge Microgateway-Betreiber, die vorhandene Plug-ins verwenden möchten, die mit dem Microgateway installiert sind. Außerdem werden die Spike-Arrest- und Kontingent-Plug-ins ausführlich beschrieben (beide sind in der Installation enthalten). Wenn Sie als Entwickler neue Plug-ins entwickeln möchten, lesen Sie den Abschnitt 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. Plugin-Module folgen einem einheitlichen Muster und werden an einem Speicherort gespeichert, der Edge Microgateway bekannt ist. So kann das Microgateway sie automatisch erkennen und laden. Edge Microgateway enthält mehrere vorhandene Plug-ins. Sie können auch benutzerdefinierte Plug-ins erstellen, wie unter Benutzerdefinierte Plug-ins entwickeln beschrieben.

Vorhandene Plug-ins, die mit Edge Microgateway gebündelt sind

Bei der Installation von Edge Microgateway werden mehrere vorhandene Plug-ins bereitgestellt. Dazu gehören:

Bestehende Plug-ins finden

Vorhandene Plugins, die mit Edge Microgateway gebündelt sind, befinden sich hier, wobei [prefix] das npm-Präfixverzeichnis 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

Gehen Sie so vor, um Plug-ins hinzuzufügen und zu konfigurieren:

1. Edge Microgateway beenden
2. Öffnen Sie eine Edge Microgateway-Konfigurationsdatei. Weitere Informationen finden Sie unter Konfigurationsänderungen vornehmen.
3. Fügen Sie das Plug-in dem plugins:sequence-Element der Konfigurationsdatei hinzu, wie unten gezeigt. 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 Plugins haben optionale Parameter, die Sie in der Konfigurationsdatei konfigurieren können. Sie können beispielsweise den folgenden Abschnitt hinzufügen, um das Spike-Arrest-Plug-in zu konfigurieren. Weitere Informationen finden Sie unter Spike-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. Speichern Sie 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 npm-Präfixverzeichnis. Wenn Sie dieses Verzeichnis nicht finden können, lesen Sie den Abschnitt Wo ist Edge Microgateway installiert?.

plugins/<plugin_name>/config/default.yaml. Sie können diesen Block beispielsweise in plugins/spikearrest/config/default.yaml einfügen. Er überschreibt alle anderen Konfigurationseinstellungen.

spikearrest:
   timeUnit: hour   
   allow: 10000   
   buffersize: 0

Plugin zur Erkennung von Spitzen verwenden

Das SpikeArrest-Plug-in schützt vor Trafficspitzen. Sie begrenzt die Anzahl der Anfragen, die von einer Edge Microgateway-Instanz verarbeitet werden.

Spike Arrest-Plug-in hinzufügen

Weitere Informationen finden Sie unter Plug-ins hinzufügen und konfigurieren.

Beispielkonfiguration für die Spitzenunterdrückung

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 die Spitzenunterdrückung

• timeUnit: Wie oft das Ausführungsfenster für die Spitze zurückgesetzt wird. Gültige Werte sind „second“ (Sekunde) oder „minute“ (Minute).
• allow: Die maximale Anzahl von Anfragen, die während des timeUnit zulässig sind. Weitere Informationen finden Sie unter Mehrere Edge Micro-Prozesse ausführen.
• bufferSize: (optional, Standardwert = 0) Wenn „bufferSize“ > 0, speichert „spikeArrest“ diese Anzahl von Anfragen in einem Puffer. Sobald das nächste Ausführungsfenster eintritt, werden die gepufferten Anfragen zuerst verarbeitet. Siehe auch Puffer hinzufügen.

Wie funktioniert Spike Arrest?

Mit Spike Arrest können Sie sich vor Trafficspitzen schützen, ohne den Traffic auf eine bestimmte Anzahl von Anfragen zu beschränken. Ihre APIs und Ihr Back-End können eine bestimmte Menge an Traffic bewältigen. Die Spike Arrest-Richtlinie hilft Ihnen dabei, den Traffic auf die gewünschte allgemeine Menge zu begrenzen.

Das Laufzeitverhalten von Spike Arrest unterscheidet sich von dem, was Sie von den Literalwerten pro Minute oder pro Sekunde erwarten können.

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

spikearrest:
   timeUnit: minute
   allow: 30

Beim Testen können Sie 30 Anfragen innerhalb einer Sekunde senden, sofern sie innerhalb einer Minute gesendet wurden. Aber das wird nicht durch die Richtlinie erzwungen. Wenn Sie darüber nachdenken, können 30 Anfragen innerhalb eines Zeitraums von 1 Sekunde in einigen Umgebungen als kleiner Anstieg angesehen werden.

Was geschieht dann tatsächlich? SpikeArrest glättet den zulässigen Traffic, um ein anstiegsartiges Verhalten zu verhindern. Dazu unterteilt es Ihre Einstellungen in kleinere Intervalle:

Raten pro Minute

Minutenraten werden in Anfragen geglättet, die in Intervallen von Sekunden zulässig sind. Zum Beispiel wird 30 Anfragen pro Minute so geglättet:

60 Sekunden (1 Minute) / 30 = 2-Sekunden-Intervalle oder etwa alle 2 Sekunden ist 1 Anfrage zulässig. Eine zweite Anfrage innerhalb von 2 Sekunden schlägt fehl. Außerdem schlägt die 31. Anfrage innerhalb einer Minute fehl.

Preise pro Sekunde

Sekundenraten 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 bzw. etwa 1 Anfrage alle 100 Millisekunden. Eine zweite Anfrage innerhalb von 100ms schlägt fehl. Außerdem schlägt eine 11. Anfrage innerhalb einer Sekunde fehl.

Wenn das Limit überschritten wird

Wenn die Anzahl der Anfragen das Limit 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 legen den Puffer auf 10 fest. Sie werden feststellen, dass die API nicht sofort einen Fehler zurückgibt, wenn Sie das Limit für die Spitzenbelastungsunterdrückung überschreiten. Stattdessen werden Anfragen (bis zur angegebenen Anzahl) gepuffert und verarbeitet, sobald das nächste geeignete 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. Bei der Spike-Arrest-Funktion wird die zulässige Anzahl von Anfragen pro Worker-Prozess berechnet. 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 die Anzahl der Worker-Prozesse jedoch konfigurieren, wenn Sie Edge Micro mit der Option --processes für den Befehl start starten. Wenn beispielsweise die Spike-Arrest-Funktion bei 100 Anfragen in einem bestimmten Zeitraum ausgelöst werden soll und Sie Edge Microgateway mit der Option --processes 4 starten, legen Sie allow: 25 in der Spike-Arrest-Konfiguration fest. Zusammenfassend lässt sich sagen, dass der Konfigurationsparameter allow auf den Wert „Anzahl der gewünschten Spike-Unterdrückungen / Anzahl der Prozesse“ festgelegt werden sollte.

Kontingent-Plug-in verwenden

Ein Kontingent gibt die Anzahl der Anfragenachrichten an, die eine App im Verlauf einer Stunde, eines Tages, einer Woche oder eines Monats an eine API senden darf. Wenn eine App das Kontingentlimit erreicht hat, werden nachfolgende API-Aufrufe abgelehnt. Weitere Informationen finden Sie unter 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

Sie konfigurieren Kontingente in der Apigee Edge-Benutzeroberfläche, in der Sie API-Produkte konfigurieren. Sie müssen wissen, welches Produkt den Microgateway-kompatiblen 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 im Organisationskonto Ihrer Apigee Edge-Organisation an.
2. Öffnen Sie in der Edge-Benutzeroberfläche das Produkt, das dem Microgateway-kompatiblen 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 wird. Sie benötigen die Schlüssel dieser App, um authentifizierte API-Aufrufe auszuführen.

Beispielkonfiguration für Kontingente

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

Wenn Sie das Kontingent-Plug-in konfigurieren möchten, fügen Sie das Element quotas in Ihre Konfigurationsdatei ein, 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"
}

So werden Kontingente gezählt

Standardmäßig synchronisiert das Microgateway seinen Kontingentzähler alle 5 Sekunden mit Apigee Edge, wenn das Kontingentintervall auf „minute“ festgelegt ist. Wenn das Intervall auf eine höhere Ebene als „Minute“ festgelegt ist, z. B. „Woche“ oder „Monat“, beträgt der Standardaktualisierungszeitraum 1 Minute.

Kontingentintervalle werden in den API-Produkten angegeben, die in Apigee Edge definiert sind. Kontingentintervalle geben an, wie viele Anfragen pro Minute, Stunde, Tag, Woche oder Monat zulässig sind. Für Produkt A gilt beispielsweise ein Kontingentintervall von 100 Anfragen pro Minute und für Produkt B ein Kontingentintervall von 10.000 Anfragen pro Stunde.

Mit der YAML-Konfiguration des Edge Microgateway-Plug-ins quota wird das Kontingentintervall nicht festgelegt. Stattdessen können Sie damit die Häufigkeit anpassen, mit der eine lokale Edge Microgateway-Instanz ihr Kontingent 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.
• Für Produkt B gilt ein Kontingent von 5.000 Anfragen pro Stunde.
• Für Produkt C gilt ein Kontingent von 1.000.000 Anfragen pro Monat.

Wie sollte das quota-Plugin für Edge Microgateway angesichts dieser Kontingenteinstellungen konfiguriert werden? Als Best Practice empfiehlt es sich, Edge Microgateway mit Synchronisierungsintervallen zu konfigurieren, die kürzer sind als die in den API-Produkten definierten Kontingentintervalle. 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 wird nach jeder 50. Anfrage oder nach 5 Sekunden mit Edge synchronisiert, je nachdem, was zuerst eintritt.
• Für Produkt B ist das Intervall „Stunde“ festgelegt. 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 „month“ (Monat) festgelegt. Edge Microgateway wird nach jeder einzelnen Anfrage oder nach einer Minute mit Edge synchronisiert, je nachdem, was zuerst eintritt.

Jedes Mal, wenn eine Microgateway-Instanz mit Edge synchronisiert wird, wird die Kontingentanzahl des Microgateways auf die abgerufene Kontingentanzahl festgelegt.

Mit den bufferSize-Einstellungen können Sie anpassen, wie der Kontingentzähler mit Edge synchronisiert wird. Bei hohem Traffic ermöglichen die bufferSize-Einstellungen, dass der Pufferzähler synchronisiert wird, bevor die standardmäßige zeitbasierte Synchronisierung ausgelöst wird.

Kontingentbereich

Die Kontingentanzahl ist auf eine Umgebung in einer Organisation beschränkt. Um diesen Bereich zu erreichen, erstellt Edge Microgateway eine Kontingent-ID, die eine Kombination aus „org + env + appName + productName“ ist.

Redis-Backing Store für Kontingente verwenden

Wenn Sie einen Redis-Backing Store für das Kontingent verwenden möchten, verwenden Sie dieselbe Konfiguration wie für das Synchronizer-Feature. Im Folgenden finden Sie die grundlegende Konfiguration, die für die Verwendung von Redis für die Kontingentspeicherung erforderlich ist:

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

quotas:
  useRedis: true

Kontingent-Plug-in testen

Wenn das Kontingent überschritten wird, wird der HTTP-Status 403 an den Client zurückgegeben, zusammen mit der folgenden Meldung:

{"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 Client-App im Laufe einer Stunde, eines Tages, einer Woche oder eines Monats an eine API senden kann. Die Kontingentrichtlinie erzwingt Nutzungsbeschränkungen für Clientanwendungen, die einen verteilten Zähler zur Verfügung stellen, der eingehende Anfragen erhöht.

Verwenden Sie eine Kontingentrichtlinie, um Geschäftsverträge oder SLAs mit Entwicklern und Partnern zu erzwingen, anstatt für die operative Trafficverwaltung. Mit einem Kontingent können Sie beispielsweise den Traffic für einen kostenlosen Dienst beschränken und gleichzeitig zahlenden Kunden uneingeschränkten Zugriff gewähren.

Mit Spike Arrest können Sie sich vor plötzlichen Spitzen im API-Traffic schützen. Die Spike-Unterdrückung wird in der Regel verwendet, um mögliche DDoS- oder andere böswillige Angriffe abzuwehren.