Einrichten einer Stufe mithilfe der API Gateway-Konsole - Amazon API Gateway
Erstellen einer neuen StufeAktualisieren von StufeneinstellungenLöschen einer Stufe

Einrichten einer Stufe mithilfe der API Gateway-Konsole

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 im Navigationsbereich APIs die Option Stages unter einer API aus.

  3. Wählen Sie im Navigationsbereich Stages die Option Erstellen.

  4. Geben Sie unter Stufe erstellen einen Namen wie beispielsweise prod für Stufenname ein.

    Anmerkung

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

  5. Optional können Sie für Beschreibung der Stufe auch eine Beschreibung der Stufe eingeben.

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

  7. Wählen Sie Create aus.

Aktualisieren von 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 Stage Editor (Stufen-Editor) der API Gateway-Konsole durchführen.

Aktualisieren der Stufeneinstellungen mithilfe der API Gateway-Konsole

Diese Schritte gehen davon aus, dass Sie die API bereits in einer Stufe bereitgestellt haben.

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

  2. Wählen Sie im Bereich APIs die API und daraufhin Stufen aus.

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

  4. Wählen Sie im Bereich Stage Editor die Registerkarte Settings.

  5. Wählen Sie zum Aktivieren der API-Zwischenspeicherung für die Stufe die Option Enable API cache im Abschnitt Cache Settings. Wählen Sie dann die gewünschten Optionen und die zugehörigen Werte für Cache capacity (Cache-Kapazität), Encrypt cache data (Cache-Daten verschlüsseln), Cache-Time-to-Live (TTL) (Cache-Gültigkeitsdauer) sowie die Anforderungen für die Cache-Invalidierung nach Schlüssel.

    Weitere Informationen zu den Cacheeinstellungen auf Stufenebene finden Sie unter Aktivieren von API-Caching für verbesserte Reaktionsfähigkeit.

    Wichtig

    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.

    Tipp

    Sie können auch die aktivierten Cache-Einstellungen auf Stage-Ebene für einzelne Methoden überschreiben. Erweitern Sie dazu im sekundären Navigationsbereich Stages (Stufen) die Stufe und wählen Sie eine Methode aus. Wählen Sie dann im Stufen-Editor die Option Override for this method für Settings. Löschen Sie im Bereich Cache Settings (Cache-Einstellungen) die Option Enable Method Cache (Methoden-Cache aktivieren) oder stellen Sie sie ein oder passen Sie andere gewünschte Optionen an. Weitere Informationen zu den Cacheeinstellungen auf Methodenebene finden Sie unter Aktivieren von API-Caching für verbesserte Reaktionsfähigkeit.

  6. Gehen Sie wie folgt vor, um Amazon CloudWatch Logs für alle Methoden zu aktivieren, die dieser Stufe dieser API Gateway-API zugeordnet sind:

    1. Wählen Sie unter CloudWatch Settings (CloudWatch-Einstellungen) die Option Enable CloudWatch Logs (CloudWatch Logs aktivieren).

      Tipp

      Um CloudWatch-Einstellungen auf Methodenebene zu aktivieren, erweitern Sie die Stufe im sekundären Navigationsbereich Stages (Stufen) und wählen Sie die gewünschten Methoden aus. Wählen Sie im Stufen-Editor Override for this method (Überschreiben für diese Methode) für Settings (Einstellungen). Wählen Sie im Bereich CloudWatch Settings (CloudWatch-Einstellungen) die Option Log to CloudWatch Logs (Protokollieren in CloudWatch Logs) und alle anderen gewünschten Optionen, bevor Sie Save Changes (Änderungen speichern) wählen.

      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.

    2. Wählen Sie für Protokollstufe die Option ERROR (FEHLER) aus, um nur Einträge auf Fehlerebene in CloudWatch Logs zu schreiben, oder INFO, um alle ERROR-Ereignisse sowie zusätzliche Informationsereignisse zu schreiben.

    3. Zur Protokollierung der vollständigen Informationen zu API-Aufrufanforderungen und -reaktionen wählen Sie Log full requests/responses data. Sensitive Daten werden nur protokolliert, wenn die Option Log full requests/responses data (Vollständige Anfragen-/Antwortendaten protokollieren) ausgewählt ist.

      Wichtig

      Wenn Sie Protokolle auf ERROR (FEHLER) festlegen und anschließend Log full requests/responses data (Umfassende Anforderungs-/Antwortdaten protokollieren) auswählen, wird jede Anforderung genauestens protokolliert. Dieses Verhalten ist beabsichtigt.

    4. Damit API Gateway die API-Metriken von API calls, Latency, Integration latency, 400 errors und 500 errors an CloudWatch meldet, wählen Sie die Option Detaillierte CloudWatch-Metriken aktivieren aus. Weitere Informationen über CloudWatch finden Sie im Amazon CloudWatch-Benutzerhandbuch.

    5. Wählen Sie Save Changes. Die neuen Einstellungen werden nach einer neuen Bereitstellung wirksam.

      Wichtig

      Um CloudWatch Logs für alle oder nur einige Methoden 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 ARN (CloudWatch-Protokollrollen-ARN) ein.

      In gängigen Anwendungsszenarien kann die IAM-Rolle beispielsweise die verwaltete Richtlinie von AmazonAPIGatewayPushToCloudWatchLogs anfügen, die die folgende Zugriffsrichtlinienanweisung enthält:

      {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:DescribeLogGroups",
                "logs:DescribeLogStreams",
                "logs:PutLogEvents",
                "logs:GetLogEvents",
                "logs:FilterLogEvents"
            ],
            "Resource": "*"
        }
    ]
}

      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.

  7. Aktivieren der Zugriffsprotokollierung für einen Kinesis Data Firehose-Bereitstellungs-Stream:

    1. Wählen Sie unter Custom Access Logging (Benutzerdefinierte Zugriffsprotokollierung) Enable Access Logging (Aktivieren von Zugriffsprotokollierung) aus.

    2. Geben Sie in Access Log Destination ARN (ARN für Zugriffsprotokollziel) den ARN eines Kinesis Data Firehose-Bereitstellungs-Streams ein. Das ARN-Format ist arn:aws:firehose:{region}:{account-id}:deliverystream/amazon-apigateway-{your-delivery-stream-name}.

      Anmerkung

      Der Name Ihres Kinesis Data Firehose-Bereitstellungs-Streams muss laute amazon-apigateway-{your-delivery-stream-name}.

    3. Geben Sie unter Log Format (Protokollformat) ein Protokollformat ein. Sie können CLF, JSON, XML oder CSV auswählen, um eines der bereitgestellten Beispiele als Leitfaden zu verwenden.

    4. Wählen Sie Save Changes.

  8. Führen Sie zum Einrichten der Drosselungs-Targets auf Stufenebene für alle Methoden, die dieser API zugeordnet sind, im Bereich Default Method Throttling (Standard-Methoden-Drosselung) die folgenden Schritte aus:

    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. Überlegen Sie sich, AWS Budgets zu verwenden, um Kosten zu überwachen und AWS WAF, um API-Anfragen zu verwalten.

    1. Wählen Sie Enable throttling (Ablehnung aktivieren).

    2. Geben Sie für Rate einen Zielsatz ein. 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 angegeben ist.

    3. Geben Sie für Burst eine Ziel-Burst-Rate ein. 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.

  9. Erweitern Sie zum Einstellen der Drosselungs-Targets auf Stufenebene für eine einzelne Methode die Stufe im sekundären Navigationsbereich Stufen, wählen Sie eine Methode aus und klicken Sie unter Einstellungen auf Überschreibung für diese Methode. Wählen Sie im Abschnitt Method Throttling (Methodendrosselung) die gewünschten Optionen aus. Weitere Informationen zur Drosselung finden Sie unter Drosseln der API-Anforderungen für einen besseren Durchsatz.

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

    Anmerkung

    Falls erforderlich, klicken Sie auf Web-ACL erstellen, um die AWS WAF-Konsole in einer neuen Browser-Registerkarte zu öffnen, erstellen Sie die Web-ACL und kehren Sie zur API-Gateway-Konsole zurück, um die Web-ACL mit der Stufe zu verknüpfen.

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

  12. So aktivieren Sie die AWS X-Ray-Ablaufverfolgung für die API-Stufe:

    1. Wählen Sie im Bereich Stage Editor die Registerkarte Logs/Nachverfolgung.

    2. Sie können die X-Ray-Ablaufverfolgung aktivieren, indem Sie Enable X-Ray Tracing (X-Ray-Ablaufverfolgung aktivieren) unter X-Ray Tracing (X-Ray-Ablaufverfolgung) wählen.

    3. So legen Sie Samplingregeln in der X-Ray-Konsole fest: Wählen Sie Set X-Ray Sampling Rules (X-Ray-Samplingregeln festlegen) aus.

    4. Wenn gewünscht, wählen Sie Set X-Ray Sampling Rules (X-Ray-Samplingregeln festlegen) aus und rufen Sie die X-Ray-Konsole zum Konfigurieren von Samplingregeln auf.

    Weitere Informationen finden Sie unter Ablaufverfolgung von Benutzeranforderungen an REST-APIs mithilfe von X-Ray.

  13. Wählen Sie Save Changes. Nachdem Sie die Stufeneinstellungen geändert haben, müssen Sie die API erneut bereitstellen, damit die Änderungen wirksam werden.

Löschen einer Stufe

Wenn Sie eine Stufe nicht mehr benötigen, können Sie diese löschen, um Kosten für ungenutzte Ressourcen zu vermeiden. In den folgenden Schritten wird gezeigt, wie Sie die API Gateway-Konsole zum Löschen einer Stufe verwenden.

Warnung

Das Löschen einer Stufe kann dazu führen, dass ein Teil der oder die gesamte zugehörige API nicht mehr von API-Aufrufern verwendet werden kann. Das Löschen einer Stufe kann nicht rückgängig gemacht werden. Sie können die Stufe jedoch neu erstellen und derselben Bereitstellung zuordnen.

Löschen einer Stufe mithilfe der API Gateway-Konsole

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

  4. Wählen Sie im Bereich Stages die Stufe aus, die Sie löschen möchten, und klicken Sie dann auf Delete Stage.

  5. Wenn Sie dazu aufgefordert werden, wählen Sie Löschen aus.