アップロード セッションを使ってサイズが大きいファイルをアップロードするUpload large files with an upload session

アプリで最大ファイル サイズまでファイルをアップロードできるようにするには、アップロード セッションを作成します。アップロード セッションにより、アプリは一連の API 要求で広範なファイルをアップロードでき、このため、アップロードの進行中に接続が切れた場合に転送を再開できます。Create an upload session to allow your app to upload files up to the maximum file size. An upload session allows your app to upload ranges of the file in sequential API requests, which allows the transfer to be resumed if a connection is dropped while the upload is in progress.

アップロード セッションを使ってファイルをアップロードするには、次の 2 つの手順を行います。To upload a file using an upload session, there are two steps:

  1. アップロード セッションを作成するCreate an upload session
  2. アップロード セッションにバイトをアップロードするUpload bytes to the upload session

アクセス許可Permissions

この API を呼び出すには、次のいずれかのアクセス許可が必要です。アクセス許可の選択方法などの詳細については、「アクセス許可」を参照してください。One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

アクセス許可の種類Permission type アクセス許可 (特権の小さいものから大きいものへ)Permissions (from least to most privileged)
委任 (職場または学校のアカウント)Delegated (work or school account) Files.ReadWrite、Files.ReadWrite.All、Sites.ReadWrite.AllFiles.ReadWrite, Files.ReadWrite.All, Sites.ReadWrite.All
委任 (個人用 Microsoft アカウント)Delegated (personal Microsoft account) Files.ReadWrite、Files.ReadWrite.AllFiles.ReadWrite, Files.ReadWrite.All
アプリケーションApplication Sites.ReadWrite.AllSites.ReadWrite.All

アップロード セッションを作成するCreate an upload session

サイズが大きいファイルのアップロードを開始するには、アプリがまず新しいアップロード セッションを要求する必要があります。これにより、完全なファイルがアップロードされるまでファイルのバイトが保存される、一時的な保存場所が作成されます。ファイルの最後のバイトがアップロードされると、アップロード セッションは完了し、最終的なファイルがアップロード先のフォルダーに表示されます。To begin a large file upload, your app must first request a new upload session. This creates a temporary storage location where the bytes of the file will be saved until the complete file is uploaded. Once the last byte of the file has been uploaded the upload session is completed and the final file is shown in the destination folder.

HTTP 要求HTTP request

POST /drives/{driveId}/items/{itemId}/createUploadSession
POST /groups/{groupId}/drive/items/{itemId}/createUploadSession
POST /me/drive/items/{itemId}/createUploadSession
POST /sites/{siteId}/drive/items/{itemId}/createUploadSession
POST /users/{userId}/drive/items/{itemId}/createUploadSession

要求本文Request body

要求の本文は必要ありません。No request body is required. ただし、要求本文に item プロパティを指定し、アップロードされているファイルに関する追加データを提供できます。However, you can specify an item property in the request body, providing additional data about the file being uploaded.

{
  "@microsoft.graph.conflictBehavior": "rename | fail | replace",
  "description": "description",
  "fileSystemInfo": { "@odata.type": "microsoft.graph.fileSystemInfo" },
  "name": "filename.txt"
}

たとえば、ファイル名が既に取得されている場合の動作を制御するために、要求本文で競合動作のプロパティを指定できます。For example, to control the behavior if the filename is already taken, you can specify the conflict behavior property in the body of the request.

{
  "item": {
    "@microsoft.graph.conflictBehavior": "rename"
  }
}

オプションの要求ヘッダーOptional request headers

名前Name Value 説明Description
if-matchif-match etagetag この要求ヘッダーが含まれていて、指定された eTag (または cTag) がアイテムの現在の etag に一致しない場合には、412 Precondition Failed エラー応答が返されます。If this request header is included and the eTag (or cTag) provided does not match the current etag on the item, a 412 Precondition Failed error response is returned.

プロパティProperties

プロパティProperty Type 説明Description
descriptiondescription StringString ユーザーに表示されるアイテムの説明を提供します。読み取り/書き込み。OneDrive 個人用においてのみProvides a user-visible description of the item. Read-write. Only on OneDrive Personal
fileSystemInfofileSystemInfo fileSystemInfofileSystemInfo クライアント上のファイル システム情報。読み取り/書き込み。File system information on client. Read-write.
namename StringString アイテムの名前 (ファイル名と拡張子)。読み取り/書き込み。The name of the item (filename and extension). Read-write.

要求Request

この要求への応答により、新たに作成された uploadSession の詳細 (ファイルの各部分をアップロードするために使用される URL など) が指定されます。The response to this request will provide the details of the newly created uploadSession, which includes the URL used for uploading the parts of the file.

