Objects

The Objects resource represents an object within Google Cloud Storage. Objects are pieces of data that you have uploaded to Google Cloud Storage. For more information, see Object Name Requirements.

Every object in Google Cloud Storage resides in a bucket. The object is owned by its original uploader, who will always retain OWNER permission on it.

In addition to the acl property, objects contain objectAccessControls, for use in fine-grained manipulation of an existing object's access controls.

To try out the methods for this resource, see Methods.

Resource representations

{
  "kind": "storage#object",
  "id": string,
  "selfLink": string,
  "name": string,
  "bucket": string,
  "generation": long,
  "metageneration": long,
  "contentType": string,
  "timeCreated": datetime,
  "updated": datetime,
  "timeDeleted": datetime,
  "temporaryHold": boolean,
  "eventBasedHold": boolean,
  "retentionExpirationTime": datetime,
  "storageClass": string,
  "timeStorageClassUpdated": datetime,
  "size": unsigned long,
  "md5Hash": string,
  "mediaLink": string,
  "contentEncoding": string,
  "contentDisposition": string,
  "contentLanguage": string,
  "cacheControl": string,
  "metadata": {
    (key): string
  },
  "acl": [
    objectAccessControls Resource
  ],
  "owner": {
    "entity": string,
    "entityId": string
  },
  "crc32c": string,
  "componentCount": integer,
  "etag": string,
  "customerEncryption": {
    "encryptionAlgorithm": string,
    "keySha256": string
  },
  "kmsKeyName": string
}

Property name	Value	Description	Notes
acl[]	list	Access controls on the object, containing one or more objectAccessControls Resources. If iamConfiguration.uniformBucketLevelAccess.enabled is set to true, this field is omitted in responses, and requests that specify this field fail.	writable
bucket	string	The name of the bucket containing this object.
cacheControl	string	Cache-Control directive for the object data. If omitted, and the object is accessible to all anonymous users, the default will be public, max-age=3600.	writable
componentCount	integer	Number of underlying components that make up a composite object. Components are accumulated by compose operations, counting 1 for each non-composite source object and componentCount for each composite source object. Note: componentCount is included in the metadata for composite objects only.
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
contentType	string	Content-Type of the object data. If an object is stored without a Content-Type, it is served as application/octet-stream.	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
customerEncryption	object	Metadata of customer-supplied encryption key, if the object is encrypted by such a key.
customerEncryption.encryptionAlgorithm	string	The encryption algorithm.
customerEncryption.keySha256	string	SHA256 hash value of the encryption key.
etag	string	HTTP 1.1 Entity tag for the object.
eventBasedHold	boolean	Whether or not the object is subject to an event-based hold.	writable
generation	long	The content generation of this object. Used for object versioning.
id	string	The ID of the object, including the bucket name, object name, and generation number.
kind	string	The kind of item this is. For objects, this is always storage#object.
kmsKeyName	string	Cloud KMS Key used to encrypt this object, if the object is encrypted by such a key.
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
mediaLink	string	Media download link.
metadata	object	User-provided metadata, in key/value pairs.	writable
metadata.(key)	string	An individual metadata entry.	writable
metageneration	long	The version of the metadata for this object at this generation. Used for preconditions and for detecting changes in metadata. A metageneration number is only meaningful in the context of a particular generation of a particular object.
name	string	The name of the object. Required if not specified by URL parameter.	writable
owner	object	The owner of the object. This will always be the uploader of the object. If iamConfiguration.uniformBucketLevelAccess.enabled is set to true, this field does not apply, and is omitted in responses.
owner.entity	string	The entity, in the form user-userId.
owner.entityId	string	The ID for the entity.
retentionExpirationTime	datetime	The earliest time that the object can be deleted, based on a bucket's retention policy, in RFC 3339 format.
selfLink	string	The link to this object.
size	unsigned long	Content-Length of the data in bytes.
storageClass	string	Storage class of the object.	writable
temporaryHold	boolean	Whether or not the object is subject to a temporary hold.	writable
timeCreated	datetime	The creation time of the object in RFC 3339 format.
timeDeleted	datetime	The deletion time of the object in RFC 3339 format. Returned if and only if this version of the object is no longer a live version, but remains in the bucket as an archived object.
timeStorageClassUpdated	datetime	The time at which the object's storage class was last changed. When the object is initially created, it will be set to timeCreated.
updated	datetime	The modification time of the object metadata in RFC 3339 format.

Methods

Available methods for Objects resources are as follows:

compose

Concatenates a list of existing objects into a new object in the same bucket.

copy

Copies a source object to a destination object. Optionally overrides metadata.

delete

Deletes an object and its metadata. Deletions are permanent if versioning is not enabled for the bucket, or if the generation parameter is used.

get

Retrieves an object or its metadata.

insert

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

list

Retrieves a list of objects matching the criteria.

patch

Updates a data blob's associated metadata. This method supports patch semantics.

rewrite

Rewrites a source object to a destination object. Optionally overrides metadata.

update

Updates an object's metadata.

watchAll

Watch for changes on all objects in a bucket.