Utilizzo di fasi per API HTTP

Una fase API è un riferimento logico a uno stato del ciclo di vita dell'API (ad esempio, dev, prod, beta o v2). Le fasi API sono identificate dal rispettivo ID API e dal nome della fase e sono incluse nell'URL utilizzato per richiamare l'API. Ogni fase è un riferimento con nome a una distribuzione dell'API e viene resa disponibile per le applicazioni client da chiamare.

È possibile creare una fase $default che viene servita dalla base dell'URL dell'API, ad esempio https://{api_id}.execute-api.{region}.amazonaws.com/. Utilizzare questo URL per richiamare una fase API.

Una distribuzione è uno snapshot della configurazione dell'API. Dopo essere stata distribuita a una fase, l'API è disponibile per i client da richiamare. È necessario distribuire un'API per attivare le modifiche apportate. Se si abilitano le distribuzioni automatiche, le modifiche apportate a un'API vengono rilasciate automaticamente.

Variabili di fase

Le variabili di fase sono coppie chiave-valore che è possibile definire per una fase di un'API HTTP. Fungono da variabili di ambiente e possono essere utilizzate nella configurazione dell'API.

Ad esempio, puoi definire una variabile di fase e quindi impostare il suo valore come un endpoint HTTP per un'integrazione proxy HTTP. Successivamente, puoi fare riferimento all'endpoint utilizzando il nome della variabile di fase associata. In questo modo, puoi utilizzare la stessa configurazione API con un endpoint diverso in ogni fase. Allo stesso modo, puoi utilizzare le variabili di fase per specificare un'integrazione delle funzioni AWS Lambda diversa per ogni fase dell'API.

Nota

Le variabili di fase non sono destinate ad essere utilizzate per i dati sensibili, come le credenziali. Per passare dati sensibili alle integrazioni, utilizzare un autorizzatore AWS Lambda. È possibile passare dati sensibili alle integrazioni nell'output del provider di autorizzazioni Lambda. Per ulteriori informazioni, consulta Formato della risposta dell'autorizzazione.

Esempi

Per utilizzare una variabile di fase per personalizzare l'endpoint di integrazione HTTP, è necessario innanzitutto impostare il nome e il valore della variabile di fase (ad esempio url) con un valore pari a example.com. Quindi, impostare un'integrazione proxy HTTP. Anziché inserire l'URL dell'endpoint, è possibile comunicare ad API Gateway di usare il valore della variabile di fase, ossi, http://${stageVariables.url}. Questo valore indica ad API Gateway di sostituire la variabile di fase ${} al runtime, a seconda della fase dell'API.

È possibile fare riferimento alle variabili di fase in modo simile per specificare un nome di funzione Lambda o un ARN del ruolo AWS.

Quando si specifica un nome di funzione Lambda come valore della variabile di fase, è necessario configurare manualmente le autorizzazioni per la funzione Lambda. Per eseguire questa operazione, puoi utilizzare AWS Command Line Interface (AWS CLI).

aws lambda add-permission --function-name arn:aws:lambda:XXXXXX:your-lambda-function-name --source-arn arn:aws:execute-api:us-east-1:YOUR_ACCOUNT_ID:api_id/*/HTTP_METHOD/resource --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction

Riferimento alle variabili di fase di API Gateway

URI di integrazione HTTP

Puoi utilizzare una variabile di fase come parte di un URI di integrazione HTTP, come mostrato negli esempi seguenti.

• Un URI completo senza protocoll – http://${stageVariables.<variable_name>}

• Un dominio completo – http://${stageVariables.<variable_name>}/resource/operation

• Un sottodominio – http://${stageVariables.<variable_name>}.example.com/resource/operation

• Un percorso – http://example.com/${stageVariables.<variable_name>}/bar

• Una stringa di query – http://example.com/foo?q=${stageVariables.<variable_name>}

Funzioni Lambda

Puoi utilizzare una variabile di fase al posto di un nome di integrazione di funzione o alias Lambda, come illustrato negli esempi seguenti.

• arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/arn:aws:lambda:<region>:<account_id>:function:${stageVariables.<function_variable_name>}/invocations

• arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/arn:aws:lambda:<region>:<account_id>:function:<function_name>:${stageVariables.<version_variable_name>}/invocations

Nota

Per utilizzare una variabile di fase per una funzione Lambda, la funzione deve essere nello stesso account dell'API. Le variabili di fase non supportano le funzioni Lambda tra più account.

AWS Credenziali di integrazione

Puoi utilizzare una variabile di fase come parte di un ARN delle credenziali utente o ruolo AWS, come illustrato nell'esempio seguente.

• arn:aws:iam::<account_id>:${stageVariables.<variable_name>}