Télécharger des fichiers volumineux à l’aide d’une session de chargement

Article
04/08/2023

Créez une session de chargement pour permettre à votre application de charger les fichiers les plus volumineux. Une session de chargement permet à votre application de charger des plages du fichier dans des demandes d’API séquentielles, ce qui permet de reprendre le transfert si une connexion est supprimée pendant le chargement.

Pour charger un fichier à l’aide d’une session de chargement, vous devez suivre ces deux étapes :

Création d’une session de chargement
Chargement des octets vers la session de chargement

Autorisations

L’une des autorisations suivantes est requise pour appeler cette API. Pour plus d’informations, notamment sur la façon de choisir les autorisations, voir Autorisations.

Type d’autorisation	Autorisations (de celle qui offre le plus de privilèges à celle qui en offre le moins)
Déléguée (compte professionnel ou scolaire)	Files.ReadWrite, Files.ReadWrite.All, Sites.ReadWrite.All
Déléguée (compte Microsoft personnel)	Files.ReadWrite, Files.ReadWrite.All
Application	Sites.ReadWrite.All

Création d’une session de chargement

Pour commencer à charger un fichier volumineux, votre application doit d’abord demander une nouvelle session de chargement. Cela crée un emplacement de stockage temporaire où les octets du fichier seront enregistrés jusqu’au chargement complet du fichier. Pour charger un nouveau fichier, spécifiez l’ID ou le chemin d’accès du dossier parent. Pour mettre à jour un fichier existant, spécifiez l’ID ou le chemin d’accès du fichier à mettre à jour. Lorsque le dernier octet du fichier est chargé, la session de chargement est terminée et le fichier final apparaît dans le dossier de destination.

Requête HTTP

POST /drives/{driveId}/items/{itemId}/createUploadSession
POST /drives/{driveId}/items/{itemId}:/{fileName}:/createUploadSession
POST /groups/{groupId}/drive/items/{itemId}/createUploadSession
POST /me/drive/items/{itemId}/createUploadSession
POST /sites/{siteId}/drive/items/{itemId}/createUploadSession
POST /users/{userId}/drive/items/{itemId}/createUploadSession

Corps de la demande

Vous n’êtes pas obligé de spécifier le corps de la demande. Toutefois, vous pouvez spécifier une propriété item dans le corps de la demande en fournissant des données supplémentaires sur le fichier en cours de chargement.

{
  "@microsoft.graph.conflictBehavior": "rename | fail | replace",
  "description": "description",
  "fileSystemInfo": { "@odata.type": "microsoft.graph.fileSystemInfo" },
  "name": "filename.txt"
}

Par exemple, pour contrôler le comportement de la session au cas où le nom de fichier serait déjà utilisé, vous pouvez spécifier dans le corps de la demande les propriétés de comportement en cas de conflit.

{
  "item": {
    "@microsoft.graph.conflictBehavior": "rename"
  }
}

En-têtes de demande facultatifs

Nom	Valeur	Description
if-match	etag	Si cet en-tête de demande est inclus et que l’eTag (ou cTag) fourni ne correspond pas à l’eTag actuel sur le dossier, une erreur `412 Precondition Failed` est renvoyée.

Propriétés

Propriété	Type	Description
description	String	Fournit une description de l’élément visible par l’utilisateur. En lecture-écriture. Uniquement sur OneDrive Personnel
fileSystemInfo	fileSystemInfo	Informations du système de fichiers sur le client. En lecture-écriture.
nom	String	Nom de l’élément (nom de fichier et extension). En lecture-écriture.

Demande

La réponse à cette demande fournira les détails du type uploadSession qui vient d’être créé, qui inclut l’URL utilisée pour charger les parties du fichier.

POST /drive/root:/{item-path}:/createUploadSession
Content-Type: application/json

{
  "item": {
    "@odata.type": "microsoft.graph.driveItemUploadableProperties",
    "@microsoft.graph.conflictBehavior": "rename",
    "name": "largefile.dat"
  }
}

Réponse

La réponse à cette demande, si celle-ci réussit, fournit les détails de l’emplacement auquel le reste des demandes doit être envoyé en tant que ressource UploadSession.

Cette ressource fournit des détails sur l’emplacement vers lequel la gamme d’octets du fichier doit être chargée ainsi que sur la date d’expiration de la session de chargement.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uploadUrl": "https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337",
  "expirationDateTime": "2015-01-29T09:21:55.523Z"
}

Chargement des octets vers la session de chargement

Pour charger le fichier, ou une partie du fichier, votre application envoie une demande PUT à la valeur uploadUrl reçue dans la réponse createUploadSession. Vous pouvez charger l’intégralité du fichier, ou le diviser en plusieurs plages d’octets, tant que le nombre maximal d’octets de chaque demande est inférieur à 60 Mio.

