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à. # Utilizzo delle variabili di fase per una REST API in Gateway API Le variabili di fase sono coppie chiave-valore che è possibile definire come attributi di configurazione associati a una fase di implementazione di una REST API. Fungono da variabili di ambiente e possono essere utilizzate nei modelli di mappatura e configurazione dell'API. Con le fasi di implementazione in Gateway API, puoi gestire più fasi di rilascio per ogni API e utilizzare le variabili di fase per configurare una fase di implementazione dell'API per l'interazione con endpoint di backend diversi. Le variabili di fase non sono destinate ad essere utilizzate per i dati sensibili, come le credenziali. Per trasferire dati sensibili alle integrazioni, usa un AWS Lambda autorizzatore. È possibile passare dati sensibili alle integrazioni nell'output del provider di autorizzazioni Lambda. Per ulteriori informazioni, consulta [Output da un sistema di autorizzazione Lambda di Gateway API](api-gateway-lambda-authorizer-output.md). ## Casi d'uso per le variabili di fase Di seguito sono riportati alcuni casi d'uso per le variabili di fase. **Specificare un endpoint di backend diverso** L'API può passare una richiesta `GET` come proxy HTTP all'host web di backend. Puoi utilizzare una variabile di fase per far sì che, quando i chiamanti dell'API invocano l'endpoint di produzione, Gateway API chiami `example.com`. Quindi, quando i chiamanti dell'API invocano la fase beta, Gateway API chiama un host web diverso, ad esempio `beta.example.com`. Analogamente, le variabili di fase si possono utilizzare per specificare un nome di funzione AWS Lambda per ogni fase dell'API. Non puoi utilizzare una variabile di fase per impostare un endpoint di integrazione diverso, ad esempio per far sì che la richiesta `GET` punti a un'integrazione di proxy HTTP in una fase e a un'integrazione di proxy Lambda in un'altra fase. Quando si specifica un nome di funzione Lambda come valore della variabile di fase, è necessario configurare manualmente le autorizzazioni per la funzione Lambda. Quando specifichi una funzione Lambda nella console API Gateway, verrà visualizzato un AWS CLI comando per configurare le autorizzazioni appropriate. A tale scopo è inoltre possibile utilizzare il seguente AWS CLI comando. ``` aws lambda add-permission --function-name "arn:aws:lambda:us-east-2:123456789012:function:my-function" --source-arn "arn:aws:execute-api:us-east-2:123456789012:api_id/*/HTTP_METHOD/resource" --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction ``` **Passare le informazioni utilizzando modelli di mappatura** Puoi accedere alle variabili di fase nei modelli di mappatura o passare i parametri di configurazione a AWS Lambda o al backend HTTP. Ad esempio, potrebbe essere necessario riutilizzare la stessa funzione Lambda per più fasi nell'API, ma la funzione deve leggere i dati da una tabella di Amazon DynamoDB diversa a seconda della fase. Nei modelli di mappatura che generano la richiesta per la funzione Lambda è possibile usare le variabili di fase per passare il nome della tabella a Lambda. Per utilizzare una variabile di fase, è necessario prima configurare una variabile di fase e quindi assegnarle un valore. Ad esempio, per personalizzare l'endpoint di integrazione HTTP, crea prima la variabile di fase `url` e poi, nella richiesta di integrazione dell'API, inserisci il valore della variabile di fase **http://\$1\$1stageVariables.url\$1**. Questo valore indica ad API Gateway di sostituire la variabile di fase `${}` al runtime, a seconda della fase di esecuzione dell'API. Per ulteriori informazioni, consulta [Imposta le variabili di fase per REST APIs in API Gateway](how-to-set-stage-variables-aws-console.md). # Imposta le variabili di fase per REST APIs in API Gateway Questa sezione mostra come configurare le variabili di fase per due fasi di implementazione di un'API di esempio utilizzando la console Gateway Amazon API. Per capire come utilizzare le variabili di fase in Gateway API, ti consigliamo di seguire tutte le procedure illustrate in questa sezione. ## Prerequisiti Prima di iniziare, verifica che siano soddisfatti i seguenti requisiti preliminari: + Devi disporre di un'API in API Gateway. Segui le istruzioni in [Sviluppa REST APIs in API Gateway](rest-api-develop.md). + Devi avere distribuito l'API almeno una volta. Segui le istruzioni in [Implementazione di REST API in Gateway API](how-to-deploy-api.md). + Devi aver creato la prima fase per un'API distribuita. Segui le istruzioni in [Creazione di una nuova fase](set-up-stages.md#how-to-create-stage-console). ## Invocazione di un endpoint HTTP mediante un'API con una variabile di fase Questa procedura descrive come creare una variabile di fase per un endpoint HTTP e due fasi per l'API. Inoltre, vengono create le variabili di fase `url`, `stageName` e `function`, che vengono utilizzate nelle procedure seguenti di questa sezione. **Per invocare un endpoint HTTP mediante un'API con una variabile di fase** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Crea un'API, quindi crea un metodo `GET` nella risorsa radice dell'API. Imposta il tipo di integrazione su **HTTP** e imposta l'**URL dell'endpoint** su **http://\$1\$1stageVariables.url\$1**. 1. Implementa l'API in una nuova fase denominata **beta**. 1. Nel riquadro di navigazione scegli **Fasi**, quindi seleziona la fase **beta**. 1. Nella scheda **Variabili di fase** scegli **Modifica**. 1. Scegli **Aggiungi variabile di fase**. 1. In **Nome**, inserisci **url**. In **Valore**, inserisci **httpbin.org/get**. 1. Scegli **Aggiungi variabile di fase**, quindi effettua le seguenti operazioni: In **Nome**, inserisci **stageName**. In **Valore**, inserisci **beta**. 1. Scegli **Aggiungi variabile di fase**, quindi effettua le seguenti operazioni: In **Nome**, inserisci **function**. In **Valore**, inserisci **HelloWorld**. 1. Scegli **Save** (Salva). 1. Ora crea una seconda fase. Dal riquadro di navigazione **Fasi** scegli **Crea fase**. In **Stage name (Nome fase)** immettere **prod**. Seleziona un'implementazione recente da **Implementazione** e scegli **Crea**. 1. Come per la fase **beta**, imposta le stesse tre variabili di fase (**url**, **version** e **function**) su valori diversi (rispettivamente **petstore-demo-endpoint.execute-api.com/petstore/pets**, **prod** e **HelloEveryone**). 1. Nel riquadro di navigazione **Stages (Fasi)** scegli **beta**. In **Dettagli fase** scegli l'icona Copia per copiare l'URL di richiamo dell'API, quindi immetti l'URL di richiamo dell'API in un browser Web. Viene avviata la richiesta `GET` della fase **beta** nella risorsa radice dell'API. **Nota** Il collegamento **Invoke URL** (URL chiamata) punta alla risorsa radice dell'API nella rispettiva fase **beta**. L'immissione dell'URL in un browser Web chiama il metodo `GET` della fase **beta** nella risorsa radice. Se i metodi vengono definiti nelle risorse figlio e non nella risorsa radice stessa, scegliendo l'URL in un browser Web viene restituita la risposta di errore `{"message":"Missing Authentication Token"}`. In questo caso, devi aggiungere al collegamento **Invoke URL (URL chiamata)** il nome di una risorsa figlio specifica. 1. La risposta che si ottiene dalla richiesta `GET` della fase **beta** è mostrata più avanti. Puoi verificare il risultato anche utilizzando un browser per accedere a **http://httpbin.org/get**. Questo valore è stato assegnato alla variabile `url` nella fase **beta**. Le due risposte sono identiche. 1. Nel riquadro di navigazione **Stages (Fasi)** scegli la fase **prod**. In **Dettagli fase** scegli l'icona Copia per copiare l'URL di richiamo dell'API, quindi immetti l'URL di richiamo dell'API in un browser Web. Viene avviata la richiesta `GET` della fase **prod** nella risorsa radice dell'API. 1. La risposta che si ottiene dalla richiesta `GET` della fase **prod** è mostrata più avanti. È possibile verificare il risultato utilizzando un browser per accedere a **http://.execute-api. petstore-demo-endpoint com/petstore/pets**. Questo valore è stato assegnato alla variabile `url` nella fase **prod**. Le due risposte sono identiche. ## Passare i metadati specifici della fase in un backend HTTP Questa procedura descrive come utilizzare un valore di variabile di fase in un'espressione di parametri di query per passare i metadati specifici delle fasi in un back-end HTTP. Utilizzeremo la variabile di fase `stageName` dichiarata nella procedura precedente. **Per passare metadati specifici della fase in un backend HTTP** 1. Nel riquadro di navigazione **Resource (Risorsa)** scegli il metodo **GET**. Per aggiungere un parametro della stringa di query all'URL del metodo, seleziona la scheda **Richiesta del metodo**, quindi nella sezione **Impostazioni della richiesta del metodo**, scegli **Modifica**. 1. Scegli i **parametri della stringa di query URL** ed effettua le seguenti operazioni: 1. Scegliere **Add query string (Aggiungi stringa di query)**. 1. In **Nome**, inserisci **stageName**. 1. Mantieni **Obbligatorio** e **Caching** disattivati. 1. Scegli **Save** (Salva). 1. Scegli la scheda **Richiesta di integrazione**, quindi seleziona **Modifica** nella sezione **Impostazioni della richiesta di integrazione**. 1. Per **URL dell'endpoint** aggiungi **?stageName=\$1\$1stageVariables.stageName\$1** al valore URL definito in precedenza, in modo che sia l'intero **URL dell'endpoint** sia **http://\$1\$1stageVariables.url\$1?stageName=\$1\$1stageVariables.stageName\$1**. 1. Scegli **Implementa API** e seleziona la fase **beta**. 1. Nel riquadro di navigazione principale scegli **Fasi**. Nel riquadro di navigazione **Stages (Fasi)** scegli **beta**. In **Dettagli fase** scegli l'icona Copia per copiare l'URL di richiamo dell'API, quindi immetti l'URL di richiamo dell'API in un browser Web. **Nota** Qui usiamo la fase beta perché l'endpoint HTTP (come specificato dalla variabile `url`, "http://httpbin.org/get") accetta le espressioni dei parametri di query e le restituisce come oggetto `args` nella rispettiva risposta. 1. Si ottiene la risposta seguente. `beta`, assegnato alla variabile di fase `stageName`, viene passata nel back-end come argomento `stageName`. ![\[Risposta dal metodo GET dell'API con un endpoint HTTP utilizzando la variabile di fase url.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/stageVariables-new-console-invoke-beta-stage-with-url-and-stageName-response.png) ## Invocare una funzione Lambda attraverso un'API con una variabile di fase Questa procedura descrive come utilizzare una variabile di fase per chiamare una funzione Lambda come back-end dell'API. Utilizzerai la variabile di fase `function` dichiarata in [Invocazione di un endpoint HTTP mediante un'API con una variabile di fase](#how-to-set-stage-variables-aws-console-http-endpoint). Quando imposti una funzione Lambda come valore di una variabile di fase, usa il nome locale della funzione, se possibile includendo l'alias o la specifica della versione, come in **HelloWorld**, **HelloWorld:1** o **HelloWorld:alpha**. Non usare l'ARN della funzione (ad esempi, **arn:aws:lambda:us-east-1:123456789012:function:HelloWorld**). La console API Gateway assume il valore della variabile di fase per una funzione Lambda come nome di funzione non qualificato ed espande la variabile di fase specificata in un ARN. **Per invocare la funzione Lambda mediante un'API con una variabile di fase** 1. Crea una funzione Lambda denominata **HelloWorld** utilizzando il runtime Node.js predefinito. Il codice deve contenere quanto segue: ``` export const handler = function(event, context, callback) { if (event.stageName) callback(null, 'Hello, World! I\'m calling from the ' + event.stageName + ' stage.'); else callback(null, 'Hello, World! I\'m not sure where I\'m calling from...'); }; ``` Per ulteriori informazioni su come creare una funzione Lambda, consulta [Nozioni di base sulla console REST API](getting-started-rest-new-console.md#getting-started-rest-new-console-create-function). 1. Nel riquadro **Risorse** seleziona **Crea risorsa**, quindi procedi come segue: 1. Per **Percorso risorsa**, seleziona **/**. 1. Per **Resource Name (Nome risorsa)** immetti **lambdav1**. 1. Scegli **Crea risorsa**. 1. Scegli la risorsa **/lambdav1** e poi scegli **Crea metodo**. Successivamente, esegui queste operazioni: 1. Per **Tipo di metodo** seleziona **GET**. 1. Per **Tipo di integrazione** seleziona **Funzione Lambda**. 1. Mantieni l'opzione **Integrazione proxy Lambda** disattivata. 1. Per **Lambda function (Funzione Lambda)**, immetti `${stageVariables.function}`. ![\[Creazione di un metodo GET integrato con una funzione Lambda come specificato dalla variabile di fase function\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/stageVariables-new-console-create-lambda-get-method.png) **Suggerimento** Quando richiesto da **Aggiungi comando di autorizzazione**, copia il comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html). Esegui il comando per ciascuna funzione Lambda che sarà assegnata alla variabile di fase `function`. Ad esempio, se il valore di `$stageVariables.function` è `HelloWorld`, esegui il comando AWS CLI seguente: ``` aws lambda add-permission --function-name arn:aws:lambda:us-east-1:account-id:function:HelloWorld --source-arn arn:aws:execute-api:us-east-1:account-id:api-id/*/GET/lambdav1 --principal apigateway.amazonaws.com --statement-id statement-id-guid --action lambda:InvokeFunction ``` In caso contrario, riceverai una risposta `500 Internal Server Error` quando verrà invocato il metodo. Sostituisci `${stageVariables.function}` con il nome della funzione Lambda assegnato alla variabile di fase. ![\[AWS CLI comando per aggiungere il permesso alla funzione Lambda da invocare dal metodo creato.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/stageVariables-new-console-add-permission-to-lambda-function.png) 1. Scegli **Crea metodo**. 1. Implementa l'API in entrambe le fasi **prod** e **beta**. 1. Nel riquadro di navigazione principale scegli **Fasi**. Nel riquadro di navigazione **Stages (Fasi)** scegli **beta**. In **Dettagli fase** scegli l'icona Copia per copiare l'URL di richiamo dell'API, quindi immetti l'URL di richiamo dell'API in un browser Web. Aggiungi **/lambdav1** all'URL prima di premere invio. Si ottiene la risposta seguente. ``` "Hello, World! I'm not sure where I'm calling from..." ``` ## Passaggio dei metadati specifici delle fasi a una funzione Lambda mediante una variabile di fase Questa procedura descrive come utilizzare una variabile di fase per passare i metadata di configurazione specifici delle fasi in una funzione Lambda. Crei un metodo `POST` e un modello di mappatura di input per generare il payload utilizzando la variabile di fase `stageName` dichiarata precedentemente. **Per passare i metadati specifici delle fasi a una funzione Lambda mediante una variabile di fase** 1. Scegli la risorsa **/lambdav1** e poi scegli **Crea metodo**. Successivamente, esegui queste operazioni: 1. Per **Tipo di metodo** seleziona **POST**. 1. Per **Tipo di integrazione** seleziona **Funzione Lambda**. 1. Mantieni l'opzione **Integrazione proxy Lambda** disattivata. 1. Per **Lambda function (Funzione Lambda)**, immetti `${stageVariables.function}`. 1. Quando richiesto da **Aggiungi comando di autorizzazione**, copia il comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html). Esegui il comando per ciascuna funzione Lambda che sarà assegnata alla variabile di fase `function`. 1. Scegli **Crea metodo**. 1. Scegli la scheda **Richiesta di integrazione**, quindi seleziona **Modifica** nella sezione **Impostazioni della richiesta di integrazione**. 1. Scegli **Modelli di mappatura**, quindi seleziona **Aggiungi modello di mappatura**. 1. Per **Tipo di contenuto** inserisci **application/json**. 1. Per **Corpo del modello** inserisci il seguente modello: ``` #set($inputRoot = $input.path('$')) { "stageName" : "$stageVariables.stageName" } ``` **Nota** In un modello di mappatura il riferimento a una variabile di fase deve essere racchiuso tra apici (come in `"$stageVariables.stageName"` o `"${stageVariables.stageName}"`), mentre altrove non si devono utilizzare gli apici (come in `${stageVariables.function}`). 1. Scegli **Save** (Salva). 1. Implementa l'API in entrambe le fasi **beta** e **prod**. 1. Per utilizzare un client REST API per passare i metadati specifici della fase, procedi come segue: 1. Nel riquadro di navigazione **Stages (Fasi)** scegli **beta**. In **Dettagli fase** scegli l'icona Copia per copiare l'URL di richiamo dell'API, quindi immetti l'URL di richiamo dell'API nel campo di input di un client REST API. Aggiungi **/lambdav1** prima di inviare la richiesta. Si ottiene la risposta seguente. ``` "Hello, World! I'm calling from the beta stage." ``` 1. Nel riquadro di navigazione **Fasi** scegli **prod**. In **Dettagli fase** scegli l'icona Copia per copiare l'URL di richiamo dell'API, quindi immetti l'URL di richiamo dell'API nel campo di input di un client REST API. Aggiungi **/lambdav1** prima di inviare la richiesta. Si ottiene la risposta seguente. ``` "Hello, World! I'm calling from the prod stage." ``` 1. Per utilizzare la funzionalità **Test** per trasmettere i metadati specifici della fase, procedi come segue: 1. Nel riquadro di navigazione **Risorse** scegli la scheda **Test**. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda. 1. Per **function** immetti **HelloWorld**. 1. Per **stageName** immetti **beta**. 1. Scegli **Test (Esegui test)**. Non è necessario aggiungere un corpo alla richiesta `POST`. Si ottiene la risposta seguente. ``` "Hello, World! I'm calling from the beta stage." ``` 1. Puoi ripetere i passaggi precedenti per testare la fase **Prod**. Per **stageName** immetti **Prod**. Si ottiene la risposta seguente. ``` "Hello, World! I'm calling from the prod stage." ``` # Riferimento alle variabili di fase API Gateway per REST APIs in API Gateway È possibile usare le variabili di fase di API Gateway nei casi seguenti. ## Espressioni di mappatura dei parametri Una variabile di fase può essere utilizzata in un'espressione di mappatura dei parametri per un parametro di intestazione di risposta o di richiesta del metodo API, senza alcuna sostituzione parziale. Nell'esempio che segue si fa riferimento alla variabile di fase senza il simbolo `$` e il simbolo `{...}` di chiusura. + `stageVariables.` ## Modelli di mappatura Una variabile di fase può essere utilizzata ovunque in un modello di mappatura, come mostrato negli esempi seguenti. + `{ "name" : "$stageVariables."}` + `{ "name" : "${stageVariables.}"}` ## Integrazione HTTP URIs Una variabile di fase può essere utilizzata come parte di un URL di integrazione HTTP, come mostrato negli esempi seguenti: + Un URI completo senza protocoll – `http://${stageVariables.}` + Un dominio completo – `http://${stageVariables.}/resource/operation` + Un sottodominio – `http://${stageVariables.}.example.com/resource/operation` + Un percorso – `http://example.com/${stageVariables.}/bar` + Una stringa di query – `http://example.com/foo?q=${stageVariables.}` ## AWS integration URIs Una variabile di fase può essere utilizzata come parte dell'azione AWS URI o dei componenti del percorso, come illustrato nell'esempio seguente. + `arn:aws:apigateway:::${stageVariables.}` ## AWS integrazione URIs (funzioni Lambda) Una variabile di fase può essere utilizzata al posto del nome o della versione/dell'alias di una funzione Lambda, come mostrato negli esempi seguenti. + `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function:${stageVariables.}/invocations` + `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function::${stageVariables.}/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. ## Bacino d’utenza di Amazon Cognito Una variabile di fase può essere utilizzata al posto di un pool di utenti di Amazon Cognito per un sistema di autorizzazione `COGNITO_USER_POOLS`. + `arn:aws:cognito-idp:::userpool/${stageVariables.}` ## AWS credenziali di integrazione Una variabile stage può essere utilizzata come parte dell'ARN delle AWS credenziali utente/ruolo, come illustrato nell'esempio seguente. + `arn:aws:iam:::${stageVariables.}`