Einrichten einer Stufe für eine REST-API in API Gateway - Amazon API Gateway
Erstellen einer neuen StufeAktualisieren von StufeneinstellungenÜberschreiben der Einstellungen auf Stufenebene

Einrichten einer Stufe für eine REST-API in API Gateway

Eine Stufe ist eine benannte Referenz auf eine Bereitstellung, bei der es sich um einen Snapshot der API handelt. Sie verwenden eine Stufe, um eine bestimmte Bereitstellung zu verwalten und zu optimieren. Beispielsweise können Sie Stufeneinstellungen konfigurieren, um Zwischenspeicherung zu aktivieren, Anforderungsdrosselung anzupassen, Protokollierung zu konfigurieren, Stufenvariablen zu definieren oder ein Canary-Release für Tests anzufügen. Im folgenden Abschnitt sehen Sie, wie Sie Ihre Stufe erstellen und konfigurieren.

Erstellen einer neuen Stufe

Nach der ersten Bereitstellung können Sie weitere Stufen hinzufügen und sie mit vorhandenen Bereitstellungen verknüpfen. Sie können über die API Gateway-Konsole eine neue Stufe erstellen oder während der Bereitstellung einer API eine vorhandene Stufe auswählen. Im Allgemeinen fügen Sie eine neue Stufe zu einer API-Bereitstellung vor der erneuten Bereitstellung der API hinzu. Gehen Sie folgendermaßen vor, um mithilfe der API Gateway-Konsole eine neue Stufe zu erstellen:

  1. Melden Sie sich bei der API Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.

  2. Wählen Sie eine REST-API aus.

  3. Wählen Sie im Hauptnavigationsbereich unter APIs die Option Stages (Stufen).

  4. Wählen Sie im Navigationsbereich Stages (Stufen) die Option Create stage (Stufe erstellen).

  5. Geben Sie unter Stage name (Stufenname) einen Namen ein (z. B. prod).

    Anmerkung

    Phasennamen dürfen nur alphanumerische Zeichen sowie Binde- und Unterstriche enthalten. Die maximale Länge beträgt 128 Zeichen.

  6. (Optional). Geben Sie unter Description (Beschreibung) eine kurze Beschreibung der Stufe ein.

  7. Wählen Sie in der Dropdown-Liste Deployment (Bereitstellung) das Datum und die Uhrzeit der vorhandenen API-Bereitstellung aus, die Sie dieser Stufe zuordnen möchten.

  8. Unter Zusätzliche Einstellungen können Sie zusätzliche Einstellungen für Ihre Stufe angeben.

  9. Wählen Sie Create stage (Stufe erstellen) aus.

Ändern der Stufeneinstellungen

