Configurare la CloudWatch registrazione per REST APIs Gateway API

Per risolvere i problemi relativi all'esecuzione della richiesta o all'accesso del client al tuoAPI, puoi abilitare Amazon CloudWatch Logs per registrare API le chiamate. Per ulteriori informazioni su CloudWatch, consulta. Monitora REST API l'esecuzione con i CloudWatch parametri di Amazon

CloudWatch formati di registro per API Gateway

Esistono due tipi di API registrazione CloudWatch: registrazione dell'esecuzione e registrazione degli accessi. Nella registrazione dell'esecuzione, API Gateway gestisce i registri. CloudWatch Il processo include la creazione di gruppi e flussi di log e la segnalazione ai flussi di log delle richieste e delle risposte dell'intermediario.

I dati registrati includono errori o tracce di esecuzione (come valori dei parametri di richiesta o risposta o payload), dati utilizzati dagli autorizzatori Lambda (precedentemente noti come autorizzatori personalizzati), se sono necessarie API le chiavi, se i piani di utilizzo sono abilitati e altre informazioni. APIGateway rimuove le intestazioni di autorizzazione, i valori delle API chiavi e parametri di richiesta sensibili simili dai dati registrati.

Quando si implementa unAPI, API Gateway crea un gruppo di log e dei flussi di log all'interno del gruppo di log. Al gruppo di log viene assegnato un nome nel formato API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}. All'interno di ciascun gruppo, i log sono suddivisi ulteriormente in flussi, che vengono ordinati in base al valore Last Event Time (Ora ultimo evento) quando vengono riportati i dati registrati.

Nella registrazione degli accessi, tu, in qualità di API sviluppatore, desideri registrare chi ha effettuato l'accesso al tuo API e in che modo il chiamante ha effettuato l'accesso al. API Puoi creare il tuo gruppo di log o scegliere un gruppo di log esistente che possa essere gestito da API Gateway. Per specificare i dettagli di accesso, si selezionano $contextle variabili, un formato di registro e una destinazione del gruppo di log.

Il formato del log di accesso deve includere almeno $context.requestId o $context.extendedRequestId. Come procedura consigliata, includi $context.requestId e $context.extendedRequestId nel formato di registro.

$context.requestId

Questo registra il valore nell'x-amzn-RequestIdintestazione. I client possono sovrascrivere il valore nell'x-amzn-RequestIdintestazione con un valore nel formato di un identificatore univoco universale (). UUID APIGateway restituisce questo ID di richiesta nell'intestazione della risposta. x-amzn-RequestId APIGateway sostituisce le richieste sovrascritte IDs che non sono in formato a UUID_REPLACED_INVALID_REQUEST_ID nei log UUID di accesso.

$context.extendedRequestId

L'extendedRequestID è un ID univoco generato da Gateway. API APIGateway restituisce questo ID di richiesta nell'intestazione della x-amz-apigw-id risposta. Un API chiamante non può fornire o sostituire questo ID di richiesta. Potrebbe essere necessario fornire questo valore a AWS Support per risolvere il problema. API Per ulteriori informazioni, consulta $contextVariabili per modelli di dati, autorizzatori, modelli di mappatura e registrazione degli accessi CloudWatch .

Nota

Sono $context supportate solo le variabili.

Scegliete un formato di registro adottato anche dal backend analitico, ad esempio Common Log Format (CLF), JSONXML, o. CSV Quindi puoi alimentarlo direttamente con i log di accesso per l'elaborazione e il rendering dei parametri. Per definire il formato dei log, impostate il gruppo di log ARN sulla destinationArn proprietà accessLogSettings/sullo stage. È possibile ottenere un gruppo di log ARN nella CloudWatch console. Per definire il formato del registro degli accessi, impostate un formato scelto nella proprietà accessLogSetting/format sullo stage.

Esempi di alcuni formati di registro degli accessi di uso comune sono mostrati nella console API Gateway e sono elencati di seguito.

• 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 (valori separati da virgola):

  $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

Autorizzazioni per la registrazione CloudWatch

Per abilitare CloudWatch i log, devi concedere a API Gateway l'autorizzazione a leggere e scrivere i log del tuo account. CloudWatch La policy AmazonAPIGatewayPushToCloudWatchLogs gestita (con un ARN ofarn:aws:iam::aws:policy/service-role/AmazonAPIGatewayPushToCloudWatchLogs) dispone di tutte le autorizzazioni richieste:

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

Nota

