Outlook メッセージまたはイベントに大きいファイルを添付するAttach large files to Outlook messages or events

Microsoft Graph API を使用すると、最大 150 MB のファイルを Outlook メッセージまたはイベント アイテムに添付できます。Using the Microsoft Graph API, you can attach files up to 150 MB to an Outlook message or event item. ファイルのサイズに応じて、次のいずれかの方法でファイルを添付します。Depending on the file size, choose one of two ways to attach the file:

  • ファイル サイズが 3 MB 未満の場合、Outlook アイテムの添付ファイル ナビゲーション プロパティで単一の投稿を実行できます。実行方法については、メッセージまたはイベントについての資料を参照してください。If the file size is under 3 MB, do a single POST on the attachments navigation property of the Outlook item; see how to do this for a message or for an event. 成功した POST 応答には、添付ファイルの ID が含まれます。The successful POST response includes the ID of the file attachment.
  • ファイルサイズが 3MB から 150MB の場合、アップロード セッションを作成し、ファイル全体のアップロードが完了するまでPUTを繰り返し使用してファイルのバイトの範囲をアップロードします。If the file size is between 3MB and 150MB, create an upload session, and iteratively use PUT to upload ranges of bytes of the file until you have uploaded the entire file. 最終的な成功PUT応答のヘッダーには、添付ファイル ID 付きの URL が含まれます。A header in the final successful PUT response includes a URL with the attachment ID.

メッセージに複数のファイルを添付するには、ファイル サイズに基づいて各ファイルのアプローチを選択し、個別のファイルに添付します。To attach multiple files to a message, choose the approach for each file based on its file size and attach the files individually.

この記事では、2 番目のアプローチをステップごとに説明します。アップロード セッションを作成して使用し、サイズの大きな添付ファイル (3 MB 以上) を Outlook アイテムに追加します。This article illustrates the second approach step by step, creating and using an upload session to add a large file attachment (of size over 3MB) to an Outlook item. 各ステップでは、メッセージおよびイベントの対応するコードを示します。Each step shows the corresponding code for a message and for an event. この記事では、ファイル全体を正常にアップロードすると、添付ファイルの ID を含む応答ヘッダーを取得し、その後に、添付ファイル ID を使用して未加工の添付ファイルのコンテンツまたは添付ファイルのメタデータを取得します。Upon successfully uploading the entire file, the article shows getting a response header that contains an ID for the file attachment, and then using that attachment ID to get the raw attachment content or attachment metadata.

重要

共有または委任されたメールボックスのメッセージまたはイベントに大容量ファイルを添付する場合は、「既知の問題」に注意してください。Be aware of a known issue if you're attaching large files to a message or event in a shared or delegated mailbox.

手順 1: アップロード セッションを作成するStep 1: Create an upload session

アップロード セッションを作成して、ファイルをメッセージまたはイベントに添付します。Create an upload session to attach a file to a message or event. 入力パラメーター AttachmentItem でファイルを指定します。Specify the file in the input parameter AttachmentItem.

操作が成功すると、HTTP 201 Createdおよび新しい uploadSession インスタンスが返されます。このインスタンスには、後続のPUT操作でファイルの一部をアップロードするために使用できる不透明な URL が含まれます。A successful operation returns HTTP 201 Created and a new uploadSession instance, which contains an opaque URL that you can use in subsequent PUT operations to upload portions of the file. uploadSession は、ファイル全体をアップロードするまでファイルのバイトが保存される一時的な保存場所を提供します。The uploadSession provides a temporary storage location where the bytes of the file are saved until you have uploaded the complete file.

