View a markdown version of this page

Zugriffsprotokollierung für REST-APIs - Amazon API Gateway
Greifen Sie auf Protokollformate zuRichten Sie die Zugriffsprotokollierung mithilfe der API Gateway-Konsole einRichten Sie die Zugriffsprotokollierung ein mit CloudFormation

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.

Zugriffsprotokollierung für REST-APIs

Bei der Zugriffsprotokollierung protokollieren Sie, wer auf Ihre API zugegriffen hat und wie der Anrufer auf die API zugegriffen hat. Sie können Ihre eigene Protokollgruppe erstellen oder eine vorhandene Protokollgruppe auswählen. Wählen Sie $context-Variablen, ein Protokollformat und eine Protokollgruppe als Ziel aus, um die Zugriffsdetails anzugeben.

Greifen Sie auf Protokollformate zu

Das Zugriffsprotokoll-Format muss mindestens $context.requestId oder $context.extendedRequestId enthalten. Es hat sich bewährt, beide in Ihr 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 Anforderungs-IDs, die nicht im Format einer UUID mit UUID_REPLACED_INVALID_REQUEST_ID in Ihren Zugriffsprotokollen vorliegen.

$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 Probleme mit Ihrer API zu beheben. Weitere Informationen finden Sie unter Variablen für die Zugriffsprotokollierung in API Gateway.

Wählen Sie ein Protokollformat aus, das auch von Ihrem analytischen Backend genutzt wird, z. B. Common Log Format (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 Loggruppen-ARN für die accessLogSettings/destinationArn Eigenschaft auf der Bühne fest. Sie können einen Loggruppen-ARN in der CloudWatch Konsole abrufen. Um das Format des Zugriffsprotokolls zu definieren, legen Sie ein ausgewähltes Format für die accessLogSetting/format Eigenschaft auf der Bühne 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):

    $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:

    <request id="$context.requestId"> <extendedRequestId>$context.extendedRequestId</extendedRequestId> <ip>$context.identity.sourceIp</ip> <caller>$context.identity.caller</caller> <user>$context.identity.user</user> <requestTime>$context.requestTime</requestTime> <httpMethod>$context.httpMethod</httpMethod> <resourcePath>$context.resourcePath</resourcePath> <status>$context.status</status> <protocol>$context.protocol</protocol> <responseLength>$context.responseLength</responseLength> </request>

  • 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

Richten Sie die Zugriffsprotokollierung mithilfe der API Gateway-Konsole ein

Bevor Sie die Zugriffsprotokollierung einrichten, stellen Sie die API schrittweise bereit und konfigurieren Sie einen entsprechenden CloudWatch Logs-Rollen-ARN für Ihr Konto.

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

  2. Klicken Sie im Hauptnavigationsbereich auf APIs und führen Sie eine der folgenden Aktionen aus:

    1. Wählen Sie eine vorhandene API und anschließend eine Stufe aus.

    2. Erstellen Sie eine API und stellen Sie diese dann einer Stufe bereit.

  3. Klicken Sie im Hauptnavigationsbereich auf Stages (Stufen).

  4. Wählen Sie im Abschnitt Logs and tracing (Protokolle und Nachverfolgung) die Option Edit (Bearbeiten) aus.

  5. Aktivieren Sie die Option Custom access logging (Benutzerdefinierte Zugriffsprotokollierung).

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

  7. 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 Greifen Sie auf Protokollformate zu.

  8. Wählen Sie Änderungen speichern aus.

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 Zugriffsprotokollierung ein mit CloudFormation

Verwenden Sie die folgende CloudFormation Beispielvorlage, um eine Amazon CloudWatch Logs-Protokollgruppe zu erstellen und die Zugriffsprotokollierung für eine Phase zu konfigurieren. Um CloudWatch Logs zu aktivieren, müssen Sie API Gateway die Berechtigung zum Lesen und Schreiben von Protokollen CloudWatch für Ihr Konto gewähren. Weitere Informationen finden Sie unter Konto mit IAM-Rolle verknüpfen im AWS CloudFormation -Benutzerhandbuch.

  TestStage:
    Type: AWS::ApiGateway::Stage
    Properties:
      StageName: test
      RestApiId: !Ref MyAPI
      DeploymentId: !Ref Deployment
      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