Outlook メッセージまたはイベントに大きいファイルを添付する

Microsoft Graph API を使用すると、最大 150 MB のファイルを Outlook メッセージまたはイベント アイテムに添付できます。 ファイルのサイズに応じて、次のいずれかの方法でファイルを添付します。

  • ファイル サイズが 3 MB 未満の場合、Outlook アイテムの 添付ファイル ナビゲーション プロパティで単一の投稿を実行できます。実行方法については、メッセージまたは イベントについての資料を参照してください。 成功した POST 応答には、添付ファイルの ID が含まれます。
  • ファイルサイズが 3MB から 150MB の場合、アップロード セッションを作成し、ファイル全体のアップロードが完了するまでPUTを繰り返し使用してファイルのバイトの範囲をアップロードします。 最終的な成功PUT応答のヘッダーには、添付ファイル ID 付きの URL が含まれます。

メッセージに複数のファイルを添付するには、ファイル サイズに基づいて各ファイルのアプローチを選択し、個別のファイルに添付します。

この記事では、2 番目のアプローチをステップごとに説明します。アップロード セッションを作成して使用し、サイズの大きな添付ファイル (3 MB 以上) を Outlook アイテムに追加します。 各ステップでは、メッセージおよびイベントの対応するコードを示します。 この記事では、ファイル全体を正常にアップロードすると、添付ファイルの ID を含む応答ヘッダーを取得し、その後に、添付ファイル ID を使用して未加工の添付ファイルのコンテンツまたは添付ファイルのメタデータを取得します。

重要

共有または委任されたメールボックスのメッセージまたはイベントに大容量ファイルを添付する場合は、「既知の問題」に注意してください。

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

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

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

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

アクセス許可

uploadSession (メッセージの場合)、および Calendars.ReadWrite (イベントの場合) を作成するために Mail.ReadWrite のアクセス許可を必ずリクエストしてください。

uploadUrl プロパティ (新しい uploadSession 内) で返される不透明な URL は事前に認証されており、後続のPUTクエリ (https://outlook.office.comドメイン内) 用の適切な認証トークンが含まれています。 そのトークンは expirationDateTime で期限切れになります。 PUT操作用にこの URL をカスタマイズしないでください。

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

要求

POST https://graph.microsoft.com/v1.0/me/messages/AAMkADI5MAAIT3drCAAA=/attachments/createUploadSession
Content-type: application/json

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

応答

次の応答例は、メッセージ用に返された uploadSession リソースを示しています。

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.uploadSession",
    "uploadUrl": "https://outlook.office.com/api/v2.0/Users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA=')/AttachmentSessions('AAMkADI5MAAIT3k0tAAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIUlN6bllHMmNI",
    "expirationDateTime": "2019-09-25T01:09:30.7671707Z",
    "nextExpectedRanges": [
        "0-"
    ]
}

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

要求

POST https://graph.microsoft.com/v1.0/me/events/AAMkADU5CCmSAAA=/attachments/createUploadSession
Content-type: application/json

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

応答

次の応答例は、イベント用に返された uploadSession リソースを示しています。

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.uploadSession",
    "uploadUrl": "https://outlook.office.com/api/v2.0/Users('d3b9214b-dd8b-441d-b7dc-c446c9fa0e69@98a79ebe-74bf-4e07-a017-7b410848cb32')/Events('AAMkADU5CCmSAAA=')/AttachmentSessions('AAMkADU5RpAACJlCs8AAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIBtw",
    "expirationDateTime": "2020-02-22T02:46:56.7410786Z",
    "nextExpectedRanges": [
        "0-"
    ]
}

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

ファイルまたはファイルの一部をアップロードするには、PUT リクエストを、uploadSession リソースの uploadUrl プロパティに関して手順 1 で返された URL に対して行います。 ファイル全体をアップロードすることも、ファイルを複数のバイトの範囲に分割することもできます。 パフォーマンスを向上させるには、各バイトの範囲を 4 MB 未満にしてください。