APIIl gateway chiama AWS Security Token Service per assumere il IAM ruolo, quindi assicurati che AWS STS sia abilitato per la regione. Per ulteriori informazioni, consulta Gestire AWS STS in una AWS regione.

Per concedere queste autorizzazioni al tuo account, crea un IAM ruolo apigateway.amazonaws.com come entità attendibile, allega la politica precedente al IAM ruolo e imposta il IAM ruolo nella proprietà ARN cloudWatchRoleArn del tuo account. È necessario impostare la proprietà cloudWatchRoleArn separatamente per ogni AWS regione in cui si desidera abilitare i registri. CloudWatch

Se ricevi un errore durante l'impostazione del IAM ruoloARN, controlla le impostazioni del tuo AWS Security Token Service account per assicurarti che AWS STS sia abilitato nella regione che stai utilizzando. Per ulteriori informazioni sull'abilitazione AWS STS, consulta Managing AWS STS in an AWS Region nella Guida IAM per l'utente.

Configurare la CloudWatch API registrazione utilizzando la console API Gateway

Per configurare la CloudWatch API registrazione, è necessario averla distribuita su una faseAPI. È inoltre necessario aver configurato un ruolo CloudWatch Logs appropriato ARN per il proprio account.

1. Accedi alla console API Gateway all'indirizzo https://console.aws.amazon.com/apigateway.

2. Nel pannello di navigazione principale, scegli Impostazioni, quindi in Registrazione seleziona Modifica.

3. Per il ruolo di CloudWatch registro ARN, inserisci un IAM ruolo con le ARN autorizzazioni appropriate. È necessario eseguire questa operazione una volta per ogni Account AWS creazione creata APIs utilizzando API Gateway.

4. Nel riquadro di navigazione principale, scegli APIs, quindi esegui una delle seguenti operazioni:

   1. Scegliete una fase esistenteAPI, quindi scegliete una fase.

   2. Createne uno API e poi distribuitelo su uno stage.

5. Nel riquadro di navigazione principale scegli Fasi.

6. Nella sezione Log e tracciamento scegli Modifica.

7. Per abilitare il logging dell'esecuzione:

   1. Seleziona un livello di registrazione dal menu a discesa CloudWatch Registri. I livelli di registrazione sono i seguenti:

      • Disattivata: la registrazione non è attivata per questa fase.

      • Solo errori: la registrazione è abilitata solo per gli errori.

      • Errori e registri delle informazioni: la registrazione è abilitata per tutti gli eventi.

   2. (Facoltativo) Seleziona Tracciamento dati per attivare la registrazione della traccia dei dati per la tua fase. Questa operazione può essere utile per la risoluzione dei problemiAPIs, ma può comportare la registrazione di dati sensibili.

      Nota

      Ti consigliamo di non utilizzare il tracciamento dei dati per la produzione. APIs

   3. (Facoltativo) Seleziona Metriche dettagliate per attivare le metriche dettagliate CloudWatch .

   Per ulteriori informazioni sulle CloudWatch metriche, consulta. Monitora REST API l'esecuzione con i CloudWatch parametri di Amazon

8. Per abilitare il logging degli accessi:

   1. Attiva Registrazione accesso personalizzato.

   2. Per Destinazione del log di Access ARN, inserisci il nome ARN di un gruppo di log. Il ARN formato èarn:aws:logs:{region}:{account-id}:log-group:log-group-name.

   3. In Formato dei log immetti un formato di log. Puoi scegliere CLF, JSONXML, o CSV. Per ulteriori informazioni sui formati di log di esempio, consulta CloudWatch formati di registro per API Gateway.

9. Scegli Save changes (Salva modifiche).

Nota

Puoi abilitare la registrazione dell'esecuzione e quella degli accessi in modo reciprocamente indipendente.

APIGateway è ora pronto per registrare le richieste al tuoAPI. Non è necessario ridistribuire il API quando si aggiornano le impostazioni dello stage, i log o le variabili dello stage.

Configura la registrazione utilizzando CloudWatch API AWS CloudFormation

Utilizza il seguente AWS CloudFormation modello di esempio per creare un gruppo di log Amazon CloudWatch Logs e configurare l'esecuzione e la registrazione degli accessi per una fase. Per abilitare CloudWatch i log, devi concedere a API Gateway l'autorizzazione a leggere e scrivere i log del tuo account. CloudWatch Per ulteriori informazioni, consulta Associare l'account al IAM ruolo nella Guida per l'AWS CloudFormation utente.

  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