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. Il permet également au transfert de reprendre si la 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. 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 la mise à jour de l’ID de l’élément.

Créer un fichier

POST /drives/{driveId}/items/{parentItemId}:/{fileName}:/createUploadSession
POST /groups/{groupId}/drive/items/{parentItemId}:/{fileName}:/createUploadSession
POST /me/drive/items/{parentItemId}:/{fileName}:/createUploadSession
POST /sites/{siteId}/drive/items/{parentItemId}:/{fileName}:/createUploadSession
POST /users/{userId}/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 /sites/{siteId}/drive/items/{itemId}/createUploadSession
POST /users/{userId}/drive/items/{itemId}/createUploadSession

En-têtes de demande

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", // only available for OneDrive (personal)
  "driveItemSource": { "@odata.type": "microsoft.graph.driveItemSource" },
  "fileSize": 1234, // only available for OneDrive (personal)
  "name": "filename.txt",
  "mediaSource": { "@odata.type": "microsoft.graph.mediaSource" }
}

L’exemple suivant contrôle le comportement lorsque le nom de fichier est déjà pris. Cet 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
}

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

Si elle réussit, la réponse à cette demande fournit les détails de l’emplacement où le reste des requêtes doit être envoyé en tant que ressource uploadSession .

Lorsqu’une session est créée et génère des URL de chargement pré-authentifiées, l’URL de chargement peut être utilisée pour terminer le chargement dans une fenêtre de temps suffisante pour les fichiers volumineux.

La ressource uploadSession fournit des détails sur l’emplacement où chaque plage d’octets du fichier doit être chargée et spécifie quand la session expire. La propriété expirationDateTime indique l’heure à laquelle la session en cours expire si aucune activité supplémentaire ne se produit. Cela entraîne le comportement suivant :

• Vous devez charger le fragment suivant ou valider la session avant l’heure spécifiée dans la propriété expirationDateTime .
• Chaque fragment chargé étend le délai d’expiration, ce qui permet aux chargements de fichiers volumineux de s’effectuer correctement. L’heure d’expiration mise à jour est retournée dans chaque demande de chargement d’un fragment de fichier.
• Si aucun fragment n’est reçu et que la session n’est pas validée, tous les fragments précédemment chargés sont ignorés.

Ce processus prend en charge les chargements de fichiers volumineux et garantit que les sessions de chargement sont gérées efficacement en empêchant les données obsolètes ou abandonnées de rester trop longtemps dans le système.

Si le fileSize paramètre est spécifié et dépasse le quota disponible, une 507 Insufficient 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’écriture de fragment réussie, il retourne la plage suivante à partir de laquelle commencer (par exemple, 523-).
• En cas d’échec où le client a envoyé un fragment que le serveur a déjà reçu, le serveur répond avec HTTP 416 Requested Range Not Satisfiable. Pour obtenir une liste plus détaillée des plages manquantes, vous pouvez demander le chargement status.
• 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. Incluez uniquement l’en-tête Authorization et le jeton du porteur lors de l’émission de la requête POST lors de la première étape. Ne l’incluez pas lors de l’émission de l’appel PUT.

Finalisation d’un fichier

Si deferCommit est ou n’est false pas défini, le chargement est automatiquement terminé lorsque la plage d’octets finale du fichier est PUT dans l’URL de chargement.

Si deferCommit a la valeurtrue, 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 la propriété par défaut définie 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": "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

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 effectuer une requête PUT avec une nouvelle ressource driveItem à utiliser lors de la validation de la session de chargement. 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 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 driveItem 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 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

Pour plus d’informations sur le retour des erreurs, voir Réponses aux erreurs.

Contenu connexe

Chargement de fichiers volumineux