Les fragments du fichier doivent être chargés séquentiellement et dans l’ordre. Si vous chargez les fragments du fichier dans le désordre, un message d’erreur est généré.

Remarque : si votre application fractionne un fichier en plusieurs gammes d’octets, la taille de chaque gamme d’octet DOIT être un multiple de 320 Kio (327 680 octets). Si la taille indiquée n’est pas un diviseur de 320 Kio, certains fichiers ne seront pas validés.

Exemple

Dans cet exemple, l’application charge les 26 premiers octets d’un fichier de 128 octets.

L’en-tête Content-Length spécifie la taille de la demande actuelle.
L’en-tête Content-Range indique la plage d’octets du fichier complet représenté par cette demande.
Vérifiez la longueur totale du fichier avant de charger le premier fragment du fichier.

PUT https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337
Content-Length: 26
Content-Range: bytes 0-25/128

<bytes 0-25 of the file>

Important : votre application doit vérifier que la taille totale du fichier spécifié dans l’en-tête Content-Range est la même pour toutes les demandes. Si une plage d’octets déclare une taille de fichier différente, la demande échoue.

Réponse

Quand la demande est terminée, le serveur répond avec 202 Accepted si d’autres plages d’octets doivent être chargées.

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "expirationDateTime": "2015-01-29T09:21:55.523Z",
  "nextExpectedRanges": ["26-"]
}

Votre application peut utiliser la valeur nextExpectedRanges pour déterminer où commencer la plage d’octets suivante. Plusieurs plages peuvent être spécifiées, indiquant les parties du fichier que le serveur n’a pas encore reçues. Cette fonction est utile si vous avez besoin de reprendre un transfert qui a été interrompu et si votre client n’est pas sûr de l’état du service.

Nous vous conseillons de déterminer la taille de vos plages d’octets en respectant les pratiques indiquées ci-dessous. La valeur nextExpectedRanges ne renverra pas forcément des plages de taille correcte pour charger une plage d’octets. La propriété nextExpectedRanges indique les plages du fichier qui n’ont pas été reçues et qui ne doivent pas être respectées pendant le chargement du fichier.

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "expirationDateTime": "2015-01-29T09:21:55.523Z",
  "nextExpectedRanges": [
  "12345-55232",
  "77829-99375"
  ]
}

Remarques

La propriété nextExpectedRanges ne répertorie pas toujours toutes les plages manquantes.
En cas de réussite de l’écriture du fragment, elle renvoie la plage de départ suivante (ex. « 523- »).
En cas d’échec, lorsque le client a envoyé un fragment que le serveur avait déjà reçu, le serveur renvoie la réponse HTTP 416 Requested Range Not Satisfiable. Vous pouvez demander le statut de chargement pour obtenir une liste plus détaillée des plages manquantes.
Le fait d’inclure l’en-tête d’autorisation lors de l’appel PUT peut provoquer une réponse HTTP 401 Unauthorized. L’en-tête d’autorisation et le jeton du porteur doivent être envoyés uniquement lors de l’émission du POST pendant la première étape. Il ne doit pas être inclus lors de l’émission de l’appel PUT.

Finalisation d’un fichier

Quand le serveur reçoit la dernière plage d’octets du fichier, il renvoie la réponse HTTP 201 Created ou HTTP 200 OK. Le corps de la réponse inclut également le jeu de propriétés par défaut défini pour l’élément driveItem qui représente le fichier terminé.

PUT https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337
Content-Length: 21
Content-Range: bytes 101-127/128

<final bytes of the file>

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "912310013A123",
  "name": "largefile.vhd",
  "size": 128,
  "file": { }
}

Gestion des conflits de chargement

Si un conflit se produit pendant le chargement du fichier (par exemple, si un élément portant le même nom est créé pendant la session de chargement), une erreur est renvoyée pendant le chargement de la dernière plage d’octets.

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error":
  {
    "code": "upload_name_conflict",
    "message": "Another file exists with the same name as the uploaded session. You can redirect the upload session to use a new filename by calling PUT with the new metadata and @microsoft.graph.sourceUrl attribute.",
  }
}

Annuler la session de chargement

Pour annuler une session de chargement, envoyez une demande DELETE à l’URL de chargement. Cette opération supprime le fichier temporaire contenant les données précédemment chargées. Cette demande doit être utilisée en cas d’abandon du chargement, par exemple, si l’utilisateur annule le transfert.

Les fichiers temporaires et leur session de chargement associée sont automatiquement nettoyés lorsque la date expirationDateTime est expirée. Les fichiers temporaires peuvent ne pas être supprimés immédiatement après l’expiration du délai.

Demande

DELETE https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337

Réponse

L’exemple suivant illustre la réponse.

HTTP/1.1 204 No Content

