Objects: insert

Stores a new object and metadata. For tips on uploading to Google Cloud Storage, see best practices.

This method supports an /upload URI and accepts uploaded media with the following characteristics:

  • Maximum file size: 5 TB
  • Accepted Media MIME types: */*

The authenticated user must have WRITER permissions on the bucket.

Note: Despite the note below, metadata-only requests are not allowed; please use only the Upload URI. To change an object's metadata, use either the update or patch methods.

Request

HTTP request

This method provides media upload functionality through two separate URIs. For more details, see the document on media upload.

  • Upload URI, for media upload requests:
    POST https://www.googleapis.com/upload/storage/v1/b/bucket/o
  • Metadata URI, for metadata-only requests:
    POST https://www.googleapis.com/storage/v1/b/bucket/o

Parameters

Parameter name Value Description
Path parameters
bucket string Name of the bucket in which to store the new object. Overrides the provided object metadata's bucket value, if any.
Required query parameters
uploadType string The type of upload request to the /upload URI. Acceptable values are:
  • media - Simple upload. Upload the media only, without any metadata.
  • multipart - Multipart upload. Upload both the media and its metadata, in a single request.
  • resumable - Resumable upload. Upload the file in a resumable fashion, using a series of at least two requests where the first request includes the metadata.
Optional query parameters
contentEncoding string If set, sets the contentEncoding property of the final object to this value. Setting this parameter is equivalent to setting the contentEncoding metadata property. This can be useful when uploading an object with uploadType=media to indicate the encoding of the content being uploaded.
ifGenerationMatch long Makes the operation conditional on whether the object's current generation matches the given value.
ifGenerationNotMatch long Makes the operation conditional on whether the object's current generation does not match the given value.
ifMetagenerationMatch long Makes the operation conditional on whether the object's current metageneration matches the given value.
ifMetagenerationNotMatch long Makes the operation conditional on whether the object's current metageneration does not match the given value.
name string Name of the object. Required when the object metadata is not otherwise provided. Overrides the object metadata's name value, if any. For information about how to URL encode object names to be path safe, see Encoding URI Path Parts.
predefinedAcl string Apply a predefined set of access controls to this object.

Acceptable values are:
  • "authenticatedRead": Object owner gets OWNER access, and allAuthenticatedUsers get READER access.
  • "bucketOwnerFullControl": Object owner gets OWNER access, and project team owners get OWNER access.
  • "bucketOwnerRead": Object owner gets OWNER access, and project team owners get READER access.
  • "private": Object owner gets OWNER access.
  • "projectPrivate": Object owner gets OWNER access, and project team members get access according to their roles.
  • "publicRead": Object owner gets OWNER access, and allUsers get READER access.
projection string Set of properties to return. Defaults to noAcl, unless the object resource specifies the acl property, when it defaults to full.

Acceptable values are:
  • "full": Include all properties.
  • "noAcl": Omit the owner, acl property.

Request body

In the request body, supply an object resource with the following properties as the metadata. For more information, see the document on media upload.

Property name Value Description Notes
Optional Properties
acl[] list Access controls on the object. writable
cacheControl string Cache-Control directive for the object data. writable
contentDisposition string Content-Disposition of the object data. writable
contentEncoding string Content-Encoding of the object data. writable
contentLanguage string Content-Language of the object data. writable
crc32c string CRC32c checksum, as described in RFC 4960, Appendix B; encoded using base64 in big-endian byte order. For more information about using the CRC32c checksum, see Hashes and ETags: Best Practices. writable
md5Hash string MD5 hash of the data; encoded using base64. For more information about using the MD5 hash, see Hashes and ETags: Best Practices. writable
metadata object User-provided metadata, in key/value pairs. writable
metadata.(key) string An individual metadata entry. writable
name string The name of this object. Required if not specified by URL parameter. writable

Response

By default, this responds with an object resource in the response body. If you provide the URL parameter alt=media, then it will respond with the object data in the response body.

Send feedback about...

Cloud Storage Documentation