以下に説明するように、要求ヘッダーとリクエストの本文を指定します。

要求ヘッダー

名前 説明
コンテンツの長さ Int32 この操作でアップロードされるバイト数です。 パフォーマンスを向上させるには、各PUT操作のバイト数の上限を 4 MB 以内に維持してください。 必須です。
Content-Range 文字列 この操作でアップロードされるファイルの 0 ベースのバイトの範囲です。bytes {start}-{end}/{total}形式で表されます。 必須です。
Content-Type 文字列 MIME タイプ。 application/octet-streamを指定します。 必須です。

Authorizationリクエスト ヘッダーを指定しないでください。 PUTクエリは、uploadUrl プロパティから事前認証された URL を使用します。このプロパティはhttps://outlook.office.comドメインへのアクセスを許可します。

要求本文

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

応答

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

  • ExpirationDateTime プロパティは、uploadUrl プロパティ値に埋め込まれた認証トークンの有効期限を示します。 この有効期限の日付/時刻は、手順 1 で最初の uploadSession によって返されたものと同じです。
  • NextExpectedRanges は、たとえば"NextExpectedRanges":["2097152"]からアップロードを開始する次のバイト位置を指定します。 ファイル内のバイトを順番にアップロードする必要があります。
  • uploadUrl プロパティは明示的に返されません。これは、アップロード セッションのすべてのPUT操作が、セッションの作成時に返されたものと同じ URL を使用するためです (手順 1)。

例: 最初にメッセージにアップロードする

要求

PUT https://outlook.office.com/api/v2.0/Users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA=')/AttachmentSessions('AAMkADI5MAAIT3k0tAAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIUlN6bllHMmNI
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

{
  "@odata.context":"https://outlook.office.com/api/v2.0/$metadata#Users('a8e8e219-4931-95c1-b73d-62626fd79c32%4072aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA%3D')/AttachmentSessions/$entity",
  "ExpirationDateTime":"2019-09-25T01:09:30.7671707Z",
  "NextExpectedRanges":["2097152"]
}

例: 最初にイベントにアップロードする

要求

PUT https://outlook.office.com/api/v2.0/Users('d3b9214b-dd8b-441d-b7dc-c446c9fa0e69@98a79ebe-74bf-4e07-a017-7b410848cb32')/Events('AAMkADU5CCmSAAA=')/AttachmentSessions('AAMkADU5RpAACJlCs8AAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIBtw
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

{
    "@odata.context":"https://outlook.office.com/api/v2.0/$metadata#Users('d3b9214b-dd8b-441d-b7dc-c446c9fa0e69%4098a79ebe-74bf-4e07-a017-7b410848cb32')/Events('AAMkADU5CCmSAAA%3D')/AttachmentSessions/$entity",
    "ExpirationDateTime":"2020-02-22T02:46:56.7410786Z",
    "NextExpectedRanges":["2097152"]
}

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

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

ファイルの最後のバイトが正常にアップロードされると、最終的なPUT操作はHTTP 201 CreatedおよびLocationヘッダーを返します。このヘッダーは、https://outlook.office.comドメイン内の添付ファイルへの URL を示します。 URL から添付ファイル ID を取得し、後で使用するために保存できます。 シナリオに応じて、その ID を使用して添付ファイルのメタデータを取得したり、Microsoft Graph エンドポイントを使用して Outlook アイテムから添付ファイルを削除したりすることができます。

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

例: 最後にメッセージにアップロードする

要求

PUT https://outlook.office.com/api/v2.0/Users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA=')/AttachmentSessions('AAMkADI5MAAIT3k0tAAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIUlN6bllHMmNI
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://outlook.office.com/api/v2.0/Users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA=')/Attachments('AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=')
Content-Length: 0

例: 最後にイベントにアップロードする

要求

