To Do タスクにファイルを添付する

Microsoft Graph の To Do API を使用すると、最大 25 MB のファイルを todoTask に添付できます。 ファイルのサイズに応じて、次のいずれかの方法でファイルを添付します。

• 任意のサイズのファイルを添付するには、アップロード セッションを作成し、ファイル全体をアップロードするまで、PUT を繰り返し使用してファイルのバイト範囲をアップロードします。 最終的な成功PUT応答のヘッダーには、添付ファイル ID 付きの URL が含まれます。
• ファイル サイズが 3 MB未満の場合は、todoTask の 添付ファイル ナビゲーション プロパティで単一の POST を実行します。 タスクに対して実行する方法を参照してください。 成功した POST 応答には、添付ファイルの ID が含まれます。

この記事では、最初のアプローチについて説明します。 アップロード セッションを作成して使用して、添付ファイルをタスクに追加する方法について詳しく説明します。

手順 1: アップロード セッションを作成する

アップロード セッションを作成して、todoTask をファイルに添付します。 入力パラメーター attachmentInfo でファイルを指定します。

操作が成功すると、HTTP 201 Createdおよび新しい uploadSession インスタンスが返されます。このインスタンスには、後続のPUT操作でファイルの一部をアップロードするために使用できる不透明な URL が含まれます。 uploadSession は、ファイル全体をアップロードするまでファイルのバイトが保存される一時的な保存場所を提供します。

応答の uploadSession オブジェクトには nextExpectedRanges プロパティも含まれています。これは、最初のアップロード開始場所がバイト 0 であることを示します。

アクセス許可

この API を呼び出すには、次のいずれかのアクセス許可が必要です。 アクセス許可の選択方法などの詳細については、「アクセス許可」を参照してください。

アクセス許可の種類	アクセス許可 (特権の小さいものから大きいものへ)
委任 (職場または学校のアカウント)	Tasks.ReadWrite
委任 (個人用 Microsoft アカウント)	Tasks.ReadWrite
アプリケーション	サポートされていません。

例: todoTask のアップロード セッションを作成する

要求

次の例は、アップロード セッションを作成する要求を示しています。

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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

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)

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、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);

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、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);

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

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)

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

応答

次の例は、応答本文でタスクに対して返される uploadSession リソースを示しています。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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

手順 2: アップロード セッションを使用して、ファイルのバイトの範囲をアップロードします

ファイルまたはファイルの一部をアップロードするには、uploadSession リソースの uploadUrl プロパティの手順 1 で返された URL に/contentを追加し、追加された URL に対してPUT要求を行います。 ファイル全体をアップロードすることも、ファイルを複数のバイトの範囲に分割することもできます。 各バイト範囲は 4 MB 未満である必要があります。

次のセクションで説明するように、要求ヘッダーと要求本文を指定します。

要求ヘッダー

名前	種類	説明
Authorization	String	ベアラー {token}。 必須です。 認証と認可についての詳細をご覧ください。
コンテンツの長さ	Int32	この操作でアップロードされるバイト数です。 パフォーマンスを向上させるには、各 PUT 操作のバイト数の上限を 4 MB 以内に維持してください。 4 MB を超える場合、要求は失敗します。 必須です。
Content-Range	文字列	この操作でアップロードされるファイルの 0 ベースのバイトの範囲です。bytes {start}-{end}/{total}形式で表されます。 必須です。
Content-Type	文字列	MIME タイプ。 application/octet-streamを指定します。 必須です。

要求本文

添付するファイルの実際のバイトを指定します。これは、Content-Range要求ヘッダーで指定された場所の範囲内にあります。

応答

アップロードが成功すると、HTTP 200 OK 応答コードおよび uploadSession オブジェクトが返されます。 応答オブジェクトでは以下の点に注意してください。

• ExpirationDateTime プロパティの値は、手順 1 で最初の uploadSession によって返されたものと同じままです。
• nextExpectedRanges は、たとえば"nextExpectedRanges":["2097152"]からアップロードを開始する次のバイト位置を指定します。 ファイル内のバイトを順番にアップロードする必要があります。

• uploadUrl プロパティは明示的に返されません。これは、アップロード セッションのすべての PUT 操作が、セッションの作成時に返されたものと同じ URL を使用するためです (手順 1)。

例: 最初に todoTask にアップロードする

要求

次の例は要求を示しています。

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

応答

次の応答例では、nextExpectedRanges プロパティに関して、サーバーが想定する次のバイトの範囲の開始を示します。

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

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

手順 3: ファイル全体がアップロードされるまで、バイトの範囲のアップロードを続けます

手順 2 の最初のアップロードに続いて、セッションの有効期限の日付/時刻に達する前に、ステップ 2 で説明したものと同様のPUT要求を使用して、ファイルの残りの部分をアップロードし続けます。 nextExpectedRanges コレクションを使用して、アップロードする次のバイト範囲を開始する場所を決定します。 サーバーがまだ受信していないファイルの部分を示す、複数の指定範囲が表示されることがあります。 これは、中断された転送を再開する必要があり、クライアント側でサービスの状態が不明な場合に便利です。

ファイルの最後のバイトが正常にアップロードされると、最後の PUT 操作は HTTP 201 Created 応答コードとファイル添付ファイルへの URL を示す Location ヘッダーを返します。 URL から添付ファイル ID を取得し、後で使用するために保存できます。

次の例では、ファイルの最後のバイト範囲を、後続の手順で todoTask およびイベントにアップロードします。

例: 最後 にtodoTask にアップロードする

要求

次の例は要求を示しています。

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

応答

次の応答例では、後で使用するために添付ファイル ID (AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=) を保存できる Location 応答ヘッダーを示します。

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

代替手順: アップロード セッションをキャンセルする

アップロード セッションが期限切れになる前の任意の時点でアップロードをキャンセルする必要がある場合は、同じ初期 URL を使用してアップロード セッションを削除できます。 操作が成功すると、HTTP 204 No Content 応答コードが返されます。

例: メッセージのアップロード セッションをキャンセルする

要求

次の例は要求を示しています。

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

応答

次の例は応答を示しています。

HTTP/1.1 204 No content