Anfügen von Dateien an eine To Do-Aufgabe

Mithilfe der To-Do-API in Microsoft Graph können Sie Dateien mit bis zu 25 MB an ein todoTask-Objekt anfügen. Abhängig von der Dateigröße wählen Sie eine von zwei Optionen zum Anfügen der Datei aus:

• Um Dateien beliebiger Größe anzuhängen, erstellen Sie eine Upload-Sitzung und verwenden Sie PUT, um iterativ Byte-Bereiche der Datei hochzuladen, bis Sie die gesamte Datei hochgeladen haben. Eine Kopfzeile in der endgültigen erfolgreichen PUT-Antwort enthält eine URL mit der Anlagen-ID.
• Wenn die Dateigröße unter 3 MB liegt, führen Sie eine einzelnePOST Aktion über die Navigationseigenschaft Anhänge einer todoTask durch. Hier finden Sie entsprechende Informationen für eine Aufgabe. Die erfolgreiche POST-Antwort enthält die ID der Dateianlage.

In diesem Artikel wird der erste Ansatz veranschaulicht. Sie erfahren Schritt für Schritt, wie Sie eine Upload-Sitzung erstellen und verwenden, um einer Aufgabe eine Dateianlage hinzuzufügen.

Schritt 1: Erstellen einer Uploadsitzung

Erstellen Sie eine Upload-Sitzung, um eine Datei an eine todoTaskanzufügen. Geben Sie die Datei im attachmentInfo-Eingabeparameter an.

Ein erfolgreicher Vorgang gibt HTTP 201 Created und eine neue uploadSession-Instanz zurück, die eine opake URL enthält, die Sie in nachfolgenden PUT-Vorgängen zum Hochladen von Teilen der Datei verwenden können. Die uploadSession bietet einen temporären Speicherort, an dem die Bytes der Datei gespeichert werden, bis der Upload vollständig abgeschlossen ist.

Das uploadSession-Objekt in der Antwort enthält außerdem die nextExpectedRanges-Eigenschaft, die angibt, dass der Startspeicherort des anfänglichen Uploads Byte 0 sein sollte.

Berechtigungen

Eine der nachfolgenden Berechtigungen ist erforderlich, um diese API aufrufen zu können. Weitere Informationen, unter anderem zur Auswahl von Berechtigungen, finden Sie unter Berechtigungen.

Berechtigungstyp	Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)
Delegiert (Geschäfts-, Schul- oder Unikonto)	Tasks.ReadWrite
Delegiert (persönliches Microsoft-Konto)	Tasks.ReadWrite
Anwendung	Nicht unterstützt

Beispiel: Upload-Sitzung für ein „todoTask“ erstellen

Anforderung

Das folgende Beispiel zeigt eine Anforderung zum Erstellen einer Uploadsitzung.

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);

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

CLI

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\
  }\
}\
'

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

Go

// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
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
)

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)

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
createUploadSession, err := graphClient.Me().Todo().Lists().ByTodoTaskListId("todoTaskList-id").Tasks().ByTodoTaskId("todoTask-id").Attachments().CreateUploadSession().Post(context.Background(), requestBody, nil)

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

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);

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

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);

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

PHP

<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Users\Item\Todo\Lists\Item\Tasks\Item\Attachments\CreateUploadSession\CreateUploadSessionPostRequestBody;
use Microsoft\Graph\Beta\Generated\Models\AttachmentInfo;
use Microsoft\Graph\Beta\Generated\Models\AttachmentType;


$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();

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

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

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.users.item.todo.lists.item.tasks.item.attachments.create_upload_session.create_upload_session_post_request_body import CreateUploadSessionPostRequestBody
from msgraph_beta.generated.models.attachment_info import AttachmentInfo
from msgraph_beta.generated.models.attachment_type import AttachmentType
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
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)

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

Antwort

Das folgende Beispiel zeigt die uploadSession-Ressource, die für die Aufgabe im Antwortkörper zurückgegeben wird.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

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-"
    ]
}

Schritt 2: Verwenden der Upload-Sitzung zum Hochladen eines Bytebereichs der Datei

Um die Datei oder einen Teil der Datei hochzuladen, fügen Sie /content an die URL an, die in Schritt 1 in der uploadUrl-Eigenschaft der uploadSession-Ressource zurückgegeben wurde, und stellen Sie eine PUT Anforderung für die angefügte URL. Sie können die gesamte Datei auf einmal hochladen oder die Datei in mehrere Bytebereiche aufteilen. Jeder Bytebereich muss kleiner als 4 MB sein.