uploadSession (メッセージの場合)、および Calendars.ReadWrite (イベントの場合) を作成するために Mail.ReadWrite のアクセス許可を必ずリクエストしてください。Make sure to request Mail.ReadWrite permission to create the uploadSession for a message, and Calendars.ReadWrite for an event. uploadUrl プロパティ (新しい uploadSession 内) で返される不透明な URL は事前に認証されており、後続のPUTクエリ (https://outlook.office.comドメイン内) 用の適切な認証トークンが含まれています。The opaque URL, returned in the uploadUrl property of the new uploadSession, is pre-authenticated and contains the appropriate authorization token for subsequent PUT queries in the https://outlook.office.com domain. そのトークンは expirationDateTime で期限切れになります。That token expires by expirationDateTime. PUT操作用にこの URL をカスタマイズしないでください。Do not customize this URL for the PUT operations.

応答の uploadSession オブジェクトには nextExpectedRanges プロパティも含まれています。これは、最初のアップロード開始場所がバイト 0 であることを示します。The uploadSession object in the response also includes the nextExpectedRanges property, which indicates the initial upload starting location should be byte 0.

例: メッセージのアップロード セッションを作成するExample: create an upload session for a message

要求Request

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

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

応答Response

次の応答例は、メッセージ用に返された uploadSession リソースを示しています。The following example response shows the uploadSession resource returned for the message.

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

例: イベントのアップロード セッションを作成するExample: create an upload session for an event

要求Request

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

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

応答Response

次の応答例は、イベント用に返された uploadSession リソースを示しています。The following example response shows the uploadSession resource returned for the event.

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: アップロード セッションを使用して、ファイルのバイトの範囲をアップロードしますStep 2: Use the upload session to upload a range of bytes of the file

ファイルまたはファイルの一部をアップロードするには、PUT リクエストを、uploadSession リソースの uploadUrl プロパティに関して手順 1 で返された URL に対して行います。To upload the file, or a portion of the file, make a PUT request to the URL returned in step 1 in the uploadUrl property of the uploadSession resource. ファイル全体をアップロードすることも、ファイルを複数のバイトの範囲に分割することもできます。You can upload the entire file, or split the file into multiple byte ranges. パフォーマンスを向上させるには、各バイトの範囲を 4 MB 未満にしてください。For better performance, keep each byte range less than 4 MB.

以下に説明するように、要求ヘッダーとリクエストの本文を指定します。Specify request headers and request body as described below.

要求ヘッダーRequest headers

名前Name 種類Type 説明Description
コンテンツの長さContent-Length Int32Int32 この操作でアップロードされるバイト数です。The number of bytes being uploaded in this operation. パフォーマンスを向上させるには、各PUT操作のバイト数の上限を 4 MB 以内に維持してください。For better performance, keep the upper limit of the number of bytes for each PUT operation to 4 MB. 必須です。Required.
Content-RangeContent-Range 文字列String この操作でアップロードされるファイルの 0 ベースのバイトの範囲です。bytes {start}-{end}/{total}形式で表されます。The 0-based byte range of the file being uploaded in this operation, expressed in the format bytes {start}-{end}/{total}. 必須です。Required.
Content-TypeContent-Type 文字列String MIME タイプ。The MIME type. application/octet-streamを指定します。Specify application/octet-stream. 必須です。Required.

Authorizationリクエスト ヘッダーを指定しないでください。Do not specify an Authorization request header. PUTクエリは、uploadUrl プロパティから事前認証された URL を使用します。このプロパティはhttps://outlook.office.comドメインへのアクセスを許可します。The PUT query uses a pre-authenticated URL from the uploadUrl property, that allows access to the https://outlook.office.com domain.

要求本文Request body

添付するファイルの実際のバイトを指定します。これは、Content-Range要求ヘッダーで指定された場所の範囲内にあります。Specify the actual bytes of the file to be attached, that are in the location range specified by the Content-Range request header.

応答Response

アップロードが成功すると、HTTP 200 OKおよび uploadSession オブジェクトが返されます。A successful upload returns HTTP 200 OK and an uploadSession object. 応答オブジェクトでは以下の点に注意してください。Note the following in the response object:

  • ExpirationDateTime プロパティは、uploadUrl プロパティ値に埋め込まれた認証トークンの有効期限を示します。The ExpirationDateTime property indicates the expiration date/time for the auth token embedded in the uploadUrl property value. この有効期限の日付/時刻は、手順 1 で最初の uploadSession によって返されたものと同じです。This expiration date/time remains the same as returned by the initial uploadSession in step 1.
  • NextExpectedRanges は、たとえば"NextExpectedRanges":["2097152"]からアップロードを開始する次のバイト位置を指定します。The NextExpectedRanges specifies the next byte location to start uploading from, for example, "NextExpectedRanges":["2097152"]. ファイル内のバイトを順番にアップロードする必要があります。You must upload bytes in a file in order.
  • uploadUrl プロパティは明示的に返されません。これは、アップロード セッションのすべてのPUT操作が、セッションの作成時に返されたものと同じ URL を使用するためです (手順 1)。The uploadUrl property is not explicitly returned, because all PUT operations of an upload session use the same URL returned when creating the session (step 1).

例: 最初にメッセージにアップロードするExample: first upload to the message

要求Request

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

応答Response

次の応答例では、NextExpectedRanges プロパティに関して、サーバーが想定する次のバイトの範囲の開始を示します。The following example response shows in the NextExpectedRanges property the start of the next byte range that the server expects.

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

例: 最初にイベントにアップロードするExample: first upload to the event

要求Request

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

応答Response

次の応答例では、NextExpectedRanges プロパティに関して、サーバーが想定する次のバイトの範囲の開始を示します。The following example response shows in the NextExpectedRanges property the start of the next byte range that the server expects.

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: ファイル全体がアップロードされるまで、バイトの範囲のアップロードを続けますStep 3: Continue uploading byte ranges until the entire file has been uploaded

手順 2 の最初のアップロードに続いて、セッションの有効期限の日付/時刻に達する前に、ステップ 2 で説明したものと同様のPUT要求を使用して、ファイルの残りの部分をアップロードし続けます。Following the initial upload in step 2, continue to upload the remaining portion of the file, using a similar PUT request as described in step 2, before you reach the expiration date/time for the session. NextExpectedRanges コレクションを使用して、アップロードする次のバイトの範囲の開始位置を決定します。Use the NextExpectedRanges collection to determine where to start the next byte range to upload. サーバーがまだ受信していないファイルの部分を示す、複数の指定範囲が表示されることがあります。You may see multiple ranges specified, indicating parts of the file that the server has not yet received. これは、中断された転送を再開する必要があり、クライアント側でサービスの状態が不明な場合に便利です。This is useful if you need to resume a transfer that was interrupted and your client is unsure of the state on the service.

ファイルの最後のバイトが正常にアップロードされると、最終的なPUT操作はHTTP 201 CreatedおよびLocationヘッダーを返します。このヘッダーは、https://outlook.office.comドメイン内の添付ファイルへの URL を示します。Once the last byte of the file has been successfully uploaded, the final PUT operation returns HTTP 201 Created and a Location header that indicates the URL to the file attachment in the https://outlook.office.com domain. URL から添付ファイル ID を取得し、後で使用するために保存できます。You can get the attachment ID from the URL and save it for later use. シナリオに応じて、その ID を使用して添付ファイルのメタデータを取得したり、Microsoft Graph エンドポイントを使用して Outlook アイテムから添付ファイルを削除したりすることができます。Depending on your scenario, you can use that ID to get the metadata of the attachment, or remove the attachment from the Outlook item using the Microsoft Graph endpoint.

次の例では、ファイルの最後のバイト範囲を、後続の手順でメッセージおよびイベントにアップロードします。The following examples show uploading the last byte range of the file to the message and to the event in the preceding steps.

例: 最後にメッセージにアップロードするExample: final upload to the message

要求Request

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

応答Response

次の応答例では、後で使用するために添付ファイル ID (AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=) を保存できる Location 応答ヘッダーを示します。The following example response shows a Location response header from which you can save the attachment ID (AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=) for later use.

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

例: 最後にイベントにアップロードするExample: final upload to the event

要求Request

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

応答Response

次の応答例では、後で使用するために添付ファイル ID (AAMkADU5CCmSAAANZAlYPeyQByv7Y=) を保存できる Location 応答ヘッダーを示します。The following example response shows a Location response header from which you can save the attachment ID (AAMkADU5CCmSAAANZAlYPeyQByv7Y=) for later use.

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 アイテムから添付ファイルを取得するStep 4 (optional): Get the file attachment from the Outlook item

通常のように、Outlook アイテムから添付ファイルを取得することは、添付ファイルのサイズによって技術的に制限されません。As always, getting an attachment from an Outlook item is not technically limited by attachment size.

ただし、base64 エンコード形式の大きな添付ファイルを取得すると、API のパフォーマンスに影響します。However, getting a large file attachment in base64-encoded format affects API performance. 大きな添付ファイルが予期される場合:If you expect a large attachment:

例: イベントに対する未加工の添付ファイルを取得するExample: Get the raw file attached to the event

次の要求例では、以下のイベント例に従い、前の手順の Location ヘッダーで返された添付ファイル ID を使用して、$value パラメーターを指定して添付ファイルの未加工のコンテンツ データを取得します。Following the event example and using the attachment ID returned in the Location header of the previous step, the next example request shows using a $value parameter to get the attachment raw content data.

要求Request

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

応答Response

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

{Raw bytes of the file}

例: メッセージに添付されたファイルのメタデータを取得するExample: Get the metadata of the file attached to the message

次の要求例では、メッセージ例に従い、$select パラメーターを使用して、contentBytes 以外のメッセージの添付ファイルのメタデータを取得します。Following the message example, the next example request shows using a $select parameter to get some of the metadata of a file attachment on a message, excluding contentBytes.

要求Request

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

応答Response

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
}

