Creazione di un'implementazione per una REST API in Gateway API

In API Gateway una distribuzione di API REST è rappresentata da una risorsa Distribuzione. È simile a un eseguibile di un'API rappresentato da una risorsa RestApi.

Per consentire al client di chiamare l'API, è necessario creare una distribuzione e associarvi una fase. Una fase è rappresentata da una risorsa Fase. Rappresenta una snapshot dell'API, inclusi metodi, integrazioni, modelli, modelli di mappatura e autorizzazioni Lambda (in precedenza note come autorizzazioni ad hoc). Quando si aggiorna l'API, è possibile ridistribuirla associando una nuova fase alla distribuzione esistente. La procedura di creazione di una fase è illustrata in Configurazione di una fase per una REST API in Gateway API.

Crea distribuzione

Le procedure seguenti mostrano come creare l'implementazione di una REST API.

AWS Management Console

Per poter distribuire un'API REST per la prima volta, è necessario crearla. Per ulteriori informazioni, consultare Sviluppo di REST API in Gateway API.

La console API Gateway consente di distribuire un'API creando una distribuzione e associandola a una fase nuova o esistente.

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

2. Nel riquadro di navigazione APIs (API) scegliere l'API che si desidera distribuire.

3. Nel riquadro Resources (Risorse) scegliere Deploy API (Distribuisci API).

4. In Fase, procedi come segue:

   1. Per creare una nuova fase, seleziona Nuova fase, quindi immetti un nome in Nome fase. Facoltativamente, puoi immettere una descrizione dell'implementazione in Descrizione distribuzione.

   2. Per scegliere una fase esistente, seleziona il nome della fase nel menu a discesa. Se lo desideri, puoi specificare una descrizione della nuova implementazione in Descrizione distribuzione.

   3. Per creare un'implementazione non associata a una fase, seleziona Nessuna fase. Successivamente, puoi associare questa implementazione a una fase.

5. Seleziona Deploy (Implementa).

AWS CLI

Quando si crea una distribuzione, viene creata un'istanza della risorsa Distribuzione. Per creare un'implementazione è possibile utilizzare la console API Gateway, la AWS CLI, un SDK AWS o l'API REST di API Gateway.

Per usare la CLI per creare una distribuzione, usa il comando create-deployment:

 aws apigateway create-deployment --rest-api-id <rest-api-id> --region <region>

L'API non è chiamabile fino a quando non si associa questa distribuzione a una fase. Con una fase esistente è possibile eseguire questa operazione aggiornando la proprietà deploymentId della fase con l'ID di distribuzione appena creato (<deployment-id>).

 aws apigateway update-stage --region <region> \
    --rest-api-id <rest-api-id> \ 
    --stage-name <stage-name> \ 
    --patch-operations op='replace',path='/deploymentId',value='<deployment-id>'

Quando distribuisci un'API per la prima volta, puoi combinare la creazione della fase e quella della distribuzione in modo che avvengano contemporaneamente:

 aws apigateway create-deployment --region <region> \
    --rest-api-id <rest-api-id> \
    --stage-name <stage-name>

Questo è quello che accade nella console API Gateway quando si distribuisce un'API per la prima volta o quando si ridistribuisce l'API in una nuova fase.

Per implementare nuovamente un'API, esegui la stessa procedura. Puoi riutilizzare la stessa fase tutte le volte che si desideri.

Fasi successive per l'implementazione di un'API

Di seguito sono riportati i passaggi successivi per l'implementazione dell'API.

Modifica delle impostazioni di fase

Dopo che un'API è stata distribuita, puoi modificare le impostazioni delle fasi per abilitare o disabilitare la cache, la registrazione o il throttling delle richieste dell'API. Puoi inoltre scegliere un certificato client per consentire al back-end di autenticare API Gateway e impostare le variabili delle fasi per passare il contesto della distribuzione all'integrazione dell'API al runtime. Per ulteriori informazioni, consulta Modifica delle impostazioni di fase

Dopo avere modificato le impostazioni della fase, per renderle effettive sarà necessario eseguire di nuovo la ridistribuzione dell'API.

Nota

Se le impostazioni aggiornate, come l'abilitazione della registrazione, richiedono un nuovo ruolo IAM, puoi aggiungere il ruolo IAM richiesto senza ridistribuire l'API. Tuttavia potrebbero essere necessari alcuni minuti prima che il nuovo ruolo IAM diventi effettivo. Fino ad allora, le tracce delle chiamate API non vengono registrate, anche se hai abilitato l'opzione di registrazione.

Scelta di diverse combinazioni di fase-implementazione

Dal momento che una distribuzione rappresenta una snapshot dell'API e una fase definisce un percorso in una snapshot, puoi scegliere combinazioni diverse di distribuzione-fase per controllare il modo in cui gli utenti effettuano chiamate nelle diverse versioni dell'API. Ciò risulta utile se ad esempio desideri eseguire il rollback a uno stato precedente della distribuzione dell'API o unire una branca privata dell'API in quella pubblica.

La procedura seguente illustra come eseguire questa operazione tramite Stage Editor (Editor fasi) nella console API Gateway. Si presume che un'API sia stata distribuita più di una volta.

1. Se non sei già nel riquadro Fasi, nel pannello di navigazione principale, scegli Fasi.

2. Seleziona la fase da aggiornare.

3. Nella scheda Cronologia delle distribuzioni seleziona l'implementazione da utilizzare per la fase.

4. Scegli Cambia implementazione attiva.

5. Conferma di voler cambiare l'implementazione attiva e scegli Cambia implementazione attiva nella finestra di dialogo Rendi attiva l'implementazione.

Passare i dati specifici dell'implementazione all'API.

Per una distribuzione, puoi impostare o modificare le variabili delle fasi per passare i dati specifici della distribuzione all'integrazione dell'API in fase di runtime. Puoi eseguire questa operazione nella scheda Stage Variables (Variabili di fase) in Stage Editor (Editor fasi). Per ulteriori informazioni, consulta le istruzioni in Utilizzo delle variabili di fase per una REST API in Gateway API.