POST /me/drive/root:/{item-path}:/createUploadSession
Content-Type: application/json

{
  "item": {
    "@odata.type": "microsoft.graph.driveItemUploadableProperties",
    "@microsoft.graph.conflictBehavior": "rename",
    "name": "largefile.dat"
  }
}

応答Response

成功した場合、この要求への応答では残りの要求を送信する場所に関する詳細が UploadSession リソースとして提示されます。The response to this request, if successful, will provide the details for where the remainder of the requests should be sent as an UploadSession resource.

このリソースは、ファイルのバイト範囲をどこにアップロードするか、およびアップロード セッションがいつ期限切れになるかに関する詳細を提供します。This resource provides details about where the byte range of the file should be uploaded and when the upload session expires.

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

{
  "uploadUrl": "https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337",
  "expirationDateTime": "2015-01-29T09:21:55.523Z"
}

アップロード セッションにバイトをアップロードするUpload bytes to the upload session

ファイル、またはファイルの一部をアップロードするために、アプリは createUploadSession 応答で受け取った uploadUrl の値に PUT 要求を行います。To upload the file, or a portion of the file, your app makes a PUT request to the uploadUrl value received in the createUploadSession response. どの要求の最大バイト数も 60 MiB 未満である限り、ファイル全体をアップロードすることも、ファイルをいくつかのバイト範囲に分割することも可能です。You can upload the entire file, or split the file into multiple byte ranges, as long as the maximum bytes in any given request is less than 60 MiB.

分割されたファイルのフラグメントは順番にアップロードされる必要があります。The fragments of the file must be uploaded sequentially in order. 誤った順序でアップロードすると、エラーが発生します。Uploading fragments out of order will result in an error.

注: アプリがファイルを複数のバイト範囲に分割する場合、各バイト範囲のサイズは 320 KiB (327,680 バイト) の倍数である必要がありますNote: If your app splits a file into multiple byte ranges, the size of each byte range MUST be a multiple of 320 KiB (327,680 bytes). 320 KiB で均等に分割できないフラグメント サイズを使用した場合、一部のファイルのコミット中にエラーになります。Using a fragment size that does not divide evenly by 320 KiB will result in errors committing some files.

Example

この例では、128 バイトのファイルのうち、最初の 26 バイトをアプリがアップロードします。In this example, the app is uploading the first 26 bytes of a 128 byte file.

  • Content-Length ヘッダーは、現在の要求のサイズを指定します。The Content-Length header specifies the size of the current request.
  • Content-Range ヘッダーは、ファイル全体の中でこの要求が表すバイト範囲を示します。The Content-Range header indicates the range of bytes in the overall file that this request represents.
  • ファイルの最初のフラグメントをアップロードする前に、ファイルの長さの合計がわかっています。The total length of the file is known before you can upload the first fragment of the file.
PUT https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337
Content-Length: 26
Content-Range: bytes 0-25/128

<bytes 0-25 of the file>

重要:****Content-Range ヘッダーで指定されたファイル サイズの合計は、すべての要求で同じである必要があります。Important: Your app must ensure the total file size specified in the Content-Range header is the same for all requests. 異なるファイル サイズのバイト範囲が宣言された場合、要求は失敗します。If a byte range declares a different file size, the request will fail.

応答Response

要求の完了時に、アップロードする必要のあるバイト範囲がまだ存在している場合、サーバーは 202 Accepted で応答します。When the request is complete, the server will respond with 202 Accepted if there are more byte ranges that need to be uploaded.

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "expirationDateTime": "2015-01-29T09:21:55.523Z",
  "nextExpectedRanges": ["26-"]
}

アプリは nextExpectedRanges の値を使用して、次のバイト範囲の開始点を判断できます。Your app can use the nextExpectedRanges value to determine where to start the next byte range. サーバーがまだ受信していないファイルの部分を示す、複数の指定範囲が表示されることがあります。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.

常に以下のベスト プラクティスに従って、バイト範囲のサイズを決定してください。You should always determine the size of your byte ranges according to the best practices below. アップロードするバイト範囲の正しいサイズの範囲を nextExpectedRanges が返すことを想定しないでください。Do not assume that nextExpectedRanges will return reanges of proper size for a byte range to upload. nextExpectedRanges プロパティは、まだ受信されていないファイルの範囲を示します。アプリによるファイル アップロード方法のパターンを示すものではありません。The nextExpectedRanges property indicates ranges of the file that have not been received and not a pattern for how your app should upload the file.

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "expirationDateTime": "2015-01-29T09:21:55.523Z",
  "nextExpectedRanges": [
  "12345-55232",
  "77829-99375"
  ]
}

