driveItem: createUploadSession

名前空間: microsoft.graph

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

アプリで最大ファイルサイズまでファイルをアップロードできるようにするには、アップロードセッションを作成します。

アップロードセッションにより、アプリは、シーケンシャル API 要求でファイルの範囲をアップロードできます。また、アップロード中に接続が切断された場合にも、転送を再開できます。

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

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

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

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

アクセス許可

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

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

注:

秘密度ラベルで保護されたファイルの内容の置き換えは、アプリのみの認証ではサポートされていません。代わりに、委任されたアクセス許可 (ユーザーコンテキスト) を使用してください。

注:

SharePoint Embedded では、コンテナーのコンテンツにアクセスするための FileStorageContainer.Selected アクセス許可が必要です。このアクセス許可は、前述のアクセス許可とは異なります。 Microsoft Graph のアクセス許可に加えて、アプリにはこの API を呼び出すために必要なコンテナーの種類のアクセス許可が必要です。詳細については、「 SharePoint Embedded の認証と承認」を参照してください。

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

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

HTTP 要求

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

新しいファイルの作成

POST /drives/{driveId}/items/{parentItemId}:/{fileName}:/createUploadSession
POST /groups/{groupId}/drive/items/{parentItemId}:/{fileName}:/createUploadSession
POST /me/drive/items/{parentItemId}:/{fileName}:/createUploadSession
POST /sites/{siteId}/drive/items/{parentItemId}:/{fileName}:/createUploadSession
POST /users/{userId}/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 /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", // only available for OneDrive (personal)
  "driveItemSource": { "@odata.type": "microsoft.graph.driveItemSource" },
  "fileSize": 1234, // only available for OneDrive (personal)
  "name": "filename.txt",
  "mediaSource": { "@odata.type": "microsoft.graph.mediaSource" }
}

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

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

プロパティ	型	説明
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 リソースとして送信する必要がある場所の詳細が提供されます。

セッションが作成され、事前認証されたアップロード URL が生成されると、アップロード URL を使用して、大きなファイルに対して十分な時間枠内でアップロードを完了できます。

uploadSession リソースは、ファイルの各バイト範囲をアップロードする場所に関する詳細を提供し、セッションの有効期限を指定します。 expirationDateTime プロパティは、それ以上アクティビティが発生しない場合に現在のセッションが期限切れになる時刻を示します。これにより、次の動作が発生します。

expirationDateTime プロパティで指定された時刻より前に、次のフラグメントをアップロードするか、セッションをコミットする必要があります。
アップロードされる各フラグメントによって有効期限が延長されるため、大きなファイルのアップロードを正常に完了できます。更新された有効期限は、ファイルフラグメントのアップロード要求ごとに返されます。
フラグメントを受信せず、セッションがコミットされていない場合、以前にアップロードされたフラグメントはすべて破棄されます。

このプロセスは、大きなファイルのアップロードをサポートし、古いデータや破棄されたデータがシステムに長く残るのを防ぐことで、アップロードセッションが効率的に管理されるようにします。

fileSize パラメーターが指定され、使用可能なクォータを超えた場合、507 Insufficient 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で応答します。不足している範囲の詳細な一覧を取得するには、アップロードステータスを要求できます。
PUT 呼び出しの発行時に Authorization ヘッダーを含めると、応答が HTTP 401 Unauthorized になる可能性があります。最初の手順で POST 要求を発行する場合にのみ、 Authorization ヘッダーとベアラートークンを含めます。 PUT 呼び出しを発行するときは、含めないでください。

ファイルの完成

deferCommit がfalseまたは未設定の場合、ファイルの最後のバイト範囲がアップロード URL に PUT されると、アップロードは自動的に完了します。

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

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

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

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

<final bytes of the file>

注:

SDK を使用して大きなファイルをアップロードするには、「 Microsoft Graph SDK を使用して大きなファイルをアップロードする」を参照してください。

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

注:

SDK を使用して大きなファイルをアップロードするには、「 Microsoft Graph SDK を使用して大きなファイルをアップロードする」を参照してください。

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

注:

SDK を使用して大きなファイルをアップロードするには、「 Microsoft Graph SDK を使用して大きなファイルをアップロードする」を参照してください。

応答

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

HTTP/1.1 204 No Content

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

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

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

例

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

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

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

注:

SDK を使用して大きなファイルをアップロードするには、「 Microsoft Graph SDK を使用して大きなファイルをアップロードする」を参照してください。

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/beta/me/drive/root:/{path_to_file}
Content-Type: application/json
If-Match: {etag or ctag}

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

注: この呼び出しでは、期待どおりに @microsoft.graph.conflictBehavior と if-match ヘッダーを使用できます。

応答

新しいメタデータを使用してファイルをコミットできる場合は、アップロードされたファイルの driveItem メタデータを含むHTTP 201 Createdまたは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 の倍数ではないフラグメントサイズを使用した場合、最後のバイト範囲をアップロードした後に、サイズの大きなファイルの転送が失敗する可能性があります。

エラー応答

エラーがどのように返されるかの詳細については、「エラー応答」を参照してください。

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

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-10-15