Moduli HTML (AWS Signature Version 2) - Amazon Simple Storage Service

Moduli HTML (AWS Signature Version 2)

Quando comunichi con Amazon S3, utilizzi in genere l'API REST o SOAP per eseguire operazioni di inserimento, recupero e di altro tipo. Con POST, gli utenti caricano i dati direttamente in Amazon S3 tramite i propri browser, che non possono elaborare l'API SOAP o creare una richiesta REST PUT.

Nota

Il supporto di SOAP su HTTP non viene più utilizzato ma è ancora disponibile su HTTPS. Le nuove funzioni di Amazon S3 non sono supportate per SOAP. Invece di utilizzare SOAP, si consiglia di utilizzare REST API o gli SDK AWS.

Per permettere agli utenti di caricare contenuti in Amazon S3 utilizzando i propri browser, devi utilizzare moduli HTML. I moduli HTML si compongono di una dichiarazione del modulo e di campi del modulo. La dichiarazione del modulo contiene informazioni generali sulla richiesta. I campi del modulo contengono informazioni dettagliate sulla richiesta, nonché la policy utilizzata per autenticarla e garantire che soddisfi le condizioni specificate.

Nota

I dati e i limiti del modulo (esclusi i contenuti del file) non possono superare 20 KB.

Questa sezione spiega come utilizzare i moduli HTML.

Codifica dei moduli HTML

Il modulo e la policy devono avere la codifica UTF-8. È possibile applicare la codifica UTF-8 al modulo specificandola nell'intestazione HTML o come intestazione di una richiesta.

Nota

La dichiarazione del modulo HTML non accetta parametri di autenticazione stringa di query.

Di seguito è illustrato un esempio della codifica UTF-8 nell'intestazione HTML:

<html> <head> ... <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> ... </head> <body>

Di seguito è illustrato un esempio della codifica UTF-8 nell'intestazione di una richiesta:

Content-Type: text/html; charset=UTF-8

Dichiarazione del modulo HTML

La dichiarazione del modulo presenta tre componenti: l'operazione, il metodo e il tipo di inquadramento. Se uno di questi valori non è impostato correttamente, la richiesta ha esito negativo.

L'operazione specifica l'URL che elabora la richiesta, il quale deve essere impostato sull'URL del bucket. Ad esempio, se il nome del bucket è awsexamplebucket1 e la regione è Stati Uniti occidentali (California settentrionale), l'URL è https://awsexamplebucket1.s3.us-west-1.amazonaws.com/.

Nota

Il nome della chiave è specificato nel campo del modulo.

Il metodo deve essere POST.

Il tipo di inquadramento (enctype) deve essere specificato e impostato su multipart/form-data sia per i caricamenti di file sia per i caricamenti di aree di testo. Per ulteriori informazioni, consulta RFC 1867.

Esempio

L'esempio seguente è la dichiarazione di un modulo per il bucket "awsexamplebucket".

<form action="https://awsexamplebucket1.s3.us-west-1.amazonaws.com/" method="post" enctype="multipart/form-data">

Campi del modulo HTML

Nella seguente tabella sono descritti i campi che possono essere utilizzati in un modulo HTML.

Nota

La variabile ${filename} viene sostituita automaticamente con il nome del file fornito dall'utente ed è riconosciuta da tutti i campi del modulo. Se il browser o il client fornisce un percorso completo o parziale al file, verrà utilizzato solo il testo che segue l'ultima barra (/) o barra rovesciata (\). Ad esempio, "C:\Program Files\directory1\file.txt" viene interpretato come "file.txt". Se non vengono forniti file o nomi di file, la variabile viene sostituita con una stringa vuota.

Nome campo Descrizione Campo obbligatorio
AWSAccessKeyId

L'ID chiave di accesso AWS del proprietario del bucket che concede a un utente anonimo l'accesso per una richiesta che soddisfa l'insieme dei vincoli della policy. Questo campo è obbligatorio se la richiesta include un documento di policy.

Condizionale

acl

Lista di controllo accessi (ACL) Amazon S3. Se si specifica una lista di controllo accessi non valida, viene generato un errore. Per ulteriori informazioni sulle ACL, consulta Liste di controllo accessi (ACL).

Tipo: string

Default: private

Valori validi: private | public-read | public-read-write | aws-exec-read | authenticated-read | bucket-owner-read | bucket-owner-full-control

No

Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires

Intestazioni specifiche per REST. Per ulteriori informazioni, consulta PUT Object.

No

key

Il nome della chiave caricata.

Per utilizzare il nome del file fornito dall'utente, utilizzare la variabile ${filename}. Ad esempio, se l'utente Betty carica il file lolcatz.jpg e si specifica /user/betty/${filename}, il file viene archiviato come /user/betty/lolcatz.jpg.

Per ulteriori informazioni, consulta Utilizzo dei metadati degli oggetti.

policy

Policy di sicurezza che descrive cosa è permesso nella richiesta. Le richieste senza policy di sicurezza sono considerate anonime e hanno esisto positivo solo su bucket pubblicamente scrivibili.