備考Remarks

  • nextExpectedRanges プロパティは、欠落してするすべての範囲の一覧を必ずしも示すわけではありません。The nextExpectedRanges property won't always list all of the missing ranges.
  • フラグメントの書き込みが成功すると、次の開始点の範囲が返されます (例: "523-")。On successful fragment writes, it will return the next range to start from (eg. "523-").
  • サーバーが既に受信していたフラグメントをクライアントが送信した場合のエラーでは、サーバーから HTTP 416 Requested Range Not Satisfiable の応答が返されます。受信されていない範囲のより詳細なリストを取得するために、アップロード ステータスを要求できます。On failures when the client sent a fragment the server had already received, the server will respond with HTTP 416 Requested Range Not Satisfiable. You can request upload status to get a more detailed list of missing ranges.
  • PUT の呼び出しを発行するときに、承認ヘッダーを含めると、HTTP 401 Unauthorized 応答が発生する可能性があります。承認ヘッダーとベアラー トークンは、最初の手順で POST を発行するときにのみ送信する必要があります。PUT を発行する場合は、含めないようにします。Including the Authorization header when issuing the PUT call may result in a HTTP 401 Unauthorized response. The Authorization header and bearer token should only be sent when issuing the POST during the first step. It should be not be included when issueing the PUT.

ファイルの完成Completing a file

ファイルの最後のバイト範囲が受信されると、サーバーは HTTP 201 Created または HTTP 200 OK の応答を返します。When the last byte range of a file is received the server will response with an HTTP 201 Created or HTTP 200 OK. 応答本文には完全なファイルを表す driveItem の既定のプロパティ セットも含まれます。The response body will also include the default property set for the driveItem representing the completed file.

PUT https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337
Content-Length: 21
Content-Range: bytes 101-127/128

<final bytes of the file>
HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "912310013A123",
  "name": "largefile.vhd",
  "size": 128,
  "file": { }
}

アップロード競合の処理Handling upload conflicts

ファイルのアップロード後に競合が発生した場合 (たとえば、アップロード セッション中に同じ名前のアイテムが作成された場合) には、最後のバイト範囲がアップロードされたときにエラーが返されます。If a conflict occurs after the file is uploaded (for example, an item with the same name was created during the upload session), an error is returned when the last byte range is uploaded.

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error":
  {
    "code": "upload_name_conflict",
    "message": "Another file exists with the same name as the uploaded session. You can redirect the upload session to use a new filename by calling PUT with the new metadata and @microsoft.graph.sourceUrl attribute.",
  }
}

アップロード セッションを取り消すCancel the upload session

アップロード セッションを取り消すには、アップロード URL に DELETE 要求を送信します。これにより、以前にアップロードしたデータを格納している一時ファイルがクリーンアップされます。これは、たとえばユーザーが転送を取り消した場合など、アップロードが中断される場合に使用する必要があります。To cancel an upload session send a DELETE request to the upload URL. This cleans up the temporary file holding the data previously uploaded. This should be used in scenarios where the upload is aborted, for example, if the user cancels the transfer.

一時ファイルとそれに伴うアップロード セッションは、expirationDateTime が経過した後、自動的にクリーンアップされます。Temporary files and their accompanying upload session are automatically cleaned up after the expirationDateTime has passed. 期限が経過しても、一時ファイルはただちに削除されるとは限りません。Temporary files may not be deleted immedately after the expiration time has elapsed.

要求Request

DELETE https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337

応答Response

次の例は応答を示しています。The following example shows the response.

HTTP/1.1 204 No Content

進行中のアップロードを再開するResuming an in-progress upload

あるアップロード要求が完了する前に、要求が切断されるか失敗すると、その要求のすべてのバイトが無視されます。これは、アプリとサービス間の接続が切断された場合に発生することがあります。このような場合、アプリは直前に完了したフラグメントからファイル転送を再開できます。If an upload request is disconnected or fails before the request is completed, all bytes in that request are ignored. This can occur if the connection between your app and the service is dropped. If this occurs, your app can still resume the file transfer from the previously completed fragment.

以前受信されたバイト範囲を知るために、アプリはアップロード セッションのステータスを要求できます。To find out which byte ranges have been received previously, your app can request the status of an upload session.

Example

uploadUrl に GET 要求を送信して、アップロードのステータスを照会します。Query the status of the upload by sending a GET request to the uploadUrl.

GET https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF86633784148bb98a1zjcUhf7b0mpUadahs

サーバーは応答で、アップロードが必要な、送信されなかったバイトの範囲のリストと、アップロード セッションの有効期限を返します。The server will respond with a list of missing byte ranges that need to be uploaded and the expiration time for the upload session.

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

{
  "expirationDateTime": "2015-01-29T09:21:55.523Z",
  "nextExpectedRanges": ["12345-"]
}

