Joindre des fichiers à une tâche

À l’aide de l’API To Do dans Microsoft Graph, vous pouvez joindre des fichiers jusqu’à 25 Mo à un masque todoTask. Selon la taille du fichier, choisissez l’une des deux façons de joindre le fichier :

• Si la taille du fichier est comprise entre 3 Mo et 150 Mo, créez une session de téléchargement, puis utilisez PUT de manière itérative pour charger des plages d’octets du fichier jusqu’à ce que vous ayez téléchargé l’intégralité du fichier. Un en-tête dans la réponse finale réussie PUT contient une URL avec l’ID de la pièce jointe.
• Si la taille du fichier est inférieure à 3 Mo, faites un simple POSTsur la propriété de navigation des pièces jointes desTâches à faire; consultez comment faire cela pour une tâche. La réponse POST réussie inclut l’ID de la pièce jointe.

Cet article illustre la première approche. Vous allez apprendre étape par étape à créer et à utiliser une session de chargement pour ajouter une pièce jointe de fichier à une tâche.

Etape 1 : création d’une session de chargement

Créer une session de chargement pour joindre un fichier à Tâches à faire. Spécifier le fichier dans le paramètre d’entrée AttachmentItem.

Une opération réussie renvoie HTTP 201 Created et une nouvelle instance uploadSession qui contient une URL opaque que vous pouvez utiliser dans les opérations PUT suivantes pour charger des parties du fichier. La uploadSession crée un emplacement de stockage temporaire où les octets du fichier sont enregistrés jusqu’au chargement complet du fichier.

L’objet uploadSession dans la réponse inclut également la propriété nextExpectedRanges, qui indique que l’emplacement de départ du chargement initial doit être l’octet 0.

Autorisations

L’une des autorisations suivantes est nécessaire 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)	Tasks.ReadWrite
Déléguée (compte Microsoft personnel)	Tasks.ReadWrite
Application	Non prise en charge.

Exemple : créer une session de téléchargement pour un message

Demande

L’exemple suivant montre une demande de création d’une session de chargement.

HTTP

POST https://graph.microsoft.com/beta/me/todo/lists/AAMDiFkfh=/tasks/AAMkADliMm=/attachments/createUploadSession
Content-Type: application/json

{
  "attachmentInfo": {
    "attachmentType": "file",
    "name": "flower",
    "size": 3483322
  }
}

C#

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Beta.Me.Todo.Lists.Item.Tasks.Item.Attachments.CreateUploadSession;
using Microsoft.Graph.Beta.Models;

