driveItem : createUploadSession

Espace de noms: microsoft.graph

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 :

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

Cette API est disponible dans les déploiements de cloud national suivants.

Autorisations

Choisissez l’autorisation ou les autorisations marquées comme moins privilégiées pour cette API. Utilisez une autorisation ou des autorisations privilégiées plus élevées uniquement si votre application en a besoin. Pour plus d’informations sur les autorisations déléguées et d’application, consultez Types d’autorisations. Pour en savoir plus sur ces autorisations, consultez les informations de référence sur les autorisations.

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. 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. Vous pouvez également différer la création finale du fichier dans la destination jusqu’à ce que vous effectuiez explicitement une demande de chargement, en définissant la propriété deferCommit dans les arguments de la demande.

Requête HTTP

POST /drives/{driveId}/items/{itemId}/createUploadSession
POST /groups/{groupId}/drive/items/{itemId}/createUploadSession
POST /me/drive/items/{itemId}/createUploadSession
POST /me/drive/items/{itemId}:/{fileName}:/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 des propriétés dans le corps de la demande pour fournir des données supplémentaires sur le fichier chargé et la personnalisation de la sémantique de l’opération de chargement.

Par exemple, la propriété item permet de définir les paramètres suivants :

{
  "@microsoft.graph.conflictBehavior": "fail (default) | replace | rename",
  "description": "description",
  "driveItemSource": { "@odata.type": "microsoft.graph.driveItemSource" },
  "fileSize": 1234,
  "name": "filename.txt",
  "mediaSource": { "@odata.type": "microsoft.graph.mediaSource" }
}

L’exemple suivant contrôle le comportement si le nom de fichier est déjà pris et spécifie également que le fichier final ne doit pas être créé tant qu’une demande d’achèvement explicite n’est pas effectuée :

{
  "item": {
    "@microsoft.graph.conflictBehavior": "rename"
  },
  "deferCommit": true
}

En-têtes de demande facultatifs

Paramètres

Demande

La réponse à cette demande fournit les détails de la session uploadSession nouvellement créée, qui inclut l’URL utilisée pour charger les parties du fichier.

Remarque : le {item-path} doit contenir le nom de l’élément spécifié dans le corps de la demande.

POST /me/drive/items/{itemID}:/{item-path}:/createUploadSession
Content-Type: application/json

{
  "item": {
    "@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.

Si le fileSize paramètre est spécifié et dépasse le quota disponible, une 507 Insufficent Storage réponse est retournée et la session de chargement n’est pas créée.

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. Le chargement de fragments dans le désordre entraîne une erreur.

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). L’utilisation d’une taille de fragment qui ne divise pas uniformément par 320 Kio entraîne des erreurs de validation de certains fichiers.

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>

Réponse

Une fois la requête 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. Vous pouvez voir plusieurs plages spécifiées, indiquant des 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. Ne supposez pas que nextExpectedRanges retourne des plages de taille appropriée pour qu’une plage d’octets soit chargée. La propriété nextExpectedRanges indique les plages du fichier qui n’ont pas été reçues et non un modèle pour la façon dont votre application doit charger le 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 d’écritures de fragments réussies, elle retourne la plage suivante à partir de laquelle commencer (par exemple« 523- »).
• En cas d’échec lorsque le client a envoyé un fragment que le serveur avait déjà reçu, le serveur répond avec 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 .PUT

Finalisation d’un fichier

Si deferCommit est false ou non définie, le téléchargement est terminé automatiquement lorsque la plage d’octets finale du fichier est placée dans l’URL de téléchargement.

Si deferCommit est true, vous pouvez effectuer explicitement le chargement de deux manières :

• Une fois que la plage d’octets finale du fichier est placée dans l’URL de chargement, envoyez une demande de publication finale à l’URL de chargement avec du contenu de longueur nulle (actuellement uniquement pris en charge sur OneDrive Entreprise et SharePoint).
• Une fois la plage d’octets finale du fichier placée sur l’URL de chargement, envoyez une demande de placement finale de la même façon dont vous traiteriez les erreurs de chargement (actuellement uniquement pris en charge sur OneDrive Personnel).

Une fois le chargement terminé, le serveur répond à la requête finale avec un 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": { }
}

POST https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337
Content-Length: 0

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.",
  }
}

Annulation de 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 ne peuvent pas être supprimés immédiatement après l’expiration du délai d’expiration.

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 répond avec une liste des plages d’octets manquantes qui doivent être chargées et 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

Lorsque la dernière plage d’octets d’un fichier est chargée, il est possible qu’une erreur se produise. 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’heure d’expiration, ce qui permet à votre application de récupérer le chargement en commitant 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 https://graph.microsoft.com/beta/me/drive/root:/{path_to_file}
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

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.
• Pour les autres erreurs, vous ne devez pas utiliser une stratégie d’interruption exponentielle, mais limiter le nombre de nouvelles tentatives effectuées.
• 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.

Contenu connexe

Chargement de fichiers volumineux