Reprise d’un chargement en cours

Si une demande de chargement est déconnectée ou échoue avant la fin de la demande, tous les octets de cette demande sont ignorés. Cela peut se produire lors de l’interruption de la connexion entre votre application et le service. Dans ce cas, votre application peut toujours reprendre le transfert du fichier à partir du fragment précédemment chargé.

Pour savoir quelles plages d’octets ont été reçues, votre application peut demander l’état d’une session de chargement.

Exemple

Demandez l’état du chargement en envoyant une requête GET à l’élément uploadUrl.

GET https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF86633784148bb98a1zjcUhf7b0mpUadahs

Le serveur envoie la liste des plages d’octets manquantes qui doivent être chargées, ainsi que le délai d’expiration de la session de chargement.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "expirationDateTime": "2015-01-29T09:21:55.523Z",
  "nextExpectedRanges": ["12345-"]
}

Chargement des données restantes

Maintenant que votre application connaît le point de départ du chargement, reprenez le chargement en suivant les étapes de la section Chargement des octets vers la session de chargement.

Gestion des erreurs de chargement

Pendant le chargement de la dernière plage d’octets d’un fichier, une erreur peut se produire. Elle peut être causée par un conflit de noms ou par le dépassement d’une limite de quota. La session de chargement est conservée jusqu’à l’expiration du délai, ce qui permet à votre application de récupérer le chargement en validant explicitement la session de chargement.

Pour valider explicitement la session de chargement, votre application doit envoyer une demande PUT avec une nouvelle ressource driveItem qui sera utilisée pour valider la session. Cette nouvelle demande devrait corriger la source ayant généré l’erreur de chargement d’origine.

Pour indiquer que votre application valide une session de chargement existante, la demande PUT doit insérer la propriété @microsoft.graph.sourceUrl avec la valeur de l’URL de votre session de chargement.

PUT /me/drive/root:/{path_to_parent}
Content-Type: application/json
If-Match: {etag or ctag}

{
  "name": "largefile.vhd",
  "@microsoft.graph.conflictBehavior": "rename",
  "@microsoft.graph.sourceUrl": "{upload session URL}"
}

Remarque : vous pouvez utiliser les en-têtes @microsoft.graph.conflictBehavior et if-match attendus dans cet appel.

Réponse HTTP

Si le fichier peut être validé avec les nouvelles métadonnées, une réponse HTTP 201 Created ou HTTP 200 OK est renvoyée avec les métadonnées d’élément du fichier téléchargé.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "912310013A123",
  "name": "largefile.vhd",
  "size": 128,
  "file": { }
}

Meilleures pratiques

Reprenez ou réessayez les chargements qui ont échoué à cause d’interruptions de connexion ou d’erreurs 5xx, telles que :
- 500 Internal Server Error
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Utilisez une stratégie d’interruption exponentielle si des erreurs de serveur 5xx sont renvoyées lors de la reprise ou de la nouvelle tentative de demandes de chargement.
Si d’autres erreurs surviennent, n’utilisez pas de stratégie d’interruption exponentielle, mais limitez le nombre de nouvelles tentatives.
Gérez les erreurs 404 Not Found lors de la reprise de chargements en recommençant le chargement complet. Ce message indique que la session de chargement n’existe plus.
Utilisez des transferts de fichier pouvant être repris quand la taille des fichiers est supérieure à 10 Mio (10 485 760 octets).
Dans l’idéal, utilisez des plages d’octets dont la taille équivaut à 10 Mio pour les connexions stables à haut débit. Pour les connexions plus lentes ou moins fiables, vous pouvez obtenir de meilleurs résultats en utilisant des fragments moins volumineux. La taille de fragment recommandée se situe entre 5 et 10 MiB.
Utilisez une plage d’octets dont la taille est un multiple de 320 Kio (327 680 octets). Si vous ne parvenez pas à utiliser une taille de fragment qui est un multiple de 320 Kio, les transferts de fichiers volumineux risquent d’échouer après le chargement de la dernière plage d’octets.

Réponses d’erreur

Consultez la rubrique Réponses d’erreur pour plus de détails sur la façon dont les erreurs sont renvoyées.

Télécharger des fichiers volumineux à l’aide d’une session de chargement

Autorisations

Création d’une session de chargement

Requête HTTP

Corps de la demande

En-têtes de demande facultatifs

Propriétés

Demande

Réponse

Chargement des octets vers la session de chargement

Exemple

Réponse

Remarques

Finalisation d’un fichier

Gestion des conflits de chargement

Annuler la session de chargement

Demande

Réponse

Reprise d’un chargement en cours

Exemple

Chargement des données restantes

Gestion des erreurs de chargement

Réponse HTTP

Meilleures pratiques

Réponses d’erreur

Ressources supplémentaires