Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
# REST-APIs in API Gateway bereitstellen
Nach der Erstellung der API müssen Sie diese bereitstellen, damit sie von den Benutzern aufgerufen werden kann.
Zum Bereitstellen einer API erstellen Sie eine API-Bereitstellung und verknüpfen sie mit einer Stufe. Eine Stufe ist ein logischer Verweis auf einen Lebenszyklusstatus Ihrer API (z. B, `dev`, `prod`, `beta`, `v2`). API-Stufen werden durch die API-ID und den Stufennamen identifiziert. Sie sind in der URL enthalten, die Sie zum Aufrufen der API verwenden. Jede Stufe ist ein benannter Verweis auf eine Bereitstellung der API und wird für Clientanwendungen zum Aufrufen zur Verfügung gestellt.
**Wichtig**
Jedes Mal, wenn Sie eine API aktualisieren, müssen Sie die API in einer vorhandenen Stufe oder in einer neuen Stufe erneut bereitstellen. Das Aktualisieren einer API umfasst das Ändern von Routen, Methoden, Integrationen, Genehmigern und allen anderen Details abgesehen von Stufeneinstellungen.
Wenn sich Ihre API erweitert, können Sie sie als unterschiedliche Versionen für verschiedene Stufen bereitstellen. Sie können Ihre API-Updates auch als [Canary-Release-Bereitstellung](canary-release.md) bereitstellen. Auf diese Weise können Ihre API-Clients auf derselben Stufe über die Produktionsveröffentlichung auf die Produktionsversion und über die Canary-Veröffentlichung auf die aktualisierte Version zugreifen.
Zum Aufrufen einer bereitgestellten API sendet der Client eine Anforderung mit einer API-URL. Die URL wird anhand eines API-Protokolls (HTTP (S) oder (WSS)), Hostnamens, Stufennamens und (für REST-APIs) Ressourcen-Pfads bestimmt. Der Hostname und der Stufenname bestimmen die Basis-URL der API.
Unter Verwendung des Standarddomänennamens der API weist die Basis-URL einer REST-API (beispielsweise) in einer bestimmten Stufe (`{stageName}`) das folgende Format auf:
```
https://{restapi-id}.execute-api.{region}.amazonaws.com/{stageName}
```
Sie können einen benutzerdefinierten Domänennamen (z. B. `api.example.com`) erstellen und damit den standardmäßigen Hostnamen der API ersetzen, um die Basis-URL der API benutzerfreundlicher zu gestalten. Um mehrere APIs unter dem benutzerdefinierten Domänennamen zu unterstützen, müssen Sie einem Basispfad eine API-Stufe zuordnen.
Mit dem benutzerdefinierten Domänennamen `{api.example.com}` und der einem Basispfad (`{basePath}`) unter dem benutzerdefinierten Domänennamen zugeordneten API-Stufe, ändert sich die Basis-URL einer REST-API wie folgt:
```
https://{api.example.com}/{basePath}
```
Sie können für jede Stufe die API-Leistung optimieren, indem Sie die standardmäßigen Drosselungslimits für Anforderungen auf Kontoebene anpassen und das API-Caching aktivieren. Sie können auch die Protokollierung für API-Aufrufe an CloudTrail oder CloudWatch aktivieren und ein Clientzertifikat für das Backend auswählen, um die API-Anforderungen zu authentifizieren. Außerdem können Sie die Stufeneinstellungen für einzelne Methoden überschreiben und Stufenvariablen definieren, um stufenbezogenen Umgebungskontext zur Laufzeit an die API-Integration zu übergeben.
Stufen ermöglichen eine robuste Versionskontrolle Ihrer API. Sie können beispielsweise eine API für eine `test`- und eine `prod`-Stufe bereitstellen und die `test`-Stufe als Test-Build und die `prod`-Stufe als stabilen Build verwenden. Nachdem die Aktualisierungen den Test bestanden haben, können Sie die `test`-Stufe auf `prod` hochstufen. Eine Hochstufung kann durch die erneute Bereitstellung der API auf der `prod`-Stufe oder durch Aktualisieren eines Stufenvariablenwerts vom Stufennamen `test` auf `prod` erfolgen.
In diesem Abschnitt wird die Bereitstellung einer API mithilfe der [API Gateway-Konsole](https://console.aws.amazon.com/apigateway) oder durch Aufrufen der [API Gateway-REST-API](https://docs.aws.amazon.com/apigateway/latest/api/) beschrieben. Informationen zur Verwendung anderer Tools finden Sie in der Dokumentation der [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/apigateway/) oder eines [AWS SDK](https://aws.amazon.com/developer/tools/#sdk).
**Topics**
+ [Eine Bereitstellung für eine REST-API in API Gateway erstellen](set-up-deployments.md)
+ [Einrichten einer Stufe für eine REST-API in API Gateway](set-up-stages.md)
+ [Einrichten einer API Gateway-Canary-Release-Bereitstellung](canary-release.md)
+ [REST-Updates APIs , die eine erneute Bereitstellung erfordern](updating-api.md)
# Eine Bereitstellung für eine REST-API in API Gateway erstellen
In API Gateway wird eine REST-API-Bereitstellung durch eine [Deployment](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html)-Ressource dargestellt. Sie ähnelt einer ausführbaren Datei einer API, die durch eine [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)-Ressource dargestellt wird.
Damit der Client Ihre API aufrufen kann, müssen Sie eine Bereitstellung erstellten und ihr eine Stufe zuordnen. Eine Stufe wird durch eine [Stage](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html)-Ressource dargestellt. Sie stellt einen Snapshot der API dar, einschließlich Methoden, Integrationen, Modellen, Mapping-Vorlagen und Lambda-Genehmigern (ehemals als benutzerdefinierte Genehmiger bezeichnet). Wenn Sie die API aktualisieren, können Sie sie erneut bereitstellen, indem Sie der vorhandenen Bereitstellung eine neue Stufe zuordnen. Das Erstellen einer Stufe wird in [Einrichten einer Stufe für eine REST-API in API Gateway](set-up-stages.md) beschrieben.
**Topics**
+ [Eine Bereitstellung auswählen](#create-deployment)
+ [Nächste Schritte für Ihre API-Bereitstellung](#apigateway-deployment-next-steps)
## Eine Bereitstellung auswählen
Im folgenden Verfahren wird gezeigt, wie Sie eine Bereitstellung für eine REST-API erstellen.
------
#### [ AWS-Managementkonsole ]
Sie müssen eine REST API erstellt haben, bevor Sie sie erstmals bereitstellen können. Weitere Informationen finden Sie unter [Entwickeln Sie REST APIs in API Gateway](rest-api-develop.md).
Mit der API Gateway-Konsole können Sie eine API bereitstellen, indem Sie eine Bereitstellung erstellen und sie mit einer neuen oder bestehenden Stufe verknüpfen.
1. Melden Sie sich bei der API-Gateway-Konsole unter [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) an.
1. Wählen Sie im **APIs**-Navigationsbereich die API, die Sie bereitstellen möchten.
1. Wählen Sie im Bereich **Ressourcen** die Option **API bereitstellen** aus.
1. Wählen Sie für **Stufe** eine der folgenden Optionen aus:
1. Um eine neue Stufe zu erstellen, wählen Sie **Neue Stufe** aus und geben Sie dann einen Namen in das Feld **Stufenname** ein. Optional können Sie unter **Beschreibung der Bereitstellung** eine Beschreibung für die Bereitstellung angeben.
1. Um eine bestehende Stufe auszuwählen, wählen Sie den Namen der Stufe im Drop-down-Menü aus. Sie sollten unter **Beschreibung der Bereitstellung** eine Beschreibung der neuen Bereitstellung angeben.
1. Um eine Bereitstellung zu erstellen, die keiner Stufe zugeordnet ist, wählen Sie **Keine Stufe** aus. Später können Sie diese Bereitstellung einer Stufe zuordnen.
1. Wählen Sie **Deploy (Bereitstellen)** aus.
------
#### [ AWS CLI ]
Wenn Sie eine Bereitstellung erstellen, instanziieren Sie die [Deployment](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html)-Ressource.
Der folgende [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html)-Befehl erstellt eine neue Bereitstellung:
```
aws apigateway create-deployment --rest-api-id rest-api-id
```
Sie können die API nicht aufrufen, bis Sie dieser Bereitstellung eine Stufe zugewiesen haben. Diesen Vorgang können Sie bei einer bereits vorhandenen Stufe durch Aktualisieren der Eigenschaft [deploymentId](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId) der Stufe mit der neu erstellten Bereitstellungs-ID ausführen. Der folgende [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html)-Befehl aktualisiert die Stufe mit einer neuen Bereitstellung. In der Konsole wird dies als **Aktive Bereitstellung** bezeichnet.
```
aws apigateway update-stage \
--rest-api-id rest-api-id \
--stage-name 'stage-name' \
--patch-operations op='replace',path='/deploymentId',value='deployment-id'
```
Beim Erstellen Ihrer Bereitstellung können Sie diese auch gleichzeitig mit einer neuen Stufe verknüpfen. Der folgende [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html)-Befehl erstellt eine neue Bereitstellung und verknüpft sie mit einer neuen Stufe namens `beta`:
```
aws apigateway create-deployment \
--rest-api-id rest-api-id \
--stage-name beta
```
------
Eine erneute API-Bereitstellung wird mit denselben Schritten durchgeführt. Sie können dieselbe Stufe verwenden.
## Nächste Schritte für Ihre API-Bereitstellung
Im Folgenden finden Sie die nächsten Schritte für Ihre API-Bereitstellung.
Ändern der Stufeneinstellungen
Nachdem eine API bereitgestellt wurde, können Sie die Stufeneinstellungen ändern, um den API-Cache, die Protokollierung oder die Anforderungsdrosselung zu aktivieren oder zu deaktivieren. Sie können auch ein Client-Zertifikat wählen, damit das Backend API Gateway authentifizieren und Stufenvariablen festlegen kann, um den Bereitstellungskontext während der Laufzeit an die API-Integration zu übergeben. Weitere Informationen finden Sie unter [Ändern der Stufeneinstellungen](set-up-stages.md#how-to-stage-settings).
Nachdem Sie die Stufeneinstellungen geändert haben, müssen Sie die API erneut bereitstellen, damit die Änderungen wirksam werden.
Wenn die aktualisierten Einstellungen, wie die Aktivierung der Protokollierung, eine neue IAM-Rolle erfordern, können Sie die erforderliche IAM-Rolle ohne erneute Bereitstellung der API hinzufügen. Allerdings kann es einige Minuten dauern, bis die neue IAM-Rolle wirksam wird. Bevor dies jedoch der Fall ist, werden Spuren Ihrer API-Aufrufe nicht protokolliert, auch wenn Sie die Protokollierung aktiviert haben.
Andere Kombinationen für die Bereitstellungsstufe auswählen
Da eine Bereitstellung einen API-Snapshot darstellt und eine Stufe einen Pfad in einen Snapshot definiert, können Sie verschiedene Bereitstellungsstufen-Kombinationen wählen, um zu steuern, wie Benutzer verschiedene Versionen der API aufrufen. Dies ist beispielsweise nützlich, wenn Sie den API-Status auf eine frühere Bereitstellung zurücksetzen oder eine "private Zweigstelle" der API in eine öffentliche integrieren möchten.
Im folgenden Verfahren wird gezeigt, wie Sie dies mithilfe des **Stage Editor (Stufen-Editor)** in der API Gateway-Konsole tun. Es wird davon ausgegangen, dass Sie eine API mehr als einmal bereitgestellt haben.
1. Wenn Sie sich noch nicht im Bereich **Stufen** befinden, wählen Sie im Hauptnavigationsbereich die Option **Stufen** aus.
1. Wählen Sie die Stufe aus, die Sie aktualisieren möchten.
1. Wählen Sie auf der Registerkarte **Bereitstellungsverlauf** die Bereitstellung aus, die die Stufe verwenden soll.
1. Wählen Sie **Aktive Bereitstellung ändern**.
1. Bestätigen Sie, dass Sie die aktive Bereitstellung ändern möchten, und wählen Sie **Aktive Bereitstellung ändern** im Dialogfeld **Bereitstellung aktivieren** aus.
Übergeben Sie bereitstellungsspezifische Daten an Ihre API.
Für eine Bereitstellung können Sie Stufenvariablen so festlegen oder ändern, dass bereitstellungsspezifische Daten während der Laufzeit an die API-Integration weitergeben werden. Sie können dies auf der Registerkarte **Stage Variables** im **Stage Editor** tun. Weitere Informationen finden Sie in den Anweisungen in [Stufenvariablen für eine REST-API in API Gateway verwenden](stage-variables.md).
# 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](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html), 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 Gateway-Konsole unter [https://console.aws.amazon.com/apigatewayan](https://console.aws.amazon.com/apigateway).
1. Wählen Sie eine REST-API aus.
1. Wählen Sie im Hauptnavigationsbereich unter APIs die Option **Stages** (Stufen).
1. Wählen Sie im Navigationsbereich **Stages** (Stufen) die Option **Create stage** (Stufe erstellen).
1. 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.
1. (Optional). Geben Sie unter **Description** (Beschreibung) eine kurze Beschreibung der Stufe ein.
1. 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.
1. Unter **Zusätzliche Einstellungen** können Sie zusätzliche Einstellungen für Ihre Stufe angeben.
1. 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. Wenn Sie den Standardendpunkt Ihrer REST-API geändert haben, wird die Änderung beim Aktualisieren einer Stufe auf alle Stufen Ihrer API übertragen. 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 Gateway-Konsole unter [https://console.aws.amazon.com/apigatewayan](https://console.aws.amazon.com/apigateway).
1. Wählen Sie eine REST-API aus.
1. Wählen Sie im Hauptnavigationsbereich unter APIs die Option **Stages** (Stufen).
1. Wählen Sie im Bereich **Stages** den Namen der Stufe aus.
1. Wählen Sie im Abschnitt **Stage details** (Stufendetails) die Option **Edit** (Bearbeiten) aus.
1. (Optional) Bearbeiten Sie die Beschreibung in **Stufenbeschreibung**.
1. Ä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. Konfigurieren Sie dann das **Standard-Caching auf Methodenebene**, die **Cachekapazität**, die **Cache-Daten verschlüsseln**, den **Cache time-to-live (TTL)** sowie alle Anforderungen für die 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](api-gateway-caching.md).
Wenn Sie API-Caching für eine API-Phase aktivieren, wird Ihrem AWS Konto möglicherweise das API-Caching in Rechnung gestellt. Caching kommt nicht für das kostenlose Kontingent in Frage. AWS
**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](api-gateway-request-throttling.md#apig-request-throttling-account-level-limits), die unter [Kontingente für die Konfiguration und Ausführung einer REST-API in API Gateway](api-gateway-execution-service-limits-table.md) 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](api-gateway-request-throttling.md#apig-request-throttling-account-level-limits), die unter [Kontingente für die Konfiguration und Ausführung einer REST-API in API Gateway](api-gateway-execution-service-limits-table.md) angegeben ist.
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](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) zu verwenden, um Kosten zu überwachen und [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html), um API-Anfragen zu verwalten.
**Firewall- und Zertifikatseinstellungen**
Um der Phase eine AWS WAF Web-ACL zuzuordnen, wählen Sie eine Web-ACL aus der **Dropdownliste 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.
1. Klicken Sie auf **Weiter**.
1. Überprüfen Sie Ihre Änderungen und klicken Sie dann auf **Änderungen speichern**.
1. Um Amazon CloudWatch Logs für alle Methoden zu aktivieren, die mit dieser Phase dieser API-Gateway-API verknüpft sind, wählen Sie im Abschnitt **Logs and tracing** die Option **Bearbeiten**.
**Anmerkung**
Um CloudWatch Logs zu aktivieren, müssen Sie auch den ARN einer IAM-Rolle angeben, die es API Gateway ermöglicht, im Namen Ihres Benutzers Informationen in CloudWatch Logs zu schreiben. Wählen Sie dazu im **APIs**Hauptnavigationsbereich die Option **Einstellungen** aus. Geben Sie dann für die **CloudWatch Protokollrolle** den ARN einer IAM-Rolle ein.
Für allgemeine Anwendungsszenarien könnte die IAM-Rolle die verwaltete Richtlinie von [Amazon APIGateway PushToCloudWatchLogs](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAPIGatewayPushToCloudWatchLogs.html) anhängen.
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 zu CloudWatch finden Sie im *[ CloudWatch Amazon-Benutzerhandbuch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)*.
1. Wählen Sie im Dropdownmenü Protokolle eine **CloudWatch 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.
1. Wählen Sie **Datenverfolgung** aus, damit API Gateway an CloudWatch die Datenverfolgungsprotokollierung für Ihre Phase berichtet. Dies kann bei der Fehlerbehebung nützlich sein APIs, kann jedoch dazu führen, dass sensible Daten protokolliert werden.
**Anmerkung**
Wir empfehlen, die **Datenverfolgung** nicht für die Produktion APIs zu verwenden.
1. Wählen Sie **Detaillierte Metriken** aus, damit API Gateway über CloudWatch die API-Metriken von `API calls` `Latency``Integration latency`,`400 errors`, und berichtet`500 errors`. Weitere Informationen zu CloudWatch finden Sie in den [Abschnitten Grundlegende Überwachung und detaillierte Überwachung](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-metrics-basic-detailed.html) im CloudWatch Amazon-Benutzerhandbuch.
**Wichtig**
Ihr Konto wird für den Zugriff auf Metriken auf Methodenebene belastet, nicht jedoch für CloudWatch Metriken auf API- oder Stufenebene.
1. Aktivieren Sie die **Benutzerdefinierte Zugriffsprotokollierung**, um die Protokollierung für ein Ziel zuzulassen.
1. 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.
1. Geben Sie unter **Log Format** (Protokollformat) ein Protokollformat ein. Weitere Informationen zu Beispielprotokollformaten finden Sie unter [CloudWatch Protokollformate für API Gateway](set-up-logging.md#apigateway-cloudwatch-log-formats).
1. Wählen Sie zum Aktivieren der [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html)-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](apigateway-xray.md).
1. Wählen Sie **Änderungen speichern ** aus. 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. Bei einigen dieser Optionen können zusätzliche Gebühren für Sie anfallen AWS-Konto.
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.\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/method-override-view-new-console.png)
1. Klicken Sie für **Methodenüberschreibungen** auf **Bearbeiten**.
1. Um CloudWatch Einstellungen auf Methodenebene zu aktivieren, wählen Sie unter **CloudWatch Protokolle** eine Protokollierungsebene aus.
1. Wählen Sie **Datenablaufverfolgung** aus, um die Protokollierung der Datenablaufverfolgung für Ihre Methode zu aktivieren.
**Anmerkung**
Wir empfehlen, die **Datenverfolgung** nicht für Produktionszwecke zu verwenden. APIs
1. Klicken Sie auf **Detaillierte Metriken**, um diese auf Methodenebene zu aktivieren. Ihr Konto wird für den Zugriff auf Metriken auf Methodenebene belastet, nicht jedoch für CloudWatch Metriken auf API- oder Stufenebene.
1. 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 [Drosseln Sie Anfragen an Ihren REST APIs für einen besseren Durchsatz in API Gateway](api-gateway-request-throttling.md).
1. 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.
1. Wählen Sie **Speichern**.
# Fügen Sie eine API-Gateway-REST-API als Ziel für Amazon Bedrock AgentCore Gateway hinzu
Ein Amazon Bedrock AgentCore Gateway bietet Entwicklern von KI-Agenten eine sichere Möglichkeit, Ihren API-Gateway-REST APIs als Model Context Protocol (MCP) -kompatible Tools bereitzustellen. AgentCore Gateway verwendet Ziele, um Tools zu definieren. Wenn Sie Ihre Phase als Ziel hinzufügen, wird Ihr Gateway zu einer einzigen MCP-URL, die einem Agenten den Zugriff auf die Tools ermöglicht. Weitere Informationen finden Sie unter [API Gateway REST API-Stufen als Ziele](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-api-gateway.html) im *Amazon Bedrock AgentCore Gateway Developer Guide*.
API-Gateway-Ziele verbinden Ihr AgentCore Gateway mit Phasen Ihres REST APIs. Sie können die gesamte Phase als Ziel einbeziehen oder Ressourcen auswählen. Nachdem Sie das API-Gateway-Ziel erstellt haben, übersetzt AgentCore Gateway eingehende MCP-Anfragen in HTTP-Anfragen und kümmert sich um die Formatierung der Antwort. MCP-Clients können die API-Dokumentation mithilfe der `tools/list` Methode abrufen und mithilfe der Methode aufrufen APIs . `tools/call`
## Überlegungen
Die folgenden Überlegungen können sich auf Ihre Verwendung auswirken, wenn Sie einem Gateway eine Phase als Ziel hinzufügen: AgentCore
+ Sie müssen bereits über ein AgentCore Gateway verfügen.
+ Nur öffentliche APIs REST-Dateien werden unterstützt.
+ Der Standardendpunkt Ihrer API kann nicht deaktiviert werden.
+ Für jede Methode Ihrer API muss entweder ein [Operationsname](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html#apigw-PutMethod-request-operationName) definiert sein, oder Sie müssen eine Namensüberschreibung erstellen, wenn Sie Ihre Phase als Ziel hinzufügen. Dieser Name wird als Name des Tools verwendet, mit dem Agenten mit Ihrer Methode interagieren.
+ Sie können die Typen`API_KEY`,`NO_AUTH`, oder `GATEWAY_IAM_ROLE` Credential Provider für Outbound Auth verwenden, um Ihrem Gateway den Zugriff auf Ihre API zu ermöglichen. Der Anbieter für `API_KEY` Anmeldeinformationen wird von Gateway definiert. AgentCore Sie können Ihren vorhandenen API-Gateway-API-Schlüssel verwenden. Weitere Informationen finden Sie unter [Outbound Auth einrichten](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-outbound-auth.html).
+ Wenn Sie einen Amazon Cognito Cognito-Benutzerpool oder einen Lambda-Autorisierer verwenden, um den Zugriff auf Ihre API zu kontrollieren, können MCP-Clients nicht darauf zugreifen.
+ Ihre API muss sich im selben Konto und in derselben Region wie Ihr Gateway befinden. AgentCore
## Fügen Sie eine API-Stufe als Ziel für ein AgentCore Gateway hinzu
Das folgende Verfahren zeigt, wie Sie eine API-Stufe als Ziel für ein AgentCore Gateway hinzufügen.
**So fügen Sie eine API-Stufe als Ziel für ein AgentCore Gateway hinzu**
1. Melden Sie sich bei der API Gateway Gateway-Konsole unter [https://console.aws.amazon.com/apigatewayan](https://console.aws.amazon.com/apigateway).
1. Wählen Sie eine REST-API aus, die in einer Phase bereitgestellt wird.
1. Klicken Sie im Hauptnavigationsbereich auf **Stufen**.
1. Wählen Sie **Stage-Aktionen** und dann **Create MCP-Ziel** aus.
1. Wählen Sie für **AgentCore Gateway** ein AgentCore Gateway aus.
1. Geben Sie **unter Zielname** einen Zielnamen ein.
1. Geben Sie **unter Zielbeschreibung** eine Beschreibung ein.
1. Behalten Sie die bereitgestellte API und die bereitgestellte Phase bei.
1. **Wählen Sie unter API-Ressourcen** auswählen die Ressourcen Ihrer API aus, auf die Agenten, die Ihr AgentCore Gateway verwenden, zugreifen können.
Wenn Sie keine Ressource auswählen, kann ein Agent die Dokumentation nicht einsehen oder den Endpunkt aufrufen.
1. Die Kombination aus Ressource und Methode sind die Operationen für das Tool. Wenn Ihre Operation keinen Namen hat, erstellen Sie eine Namensüberschreibung.
Sie können auch einen Operationsnamen für eine Methode definieren, wenn Sie sie erstellen.
1. **Wählen Sie für die **Konfiguration „Outbound Auth**“ entweder „**IAM-Rolle**“, „**Keine Autorisierung**“ oder „API-Schlüssel“.**
1. Wählen Sie **Ziel erstellen**.
Um alle AgentCore Gateways anzuzeigen, die Zugriff auf Ihre haben APIs, wählen Sie im Hauptnavigationsbereich den Abschnitt **MCP-Ziele** aus. In diesem Abschnitt können Sie ein MCP-Ziel für jede API in Ihrer Region erstellen, die in einer Phase bereitgestellt wird. Wählen Sie **Create MCP-Ziel** aus und folgen Sie den vorherigen Schritten.
Sie können auch die verfügbaren Tools für Ihr Ziel anzeigen und Ihr Ziel in der AgentCore Gateway-Konsole bearbeiten. Weitere Informationen finden [Sie unter Ziele zu einem vorhandenen AgentCore Gateway hinzufügen](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-building-adding-targets.html).
# 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.
1. Melden Sie sich bei der API Gateway-Konsole unter [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) an.
1. Wählen Sie eine REST-API aus.
1. Klicken Sie im Hauptnavigationsbereich auf **Stages** (Stufen).
1. Wählen Sie im Bereich **Stages** (Stufen) die Stufe aus, die Sie löschen möchten, und klicken Sie dann unter **Stage actions** (Stufenaktionen) auf **Delete stage** (Stufe löschen).
1. Geben Sie bei der Aufforderung **confirm** ein und klicken Sie dann auf **Delete** (Löschen).
# Tags für eine API-Stufe in API Gateway einrichten
In API Gateway können Sie einer API-Stufe ein Tag hinzufügen, das Tag aus der Stufe entfernen oder das Tag anzeigen. Dazu können Sie die API-Gateway-Konsole, die AWS CLI/das SDK oder die API-Gateway-REST-API verwenden.
Eine Stufe kann auch Tags von der übergeordneten REST-API erben. Weitere Informationen finden Sie unter [Tag-Vererbung in der Amazon API Gateway V1-API](apigateway-tagging-supported-resources.md#apigateway-tagging-inheritance).
Weitere Informationen über das Markieren mit Tags von API Gateway-Ressourcen finden Sie unter [API Gateway-Ressourcen taggen](apigateway-tagging.md).
**Topics**
+ [Einrichten von Tags für eine API-Stufe mit der API-Gateway-Konsole](#set-up-tags-using-console)
+ [Tags für eine API-Stufe mithilfe der AWS CLI-Konsole einrichten](#set-up-tags-using-cli)
+ [Einrichten von Tags für eine API-Stufe mit der API-Gateway-REST-API](#set-up-tags-using-api)
## Einrichten von Tags für eine API-Stufe mit der API-Gateway-Konsole
Die folgende Vorgehensweise beschreibt, wie Sie Tags für eine API-Stufe einrichten.
**So richten Sie Tags für eine API-Stufe mithilfe der API Gateway-Konsole ein**
1. Melden Sie sich bei der API Gateway-Konsole an.
1. Wählen Sie eine vorhandene API aus oder erstellen Sie eine neue API, die Ressourcen, Methoden und die entsprechenden Integrationen enthält.
1. Wählen Sie eine Stufe aus oder stellen Sie die API in einer neuen Stufe bereit.
1. Klicken Sie im Hauptnavigationsbereich auf **Stages** (Stufen).
1. Wählen Sie die Registerkarte **Tags** aus. Möglicherweise müssen Sie die rechte Pfeiltaste wählen, um die Registerkarte anzuzeigen.
1. Wählen Sie **Tags verwalten** aus.
1. Klicken Sie im **Tag Editor** (Tag-Editor) auf **Add Tag** (Tag hinzufügen). Geben Sie einen Tag-Schlüssel (z. B. `Department`) in das Feld **Schlüssel** und einen Tag-Wert (z. B. `Sales`) in das Feld **Wert** ein. Wählen Sie **Save** (Speichern) aus, um das Tag zu speichern.
1. Wiederholen Sie bei Bedarf Schritt 5, um der API-Stufe weitere Tags hinzuzufügen. Die maximale Anzahl der Tags pro Stufe beträgt 50.
1. Um ein vorhandenes Tag aus der Stufe zu entfernen, wählen Sie **Remove** (Entfernen) aus.
1. Wenn die API zuvor in der API Gateway-Konsole bereitgestellt wurde, müssen Sie sie erneut implementieren, damit die Änderungen wirksam werden.
## Tags für eine API-Stufe mithilfe der AWS CLI-Konsole einrichten
Sie können Tags für eine API-Stufe mithilfe von AWS CLI und dem Befehl [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) oder [tag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/tag-resource.html) erstellen. Sie können einen oder mehrere Tags aus einer API-Stufe mithilfe des Befehls [untag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/untag-resource.html) löschen.
Der folgende [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html)-Befehl fügt beim Erstellen einer `test`-Stufe ein Tag hinzu:
```
aws apigateway create-stage --rest-api-id abc1234 --stage-name test --description 'Testing stage' --deployment-id efg456 --tag Department=Sales
```
Der folgende [tag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/tag-resource.html)-Befehl fügt einer `prod`-Stufe ein Tag hinzu:
```
aws apigateway tag-resource --resource-arn arn:aws:apigateway:us-east-2::/restapis/abc123/stages/prod --tags Department=Sales
```
Der folgende [untag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/untag-resource.html)-Befehl entfernt das Tag `Department=Sales` aus der `test`-Stufe:
```
aws apigateway untag-resource --resource-arn arn:aws:apigateway:us-east-2::/restapis/abc123/stages/test --tag-keys Department
```
## Einrichten von Tags für eine API-Stufe mit der API-Gateway-REST-API
Sie können Tags für eine API-Stufe mit Hilfe der API Gateway-REST-API einrichten, indem Sie eine der folgenden Aktionen ausführen:
+ Rufen Sie [https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html) auf, um eine API-Stufe mit einem Tag zu versehen.
+ Rufen Sie [https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html) auf, um einen oder mehrere Tags aus einer API-Stufe zu löschen.
+ Rufen Sie [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html) auf, um einen oder mehrere Tags zu einer API-Stufe, die Sie erstellen, hinzuzufügen.
Sie können außerdem [https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html](https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html) aufrufen, um Tags in einer API-Stufe zu beschreiben.
### Tag zu einer API-Stufe hinzufügen
Nach Bereitstellung einer API (`m5zr3vnks7`) für eine Stufe (`test`) versehen Sie die Stufe durch Aufruf von [https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html) mit einem Tag. Die erforderliche Amazon-Ressourcenname (ARN) (`arn:aws:apigateway:us-east-1::/restapis/m5zr3vnks7/stages/test`) der Stufe muss URL-codiert sein (`arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftest`).
```
PUT /tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftest
{
"tags" : {
"Department" : "Sales"
}
}
```
Sie können auch die vorherige Anforderung verwenden, um einen bestehenden Tag auf einen neuen Wert zu aktualisieren.
Sie können Tags zu einer Stufe hinzufügen, wenn Sie [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html) aufrufen, um die Stufe zu erstellen:
```
POST /restapis//stages
{
"stageName" : "test",
"deploymentId" : "adr134",
"description" : "test deployment",
"cacheClusterEnabled" : "true",
"cacheClusterSize" : "500",
"variables" : {
"sv1" : "val1"
},
"documentationVersion" : "test",
"tags" : {
"Department" : "Sales",
"Division" : "Retail"
}
}
```
### Tag von einer API-Stufe entfernen
Rufen Sie [https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html) auf, um den `tags:untag`-Tag von der Stufe zu entfernen:
```
DELETE /tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftest?tagKeys=Department
Host: apigateway.us-east-1.amazonaws.com
Authorization: ...
```
Um mehrere Tags zu entfernen, verwenden Sie eine kommagetrennte Liste mit Tag-Schlüsseln im Abfrageausdruck (zum Beispiel `?tagKeys=Department,Division,…`).
### Beschreiben von Tags für eine API-Stufe
Um existierende Tags einer bestehenden Stufe zu beschreiben, rufen Sie [https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html](https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html) auf:
```
GET /tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftags
Host: apigateway.us-east-1.amazonaws.com
Authorization: ...
```
Eine erfolgreiche Antwort ähnelt dem folgenden Beispiel:
```
200 OK
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-tags-{rel}.html",
"name": "tags",
"templated": true
},
"tags:tag": {
"href": "/tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftags"
},
"tags:untag": {
"href": "/tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftags{?tagKeys}",
"templated": true
}
},
"tags": {
"Department": "Sales"
}
}
```
# Stufenvariablen für eine REST-API in API Gateway verwenden
Bei Stufenvariablen handelt es sich um Wert-Paare, die Sie als Konfigurationsattribute für eine REST-API-Bereitstellungsstufe definieren können. Sie weisen dasselbe Verhalten auf wie Umgebungsvariablen und können für die API-Einrichtung und Mapping-Vorlagen verwendet werden. Mit den Bereitstellungsstufen in API Gateway können Sie für jede API mehrere Freigabestufen verwalten. Über die Stufenvariablen können Sie eine API-Bereitstellungsstufe für die Interaktion mit verschiedenen Backend-Endpunkten konfigurieren.
Stage-Variablen sind nicht dazu gedacht, für sensible Daten wie Anmeldeinformationen verwendet zu werden. Verwenden Sie einen AWS Lambda Autorisierer, um sensible Daten an Integrationen weiterzugeben. Sie können sensible Daten an Integrationen in der Ausgabe des Lambda-Genehmigers übergeben. Weitere Informationen hierzu finden Sie unter [Ausgabe von einem API-Gateway-Lambda-Genehmiger](api-gateway-lambda-authorizer-output.md).
## Anwendungsfälle für Stufenvariablen
Im Folgenden sehen Sie Anwendungsfälle für Ihre Stufenvariablen.
**Geben Sie einen anderen Backend-Endpunkt an**
Ihre API kann beispielsweise eine `GET`-Anforderung als HTTP-Proxy an den Backend-Webhost übergeben. Mit einer Stufenvariable können Sie veranlassen, dass API Gateway `example.com` aufruft, wenn API-Aufrufer Ihren Produktionsendpunkt aufrufen. Wenn API-Aufrufer dann die Beta-Phase aufrufen, ruft API Gateway einen anderen Webhost auf, z. B. `beta.example.com`. Ebenso lässt sich über Stufenvariablen für jede Stufe Ihrer API ein anderer AWS Lambda -Funktionsname angeben. Sie können eine Stufenvariable nicht für die Festlegung eines anderen Integrationsendpunkts verwenden, z. B. um die `GET`-Anforderung auf eine HTTP-Proxyintegration in einer Stufe, und eine Lambda-Proxyintegration in einer anderen Stufe zu verweisen.
Wenn Sie einen Lambda-Funktionsnamen als Stufenvariablenwert angeben, müssen Sie die Berechtigungen für die Lambda-Funktion manuell konfigurieren. Wenn Sie eine Lambda-Funktion in der API Gateway Gateway-Konsole angeben, erscheint ein AWS CLI Befehl zur Konfiguration der richtigen Berechtigungen. Sie können dazu auch den folgenden AWS CLI Befehl verwenden.
```
aws lambda add-permission --function-name "arn:aws:lambda:us-east-2:123456789012:function:my-function" --source-arn "arn:aws:execute-api:us-east-2:123456789012:api_id/*/HTTP_METHOD/resource" --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction
```
**Informationen mithilfe von Zuweisungsvorlagen übergeben**
Sie können in den Zuweisungsvorlagen auf Stufenvariablen zugreifen oder Konfigurationsparameter an Ihr AWS Lambda oder das HTTP-Backend übergeben. Beispielsweise möchten Sie vielleicht die gleiche Lambda-Funktion für mehrere Stufen in Ihrer API verwenden, jedoch soll die Funktion abhängig von der aufgerufenen Stufe jeweils Daten aus einer anderen Amazon DynamoDB-Tabelle auslesen. In den Mapping-Vorlagen, von denen die Anforderung für die Lambda-Funktion generiert wird, können Sie den Tabellennamen mit Stufenvariablen an Lambda übergeben.
Eine Stufenvariable muss zunächst konfiguriert und dann muss dieser ein Wert zugewiesen werden, bevor Sie die Stufenvariable verwenden können. Um beispielsweise den HTTP-Integrationsendpunkt anzupassen, erstellen Sie zuerst die `url`-Stufenvariable und geben dann den Wert der Stufenvariablen (**http://\$1\$1stageVariables.url\$1**) in der Integrationsanforderung Ihrer API ein. Mit diesem Wert wird API Gateway angewiesen, die Stufenvariable `${}` zur Laufzeit abhängig von der ausgeführten API-Stufe zu ersetzen. Weitere Informationen finden Sie unter [Stufenvariablen für REST APIs in API Gateway einrichten](how-to-set-stage-variables-aws-console.md).
# Stufenvariablen für REST APIs in API Gateway einrichten
In diesem Abschnitt erfahren Sie, wie Sie mit der Amazon-API-Gateway-Konsole verschiedene Stufenvariablen für zwei Bereitstellungsstufen einer Beispiel-API einrichten. Für ein besseres Verständnis, wie Stufenvariablen in API Gateway verwendet werden, empfehlen wir, dass Sie alle Schritte in diesem Abschnitt befolgen.
## Voraussetzungen
Überprüfen Sie vor Beginn, ob die folgenden Anforderungen erfüllt sind:
+ Es muss eine API in API Gateway verfügbar sein. Folgen Sie den Anweisungen in [Entwickeln Sie REST APIs in API Gateway](rest-api-develop.md).
+ Sie müssen die API mindestens einmal bereitgestellt haben. Folgen Sie den Anweisungen in [REST-APIs in API Gateway bereitstellen](how-to-deploy-api.md).
+ Sie müssen die erste Stufe für eine bereitgestellte API erstellt haben. Folgen Sie den Anweisungen in [Erstellen einer neuen Stufe](set-up-stages.md#how-to-create-stage-console).
## Aufrufen eines HTTP-Endpunkts über eine API mit einer Stufenvariable
In diesem Verfahren wird beschrieben, wie Sie eine Stufenvariable für einen HTTP-Endpunkt und zwei Stufen für Ihre API erstellen. Darüber hinaus erstellen Sie die Stufenvariablen `url`, `stageName` und `function`, die in den folgenden Abläufen in diesem Abschnitt verwendet werden.
**Aufrufen eines HTTP-Endpunkts über eine API mit einer Stufenvariable**
1. Melden Sie sich bei der API Gateway Gateway-Konsole unter [https://console.aws.amazon.com/apigatewayan](https://console.aws.amazon.com/apigateway).
1. Erstellen Sie eine API und anschließend eine `GET`-Methode für die Root-Ressource der API. Stellen Sie den Integrationstyp auf **HTTP** und die **Endpunkt-URL** auf **http://\$1\$1stageVariables.url\$1**.
1. Stellen Sie die API für eine neue Stufe namens **beta** bereit.
1. Wählen Sie im Navigationsbereich **Stages** (Stufen) die Stufe **beta**.
1. Wählen Sie auf der Registerkarte **Stage variables** (Stufenvariablen) die Option **Edit** (Bearbeiten) aus.
1. Wählen Sie **Add stage variable** (Stufenvariable hinzufügen).
1. Geben Sie unter **Name** **url** ein. Geben Sie für **Value** (Wert) **httpbin.org/get** ein.
1. Wählen Sie **Add stage variable** (Stufenvariable hinzufügen) und gehen Sie wie folgt vor:
Geben Sie unter **Name** **stageName** ein. Geben Sie für **Value** (Wert) **beta** ein.
1. Wählen Sie **Add stage variable** (Stufenvariable hinzufügen) und gehen Sie wie folgt vor:
Geben Sie unter **Name** **function** ein. Geben Sie für **Value** (Wert) **HelloWorld** ein.
1. Wählen Sie **Speichern**.
1. Erstellen Sie nun eine zweite Stufe. Wählen Sie im Navigationsbereich **Stages** (Stufen) die Option **Create stage** (Stufe erstellen). Geben Sie für **Stage name (Stufenname)** **prod** ein. Wählen Sie in **Deployment** (Bereitstellung) eine kürzlich ausgeführte Bereitstellung und anschließend **Create stage** (Stufe erstellen) aus.
1. Legen Sie wie im Fall der Phase **beta** die gleichen drei Stufenvariablen (**url**, **stageName** und **function**) auf unterschiedliche Werte fest („**petstore-demo-endpoint.execute-api.com/petstore/pets**“, „**prod**“ und „**HelloEveryone**“).
1. Wählen Sie im Navigationsbereich **Stages** **beta**. Wählen Sie unter **Stage details** (Stufendetails) das Kopiersymbol, um die Aufruf-URL Ihrer API zu kopieren, und geben Sie dann die Aufruf-URL Ihrer API in einen Webbrowser ein. Hierdurch wird die **beta**-Stufen-Anforderung `GET` für die Stammressource der API gestartet.
**Anmerkung**
Der Link **Invoke URL** verweist auf die Stammressource der API auf der **beta**-Stufe. Durch die Eingabe der URL in einem Webbrowser wird die **beta**-Stufenmethode `GET` für die Stammressource aufgerufen. Wenn Methoden für untergeordnete Ressourcen und nicht für die Stammressource selbst definiert sind, erhalten Sie bei der Eingabe der URL in einen Webbrowser die Fehlermeldung `{"message":"Missing Authentication Token"}`. In diesem Fall müssen Sie dem Link **Invoke URL** den Namen einer spezifischen untergeordneten Ressource anfügen.
1. Im Folgenden wird die Antwort angezeigt, die Sie von der **beta**-Stufen-Anforderung `GET` erhalten. Sie können das Ergebnis auch überprüfen, indem Sie in einem Browser zu **http://httpbin.org/get** navigieren. Dieser Wert wurde der `url`-Variablen in der **beta**-Stufe zugewiesen. Die beiden Antworten sind identisch.
1. Wählen Sie im Navigationsbereich **Stages** die Stufe **prod**. Wählen Sie unter **Stage details** (Stufendetails) das Kopiersymbol, um die Aufruf-URL Ihrer API zu kopieren, und geben Sie dann die Aufruf-URL Ihrer API in einen Webbrowser ein. Hierdurch wird die **prod**-Stufen-Anforderung `GET` für die Stammressource der API gestartet.
1. Im Folgenden wird die Antwort angezeigt, die Sie von der **prod**-Stufen-Anforderung `GET` erhalten. Sie können das Ergebnis überprüfen, indem Sie in einem Browser zu **http://.execute-api navigieren. petstore-demo-endpoint com/petstore/pets**. Dieser Wert wurde der `url`-Variablen in der **prod**-Stufe zugewiesen. Die beiden Antworten sind identisch.
## Übergabe phasenspezifischer Metadaten an ein HTTP-Backend
In diesem Verfahren wird beschrieben, wie stufenbezogene Metadaten mittels eines Stufenvariablenwerts in einem Abfrageparameterausdruck an ein HTTP-Backend übergeben werden. Hier verwenden wir die `stageName`-Stufenvariable, die im vorangegangenen Verfahren deklariert wurde.
**Übergabe phasenspezifischer Metadaten an ein HTTP-Backend**
1. Wählen Sie im Navigationsbereich **Resource** die Methode **GET**.
Um der URL der Methode einen Abfragezeichenfolge-Parameter hinzuzufügen, wählen Sie die Registerkarte **Method Request** (Methodenanforderung) und anschließend im Abschnitt **Method request settings** (Einstellungen der Methodenanforderung) die Option **Edit** (Bearbeiten).
1. Wählen Sie **URL query string parameters** (URL-Abfragezeichenfolgen-Parameter) und gehen Sie wie folgt vor:
1. Wählen Sie **Abfragezeichenfolge hinzufügen** aus.
1. Geben Sie unter **Name** **stageName** ein.
1. Lassen Sie die Optionen **Required** (Obligatorisch) and **Caching** (Cache) deaktiviert.
1. Wählen Sie **Speichern**.
1. Wählen Sie die Registerkarte **Integration request** (Integrationsanforderung) und dann im Abschnitt **Integration request settings** (Einstellungen für Integrationsanforderungen) die Option **Edit** (Bearbeiten) aus.
1. Fügen Sie bei **Endpoint URL** (Endpunkt-URL) den Wert **?stageName=\$1\$1stageVariables.stageName\$1** an den zuvor definierten URL-Wert an, damit die gesamte **Endpoint URL** (Endpunkt-URL) **http://\$1\$1stageVariables.url\$1?stageName=\$1\$1stageVariables.stageName\$1** lautet.
1. Wählen Sie **Deploy API** (API bereitstellen) und wählen Sie die Stufe **beta** aus.
1. Klicken Sie im Hauptnavigationsbereich auf **Stages** (Stufen). Wählen Sie im Navigationsbereich **Stages** **beta**. Wählen Sie unter **Stage details** (Stufendetails) das Kopiersymbol, um die Aufruf-URL Ihrer API zu kopieren, und geben Sie dann die Aufruf-URL Ihrer API in einen Webbrowser ein.
**Anmerkung**
Sie verwenden hier die beta-Stufe, da der HTTP-Endpunkt (von der `url`-Variable mit "http://httpbin.org/get" angegeben) Abfrageparameterausdrücke annimmt und diese in der Antwort als `args`-Objekt zurückgibt.
1. Sie erhalten die folgende Antwort. Beachten Sie, dass `beta` (zugeordnet zur `stageName`-Stufenvariable) als `stageName`-Argument an das Backend übergeben wird.
![\[Antwort der GET-Methode der API über einen HTTP-Endpunkt mit der url-Stufenvariable.\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/stageVariables-new-console-invoke-beta-stage-with-url-and-stageName-response.png)
## Aufrufen einer Lambda-Funktion über eine API mit einer Stufenvariable
In diesem Verfahren wird beschrieben, wie Sie eine Stufenvariable verwenden, um eine Lambda-Funktion als Backend der API aufzurufen. Hier verwenden Sie die `function`-Stufenvariable, die in [Aufrufen eines HTTP-Endpunkts über eine API mit einer Stufenvariable](#how-to-set-stage-variables-aws-console-http-endpoint) deklariert wurde.
Wenn Sie eine Lambda-Funktion als Wert einer Stufenvariable festlegen, verwenden Sie den lokalen Namen der Funktion und binden den Alias oder die Versionsangabe ein, z. B. **HelloWorld**, **HelloWorld:1** oder **HelloWorld:alpha**. Nutzen Sie nicht den ARN der Funktion (z. B, **arn:aws:lambda:us-east-1:123456789012:function:HelloWorld**). Die API Gateway-Konsole betrachtet den Stufenvariablenwert einer Lambda-Funktion als unvollständigen Funktionsnamen und erweitert die Stufenvariable zu einem ARN.
**Aufrufen einer Lambda-Funktion über eine API mit einer Stufenvariable**
1. Erstellen Sie eine Lambda-Funktion namens **HelloWorld** mit der Laufzeit Node.js. Der Code muss Folgendes enthalten:
```
export const handler = function(event, context, callback) {
if (event.stageName)
callback(null, 'Hello, World! I\'m calling from the ' + event.stageName + ' stage.');
else
callback(null, 'Hello, World! I\'m not sure where I\'m calling from...');
};
```
Weitere Informationen zum Erstellen einer Lambda-Funktion finden Sie unter [Erste Schritte mit der REST-API-Konsole](getting-started-rest-new-console.md#getting-started-rest-new-console-create-function).
1. Wählen Sie im Bereich **Ressources** (Ressourcen) die Option **Create resource** (Ressource erstellen) aus, und gehen Sie dann wie folgt vor:
1. Wählen Sie für **Resource path** (Ressourcenpfad) die Option**/**aus.
1. Geben Sie für **Resource name (Ressourcenname)** **lambdav1** ein.
1. Wählen Sie **Create Resource** (Ressource erstellen) aus.
1. Wählen Sie die **/lambdav1**-Ressource aus und klicken Sie dann auf **Methode erstellen**.
Führen Sie dann die folgenden Schritte aus:
1. Wählen Sie als **Methodentyp** die Option **GET** (Abrufen) aus.
1. Wählen Sie für den **Integration type** (Integrationstyp) die Option **Lambda function** (Lambda-Funktion) aus.
1. Lassen Sie **Lambda proxy integration** (Lambda-Proxyintegration) deaktiviert.
1. Geben Sie für die **Lambda function (Lambda-Funktion)** `${stageVariables.function}` ein.
![\[Erstellen einer GET-Methode, die in eine Lambda-Funktion integriert ist (wie festgelegt über die function-Stufenvariable)\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/stageVariables-new-console-create-lambda-get-method.png)
**Tipp**
Wenn Sie zur Eingabe des **Berechtigungsbefehl hinzufügen** aufgefordert werden, kopieren Sie den [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html)-Befehl. Sie müssen den Befehl für jede Lambda-Funktion ausführen, die der `function`-Stufenvariable zugewiesen werden soll. Wenn der `$stageVariables.function`-Wert beispielsweise `HelloWorld` lautet, führen Sie den folgenden AWS CLI -Befehl aus:
```
aws lambda add-permission --function-name arn:aws:lambda:us-east-1:account-id:function:HelloWorld --source-arn arn:aws:execute-api:us-east-1:account-id:api-id/*/GET/lambdav1 --principal apigateway.amazonaws.com --statement-id statement-id-guid --action lambda:InvokeFunction
```
Falls das nicht geschieht, führt der Aufruf der Methode zur Fehlermeldung `500 Internal Server Error`. Ersetzen Sie `${stageVariables.function}` durch den Lambda-Funktionsnamen, der dieser Stufenvariable zugeordnet ist.
![\[AWS CLI Befehl, um der Lambda-Funktion die Erlaubnis zu geben, von der von Ihnen erstellten Methode aufgerufen zu werden.\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/stageVariables-new-console-add-permission-to-lambda-function.png)
1. Wählen Sie **Methode erstellen** aus.
1. Stellen Sie die API in den Stufen **prod** und **beta** bereit.
1. Klicken Sie im Hauptnavigationsbereich auf **Stages** (Stufen). Wählen Sie im Navigationsbereich **Stages** **beta**. Wählen Sie unter **Stage details** (Stufendetails) das Kopiersymbol, um die Aufruf-URL Ihrer API zu kopieren, und geben Sie dann die Aufruf-URL Ihrer API in einen Webbrowser ein. Hängen Sie **/lambdav1** an die URL an, bevor Sie die Eingabetaste drücken.
Sie erhalten die folgende Antwort.
```
"Hello, World! I'm not sure where I'm calling from..."
```
## Übergeben von stufenbezogenen Metadaten an eine Lambda-Funktion über eine Stufenvariable
In diesem Verfahren wird beschrieben, wie stufenbezogene Konfigurationsmetadaten mittels einer Stufenvariable an eine Lambda-Funktion übergeben werden. Erstellen Sie eine `POST`-Methode und eine Eingabe-Mapping-Vorlage, um Nutzlast mit der zuvor deklarierten `stageName`-Stufenvariable zu generieren.
**Übergeben von stufenbezogenen Metadaten an eine Lambda-Funktion über eine Stufenvariable**
1. Wählen Sie die **/lambdav1**-Ressource aus und klicken Sie dann auf **Methode erstellen**.
Führen Sie dann die folgenden Schritte aus:
1. Wählen Sie unter **Method type** (Methodentyp) die Option **POST** aus.
1. Wählen Sie für den **Integration type** (Integrationstyp) die Option **Lambda function** (Lambda-Funktion) aus.
1. Lassen Sie **Lambda proxy integration** (Lambda-Proxyintegration) deaktiviert.
1. Geben Sie für die **Lambda function (Lambda-Funktion)** `${stageVariables.function}` ein.
1. Wenn Sie zur Eingabe des **Berechtigungsbefehl hinzufügen** aufgefordert werden, kopieren Sie den [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html)-Befehl. Sie müssen den Befehl für jede Lambda-Funktion ausführen, die der `function`-Stufenvariable zugewiesen werden soll.
1. Wählen Sie **Methode erstellen** aus.
1. Wählen Sie die Registerkarte **Integration request** (Integrationsanforderung) und dann im Abschnitt **Integration request settings** (Einstellungen für Integrationsanforderungen) die Option **Edit** (Bearbeiten) aus.
1. Wählen Sie **Mapping-Vorlagen** aus und klicken Sie dann auf **Mapping-Vorlage hinzufügen**.
1. Geben Sie für **Content type** (Inhaltstyp) **application/json** ein.
1. Geben Sie für **Template body** (Vorlagentext) die folgende Vorlage ein:
```
#set($inputRoot = $input.path('$'))
{
"stageName" : "$stageVariables.stageName"
}
```
**Anmerkung**
In einer Mapping-Vorlage muss eine Stufenvariable in Anführungszeichen (wie in `"$stageVariables.stageName"` oder `"${stageVariables.stageName}"`) referenziert werden. An anderen Stellen muss sie ohne Anführungszeichen (wie in ) referenziert werd `${stageVariables.function}`).
1. Wählen Sie **Speichern**.
1. Stellen Sie die API in den Stufen **beta** und **prod** bereit.
1. Gehen Sie wie folgt vor, um einen REST-API-Client zum Übergeben von stufenspezifischen Metadaten zu verwenden:
1. Wählen Sie im Navigationsbereich **Stages** **beta**. Wählen Sie unter **Stage details** (Stufendetails) das Kopiersymbol, um die Aufruf-URL Ihrer API zu kopieren, und geben Sie dann die Aufruf-URL Ihrer API in das Eingabefeld eines REST-API-Clients ein. Hängen Sie **/lambdav1** an, bevor Sie Ihre Anfrage absenden.
Sie erhalten die folgende Antwort.
```
"Hello, World! I'm calling from the beta stage."
```
1. Wählen Sie im Navigationsbereich **Stages** (Stufen) die Option **prod**. Wählen Sie unter **Stage details** (Stufendetails) das Kopiersymbol, um die Aufruf-URL Ihrer API zu kopieren, und geben Sie dann die Aufruf-URL Ihrer API in das Eingabefeld eines REST-API-Clients ein. Hängen Sie **/lambdav1** an, bevor Sie Ihre Anfrage absenden.
Sie erhalten die folgende Antwort.
```
"Hello, World! I'm calling from the prod stage."
```
1. Gehen Sie wie folgt vor, um die Funktion **Test** zum Übergeben von stufenspezifischen Metadaten zu verwenden:
1. Wählen Sie im Navigationsbereich **Resources** (Ressourcen) die Registerkarte **Test**. Möglicherweise müssen Sie die rechte Pfeiltaste wählen, um die Registerkarte anzuzeigen.
1. Geben Sie für **function** **HelloWorld** ein.
1. Geben Sie für **stageName** **beta** ein.
1. Wählen Sie **Test** aus. Sie müssen Ihrer `POST`-Anfrage keinen Text hinzufügen.
Sie erhalten die folgende Antwort.
```
"Hello, World! I'm calling from the beta stage."
```
1. Sie können die vorherigen Schritte wiederholen, um die **Prod**-Stufe zu testen. Geben Sie für **stageName** **Prod** ein.
Sie erhalten die folgende Antwort.
```
"Hello, World! I'm calling from the prod stage."
```
# API Gateway-Stufenvariablenreferenz für REST APIs in API Gateway
Sie können die API Gateway-Stufenvariablen in folgenden Fällen verwenden.
## Parameter-Mapping-Ausdrücke
Eine Stufenvariable kann in einem Parameter-Mapping-Ausdruck für den Header-Parameter einer API-Methodenanforderung oder -antwort genutzt werden, und zwar ohne Teilsubstitution. Im folgenden Beispiel wird die Stufenvariable ohne `$` und umschließende `{...}` referenziert.
+ `stageVariables.`
## Mapping-Vorlagen
Eine Stufenvariable kann überall in einer Mapping-Vorlage verwendet werden, wie in den folgenden Beispielen dargestellt.
+ `{ "name" : "$stageVariables."}`
+ `{ "name" : "${stageVariables.}"}`
## HTTP-Integration URIs
Eine Stufenvariable kann als Teil einer HTTP-Integrations-URL verwendet werden, wie in den folgenden Beispielen dargestellt:
+ Eine vollständige URI ohne Protokoll – `http://${stageVariables.}`
+ Eine vollständige Domäne – `http://${stageVariables.}/resource/operation`
+ Eine Unterdomäne – `http://${stageVariables.}.example.com/resource/operation`
+ Ein Pfad – `http://example.com/${stageVariables.}/bar`
+ Eine Abfragezeichenfolge – `http://example.com/foo?q=${stageVariables.}`
## AWS Integration URIs
Eine Stufenvariable kann als Teil von AWS URI-Aktions- oder Pfadkomponenten verwendet werden, wie im folgenden Beispiel gezeigt.
+ `arn:aws:apigateway:::${stageVariables.}`
## AWS Integration URIs (Lambda-Funktionen)
Eine Stufenvariable kann anstelle des Lambda-Funktionsnamens (oder Version/Alias) verwendet werden, wie in den folgenden Beispielen dargestellt.
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function:${stageVariables.}/invocations`
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function::${stageVariables.}/invocations`
**Anmerkung**
Um eine Stufenvariable für eine Lambda-Funktion zu verwenden, muss sich die Funktion im selben Konto wie die API befinden. Stufenvariablen unterstützen keine kontoübergreifenden Lambda-Funktionen.
## Amazon-Cognito-Benutzerpool
Eine Stufenvariable kann anstelle eines Amazon-Cognito-Benutzerpools für einen `COGNITO_USER_POOLS`-Genehmiger verwendet werden.
+ `arn:aws:cognito-idp:::userpool/${stageVariables.}`
## AWS Anmeldeinformationen für die Integration
Eine Stufenvariable kann als Teil des ARN für AWS Benutzer-/Rollenanmeldedaten verwendet werden, wie im folgenden Beispiel gezeigt.
+ `arn:aws:iam:::${stageVariables.}`
# Einrichten einer API Gateway-Canary-Release-Bereitstellung
[Canary-Release](https://martinfowler.com/bliki/CanaryRelease.html) ist eine Softwareentwicklungsstrategie, bei der eine neue Version einer API (und anderer Software) zu Testzwecken eingesetzt wird und die Basisversion weiterhin als Produktionsrelease für den normalen Betrieb auf derselben Stufe eingesetzt wird. Im Rahmen dieses Artikels gehen wir davon aus, dass die Basisversion das Produktionsrelease ist. Sie können das Canary-Release jedoch auch für Tests in jeder anderen Version verwenden.
Bei einer Canary-Release-Bereitstellung wird der gesamte API-Verkehr mit einem vorkonfigurierten Verhältnis nach dem Zufallsprinzip in ein Produktionsrelease und ein Canary-Release getrennt. Normalerweise erhält die Canary-Release einen kleinen Prozentsatz des API-Verkehrs und das Produktionsrelease nimmt den Rest in Anspruch. Die aktualisierten API-Features sind nur für den API-Verkehr über das Canary-Release sichtbar. Sie können den Prozentsatz des Canary-Datenverkehrs anpassen, um die Testabdeckung oder die Leistung zu optimieren.
Indem man den Canary-Verkehr gering und die Auswahl zufällig hält, werden die meisten Benutzer zu keiner Zeit durch potenzielle Fehler in der neuen Version beeinträchtigt und kein einzelner Benutzer wird ständig beeinträchtigt.
Nachdem die Testmetriken Ihre Anforderungen erfüllt haben, können Sie das Canary-Release in das Produktionsrelease überführen und Canary für die Bereitstellung deaktivieren. Damit stehen die neuen Features bereits in der Produktionsstufe zur Verfügung.
**Topics**
+ [Canary-Release-Bereitstellung in API Gateway](#api-gateway-canary-release-deployment-overview)
+ [Erstellen einer Canary-Release-Bereitstellung](create-canary-deployment.md)
+ [Aktualisieren eines Canary-Releases](update-canary-deployment.md)
+ [Hochstufen eines Canary-Releases](promote-canary-deployment.md)
+ [Deaktivieren eines Canary-Releases](delete-canary-deployment.md)
## Canary-Release-Bereitstellung in API Gateway
In API Gateway verwendet eine Canary-Release-Bereitstellung die Bereitstellungsstufe für die Produktionsfreigabe der Basisversion einer API und fügt der Stufe ein Canary-Release für die neuen Versionen relativ zur Basisversion der API hinzu. Die Stufe ist der ersten Bereitstellung und das Canary-Release den nachfolgenden Bereitstellungen zugeordnet. Zu Beginn verweisen sowohl die Stufe als auch das Canary auf die gleiche API-Version. Wir nutzen die Begriffe Stufen- und Produktionsrelease und Canary und Canary-Release in diesem Abschnitt gleichwertig.
Um eine API mit einem Canary-Release bereitzustellen, erstellen Sie eine Canary-Release-Bereitstellung, indem Sie die [Canary-Einstellungen](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) zur [Stufe](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) einer regulären [Bereitstellung](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html) hinzufügen. Die Canary-Einstellungen beschreiben das zugrunde liegende Canary-Release und die Stufe repräsentiert die Produktionsfreigabe der API innerhalb dieser Bereitstellung. Um Canary-Einstellungen hinzuzufügen, legen Sie `canarySettings` in der Bereitstellungsstufe fest und geben Sie Folgendes an:
+ Eine Bereitstellungs-ID. Diese ID ist zunächst mit der ID der Basisversion, die für die Stufe festgelegt wurde, identisch.
+ Ein [Prozentsatz des API-Verkehrs](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#percentTraffic) zwischen 0,0 und 100,0 (inklusive) für das Canary-Release.
+ [Stufenvariablen für das Canary-Release](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#stageVariableOverrides), die die Stufenvariablen des Produktionsreleases überschreiben können.
+ Die [Verwendung des Stage-Caches](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#useStageCache) für Canary-Anfragen, sofern der [useStageCache](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#useStageCache)festgelegt und das API-Caching auf der Bühne aktiviert ist.
Nachdem ein Canary-Release aktiviert wurde, kann die Bereitstellungsstufe nicht mit einem anderen nicht-Canary-Release verbunden werden, bis das Canary-Release deaktiviert und die Canary-Einstellungen von der Stufe entfernt wurden.
Wenn Sie die Protokollierung der API-Ausführung aktivieren, werden für das Canary-Release eigenen Protokolle und Metriken für alle Canary-Anforderungen generiert. Sie werden sowohl an eine CloudWatch Log-Protokollgruppe für die Produktionsphase als auch an eine Logs-Protokollgruppe für die Kanaren CloudWatch gemeldet. Gleiches gilt für die Zugriffsprotokollierung. Die separaten Canary-spezifischen Protokolle sind hilfreich, um neue API-Änderungen zu validieren und zu entscheiden, ob die Änderungen akzeptiert werden sollen und das Canary-Release in die Produktionsstufe übernommen werden soll oder ob die Änderungen verworfen werden sollen und das Canary-Release aus der Produktionsstufe zurückgenommen werden soll.
Die Protokollgruppe für die Ausführung in der Produktionsstufe heißt `API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}` und die Protokollgruppe für die Ausführung im Canary-Release heißt `API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}/Canary`. Für die Zugriffsprotokollierung müssen Sie eine neue Protokollgruppe anlegen oder eine bestehende auswählen. Der Name der Canary-Release-Zugriffsprotokollgruppe enthält das Suffix `/Canary`, das an den Namen der ausgewählten Protokollgruppe angehängt ist.
Eine Canary-Version kann den Stage-Cache verwenden, falls dieser aktiviert ist, um Antworten zu speichern und zwischengespeicherte Einträge zu verwenden, um Ergebnisse innerhalb eines vorkonfigurierten Zeitraums time-to-live (TTL) an die nächsten Canary-Anfragen zurückzugeben.
Bei einer Canary-Release-Bereitstellung können das Produktions- und das Canary-Release der API der gleichen Version oder verschiedenen Versionen zugeordnet werden. Wenn sie verschiedenen Versionen zugeordnet sind, werden die Antworten für Produktions- und Canary-Anforderungen getrennt zwischengespeichert und der Stage-Cache liefert entsprechende Ergebnisse für Produktions- und Canary-Anforderungen. Wenn das Produktionsrelease und das Canary-Release mit derselben Bereitstellung verbunden sind, verwendet der Stage-Cache einen einzigen Cache-Key für beide Arten von Anforderungen und gibt dieselbe Antwort für dieselben Anforderungen aus dem Produktionsrelease und dem Canary-Release zurück.
# Erstellen einer Canary-Release-Bereitstellung
Sie erstellen eine Canary-Release-Bereitstellung bei der Bereitstellung der API mit [Canary-Einstellungen](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDeployment.html#canarySettings) als zusätzliche Eingabe für die [Bereitstellungserstellung](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDeployment.html).
Sie können auch aus einer bestehenden Nicht-Canary-Bereitstellung eine Canary-Release-Bereitstellung erstellen, indem Sie eine [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html)-Anforderung erstellen, um die Canary-Einstellungen für die Stufe hinzuzufügen.
Beim Erstellen einer nicht-Canary-Release-Bereitstellung können Sie einen nicht existierenden Stufennamen angeben. API Gateway erstellt eine Stufe, wenn die angegebene Stufe nicht existiert. Sie können jedoch beim Anlegen einer Canary-Release-Bereitstellung keinen nicht existierenden Stufennamen angeben. Sie erhalten eine Fehlermeldung und API Gateway erstellt keine Canary-Release-Bereitstellung.
Sie können eine Canary-Release-Bereitstellung in API Gateway mit der API Gateway Gateway-Konsole AWS CLI, dem oder einem AWS SDK erstellen.
**Topics**
+ [Erstellen einer Canary-Bereitstellung mithilfe der API Gateway-Konsole](#create-canary-deployment-using-console)
+ [Erstellen Sie eine Canary-Bereitstellung mit dem AWS CLI](#create-canary-deployment-using-cli)
## Erstellen einer Canary-Bereitstellung mithilfe der API Gateway-Konsole
Gehen Sie nach den Anweisungen unten vor, um eine Canary-Release-Bereitstellung mit der API Gateway-Konsole zu erstellen:
**So erstellen Sie eine erste Canary-Release-Bereitstellung**
1. Melden Sie sich bei der API Gateway-Konsole an.
1. Wählen Sie eine vorhandene REST API aus oder erstellen Sie eine neue REST API.
1. Klicken Sie im Hauptnavigationsbereich von auf **Resources** (Ressourcen) und auf **Deploy API** (API bereitstellen). Befolgen Sie die Anweisungen auf der Seite in **Deploy API**, um die API in einer neuen Stufe bereitzustellen.
Bislang haben Sie die API in einer Produktions-Release-Stufe bereitgestellt. Als Nächstes konfigurieren Sie Canary-Einstellungen für die Stufe und, falls erforderlich, auch das Caching. Sie legen Stufenvariablen fest oder konfigurieren die API-Ausführung oder die Zugriffsprotokolle.
1. Um das API-Caching zu aktivieren oder der Phase eine AWS WAF Web-ACL zuzuordnen, wählen Sie im Abschnitt **Stage-Details** die Option **Bearbeiten** aus. Für weitere Informationen siehe [Cache-Einstellungen für REST APIs in API Gateway](api-gateway-caching.md) oder [So verknüpfen Sie mithilfe der API Gateway Gateway-Konsole eine AWS WAF Web-ACL mit einer API-Gateway-API-Stufe](apigateway-control-access-aws-waf.md#apigateway-control-access-aws-waf-console).
1. Um die Ausführung zu konfigurieren oder auf die Protokollierung zuzugreifen, wählen Sie im Abschnitt **Logs and tracing** (Protokolle und Nachverfolgung) die Option **Edit** (Bearbeiten) und folgen Sie den Anweisungen am Bildschirm. Weitere Informationen finden Sie unter [Richten Sie die CloudWatch Protokollierung für REST APIs in API Gateway ein](set-up-logging.md).
1. Um Stufenvariablen festzulegen, wählen Sie die Registerkarte **Stage variables** (Stufenvariablen) und folgen Sie den Anweisungen am Bildschirm, um Stufenvariablen hinzuzufügen oder zu ändern. Weitere Informationen finden Sie unter [Stufenvariablen für eine REST-API in API Gateway verwenden](stage-variables.md).
1. Wählen Sie die Registerkarte **Canary** und dann **Create canary** (Canary erstellen) aus. Möglicherweise müssen Sie die rechte Pfeiltaste wählen, um die Registerkarte **Canary** anzuzeigen.
1. Geben Sie unter **Canary settings** (Canary-Einstellungen) für **Canary** den Prozentsatz der Anfragen ein, die an den Canary weitergeleitet werden sollen.
1. Wählen Sie bei Bedarf **Stage Cache** (Stufen-Cache) aus, um das Caching für die Canary-Version zu aktivieren. Der Cache steht für das Canary-Release erst dann zur Verfügung, wenn das API-Caching aktiviert ist.
1. Um bestehende Stufenvariablen zu überschreiben, geben Sie für **Canary Override** (Überschreibung des Canary) einen neuen Wert für die Stufenvariable ein.
Nachdem das Canary-Release in der Bereitstellungsstufe initialisiert wurde, ändern Sie die API und testen die Änderungen. Sie können die API in derselben Stufe erneut bereitstellen, sodass sowohl die aktualisierte Version als auch die Basisversion über dieselbe Stufe zugreifbar sind. In den folgenden Schritten wird beschrieben, wie Sie dies tun.
**So stellen Sie die neueste API-Version für ein Canary bereit**
1. Wählen Sie bei jeder Aktualisierung der API **Deploy API** (API bereitstellen) aus.
1. Wählen Sie in **Deploy API** (API bereitstellen) in der Dropdown-Liste **Deployment stage** (Bereitstellungsstufe) die Stufe aus, die einen Canary enthält.
1. (Optional) Geben Sie unter **Deployment description** (Beschreibung der Bereitstellen) eine Beschreibung ein.
1. Wählen Sie **Deploy**, um die neueste API-Version auf das Canary-Release zu übertragen.
1. Falls erwünscht, rekonfigurieren Sie die Stufeneinstellungen, Protokolle oder Canary-Einstellungen, wie in beschriebe [So erstellen Sie eine erste Canary-Release-Bereitstellung](#to-create-canary-release-on-new-deployment).
Dadurch verweist das Canary-Release auf die neueste Version, während das Produktionsrelease noch auf die erste Version der API verweist. [https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) hat jetzt einen neuen **deploymentId**-Wert, während die Stufe noch den ursprünglichen [https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId)-Wert aufweist. Hinter den Kulissen ruft die Konsole [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) auf.
## Erstellen Sie eine Canary-Bereitstellung mit dem AWS CLI
**So erstellen Sie eine Canary-Bereitstellung für eine neue Stufe**
1. Verwenden Sie den folgenden [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html)-Befehl, um eine Bereitstellung mit zwei Stufenvariablen, aber ohne Canary zu erstellen:
```
aws apigateway create-deployment \
--variables sv0=val0,sv1=val1 \
--rest-api-id abcd1234 \
--stage-name 'prod'
```
Die Ausgabe sieht wie folgt aus:
```
{
"id": "du4ot1",
"createdDate": 1511379050
}
```
1. Verwenden Sie den folgenden [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html)-Befehl, um eine Canary-Bereitstellung in der `prod`-Stufe zu erstellen:
```
aws apigateway create-deployment \
--rest-api-id abcd1234 \
--canary-settings percentTraffic=10.5,stageVariableOverrides={sv1='val2',sv2='val3'},useStageCache=false \
--stage-name 'prod'
```
Die Ausgabe sieht wie folgt aus:
```
{
"id": "a6rox0",
"createdDate": 1511379433
}
```
Die resultierende Bereitstellungs-`id` identifiziert die Testversion der API für das Canary-Release. Dadurch ist die zugehörige Stufe für Canary aktiviert.
1. (Optional) Verwenden Sie den folgenden [get-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-stage.html)-Befehl, um die Repräsentation der Stufe anzuzeigen:
```
aws apigateway get-stage --rest-api-id acbd1234 --stage-name prod
```
Nachfolgend ist eine Repräsentation der `Stage` als Ausgabe des Befehls zu sehen:
```
{
"stageName": "prod",
"variables": {
"sv0": "val0",
"sv1": "val1"
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": "du4ot1",
"lastUpdatedDate": 1511379433,
"createdDate": 1511379050,
"canarySettings": {
"percentTraffic": 10.5,
"deploymentId": "a6rox0",
"useStageCache": false,
"stageVariableOverrides": {
"sv2": "val3",
"sv1": "val2"
}
},
"methodSettings": {}
}
```
In diesem Beispiel verwendet die Basisversion der API die Stufenvariablen `{"sv0":val0", "sv1":val1"}`, während die Testversion die Stufenvariablen `{"sv1":val2", "sv2":val3"}` verwendet. Sowohl das Produktionsrelease als auch das Canary-Release verwenden die gleiche Stufenvariable `sv1`, jedoch mit unterschiedlichen Werten (`val1` und `val2`). Die Stufenvariable `sv0` wird ausschließlich im Produktionsrelease verwendet und die Stufenvariable `sv2` wird nur im Canary-Release verwendet.
Sie können auch eine Canary-Release-Bereitstellung aus einer bestehenden regulären Bereitstellung erstellen, indem Sie die Stufe aktualisieren, um einen Canary zu aktivieren.
**So erstellen Sie eine Canary-Release-Bereitstellung aus einer vorhandenen Bereitstellung**
1. Verwenden Sie den [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html)-Befehl, um eine Bereitstellung ohne einen Canary zu erstellen:
```
aws apigateway create-deployment \
--variables sv0=val0,sv1=val1 \
--rest-api-id abcd1234 \
--stage-name 'beta'
```
1. Verwenden Sie den [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html)-Befehl, um die Stufe zu aktualisieren und einen Canary zu aktivieren:
```
aws apigateway update-stage \
--rest-api-id abcd1234 \
--stage-name 'beta' \
--patch-operations '[{
"op": "replace",
"value": "0.0",
"path": "/canarySettings/percentTraffic"
}, {
"op": "copy",
"from": "/canarySettings/stageVariableOverrides",
"path": "/variables"
}, {
"op": "copy",
"from": "/canarySettings/deploymentId",
"path": "/deploymentId"
}]'
```
Die Ausgabe sieht wie folgt aus:
```
{
"stageName": "beta",
"variables": {
"sv0": "val0",
"sv1": "val1"
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": "cifeiw",
"lastUpdatedDate": 1511381930,
"createdDate": 1511380879,
"canarySettings": {
"percentTraffic": 10.5,
"deploymentId": "cifeiw",
"useStageCache": false,
"stageVariableOverrides": {
"sv2": "val3",
"sv1": "val2"
}
},
"methodSettings": {}
}
```
Da Sie einen Canary in einer bestehenden Version der API aktiviert haben, verweisen sowohl die Produktionsveröffentlichung (`Stage`) als auch die Canary-Veröffentlichung (`canarySettings`) auf dieselbe Bereitstellung. Nachdem Sie die API geändert und für diese Stufe wieder bereitgestellt haben, ist die neue Version im Canary-Release. Die Basisversion verbleibt im Produktions-Release. Dies wirkt sich auf die Stufenentwicklung aus, wenn die `deploymentId` im Canary-Release auf die neue Bereitstellungs-`id` aktualisiert wird und die `deploymentId` im Produktions-Release unverändert bleibt.
# Aktualisieren eines Canary-Releases
Nach der Bereitstellung eines Canary-Releases können Sie den prozentualen Anteil des Canary-Verkehrs anpassen oder die Verwendung eines Stage-Caches aktivieren oder deaktivieren, um die Testperformance zu optimieren. Sie können außerdem Stufenvariablen modifizieren, die im Canary-Release verwendet werden, wenn der Ausführungskontext aktualisiert wird. Um solche Aktualisierungen vorzunehmen, rufen Sie die Operation [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) mit neuen Werten für [canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) auf.
Sie können eine Canary-Version mit der API Gateway Gateway-Konsole, dem Befehl AWS CLI [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) oder einem AWS SDK aktualisieren.
**Topics**
+ [Aktualisieren eines Canary-Releases mit der API Gateway-Konsole](#update-canary-deployment-using-console)
+ [Aktualisieren Sie eine Canary-Version mit dem AWS CLI](#update-canary-deployment-using-cli)
## Aktualisieren eines Canary-Releases mit der API Gateway-Konsole
Um die API Gateway-Konsole zur Aktualisierung der vorhandenen Canary-Einstellungen einer Stufe zu nutzen, führen Sie die folgenden Schritte aus:
**Aktualisieren bestehender Canary-Einstellungen**
1. Melden Sie sich bei der API Gateway-Konsole an und wählen Sie eine bestehende REST API aus.
1. Wählen Sie im Hauptnavigationsbereich **Stages** (Stufen) und anschließend eine bestehende Stufe aus.
1. Wählen Sie die Registerkarte **Canary** und anschließend **Edit** (Bearbeiten) aus. Möglicherweise müssen Sie die rechte Pfeiltaste wählen, um die Registerkarte **Canary** anzuzeigen.
1. Aktualisieren Sie **Request distribution** (Verteilung anfordern), indem Sie den Prozentsatz auf einen Wert zwischen 0,0 und 100,0 (inklusive) erhöhen oder verringern.
1. Aktivieren oder deaktivieren Sie das Kontrollkästchen unter **Stage cache** (Stage-Cache).
1. Fügen Sie **Canary stage variables** (Canary-Stufenvariablen) hinzu, entfernen oder ändern Sie sie.
1. Wählen Sie **Speichern**.
## Aktualisieren Sie eine Canary-Version mit dem AWS CLI
Um einen Canary AWS CLI zu aktualisieren, verwenden Sie den [https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html)Befehl und ändern Sie den Patch-Vorgang für jeden Parameter des Canary.
Der folgende [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html)-Befehl aktualisiert, ob der Canary den Stufen-Cache verwendet:
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations op=replace,path=/canarySettings/useStageCache,value=true
```
Der folgende [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html)-Befehl aktualisiert den Prozentsatz des Canary-Datenverkehrs:
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations op=replace,path=/canarySettings/percentTraffic,value=25.0
```
Der folgende [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html)-Befehl aktualisiert Stufenvariablen. Das Beispiel zeigt, wie Sie eine neue Stufenvariable mit dem Namen `newVar` erstellen, die Stufenvariable `var2` überschreiben und die Stufenvariable `var1` entfernen:
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations '[{
"op": "replace",
"path": "/canarySettings/stageVariableOverrides/newVar",
"value": "newVal"
}, {
"op": "replace",
"path": "/canarySettings/stageVariableOverrides/var2",
"value": "val4"
}, {
"op": "remove",
"path": "/canarySettings/stageVariableOverrides/var1"
}]'
```
Sie können das oben Genannte aktualisieren, indem Sie die Operationen zu einem einzigen `patch-operations`-Wert zusammenfassen:
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations '[{
"op": "replace",
"path": "/canarySettings/percentTraffic",
"value": "20.0"
}, {
"op": "replace",
"path": "/canarySettings/useStageCache",
"value": "true"
}, {
"op": "remove",
"path": "/canarySettings/stageVariableOverrides/var1"
}, {
"op": "replace",
"path": "/canarySettings/stageVariableOverrides/newVar",
"value": "newVal"
}, {
"op": "replace",
"path": "/canarySettings/stageVariableOverrides/val2",
"value": "val4"
}]'
```
# Hochstufen eines Canary-Releases
Wenn Sie ein Canary-Release hochstufen, ersetzt das Canary-Release die aktuellen Einstellungen der Stufe. Das Hochstufen eines Canary-Releases bedeutet nicht, dass das Canary für die Stufe deaktiviert wird. Um ein Canary zu deaktivieren, müssen Sie die Canary-Einstellungen der Stufe entfernen. Sie stufen ein Canary-Release wie folgt hoch.
+ Setzen Sie die [Bereitstellungs-ID](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId) der Stufe mit den [Bereitstellungs-ID](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings)-Einstellungen des Canarys zurück. Dadurch wird der API-Snapshot der Stufe mit dem Snapshot des Canarys aktualisiert, sodass die Testversion auch zum Produktionsrelease wird.
+ Aktualisieren Sie Stufenvariablen mit Canary-Stufenvariablen, falls vorhanden. Dadurch wird der API-Ausführungskontext der Stufe mit dem des Canarys aktualisiert. Ohne dieses Update kann die neue API-Version unerwartete Ergebnisse liefern, wenn die Testversion unterschiedliche Stufenvariablen oder unterschiedliche Werte vorhandener Stufenvariablen verwendet.
+ Legen Sie den Prozentsatz des Canary-Verkehrs auf 0,0 % fest.
**Topics**
+ [Hochstufen eines Canary-Releases mit der API Gateway-Konsole](#promote-canary-release-deployment-console)
+ [Bewerben Sie eine Canary-Version mit dem AWS CLI](#promote-canary-release-cli)
## Hochstufen eines Canary-Releases mit der API Gateway-Konsole
Gehen Sie nach den Anweisungen unten vor, um eine Canary-Release-Bereitstellung mit der API Gateway-Konsole hochzustufen:
**Hochstufen einer Canary-Release-Bereitstellung**
1. Melden Sie sich bei der API Gateway-Konsole an und wählen Sie eine bestehende API im Hauptnavigationsbereich aus.
1. Wählen Sie im Hauptnavigationsbereich **Stages** (Stufen) und anschließend eine bestehende Stufe aus.
1. Wählen Sie die Registerkarte **Canary**.
1. Wählen Sie **Promote Canary** (Canary hochstufen) aus.
1. Bestätigen Sie die durchzuführenden Änderungen und wählen Sie **Promote canary** (Canary hochstufen) aus.
Nach der Aktion verweist das Produktionsrelease auf die gleiche API-Version (**deploymentId**) wie das Canary-Release. Sie können dies mit dem überprüfen AWS CLI. Ein Beispiel finden Sie unter [Bewerben Sie eine Canary-Version mit dem AWS CLI](#promote-canary-release-cli).
## Bewerben Sie eine Canary-Version mit dem AWS CLI
Um eine Canary-Version mithilfe der AWS CLI Befehle zur Produktionsversion hochzustufen, rufen Sie den `update-stage` Befehl auf, um die Canary-assoziierte `deploymentId` Version in die Stage-Associated zu kopieren`deploymentId`, den Prozentsatz des Canary-Traffics auf Null (`0.0`) zurückzusetzen und alle kanariengebundenen Stage-Variablen in die entsprechenden Stage-Variablen zu kopieren.
Angenommen, wir haben eine Canary-Release-Bereitstellung, die durch eine in etwa wie folgt aussehende Stufe beschrieben wird:
```
{
"_links": {
...
},
"accessLogSettings": {
...
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"canarySettings": {
"deploymentId": "eh1sby",
"useStageCache": false,
"stageVariableOverrides": {
"sv2": "val3",
"sv1": "val2"
},
"percentTraffic": 10.5
},
"createdDate": "2017-11-20T04:42:19Z",
"deploymentId": "nfcn0x",
"lastUpdatedDate": "2017-11-22T00:54:28Z",
"methodSettings": {
...
},
"stageName": "prod",
"variables": {
"sv1": "val1"
}
}
```
Verwenden Sie den folgenden [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html)-Befehl, um den Canary hochzustufen:
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations '[{
"op": "replace",
"value": "0.0",
"path": "/canarySettings/percentTraffic"
}, {
"op": "copy",
"from": "/canarySettings/stageVariableOverrides",
"path": "/variables"
}, {
"op": "copy",
"from": "/canarySettings/deploymentId",
"path": "/deploymentId"
}]'
```
Die Ausgabe sieht wie folgt aus:
```
{
"_links": {
...
},
"accessLogSettings": {
...
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"canarySettings": {
"deploymentId": "eh1sby",
"useStageCache": false,
"stageVariableOverrides": {
"sv2": "val3",
"sv1": "val2"
},
"percentTraffic": 0
},
"createdDate": "2017-11-20T04:42:19Z",
"deploymentId": "eh1sby",
"lastUpdatedDate": "2017-11-22T05:29:47Z",
"methodSettings": {
...
},
"stageName": "prod",
"variables": {
"sv2": "val3",
"sv1": "val2"
}
}
```
Durch ein Hochstufen eines Canary-Release wird Canary nicht deaktiviert und die Bereitstellung bleibt weiterhin eine Canary-Release-Bereitstellung. Um daraus eine reguläre Produktions-Release-Bereitstellung zu machen, müssen Sie die Canary-Einstellungen deaktivieren. Weitere Informationen dazu, wie Sie eine Canary-Release-Bereitstellung deaktivieren, finden Sie unter [Deaktivieren eines Canary-Releases](delete-canary-deployment.md).
# Deaktivieren eines Canary-Releases
Um eine Canary-Release-Bereitstellung zu deaktivieren, müssen Sie [https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) auf null setzen, um es von der Stufe zu entfernen.
Sie können eine Canary-Release-Bereitstellung mit der API Gateway Gateway-Konsole AWS CLI, dem oder einem AWS SDK deaktivieren.
**Topics**
+ [Deaktivieren eines Canary-Releases mit der API Gateway-Konsole](#delete-canary-release-console)
+ [Schalten Sie eine Canary-Version mit dem aus AWS CLI](#delete-canary-release-cli)
## Deaktivieren eines Canary-Releases mit der API Gateway-Konsole
Gehen Sie nach den Anweisungen unten vor, um eine Canary-Release-Bereitstellung mit der API Gateway-Konsole zu deaktivieren:
**Deaktivieren einer Canary-Release-Bereitstellung**
1. Melden Sie sich bei der API Gateway-Konsole an und wählen Sie eine bestehende API im Hauptnavigationsbereich aus.
1. Wählen Sie im Hauptnavigationsbereich **Stages** (Stufen) und anschließend eine bestehende Stufe aus.
1. Wählen Sie die Registerkarte **Canary**.
1. Wählen Sie **Löschen** aus.
1. Bestätigen Sie, dass Sie das Canary löschen möchten, indem Sie **Delete** auswählen.
Dadurch wird die Eigenschaft [https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) auf `null` gesetzt und aus der [Bereitstellungsstufe](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) entfernt. Sie können dies mit dem überprüfen AWS CLI. Ein Beispiel finden Sie unter [Schalten Sie eine Canary-Version mit dem aus AWS CLI](#delete-canary-release-cli).
## Schalten Sie eine Canary-Version mit dem aus AWS CLI
Der folgende [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html)-Befehl deaktiviert die Bereitstellung der Canary-Version:
```
aws apigateway update-stage \
--rest-api-id abcd1234 \
--stage-name canary \
--patch-operations '[{"op":"remove", "path":"/canarySettings"}]'
```
Die Ausgabe sollte wie folgt aussehen:
```
{
"stageName": "prod",
"accessLogSettings": {
...
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": "nfcn0x",
"lastUpdatedDate": 1511309280,
"createdDate": 1511152939,
"methodSettings": {
...
}
}
```
Wie aus der Ausgabe hervorgeht, ist die Eigenschaft [canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) nun nicht mehr in der [Stufe](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) einer Canary-deaktivierten Bereitstellung enthalten.
# REST-Updates APIs , die eine erneute Bereitstellung erfordern
Die Pflege einer API ist gleichzusetzen mit der Anzeige, Aktualisierung und Löschung der vorhandenen API-Einrichtungen. Sie können eine API mithilfe der API Gateway Gateway-Konsole,, AWS CLI CloudFormation, eines SDK oder der API Gateway Gateway-REST-API verwalten. Die Aktualisierung einer API umfasst die Änderung bestimmter Ressourceneigenschaften oder Konfigurationseinstellungen der API. Während Ressourcenaktualisierungen die erneute Bereitstellung der API erfordern, ist die für Konfigurationsaktualisierungen nicht erforderlich.
In der folgenden Tabelle werden API-Konfigurationen beschrieben, die bei einer Aktualisierung eine erneute Bereitstellung Ihrer API erfordern.
| Ressource | Hinweise |
| --- | --- |
| [ApiKey](https://docs.aws.amazon.com/apigateway/latest/api/API_ApiKey.html) | Informationen zu den entsprechenden Eigenschaften und unterstützten Operationen finden Sie unter [apikey:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateApiKey.html). Die Aktualisierung erfordert die erneute Bereitstellung der API. |
| [Authorizer](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) | Informationen zu den entsprechenden Eigenschaften und unterstützten Operationen finden Sie unter [authorizer:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAuthorizer.html). Die Aktualisierung erfordert die erneute Bereitstellung der API. |
| [disableExecuteApiEndpunkt](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html#apigw-UpdateRestApi-response-disableExecuteApiEndpoint) | Die Aktualisierung erfordert das Ändern einer beliebigen Stufe der API, zum Beispiel das erneute Bereitstellen der API in einer Stufe. |
| [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) | Informationen zu den entsprechenden Eigenschaften und unterstützten Operationen finden Sie unter [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html). Die Aktualisierung erfordert die erneute Bereitstellung der API. |
| [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) | Informationen zu den entsprechenden Eigenschaften und unterstützten Operationen finden Sie unter [documentationversion:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationVersion.html). Die Aktualisierung erfordert die erneute Bereitstellung der API. |
| [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) | Informationen zu den entsprechenden Eigenschaften und unterstützten Operationen finden Sie unter [gatewayresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateGatewayResponse.html#remarks). Die Aktualisierung erfordert die erneute Bereitstellung der API. |
| [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) | Informationen zu den entsprechenden Eigenschaften und unterstützten Operationen finden Sie unter [integration:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateIntegration.html). Die Aktualisierung erfordert die erneute Bereitstellung der API. |
| [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) | Informationen zu den entsprechenden Eigenschaften und unterstützten Operationen finden Sie unter [integrationresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateIntegrationResponse.html). Die Aktualisierung erfordert die erneute Bereitstellung der API. |
| [Methode](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) | Informationen zu den entsprechenden Eigenschaften und unterstützten Operationen finden Sie unter [method:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html). Die Aktualisierung erfordert die erneute Bereitstellung der API. |
| [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) | Informationen zu den entsprechenden Eigenschaften und unterstützten Operationen finden Sie unter [methodresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethodResponse.html). Die Aktualisierung erfordert die erneute Bereitstellung der API. |
| [Model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) | Informationen zu den entsprechenden Eigenschaften und unterstützten Operationen finden Sie unter [model:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateModel.html). Die Aktualisierung erfordert die erneute Bereitstellung der API. |
| [RequestValidator](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html) | Informationen zu den entsprechenden Eigenschaften und unterstützten Operationen finden Sie unter [requestvalidator:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRequestValidator.html). Die Aktualisierung erfordert die erneute Bereitstellung der API. |
| [Ressource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) | Informationen zu den entsprechenden Eigenschaften und unterstützten Operationen finden Sie unter [resource:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html). Die Aktualisierung erfordert die erneute Bereitstellung der API. |
| [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html) | Informationen zu den entsprechenden Eigenschaften und unterstützten Operationen finden Sie unter [restapi:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html). Die Aktualisierung erfordert die erneute Bereitstellung der API. Dazu gehört auch die Änderung der Ressourcenrichtlinien. |
| [VpcLink](https://docs.aws.amazon.com/apigateway/latest/api/API_VpcLink.html) | Informationen zu den entsprechenden Eigenschaften und unterstützten Operationen finden Sie unter [vpclink:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateVpcLink.html). Die Aktualisierung erfordert die erneute Bereitstellung der API. |
In der folgenden Tabelle werden API-Konfigurationen beschrieben, die bei einer Aktualisierung keine erneute Bereitstellung Ihrer API erfordern.
| Konfiguration | Hinweise |
| --- | --- |
| [Account](https://docs.aws.amazon.com/apigateway/latest/api/API_GetAccount.html) | Informationen zu den entsprechenden Eigenschaften und unterstützten Operationen finden Sie unter [account:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html). Die Aktualisierung erfordert keine erneute Bereitstellung der API. |
| [Bereitstellung](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html) | Informationen zu den entsprechenden Eigenschaften und unterstützten Operationen finden Sie unter [deployment:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDeployment.html). |
| [DomainName](https://docs.aws.amazon.com/apigateway/latest/api/API_DomainName.html) | Informationen zu den entsprechenden Eigenschaften und unterstützten Operationen finden Sie unter [domainname:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDomainName.html). Die Aktualisierung erfordert keine erneute Bereitstellung der API. |
| [BasePathMapping](https://docs.aws.amazon.com/apigateway/latest/api/API_BasePathMapping.html) | Informationen zu den entsprechenden Eigenschaften und unterstützten Operationen finden Sie unter [basepathmapping:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateBasePathMapping.html). Die Aktualisierung erfordert keine erneute Bereitstellung der API. |
| [IP-Adresstyp](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateRestApi.html) | Die Aktualisierung erfordert keine erneute Bereitstellung der API. |
| [Stage](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) | Informationen zu den entsprechenden Eigenschaften und unterstützten Operationen finden Sie unter [stage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html). Die Aktualisierung erfordert keine erneute Bereitstellung der API. |
| [Usage](https://docs.aws.amazon.com/apigateway/latest/api/API_GetUsage.html) | Informationen zu den entsprechenden Eigenschaften und unterstützten Operationen finden Sie unter [usage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsage.html). Die Aktualisierung erfordert keine erneute Bereitstellung der API. |
| [UsagePlan](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html) | Informationen zu den entsprechenden Eigenschaften und unterstützten Operationen finden Sie unter [usageplan:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html). Die Aktualisierung erfordert keine erneute Bereitstellung der API. |