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à.
# Tutorial: creazione di una REST API come un proxy Amazon S3
Per illustrare l'uso di un'API REST in API Gateway come proxy Amazon S3, in questa sezione viene descritto come creare e configurare un'API REST per esporre le operazioni Amazon S3 seguenti:
+ Esponi GET sulla risorsa radice dell'API per [elencare tutti i bucket Amazon S3 di un intermediario](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html).
+ Esponi GET su una risorsa cartella per [visualizzare un elenco di tutti gli oggetti di un bucket Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html).
+ Esponi GET su una Folder/Item risorsa per [visualizzare o scaricare un oggetto da un bucket Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html).
Puoi importare l'API di esempio come proxy Amazon S3, come illustrato in [Definizioni OpenAPI dell'API di esempio come un proxy Amazon S3](api-as-s3-proxy-export-swagger-with-extensions.md). Questo esempio include più metodi esposti. Per istruzioni su come importare l'API tramite la definizione OpenAPI, consulta [Sviluppa REST APIs utilizzando OpenAPI in API Gateway](api-gateway-import-api.md).
**Nota**
Per integrare l'API di API Gateway con Amazon S3, devi scegliere una regione in cui i servizi API Gateway e Amazon S3 siano entrambi disponibili. Per la disponibilità delle regioni, consulta [Endpoint e quote Amazon API Gateway](https://docs.aws.amazon.com/general/latest/gr/apigateway.html).
**Topics**
+ [Configurazione delle autorizzazioni IAM per consentire all'API di invocare operazioni Amazon S3](#api-as-s3-proxy-iam-permissions)
+ [Creazione di risorse API per rappresentare risorse Amazon S3](#api-as-s3-proxy-create-resources)
+ [Esposizione di un metodo API per elencare i bucket Amazon S3 dell'intermediario](#api-root-get-as-s3-get-service)
+ [Esposizione dei metodi API per accedere a un bucket Amazon S3](#api-folder-operations-as-s3-bucket-actions)
+ [Esposizione dei metodi API per accedere a un oggetto Amazon S3 in un bucket](#api-items-in-folder-as-s3-objects-in-bucket)
+ [Definizioni OpenAPI dell'API di esempio come un proxy Amazon S3](api-as-s3-proxy-export-swagger-with-extensions.md)
+ [Chiamata dell'API mediante un client API REST](api-as-s3-proxy-test-using-postman.md)
## Configurazione delle autorizzazioni IAM per consentire all'API di invocare operazioni Amazon S3
Per permettere all'API di richiamare le operazioni Amazon S3, devi aver collegato le policy IAM appropriate a un ruolo IAM. In questo passaggio si crea un nuovo ruolo IAM.
**Per creare il ruolo di esecuzione del proxy del AWS servizio**
1. Accedi Console di gestione AWS e apri la console IAM all'indirizzo [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. Scegliere **Roles (Ruoli)**.
1. Scegli **Crea ruolo**.
1. Scegli il **AWS servizio** in **Seleziona il tipo di entità affidabile**, quindi seleziona **API Gateway** e seleziona Consenti **a API Gateway di inviare i log ai CloudWatch log**.
1. Scegli **Successivo** e di nuovo **Successivo**.
1. In **Role name (Nome ruolo)** immettere **APIGatewayS3ProxyPolicy** e quindi selezionare **Create role (Crea ruolo)**.
1. Nell'elenco **Roles (Ruoli)** scegliere il ruolo appena creato. Potrebbe essere necessario scorrere o utilizzare la barra di ricerca per trovare il ruolo.
1. Per il ruolo selezionato, seleziona la scheda **Aggiungi autorizzazioni**.
1. Dall'elenco a discesa scegli **Collega policy**.
1. Nella barra di ricerca inserisci **AmazonS3FullAccess** e scegli **Aggiungi autorizzazioni**.
**Nota**
Per semplicità, questo tutorial utilizza una policy gestita. Come best practice, dovresti creare la tua policy IAM per concedere le autorizzazioni minime richieste.
1. Annota l'**ARN del ruolo** appena creato, lo utilizzerai in seguito.
## Creazione di risorse API per rappresentare risorse Amazon S3
Si utilizza la risorsa radice dell'API (`/`) come container dei bucket Amazon S3 di un chiamante autenticato. Inoltre, si dovranno creare le risorse `Folder` e `Item` per rappresentare rispettivamente un bucket Amazon S3 e un oggetto Amazon S3 specifico. Il nome della cartella e la chiave dell'oggetto verranno specificati dall'intermediario nell'ambito di un URL di richiesta nel formato dei parametri di percorso.
**Nota**
Quando accedi a oggetti la cui chiave include `/` o qualsiasi altro carattere speciale, il carattere deve avere la codifica URL. Ad esempio, `test/test.txt` dovrebbe avere la codifica `test%2Ftest.txt`.
**Per creare una risorsa API che espone le caratteristiche del servizio Amazon S3**
1. **Nello stesso modo in Regione AWS cui hai creato il tuo bucket Amazon S3, crea un'API denominata MyS3.** Questa risorsa della radice dell'API (**/**) rappresenta il servizio Amazon S3. In questa fase crei le due risorse aggiuntive **/\$1folder\$1** e **/\$1item\$1**.
1. Scegli **Crea risorsa**.
1. Mantieni l'opzione **Risorsa proxy** disattivata.
1. Per **Percorso risorsa** seleziona `/`.
1. Per **Resource Name (Nome risorsa)** immetti **\$1folder\$1**.
1. Mantieni **CORS (Cross Origin Resource Sharing)** deselezionato.
1. Scegli **Crea risorsa**.
1. Seleziona la risorsa **/\$1folder\$1**, quindi scegli **Crea risorsa**.
1. Ripeti le fasi precedenti per creare una risorsa figlio **/\$1folder\$1** denominata **\$1item\$1**.
L'API finale è simile a quanto riportato di seguito:
![\[Creazione di un'API in API Gateway come un proxy Amazon S3\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/aws_proxy_s3_create_api-resources_new_console.png)
## Esposizione di un metodo API per elencare i bucket Amazon S3 dell'intermediario
Per ottenere l'elenco dei bucket Amazon S3 dell'intermediario, è necessario richiamare l'operazione [GET Service](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html) in Amazon S3. Nella risorsa radice dell'API, (**/**), crea il metodo GET. Configura il metodo GET per l'integrazione con Amazon S3, come indicato di seguito.
**Per creare e inizializzare il metodo `GET /` dell'API**
1. Seleziona la risorsa **/**, quindi scegli **Crea metodo**.
1. Per Tipo di metodo seleziona **GET**.
1. Per **Tipo di integrazione** seleziona **Servizio AWS**.
1. Per **Regione AWS**, seleziona il Regione AWS luogo in cui hai creato il tuo bucket Amazon S3.
1. Per **Servizio AWS** seleziona **Amazon Simple Storage Service**.
1. Lascia vuoto **Sottodominio AWS **.
1. Per **Metodo HTTP** seleziona **GET**.
1. In **Tipo di operazione** scegli **Utilizza sostituzione percorso**.
Con la sostituzione del percorso, API Gateway invia la richiesta client ad Amazon S3 come [richiesta in stile percorso dell'API REST Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAPI.html), in cui la risorsa Amazon S3 viene espressa dal percorso della risorsa del modello `s3-host-name/bucket/key`. API Gateway imposta il valore `s3-host-name` e passa i valori `bucket` e `key` specificati dal client ad Amazon S3.
1. In **Sostituzione percorso** immetti **/**.
1. Per **Ruolo di esecuzione** immetti l'ARN del ruolo per **APIGatewayS3ProxyPolicy**.
1. Scegli **Impostazioni della richiesta del metodo**.
Si utilizzano le impostazioni della richiesta del metodo per controllare chi può chiamare questo metodo dell'API.
1. Per **Autorizzazioni** seleziona `AWS_IAM` nel menu a discesa.
![\[Dichiarazione dei tipi di risposta di metodo\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/aws_proxy_s3_setup_method_request_authorization_new_console.png)
1. Scegli **Crea metodo**.
Questa configurazione integra la richiesta `GET https://your-api-host/stage/` front-end con il back-end `GET https://your-s3-host/`.
Per consentire all'API di restituire correttamente risposte di esito positivo ed eccezioni al chiamante, si dichiarano le risposte 200, 400 e 500 in **Risposta metodo**. Si utilizza la mappatura predefinita per le risposte 200 in modo che le risposte di backend del codice di stato non dichiarate in questa sede vengano restituite al chiamante come risposte 200.
**Per dichiarare i tipi di risposta del metodo `GET /`**
1. Nella scheda **Risposta metodo** scegli **Modifica** in **Risposta 200**.
1. Scegli **Aggiungi intestazione** e procedi come descritto di seguito:
1. Per **Nome intestazione** immetti **Content-Type**.
1. Seleziona **Add header (Aggiungi intestazione)**.
Ripeti queste fasi per creare un'intestazione **Timestamp** e un'intestazione **Content-Length**.
1. Scegli **Save** (Salva).
1. Nella scheda **Risposta metodo** scegli **Crea risposta** in **Risposte del metodo**.
1. Per **Codice di stato HTTP** immetti **400**.
Non impostare alcuna intestazione per questa risposta.
1. Scegli **Save** (Salva).
1. Ripeti le seguenti fasi per creare la risposta 500.
Non impostare alcuna intestazione per questa risposta.
Poiché la risposta di integrazione con esito positivo da Amazon S3 restituisce l'elenco di bucket come payload XML e la risposta del metodo predefinita di Gateway API restituisce un payload JSON, è necessario mappare il valore del parametro di intestazione Content-Type di backend all'equivalente di frontend. In caso contrario, il client riceverà `application/json` come tipo di contenuto quando il corpo della risposta è effettivamente una stringa XML. La procedura seguente descrive come eseguire questa configurazione. È possibile inoltre visualizzare altri parametri di intestazione per il client, ad esempio Date e Content-Length.
**Per configurare le mappature delle intestazioni di risposta per il metodo GET /.**
1. Nella scheda **Risposta di integrazione** scegli **Modifica** in **Predefinito - Risposta**.
1. Per l'intestazione **Content-Length** immetti **integration.response.header.Content-Length** come valore di mappatura.
1. Per l'intestazione **Content-Type** immetti **integration.response.header.Content-Type** come valore di mappatura.
1. Per l'intestazione **Timestamp** immetti **integration.response.header.Date** come valore di mappatura.
1. Scegli **Save** (Salva). Il risultato sarà essere simile al seguente:
![\[Mappatura delle intestazioni delle risposte di integrazione alle intestazioni delle risposte di metodo\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/aws_proxy_s3_setup_integration_response_headers_new_console.png)
1. Nella scheda **Risposta di integrazione** scegli **Crea risposta** in **Risposte di integrazione**.
1. Per **HTTP status regex (Regex stato HTTP)**, immettere **4\$1d\$12\$1**. Tutti i codici di stato della risposta HTTP 4xx sono così mappati alla risposta del metodo.
1. Per **Codice di stato risposta metodo** seleziona **400**.
1. Scegli **Create** (Crea).
1. Ripeti le seguenti fasi per creare una risposta di integrazione per la risposta del metodo 500. Per **HTTP status regex (Regex stato HTTP)**, immettere **5\$1d\$12\$1**.
Come suggerisce la buona norma, è opportuno testare l'API configurata fino a questo momento.
**Test del metodo `GET /`**
1. Seleziona la scheda **Test**. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.
1. Scegli **Test (Esegui test)**. Il risultato sarà simile all'immagine seguente:
![\[Risultato del test del bucket GET nella radice dell'API\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/aws_proxy_s3_test_root_get_result_new_console.png)
## Esposizione dei metodi API per accedere a un bucket Amazon S3
Per utilizzare un bucket Amazon S3, esponi il metodo `GET` nella risorsa /\$1folder\$1 per elencare gli oggetti del bucket. Le istruzioni sono simili a quelle descritte in [Esposizione di un metodo API per elencare i bucket Amazon S3 dell'intermediario](#api-root-get-as-s3-get-service). Per altri metodi, puoi importare l'API di esempio come descritto in [Definizioni OpenAPI dell'API di esempio come un proxy Amazon S3](api-as-s3-proxy-export-swagger-with-extensions.md).
**Per esporre il metodo GET in una risorsa folder**
1. Seleziona la risorsa **/\$1folder\$1**, quindi scegli **Crea metodo**.
1. Per Tipo di metodo seleziona **GET**.
1. Per **Tipo di integrazione** seleziona **Servizio AWS**.
1. Per **Regione AWS**, seleziona il Regione AWS luogo in cui hai creato il tuo bucket Amazon S3.
1. Per **Servizio AWS** seleziona **Amazon Simple Storage Service**.
1. Lascia vuoto **Sottodominio AWS **.
1. Per **Metodo HTTP** seleziona **GET**.
1. In **Tipo di operazione** scegli **Utilizza sostituzione percorso**.
1. Per **Sostituzione percorso** immetti **\$1bucket\$1**.
1. Per **Ruolo di esecuzione** immetti l'ARN del ruolo per **APIGatewayS3ProxyPolicy**.
1. Scegli **Crea metodo**.
Imposta il parametro di percorso `{folder}` nell'URL dell'endpoint Amazon S3. Dovrai mappare il parametro di percorso `{folder}` della richiesta di metodo al parametro di percorso `{bucket}` della richiesta di integrazione.
**Per mappare `{folder}` a `{bucket}`**
1. Nella scheda **Richiesta di integrazione** scegli **Modifica** in **Impostazioni della richiesta di integrazione**.
1. Seleziona **Parametri di percorso URL**, quindi scegli **Aggiungi parametro di percorso**.
1. In **Nome**, inserisci **bucket**.
1. In **Mappato da**, inserire **method.request.path.folder**.
1. Scegli **Save** (Salva).
A questo punto esegui il test dell'API.
**Per testare il metodo `/{folder} GET`**
1. Seleziona la scheda **Test**. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.
1. In **Percorso** immetti il nome del tuo bucket per **folder**.
1. Scegli **Test (Esegui test)**.
Il risultato del test conterrà l'elenco degli oggetti presenti nel bucket.
![\[Test del metodo GET per la creazione di un bucket Amazon S3.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/aws_proxy_s3_test_api_folder_get_new_console.png)
## Esposizione dei metodi API per accedere a un oggetto Amazon S3 in un bucket
Amazon S3 supporta le operazioni GET, DELETE, HEAD, OPTIONS, POST e PUT per accedere agli oggetti e gestirli in un bucket specifico. In questo tutorial, esponi un metodo `GET` nella risorsa `{folder}/{item}` per ottenere un'immagine da un bucket. Per ulteriori applicazioni della risorsa `{folder}/{item}`, consulta l'API di esempio in [Definizioni OpenAPI dell'API di esempio come un proxy Amazon S3](api-as-s3-proxy-export-swagger-with-extensions.md).
**Per esporre il metodo GET in un elemento**
1. Seleziona la risorsa **/\$1item\$1**, quindi scegli **Crea metodo**.
1. Per Tipo di metodo seleziona **GET**.
1. Per **Tipo di integrazione** seleziona **Servizio AWS**.
1. Per **Regione AWS**, seleziona il Regione AWS luogo in cui hai creato il tuo bucket Amazon S3.
1. Per **Servizio AWS** seleziona **Amazon Simple Storage Service**.
1. Lascia vuoto **Sottodominio AWS **.
1. Per **Metodo HTTP** seleziona **GET**.
1. In **Tipo di operazione** scegli **Utilizza sostituzione percorso**.
1. Per **Sostituzione percorso** immetti **\$1bucket\$1/\$1object\$1**.
1. Per **Ruolo di esecuzione** immetti l'ARN del ruolo per **APIGatewayS3ProxyPolicy**.
1. Scegli **Crea metodo**.
Imposta i parametri di percorso `{folder}` e `{item}` nell'URL dell'endpoint Amazon S3. Dovrai mappare il parametro di percorso della richiesta di metodo al parametro di percorso della richiesta di integrazione.
In questa fase si effettuano le operazioni seguenti:
+ Mappa il parametro di percorso `{folder}` della richiesta di metodo al parametro di percorso `{bucket}` della richiesta di integrazione.
+ Mappa il parametro di percorso `{item}` della richiesta di metodo al parametro di percorso `{object}` della richiesta di integrazione.
**Per mappare `{folder}` a `{bucket}` e `{item}` a `{object}`**
1. Nella scheda **Richiesta di integrazione** scegli **Modifica** in **Impostazioni della richiesta di integrazione**.
1. Scegli **Parametri di percorso URL**.
1. Scegli **Aggiungi parametro di percorso**.
1. In **Nome**, inserisci **bucket**.
1. In **Mappato da**, inserire **method.request.path.folder**.
1. Scegli **Aggiungi parametro di percorso**.
1. In **Nome**, inserisci **object**.
1. In **Mappato da**, inserire **method.request.path.item**.
1. Scegli **Save** (Salva).
**Per testare il metodo `/{folder}/{object} GET`**
1. Seleziona la scheda **Test**. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.
1. In **Percorso** immetti il nome del tuo bucket per **folder**.
1. In **Percorso** immetti il nome di un elemento per **item**.
1. Scegli **Test (Esegui test)**.
Il corpo della risposta conterrà il contenuto dell'elemento.
![\[Test del metodo GET per la creazione di un bucket Amazon S3.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/aws_proxy_s3_test_api_item_get_new_console.png)
La richiesta restituisce correttamente il testo normale ("Hello world") come contenuto del file specificato (test.txt) nel bucket Amazon S3 fornito (amzn-s3-demo-bucket).
Per scaricare o caricare file binari ovvero, in API Gateway, tutti i contenuti JSON che hanno una codifica diversa da UTF-8, sono necessarie impostazioni API aggiuntive, come mostrato di seguito:
**Per scaricare o caricare file binari da S3**
1. Registra i tipi di file multimediali del file interessato nelle API. binaryMediaTypes Questa operazione può essere eseguita nella console:
1. Scegli **Impostazioni API** per l'API.
1. In **Tipi di media binari** scegli **Gestisci tipi di supporti**.
1. Scegli **Aggiungi tipo di supporto binario**, quindi immetti il tipo di supporto richiesto, ad esempio `image/png`.
1. Scegli **Salva modifiche** per salvare l'impostazione.
1. Aggiungi l'intestazione `Content-Type` (for upload) and/or `Accept` (for download) alla richiesta del metodo per richiedere al client di specificare il tipo di supporto binario richiesto e mapparlo alla richiesta di integrazione.
1. Imposta **Content Handling** (Gestione contenuto) su `Passthrough` nella richiesta di integrazione (per il caricamento) e in una risposta di integrazione (per il download). Assicurati che per il tipo di contenuto interessato non sia definito un modello di mappatura. Per ulteriori informazioni, consulta [Trasformazioni dei dati per REST APIs in API Gateway](rest-api-data-transformations.md).
Il limite della dimensione del payload è 10 MB. Consulta [Quote per la configurazione e l’esecuzione di una REST API in Gateway API](api-gateway-execution-service-limits-table.md).
Assicurati che ai file in Amazon S3 vengano aggiunti tipi di contenuto corretti come metadati dei file. Per il contenuto multimediale riproducibile in streaming, potrebbe essere necessario aggiungere anche `Content-Disposition:inline` ai metadati.
Per ulteriori informazioni sul supporto binario in API Gateway, consulta [Conversioni dei tipi di contenuto in API Gateway](api-gateway-payload-encodings-workflow.md).