Uploading large files to OneDrive by using BITS
This topic describes how to upload large files to OneDrive by using the BITS Upload Protocol.
Last modified: June 15, 2017
Applies to: OneDrive
OneDrive handles uploading large files by supporting the BITS Upload Protocol. BITS (Background Intelligent Transfer Service) is a simple extension to HTTP that enables resumable file uploads to OneDrive.
The standard PUT method for uploading a file has a 100 MB limit, but using the BITS protocol will allow you to upload much larger files. BITS also provides connection tolerance by splitting the file into separate fragments, which are uploaded sequentially and reassembled into the original file on the service. If a fragment transfer is interrupted, only that fragment needs to be uploaded again, and previously uploaded fragments are preserved on the server.
Note
|
|---|
|
Unlike the Live SDK, there is no logic to resize or resample photos that run when photos are uploaded with BITS. |
To upload a large file, this particular call pattern is required:
-
Request an upload session.
-
Upload file fragments.
-
Close the upload session.
To begin, make a request to OneDrive to create a new upload session.
Request
Your app must first get the user's ID, a unique identifier for OneDrive, to build the URL. You can do this by using the Live SDK to make a request for the user's profile information. The value returned in the id field is the user's ID. See Getting user data (REST) for more info.
After your app has the user's ID, it uses it to build the request to create an upload session. In this example, the file Terwiliger.jpg is uploaded into a folder named Portland in the root of the user's OneDrive.
POST /users/0x{id}/LiveFolders/Portland/Terwiliger.jpg HTTP/1.1
Host: storage.live.com
X-Http-Method-Override: BITS_POST
Authorization: Bearer {access-token}
BITS-Packet-Type: Create-Session
BITS-Supported-Protocols: {7df0354d-249b-430f-820d-3d2a9bef4931}
Note |
|---|
You can upload files based on the folder's resource ID or the path of the folder. |
To upload a file using the folder resource ID, use a URL format like this:
https://storage.live.com/users/0x{id}/items/{folder-id}/newfilename.jpg
To upload using path, the URL format should look like this:
https://storage.live.com/users/0x{id}/LiveFolders/{folder-path}/newfilename.jpg
Header name | Description |
|---|---|
X-Http-Method-Override | BITS uses the BITS_POST custom HTTP method. If your HTTP stack does not support custom protocols, you can use this header to change the HTTP method from POST to BITS_POST. |
Authorizationn | Set the OAuth access token received from OAuth 2.0. |
BITS-Packet-Type | Create-Session indicates that the request is to create a new upload session. |
BITS-Supported-Protocols | The GUID represents the version of BITS used for the session. |
Response
If successful, the service will return an HTTP 201 Created response:
HTTP/1.1 201 Created
Content-Length: 0
Date: Fri, 19 Nov 2010 10:31:16 GMT
BITS-Packet-Type: ACK
BITS-Protocol: {7df0354d-249b-430f-820d-3d2a9bef4931}
BITS-Session-Id: {session-id}
Header name | Description |
|---|---|
BITS-Packet-Type | ACK represents the server is acknowledging the request. |
BITS-Protocol | The service echoes back the GUID for the specific protocol implementation. |
BITS-Session-Id | This value should be stored and included in subsequent requests to connect them to the session that was created. |
201 Created indicates that the upload session has been created and is ready to receive the contents of the file. No file is created or visible in the user's OneDrive account until the upload session is complete. If the upload is not completed before the session ends, any received part(s) of the file is deleted from OneDrive.
Note |
|---|
An upload session is valid for a maximum of 24 hours. If the session has not completed within that time, the session and all uploaded data is deleted and clients must start the upload again from scratch. |
Your app or service should create a plan for how the file will be split into fragments to uploaded. OneDrive has a maximum fragment size of 60 MB.
For example, if you have a 150 MB file to upload, you might prefer to upload the file using 15 fragments each of 10 MB. This way if the connection is interrupted during the upload, the largest amount of data that would need to be uploaded again would be 10 MB.
After your app has a plan for the number of fragments and their size, it can start uploading each fragment.
Request
To upload a fragment, the app will post to the same URL used to create the upload session, but with a different set of headers that define which upload session to use and the information about the fragment being uploaded.
POST /users/0x{id}/LiveFolders/Portland/Terwiliger.jpg HTTP/1.1
Host: storage.live.com
X-Http-Method-Override: BITS_POST
Authorization: Bearer {access-token}
BITS-Packet-Type: Fragment
BITS-Session-Id: {session-id}
Content-Length: {length}
Content-Range: bytes {range}/{total-length}{payload}
Header name | Description |
|---|---|
X-Http-Method-Override | BITS uses the BITS_POST custom HTTP method. If your HTTP stack does not support custom protocols, you can use this header to change the HTTP method from POST to BITS_POST. |
Authorization | Set the OAuth access token received from OAuth 2.0. |
BITS-Packet-Type | Fragment indicates that the request is part of the file content. |
BITS-Session-Id | The same value returned when creating the session, should be written to this header. |
Content-Length | Number of bytes in the current fragment. |
Content-Range | Bytes included in this fragment and the total length of the file. For example 0-10485759/1048576000 would indicate that the fragment is the first 10 MB of a 100MB file. See RFC 2616 for more details. |
Response
The server response to the uploaded fragment will provide information about how much of the file has been received and the next range of bytes expected.
HTTP/1.1 200 OK
Content-Length: 0
Date: Fri, 19 Nov 2010 10:31:16 GMT
BITS-Packet-Type: ACK
BITS-Session-Id: {session-id}
BITS-Received-Content-Range: {n}
Header name | Description |
|---|---|
BITS-Packet-Type | ACK represents the server is acknowledging the request. |
BITS-Session-Id | This value connects the response to the upload session created in the initial request. |
BITS-Received-Content-Range | Indicates the number of bytes from the start of the file that have been received. |
Note |
|---|
You must upload fragments of a file in order, from beginning to end of the file. |
OneDrive does not support uploading bytes that have been previously uploaded. The service will respond with a 416 Range-Not-Satisfiable if the fragment request overlaps with an existing fragment that has already been received.
After each individual fragment has been uploaded, your application makes a request to close the upload session and commit the file to the user's OneDrive. If this call is not made, the file will not be saved and will be purged from temporary storage after 24 hours.
Request
POST /users/0x{cid}/LiveFolders/Portland/Terwiliger.jpg HTTP/1.1
Host: storage.live.com
X-Http-Method-Override: BITS_POST
Authorization: Bearer {access-token}
BITS-Packet-Type: Close-Session
BITS-Session-Id: {session-id}
Content-Length: 0
Header name | Description |
|---|---|
X-Http-Method-Override | BITS uses the BITS_POST custom HTTP method. If your HTTP stack does not support custom protocols, you can use this header to change the HTTP method from POST to BITS_POST. |
Authorization | Set the OAuth access token received from OAuth 2.0. |
BITS-Packet-Type | Close-Session indicates that the request is to close the upload session. |
BITS-Session-Id | The same value returned when creating the session should be written to this header. |
Content-Length | Should always be 0 for this request. |
Response
The server response to the uploaded fragment will provide information about how much of the file has been received and the next range of bytes expected.
HTTP/1.1 200 OK
Content-Length: 0
Date: Fri, 19 Nov 2010 10:31:16 GMT
BITS-Packet-Type: ACK
BITS-Session-Id: {session-id}
X-Resource-Id: {file-id}
Header name | Description |
|---|---|
BITS-Packet-Type | ACK represents the server is acknowledging the request. |
BITS-Session-Id | This value connects the response to the upload session created in the initial request. |
BITS-Received-Content-Range | Number that indicates the number of bytes from the start of the file that have been received. |
X-Resource-Id | The resource ID for the uploaded file. |
Note |
|---|
The value for X-Resource-Id is the resource identifier for the uploaded file in the user's OneDrive. You can use this value to make additional API calls for the file, for example to set additional metadata or properties on the file. |
Note