var requestBody = new CreateUploadSessionPostRequestBody
{
	AttachmentInfo = new AttachmentInfo
	{
		AttachmentType = AttachmentType.File,
		Name = "flower",
		Size = 3483322L,
	},
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Todo.Lists["{todoTaskList-id}"].Tasks["{todoTask-id}"].Attachments.CreateUploadSession.PostAsync(requestBody);

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta users todo lists tasks attachments create-upload-session post --user-id {user-id} --todo-task-list-id {todoTaskList-id} --todo-task-id {todoTask-id} --body '{\
  "attachmentInfo": {\
    "attachmentType": "file",\
    "name": "flower",\
    "size": 3483322\
  }\
}\
'

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Go

import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-beta-sdk-go/users"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestBody := graphusers.NewItemCreateUploadSessionPostRequestBody()
attachmentInfo := graphmodels.NewAttachmentInfo()
attachmentType := graphmodels.FILE_ATTACHMENTTYPE 
attachmentInfo.SetAttachmentType(&attachmentType) 
name := "flower"
attachmentInfo.SetName(&name) 
size := int64(3483322)
attachmentInfo.SetSize(&size) 
requestBody.SetAttachmentInfo(attachmentInfo)

createUploadSession, err := graphClient.Me().Todo().Lists().ByTodoTaskListId("todoTaskList-id").Tasks().ByTodoTaskId("todoTask-id").Attachments().CreateUploadSession().Post(context.Background(), requestBody, nil)

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

com.microsoft.graph.beta.users.item.todo.lists.item.tasks.item.attachments.createuploadsession.CreateUploadSessionPostRequestBody createUploadSessionPostRequestBody = new com.microsoft.graph.beta.users.item.todo.lists.item.tasks.item.attachments.createuploadsession.CreateUploadSessionPostRequestBody();
AttachmentInfo attachmentInfo = new AttachmentInfo();
attachmentInfo.setAttachmentType(AttachmentType.File);
attachmentInfo.setName("flower");
attachmentInfo.setSize(3483322L);
createUploadSessionPostRequestBody.setAttachmentInfo(attachmentInfo);
var result = graphClient.me().todo().lists().byTodoTaskListId("{todoTaskList-id}").tasks().byTodoTaskId("{todoTask-id}").attachments().createUploadSession().post(createUploadSessionPostRequestBody);

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const uploadSession = {
  attachmentInfo: {
    attachmentType: 'file',
    name: 'flower',
    size: 3483322
  }
};

await client.api('/me/todo/lists/AAMDiFkfh=/tasks/AAMkADliMm=/attachments/createUploadSession')
	.version('beta')
	.post(uploadSession);

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\CreateUploadSessionPostRequestBody;
use Microsoft\Graph\Generated\Models\AttachmentInfo;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new CreateUploadSessionPostRequestBody();
$attachmentInfo = new AttachmentInfo();
$attachmentInfo->setAttachmentType(new AttachmentType('file'));
$attachmentInfo->setName('flower');
$attachmentInfo->setSize(3483322);
$requestBody->setAttachmentInfo($attachmentInfo);

$result = $graphServiceClient->me()->todo()->lists()->byTodoTaskListId('todoTaskList-id')->tasks()->byTodoTaskId('todoTask-id')->attachments()->createUploadSession()->post($requestBody)->wait();

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

PowerShell

Import-Module Microsoft.Graph.Beta.Users.Actions

$params = @{
	attachmentInfo = @{
		attachmentType = "file"
		name = "flower"
		size = 3483322
	}
}

# A UPN can also be used as -UserId.
New-MgBetaUserTodoListTaskAttachmentUploadSession -UserId $userId -TodoTaskListId $todoTaskListId -TodoTaskId $todoTaskId -BodyParameter $params

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Python

from msgraph import GraphServiceClient
from msgraph.generated.models.create_upload_session_post_request_body import CreateUploadSessionPostRequestBody
from msgraph.generated.models.attachment_info import AttachmentInfo

graph_client = GraphServiceClient(credentials, scopes)

request_body = CreateUploadSessionPostRequestBody(
	attachment_info = AttachmentInfo(
		attachment_type = AttachmentType.File,
		name = "flower",
		size = 3483322,
	),
)

result = await graph_client.me.todo.lists.by_todo_task_list_id('todoTaskList-id').tasks.by_todo_task_id('todoTask-id').attachments.create_upload_session.post(request_body)

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Réponse

L’exemple suivant montre la ressource uploadSession retournée pour la tâche dans le corps de la réponse.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#microsoft.graph.uploadSession",
    "uploadUrl": "https://graph.microsoft.com/beta/users/6f9a2a92-8527-4d64-837e-b5312852f36d/todo/lists/AAMDiFkfh=/tasks/AAMkADliMm=/attachmentSessions/AAMkADliMm=",
    "expirationDateTime": "2022-06-09T10:45:27.4324526Z",
    "nextExpectedRanges": [
        "0-"
    ]
}

Étape 2 : utiliser la session de téléchargement pour charger une plage d’octets du fichier

Pour charger le fichier, ou une partie du fichier, ajoutez /content à l’URL retournée à l’étape 1 dans la propriété uploadUrl de la ressource uploadSession et effectuez une PUT requête sur l’URL ajoutée. Vous pouvez télécharger l’intégralité du fichier ou fractionner le fichier en plusieurs plages d’octets. Chaque plage d’octets doit être inférieure à 4 Mo.

Spécifiez les en-têtes de requête et le corps de la demande, comme décrit dans les sections suivantes.

En-têtes de demande

Nom	Type	Description
Autorisation	Chaîne	Porteur {token}. Obligatoire.
Content-Length	Int32	Nombre d’octets téléchargés dans cette opération. Pour de meilleures performances, limitez le nombre d’octets pour chaque opération PUT à 4 Mo. La demande échoue pour tout élément supérieur à 4 Mo. Obligatoire.
Content-Range	Chaîne	La plage d’octets basée sur 0 du fichier téléchargé pendant cette opération, exprimée dans le format bytes {start}-{end}/{total}. Obligatoire.
Content-Type	String	Le type MIME. Précisez application/octet-stream. Obligatoire.

