The Google Cloud Storage JSON API allows you to upload object data when creating a new Object resource. Any kind of file data is permitted.
Contents
Upload options
The Google Cloud Storage JSON API allows you to upload certain types of binary data, or media. The specific characteristics of the data you can upload are specified on the reference page for any method that supports media uploads:
- Maximum upload file size : The maximum amount of data you can store with this method.
- Accepted media MIME types : The types of binary data you can store using this method.
There are three different ways to make upload requests, and you specify the method you are using with the
uploadType
request parameter:
-
Simple upload
:
uploadType=media
. For quick transfer of smaller files, for example, 5 MB or less. -
Multipart upload
:
uploadType=multipart
. For quick transfer of smaller files and metadata; transfers the file along with metadata that describes it, all in a single request. -
Resumable upload
:
uploadType=resumable
. For reliable transfer, especially important with larger files. With this method, you use a session initiating request, which optionally can include metadata. This is a good strategy to use for most applications, since it also works for smaller files at the cost of one additional HTTP request per upload.
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/storage/v1beta1/b/myBucket/o
. -
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 /storage/v1beta1/b/myBucket/o
.
Simple upload
The most straightforward method for uploading a file is by making a simple upload request. This option is a good choice when:
- The file is small enough to upload again in its entirety if the connection fails.
- There is no metadata to send. This might be true if you plan to send metadata for this resource in a separate request, or if no metadata is supported or available.
To use simple upload, make a
POST
request to
the method's
/upload
URI and add the query parameter
uploadType=media
. Since simple uploads do not include metadata, you must provide additional query parameter information (like
&name=myObject
) to identify which resource the upload is associated with. For example:
POST https://www.googleapis.com/upload/storage/v1beta1/b/myBucket/o?uploadType=media&name=myObject
The HTTP headers to use when making a simple upload request include: