driveItem: createUploadSession

  • [アーティクル]

名前空間: microsoft.graph

アプリで最大ファイル サイズまでファイルをアップロードできるようにするには、アップロード セッションを作成します。 アップロード セッションを使用すると、アプリはシーケンシャル API 要求でファイルの範囲をアップロードできます。 アップロード セッションを使用すると、アップロードの進行中に接続が切断された場合に転送を再開することもできます。

アップロード セッションを使用してファイルをアップロードするには:

  1. アップロード セッションを作成する
  2. アップロード セッションにバイトをアップロードする

この API は、次の国内クラウド展開で使用できます。

グローバル サービス 米国政府機関 L4 米国政府機関 L5 (DOD) 21Vianet が運営する中国
✅ ✅ ✅ ✅

アクセス許可

この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「 アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、 アクセス許可のリファレンスを参照してください。

アクセス許可の種類 最小特権アクセス許可 特権の高いアクセス許可
委任 (職場または学校のアカウント) Files.ReadWrite Files.ReadWrite.All、Sites.ReadWrite.All
委任 (個人用 Microsoft アカウント) Files.ReadWrite Files.ReadWrite.All
アプリケーション Sites.ReadWrite.All 注意事項なし。

アップロード セッションを作成する

サイズが大きいファイルのアップロードを開始するには、アプリがまず新しいアップロード セッションを要求する必要があります。 この要求により、完全なファイルがアップロードされるまでファイルのバイトが保存される一時ストレージの場所が作成されます。 ファイルの最後のバイトがアップロードされると、アップロード セッションが完了し、最終的なファイルがコピー先フォルダーに表示されます。 または、要求引数に deferCommit プロパティを設定することで、アップロードを完了する要求を明示的に行うまで、コピー先でのファイルの最終作成を延期することもできます。

HTTP 要求

新しいファイルをアップロードするには、要求で親 ID と新しいファイル名の両方を指定する必要があります。 ただし、更新には、更新されるアイテムの ID のみが必要です。

新しいファイルを作成する

POST /me/drive/items/{parentItemId}:/{fileName}:/createUploadSession

既存のファイルを更新する

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

要求ヘッダー

名前 値 説明
if-match etag この要求ヘッダーが含まれていて、指定された eTag (または cTag) がアイテムの現在の etag と一致しない場合は、 412 Precondition Failed エラー応答が返されます。
if-none-match etag この要求ヘッダーが含まれており、指定された eTag (または cTag) がアイテムの現在の etag と一致する場合は、 412 Precondition Failed エラー応答が返されます。

要求本文

要求の本文は必要ありません。 ただし、要求本文でプロパティを指定して、アップロードするファイルに関する詳細情報を提供したり、アップロード操作のセマンティクスをカスタマイズしたりできます。

たとえば、 item プロパティを使用すると、次のパラメーターを設定できます。

{
  "@microsoft.graph.conflictBehavior": "fail (default) | replace | rename",
  "description": "description",
  "driveItemSource": { "@odata.type": "microsoft.graph.driveItemSource" },
  "fileSize": 1234,
  "name": "filename.txt",
  "mediaSource": { "@odata.type": "microsoft.graph.mediaSource" }
}

次の例では、ファイル名が既に取得されている場合の動作を制御します。 この例では、明示的な完了要求が行われるまで、最終的なファイルを作成しないように指定します。

{
  "item": {
    "@microsoft.graph.conflictBehavior": "rename"
  },
  "deferCommit": true
}

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

名前 値 説明
if-match etag この要求ヘッダーが含まれていて、指定された eTag (または cTag) がアイテムの現在の etag と一致しない場合は、 412 Precondition Failed エラー応答が返されます。

パラメーター

パラメーター 型 説明
deferCommit ブール値 に設定されている true場合、宛先でファイルを最終的に作成するには、明示的な要求が必要です。
項目 driveItemUploadableProperties アップロード中のファイルに関するデータ

要求

この要求に対する応答は、新しく作成された uploadSession の詳細を提供します。これには、ファイルの部分のアップロードに使用される URL が含まれます。

注: {item-path} には、要求本文で指定されたアイテムの名前が含まれている必要があります。

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

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

応答

成功した場合、この要求への応答では残りの要求を送信する場所に関する詳細が UploadSession リソースとして提示されます。

