Faire des demandes d'API

Outre l'utilisation de la console, vous pouvez utiliser l'AWS Transfer FamilyAPI pour configurer et gérer vos serveurs par programmation. Cette section décrit les opérations AWS Transfer Family, la signature des requêtes pour l'authentification et la gestion des erreurs. Pour plus d'informations sur les régions et les points de terminaison disponibles pour Transfer Family, consultez la section AWS Transfer FamilyPoints de terminaison et quotas dans le Références générales AWS

Transfer Family a requis les en-têtes de demande

Cette section décrit les en-têtes obligatoires que vous devez envoyer avec chaque requête POST àAWS Transfer Family. Vous incluez les en-têtes HTTP pour identifier les informations clés relatives à la requête, y compris l'opération que vous souhaitez appeler, la date de la requête et les informations correspondant à votre autorisation en tant qu'expéditeur de la requête. Les en-têtes ne sont pas sensibles à la casse et leur ordre n'est pas important.

L'exemple suivant montre les en-têtes utilisés dans l'ListServersopération.

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}

Les en-têtes suivants doivent être inclus dans vos requêtes POST adressées à Transfer Family. Les en-têtes ci-dessous qui commencent par « x-amz » sont spécifiques à. AWS Tous les autres en-têtes répertoriés sont des en-têtes courants utilisés dans les transactions 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

Transfer Family : saisie et signature des demandes

Toutes les entrées de demande doivent être envoyées dans le cadre de la charge utile JSON dans le corps de la demande. Pour les actions dans lesquelles tous les champs de requête sont facultatifs, par exempleListServers, vous devez toujours fournir un objet JSON vide dans le corps de la demande, tel que{}. La structure de la demande/réponse de charge utile de Transfer Family est documentée dans la référence d'API existante, par exemple. DescribeServer

Transfer Family prend en charge l'authentification à l'aide de AWS Signature Version 4. Pour plus de détails, consultez la section Signature des demandes d'AWSAPI.

Réponses d'erreur

Lorsqu'il y a une erreur, les informations de l'en-tête de réponse contiennent :

Le corps d'une réponse d'erreur contient des informations sur l'erreur qui s'est produite. L'exemple de réponse d'erreur suivant illustre la syntaxe de sortie des éléments de réponse commune à toutes les réponses d'erreur.

{
    "__type": "String",
    "Message": "String", <!-- Message is lowercase in some instances -->
    "Resource": String,
    "ResourceType": String
    "RetryAfterSeconds": String
}

Le tableau suivant explique les champs de réponse d'erreur JSON affichés dans la syntaxe précédente.

Exemples de réponses aux erreurs

Le corps JSON suivant est renvoyé si vous appelez l'DescribeServerAPI et spécifiez un serveur qui n'existe pas.

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

Le corps JSON suivant est renvoyé si l'exécution d'une API entraîne un ralentissement.

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

Le corps JSON suivant est renvoyé si vous utilisez l'CreateServerAPI et que vous ne disposez pas des autorisations suffisantes pour créer un serveur Transfer Family.

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

Le corps JSON suivant est renvoyé si vous utilisez l'CreateUserAPI et spécifiez un utilisateur qui existe déjà.

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

Bibliothèques disponibles

AWSfournit des bibliothèques, des exemples de code, des didacticiels et d'autres ressources aux développeurs de logiciels qui préfèrent créer des applications à l'aide d'API spécifiques au langage plutôt que des outils de ligne de commande et de l'API de requête. Ces bibliothèques fournissent des fonctions de base (non incluses dans les API), telles que l'authentification des demandes, les nouvelles tentatives et la gestion des erreurs, afin de faciliter le démarrage. Voir Outils sur lesquels s'appuyer AWS

Pour les bibliothèques et les exemples de code dans toutes les langues, voir Exemples de code et bibliothèques.