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 | 注意事項なし。 |
アップロード セッションを作成する
サイズが大きいファイルのアップロードを開始するには、アプリがまず新しいアップロード セッションを要求する必要があります。
これにより、完全なファイルがアップロードされるまでファイルのバイトが保存される、一時的な保存場所が作成されます。
ファイルの最後のバイトがアップロードされると、アップロード セッションは完了し、最終的なファイルがアップロード先のフォルダーに表示されます。
あるいは、アップロードを完了するための要求を明示的に要求するまで、要求の引数に deferCommit プロパティを設定することで、コピー先のファイルの最終的な作成を遅らせることができます。
HTTP 要求
POST /drives/{driveId}/items/{itemId}/createUploadSession
POST /groups/{groupId}/drive/items/{itemId}/createUploadSession
POST /me/drive/items/{itemId}/createUploadSession
POST /me/drive/items/{itemId}:/{fileName}:/createUploadSession
POST /sites/{siteId}/drive/items/{itemId}/createUploadSession
POST /users/{userId}/drive/items/{itemId}/createUploadSession
要求本文
要求の本文は必要ありません。 ただし、アップロード中のファイルについての追加データを提供し、アップロード操作のセマンティクスをカスタマイズすることによって、要求本文のプロパティを指定することができます。
たとえば、 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応答します。 受信されていない範囲のより詳細なリストを取得するために、アップロード ステータスを要求できます。 PUTの呼び出しを発行するときに、承認ヘッダーを含めると、HTTP 401 Unauthorized応答が発生する可能性があります。 Authorization ヘッダーとベアラー トークンは、最初の手順で をPOST発行するときにのみ送信する必要があります。 を発行するときに含めないようにする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>
注:
- 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": "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.",
}
}
アップロード セッションを取り消す
アップロード セッションを取り消すには、アップロード 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 ヘッダーを使用できます。
応答
新しいメタデータを使用してファイルをコミットできる場合は、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 Error502 Bad Gateway503 Service Unavailable504 Gateway Timeout
- アップロード要求を再開または再試行するときに 5xx サーバー エラーが返された場合には、指数近似バックオフを使用します。
- その他のエラーについては、指数バックオフ戦略を使用せず、再試行回数を制限する必要があります。
- 再開可能なアップロードを実行中の
404 Not Foundエラーは、アップロード全体を最初からやり直して処理します。 これは、アップロード セッションがもはや存在しなくなったことを示します。 - 10 MiB (10,485,760 バイト) を超えるサイズのファイルには、再開可能なファイル転送を使用します。
- 安定した高速接続で最適なバイト範囲サイズは 10 MiB です。 より低速な、または信頼性の低い接続では、フラグメント サイズをより小さくした方が良い結果を得られます。 推奨されるフラグメント サイズは、5 から 10 MiB です。
- 320 KiB (327,680 バイト) の倍数のバイト範囲サイズを使用してください。 320 KiB の倍数ではないフラグメント サイズを使用した場合、最後のバイト範囲をアップロードした後に、サイズの大きなファイルの転送が失敗する可能性があります。
エラー応答
エラーがどのように返されるかについては、「エラー応答」のトピックを参照してください。
関連コンテンツ
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示