No

success_action_redirect, redirect

L'URL a cui viene reindirizzato il client dopo il corretto caricamento. Amazon S3 aggiunge i valori di bucket, chiave ed ETag come parametri della stringa di query all'URL.

Se success_action_redirect non è specificato, Amazon S3 restituisce il tipo di documento vuoto specificato nel campo success_action_status.

Se Amazon S3 non riesce a interpretare l'URL, ignora il campo .

Se il caricamento non riesce, Amazon S3 visualizza un errore e non reindirizza l'utente a un URL.

Per ulteriori informazioni, consulta Reindirizzamento.

Nota

Il nome del campo di reindirizzamento è obsoleto e in futuro il supporto del nome del campo di reindirizzamento verrà eliminato.

No

success_action_status

Il codice di stato restituito al client dopo il corretto caricamento, se non è specificato success_action_redirect.

I valori validi sono 200, 201 o 204 (default).

Se il valore è impostato su 200 o 204, Amazon S3 restituisce un documento vuoto con codice di stato 200 o 204.

Se il valore è impostato su 201, Amazon S3 restituisce un documento XML con codice di stato 201. Per informazioni sul contenuto del documento XML, consulta POST Object.

Se il valore non è impostato o non è valido, Amazon S3 restituisce un documento vuoto con codice di stato 204.

Nota

Alcune versioni di Adobe Flash Player non gestiscono correttamente le risposte HTTP con corpo vuoto. Per supportare i caricamenti tramite Adobe Flash, si consiglia di impostare success_action_status su 201.

No

signature

La firma HMAC costruita utilizzando la Secret Access Key che corrisponde all'AWSAccessKeyId fornito. Questo campo è obbligatorio se la richiesta include un documento di policy.

Per ulteriori informazioni, consulta Identity and Access Management in Amazon S3.

Condizionale

x-amz-security-token

Token di sicurezza utilizzato dalle credenziali per la sessione

Se la richiesta utilizza Amazon DevPay, richiede due campi del modulo x-amz-security-token: uno per il token prodotto e uno per il token utente.

Se la richiesta utilizza le credenziali per la sessione, richiede un modulo x-amz-security-token. Per ulteriori informazioni, consulta Credenziali di sicurezza temporanee nella Guida per l'utente di IAM.

No

Altri nomi di campi con prefisso x-amz-meta-

Metadata specificati dall'utente.

Amazon S3 non convalida o utilizza questi dati.

Per ulteriori informazioni, consulta PutObject.

No

file

File o contenuto di testo.

Il file o il contenuto deve essere l'ultimo campo del modulo. Tutti i campi al di sotto di questo vengono ignorati.

Non è possibile caricare più di un file alla volta.

Costruzione della policy

La policy è un documento JSON con codifica UTF-8 e Base64 che specifica le condizioni che la richiesta deve soddisfare ed è utilizzata per autenticare il contenuto. A seconda di come si progettano i documenti di policy, è possibile utilizzarli per caricamento, per utente, per tutti i caricamenti o secondo altre progettazioni in base alle esigenze.

Nota

Sebbene il documento di policy sia facoltativo, è fortemente consigliato rispetto a rendere il bucket pubblicamente scrivibile.

Di seguito è illustrato un esempio di documento di policy:

{ "expiration": "2007-12-01T12:00:00.000Z", "conditions": [ {"acl": "public-read" }, {"bucket": "awsexamplebucket1" }, ["starts-with", "$key", "user/eric/"], ] }

Il documento di policy contiene la scadenza e le condizioni.

Expiration

L'elemento scadenza specifica la data di scadenza della policy in formato ISO 8601 UTC. Ad esempio, "2007-12-01T12:00:00.000Z" specifica che la policy non è valida dopo mezzanotte, orario UTC, del 01/12/2007. In una policy la scadenza è obbligatoria.

Condizioni

Le condizioni nel documento di policy convalidano i contenuti dell'oggetto caricato. Ciascun campo del modulo specificato nel modulo (ad eccezione di AWSAccessKeyId, firma, file, policy e nomi dei campi con prefisso x-ignore-) deve essere incluso nell'elenco delle condizioni.

Nota

Se si dispone di più campi con lo stesso nome, i valori devono essere separati da virgole. Ad esempio, se si dispone di due campi denominati "x-amz-meta-tag", dove il valore del primo è "Ninja" e quello del secondo è "Stallman", si imposta il documento di policy su Ninja,Stallman.

Tutte le variabili all'interno del modulo vengono estese prima della convalida della policy. Pertanto, tutte le corrispondenze delle condizioni devono essere eseguite rispetto ai campi estesi. Ad esempio, se si imposta il campo della chiave su user/betty/${filename}, la policy potrebbe essere [ "starts-with", "$key", "user/betty/" ]. Non inserire [ "starts-with", "$key", "user/betty/${filename}" ]. Per ulteriori informazioni, consulta Corrispondenza delle condizioni.

La tabella seguente descrive le condizioni del documento di policy.