このリソースは、ファイルのバイト範囲をどこにアップロードするか、およびアップロード セッションがいつ期限切れになるかに関する詳細を提供します。

パラメーターが fileSize 指定され、使用可能な 507 Insufficent Storage クォータを超えた場合、応答が返され、アップロード セッションは作成されません。

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

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

アップロード セッションにバイトをアップロードする

ファイル、またはファイルの一部をアップロードするために、アプリは createUploadSession 応答で受け取った uploadUrl の値に PUT 要求を行います。 どの要求の最大バイト数も 60 MiB 未満である限り、ファイル全体をアップロードすることも、ファイルをいくつかのバイト範囲に分割することも可能です。

分割されたファイルのフラグメントは順番にアップロードされる必要があります。 フラグメントを順に並べ替え外にアップロードすると、エラーが発生します。

注: アプリがファイルを複数のバイト範囲に分割する場合、各バイト範囲のサイズは 320 KiB (327,680 バイト) の倍数である必要があります。

320 KiB で均等に分割されないフラグメント サイズを使用すると、一部のファイルをコミットするエラーが発生します。

例

この例では、アプリは 128 バイト ファイルの最初の 26 バイトをアップロードしています。

  • Content-Length ヘッダーは、現在の要求のサイズを指定します。
  • Content-Range ヘッダーは、ファイル全体の中でこの要求が表すバイト範囲を示します。
  • ファイルの最初のフラグメントをアップロードする前に、ファイルの長さの合計がわかっています。
PUT https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337
Content-Length: 26
Content-Range: bytes 0-25/128

<bytes 0-25 of the file>

注:

  • SDK を使用して大きなファイルをアップロードするには、「 Microsoft Graph SDK を使用して大きなファイルをアップロードする」を参照してください。
  • アプリでは、 Content-Range ヘッダーで指定された合計ファイル サイズがすべての要求で同じであることを確認する必要があります。 異なるファイル サイズのバイト範囲が宣言された場合、要求は失敗します。

応答

要求が完了すると、アップロードする必要があるバイト範囲が増えた場合、サーバーは で 202 Accepted 応答します。

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

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

アプリは nextExpectedRanges の値を使用して、次のバイト範囲の開始点を判断できます。 指定された複数の範囲が表示される場合があります。これは、サーバーがまだ受信していないファイルの一部を示します。 これは、中断された転送を再開する必要があり、クライアント側でサービスの状態が不明な場合に便利です。

常に以下のベスト プラクティスに従って、バイト範囲のサイズを決定してください。 nextExpectedRanges は、アップロードするバイト範囲に適したサイズの範囲を返すと想定しないでください。 nextExpectedRanges プロパティは、受信されていないファイルの範囲を示し、アプリでファイルをアップロードする方法のパターンを示しません。

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

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

注釈

  • プロパティには nextExpectedRanges 、不足しているすべての範囲が必ずしも一覧表示されるわけではありません。
  • フラグメントの書き込みが成功すると、開始元の次の範囲 ("523-" など) が返されます。
  • クライアントがサーバーが既に受信したフラグメントを送信したときにエラーが発生すると、サーバーは で HTTP 416 Requested Range Not Satisfiable応答します。 受信されていない範囲のより詳細なリストを取得するために、アップロード ステータスを要求できます。
  • 呼び出しを発行するときに Authorization ヘッダーを PUT 含めると、応答が発生する HTTP 401 Unauthorized 可能性があります。 最初の手順で を発行 POST する場合にのみ、Authorization ヘッダーとベアラー トークンを送信します。 呼び出しを発行 PUT するときに含めないでください。

ファイルの完成

deferCommit が正しくない、または設定を解除された場合、ファイルの最終的なバイト範囲がアップロード URL に格納されると、アップロードが自動的に完了します。

deferCommit が true の場合は、次の2つの方法でアップロードを明示的に完了できます。

  • ファイルの最終的なバイト範囲がアップロード URL に設定されたら、長さ0のコンテンツのアップロード URL に最終投稿要求を送信します (現在、OneDrive for Business と SharePoint でのみサポートされています)。
  • ファイルの最後のバイト範囲がアップロード URL に格納された後、アップロードエラーを処理するのと同じ方法で最終的な PUT 要求を送信します (現在のところ、OneDrive Personal でのみサポートされています)。