残りのデータをアップロードするUpload remaining data

アプリにアップロードの開始点がわかると、「アップロード セッションにバイトをアップロードする」の次の手順でアップロードを再開します。Now that your app knows where to start the upload from, resume the upload by following the steps in upload bytes to the upload session.

アップロード エラーの処理Handle upload errors

ファイルの最後のバイト範囲がアップロードされるときに、エラーが発生する可能性があります。When the last byte range of a file is uploaded, it is possible for an error to occur. この原因として、名前の競合またはクォータ制限の超過が考えられます。This can be due to a name conflict or quota limitation being exceeded. アップロード セッションは有効期限が切れるまで保持されるので、アプリはアップロード セッションを明示的にコミットすることで、アップロードを回復することができます。The upload session will be preserved until the expiration time, which allows your app to recover the upload by explicitly committing the upload session.

アプリでアップロード セッションを明示的にコミットするには、アップロード セッションのコミット時に使用される新しい driveItem リソースを使って PUT 要求を送信する必要があります。To explicitly commit the upload session, your app must make a PUT request with a new driveItem resource that will be used when committing the upload session. この新しい要求により、元のアップロード エラーの原因となったエラーが修正されるはずです。This new request should correct the source of error that generated the original upload error.

既存のアップロード セッションをアプリでコミットすることを示すために、アップロード セッション URL の値を指定した @microsoft.graph.sourceUrl プロパティを PUT 要求に含める必要があります。To indicate that your app is committing an existing upload session, the PUT request must include the @microsoft.graph.sourceUrl property with the value of your upload session URL.

PUT /me/drive/root:/{path_to_parent}
Content-Type: application/json
If-Match: {etag or ctag}

{
  "name": "largefile.vhd",
  "@microsoft.graph.conflictBehavior": "rename",
  "@microsoft.graph.sourceUrl": "{upload session URL}"
}

注: この呼び出しでは、期待どおりに @microsoft.graph.conflictBehaviorif-match ヘッダーを使用できます。Note: You can use the @microsoft.graph.conflictBehavior and if-match headers as expected in this call.

応答Response

新しいメタデータを使用してファイルをコミットできる場合は、HTTP 201 Created または HTTP 200 OK の応答が、アップロードしたファイルのアイテム メタデータとともに返されます。If the file can be committed using the new metadata, an HTTP 201 Created or HTTP 200 OK response will be returned with the Item metadata for the uploaded file.

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

{
  "id": "912310013A123",
  "name": "largefile.vhd",
  "size": 128,
  "file": { }
}

ベスト プラクティスBest practices

  • 接続の中断や 5xx エラーにより失敗したアップロードは、次のように再開または再試行します。Resume or retry uploads that fail due to connection interruptions or any 5xx errors, including:
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • アップロード要求を再開または再試行するときに 5xx サーバー エラーが返された場合には、指数近似バックオフを使用します。Use an exponential back off strategy if any 5xx server errors are returned when resuming or retrying upload requests.
  • その他のエラーの場合は指数近似バックオフは使わず、再試行回数を制限する必要があります。For other errors, you should not use an exponential back off strategy but limit the number of retry attempts made.
  • 再開可能なアップロードを実行中の 404 Not Found エラーは、アップロード全体を最初からやり直して処理します。Handle 404 Not Found errors when doing resumable uploads by starting the entire upload over. これは、アップロード セッションがもはや存在しなくなったことを示します。This indicates the upload session no longer exists.
  • 10 MiB (10,485,760 バイト) を超えるサイズのファイルには、再開可能なファイル転送を使用します。Use resumable file transfers for files larger than 10 MiB (10,485,760 bytes).
  • 安定した高速接続で最適なバイト範囲サイズは 10 MiB です。A byte range size of 10 MiB for stable high speed connections is optimal. より低速な、または信頼性の低い接続では、フラグメント サイズをより小さくした方が良い結果を得られます。For slower or less reliable connections you may get better results from a smaller fragment size. 推奨されるフラグメント サイズは、5 から 10 MiB です。The recommended fragment size is between 5-10 MiB.
  • 320 KiB (327,680 バイト) の倍数のバイト範囲サイズを使用してください。Use a byte range size that is a multiple of 320 KiB (327,680 bytes). 320 KiB の倍数ではないフラグメント サイズを使用した場合、最後のバイト範囲をアップロードした後に、サイズの大きなファイルの転送が失敗する可能性があります。Failing to use a fragment size that is a multiple of 320 KiB can result in large file transfers failing after the last byte range is uploaded.

エラー応答Error responses

エラーがどのように返されるかについては、「エラー応答」のトピックを参照してください。See the Error Responses topic for details about how errors are returned.