Nome elemento Descrizione
acl

Specifica le condizioni che l'ACL deve soddisfare.

Supporta la corrispondenza esatta e starts-with.

content-length-range

Specifica la dimensione minima e massima consentita per il contenuto caricato.

Supporta la corrispondenza dell'intervallo.

Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires

Intestazioni specifiche per REST.

Supporta la corrispondenza esatta e starts-with.

key

Il nome della chiave caricata.

Supporta la corrispondenza esatta e starts-with.

success_action_redirect, redirect

L'URL a cui viene reindirizzato il client dopo il corretto caricamento.

Supporta la corrispondenza esatta e starts-with.

success_action_status

Il codice di stato restituito al client dopo il corretto caricamento, se non è specificato success_action_redirect.

Supporta la corrispondenza esatta.

x-amz-security-token

Token di sicurezza Amazon DevPay.

Ogni richiesta che utilizza Amazon DevPay richiede due campi del modulo x-amz-security-token: uno per il token prodotto e uno per il token utente. Di conseguenza, i valori devono essere separati da virgole. Ad esempio, se il token utente è eW91dHViZQ== e il token prodotto è b0hnNVNKWVJIQTA=, si imposta la voce di policy su: { "x-amz-security-token": "eW91dHViZQ==,b0hnNVNKWVJIQTA=" }.

Altri nomi di campi con prefisso x-amz-meta-

Metadata specificati dall'utente.

Supporta la corrispondenza esatta e starts-with.

Nota

Se il kit di strumenti aggiunge ulteriori campi (ad esempio, Flash aggiunge il nome del file), è necessario aggiungerli al documento di policy. Se puoi controllare questa funzionalità, aggiungi il prefisso x-ignore- al campo in modo che Amazon S3 ignori la funzionalità e non ne alteri le versioni future.

Corrispondenza delle condizioni

La tabella seguente descrive i tipi di corrispondenza delle condizioni. Sebbene occorra specificare una condizione per ciascun campo del modulo specificato nel modulo, è possibile creare criteri di corrispondenza più complessi specificando più condizioni per un campo del modulo.

Condition Descrizione

Corrispondenze esatte

Le corrispondenze esatte verificano che i campi corrispondano a specifici valori. Questo esempio indica che l'ACL deve essere impostata su public-read:

{"acl": "public-read" }

Questo esempio rappresenta un modo alternativo per indicare che l'ACL deve essere impostata su public-read:

[ "eq", "$acl", "public-read" ]

Inizia con

Se il valore deve iniziare con un determinato valore, utilizzare starts-with. Questo esempio indica che la chiave deve iniziare con user/betty:

["starts-with", "$key", "user/betty/"]

Corrispondenza di qualsiasi contenuto

Per configurare la policy in modo da autorizzare qualsiasi contenuto in un campo, utilizzare starts-with con un valore vuoto. Questo esempio permette qualsiasi success_action_redirect:

["starts-with", "$success_action_redirect", ""]

Specifica degli intervalli

Per i campi che accettano intervalli, separare gli intervalli superiori e inferiori con una virgola. Questo esempio permette una dimensione dei file da 1 a 10 megabyte:

["content-length-range", 1048579, 10485760]

Utilizzo di escape con caratteri

La tabella seguente descrive i caratteri da inserire in una sequenza di escape in un documento di policy.

Sequenza di escape Descrizione

\\

Barra rovesciata

\$

Simbolo del dollaro

\b

Backspace

\f

Avanzamento modulo

\n

Nuova riga

\r

Ritorno a capo

\t

Tabulatore orizzontale

\v

Tabulatore verticale

\uxxxx

Tutti i caratteri Unicode

Costruzione di una firma

Fase Descrizione
1

Codificare la policy utilizzando UTF-8.

2

Codificare i byte UTF-8 utilizzando Base64.

3

Firmare la policy con la Secret Access Key utilizzando HMAC SHA-1.

4

Codificare la firma SHA-1 utilizzando Base64.

Per ulteriori informazioni sull'autenticazione, consulta Identity and Access Management in Amazon S3.

Reindirizzamento

Questa sezione descrive come gestire i reindirizzamenti.

Reindirizzamento generico

Al completamento della richiesta POST, l'utente viene reindirizzato alla posizione specificata nel campo success_action_redirect. Se Amazon S3 non riesce a interpretare l'URL, ignora il campo success_action_redirect.

Se success_action_redirect non è specificato, Amazon S3 restituisce il tipo di documento vuoto specificato nel campo success_action_status.

Se la richiesta POST non riesce, Amazon S3 visualizza un errore e non fornisce un reindirizzamento.

Reindirizzamento precedente al caricamento

Se il bucket è stato creato utilizzando <CreateBucketConfiguration>, gli utenti finali potrebbero richiedere un reindirizzamento. In tal caso, alcuni browser potrebbero gestire il reindirizzamento in modo errato. Ciò è relativamente raro, ma vi è maggiore probabilità che si verifichi subito dopo la creazione del bucket.