Nach der erfolgreichen Bereitstellung einer API wird die Stufe mit Standardeinstellungen gefüllt. Sie können die Konsole oder die API Gateway-REST-API verwenden, um die Stufeneinstellungen zu ändern, einschließlich des API-Cachings und der Protokollierung. Im Folgenden wird gezeigt, wie Sie dies mithilfe des Stufen-Editor der API Gateway-Konsole durchführen.

  1. Melden Sie sich bei der API Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.

  2. Wählen Sie eine REST-API aus.

  3. Wählen Sie im Hauptnavigationsbereich unter APIs die Option Stages (Stufen).

  4. Wählen Sie im Bereich Stages den Namen der Stufe aus.

  5. Wählen Sie im Abschnitt Stage details (Stufendetails) die Option Edit (Bearbeiten) aus.

  6. (Optional) Bearbeiten Sie die Beschreibung in Stufenbeschreibung.

  7. Ändern Sie die folgenden Einstellungen in Zusätzliche Einstellungen:

    Cache-Einstellungen

    Aktivieren Sie Provision-API-Cache, um API-Zwischenspeicherung für die Stufe zu erlauben. Anschließend konfigurieren Sie Standard-Caching auf Methodenebene, Cache-Kapazität, Cache-Daten verschlüsseln, Cache time-to-live (TTL) sowie alle anderen Anforderungen für eine Cache-Invalidierung pro Schlüssel.

    Caching ist erst dann aktiv, wenn Sie das Standard-Caching auf Methodenebene oder den Cache auf Methodenebene für eine bestimmte Methode aktivieren.

    Weitere Informationen zu Cache-Einstellungen finden Sie unter Cache-Einstellungen für REST-APIs in API Gateway.

    Anmerkung

    Wenn Sie das API-Caching für eine API-Phase aktivieren, wird Ihrem AWS-Konto möglicherweise das API-Caching in Rechnung gestellt. Caching ist für das kostenlose AWS-Kontingent nicht zulässig.

    Drosselungseinstellungen

    Aktivieren Sie die Option Drosselung zum Einrichten der Drosselungs-Targets auf Stufenebene für alle Methoden, die dieser API zugeordnet sind.

    Geben Sie für Rate einen Zielsatz ein. Dies ist die Rate in Anfragen pro Sekunde, mit der Token zum Token-Bucket hinzugefügt werden. Diese Rate auf Stufenebene darf nicht größer sein als die Rate auf Kontoebene, die unter API Gateway-Kontingente für die Konfiguration und Ausführung einer REST-API vorgegeben ist.

    Geben Sie für Burst eine Ziel-Burst-Rate ein. Die Burst-Rate ist die Kapazität des Token-Buckets. Dies ermöglicht mehr Anfragen für einen bestimmten Zeitraum als der Zielsatz. Diese Burst-Rate auf Stufenebene darf nicht größer sein als die Burst-Rate auf Kontoebene, die unter API Gateway-Kontingente für die Konfiguration und Ausführung einer REST-API angegeben ist.

    Anmerkung

    Drosselungsraten sind keine harten Grenzwerte und werden auf Best-Effort-Basis angewendet. In manchen Fällen können Kunden die von Ihnen festgelegten Ziele überschreiten. Verlassen Sie sich nicht auf die Drosselung, um Kosten zu kontrollieren oder den Zugriff auf eine API zu blockieren. Ziehen Sie es in Betracht, AWS Budgets zu verwenden, um Kosten zu überwachen und AWS WAF, um API-Anfragen zu verwalten.

    Firewall- und Zertifikatseinstellungen

    Um eine AWS WAF-Web-ACL mit der Stufe zu verknüpfen, wählen Sie aus der Dropdown-Liste Web ACL (Web-ACL) eine Web-ACL aus. Falls gewünscht, wählen Sie Block API Request if WebACL cannot be evaluated (Fail- Close) (API-Anforderung blockieren, wenn WebACL nicht ausgewertet werden kann (Fehler – Schließen)).

    Um ein Client-Zertifikat für Ihre Stufe auszuwählen, wählen Sie ein Zertifikat aus dem Dropdownmenü Client certificate (Client-Zertifikat) aus.

  8. Klicken Sie auf Weiter.

  9. Überprüfen Sie Ihre Änderungen und klicken Sie dann auf Änderungen speichern.

  10. Gehen Sie wie folgt vor, um Amazon CloudWatch Logs für alle mit dieser Stufe dieser API-Gateway-API zugeordneten Methoden zu aktivieren:

    Anmerkung

    Um CloudWatch Logs zu aktivieren, müssen Sie auch den ARN einer IAM-Rolle angeben, die es API Gateway ermöglicht, im Namen des Benutzers Informationen in CloudWatch Logs zu schreiben. Wählen Sie dazu Settings im Hauptnavigationsbereich APIs. Geben Sie dann den ARN einer IAM-Rolle in das Textfeld CloudWatch log role (CloudWatch-Protokollrollen) ein.

    In gängigen Anwendungsszenarien kann die IAM-Rolle beispielsweise die verwaltete Richtlinie von AmazonAPIGatewayPushToCloudWatchLogs anfügen.

    Die IAM-Rolle muss zudem die folgende Vertrauensstellungsanweisung enthalten:

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "Service": "apigateway.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

    Weitere Informationen über CloudWatch finden Sie im Amazon CloudWatch-Benutzerhandbuch.

  11. Wählen Sie im Dropdown-Menü CloudWatch Logs (CloudWatch-Protokolle) eine Protokollierungsebene aus. Die folgenden Protokollstufen sind verfügbar:

    • Aus - Protokollierung ist für diese Stufe nicht aktiviert.

    • Nur Fehler - Protokollierung ist nur für Fehler aktiviert.

    • Fehler und Informationsprotokolle - Protokollierung ist für alle Ereignisse aktiviert.

  12. Wählen Sie Datenablaufverfolgung aus, damit API Gateway das Datenablaufverfolgungs-Protokoll für Ihre Stufe an CloudWatch meldet. Dies kann zur Fehlerbehebung bei APIs hilfreich sein, kann aber dazu führen, dass sensible Daten protokolliert werden.

    Anmerkung

    Wir empfehlen, Datenablaufverfolgung nicht für Produktions-APIs zu verwenden.

  13. Wählen Sie Detaillierte Metriken aus, damit API Gateway die API-Metriken von API calls, Latency, Integration latency, 400 errors und 500 errors an CloudWatch meldet. Weitere Informationen über CloudWatch finden Sie unter Grundlegende Überwachung und detaillierte Überwachung im Amazon-CloudWatch-Benutzerhandbuch.

    Wichtig

    In Ihrem Konto fallen für den Zugriff auf die CloudWatch-Metriken auf Methodenebene Gebühren an, nicht jedoch für die API-Metriken oder die Metriken auf Stufenebene.

  14. Aktivieren Sie die Benutzerdefinierte Zugriffsprotokollierung, um die Protokollierung für ein Ziel zuzulassen.

  15. Geben Sie für ARN für Zugriffsprotokollziel den ARN einer Protokollgruppe oder eines Firehose-Streams ein.

    Das ARN-Format für Firehose ist arn:aws:firehose:{region}:{account-id}:deliverystream/amazon-apigateway-{your-stream-name}. Der Name Ihres Firehose-Streams muss amazon-apigateway-{your-stream-name} lauten.

  16. Geben Sie unter Log Format (Protokollformat) ein Protokollformat ein. Weitere Informationen zu Beispielprotokollformaten finden Sie unter CloudWatch-Protokollformate für API Gateway.

  17. Wählen Sie zum Aktivieren der AWS X-Ray-Nachverfolgung für die API-Stufe die Option X-Ray tracing (X-Ray-Nachverfolgung). Weitere Informationen finden Sie unter Benutzeranforderungen für Ablaufverfolgung an REST-APIs mithilfe von X-Ray in API Gateway.

  18. Wählen Sie Save Changes (Änderungen speichern). Stellen Sie Ihre API erneut bereit, damit die neuen Einstellungen wirksam werden.