代替: アップロード セッションをキャンセルするAlternative: Cancel the upload session

アップロード セッションが期限切れになる前の任意の時点でアップロードをキャンセルする必要がある場合は、同じ初期不透明 URL を使用してアップロード セッションを削除できます。At any point of time before the upload session expires, if you have to cancel the upload, you can use the same initial opaque URL to delete the upload session. 操作が成功するとHTTP 204 No Contentが返されます。A successful operation returns HTTP 204 No Content.

例: メッセージのアップロード セッションをキャンセルするExample: cancel the upload session for the message

要求Request

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

応答Response

HTTP/1.1 204 No content

エラーErrors

ErrorAttachmentSizeShouldNotBeLessThanMinimumSizeErrorAttachmentSizeShouldNotBeLessThanMinimumSize

このエラーは、アップロード セッションを作成して 3 MB 未満のファイルを添付しようとすると返されます。This error is returned when attempting to create an upload session to attach a file smaller than 3 MB. ファイル サイズが 3 MB 未満の場合、メッセージまたはイベント添付ファイル ナビゲーション プロパティで単一の投稿を実行する必要があります。If the file size is under 3 MB, you should do a single POST on the attachments navigation property of the message or of the event. 成功したPOST応答には、メッセージに添付されたファイルの ID が含まれます。The successful POST response includes the ID of the file attached to the message.