Geben Sie die Anforderungsheader und den Anforderungstext an, wie in den folgenden Abschnitten beschrieben.

Anforderungsheader

Name	Typ	Beschreibung
Authorization	Zeichenfolge	Bearer {token}. Erforderlich. Erfahren Sie mehr über die Authentifizierung und Autorisierung.
Content-Length	Int32	Die Anzahl von Bytes, die in diesem Vorgang hochgeladen werden. Die Obergrenze für die Anzahl der Bytes für jeden PUTVorgang beträgt 4 MB. Die Anforderung schlägt bei mehr als 4 MB fehl. Erforderlich.
Content-Range	Zeichenfolge	Der 0-basierte Byte-Bereich der Datei, die in diesem Vorgang hochgeladen wird. Wird im Format bytes {start}-{end}/{total} angegeben. Erforderlich.
Content-Type	Zeichenfolge	Der MIME-Typ. application/octet-stream angeben. Erforderlich.

Anforderungstext

Geben Sie die tatsächlichen Bytes der anzufügenden Datei an, die sich im im Content-Range-Anforderungsheader angegebenen Speicherbereich befinden.

Antwort

Bei einem erfolgreichen Upload wird ein HTTP 200 OKAntwortcode und ein uploadSession-Objekt zurückgegeben. Beachten Sie Folgendes im Antwortobjekt:

• Der expirationDateTime-Eigenschaftswert bleibt unverändert gegenüber dem vom anfänglichen uploadSession in Schritt 1 zurückgegebenen.
• In NextExpectedRanges wird der nächste Byte-Speicherort angegeben, aus dem der Upload gestartet werden soll, z. B. "nextExpectedRanges":["2097152"]. Sie müssen die Bytes einer Datei in der korrekten Reihenfolge hochladen.

• Die uploadUrl-Eigenschaft wird nicht explizit zurückgegeben, da alle PUTVorgänge einer Upload-Sitzung die gleiche URL verwenden, die beim Erstellen der Sitzung zurückgegeben wird (Schritt 1).

Beispiel: Erster Upload in die „todoTask“

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

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>
}

Antwort

Es folgt ein Beispiel für eine Antwort, die in der Eigenschaft nextExpectedRanges den Beginn des nächsten vom Server erwarteten Bytebereichs anzeigt.

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

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

Schritt 3: Fortsetzen des Hochladens von Bytebereichen, bis die gesamte Datei hochgeladen wurde

Fahren Sie nach dem ersten Upload, der in Schritt 2 beschrieben wurde, mit dem Hochladen der verbleibenden Teile der Datei fort, indem Sie eine ähnliche PUT-Anforderung wie in Schritt 2 beschrieben verwenden, bevor Sie den Ablauftermin für die Sitzung erreichen. Verwenden Sie die Sammlung NextExpectedRanges, um zu bestimmen, wo der nächste Bytebereich für den Upload beginnen soll. Eventuell werden mehrere Bereiche angegeben. Sie stehen für Teile der Datei, die der Server noch nicht empfangen hat. Dies ist nützlich, wenn eine Übertragung nach einer Unterbrechung fortgesetzt werden soll und der Client den Dienststatus nicht kennt.

Nachdem das letzte Byte der Datei erfolgreich hochgeladen wurde, gibt der endgültige PUTVorgang einen HTTP 201 CreatedAntwortcode und einen LocationHeader zurück, der die URL der Dateianlage angibt. Sie können die Anlagen-ID aus der URL abrufen und zur späteren Verwendung speichern.

Die folgenden Beispiele zeigen, wie in den vorangegangenen Schritten der letzte Bytebereich der Datei in die todoTask hochgeladen wird.

Beispiel: Abschließender Upload in die „todoTask“

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

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>
}

Antwort

Die folgende Beispielantwort zeigt einen LocationAntwortheader, von dem aus Sie die Anlagen-ID (AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=) zur späteren Verwendung speichern können.

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

Alternativer Schritt: Abbrechen der Upload-Sitzung

Wenn Sie zu einem beliebigen Zeitpunkt vor Ablauf der Upload-Sitzung den Upload abbrechen müssen, können Sie dieselbe ursprüngliche URL verwenden, um die Upload-Sitzung zu löschen. Bei einem erfolgreichen Vorgang wird ein HTTP-204 No Content Antwortcode zurückgegeben.

Beispiel: Abbrechen der Uploadsitzung

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

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

Antwort

Das folgende Beispiel zeigt die Antwort.

HTTP/1.1 204 No content