Überschreiben der Einstellungen auf Stufenebene

Nachdem Sie die Einstellungen auf Stufenebene angepasst haben, können Sie sie für jede API-Methode überschreiben. Einige dieser Optionen können zu zusätzlichen Gebühren für Ihr AWS-Konto führen.

  1. Vergrößern Sie die Stufe im sekundären Navigationsbereich, um Methodenüberschreibungen zu konfigurieren und wählen Sie dann eine Methode aus.

    Vergrößern der Stufe im sekundären Navigationsbereich und Auswahl einer Methode.

  2. Klicken Sie für Methodenüberschreibungen auf Bearbeiten.

  3. Wählen Sie eine Protokollebene aus, um für CloudWatch Logs Einstellungen auf Methodenebene zu aktivieren.

  4. Wählen Sie Datenablaufverfolgung aus, um die Protokollierung der Datenablaufverfolgung für Ihre Methode zu aktivieren.

    Anmerkung

    Wir empfehlen, Datenablaufverfolgung nicht für Produktions-APIs zu verwenden.

  5. Klicken Sie auf Detaillierte Metriken, um diese auf Methodenebene zu aktivieren. In Ihrem Konto fallen für den Zugriff auf die CloudWatch-Metriken auf Methodenebene Gebühren an, nicht jedoch für die API-Metriken oder die Metriken auf Stufenebene.

  6. Klicken Sie auf Drosselung, um diese auf Methodenebene zu aktivieren. Geben Sie die entsprechenden Optionen auf Methodenebene ein. Weitere Informationen zur Drosselung finden Sie unter Drosselungsanforderungen für Ihre REST-APIs für verbesserten Durchsatz in API Gateway.

  7. Klicken Sie auf Methoden-Cache aktivieren, um den Cache auf Methodenebene zu konfigurieren. Wenn Sie die Standardeinstellung für den Cache auf Methodenebene in den Stufendetails ändern, hat dies keine Auswirkungen auf diese Einstellung.

  8. Wählen Sie Save (Speichern) aus.