アップロードが完了すると、サーバーは または HTTP 200 OKで最終要求HTTP 201 Createdに応答します。 応答本文には完全なファイルを表す driveItem の既定のプロパティ セットも含まれます。

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": { }
}

POST https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337
Content-Length: 0

注:

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

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

アップロード競合の処理

ファイルのアップロード後に競合が発生した場合 (たとえば、アップロード セッション中に同じ名前のアイテムが作成された場合) には、最後のバイト範囲がアップロードされたときにエラーが返されます。

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

{
  "error":
  {
    "code": "nameAlreadyExists",
    "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.",
  }
}

アップロード セッションを取り消す

アップロード セッションを取り消すには、アップロード URL に DELETE 要求を送信します。 これにより、以前にアップロードしたデータを格納している一時ファイルがクリーンアップされます。 これは、たとえばユーザーが転送を取り消した場合など、アップロードが中断される場合に使用する必要があります。

一時ファイルとそれに伴うアップロード セッションは、expirationDateTime が経過した後、自動的にクリーンアップされます。 有効期限が経過した直後に一時ファイルが削除されない場合があります。

要求

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

注:

応答

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

HTTP/1.1 204 No Content

進行中のアップロードを再開する

あるアップロード要求が完了する前に、要求が切断されるか失敗すると、その要求のすべてのバイトが無視されます。 これは、アプリとサービス間の接続が切断された場合に発生することがあります。 このような場合、アプリは直前に完了したフラグメントからファイル転送を再開できます。

以前受信されたバイト範囲を知るために、アプリはアップロード セッションのステータスを要求できます。

例

uploadUrl に GET 要求を送信して、アップロードのステータスを照会します。

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

サーバーは、アップロードする必要がある不足しているバイト範囲と、アップロード セッションの有効期限の一覧で応答します。

注:

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

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

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

アプリにアップロードの開始点がわかると、「アップロード セッションにバイトをアップロードする」の次の手順でアップロードを再開します。

アップロード エラーの処理

ファイルの最後のバイト範囲がアップロードされると、エラーが発生する可能性があります。 この原因として、名前の競合またはクォータ制限の超過が考えられます。 アップロード セッションは有効期限が切れるまで保持されます。これにより、アプリはアップロード セッションを明示的にコミットしてアップロードを回復できます。

アプリでアップロード セッションを明示的にコミットするには、アップロード セッションのコミット時に使用される新しい driveItem リソースを使って PUT 要求を送信する必要があります。 この新しい要求により、元のアップロード エラーの原因となったエラーが修正されるはずです。

既存のアップロード セッションをアプリでコミットすることを示すために、アップロード セッション URL の値を指定した @microsoft.graph.sourceUrl プロパティを PUT 要求に含める必要があります。

PUT https://graph.microsoft.com/v1.0/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}"
}

応答

新しいメタデータを使用してファイルをコミットできる場合は、 HTTP 201 Created アップロードされたファイルの Item メタデータを含む または HTTP 200 OK 応答が返されます。

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

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

ベスト プラクティス

  • 接続の中断や 5xx エラーにより失敗したアップロードは、次のように再開または再試行します。
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • アップロード要求を再開または再試行するときに 5xx サーバー エラーが返された場合には、指数近似バックオフを使用します。
  • その他のエラーについては、指数バックオフ戦略を使用せず、再試行回数を制限する必要があります。
  • 再開可能なアップロードを実行中の 404 Not Found エラーは、アップロード全体を最初からやり直して処理します。 これは、アップロード セッションがもはや存在しなくなったことを示します。
  • 10 MiB (10,485,760 バイト) を超えるサイズのファイルには、再開可能なファイル転送を使用します。
  • 安定した高速接続で最適なバイト範囲サイズは 10 MiB です。 接続の信頼性が低下する場合は、フラグメント サイズが小さい方が良い結果が得られる場合があります。 推奨されるフラグメント サイズは、5 から 10 MiB です。
  • 320 KiB (327,680 バイト) の倍数のバイト範囲サイズを使用してください。 320 KiB の倍数ではないフラグメント サイズを使用した場合、最後のバイト範囲をアップロードした後に、サイズの大きなファイルの転送が失敗する可能性があります。

エラー応答

エラーが返される方法の詳細については、 エラー応答 に関する記事を参照してください。

関連コンテンツ

大きなファイルのアップロード