PUT https://outlook.office.com/api/v2.0/Users('d3b9214b-dd8b-441d-b7dc-c446c9fa0e69@98a79ebe-74bf-4e07-a017-7b410848cb32')/Events('AAMkADU5CCmSAAA=')/AttachmentSessions('AAMkADU5RpAACJlCs8AAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIBtw
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 (AAMkADU5CCmSAAANZAlYPeyQByv7Y=) を保存できる Location 応答ヘッダーを示します。

HTTP/1.1 201 Created

Location: https://outlook.office.com/api/v2.0/Users('d3b9214b-dd8b-441d-b7dc-c446c9fa0e69@98a79ebe-74bf-4e07-a017-7b410848cb32')/Events('AAMkADU5CCmSAAA=')/Attachments('AAMkADU5CCmSAAANZAlYPeyQByv7Y=')
Content-Length: 0

手順 4 (オプション): Outlook アイテムから添付ファイルを取得する

通常のように、Outlook アイテムから添付ファイルを取得することは、添付ファイルのサイズによって技術的に制限されません。

ただし、base64 エンコード形式の大きな添付ファイルを取得すると、API のパフォーマンスに影響します。 大きな添付ファイルが予期される場合:

例: イベントに対する未加工の添付ファイルを取得する

このセクションの要求例では、以下のイベント例に従い、前の手順の Location ヘッダーで返された添付ファイル ID を使用して、$value パラメーターを指定して添付ファイルの未加工のコンテンツ データを取得します。

アクセス許可

この操作には、必要に応じて、最も特権の少ない委任またはアプリケーションのアクセス許可 Calendars.Read を使用します。 詳細については、「予定表のアクセス許可」を参照してください。

要求

GET https://graph.microsoft.com/v1.0/Users('d3b9214b-dd8b-441d-b7dc-c446c9fa0e69@98a79ebe-74bf-4e07-a017-7b410848cb32')/Events('AAMkADU5CCmSAAA=')/Attachments('AAMkADU5CCmSAAANZAlYPeyQByv7Y=')/$value

応答

HTTP/1.1 200 OK
content-length: 3483322
Content-type: image/jpeg

{Raw bytes of the file}

例: メッセージに添付されたファイルのメタデータを取得する

このセクションの要求例では、メッセージ例に従い、$select パラメーターを使用して、contentBytes 以外のメッセージの添付ファイルのメタデータを取得します。

アクセス許可

この操作には、必要に応じて、最も特権の少ない委任またはアプリケーションのアクセス許可 Mail.Read を使用します。 詳細については、「メールのアクセス許可」を参照してください。

要求

GET https://graph.microsoft.com/api/v1.0/Users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA=')/Attachments('AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=')?$select=lastModifiedDateTime,name,contentType,size,isInline

応答

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('a8e8e219-4931-95c1-b73d-62626fd79c32%4072aa88bf-76f0-494f-91ab-2d7cd730db47')/messages('AAMkADI5MAAIT3drCAAA%3D')/attachments/$entity",
    "@odata.type": "#microsoft.graph.fileAttachment",
    "@odata.mediaContentType": "image/jpeg",
    "id": "AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=",
    "lastModifiedDateTime": "2019-09-24T23:27:43Z",
    "name": "flower",
    "contentType": "image/jpeg",
    "size": 3640066,
    "isInline": false
}

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

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

アクセス許可

最初の不透明な URL は事前認証されており、そのアップロード セッションの後続のクエリに適切な承認トークンが含まれているため、この操作の承認リクエスト ヘッダーを指定しないでください。

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

要求

DELETE https://outlook.office.com/api/v2.0/Users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA=')/AttachmentSessions('AAMkADI5MAAIT3k0tAAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIUlN6bllHMmNI

応答

HTTP/1.1 204 No content

エラー

ErrorAttachmentSizeShouldNotBeLessThanMinimumSize

このエラーは、アップロード セッションを作成して 3 MB 未満のファイルを添付しようとすると返されます。 ファイル サイズが 3 MB 未満の場合、メッセージまたは イベント添付ファイル ナビゲーション プロパティで単一の投稿を実行する必要があります。 成功したPOST応答には、メッセージに添付されたファイルの ID が含まれます。