Configurare la CloudWatch registrazione per REST APIs in API Gateway - Amazon API Gateway
CloudWatch formati di registro per API GatewayAutorizzazioni per la registrazione CloudWatch Configurare la registrazione delle CloudWatch API utilizzando la console API GatewayConfigurare la registrazione CloudWatch delle API utilizzando AWS CloudFormation

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Configurare la CloudWatch registrazione per REST APIs in API Gateway

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

CloudWatch formati di registro per API Gateway

Esistono due tipi di accesso tramite API CloudWatch: registrazione dell'esecuzione e registrazione degli accessi. Nella registrazione dell'esecuzione, API Gateway gestisce i CloudWatch log. 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 nei log includono errori o tracce di esecuzione (come valori di parametri di richiesta o di risposta oppure payload), dati usati da sistemi di autorizzazione Lambda (noti in precedenza come sistemi di autorizzazione ad hoc), indicazioni sull'eventuale necessità di chiavi API e sull'eventuale abilitazione dei piani di utilizzo e altre informazioni. Gateway API oscura le intestazioni di autorizzazione, i valori delle chiavi API e parametri di richiesta sensibili simili dai dati registrati nei log.

Per migliorare il tuo livello di sicurezza, ti consigliamo di utilizzare la registrazione di esecuzione a livello OR. ERROR INFO Potrebbe essere necessario eseguire questa operazione per rispettare vari quadri di conformità. Per ulteriori informazioni, consulta i controlli di Amazon API Gateway nella Guida AWS Security Hub per l'utente.

Quando si distribuisce un'API, API Gateway crea un gruppo di log e i relativi flussi. 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, in qualità di sviluppatore dell'API puoi registrare chi ha avuto accesso alla tua API e in che modo l'intermediario ha avuto accesso all'API. Puoi creare un gruppo di log personalizzato o sceglierne uno esistente che potrebbe essere gestito da API Gateway. Per specificare i dettagli di accesso, seleziona le variabili $context, un formato di log e un gruppo di log come destinazione.

Il formato del log di accesso deve includere almeno $context.requestId o $context.extendedRequestId. Come best practice, includere $context.requestId e $context.extendedRequestId nel formato di log.

$context.requestId

In questo modo il valore dell'intestazione x-amzn-RequestId viene registrato nel log. I client possono sostituire il valore nell'intestazione x-amzn-RequestId con un valore nel formato di un identificatore univoco universale (UUID). API Gateway restituisce questo ID richiesta nell'intestazione della risposta di x-amzn-RequestId. API Gateway sostituisce le richieste sovrascritte IDs che non sono in formato UUID nei log di accesso. UUID_REPLACED_INVALID_REQUEST_ID

$context.extendedRequestId

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

Nota

Sono supportate solo le variabili $context.

Seleziona un formato di log adottato anche dal back-end analitico, ad esempio Common Log Format (CLF), JSON, XML o CSV. Quindi puoi alimentarlo direttamente con i log di accesso per l'elaborazione e il rendering dei parametri. Per definire il formato di registro, impostate l'ARN del gruppo di log sulla proprietà accessLogSettings/destinationARN sullo stage. È possibile ottenere un ARN del gruppo di log 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 log delle operazioni di accesso utilizzati con maggiore frequenza sono mostrati nella console API Gateway ed elencati qui 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 ad API Gateway l'autorizzazione a leggere e scrivere i log del tuo CloudWatch account. Amazon APIGateway PushToCloudWatchLogs dispone di tutte le autorizzazioni necessarie.

Nota

Chiama AWS Security Token Service API Gateway per assumere il ruolo IAM, quindi assicurati che AWS STS sia abilitato per la regione. Per ulteriori informazioni, consulta Managing AWS STS in an AWS Region.

Per concedere queste autorizzazioni al tuo account, crea un ruolo IAM con apigateway.amazonaws.com come entità affidabile, collega la policy precedente al ruolo IAM e imposta l'ARN del ruolo IAM sulla proprietà Arn del cloudWatchRole tuo account. È necessario impostare la proprietà cloudWatchRoleArn separatamente per ogni AWS regione in cui si desidera abilitare i log. CloudWatch

Se ricevi un errore durante l'impostazione dell'ARN del ruolo IAM, controlla le impostazioni AWS Security Token Service dell'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 IAM User Guide.

Configurare la registrazione delle CloudWatch API utilizzando la console API Gateway

Per configurare la registrazione CloudWatch dell'API, è necessario aver distribuito l'API in una fase. È inoltre necessario aver configurato un ARN del ruolo CloudWatch Logs appropriato 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 l'ARN del ruolo di CloudWatch registro, inserisci l'ARN di un ruolo IAM con le 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. Seleziona un'API esistente e quindi scegli una fase.

    2. Crea un'API e implementala in una fase.

  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 dei log sono:

      • Inattivo: la registrazione dei log non è attivata per questa fase.

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

      • Errori e log informativi: la registrazione dei log è abilitata per tutti gli eventi.

    2. (Facoltativo) Seleziona Tracciamento dei dati per attivare la registrazione dei log della traccia dei dati per la fase. Questo può essere utile per la risoluzione dei problemi APIs, 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 l'esecuzione delle API REST con i CloudWatch parametri di Amazon

  8. Per abilitare il logging degli accessi:

    1. Attiva Registrazione accesso personalizzato.

    2. Immetti l'ARN di un gruppo di log in ARN di destinazione del log degli accessi. Il formato dell'ARN è arn:aws:logs:{region}:{account-id}:log-group:log-group-name.

    3. In Formato dei log immetti un formato di log. Puoi scegliere CLF, JSON, XML 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.

API Gateway ora è pronto a registrare i log delle richieste all'API. Non è necessario ridistribuire l'API quando si aggiornano le impostazioni delle fasi, i log o le variabili delle fasi.

Configurare la registrazione CloudWatch delle API utilizzando 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 ad API Gateway l'autorizzazione a leggere e scrivere i log del tuo CloudWatch account. Per ulteriori informazioni, consulta Associate account with IAM role nella Guida per l'utente di AWS CloudFormation .

  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