Corps de la demande

Spécifiez les octets réels du fichier à joindre, qui se trouvent dans la plage d’emplacements spécifiée par l’en-tête de demande Content-Range.

Réponse

Un téléchargement réussi renvoie HTTP 200 OK et un objet uploadSession. Notez ce qui suit dans l’objet de réponse :

• La valeur de la propriété expirationDateTime reste la même que celle renvoyée par UploadSession initiale à l'étape 1.
• NextExpectedRanges spécifie l’emplacement d’octet suivant à partir duquel démarrer le chargement, par exemple, "nextExpectedRanges":["2097152"]. Vous devez charger les octets d’un fichier dans l’ordre.

• La propriété uploadUrl n’est pas explicitement renvoyée, car toutes les opérations PUT d’une session de téléchargement utilisent la même URL, renvoyée quand vous créez la session (étape 1).

Exemple : le premier chargement dans Tâches à faire

Demande

L’exemple suivant illustre une demande.

PUT https://graph.microsoft.com/beta/users/6f9a2a92-8527-4d64-837e-b5312852f36d/todo/lists/AAMDiFkfh=/tasks/AAMkADliMm=/attachmentSessions/AAMkADliMm=/content
Content-Type: application/octet-stream
Content-Length: 2097152
Content-Range: bytes 0-2097151/3483322

{
  <bytes 0-2097151 of the file to be attached, in binary format>
}

Réponse

L’exemple de réponse suivant illustre la propriété nextNextExpectedRanges le début de la plage d’octets suivante attendue par le serveur.

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

{
  "ExpirationDateTime":"2022-06-09T10:45:27.4324526Z",
  "NextExpectedRanges":["2097152"]
}

Étape 3 : continuer à télécharger des plages d’octets jusqu’à ce que le fichier entier ait été téléchargé

Suite au téléchargement initial à l’étape 2, continuez à charger la partie restante du fichier à l’aide d’une requête PUT similaire, comme décrit à l’étape 2, avant d’atteindre la date/heure d’expiration de la session. Utilisez la collection nextNextExpectedRanges pour déterminer où commencer la prochaine plage octets à télécharger. 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.

Une fois que le dernier octet du fichier a été téléchargé avec succès, PUTl'opération finale renvoie unHTTP 201 Created code de réponse et un Locationen-tête qui indique l'URL du fichier joint. Vous pouvez obtenir l’ID de la pièce jointe à partir de l’URL et l’enregistrer pour une utilisation ultérieure.

Les exemples suivants montrent comment télécharger la dernière plage d'octets du fichier vers Tâches à faire dans les étapes précédentes.

Exemple : le chargement final dans Tâches à faire

Demande

L’exemple suivant illustre une demande.

PUT https://graph.microsoft.com/beta/users/6f9a2a92-8527-4d64-837e-b5312852f36d/todo/lists/AAMDiFkfh=/tasks/AAMkADliMm=/attachmentSessions/AAMkADliMm=/content
Content-Type: application/octet-stream
Content-Length: 1386170
Content-Range: bytes 2097152-3483321/3483322

{
  <bytes 2097152-3483321 of the file to be attached, in binary format>
}

Réponse

Ce qui suit est un exemple de réponse qui montre un Location en-tête de réponse à partir duquel vous pouvez enregistrer l’ID pièce jointe (AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=) pour une utilisation ultérieure.

HTTP/1.1 201 Created

Location: https://graph.microsoft.com/beta/users/6f9a2a92-8527-4d64-837e-b5312852f36d/todo/lists/AAMDiFkfh=/tasks/AAMkADliMm=/Attachments/AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=
Content-Length: 0

Étapes alternative : annulation de la session de chargement

À tout moment avant l’expiration de la session de chargement, si vous devez annuler le chargement, vous pouvez utiliser la même URL qu’initialement pour supprimer la session de chargement. Une opération réussie retourne un code de réponse HTTP 204 No Content.

Exemple : annuler la session de chargement

Demande

L’exemple suivant illustre une demande.

DELETE https://graph.microsoft.com/beta/users/6f9a2a92-8527-4d64-837e-b5312852f36d/todo/lists/AAMDiFkfh=/tasks/AAMkADliMm=/attachmentSessions/AAMkADliMm=

Réponse

L’exemple suivant illustre la réponse.

HTTP/1.1 204 No content