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à.
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.
-
Esponi GET su una risorsa cartella per visualizzare un elenco di tutti gli oggetti di un bucket Amazon S3.
-
Esponi GET su una risorsa cartella/voce per visualizzare o scaricare un oggetto da un bucket Amazon S3.
Puoi importare l'API di esempio come proxy Amazon S3, come illustrato in Definizioni OpenAPI dell'API di esempio come un proxy Amazon S3. 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.
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.
Argomenti
Configurazione delle autorizzazioni IAM per consentire all'API di invocare operazioni Amazon S3
Creazione di risorse API per rappresentare risorse Amazon S3
Esposizione di un metodo API per elencare i bucket Amazon S3 dell'intermediario
Esposizione dei metodi API per accedere a un bucket Amazon S3
Esposizione dei metodi API per accedere a un oggetto Amazon S3 in un bucket
Definizioni OpenAPI dell'API di esempio come un proxy Amazon S3
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, crei un nuovo ruolo IAM.
Per creare il ruolo di esecuzione del proxy di AWS servizio
Accedi AWS Management Console e apri la console IAM all'indirizzo https://console.aws.amazon.com/iam/
. -
Scegliere Roles (Ruoli).
-
Scegliere Crea ruolo.
-
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.
-
Scegli Successivo e di nuovo Successivo.
-
In Role name (Nome ruolo) immettere
APIGatewayS3ProxyPolicye quindi selezionare Create role (Crea ruolo). -
Nell'elenco Roles (Ruoli) scegliere il ruolo appena creato. Potrebbe essere necessario scorrere o utilizzare la barra di ricerca per trovare il ruolo.
-
Per il ruolo selezionato, seleziona la scheda Aggiungi autorizzazioni.
-
Dall'elenco a discesa scegli Collega policy.
-
Nella barra di ricerca inserisci
AmazonS3FullAccesse 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.
-
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
-
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 /{folder} e /{item}.
-
Scegli Crea risorsa.
Mantieni l'opzione Risorsa proxy disattivata.
Per Percorso risorsa seleziona
/.Per Resource Name (Nome risorsa) immetti
{folder}.Mantieni CORS (Cross Origin Resource Sharing) deselezionato.
Scegli Crea risorsa.
Seleziona la risorsa /{folder}, quindi scegli Crea risorsa.
Ripeti le fasi precedenti per creare una risorsa figlio /{folder} denominata
{item}.L'API finale è simile a quanto riportato di seguito:
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 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
-
Seleziona la risorsa /, quindi scegli Crea metodo.
Per Tipo di metodo seleziona GET.
Per Tipo di integrazione seleziona Servizio AWS.
Per Regione AWS, seleziona il Regione AWS luogo in cui hai creato il tuo bucket Amazon S3.
Per Servizio AWS seleziona Amazon Simple Storage Service.
Lascia vuoto Sottodominio AWS .
Per Metodo HTTP seleziona GET.
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, in cui la risorsa Amazon S3 viene espressa dal percorso della risorsa del modello
s3-host-name/bucket/key. API Gateway imposta il valores3-host-namee passa i valoribucketekeyspecificati dal client ad Amazon S3.In Sostituzione percorso immetti /.
Per Ruolo di esecuzione immetti l'ARN del ruolo per
APIGatewayS3ProxyPolicy.Scegli Impostazioni della richiesta del metodo.
Si utilizzano le impostazioni della richiesta del metodo per controllare chi può chiamare questo metodo dell'API.
-
Per Autorizzazioni seleziona
AWS_IAMnel menu a discesa.
Scegli Crea metodo.
Questa configurazione integra la richiesta GET
https:// front-end con il back-end your-api-host/stage/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 /
-
Nella scheda Risposta metodo scegli Modifica in Risposta 200.
-
Scegli Aggiungi intestazione e procedi come descritto di seguito:
Per Nome intestazione immetti
Content-Type.Seleziona Add header (Aggiungi intestazione).
Ripeti queste fasi per creare un'intestazione
Timestampe un'intestazioneContent-Length. Seleziona Salva.
Nella scheda Risposta metodo scegli Crea risposta in Risposte del metodo.
Per Codice di stato HTTP immetti 400.
Non impostare alcuna intestazione per questa risposta.
Seleziona Salva.
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 /.
-
Nella scheda Risposta di integrazione scegli Modifica in Predefinito - Risposta.
Per l'intestazione Content-Length immetti
integration.response.header.Content-Lengthcome valore di mappatura.Per l'intestazione Content-Type immetti
integration.response.header.Content-Typecome valore di mappatura.Per l'intestazione Timestamp immetti
integration.response.header.Datecome valore di mappatura.Seleziona Salva. Il risultato sarà essere simile al seguente:
-
Nella scheda Risposta di integrazione scegli Crea risposta in Risposte di integrazione.
Per HTTP status regex (Regex stato HTTP), immettere
4\d{2}. Tutti i codici di stato della risposta HTTP 4xx sono così mappati alla risposta del metodo.Per Codice di stato risposta metodo seleziona
400.Scegli Create (Crea) .
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\d{2}.
Come suggerisce la buona norma, è opportuno testare l'API configurata fino a questo momento.
Test del metodo GET /
-
Seleziona la scheda Test. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.
-
Scegli Test (Esegui test). Il risultato sarà simile all'immagine seguente:
Esposizione dei metodi API per accedere a un bucket Amazon S3
Per utilizzare un bucket Amazon S3, esponi il metodo GET nella risorsa /{folder} 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. Per altri metodi, puoi importare l'API di esempio come descritto in Definizioni OpenAPI dell'API di esempio come un proxy Amazon S3.
Per esporre il metodo GET in una risorsa folder
Seleziona la risorsa /{folder}, quindi scegli Crea metodo.
Per Tipo di metodo seleziona GET.
Per Tipo di integrazione seleziona Servizio AWS.
Per Regione AWS, seleziona il Regione AWS luogo in cui hai creato il tuo bucket Amazon S3.
Per Servizio AWS seleziona Amazon Simple Storage Service.
Lascia vuoto Sottodominio AWS .
Per Metodo HTTP seleziona GET.
In Tipo di operazione scegli Utilizza sostituzione percorso.
Per Sostituzione percorso immetti
{bucket}.Per Ruolo di esecuzione immetti l'ARN del ruolo per
APIGatewayS3ProxyPolicy.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}
-
Nella scheda Richiesta di integrazione scegli Modifica in Impostazioni della richiesta di integrazione.
Seleziona Parametri di percorso URL, quindi scegli Aggiungi parametro di percorso.
Per Nome, immetti
bucket.-
In Mappato da, inserire
method.request.path.folder. Seleziona Salva.
A questo punto esegui il test dell'API.
Per testare il metodo /{folder} GET
-
Seleziona la scheda Test. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.
-
In Percorso immetti il nome del tuo bucket per folder.
-
Scegli Test (Esegui test).
Il risultato del test conterrà l'elenco degli oggetti presenti nel bucket.
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.
Per esporre il metodo GET in un elemento
-
Seleziona la risorsa /{item}, quindi scegli Crea metodo.
-
Per Tipo di metodo seleziona GET.
-
Per Tipo di integrazione seleziona Servizio AWS.
-
Per Regione AWS, seleziona il Regione AWS luogo in cui hai creato il tuo bucket Amazon S3.
-
Per Servizio AWS seleziona Amazon Simple Storage Service.
-
Lascia vuoto Sottodominio AWS .
-
Per Metodo HTTP seleziona GET.
-
In Tipo di operazione scegli Utilizza sostituzione percorso.
-
Per Sostituzione percorso immetti {bucket}/{object}.
-
Per Ruolo di esecuzione immetti l'ARN del ruolo per
APIGatewayS3ProxyPolicy. -
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}
-
Nella scheda Richiesta di integrazione scegli Modifica in Impostazioni della richiesta di integrazione.
-
Scegli Parametri di percorso URL.
-
Scegli Aggiungi parametro di percorso.
-
Per Nome, immetti
bucket. -
In Mappato da, inserire
method.request.path.folder. -
Scegli Aggiungi parametro di percorso.
-
Per Nome, immetti
object. -
In Mappato da, inserire
method.request.path.item. -
Seleziona Salva.
Per testare il metodo /{folder}/{object} GET
-
Seleziona la scheda Test. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.
-
In Percorso immetti il nome del tuo bucket per folder.
-
In Percorso immetti il nome di un elemento per item.
-
Scegli Test (Esegui test).
Il corpo della risposta conterrà il contenuto dell'elemento.
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
-
Registra i tipi di file multimediali del file interessato nelle API. binaryMediaTypes Questa operazione può essere eseguita nella console:
-
Scegli Impostazioni API per l'API.
-
In Tipi di media binari scegli Gestisci tipi di supporti.
-
Scegli Aggiungi tipo di supporto binario, quindi immetti il tipo di supporto richiesto, ad esempio
image/png. -
Scegli Salva modifiche per salvare l'impostazione.
-
-
Aggiungi l'intestazione
Content-Type(per il caricamento) e/oAccept(per il download) alla richiesta di metodo per chiedere al client di specificare il tipo di supporto binario richiesto e mapparlo alla richiesta di integrazione. -
Imposta Content Handling (Gestione contenuto) su
Passthroughnella 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.
Il limite della dimensione del payload è 10 MB. Consulta Quote di API Gateway per la configurazione e l'esecuzione di un'API REST.
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.
