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 überwachen
In diesem Abschnitt erfahren Sie, wie Sie Ihre API mithilfe von CloudWatch-Metriken, CloudWatch Logs, Firehose und AWS X-Ray überwachen. Durch die Kombination von CloudWatch-Ausführungsprotokollen und CloudWatch-Metriken können Sie Fehler und Ablaufverfolgungen der Ausführung protokollieren und die Leistung Ihrer API überwachen. Möglicherweise möchten Sie auch API-Aufrufe an Firehose protokollieren. Sie können auch AWS X-Ray verwenden, um Aufrufe über die nachgeschalteten Services zu verfolgen, aus denen Ihre API besteht.
**Anmerkung**
API Gateway generiert in den folgenden Fällen möglicherweise keine Protokolle und Metriken:
413 Request Entity Too Large-Fehler
431 Request-Header-Fields-Too-Large-Fehler
Übermäßige 429 Too Many Requests-Fehler
Fehler der Serie 400 von Anfragen, die an eine benutzerdefinierte Domäne gesendet wurden, die keine API-Zuordnung hat
Fehler der Serie 500, die durch interne Ausfälle verursacht werden
API Gateway generiert beim Testen einer REST-API-Methode keine Protokolle und Metriken. Die CloudWatch-Einträge werden simuliert. Weitere Informationen finden Sie unter [API Gateway-Konsole zum Testen einer REST-API-Methode verwenden](how-to-test-method.md).
**Topics**
+ [Überwachen Sie die REST-API-Ausführung mit CloudWatch Amazon-Metriken](monitoring-cloudwatch.md)
+ [Richten Sie die CloudWatch Protokollierung für REST APIs in API Gateway ein](set-up-logging.md)
+ [Protokollierung von REST-API-Aufrufen unter Amazon Data Firehose im API Gateway](apigateway-logging-to-kinesis.md)
+ [Variablen für die Zugriffsprotokollierung in API Gateway](api-gateway-variables-for-access-logging.md)
+ [Benutzeranforderungen für Ablaufverfolgung an REST-APIs mithilfe von X-Ray in API Gateway](apigateway-xray.md)
# Überwachen Sie die REST-API-Ausführung mit CloudWatch Amazon-Metriken
Sie können die API-Ausführung überwachen CloudWatch, indem Sie die Rohdaten von API Gateway sammeln und in lesbare near-real-time Metriken umwandeln. Diese Statistiken werden für einen Zeitraum von 15 Monaten aufgezeichnet, damit Sie auf Verlaufsinformationen zugreifen können und einen besseren Überblick darüber erhalten, wie Ihre Webanwendung oder der Service ausgeführt wird. Standardmäßig werden API-Gateway-Metrikdaten automatisch innerhalb von CloudWatch einer Minute gesendet. Weitere Informationen finden Sie unter [Was ist Amazon CloudWatch?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) im * CloudWatch Amazon-Benutzerhandbuch*.
Die von API Gateway gemeldeten Metriken bieten Informationen, die Sie auf unterschiedliche Weise analysieren können. Die folgende Liste zeigt einige häufige Verwendungszwecke für die Metriken, die Vorschläge für den Einstieg sind:
+ Überwachen Sie die **IntegrationLatency**-Metriken, um die Reaktionsfähigkeit des Backends zu messen.
+ Überwachen Sie die **Latency**-Metriken, um die allgemeine Reaktionsfähigkeit Ihrer API-Aufrufe zu messen.
+ Überwachen Sie die **CacheHitCount**- und **CacheMissCount**-Metriken, um die Cache-Kapazitäten zu optimieren und die gewünschte Leistung zu erreichen.
**Topics**
+ [Amazon API Gateway-Dimensionen und -Metriken](api-gateway-metrics-and-dimensions.md)
+ [Anzeigen von CloudWatch-Metriken mit dem API-Dashboard in API Gateway](how-to-api-dashboard.md)
+ [API Gateway Gateway-Metriken in der CloudWatch Konsole anzeigen](metrics_dimensions_view_in_cloud_watch.md)
+ [API Gateway Gateway-Protokollereignisse in der CloudWatch Konsole anzeigen](view-cloudwatch-log-events-in-cloudwatch-console.md)
+ [Überwachungstools AWS für API Gateway](monitoring_automated_manual.md)
# Amazon API Gateway-Dimensionen und -Metriken
Die Metriken und Dimensionen, die API Gateway an Amazon sendet, CloudWatch sind unten aufgeführt. Weitere Informationen finden Sie unter [Überwachen Sie die REST-API-Ausführung mit CloudWatch Amazon-Metriken](monitoring-cloudwatch.md).
## API Gateway-Metriken
Amazon API Gateway sendet Metrikdaten an CloudWatch jede Minute.
Der `AWS/ApiGateway`-Namespace enthält die folgenden Metriken.
| Metrik | Beschreibung |
| --- | --- |
| 4XXError | Die Anzahl der erfassten clientseitigen Fehler innerhalb eines bestimmten Zeitraums. API Gateway zählt modifizierte Gateway-Antwortstatuscodes als 4 XXError Fehler. Die Statistik `Sum` repräsentiert diese Metrik, also die Gesamtzahl der 4XXError-Fehler in dem angegebenen Zeitraum. Die Statistik `Average` repräsentiert die 4XXError-Fehlerrate, also die Gesamtzahl der 4XXError-Fehler geteilt durch die Gesamtzahl der Anforderungen innerhalb des Zeitraums. Der Nenner entspricht der Count-Metrik (unten). Unit: Count |
| 5XXError | Die Anzahl der erfassten serverseitigen Fehler innerhalb eines bestimmten Zeitraums Die Statistik `Sum` repräsentiert diese Metrik, also die Gesamtzahl der 5XXError-Fehler in dem angegebenen Zeitraum. Die Statistik `Average` repräsentiert die 5XXError-Fehlerrate, also die Gesamtzahl der 5XXError-Fehler geteilt durch die Gesamtzahl der Anforderungen innerhalb des Zeitraums. Der Nenner entspricht der Count-Metrik (unten). Unit: Count |
| CacheHitCount | Die Anzahl aller vom API-Cache innerhalb eines bestimmten Zeitraums bedienten Anforderungen Die Statistik `Sum` repräsentiert diese Metrik, also die Gesamtzahl der Cache-Zugriffe innerhalb des angegebenen Zeitraums. Die Statistk `Average` stellt die Cache-Zugriffsrate, also die Gesamtzahl der Cache-Zugriffe geteilt durch die Gesamtzahl der Anforderungen innerhalb des Zeitraums, dar. Der Nenner entspricht der Count-Metrik (unten). Unit: Count |
| CacheMissCount | Die Anzahl aller vom Backend innerhalb eines bestimmten Zeitraums bedienten Anforderungen, wenn das API-Caching aktiviert ist Die Statistik `Sum` repräsentiert diese Metrik, also die Gesamtzahl der Cache-Fehler innerhalb des angegebenen Zeitraums. Die Statistik `Average` repräsentiert die Cache-Fehlerrate, also die Gesamtzahl der Cache-Fehler geteilt durch die Gesamtzahl der Anforderungen innerhalb des Zeitraums. Der Nenner entspricht der Count-Metrik (unten). Unit: Count |
| Count | Die Gesamtzahl der API-Anforderungen innerhalb eines bestimmten Zeitraums Die Statistik `SampleCount` stellt diese Metrik dar. Unit: Count |
| IntegrationLatency | Die Zeit zwischen dem Zeitpunkt, zu dem API Gateway eine Anfrage an das Backend weiterleitet und zu dem Zeitpunkt, zu dem es eine Antwort vom Backend erhält. Unit: Millisecond |
| Latency | Die Zeit zwischen dem Zeitpunkt, zu dem API Gateway eine Anfrage von einem Client empfängt, und dem Zeitpunkt, an dem es eine Antwort an den Client zurückgibt. Die Latenzzeit schließt die Integrationslatenzzeit und anderen API Gateway-Overhead ein. Unit: Millisecond |
## Dimensionen für Metriken
Sie können die Dimensionen in der folgenden Tabelle verwenden, um API Gateway-Metriken zu filtern.
**Anmerkung**
API Gateway entfernt Nicht-ASCII-Zeichen aus der ApiName Dimension, bevor Metriken an gesendet werden. CloudWatch Wenn der APIName keine ASCII-Zeichen enthält, wird die API ID als ApiName verwendet.
| Dimension | Beschreibung |
| --- | --- |
| ApiName | Filtert API Gateway-Metriken für die REST-API mit dem angegebenen API-Namen. |
| ApiName, Method, Resource, Stage | Filtert API Gateway-Metriken für die API-Methode mit dem angegebenen API-Namen, der Stufe, Ressource und Methode. API Gateway sendet diese Metriken nur, wenn Sie detaillierte CloudWatch Metriken explizit aktiviert haben. Wählen Sie in der Konsole eine Stufe aus, und klicken Sie dann unter **Ptotokolle und Nachverfolgung** auf **Bearbeiten**. Wählen Sie **Detaillierte Metriken** aus und klicken Sie dann auf **Änderungen speichern**. Alternativ können Sie den AWS CLI Befehl [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) aufrufen, um die `metricsEnabled` Eigenschaft zu aktualisieren. `true` Durch die Aktivierung dieser Metriken wird Ihr Konto mit zusätzlichen Gebühren belastet. Preisinformationen finden Sie unter [ CloudWatchAmazon-Preise](https://aws.amazon.com/cloudwatch/pricing/). |
| ApiName, Stage | Filtert API Gateway-Metriken für die API-Stufenressource mit dem angegebenen API-Namen und der Stufe. |
# Anzeigen von CloudWatch-Metriken mit dem API-Dashboard in API Gateway
Sie können das API-Dashboard in der API Gateway-Konsole verwenden, um die CloudWatch-Metriken Ihrer bereitgestellten API in API Gateway anzuzeigen. Diese werden als eine Zusammenfassung der API-Aktivität im Zeitverlauf angezeigt.
**Topics**
+ [Voraussetzungen](#how-to-api-dashboard-prerequisites)
+ [Untersuchen von API-Aktivitäten im Dashboard](#how-to-api-dashboard-console)
## Voraussetzungen
1. Sie müssen über eine in API Gateway erstellte API verfügen. Folgen Sie den Anweisungen in [Entwickeln Sie REST APIs in API Gateway](rest-api-develop.md).
1. 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).
## Untersuchen von API-Aktivitäten im Dashboard
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 API aus.
1. Wählen Sie im Haupt-Navigationsbereich **Dashboard** aus.
1. Wählen Sie für **Stufe** die gewünschte Stufe aus.
1. Wählen Sie **Datumsbereich** aus, um einen Datumsbereich anzugeben.
1. Aktualisieren Sie bei Bedarf einzelne Metriken in separaten Grafiken mit den Titeln **API-Aufrufe**, **Latenz**, **Integrationslatenz**, **Latenz**, **4xx-Fehler** und **5xx-Fehler**.
**Tipp**
Um die CloudWatch-Metriken auf Methodenebene zu untersuchen, stellen Sie sicher, dass Sie CloudWatch Logs auf einer Methodenebene aktiviert haben. Weitere Informationen zum Einrichten der Protokollierung auf Methodenebene finden Sie unter [Überschreiben der Einstellungen auf Stufenebene](set-up-stages.md#how-to-method-override).
# API Gateway Gateway-Metriken in der CloudWatch Konsole anzeigen
Metriken werden zunächst nach dem Service-Namespace und anschließend nach den verschiedenen Dimensionskombinationen in den einzelnen Namespaces gruppiert. Aktivieren Sie „Detaillierte Metriken“, um die Metriken auf Methodenebene für Ihre API anzuzeigen. Weitere Informationen finden Sie unter [Ändern der Stufeneinstellungen](set-up-stages.md#how-to-stage-settings).
**So zeigen Sie API Gateway Gateway-Metriken mit der CloudWatch Konsole an**
1. Öffnen Sie die CloudWatch Konsole unter [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Ändern Sie, falls erforderlich, die AWS-Region. Wählen Sie in der Navigationsleiste die Region aus, in der sich Ihre AWS Ressourcen befinden.
1. Wählen Sie im Navigationsbereich **Metrics** aus.
1. Klicken Sie auf der Registerkarte **All metrics** auf **API Gateway**.
1. Klicken Sie auf den Bereich **By Stage**, um Metriken nach Phase anzuzeigen. Wählen Sie dann Ihre Namen APIs und die Namen der Metriken aus.
1. Klicken Sie auf den Bereich **By Api Name**, um Metriken für eine bestimmte API anzuzeigen. Wählen Sie dann Ihre Namen APIs und die Namen der Metriken aus.
**So zeigen Sie Metriken mit der AWS CLI an**
1. Verwenden Sie den folgenden [list-metrics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/list-metrics.html)-Befehl, um Metriken aufzuführen:
```
aws cloudwatch list-metrics --namespace "AWS/ApiGateway"
```
Nachdem Sie eine Metrik erstellt haben, kann es bis zu 15 Minuten dauern, bis die Metrik angezeigt wird. Verwenden Sie [get-metric-data](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/update-domain-name.html)oder, um Metrikstatistiken schneller zu sehen [get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/update-domain-name.html).
1. Verwenden Sie den folgenden [get-metrics-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html)Befehl, um den Durchschnitt über einen bestimmten Zeitraum in Intervallen von 5 Minuten anzuzeigen:
```
aws cloudwatch get-metric-statistics --namespace AWS/ApiGateway --metric-name Count --start-time 2011-10-03T23:00:00Z --end-time 2017-10-05T23:00:00Z --period 300 --statistics Average
```
# API Gateway Gateway-Protokollereignisse in der CloudWatch Konsole anzeigen
Im folgenden Abschnitt werden die erforderlichen Voraussetzungen und die Anzeige von API-Gateway-Protokollereignissen in der CloudWatch Konsole erläutert.
## Voraussetzungen
1. Sie müssen über eine in API Gateway erstellte API verfügen. Folgen Sie den Anweisungen in [Entwickeln Sie REST APIs in API Gateway](rest-api-develop.md).
1. Sie müssen die API mindestens einmal in der API bereitgestellt haben. Befolgen Sie die Anweisungen unter [REST-APIs in API Gateway bereitstellen](how-to-deploy-api.md) und [Aufrufen von REST-APIs in API Gateway](how-to-call-api.md).
1. Sie müssen CloudWatch Logs für eine Phase aktiviert haben. Folgen Sie den Anweisungen in [Richten Sie die CloudWatch Protokollierung für REST APIs in API Gateway ein](set-up-logging.md).
## Um protokollierte API-Anfragen und -Antworten mit der CloudWatch Konsole anzuzeigen
1. Öffnen Sie die CloudWatch Konsole unter [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Ändern Sie, falls erforderlich, die AWS-Region. Wählen Sie in der Navigationsleiste die Region aus, in der sich Ihre AWS Ressourcen befinden. Weitere Informationen finden Sie unter [-Regionen und Endpunkte](https://docs.aws.amazon.com/general/latest/gr/rande.html).
1. Wählen Sie im Navigationsbereich **Logs (Protokolle)**, **Log groups (Protokollgruppen)** aus.
1. Wählen Sie in der Tabelle **Protokollgruppen** eine Protokollgruppe mit dem Namen **API-Gateway-Execution-Logs\$1** \$1\$1/\$1stage-name\$1 aus. rest-api-id
1. Wählen Sie in der Tabelle **Log Streams** einen Protokoll-Stream aus. Sie können den gewünschten Protokoll-Stream anhand des Zeitstempels finden.
1. Klicken Sie auf **Text**, um den reinen Text anzuzeigen, oder klicken Sie auf **Row**, um das Ereignis zeilenweise anzuzeigen.
**Wichtig**
CloudWatch ermöglicht das Löschen von Protokollgruppen oder Streams. Löschen Sie API Gateway-API-Protokollgruppen oder -Streams nicht manuell. Lassen Sie API Gateway diese Ressourcen verwalten. Wenn Sie Protokollgruppen oder Streams manuell löschen, werden API-Anforderungen und -Antworten möglicherweise nicht protokolliert. In diesem Fall können Sie die gesamte Protokollgruppe für die API löschen und die API erneut bereitstellen. Dies liegt daran, dass API Gateway Protokollgruppen oder -Streams einer API-Stufe zum Zeitpunkt der Bereitstellung erstellt.
# Überwachungstools AWS für API Gateway
AWS bietet verschiedene Tools, mit denen Sie API Gateway überwachen können. Sie können einige dieser Tools für die automatische Überwachung konfigurieren, während andere manuellen Eingriff erfordern. Wir empfehlen, dass Sie die Überwachungsaufgaben möglichst automatisieren.
## Automatisierte Überwachungstools in AWS
Sie können die folgenden automatisierten Tools zur Überwachung von API Gateway verwenden und auftretende Probleme melden:
+ **Amazon CloudWatch Alarms** — Überwachen Sie eine einzelne Metrik über einen von Ihnen angegebenen Zeitraum und führen Sie eine oder mehrere Aktionen aus, die auf dem Wert der Metrik im Verhältnis zu einem bestimmten Schwellenwert über mehrere Zeiträume basieren. Die Aktion ist eine Benachrichtigung, die an ein Amazon Simple Notification Service (Amazon SNS) -Thema oder eine Amazon EC2 Auto Scaling Scaling-Richtlinie gesendet wird. CloudWatch Alarme lösen keine Aktionen aus, nur weil sie sich in einem bestimmten Status befinden. Der Status muss sich geändert haben und für eine bestimmte Anzahl von Zeiträumen beibehalten worden sein. Weitere Informationen finden Sie unter [Überwachen Sie die REST-API-Ausführung mit CloudWatch Amazon-Metriken](monitoring-cloudwatch.md).
+ **Amazon CloudWatch Logs** — Überwachen, speichern und greifen Sie auf Ihre Protokolldateien aus AWS CloudTrail oder anderen Quellen zu. Weitere Informationen finden Sie unter [Was ist CloudWatch Logs?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html) im * CloudWatch Amazon-Benutzerhandbuch*.
+ **Amazon EventBridge (früher CloudWatch Events genannt)** — Ordnen Sie Ereignisse zu und leiten Sie sie an eine oder mehrere Zielfunktionen oder Streams weiter, um Änderungen vorzunehmen, Statusinformationen zu erfassen und Korrekturmaßnahmen zu ergreifen. Weitere Informationen finden Sie unter [Was ist Amazon EventBridge?](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) im *EventBridge Benutzerhandbuch*.
+ **AWS CloudTrail Protokollüberwachung** — Teilen Sie Protokolldateien zwischen Konten, überwachen CloudTrail Sie Protokolldateien in Echtzeit, indem Sie sie an CloudWatch Logs senden, schreiben Sie Anwendungen zur Protokollverarbeitung in Java und stellen Sie sicher, dass sich Ihre Protokolldateien nach der Lieferung von nicht geändert haben CloudTrail. Weitere Informationen finden Sie unter [Arbeiten mit CloudTrail Protokolldateien](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-working-with-log-files.html) im *AWS CloudTrail Benutzerhandbuch*.
## Manuelle Überwachungstools
Ein weiterer wichtiger Teil der Überwachung von API Gateway besteht darin, die Elemente, die von den CloudWatch Alarmen nicht abgedeckt werden, manuell zu überwachen. Das API Gateway und andere AWS Konsolen-Dashboards bieten einen at-a-glance Überblick über den Zustand Ihrer AWS Umgebung. CloudWatch Wir empfehlen, auch die Protokolldateien für die API-Ausführung zu überprüfen.
+ Das API Gateway-Dashboard zeigt die folgenden Statistiken für eine bestimmte API-Stufe in einem bestimmten Zeitraum:
+ **API Calls**
+ **Cache Hit**, nur wenn das API-Caching aktiviert ist.
+ **Cache Miss**, nur wenn das API-Caching aktiviert ist.
+ **Latency**
+ **Integration Latency**
+ **4XX Error**
+ **5XX Error**
+ Auf der CloudWatch Startseite wird Folgendes angezeigt:
+ Aktuelle Alarme und Status
+ Diagramme mit Alarmen und Ressourcen
+ Servicestatus
Darüber hinaus können CloudWatch Sie Folgendes verwenden:
+ Erstellen [angepasster Dashboards](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html) zur Überwachung der gewünschten Services.
+ Aufzeichnen von Metrikdaten, um Probleme zu beheben und Trends zu erkennen
+ Suchen und durchsuchen Sie alle Ihre AWS Ressourcenmetriken
+ Erstellen und Bearbeiten von Alarmen, um über Probleme benachrichtigt zu werden
## CloudWatch Alarme zur Überwachung des API Gateway erstellen
Sie können einen CloudWatch Alarm erstellen, der eine Amazon SNS SNS-Nachricht sendet, wenn sich der Status des Alarms ändert. Ein Alarm überwacht eine Metrik über einen bestimmten, von Ihnen definierten Zeitraum und führt eine oder mehrere Aktionen durch, die vom Wert der Metrik im Vergleich zu einem festgelegten Schwellenwert in einer Reihe von Zeiträumen abhängt. Die Aktion ist eine Benachrichtigung, die an ein Amazon SNS-Thema oder eine Auto Scaling-Richtlinie gesendet wird. Bei Alarmen werden nur Aktionen für anhaltende Statusänderungen ausgelöst. CloudWatch Alarme lösen keine Aktionen aus, nur weil sie sich in einem bestimmten Zustand befinden. Der Zustand muss sich geändert haben und für eine bestimmte Anzahl von Zeiträumen beibehalten worden sein.
# Richten Sie die CloudWatch Protokollierung für REST APIs in API Gateway ein
Um Probleme im Zusammenhang mit der Ausführung von Anfragen oder dem Client-Zugriff auf Ihre API zu beheben, können Sie Amazon CloudWatch Logs zur Protokollierung von API-Aufrufen aktivieren. Weitere Informationen zu finden Sie CloudWatch unter[Überwachen Sie die REST-API-Ausführung mit CloudWatch Amazon-Metriken](monitoring-cloudwatch.md).
## CloudWatch Protokollformate für API Gateway
Es gibt zwei Arten der API-Anmeldung CloudWatch: Ausführungsprotokollierung und Zugriffsprotokollierung. Bei der Ausführungsprotokollierung verwaltet API Gateway die CloudWatch Protokolle. Der Prozess umfasst das Erstellen von Protokollgruppen und -Streams sowie die Meldung der Anforderungen und Antworten jedes Aufrufers an Protokoll-Streams.
Die Protokolldaten umfassen Fehler oder Ablaufverfolgungen der Ausführung (z. B. Parameterwerte oder Nutzlasten von Anforderungen oder Antworten), von Lambda-Genehmigern (ehemals als benutzerdefinierte Genehmiger bezeichnet) verwendete Daten, Angaben darüber, ob API-Schlüssel erforderlich sind, Informationen dazu, ob Nutzungspläne aktiviert sind, und mehr. API Gateway redigiert Genehmigungs-Header, API-Schlüsselwerte und ähnliche sensible Anforderungsparameter aus den protokollierten Daten.
Zur Verbesserung Ihrer Sicherheitslage empfehlen wir Ihnen, die Ausführungsprotokollierung auf der `ERROR`- oder `INFO`-Ebene zu verwenden. Dies kann erforderlich sein, um verschiedene Compliance-Rahmenwerke einzuhalten. Weitere Informationen finden Sie unter [Amazon-API-Gateway-Steuerelemente](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) im *Benutzerhandbuch für AWS Security Hub *.
Wenn Sie eine API bereitstellen, erstellt API Gateway eine Protokollgruppe und -Streams unter der Protokollgruppe. Die Protokollgruppe wird nach dem `API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}`-Format benannt. In jeder Protokollgruppe, werden die Protokolle weiter in Protokoll-Streams unterteilt, die bei Meldung von Protokolldaten nach **Last Event Time** sortiert werden.
In der Zugriffsprotokollierung protokollieren Sie, als API-Entwickler, wer auf Ihre API zugegriffen hat und wie der Aufrufer auf die API zugegriffen hat. Erstellen Sie eine eigene Protokollgruppe oder wählen Sie eine vorhandene Protokollgruppe aus, die von API Gateway verwaltet werden kann. Wählen Sie [`$context`](api-gateway-variables-for-access-logging.md)-Variablen, ein Protokollformat und eine Protokollgruppe als Ziel aus, um die Zugriffsdetails anzugeben.
Das Zugriffsprotokoll-Format muss mindestens `$context.requestId` oder `$context.extendedRequestId` enthalten. Es hat sich bewährt, `$context.requestId` und `$context.extendedRequestId` in das Protokollformat aufzunehmen.
**`$context.requestId`**
Hiermit wird der Wert in der `x-amzn-RequestId`-Kopfzeile protokolliert. Clients können den Wert im `x-amzn-RequestId`-Header durch einen Wert im Format einer UUID (Universally Unique Identifier) überschreiben. API Gateway gibt diese Anforderungs-ID im `x-amzn-RequestId`-Antwort-Header zurück. API Gateway ersetzt überschriebene Anfragen IDs , die nicht das Format einer UUID haben, durch `UUID_REPLACED_INVALID_REQUEST_ID` in Ihren Zugriffsprotokollen.
**`$context.extendedRequestId`**
Die extendedRequestId ist eine eindeutige, von API Gateway generierte Kennung. API Gateway gibt diese Anforderungs-ID im `x-amz-apigw-id`-Antwort-Header zurück. Ein API-Aufrufer kann diese Anforderungs-ID nicht bereitstellen oder überschreiben. Möglicherweise müssen Sie diesen Wert dem AWS Support zur Verfügung stellen, um die Fehlerbehebung für Ihre API zu unterstützen. Weitere Informationen finden Sie unter [Variablen für die Zugriffsprotokollierung in API Gateway](api-gateway-variables-for-access-logging.md).
Wählen Sie ein Protokollformat aus, das auch von Ihrem analytischen Backend genutzt wird, z. B. [Common Log Format](https://httpd.apache.org/docs/current/logs.html#common) (CLF), JSON, XML, oder CSV. Anschließend können Sie die Zugriffsprotokolle direkt eingeben und Ihre Metriken berechnen und rendern lassen. [Um das Protokollformat zu definieren, legen Sie den ARN der Protokollgruppe in der Eigenschaft [accessLogSettings/DestinationArn](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#destinationArn) auf der Bühne fest.](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) Sie können einen Protokollgruppen-ARN in der CloudWatch Konsole abrufen. Um das Format des Zugriffsprotokolls zu definieren, legen Sie in der Eigenschaft [accessLogSetting/format auf der [Bühne](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) ein ausgewähltes Format](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#format) fest.
Beispiele für einige häufig verwendete Zugriffsprotokollformate werden in der API Gateway-Konsole dargestellt und wie folgt aufgeführt.
+ `CLF` ([Common Log Format](https://httpd.apache.org/docs/current/logs.html#common)):
```
$context.identity.sourceIp $context.identity.caller $context.identity.user [$context.requestTime]"$context.httpMethod $context.resourcePath $context.protocol" $context.status $context.responseLength $context.requestId $context.extendedRequestId
```
+ `JSON`:
```
{ "requestId":"$context.requestId", "extendedRequestId":"$context.extendedRequestId","ip": "$context.identity.sourceIp", "caller":"$context.identity.caller", "user":"$context.identity.user", "requestTime":"$context.requestTime", "httpMethod":"$context.httpMethod", "resourcePath":"$context.resourcePath", "status":"$context.status", "protocol":"$context.protocol", "responseLength":"$context.responseLength" }
```
+ `XML`:
```
$context.extendedRequestId $context.identity.sourceIp $context.identity.caller $context.identity.user $context.requestTime $context.httpMethod $context.resourcePath $context.status $context.protocol $context.responseLength
```
+ `CSV` (durch Komma getrennte Werte):
```
$context.identity.sourceIp,$context.identity.caller,$context.identity.user,$context.requestTime,$context.httpMethod,$context.resourcePath,$context.protocol,$context.status,$context.responseLength,$context.requestId,$context.extendedRequestId
```
## Berechtigungen für die Protokollierung CloudWatch
Um CloudWatch Logs zu aktivieren, müssen Sie API Gateway die Erlaubnis erteilen, Logs CloudWatch für Ihr Konto zu lesen und zu schreiben. [Amazon APIGateway PushToCloudWatchLogs](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAPIGatewayPushToCloudWatchLogs.html) verfügt über alle erforderlichen Berechtigungen.
**Anmerkung**
API Gateway ruft AWS -Security-Token-Service auf, um die IAM-Rolle zu übernehmen. Stellen Sie also sicher, dass diese für die Region aktiviert AWS STS ist. Weitere Informationen finden Sie unter [AWS STS in einer AWS Region verwalten](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html).
[https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html#cloudWatchRoleArn](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html#cloudWatchRoleArn) Sie müssen die Eigenschaft [cloudWatchRoleArn](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html#cloudWatchRoleArn) für jede AWS Region, in der Sie Logs aktivieren möchten, separat festlegen. CloudWatch
Wenn Sie beim Einstellen des ARN für die IAM-Rolle eine Fehlermeldung erhalten, überprüfen Sie Ihre AWS -Security-Token-Service Kontoeinstellungen, um sicherzustellen, dass diese in der Region, die Sie verwenden, aktiviert AWS STS ist. Weitere Informationen zur Aktivierung AWS STS finden Sie im *IAM-Benutzerhandbuch* unter [AWS STS in einer AWS Region verwalten](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html#sts-regions-activate-deactivate).
## CloudWatch API-Protokollierung mit der API Gateway Gateway-Konsole einrichten
Um die CloudWatch API-Protokollierung einzurichten, müssen Sie die API in einer Phase bereitgestellt haben. Sie müssen auch [einen entsprechenden CloudWatch Logs-Rollen-ARN](#set-up-access-logging-permissions) für Ihr Konto konfiguriert haben.
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 im Hauptnavigationsbereich **Settings** (Einstellungen) und dann unter **Logging** (Protokollierung) die Option **Edit** (Bearbeiten) aus.
1. Geben Sie für die **CloudWatch Protokollrolle ARN** einen ARN einer IAM-Rolle mit den entsprechenden Berechtigungen ein. Sie müssen dies einmal für jeden Vorgang tun AWS-Konto , der APIs mithilfe von API Gateway erstellt wurde.
1. Wählen Sie im Hauptnavigationsbereich eine der folgenden Optionen aus **APIs**, und führen Sie dann eine der folgenden Aktionen aus:
1. Wählen Sie eine vorhandene API und anschließend eine Stufe aus.
1. Erstellen Sie eine API und stellen Sie diese dann einer Stufe bereit.
1. Klicken Sie im Hauptnavigationsbereich auf **Stages** (Stufen).
1. Wählen Sie im Abschnitt **Logs and tracing** (Protokolle und Nachverfolgung) die Option **Edit** (Bearbeiten) aus.
1. So aktivieren Sie die Ausführungsprotokollierung:
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. (Optional) Wählen Sie **Datenablaufverfolgung** aus, um die Protokollierung der Datenablaufverfolgung für Ihre Stufe zu aktivieren. 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. (Optional) Wählen Sie **Detaillierte Metriken** aus, um detaillierte CloudWatch Metriken zu aktivieren.
Weitere Informationen zu CloudWatch Metriken finden Sie unter[Überwachen Sie die REST-API-Ausführung mit CloudWatch Amazon-Metriken](monitoring-cloudwatch.md).
1. So aktivieren Sie die Zugriffsprotokollierung:
1. Aktivieren Sie die Option **Custom access logging** (Benutzerdefinierte Zugriffsprotokollierung).
1. Geben Sie den ARN einer Protokollgruppe in **Access Log Destination ARN** (Ziel-ARN des Zugriffsprotokolls) ein. Das ARN-Format ist `arn:aws:logs:{region}:{account-id}:log-group:log-group-name`.
1. Geben Sie unter **Log Format** (Protokollformat) ein Protokollformat ein. Sie können zwischen **CLF**, **JSON**, **XML** oder **CSV** wählen. Weitere Informationen zu Beispielprotokollformaten finden Sie unter [CloudWatch Protokollformate für API Gateway](#apigateway-cloudwatch-log-formats).
1. Wählen Sie **Änderungen speichern ** aus.
**Anmerkung**
Sie können die Ausführungs- und Zugriffsprotokollierung unabhängig voneinander aktivieren.
API Gateway kann nun Anforderungen an Ihre API protokollieren. Sie müssen die API nicht erneut bereitstellen, wenn Sie die Stufeneinstellungen, Protokolle oder Stufenvariablen aktualisieren.
## Richten Sie die CloudWatch API-Protokollierung ein mit CloudFormation
Verwenden Sie die folgende CloudFormation Beispielvorlage, um eine Amazon CloudWatch Logs-Protokollgruppe zu erstellen und die Ausführungs- und Zugriffsprotokollierung für eine Phase zu konfigurieren. Um CloudWatch Logs zu aktivieren, müssen Sie API Gateway die Erlaubnis erteilen, Logs CloudWatch für Ihr Konto zu lesen und zu schreiben. Weitere Informationen finden Sie unter [Konto mit IAM-Rolle verknüpfen](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-account.html#aws-resource-apigateway-account--examples) im *AWS CloudFormation -Benutzerhandbuch*.
```
TestStage:
Type: AWS::ApiGateway::Stage
Properties:
StageName: test
RestApiId: !Ref MyAPI
DeploymentId: !Ref Deployment
Description: "test stage description"
MethodSettings:
- ResourcePath: "/*"
HttpMethod: "*"
LoggingLevel: INFO
AccessLogSetting:
DestinationArn: !GetAtt MyLogGroup.Arn
Format: $context.extendedRequestId $context.identity.sourceIp $context.identity.caller $context.identity.user [$context.requestTime] "$context.httpMethod $context.resourcePath $context.protocol" $context.status $context.responseLength $context.requestId
MyLogGroup:
Type: AWS::Logs::LogGroup
Properties:
LogGroupName: !Join
- '-'
- - !Ref MyAPI
- access-logs
```
# Protokollierung von REST-API-Aufrufen unter Amazon Data Firehose im API Gateway
Sie können API-Aufrufe unter Amazon Data Firehose protokollieren, um Probleme im Zusammenhang mit dem Client-Zugriff auf Ihre API zu beheben. Weitere Informationen zu Firehose finden Sie unter [Was ist Amazon Data Firehose?](https://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html).
Für die Zugriffsprotokollierung können Sie nur CloudWatch oder Firehose aktivieren — Sie können nicht beide aktivieren. Sie können jedoch die Ausführungsprotokollierung und Firehose für die Zugriffsprotokollierung aktivieren CloudWatch .
**Topics**
+ [Firehose-Protokollformate für API Gateway](#apigateway-kinesis-log-formats)
+ [Berechtigungen für die Firehose-Protokollierung](#set-up-kinesis-access-logging-permissions)
+ [Einrichten der Firehose-Zugriffsprotokollierung mithilfe der API-Gateway-Konsole](#set-up-kinesis-access-logging-using-console)
## Firehose-Protokollformate für API Gateway
Die Firehose-Protokollierung verwendet dasselbe Format wie die [CloudWatch Protokollierung](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-logging.html).
## Berechtigungen für die Firehose-Protokollierung
Wenn die Firehose-Zugriffsprotokollierung für eine Stufe aktiviert ist, erstellt API Gateway eine servicebezogene Rolle für Ihr Konto, sofern die Rolle nicht bereits vorhanden ist. Die Rolle wird `AWSServiceRoleForAPIGateway` benannt und die verwaltete `APIGatewayServiceRolePolicy`-Richtlinie wird an sie angehängt. Weitere Informationen zu serviceverknüpften Rollen finden Sie unter [Verwenden serviceverknüpfter Rollen](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html).
**Anmerkung**
Der Name Ihres Firehose-Streams muss `amazon-apigateway-{your-stream-name}` lauten.
## Einrichten der Firehose-Zugriffsprotokollierung mithilfe der API-Gateway-Konsole
Zum Einrichten der API-Protokollierung müssen Sie die API für eine Stufe bereitgestellt haben. Ein Firehose-Stream muss bereits erstellt worden sein.
1. Melden Sie sich bei der API Gateway Gateway-Konsole unter [https://console.aws.amazon.com/apigatewayan](https://console.aws.amazon.com/apigateway).
1. Führen Sie eine der folgenden Aktionen aus:
1. Wählen Sie eine vorhandene API und anschließend eine Stufe aus.
1. Erstellen Sie eine API und stellen Sie diese einer Stufe bereit.
1. Klicken Sie im Hauptnavigationsbereich auf **Stages** (Stufen).
1. Wählen Sie im Abschnitt **Logs and tracing** (Protokolle und Nachverfolgung) die Option **Edit** (Bearbeiten) aus.
1. So aktivieren Sie die Zugriffsprotokollierung für einen Firehose-Stream:
1. Aktivieren Sie die Option **Custom access logging** (Benutzerdefinierte Zugriffsprotokollierung).
1. Geben Sie den ARN eines Firehose-Streams unter **ARN für Zugriffsprotokollziel** ein. Das ARN-Format ist `arn:aws:firehose:{region}:{account-id}:deliverystream/amazon-apigateway-{your-stream-name}`.
**Anmerkung**
Der Name Ihres Firehose-Streams muss `amazon-apigateway-{your-stream-name}` lauten.
1. Geben Sie unter **Log Format** (Protokollformat) ein Protokollformat ein. Sie können zwischen **CLF**, **JSON**, **XML** oder **CSV** wählen. 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 **Änderungen speichern ** aus.
API Gateway kann ab sofort API-Aufrufe unter Firehose protokollieren. Sie müssen die API nicht erneut bereitstellen, wenn Sie die Stufeneinstellungen, Protokolle oder Stufenvariablen aktualisieren.
# Variablen für die Zugriffsprotokollierung in API Gateway
In der Zugriffsprotokollierung protokollieren Sie, als API-Entwickler, wer auf Ihre API zugegriffen hat und wie der Aufrufer auf die API zugegriffen hat. Erstellen Sie eine eigene Protokollgruppe oder wählen Sie eine vorhandene Protokollgruppe aus, die von API Gateway verwaltet werden kann. Um die Zugriffsdetails anzugeben, können Sie die folgenden `$context`-Variablen verwenden, bei denen die Groß- und Kleinschreibung beachtet werden muss.
Eine Liste der Referenzvariablen für Datentransformationen finden Sie unter [Variablen für Datentransformationen für API Gateway](api-gateway-mapping-template-reference.md).
| Parameter | Description |
| --- | --- |
| \$1context.accountId | Die AWS Konto-ID des API-Besitzers. |
| \$1context.apiId | Die ID, die API Gateway Ihrer API zuweist. |
| \$1context.authorize.error | Die Autorisierungsfehlermeldung. |
| \$1context.authorize.latency | Die Autorisierungslatenz in ms |
| \$1context.authorize.status | Der Statuscode, der von einem Autorisierungsversuch zurückgegeben wurde. |
| \$1context.authorizer.claims.property | Eine Eigenschaft der Claims, die aus dem Amazon Cognito-Benutzerpool zurückgegeben werden, nachdem der Methodenaufrufer erfolgreich authentifiziert wurde. Weitere Informationen finden Sie unter [Steuern Sie den Zugriff auf REST APIs mithilfe von Amazon Cognito Cognito-Benutzerpools als Autorisierer](apigateway-integrate-with-cognito.md). Bei einem Aufruf von `$context.authorizer.claims` wird null (0) zurückgegeben. |
| \$1context.authorizer.error | Die von einem Genehmiger zurückgegebene Fehlermeldung. |
| \$1context.authorizer.integrationLatency | Die Integrationslatenz des Genehmigers in Millisekunden |
| \$1context.authorizer.integrationStatus | Der von einem Lambda-Genehmiger zurückgegebene Statuscode. |
| \$1context.authorizer.latency | Der Genehmiger-Latenz in ms. |
| \$1context.authorizer.principalId | Die ID des Prinzipalbenutzers in Verbindung mit dem Token, das vom Client gesendet und von einem API Gateway-Lambda-Genehmiger (früher als benutzerdefinierter Genehmiger bekannt) zurückgegeben wurde. Weitere Informationen finden Sie unter [API Gateway-Lambda-Genehmiger verwenden](apigateway-use-lambda-authorizer.md). |
| \$1context.authorizer.property | Der in einer Zeichenfolge umgewandelte Wert des angegebenen Schlüssel-Wert-Paares der `context`-Zuordnung, der von einer API Gateway Lambda-Genehmigerfunktion zurückgegeben wird. Angenommen, der Genehmiger gibt folgende `context`-Zuweisung zurück: "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} Ein Aufruf von `$context.authorizer.key` gibt die Zeichenfolge `"value"` zurück, ein Aufruf von `$context.authorizer.numKey` gibt die Zeichenfolge `"1"` zurück und ein Aufruf von `$context.authorizer.boolKey` gibt die Zeichenfolge `"true"` zurück. Denn *property* das einzige unterstützte Sonderzeichen ist der `(_)` Unterstrich. Weitere Informationen finden Sie unter [API Gateway-Lambda-Genehmiger verwenden](apigateway-use-lambda-authorizer.md). |
| \$1context.authorizer.requestId | Die Anforderungs-ID des AWS Endpunkts. |
| \$1context.authorizer.status | Der von einem Genehmiger zurückgegebene Statuscode. |
| \$1context.authenticate.error | Die von einem Authentifizierungsversuch zurückgegebene Fehlermeldung. |
| \$1context.authenticate.latency | Die Authentifizierungslatenz in ms |
| \$1context.authenticate.status | Der Statuscode, der von einem Authentifizierungsversuch zurückgegeben wurde. |
| \$1context.awsEndpointRequestId | Die Anforderungs-ID des AWS Endpunkts. |
| \$1context.cipherSuite | Die Chiffre im IANA-Format, die während des TLS-Handshakes zwischen dem Client und dem API Gateway ausgehandelt wird. |
| \$1context.customDomain.basePathMatched | Der Pfad für ein API-Mapping, mit dem eine eingehende Anforderung übereinstimmte. Gilt, wenn ein Client einen benutzerdefinierten Domain-Namen für den Zugriff auf eine API verwendet. Wenn ein Client beispielsweise eine Anforderung an `https://api.example.com/v1/orders/1234` sendet und die Anforderung dem API-Mapping mit dem Pfad `v1/orders` übereinstimmt, lautet der Wert `v1/orders`. Weitere Informationen hierzu finden Sie unter [Verwenden Sie API-Zuordnungen, um API-Stufen mit einem benutzerdefinierten Domainnamen für REST zu verbinden APIs](rest-api-mappings.md). |
| \$1context.customDomain.routingRuleIdMatched | Die Routing-Regel, mit der eine eingehende Anfrage übereinstimmte. Gilt, wenn ein Client einen benutzerdefinierten Domain-Namen für den Zugriff auf eine API verwendet. Weitere Informationen hierzu finden Sie unter [Routing-Regeln zum Verbinden von API-Stufen mit einem benutzerdefinierten Domainnamen für REST APIs](rest-api-routing-rules.md). |
| \$1context.deploymentId | Die ID der API-Bereitstellung |
| \$1context.domainName | Der zum Aufrufen der API verwendete vollständige Domänennamen. Dieser Wert sollte mit dem für den eingehenden `Host`-Header übereinstimmen. |
| \$1context.domainPrefix | Das erste Label der `$context.domainName`. |
| \$1context.endpointType | Der Endpunkttyp der API. |
| \$1context.error.message | Eine Zeichenfolge, die eine API Gateway-Fehlermeldung enthält. Diese Variable kann nur für die einfache Variablenersetzung in einer [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)Body-Mapping-Vorlage, die nicht von der Velocity Template Language-Engine verarbeitet wird, und in der Zugriffsprotokollierung verwendet werden. Weitere Informationen erhalten Sie unter [Überwachen Sie die WebSocket API-Ausführung mit CloudWatch Metriken](apigateway-websocket-api-logging.md) und [Einrichten von Gateway-Antworten, um Fehlerantworten anzupassen](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). |
| \$1context.error.messageString | Die Wert von \$1context.error.message in Anführungszeichen, d. h. "\$1context.error.message". |
| \$1context.error.responseType | [Ein Typ von. [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType) Diese Variable kann nur für die einfache Variablenersetzung in einer [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)Body-Mapping-Vorlage, die nicht von der Velocity Template Language-Engine verarbeitet wird, und für die Zugriffsprotokollierung verwendet werden. Weitere Informationen erhalten Sie unter [Überwachen Sie die WebSocket API-Ausführung mit CloudWatch Metriken](apigateway-websocket-api-logging.md) und [Einrichten von Gateway-Antworten, um Fehlerantworten anzupassen](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). |
| \$1context.error.validationErrorString | Eine Zeichenfolge mit einer detaillierten Validierungs-Fehlermeldung. |
| \$1context.extendedRequestId | Die erweiterte ID, die API Gateway generiert und der API-Anfrage zuweist. Die erweiterte Anforderungs-ID enthält zusätzliche nützliche Informationen für Debugging und Fehlerbehebung. |
| \$1context.httpMethod | Die verwendete HTTP-Methode. Gültige Werte sind: `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` und `PUT`. |
| \$1context.identity.accountId | Die mit der Anfrage verknüpfte AWS Konto-ID. |
| \$1context.identity.apiKey | Bei API-Methoden, für die ein API-Schlüssel erforderlich ist, ist diese Variable der API-Schlüssel für die Methodenanforderung. Bei Methoden, für die kein API-Schlüssel erforderlich ist, ist diese Variable nichtig. Weitere Informationen finden Sie unter [Nutzungspläne und API-Schlüssel für REST APIs in API Gateway](api-gateway-api-usage-plans.md). |
| \$1context.identity.apiKeyId | Die API-Schlüssel-ID für die API-Anforderung, falls ein API-Schlüssel erforderlich ist. |
| \$1context.identity.caller | Die Hauptkennung des Aufrufers, der die Anforderung signiert hat. Wird für Ressourcen unterstützt, die die IAM-Autorisierung verwenden. |
| \$1context.identity.cognitoAuthenticationProvider | Eine durch Komma getrennte Liste aller Amazon-Cognito-Authentifizierungsanbieter, die vom anfordernden Aufrufer verwendet werden. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde. Zum Beispiel für eine Identität aus einem Amazon Cognito-Benutzerpool, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Weitere Informationen zu verfügbaren Amazon-Cognito-Authentifizierungsanbietern finden Sie unter [Verbundidentitäten verwenden](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) im *Amazon-Cognito-Entwicklerhandbuch*. |
| \$1context.identity.cognitoAuthenticationType | Der Amazon Cognito-Authentifizierungstyp des Aufrufers, der den Anfrage erstellt hat. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde. Mögliche Werte sind `authenticated` für authentifizierte Identitäten und `unauthenticated` für nicht authentifizierte Identitäten. |
| \$1context.identity.cognitoIdentityId | Die Amazon Cognito Identitäts-ID des anfordernden Aufrufers. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde. |
| \$1context.identity.cognitoIdentityPoolId | Die Amazon Cognito Identitätspool-ID des anfordernden Aufrufers. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde. |
| \$1context.identity.principalOrgId | Die [AWS -Organisations-ID](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). |
| \$1context.identity.sourceIp | Die Quell-IP-Adresse der TCP-Verbindung, von der die Anforderung an den API-Gateway-Endpunkt gesendet wird. |
| \$1context.identity.clientCert.clientCertPem | Das PEM-codierte Clientzertifikat, das der Client während der gegenseitigen TLS-Authentifizierung präsentiert hat. Vorhanden, wenn ein Client mithilfe eines benutzerdefinierten Domänennamens, für den gegenseitige TLS aktiviert ist, auf eine API zugreift. Nur in Zugriffsprotokollen vorhanden, wenn die gegenseitige TLS-Authentifizierung fehlschlägt. |
| \$1context.identity.clientCert.subjectDN | Der Distinguished Name des Zertifikatantragsstellers, den ein Client präsentiert. Vorhanden, wenn ein Client mithilfe eines benutzerdefinierten Domain-Namens, für den gegenseitige TLS aktiviert ist, auf eine API zugreift. Nur in Zugriffsprotokollen vorhanden, wenn die gegenseitige TLS-Authentifizierung fehlschlägt. |
| \$1context.identity.clientCert.issuerDN | Der Distinguished Name des Ausstellers des Zertifikats, das ein Client präsentiert. Vorhanden, wenn ein Client mithilfe eines benutzerdefinierten Domänennamens, für den gegenseitige TLS aktiviert ist, auf eine API zugreift. Nur in Zugriffsprotokollen vorhanden, wenn die gegenseitige TLS-Authentifizierung fehlschlägt. |
| \$1context.identity.clientCert.serialNumber | Die Seriennummer des Zertifikats. Vorhanden, wenn ein Client mithilfe eines benutzerdefinierten Domänennamens, für den gegenseitige TLS aktiviert ist, auf eine API zugreift. Nur in Zugriffsprotokollen vorhanden, wenn die gegenseitige TLS-Authentifizierung fehlschlägt. |
| \$1context.identity.clientCert.validity.notBefore | Das Datum, vor dem das Zertifikat ungültig ist. Vorhanden, wenn ein Client mithilfe eines benutzerdefinierten Domänennamens, für den gegenseitige TLS aktiviert ist, auf eine API zugreift. Nur in Zugriffsprotokollen vorhanden, wenn die gegenseitige TLS-Authentifizierung fehlschlägt. |
| \$1context.identity.clientCert.validity.notAfter | Das Datum, nach dem das Zertifikat ungültig ist. Vorhanden, wenn ein Client mithilfe eines benutzerdefinierten Domänennamens, für den gegenseitige TLS aktiviert ist, auf eine API zugreift. Nur in Zugriffsprotokollen vorhanden, wenn die gegenseitige TLS-Authentifizierung fehlschlägt. |
| \$1context.identity.vpcId | Die VPC-ID der VPC, deren Anforderung an den API-Gateway-Endpunkt gesendet wird. |
| \$1context.identity.vpceId | Die VPC-Endpunkt-ID des VPC-Endpunkts, dessen Anforderung an den API-Gateway-Endpunkt gesendet wird. Diese ist nur vorhanden, wenn Ihre API privat ist. |
| \$1context.identity.user | Die Hauptkennung des Benutzers, der für den Ressourcenzugriff autorisiert wird. Wird für Ressourcen unterstützt, die die IAM-Autorisierung verwenden. |
| \$1context.identity.userAgent | Die [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent)-Kopfzeile des API-Aufrufers. |
| \$1context.identity.userArn | Der ARN (Amazon Resource Name) des tatsächlichen Benutzers nach der Authentifizierung. Weitere Informationen finden Sie unter [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html). |
| \$1context.integration.error | Die von einer Integration zurückgegebene Fehlermeldung. |
| \$1context.integration.integrationStatus | Bei der Lambda-Proxyintegration wurde der Statuscode vom Lambda-Funktionscode zurückgegeben AWS Lambda, nicht vom Backend-Funktionscode. |
| \$1context.integration.latency | Die Integrationslatenz in Millisekunden. Äquivalent mit \$1context.integrationLatency. |
| \$1context.integration.requestId | Die AWS Anforderungs-ID des Endpunkts. Äquivalent mit \$1context.awsEndpointRequestId. |
| \$1context.integration.responseTransferMode | Der Antwortübertragungsmodus Ihrer Integration. Dies kann entweder BUFFERED oder STREAMEDsein. |
| \$1context.integration.status | Der von einer Integration zurückgegebene Statuscode. Bei Lambda-Proxy-Integrationen ist dies der Statuscode, der von Ihrem Lambda-Funktionscode zurückgegeben wird. |
| \$1context.integration.timeToAllHeaders | Die Zeit zwischen dem Zeitpunkt, zu dem API Gateway die Integrationsverbindung herstellt, und dem Empfang aller Integrationsantwort-Header vom Client. |
| \$1context.integration.timeToFirstContent | Die Zeit zwischen dem Zeitpunkt, zu dem API Gateway die Integrationsverbindung herstellt, und dem Empfang der ersten Inhaltsbytes. |
| \$1context.integrationLatency | Die Integrationslatenz in Millisekunden. |
| \$1context.integrationStatus | Für die Lambda-Proxyintegration stellt dieser Parameter den Statuscode dar, der vom Lambda-Funktionscode zurückgegeben wurde AWS Lambda, nicht aus dem Back-End-Lambda-Funktionscode. |
| \$1context.isCanaryRequest | Gibt `true` zurück, wenn die Anforderung an den Canary gerichtet war oder `false`, wenn die Anforderung nicht an den Canary ging. Dies ist nur vorhanden, wenn Sie einen Canary aktiviert haben. |
| \$1context.path | Der Anforderungspfad. Bei einer Nicht-Proxy-Anforderungs-URL von https://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child lautet der \$1context.path-Wert beispielsweise /\$1stage\$1/root/child. |
| \$1context.protocol | Das Anforderungsprotokoll ist z. B, HTTP/1.1. API Gateway APIs kann HTTP/2-Anfragen akzeptieren, aber API Gateway sendet Anfragen über HTTP/1.1 an Backend-Integrationen. Infolgedessen wird das Anforderungsprotokoll als HTTP/1.1 protokolliert, auch wenn ein Client eine Anfrage sendet, die HTTP/2 verwendet. |
| \$1context.requestId | Eine ID für die Anforderung. Clients können diese Anforderungs-ID überschreiben. Verwenden von `$context.extendedRequestId` für eine eindeutige Anforderungs-ID, die API Gateway generiert. |
| \$1context.requestOverride.header.header\$1name | Der Anforderungs-Header-Override. Wenn dieser Parameter definiert ist, enthält er die Header, die statt der **HTTP Header**, die im Bereich **Integrationsanforderung** definiert sind, verwendet werden sollen. Weitere Informationen finden Sie unter [Überschreiben Sie die Anfrage- und Antwortparameter und Statuscodes Ihrer API für REST APIs in API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestOverride.path.path\$1name | Der Anforderungspfad-Override. Wenn dieser Parameter definiert ist, enthält er den Anforderungspfad, der statt der **URL-Pfadparameter**, die im Bereich **Integrationsanforderung** definiert sind, verwendet werden soll. Weitere Informationen finden Sie unter [Überschreiben Sie die Anfrage- und Antwortparameter und Statuscodes Ihrer API für REST APIs in API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestOverride.querystring.querystring\$1name | Der Abfragestring-Override. Wenn dieser Parameter definiert ist, enthält er die Abfragestrings, die statt der **URL-Abfragestring-Parameter**, die im Bereich **Integrationsanforderung** definiert sind, verwendet werden sollen. Weitere Informationen finden Sie unter [Überschreiben Sie die Anfrage- und Antwortparameter und Statuscodes Ihrer API für REST APIs in API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.responseLatency | Die Antwortlatenz in Millisekunden. |
| \$1context.responseLength | Die Länge der Antwortnutzlast in Byte. |
| \$1context.responseOverride.header.header\$1name | Der Antwort-Header-Override. Wenn dieser Parameter definiert ist, enthält er den Header, der anstelle des Antwort-Headers, der als Standard-Mapping im Bereich Integrationsantwort definiert ist, ausgegeben werden soll. Weitere Informationen finden Sie unter [Überschreiben Sie die Anfrage- und Antwortparameter und Statuscodes Ihrer API für REST APIs in API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.responseOverride.status | Der Antwortstatuscode-Override. Wenn dieser Parameter definiert ist, enthält er den Statuscode, der anstelle des Methoden-Antwortstatus, der als Standard-Mapping im Bereich Integrationsantwort definiert ist, ausgegeben werden soll. Weitere Informationen finden Sie unter [Überschreiben Sie die Anfrage- und Antwortparameter und Statuscodes Ihrer API für REST APIs in API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestTime | Die Anforderungszeit im [CLF](https://httpd.apache.org/docs/current/logs.html#common)-Format (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). |
| \$1context.requestTimeEpoch | Die Anforderungszeit im [Epoch](https://en.wikipedia.org/wiki/Unix_time)-Format in Millisekunden. |
| \$1context.resourceId | Der Bezeichner, den API Gateway Ihrer Ressource zuweist. |
| \$1context.resourcePath | Der Pfad zu Ihrer Ressource. Beim Nicht-Proxy-Anforderungs-URI von `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child` lautet der `$context.resourcePath`-Wert beispielsweise `/root/child`. Weitere Informationen finden Sie unter [Tutorial: REST-API mit HTTP-API ohne Proxy-Integration erstellen](api-gateway-create-api-step-by-step.md). |
| \$1context.stage | Die Bereitstellungsstufe der API-Anforderung (z. B. `Beta` oder `Prod`). |
| \$1context.status | Der Status der Methodenantwort. |
| \$1context.tlsVersion | Die TLS-Version, die während des TLS-Handshakes zwischen dem Client und dem API Gateway ausgehandelt wird. |
| \$1context.waf.error | Die Fehlermeldung wurde von AWS WAF zurückgegeben. |
| \$1context.waf.latency | Die AWS WAF Latenz in ms. |
| \$1context.waf.status | Der Statuscode wurde von zurückgegeben AWS WAF. |
| \$1context.xrayTraceId | Die Trace-ID für die X-Ray-Trace. Weitere Informationen finden Sie unter [AWS X-Ray Mit API Gateway REST einrichten APIs](apigateway-enabling-xray.md). |
| \$1context.wafResponseCode | Die von [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) empfangene Antwort: `WAF_ALLOW` oder `WAF_BLOCK`. Wird nicht festgelegt, wenn die Stufe mit keiner Web-ACL verknüpft ist. Weitere Informationen finden Sie unter [Verwenden Sie AWS WAF , um Ihren REST APIs in API Gateway zu schützen](apigateway-control-access-aws-waf.md). |
| \$1context.webaclArn | Vollständiger ARN der Web-Zugriffskontrollliste (Web-ACL), anhand deren entschieden wird, ob die Anforderung zugelassen oder blockiert wird. Wird nicht festgelegt, wenn die Stufe mit keiner Web-ACL verknüpft ist. Weitere Informationen finden Sie unter [Verwenden Sie AWS WAF , um Ihren REST APIs in API Gateway zu schützen](apigateway-control-access-aws-waf.md). |
# Benutzeranforderungen für Ablaufverfolgung an REST-APIs mithilfe von X-Ray in API Gateway
Sie können [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html) verwenden, um Benutzeranforderungen auf ihrem Weg durch Ihre Amazon-API-Gateway-REST-APIs zu den zugrunde liegenden Diensten zu verfolgen und zu analysieren. API Gateway unterstützt die X-Ray-Ablaufverfolgung für alle API Gateway-REST-API-Endpunkttypen: Regional, Edge-optimiert und privat. Sie können X-Ray mit Amazon API Gateway in allen AWS-Regionen verwenden, in denen X-Ray verfügbar ist.
Da X-Ray Ihnen eine End-to-End-Ansicht einer gesamten Anforderung bietet, können Sie Latenzen in Ihren APIs und deren Backend-Services analysieren. Sie können eine X-Ray-Servicezuordnung verwenden, um die Latenz einer gesamten Anforderung und der der nachgeschalteten Services anzuzeigen, die in X-Ray integriert sind. Sie können auch Samplingregeln konfigurieren, um X-Ray mitzuteilen, welche Anforderungen mit welchen Abtastraten gemäß den von Ihnen angegebenen Kriterien aufgezeichnet werden sollen.
Wenn Sie eine API Gateway-API von einem Service aufrufen, der bereits verfolgt wird, wird API Gateway die Ablaufverfolgung auch dann ausführen, wenn die X-Ray-Ablaufverfolgung in der API nicht aktiviert ist.
Sie können X-Ray für eine API-Stufe aktivieren, indem Sie die API Gateway-Konsole oder die API Gateway-API oder -CLI verwenden.
**Topics**
+ [AWS X-Ray Mit API Gateway REST einrichten APIs](apigateway-enabling-xray.md)
+ [Verwenden Sie AWS X-Ray Service Maps und Trace Views mit API Gateway](apigateway-using-xray-maps.md)
+ [AWS X-Ray Sampling-Regeln für API Gateway konfigurieren APIs](apigateway-configuring-xray-sampling-rules.md)
+ [AWS X-Ray Ablaufverfolgungen für Amazon API Gateway APIs](apigateway-understanding-xray-traces.md)
# AWS X-Ray Mit API Gateway REST einrichten APIs
In diesem Abschnitt finden Sie detaillierte Informationen zur Einrichtung [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html)mit API Gateway REST APIs.
**Topics**
+ [X-Ray-Ablaufverfolgungsmodi für API Gateway](#apigateway-tracing-modes)
+ [Berechtigungen für die X-Ray-Ablaufverfolgung](#set-up-xray-tracing-permissions)
+ [Aktivieren der X-Ray-Ablaufverfolgung in der API Gateway-Konsole](#apigateway-xray-console-setup)
+ [Aktivieren der AWS X-Ray Ablaufverfolgung mit der API Gateway Gateway-CLI](#apigateway-xray-cli-setup)
## X-Ray-Ablaufverfolgungsmodi für API Gateway
Der Pfad einer Anforderung über Ihre Anwendung wird mit einer Nachverfolgungs-ID verfolgt. Eine Ablaufverfolgung erfasst alle von einer einzelnen Anforderung generierten Segmente; in der Regel handelt es sich dabei um eine HTTP `GET`- oder `POST`-Anforderung.
Es gibt zwei Ablaufverfolgungsmodi für eine API Gateway-API:
+ **Passiv**: Dies ist die Standardeinstellung, wenn Sie die X-Ray-Ablaufverfolgung in einer API-Stufe nicht aktiviert haben. Bei diesem Ansatz wird die API Gateway-API nur nachverfolgt, wenn X-Ray für einen Upstream-Service aktiviert wurde.
+ **Aktiv**: Wenn eine API Gateway-API-Stufe diese Einstellung aufweist, stellt API Gateway die API-Aufrufanfragen automatisch auf Basis des von X-Ray bereitgestellten Sampling-Algorithmus zusammen.
Wenn die aktive Ablaufverfolgung in einer Stufe aktiviert ist, wird API Gateway in Ihrem Konto eine servicebezogene Rolle erstellen, sofern die Rolle nicht bereits vorhanden ist. Die Rolle wird benannt `AWSServiceRoleForAPIGateway`und die `APIGatewayServiceRolePolicy` verwaltete Richtlinie wird an sie angehängt. Weitere Informationen zu serviceverknüpften Rollen finden Sie unter [Verwenden serviceverknüpfter Rollen](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html).
**Anmerkung**
X-Ray wendet einen Sampling-Algorithmus an, um eine effizient Ablaufverfolgung zu gewährleisten und gleichzeitig ein repräsentatives Beispiel für die Anforderungen bereitzustellen, die von Ihrer API bedient werden. Der Standardeinstellung für den Sampling-Algorithmus lautet 1 Anforderung pro Sekunde, wobei 5 Prozent der Anforderungen, die über dieses Limit hinausgehen, auch erfasst werden.
Sie können den Ablaufverfolgungsmodus für Ihre API ändern, indem Sie die API Gateway Gateway-Verwaltungskonsole, die API Gateway Gateway-CLI oder ein AWS SDK verwenden.
## Berechtigungen für die X-Ray-Ablaufverfolgung
Wenn Sie die X-Ray-Ablaufverfolgung in einer Stufe aktivieren, wird API Gateway in Ihrem Konto eine servicebezogene Rolle erstellen, sofern die Rolle nicht bereits vorhanden ist. Die Rolle wird benannt `AWSServiceRoleForAPIGateway`und die `APIGatewayServiceRolePolicy` verwaltete Richtlinie wird an sie angehängt. Weitere Informationen zu serviceverknüpften Rollen finden Sie unter [Verwenden serviceverknüpfter Rollen](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html).
## Aktivieren der X-Ray-Ablaufverfolgung in der API Gateway-Konsole
Sie können die Amazon API Gateway-Konsole verwenden, um die aktive Ablaufverfolgung in einer API-Stufe zu aktivieren.
Diese Schritte gehen davon aus, dass Sie die API bereits in einer Stufe bereitgestellt haben.
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 Ihre API und dann im Hauptnavigationsbereich die Option **Stages** (Stufe).
1. Wählen Sie im Bereich **Stages** (Stufen) eine Stufe aus.
1. Wählen Sie im Abschnitt **Logs and tracing** (Protokolle und Nachverfolgung) die Option **Edit** (Bearbeiten) aus.
1. Sie können die aktive X-Ray-Nachverfolgung aktivieren, indem Sie **X-Ray tracing** (X-Ray-Nachverfolgung) auswählen, um die X-Ray-Nachverfolgung zu aktivieren.
1. Wählen Sie **Änderungen speichern ** aus.
Nachdem Sie X-Ray für Ihre API-Stufe aktiviert haben, können Sie die Ablaufverfolgungen und Service-Übersichten mithilfe der X-Ray-Verwaltungskonsole anzeigen.
## Aktivieren der AWS X-Ray Ablaufverfolgung mit der API Gateway Gateway-CLI
Der folgende [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html)-Befehl erstellt eine Stufe mit aktiver X-Ray-Ablaufverfolgung:
```
aws apigateway create-stage \
--rest-api-id rest-api-id \
--stage-name stage-name \
--deployment-id deployment-id \
--region region \
--tracing-enabled=true
```
Die Ausgabe sieht wie folgt aus:
```
{
"tracingEnabled": true,
"stageName": stage-name,
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": deployment-id,
"lastUpdatedDate": 1533849811,
"createdDate": 1533849811,
"methodSettings": {}
}
```
Der folgende [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html)-Befehl erstellt eine Stufe ohne aktive X-Ray-Ablaufverfolgung:
```
aws apigateway create-stage \
--rest-api-id rest-api-id \
--stage-name stage-name \
--deployment-id deployment-id \
--region region \
--tracing-enabled=false
```
Die Ausgabe sieht wie folgt aus:
```
{
"tracingEnabled": false,
"stageName": stage-name,
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": deployment-id,
"lastUpdatedDate": 1533849811,
"createdDate": 1533849811,
"methodSettings": {}
}
```
Der folgende [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html)-Befehl aktiviert die aktive X-Ray-Ablaufverfolgung für eine bereitgestellte API:
```
aws apigateway update-stage \
--rest-api-id rest-api-id \
--stage-name stage-name \
--patch-operations op=replace,path=/tracingEnabled,value=true
```
Der folgende [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html)-Befehl deaktiviert die aktive X-Ray-Ablaufverfolgung für eine bereitgestellte API:
```
aws apigateway update-stage \
--rest-api-id rest-api-id \
--stage-name stage-name \
--region region \
--patch-operations op=replace,path=/tracingEnabled,value=false
```
Die Ausgabe sieht wie folgt aus:
```
{
"tracingEnabled": false,
"stageName": stage-name,
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": deployment-id,
"lastUpdatedDate": 1533850033,
"createdDate": 1533849811,
"methodSettings": {}
}
```
Sobald Sie X-Ray für Ihre API-Stufe aktiviert haben, verwenden Sie die X-Ray-CLI zum Abrufen von Ablaufverfolgungsinformationen. Weitere Informationen finden Sie unter [Verwenden der X-Ray-API mit der AWS CLI](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-tutorial).
# Verwenden Sie AWS X-Ray Service Maps und Trace Views mit API Gateway
In diesem Abschnitt finden Sie detaillierte Informationen zur Verwendung von [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html)-Service-Übersichten und Nachverfolgungsansichten mit API Gateway.
**Topics**
+ [Beispiel für eine X-Ray-Service-Übersicht](#apigateway-using-xray-maps-active)
+ [Beispiel für eine X-Ray-Ablaufverfolgungsansicht](#apigateway-using-xray-trace-view-active)
## Beispiel für eine X-Ray-Service-Übersicht
AWS X-Ray Service Maps zeigen Informationen zu Ihrer API und all ihren nachgelagerten Diensten. Wenn X-Ray für eine API-Stufe in API Gateway aktiviert ist, wird in der Service-Übersicht ein Knoten angezeigt, der Informationen zur Gesamtzeit enthält, die im API Gateway-Service verbracht wurde. Sie erhalten detaillierte Informationen über den Antwortstatus und ein Histogramm der API-Reaktionszeit für den ausgewählten Zeitraum. Für APIs die Integration mit AWS Diensten wie AWS Lambda Amazon DynamoDB werden Sie mehr Knoten sehen, die Leistungskennzahlen für diese Dienste bereitstellen. Es wird eine Service-Übersicht für jede API-Stufe geben.
Das folgende Beispiel zeigt eine Service-Übersicht für die `test` Stufe einer aufgerufenen API `xray`. Diese API hat zwei Lambda-Integrationen. Die Knoten stellen den API-Gateway-Service und die beiden Lambda-Funktionen dar.
Eine detaillierte Erläuterung der Service-Übersichtsstruktur finden Sie unter [Verwenden der X-Ray-Trace-Map](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-servicemap).
![\[Service-Übersicht-Beispiel für eine API Gateway-API-Stufe\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/apigateway-xray-servicemap-2.png)
Sie können die Service-Übersicht vergrößern und eine Ansicht der Nachverfolgung für die API-Stufe anzeigen. Die Nachverfolgung zeigt detaillierte Informationen zu Ihrer API an, die als Segmente und Untersegmente dargestellt werden. Beispiel: Die Ablaufverfolgung für die Service-Übersicht umfasst die oben gezeigten Segmente für den Lambda-Service und die Lambda-Funktion. [Weitere Informationen finden Sie unter AWS Lambda und. AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-lambda.html)
Wenn Sie einen Knoten oder ein Edge in einer X-Ray-Service-Übersicht auswählen, zeigt die X-Ray-Konsole ein Histogramm der Latenzverteilung. Sie können ein Latenzhistogramm verwenden, um zu sehen, wie lange es dauert, bis ein Service seine Anforderungen erfüllt. Es folgt ein Histogramm der API Gateway-Stufe, die in der vorherigen Service-Übersicht `xray/test` benannt wurde. Eine detaillierte Erklärung der Latenz-Verteilungshistogramme finden Sie unter [Verwenden von Latenzhistogrammen](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-histograms).
![\[X-Ray-Histogramm einer API Gateway-API-Stufe\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/apigateway-xray-histogram-1.png)
## Beispiel für eine X-Ray-Ablaufverfolgungsansicht
Das folgende Diagramm zeigt eine Ablaufverfolgungsansicht, die für die oben beschriebene Beispiel-API mit einer Lambda-Backend-Funktion generiert wurde. Eine erfolgreiche API-Methodenanforderung wird mit einem Antwortcode von 200 angezeigt.
Eine detaillierte Erläuterung der Ablaufverfolgungsansichten finden Sie unter [Anzeigen von Ablaufverfolgungsdetails](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-traces).
![\[API Gateway mit aktivierter Ablaufverfolgung\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/apigateway-xray-traceview-1.png)
# AWS X-Ray Sampling-Regeln für API Gateway konfigurieren APIs
Sie können die AWS X-Ray Konsole oder das SDK verwenden, um Sampling-Regeln für Ihre Amazon API Gateway zu konfigurieren. Eine Samplingregel gibt an, welche Anforderungen X-Ray für Ihre API aufzeichnen soll. Durch das Anpassen von Samplingregeln können Sie die Menge der von Ihnen aufgezeichneten Daten steuern und das Stichprobenverhalten im laufenden Betrieb ändern, ohne Ihren Code ändern oder neu implementieren zu müssen.
Bevor Sie Ihre X-Ray-Samplingregeln festlegen, lesen Sie die folgenden Themen im X-Ray-Entwicklerhandbuch:
+ [Konfigurieren von Samplingregeln](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-sampling)
+ [Verwenden von Samplingregeln mit der X-Ray-API](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-sampling)
**Topics**
+ [Optionswerte für Röntgenprobenabtastregeln für API Gateway APIs](#apigateway-xray-sampling-rule-options)
+ [Beispiele für X-Ray-Samplingregeln](#apigateway-xray-sampling-rules-examples)
## Optionswerte für Röntgenprobenabtastregeln für API Gateway APIs
Die folgenden X-Ray-Samplingoptionen sind für API Gateway relevant. String-Werte können Platzhalter verwenden, um ein einzelnes Zeichen (?) Oder null oder mehr Zeichen (\$1) zu finden. Für weitere Informationen, einschließlich einer detaillierten Erklärung wie die Einstellungen **Reservoir** und **Rate** verwendet werden, finden Sie unter [Konfigurieren von Samplingregeln](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-sampling).
+ **Regelname** (Zeichenfolge) – Ein eindeutiger Name für die Regel.
+ **Priorität** (Ganzzahl zwischen 1 und 9999) – Die Priorität der Samplingregel. Services werten Regeln in aufsteigender Reihenfolge der Priorität aus und treffen eine Sampleentscheidung mit der ersten übereinstimmenden Regel.
+ **Reservoir** (nicht negative Ganzzahl) – Eine feste Anzahl übereinstimmender Anfragen an das Gerät pro Sekunde vor Anwendung des festen Satzes. Das Reservoir wird nicht direkt von Services verwendet, sondern gilt für alle Services, die die Regel gemeinsam verwenden.
+ **Rate** (Anzahl zwischen 0 und 100) – Der Prozentsatz der übereinstimmenden Anfragen an das Gerät, nachdem das Reservoir erschöpft ist.
+ **Servicename** (Zeichenfolge) – Der API-Stufenname in Form von ***\$1api-name\$1*/*\$1stage-name\$1***. Wenn Sie die [PetStore](api-gateway-create-api-from-example.md)Beispiel-API beispielsweise in einer Phase mit dem Namen bereitstellen würden, wäre der Wert für den **Dienstnamen `test`**, den Sie in Ihrer Stichprobenregel angeben müssen**pets/test**, wie folgt:
+ **Servicetyp** (Zeichenfolge) – Für eine API Gateway-API kann entweder **AWS::ApiGateway::Stage** oder **AWS::ApiGateway::\$1** angegeben werden.
+ **Host** (Zeichenfolge) – Der Hostname aus dem HTTP-Host-Header. Setzen Sie dies auf **\$1**, um mit allen Hostnamen übereinzustimmen. Oder geben Sie einen vollständigen oder teilweisen Hostnamen an, z. B. **api.example.com** oder **\$1.example.com**.
+ **Ressourcen-ARN** (Zeichenfolge) – Der ARN der API-Stufe, z. B. **arn:aws:apigateway:*region*::/restapis/*api-id*/stages/*stage-name***.
Der Stufenname kann von der Konsole oder der API Gateway-CLI oder -API abgerufen werden. Weitere Informationen zu ARN-Formaten finden Sie unter [Allgemeine Amazon Web Services-Referenz](https://docs.aws.amazon.com/general/latest/gr/).
+ **HTTP-Methode** (Zeichenfolge) – Die Methode, die gesampelt werden soll, z. B. **GET**.
+ **URL path** (URL-Pfad) (Zeichenfolge) – Der URL-Pfad der Anforderung.
+ (optional) **Attribute** (Schlüssel und Wert) – Header aus der ursprünglichen HTTP-Anforderung, z. B. **Connection**, **Content-Length** oder **Content-Type**. Jeder Attributwert kann bis zu 32 Zeichen lang sein.
## Beispiele für X-Ray-Samplingregeln
**Beispiel \$11 für Samplingregeln**
Diese Regel sampelt alle `GET` Anforderungen für die `testxray` API- `test` Stufe.
+ **Rule name (Regelname — ****test-sampling**
+ **Priorität — ****17**
+ **Reservoirgröße — ****10**
+ **Bestimmtes Zeitintervall — ****10**
+ **Servicename — ****testxray/test**
+ **Servicetyp – ****AWS::ApiGateway::Stage**
+ **HTTP-Methode — ****GET**
+ **Ressourcen-ARN – ****\$1**
+ **Host — ****\$1**
**Beispiel \$12 für Samplingregeln**
Diese Regel sampelt alle Anforderungen für die `testxray` API in der `prod`-Stufe.
+ **Rule name (Regelname — ****prod-sampling**
+ **Priorität — ****478**
+ **Reservoirgröße — ****1**
+ **Bestimmtes Zeitintervall — ****60**
+ **Servicename — ****testxray/prod**
+ **Servicetyp – ****AWS::ApiGateway::Stage**
+ **HTTP-Methode — ****\$1**
+ **Ressourcen-ARN – ****\$1**
+ **Host — ****\$1**
+ **Attribute** — **\$1\$1**
# AWS X-Ray Ablaufverfolgungen für Amazon API Gateway APIs
In diesem Abschnitt werden AWS X-Ray Trace-Segmente, Untersegmente und andere Trace-Felder für Amazon API Gateway APIs behandelt.
Bevor Sie diesen Abschnitt lesen, lesen Sie sich die folgenden Themen im X-Ray-Entwicklerhandbuch durch:
+ [Verwenden Sie ein AWS-Managementkonsole](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html)
+ [X-Ray-Segmentdokumente](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-segmentdocuments)
+ [Konzepte](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html#xray-concepts)
**Topics**
+ [Beispiele für Ablaufverfolgungsobjekte für eine API Gateway-API](#apigateway-understanding-xray-traces-example-segments)
+ [Verstehen der Ablaufverfolgung](#apigateway-understanding-xray-traces-segments)
## Beispiele für Ablaufverfolgungsobjekte für eine API Gateway-API
In diesem Abschnitt werden einige der Objekte erläutert, die in einer Ablaufverfolgung für eine API Gateway-API angezeigt werden.
**Anmerkungen**
Anmerkungen können in Segmenten und Untersegmenten vorkommen. Sie werden als Filterausdrücke in Stichprobenregeln zum Filtern von Nachverfolgungs verwendet. Weitere Informationen finden Sie unter [Konfigurieren von Samplingregeln](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-sampling).
Im Folgenden sehen Sie ein Beispiel für ein `annotations`-Objekt, in dem eine API-Stufe durch die API-ID und den API-Stufennamen identifiziert wird:
```
"annotations": {
"aws:api_id": "a1b2c3d4e5",
"aws:api_stage": "dev"
}
```
Weitere Informationen zu Anmerkungen finden Sie unter [X-Ray-Segmentdokumente](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-segmentdocuments) und wählen Sie dann **X-Ray-Segmentdokumente**, **Anmerkungen** aus.
**AWS Ressourcendaten**
Das `aws`-Objekt wird nur in Segmenten angezeigt. Im Folgenden finden Sie ein Beispiel für ein `aws` Objekt, das der Standard-Sampling-Regel entspricht. Eine ausführliche Erläuterung der Samplingregeln finden Sie unter [Konfigurieren von Samplingregeln](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-sampling).
```
"aws": {
"xray": {
"sampling_rule_name": "Default"
},
"api_gateway": {
"account_id": "123412341234",
"rest_api_id": "a1b2c3d4e5",
"stage": "dev",
"request_id": "a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6"
}
}
```
Weitere Informationen zum `aws`-Objekt finden Sie unter [X-Ray-Segmentdokumente](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-segmentdocuments) und wählen Sie dann **X-Ray-Segmentdokumente**, **AWS Ressourcendaten** aus.
## Verstehen der Ablaufverfolgung
Im Folgenden finden Sie ein Ablaufverfolgungssegment für eine API Gateway-Stufe. Eine detaillierte Beschreibung der Felder, aus denen das Ablaufverfolgungssegment besteht, finden Sie unter [X-Ray-Segmentdokumente](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-segmentdocuments).
```
{
"Document": {
"id": "a1b2c3d4a1b2c3d4",
"name": "testxray/dev",
"start_time": 1533928226.229,
"end_time": 1533928226.614,
"metadata": {
"default": {
"extended_request_id": "abcde12345abcde=",
"request_id": "a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6"
}
},
"http": {
"request": {
"url": "https://example.com/dev?username=demo&message=hellofromdemo/",
"method": "GET",
"client_ip": "192.0.2.0",
"x_forwarded_for": true
},
"response": {
"status": 200,
"content_length": 0
}
},
"aws": {
"xray": {
"sampling_rule_name": "Default"
},
"api_gateway": {
"account_id": "123412341234",
"rest_api_id": "a1b2c3d4e5",
"stage": "dev",
"request_id": "a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6"
}
},
"annotations": {
"aws:api_id": "a1b2c3d4e5",
"aws:api_stage": "dev"
},
"trace_id": "1-a1b2c3d4-a1b2c3d4a1b2c3d4a1b2c3d4",
"origin": "AWS::ApiGateway::Stage",
"resource_arn": "arn:aws:apigateway:us-east-1::/restapis/a1b2c3d4e5/stages/dev",
"subsegments": [
{
"id": "abcdefgh12345678",
"name": "Lambda",
"start_time": 1533928226.233,
"end_time": 1533928226.6130002,
"http": {
"request": {
"url": "https://example.com/2015-03-31/functions/arn:aws:lambda:us-east-1:123412341234:function:xray123/invocations",
"method": "GET"
},
"response": {
"status": 200,
"content_length": 62
}
},
"aws": {
"function_name": "xray123",
"region": "us-east-1",
"operation": "Invoke",
"resource_names": [
"xray123"
]
},
"namespace": "aws"
}
]
},
"Id": "a1b2c3d4a1b2c3d4"
}
```