La documentazione del gateway di file Amazon S3 è stata spostata in Cos'è un gateway di file Amazon S3?
La documentazione di Amazon FSx File Gateway è stata spostata in Cos'è Amazon FSx File Gateway?
La documentazione del gateway di nastri virtuali è stata spostata in Cos'è un gateway di nastri virtuali?
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à.
APIRiferimento per Storage Gateway
Oltre a utilizzare la console, è possibile utilizzarla per configurare e AWS Storage Gateway API gestire i gateway in modo programmatico. Questa sezione descrive AWS Storage Gateway le operazioni, la richiesta di firma per l'autenticazione e la gestione degli errori. Per ulteriori informazioni sulle regioni e sugli endpoint disponibili per Storage Gateway, consulta Endpoint e quote AWS Storage Gateway nella Riferimenti generali di AWS.
Nota
È inoltre possibile utilizzare AWS SDKs il per sviluppare applicazioni con AWS Storage Gateway. Il AWS SDKs per Java,. NETe PHP racchiude le informazioni sottostanti AWS Storage Gateway API, semplificando le attività di programmazione. Per informazioni sul download delle SDK librerie, vedete Sample Code Libraries.
Argomenti
Intestazioni obbligatorie delle richieste in Storage Gateway
Questa sezione descrive le intestazioni richieste da inviare con ogni POST richiesta a Storage Gateway. Sono incluse HTTP intestazioni per identificare le informazioni chiave sulla richiesta, tra cui l'operazione che si desidera richiamare, la data della richiesta e le informazioni che indicano l'autorizzazione dell'utente come mittente della richiesta. Le intestazioni fanno distinzione tra maiuscole e minuscole, ma l'ordine delle intestazioni non è importante.
L'esempio seguente mostra le intestazioni utilizzate nell'operazione. ActivateGateway
POST / HTTP/1.1 Host: storagegateway.us-east-2.amazonaws.com Content-Type: application/x-amz-json-1.1 Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20120425/us-east-2/storagegateway/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=9cd5a3584d1d67d57e61f120f35102d6b3649066abdd4bf4bbcf05bd9f2f8fe2 x-amz-date: 20120912T120000Z x-amz-target: StorageGateway_20120630.ActivateGateway
Di seguito sono riportate le intestazioni da includere nelle POST richieste a Storage Gateway. Le intestazioni mostrate di seguito che iniziano con «x-amz» sono intestazioni specifiche. AWS Tutte le altre intestazioni elencate sono intestazioni comuni utilizzate nelle transazioni. HTTP
Header | Descrizione |
---|---|
Authorization |
L'intestazione di autorizzazione contiene diverse informazioni sulla richiesta, che permettono a Storage Gateway di determinare se la richiesta è un'operazione valida per il richiedente. Il formato di questa intestazione è il seguente (con l'aggiunta di interruzioni di riga ai fini della leggibilità):
Nella sintassi precedente, si specificano l'anno YourAccessKey, il mese e il giorno (aaaammgg), la regione e il. CalculatedSignature Il formato dell'intestazione di autorizzazione è dettato dai requisiti del processo di firma V4. AWS I dettagli sulla firma vengono approfonditi nell'argomento Firmare le richieste. |
Content-Type |
Usa
|
Host |
Usa l'intestazione host per specificare l'endpoint Storage Gateway in cui invii la richiesta. Ad esempio,
|
x-amz-date |
È necessario fornire il timestamp nell'intestazione o nell'HTTP
|
x-amz-target |
Questa intestazione specifica la versione API e l'operazione richiesta. I valori di intestazione di destinazione sono formati concatenando la API versione con il API nome e sono nel seguente formato.
Il operationNamevalore (ad esempio "ActivateGateway«) può essere trovato dall'elenco,. API APIRiferimento per Storage Gateway |
Firmare le richieste
Storage Gateway richiede l'autenticazione con firma di ogni richiesta inviata. Per firmare una richiesta, è necessario calcolare una firma digitale utilizzando una funzione hash crittografica. Una funzione hash crittografica è una funzione che restituisce un valore hash univoco basato sull'input. L'input alla funzione hash include il testo della richiesta e la tua chiave di accesso segreta. La funzione hash restituisce un valore hash che includi nella richiesta come firma. La firma è parte dell'intestazione Authorization
della richiesta.
Dopo aver ricevuto la richiesta, Storage Gateway ricalcola la firma utilizzando la stessa funzione hash e lo stesso input utilizzati per firmare la richiesta. Se la firma risultante corrisponde alla firma nella richiesta, Storage Gateway elabora la richiesta. In caso contrario, la richiesta viene respinta.
Storage Gateway supporta l'autenticazione con AWS Signature Version 4. La procedura per il calcolo di una firma può essere suddivisa in tre fasi:
-
Fase 1. Creazione di una richiesta canonica
Riorganizza la tua HTTP richiesta in un formato canonico. L'utilizzo di un formato canonico è necessario in quanto Storage Gateway utilizza quel formato quando ricalcola una firma da confrontare con quella che hai inviato.
-
Fase 2: creazione di una stringa di firma
Crea una stringa che utilizzerai come uno dei valori di input per la funzione hash crittografica. La stringa, denominata stringa di firma, è una concatenazione del nome dell'algoritmo hash, della data della richiesta, di una stringa di ambito credenziali e della richiesta in formato canonico creata nella fase precedente. La stringa di ambito credenziali è anch'essa una concatenazione di data, regione e informazioni sul servizio.
-
Fase 3. Creazione di una firma
Crea una firma per la tua richiesta utilizzando una funzione hash crittografica che accetta due stringhe di input: la tua stringa di firma e una chiave derivata. La chiave derivata viene calcolata partendo dalla chiave di accesso segreta e utilizzando la stringa Credential Scope per creare una serie di codici di autenticazione dei messaggi basati su Hash (). HMACs
Esempio di calcolo di firma
L'esempio seguente illustra i dettagli della creazione di una firma per. ListGateways L'esempio può essere utilizzato come riferimento per verificare il metodo di calcolo della firma. Altri calcoli di riferimento sono descritti in Suite di test Signature Version 4 nel glossario di Amazon Web Services.
L'esempio presuppone quanto segue:
-
Il timestamp della richiesta è «Lun, 10 settembre 2012 00:00:00". GMT
-
L'endpoint è la regione Stati Uniti orientali (Ohio).
La sintassi generale della richiesta (incluso il corpo) è: JSON
POST / HTTP/1.1 Host: storagegateway.us-east-2.amazonaws.com x-amz-Date: 20120910T000000Z Authorization:
SignatureToBeCalculated
Content-type: application/x-amz-json-1.1 x-amz-target: StorageGateway_20120630.ListGateways {}
Il formato canonico della richiesta calcolata per è:
POST / content-type:application/x-amz-json-1.1 host:storagegateway.us-east-2.amazonaws.com x-amz-date:20120910T000000Z x-amz-target:StorageGateway_20120630.ListGateways content-type;host;x-amz-date;x-amz-target 44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a
L'ultima riga della richiesta canonica è l'hash del corpo della richiesta. Nota inoltre la terza riga vuota nella richiesta canonica. Questo perché non esistono parametri di interrogazione per questo API (o per alcun Storage GatewayAPIs).
AWS4-HMAC-SHA256 20120910T000000Z 20120910/us-east-2/storagegateway/aws4_request 92c0effa6f9224ac752ca179a04cecbede3038b0959666a8160ab452c9e51b3e
La prima riga della stringa di firma è l'algoritmo, la seconda è il timestamp, la terza è l'ambito credenziali e l'ultima è un hash del formato della richiesta canonica in Fase 1.
Per , la chiave derivata può essere rappresentata come segue:
derived key = HMAC(HMAC(HMAC(HMAC("AWS4" + YourSecretAccessKey,"20120910"),"us-east-2"),"storagegateway"),"aws4_request")
Se viene utilizzata la chiave di accesso segreta, wJalr XUtnFEMI /K7MDENG/bPxRfiCYEXAMPLEKEY, la firma calcolata è:
6d4c40b8f2257534dbdca9f326f147a0a7a419b63aff349d9d9c737c9a0f4c81
La fase finale consiste nel creare l'intestazione Authorization
. Per la chiave di accesso dimostrativaAKIAIOSFODNN7EXAMPLE, l'intestazione (con interruzioni di riga aggiunte per motivi di leggibilità) è:
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20120910/us-east-2/storagegateway/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=6d4c40b8f2257534dbdca9f326f147a0a7a419b63aff349d9d9c737c9a0f4c81
Risposte agli errori
Questa sezione fornisce informazioni di riferimento sugli errori. AWS Storage Gateway Questi errori sono rappresentati da un'eccezione di errore e da un codice di errore dell'operazione. Ad esempio, l'eccezione di errore InvalidSignatureException
viene restituita da qualsiasi API risposta in caso di problemi con la firma della richiesta. Tuttavia, il codice di errore dell'operazione ActivationKeyInvalid
viene restituito solo per ActivateGatewayAPI.
A seconda del tipo di errore, Storage Gateway può restituire solo un'eccezione oppure sia un'eccezione che un codice di errore dell'operazione. In Risposte agli errori vengono forniti esempi di risposte di errore.
Eccezioni
Nella tabella seguente sono elencate le AWS Storage Gateway API eccezioni. Quando un' AWS Storage Gateway operazione restituisce una risposta di errore, il corpo della risposta contiene una di queste eccezioni. InternalServerError
e InvalidGatewayRequestException
restituiscono uno dei messaggi Codici di errore delle operazioni dei codici di errore delle operazioni che forniscono il codice di errore dell'operazione specifico.
Eccezione | Messaggio | HTTPCodice di stato |
---|---|---|
IncompleteSignatureException |
La firma specificata non è completa. | 400 Richiesta non valida |
InternalFailure |
L'elaborazione della richiesta non è riuscita a causa di un errore, un'eccezione o un guasto sconosciuto. | 500 - Errore interno del server |
InternalServerError |
Uno dei messaggi dei codici di errore delle operazioni in Codici di errore delle operazioni. | 500 - Errore interno del server |
InvalidAction |
L'azione o l'operazione richiesta non è valida. | 400 Richiesta non valida |
InvalidClientTokenId |
Il certificato X.509 o AWS l'ID della chiave di accesso fornito non esiste nei nostri archivi. | 403 Non consentito |
InvalidGatewayRequestException |
Uno dei messaggi dei codici di errore delle operazioni in Codici di errore delle operazioni. | 400 Richiesta non valida |
InvalidSignatureException |
La firma di richiesta che abbiamo calcolato non corrisponde alla firma che hai fornito. Controlla la tua chiave di AWS accesso e il metodo di firma. | 400 Richiesta non valida |
MissingAction |
Nella richiesta manca un parametro di un'azione o un'operazione. | 400 Richiesta non valida |
MissingAuthenticationToken |
La richiesta deve contenere un ID chiave di AWS accesso valido (registrato) o un certificato X.509. | 403 Non consentito |
RequestExpired |
La richiesta ha superato la data di scadenza o la data della richiesta (con margine di 15 minuti) oppure la data della richiesta è oltre 15 minuti nel futuro. | 400 Richiesta non valida |
SerializationException |
Si è verificato un errore durante la serializzazione. Verifica che il tuo JSON payload sia ben formato. | 400 Richiesta non valida |
ServiceUnavailable |
La richiesta non è riuscita a causa di un errore temporaneo del server. | 503 Service Unavailable (503 Servizio non disponibile) |
SubscriptionRequiredException |
L' AWS Access Key Id richiede un abbonamento per il servizio. | 400 Richiesta non valida |
ThrottlingException |
Velocità superata. | 400 Richiesta non valida |
TooManyRequests |
Troppe richieste. | 429 Troppe richieste |
UnknownOperationException |
È stata specificata un'operazione sconosciuta. Le operazioni valide sono elencate in Operazioni in Storage Gateway. | 400 Richiesta non valida |
UnrecognizedClientException |
Il token di sicurezza incluso nella richiesta non è valido. | 400 Richiesta non valida |
ValidationException |
Il valore di un parametro di input è errato o non compreso nell'intervallo. | 400 Richiesta non valida |
Codici di errore delle operazioni
La tabella seguente mostra la mappatura tra i codici di errore AWS Storage Gateway operativi e APIs che può restituire i codici. Tutti i codici di errore delle operazioni vengono restituiti con una delle due eccezioni generali InternalServerError
e InvalidGatewayRequestException
descritte in Eccezioni.
Codice di errore dell'operazione | Messaggio | Operazioni che restituiscono questo codice di errore |
---|---|---|
ActivationKeyExpired |
La chiave di attivazione specificata è scaduta. | ActivateGateway |
ActivationKeyInvalid |
La chiave di attivazione specificata non è valida. | ActivateGateway |
ActivationKeyNotFound |
La chiave di attivazione specificata non è stata trovata. | ActivateGateway |
BandwidthThrottleScheduleNotFound |
La limitazione di larghezza di banda specificata non è stata trovata. | DeleteBandwidthRateLimit |
CannotExportSnapshot |
Lo snapshot specificato non può essere esportato. | |
InitiatorNotFound |
L'iniziatore specificato non è stato trovato. | DeleteChapCredentials |
DiskAlreadyAllocated |
Il disco specificato è già allocato. | |
DiskDoesNotExist |
Il disco specificato non esiste. | |
DiskSizeNotGigAligned |
Il disco specificato non è allineato ai gigabyte. | |
DiskSizeGreaterThanVolumeMaxSize |
La dimensione del disco specificata è superiore alla dimensione massima del volume. | CreateStorediSCSIVolume |
DiskSizeLessThanVolumeSize |
La dimensione del disco specificata è inferiore alla dimensione del volume. | CreateStorediSCSIVolume |
DuplicateCertificateInfo |
Le informazioni sul certificato specificate sono duplicate. | ActivateGateway |
GatewayInternalError |
Si è verificato un errore interno del gateway. | |
GatewayNotConnected |
Il gateway specificato non è connesso. | |
GatewayNotFound |
Il gateway specificato non è stato trovato. | |
GatewayProxyNetworkConnectionBusy |
La connessione di rete proxy gateway specificata è occupata. | |
InternalError |
Si è verificato un errore interno. | |
InvalidParameters |
La richiesta specificata contiene parametri non corretti. | |
LocalStorageLimitExceeded |
Il limite di storage locale è stato superato. | |
LunInvalid |
Il valore specificato non LUN è corretto. | CreateStorediSCSIVolume |
MaximumVolumeCountExceeded |
Il numero massimo di volumi è stato superato. | |
NetworkConfigurationChanged |
La configurazione di rete del gateway è stata modificata. | |
NotSupported |
L'operazione specificata non è supportata. | |
OutdatedGateway |
Il gateway specificato non è aggiornato. | ActivateGateway |
SnapshotInProgressException |
Lo snapshot specificato è in corso. | DeleteVolume |
SnapshotIdInvalid |
Lo snapshot specificato non è valido. | |
StagingAreaFull |
L'area di gestione temporanea è piena. | |
TargetAlreadyExists |
La destinazione specificata esiste già. | |
TargetInvalid |
La destinazione specificata non è valida. | |
TargetNotFound |
La destinazione specificata non è stata trovata. | |
UnsupportedOperationForGatewayType |
L'operazione specificata non è valida per il tipo di gateway. | |
VolumeAlreadyExists |
Il volume specificato esiste già. | |
VolumeIdInvalid |
Il volume specificato non è valido. | DeleteVolume |
VolumeInUse |
Il volume specificato è già in uso. | DeleteVolume |
VolumeNotFound |
Il volume specificato non è stato trovato. | |
VolumeNotReady |
Il volume specificato non è pronto. |
Risposte agli errori
Quando si verifica un errore, le informazioni dell'intestazione della risposta contengono:
-
Tipo di contenuto: application/ -1.1 x-amz-json
-
Un codice appropriato o di stato
4xx
5xx
HTTP
Il corpo di una risposta di errore contiene informazioni relative all'errore. La risposta di errore di esempio seguente mostra la sintassi di output degli elementi della risposta comuni a tutte le risposte di errore.
{ "__type": "String", "message": "String", "error": { "errorCode": "String", "errorDetails": "String" } }
La tabella seguente illustra i campi JSON di risposta agli errori mostrati nella sintassi precedente.
- __type
-
Una delle eccezioni elencate in Eccezioni.
▬Tipo: stringa
- error
-
Contiene dettagli API sull'errore specifici. In caso di errori generali (ossia non specificiAPI), queste informazioni sull'errore non vengono visualizzate.
Tipo: raccolta
- errorCode
-
Uno dei codici di errore delle operazioni .
▬Tipo: stringa
- errorDetails
-
Questo campo non è utilizzato nella versione corrente diAPI.
▬Tipo: stringa
- message
-
Uno dei messaggi dei codici di errore delle operazioni.
▬Tipo: stringa
Esempi di risposta di errore
Il seguente JSON corpo viene restituito se si utilizza DescribeStoredi SCSIVolumes API e si specifica un input di ARN richiesta gateway che non esiste.
{ "__type": "InvalidGatewayRequestException", "message": "The specified volume was not found.", "error": { "errorCode": "VolumeNotFound" } }
Il seguente JSON corpo viene restituito se Storage Gateway calcola una firma che non corrisponde alla firma inviata con una richiesta.
{ "__type": "InvalidSignatureException", "message": "The request signature we calculated does not match the signature you provided." }
Operazioni in Storage Gateway
Per un elenco delle operazioni dello Storage Gateway, vedere Azioni nel AWS Storage Gateway APIriferimento.