This page describes how to make a multipart upload request in the Drive API. A multipart upload request allows you to send metadata along with the data to upload. Use this option if the data you are sending is small enough to upload again in its entirety if the connection fails.
If your file does not have any metadata, use simple upload instead. For larger files (more than 5 MB) or less reliable network connections, use resumable upload instead.
Learn about request URIs
When you upload media, you use a special URI. In fact, methods that support media uploads have two URI endpoints:
- The
/upload
URI, for the media. The format of the/upload
endpoint is the standard resource URI with an/upload
prefix. Use this URI when transferring the media data itself. Example:POST /upload/drive/v3/files
. - The standard resource URI, for the metadata. If the resource contains any
data fields, those fields are used to store metadata describing the uploaded
file. You can use this URI when creating or updating metadata values.
Example:
POST /drive/v3/files/
.
Sending a multipart upload request
To use multipart upload:
- Create a
POST
request to the method's/upload
URI. To update an existing file, usePUT
. Add the query parameter
uploadType=multipart
.For example:
POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart
Create the body of the request. Format the body according to the
multipart/related
content type [RFC 2387], which contains two parts:- Metadata part. Must come first, and must have a
Content-Type
header set toapplication/json; charset=UTF-8
. Add the file's metadata to this part in JSON format. - Media part. Must come second, and must have a
Content-Type
header, which may have any MIME type. Add the file's data to this part.
Identify each part with a boundary string, preceded by two hyphens. In addition, add two hyphens after the final boundary string.
- Metadata part. Must come first, and must have a
Add the following top-level HTTP headers:
Content-Type
. Set tomultipart/related
, and include the boundary string you're using to identify the different parts of the request. For example:Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length
. Set to the total number of bytes in the request body.
Send the request.
Example: Sending a multipart upload request
The following example shows a multipart upload request:
POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart HTTP/1.1 Authorization: Bearer [YOUR_AUTH_TOKEN] Content-Type: multipart/related; boundary=foo_bar_baz Content-Length: [NUMBER_OF_BYTES_IN_ENTIRE_REQUEST_BODY] --foo_bar_baz Content-Type: application/json; charset=UTF-8 { "name": "myObject" } --foo_bar_baz Content-Type: image/jpeg [JPEG_DATA] --foo_bar_baz--
If the request succeeds, the server returns the HTTP 200 OK
status code along
with the file's metadata:
HTTP/1.1 200 Content-Type: application/json { "name": "myObject" }
Handling errors
When uploading media, be sure to follow these best practices related to error handling:
- 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
- Resume or retry uploads that fail due to 403 rate limit errors.
- Use an exponential backoff strategy if any 5xx server error is returned when resuming or retrying upload requests. These errors can occur if a server is getting overloaded. Exponential backoff can help alleviate these kinds of problems when there is a high volume of requests or heavy network traffic.
For additional details, see Handling API Errors