Configurazione di una fase per una REST API in Gateway API - Amazon API Gateway
Creazione di una nuova faseAggiornamento delle impostazioni della faseSostituzione delle impostazioni a livello di fase

Configurazione di una fase per una REST API in Gateway API

Una fase è un riferimento con nome a un'implementazione, corrispondente a uno snapshot dell'API. Utilizzare una Stage (Fase) per gestire e ottimizzare una specifica distribuzione. Ad esempio, puoi configurare le impostazioni di fase per abilitare la memorizzazione nella cache, personalizzare il throttling della richiesta, configurare la registrazione, definire le variabili di fase o collegare una release Canary a scopi di test. La sezione seguente illustra come creare e configurare la fase.

Creazione di una nuova fase

Dopo la distribuzione iniziale, puoi aggiungere altre fasi e associarle alle distribuzioni esistenti. Puoi usare la console API Gateway per creare una nuova fase oppure puoi scegliere una fase esistente durante la distribuzione di un'API. In generale, puoi aggiungere una nuova fase a una distribuzione API prima di ridistribuirla. Per creare una nuova fase mediante la console Gateway API procedi come riportato di seguito:

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

  2. Scegliere una REST API.

  3. Nel riquadro di navigazione principale scegli Fasi sotto un'API.

  4. Dal riquadro di navigazione Fasi scegli Crea fase.

  5. Per Nome fase immetti un nome, ad esempio prod.

    Nota

    I nomi di fasi possono contenere solo caratteri alfanumerici, trattini e caratteri di sottolineatura. La lunghezza massima è 128 caratteri.

  6. (Facoltativo). In Descrizione inserisci una breve descrizione.

  7. In Implementazione seleziona la data e l'ora dell'implementazione API esistente che intendi associare a questa fase.

  8. In Impostazioni aggiuntive puoi specificare le impostazioni aggiuntive per la fase.

  9. Scegli Crea fase.

Modifica delle impostazioni di fase

