Effettuare richieste API

Oltre a utilizzare la console, puoi utilizzare l'AWS Transfer FamilyAPI per configurare e gestire i tuoi server in modo programmatico. Questa sezione descrive le operazioni AWS Transfer Family, la firma delle richieste per l'autenticazione e la gestione degli errori. Per informazioni sulle regioni e gli endpoint disponibili per Transfer Family, consulta AWS Transfer Familyendpoint e quote nel Riferimenti generali di AWS

Intestazioni di richiesta obbligatorie per Transfer Family

Questa sezione descrive le intestazioni obbligatorie a cui devi inviare con ogni richiesta POST. AWS Transfer Family Devi includere intestazioni HTTP per identificare le informazioni principali sulla richiesta, tra cui l'operazione che vuoi richiamare, la data della richiesta e le informazioni che indicano la tua autorizzazione 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'ListServersoperazione.

POST / HTTP/1.1
Host: transfer.us-east-1.amazonaws.com
x-amz-target: TransferService.ListServers
x-amz-date: 20220507T012034Z
Authorization: AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/20220507/us-east-1/transfer/aws4_request,
    SignedHeaders=content-type;host;x-amz-date;x-amz-target,
    Signature=13550350a8681c84c861aac2e5b440161c2b33a3e4f302ac680ca5b686de48de
Content-Type: application/x-amz-json-1.1
Content-Length: 17

{"MaxResults":10}

Di seguito sono riportate le intestazioni che devono essere incluse nelle richieste POST a Transfer Family. Le intestazioni mostrate di seguito che iniziano con «x-amz» sono specifiche per. AWS Tutte le altre intestazioni elencate sono intestazioni comuni usate in transazioni HTTP.

Content-Type: application/x-amz-json-1.1

Host: transfer.region.amazonaws.com

x-amz-date: YYYYMMDD'T'HHMMSS'Z'

x-amz-target: TransferService.operationName

Input e firma delle richieste Transfer Family

Tutti gli input della richiesta devono essere inviati come parte del payload JSON nel corpo della richiesta. Per le azioni in cui tutti i campi di richiesta sono facoltativi, ad esempioListServers, è comunque necessario fornire un oggetto JSON vuoto nel corpo della richiesta, ad esempio. {} La struttura della richiesta/risposta del payload Transfer Family è documentata, ad esempio, nel riferimento all'API esistente. DescribeServer

Transfer Family supporta l'autenticazione tramite AWS Signature Version 4. Per i dettagli, consulta la sezione Richieste AWS API di firma.

Risposte agli errori

Quando si verifica un errore, le informazioni dell'intestazione della risposta contengono:

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", <!-- Message is lowercase in some instances -->
    "Resource": String,
    "ResourceType": String
    "RetryAfterSeconds": String
}

La tabella seguente illustra i campi della risposta di errore JSON mostrata nella sintassi precedente.

Esempi di risposte agli errori

Il seguente corpo JSON viene restituito se si chiama l'DescribeServerAPI e si specifica un server che non esiste.

{
  "__type": "ResourceNotFoundException",
  "Message": "Unknown server",
  "Resource": "s-11112222333344444",
  "ResourceType": "Server"
}

Il seguente corpo JSON viene restituito se l'esecuzione di un'API causa la limitazione.

{
   "__type":"ThrottlingException",
   "RetryAfterSeconds":"1"
}

Il seguente corpo JSON viene restituito se si utilizza l'CreateServerAPI e non si dispone di autorizzazioni sufficienti per creare un server Transfer Family.

{
  "__type": "AccessDeniedException",
  "Message": "You do not have sufficient access to perform this action."
}

Il seguente corpo JSON viene restituito se si utilizza l'CreateUserAPI e si specifica un utente già esistente.

{  
  "__type": "ResourceExistsException",  
  "Message": "User already exists",
  "Resource": "Alejandro-Rosalez",
  "ResourceType": "User"
}  

Librerie disponibili

AWSfornisce librerie, codice di esempio, tutorial e altre risorse per gli sviluppatori di software che preferiscono creare applicazioni utilizzando API specifiche del linguaggio anziché gli strumenti da riga di comando e l'API Query. Queste librerie forniscono funzioni di base (non incluse nelle API), come l'autenticazione delle richieste, i nuovi tentativi di richiesta e la gestione degli errori, in modo che sia più facile iniziare. Vedi Strumenti su cui basarsi AWS

Per le librerie e il codice di esempio in tutte le lingue, vedi Codice di esempio e librerie.