driveItem : createUploadSession

  • Article

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. Les sessions de chargement permettent également au transfert de reprendre si une connexion est supprimée pendant que le chargement est en cours.

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.

Service global Gouvernement des États-Unis L4 Us Government L5 (DOD) Chine gérée par 21Vianet
✅ ✅ ✅ ✅

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.

Type d’autorisation Autorisations avec privilèges minimum Autorisations privilégiées plus élevées
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 Non disponible.

Création d’une session de chargement

Pour commencer à charger un fichier volumineux, votre application doit d’abord demander une nouvelle session de chargement. Cette requête crée un emplacement de stockage temporaire où les octets du fichier sont enregistrés jusqu’à ce que le fichier complet soit chargé. Lorsque le dernier octet du fichier est chargé, la session de chargement est terminée et le fichier final est affiché dans le dossier de destination. Vous pouvez également différer la création finale du fichier dans la destination jusqu’à ce que vous effectuez explicitement une demande pour terminer le chargement, en définissant la propriété deferCommit dans les arguments de la requête.

Requête HTTP

Pour charger un nouveau fichier, vous devez fournir à la fois l’ID parent et le nouveau nom de fichier dans la demande. Toutefois, une mise à jour nécessite uniquement l’ID de l’élément qui sera mis à jour.

Créer un fichier

POST /me/drive/items/{parentItemId}:/{fileName}:/createUploadSession

Mettre à jour un fichier existant

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

En-têtes de demande

Nom Valeur Description
if-match etag Si cet en-tête de requête est inclus et que l’eTag (ou cTag) fourni ne correspond pas à l’etag actuel sur l’élément, une 412 Precondition Failed réponse d’erreur est retournée.
if-none-match etag Si cet en-tête de requête est inclus et que l’eTag (ou cTag) fourni correspond à l’etag actuel sur l’élément, une 412 Precondition Failed réponse d’erreur est retournée.

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 plus d’informations sur le fichier en cours de chargement et personnaliser 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. L’exemple 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

Nom Valeur Description
if-match etag Si cet en-tête de requête est inclus et que l’eTag (ou cTag) fourni ne correspond pas à l’etag actuel sur l’élément, une 412 Precondition Failed réponse d’erreur est retournée.

Paramètres

Paramètre Type Description
deferCommit Booléen Si la truevaleur est définie sur , la création finale du fichier dans la destination nécessite une demande explicite.
item driveItemUploadableProperties Données relatives au fichier en cours de chargement

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>

Remarque

  • Pour charger des fichiers volumineux à l’aide de kits SDK, consultez Charger des fichiers volumineux à l’aide des sdk Microsoft Graph.
  • Votre application doit s’assurer que la taille totale du fichier spécifiée dans l’en-tête Content-Range est identique pour toutes les requêtes. Si une plage d’octets déclare une taille de fichier différente, la demande échoue.

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 nextExpectedRanges propriété 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.
  • Si vous incluez l’en-tête Authorization lors de l’émission de l’appel PUT , cela peut entraîner une HTTP 401 Unauthorized réponse. Envoyez uniquement l’en-tête d’autorisation et le jeton du porteur lors de l’émission de lors POST de la première étape. Ne l’incluez pas lorsque vous émettez l’appel 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>

Remarque

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

Remarque

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

Demande

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

Remarque

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.

Remarque

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/v1.0/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}"
}

Réponse

Si le fichier peut être commité à l’aide des nouvelles métadonnées, une HTTP 201 Created réponse ou HTTP 200 OK est retournée avec les métadonnées Item pour le fichier 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 à partir d’une taille de fragment plus petite. 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

Pour plus d’informations sur la façon dont les erreurs sont retournées, consultez l’article Réponses aux erreurs.

Contenu connexe

Chargement de fichiers volumineux