Dopo una distribuzione riuscita di un'API, la fase viene popolata di impostazioni predefinite. Per modificare le impostazioni di una fase, incluso caching e registrazione delle API, puoi utilizzare la console o l'API REST di API Gateway. La procedura seguente illustra come effettuare questa operazione tramite l'editor della fase della console Gateway API.

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

  2. Scegliere una REST API.

  3. Nel riquadro di navigazione principale scegli Fasi sotto un'API.

  4. Nel riquadro Stages (Fasi), selezionare il nome della fase.

  5. Nella sezione Dettagli fase scegli Modifica.

  6. (Facoltativo) In Descrizione fase modifica la descrizione.

  7. In Impostazioni aggiuntive modifica le seguenti impostazioni:

    Impostazioni cache

    Per abilitare il caching delle API per la fase, attiva Cache API con provisioning. Configura quindi Memorizzazione nella cache predefinita a livello di metodo, Capacità cache, Crittografa dati cache, Cache time-to-live (TTL), nonché i requisiti per l'invalidazione della cache per chiave.

    Il caching non è attivo finché non viene attivato il caching predefinito a livello di metodo o il caching a livello di metodo per un metodo specifico.

    Per ulteriori informazioni sulle impostazioni della cache, consulta Impostazioni della cache per REST API in Gateway API.

    Nota

    Se si abilita il caching per una fase API, è possibile che il costo di tale operazione venga addebitato sull'account AWS. Il caching non rientra nel piano gratuito di AWS.

    Impostazioni di limitazione (della larghezza di banda della rete)

    Per impostare le destinazioni di limitazione (della larghezza di banda della rete) a livello di fase per tutti i metodi associati a questa API, attiva Throttling.

    Per Rate(Tasso), inserire un tasso di destinazione. Questa è la velocità, espressa in richieste al secondo, con cui i token vengono aggiunti al bucket di token. La velocità a livello di fase non deve essere superiore alla velocità a livello di account come specificato in Quote di API Gateway per la configurazione e l'esecuzione di un'API REST.

    Per Burst (ottimizzazione), inserisci un tasso di destinazione. La frequenza di burst è la capacità del token bucket. Ciò consente di passare più richieste per un periodo di tempo rispetto al tasso di destinazione. Questo tasso di ottimizzazione a livello di fase non deve essere superiore al tasso di ottimizzazione a livello di account come specificato in Quote di API Gateway per la configurazione e l'esecuzione di un'API REST.

    Nota

    I tassi di limitazione (della larghezza di banda della rete) non sono limiti rigidi e vengono applicati sulla base del miglior tentativo. In alcuni casi, i client possono superare gli obiettivi impostati. Non fare affidamento sulla limitazione (della larghezza di banda della rete) per controllare i costi o bloccare l'accesso a un'API. Considera l'utilizzo di Budget AWS per monitorare i costi e di AWS WAF per gestire le richieste API.

    Impostazioni di firewall e certificati

    Per associare una lista di controllo degli accessi (ACL) Web AWS WAF alla fase, scegli un'ACL Web dall'elenco a discesa ACL Web. Se si desidera, scegliere Block API Request if WebACL cannot be evaluated (Blocca richiesta API se non è possibile valutare WebACL).

    Per selezionare un certificato client per la fase, scegli un certificato dal menu a discesa Certificati client.

  8. Scegli Continua.

  9. Esamina le modifiche e scegli Salva modifiche.

  10. Per abilitare File di log Amazon CloudWatch per tutti i metodi associati a questa fase dell'API di Gateway API, scegli Modifica nella sezione Log e tracciamento.

    Nota

    Per abilitare File di log CloudWatch è necessario specificare anche l'ARN di un ruolo IAM che consenta a Gateway API di scrivere informazioni in File di log CloudWatch per conto dell'utente. A questo scopo, selezionare Settings (Impostazioni) dal riquadro di navigazione principale API. Immetti quindi l'ARN di un ruolo IAM nel campo Ruolo del log di CloudWatch .

    Negli scenari di applicazione comuni, il ruolo IAM può collegare la policy gestita AmazonAPIGatewayPushToCloudWatchLogs.

    Il ruolo IAM deve anche contenere la seguente dichiarazione di relazione di attendibilità:

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "Service": "apigateway.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

    Per ulteriori informazioni su CloudWatch, consulta la Guida per l'utente di Amazon CloudWatch.

  11. Scegli un livello di registrazione dal menu a discesa CloudWatch Logs. 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.

  12. Seleziona Tracciamento dei dati per fare in modo che Gateway API invii a CloudWatch la registrazione dei log della traccia dei dati per la fase. Ciò può essere utile per risolvere i problemi relativi alle API, ma può comportare la registrazione di dati sensibili.

    Nota

    Si consiglia di non utilizzare Tracciamento dei dati per le API di produzione.

  13. Seleziona Parametri dettagliati per fare in modo che Gateway API invii a CloudWatch le metriche API di API calls, Latency, Integration latency, 400 errors e 500 errors. Per ulteriori informazioni su CloudWatch, consulta Basic monitoring and detailed monitoring nella Guida per l'utente di Amazon CloudWatch.

    Importante

    All'account verranno addebitati i costi per l'accesso ai parametri di CloudWatch a livello di metodo, ma non per l'accesso ai parametri a livello di API o di fasi.

  14. Per abilitare la registrazione degli accessi a una destinazione, attiva Registrazione accesso personalizzato.

  15. In ARN di destinazione del log degli accessi inserisci l'ARN di un gruppo di log o un flusso Firehose.

    Il formato dell'ARN per Firehose è arn:aws:firehose:{region}:{account-id}:deliverystream/amazon-apigateway-{your-stream-name}. Il nome del flusso di Firehose deve essere amazon-apigateway-{your-stream-name}.

  16. In Formato log immetti un formato di log. Per ulteriori informazioni sui formati di log di esempio, consulta Formati dei log di CloudWatch per API Gateway.

  17. Per abilitare il tracciamento AWS X-Ray per la fase API, seleziona Tracciamento X-Ray. Per ulteriori informazioni, consultare Traccia delle richieste degli utenti alle REST API utilizzando X-Ray in Gateway API.

  18. Scegli Salva modifiche. Implementa nuovamente l'API per rendere effettive le nuove impostazioni.

Sostituzione delle impostazioni a livello di fase

Dopo aver personalizzato le impostazioni a livello di fase, è possibile sostituirle per ogni metodo API. Alcune di queste opzioni potrebbero comportare costi aggiuntivi per il tuo Account AWS.

  1. Per configurare le sostituzioni dei metodi, espandi la fase nel pannello di navigazione secondario, quindi scegli un metodo.

    Espandi la fase nel pannello di navigazione secondario e scegli un metodo.

  2. Per Sostituzioni del metodo scegli Modifica.

  3. Per attivare le impostazioni CloudWatch a livello di metodo, seleziona un livello di registrazione per File di log CloudWatch.

  4. Per attivare la registrazione dei log della traccia dei dati per il metodo, seleziona Tracciamento dei dati.

    Nota

    Si consiglia di non utilizzare Tracciamento dei dati per le API di produzione.

  5. Per attivare i parametri dettagliati a livello di metodo, seleziona Parametri dettagliati. All'account verranno addebitati i costi per l'accesso ai parametri di CloudWatch a livello di metodo, ma non per l'accesso ai parametri a livello di API o di fasi.

  6. Per attivare la limitazione (della larghezza di banda della rete) a livello di metodo, seleziona Throttling. Immetti le opzioni appropriate a livello di metodo. Per ulteriori informazioni sulla limitazione, consulta Richieste di limitazione (della larghezza di banda della rete) alle REST API per un throughput migliore in Gateway API.

  7. Per configurare la cache a livello di metodo, seleziona Abilita cache metodo. La modifica dell'impostazione del caching predefinito a livello di metodo nei dettagli della fase non influisce su questa impostazione.

  8. Seleziona Salva.