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.

For a list of methods for this resource, see the end of this page.

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": [
    {
      "kind": "storage#objectAccessControl",
      "id": string,
      "selfLink": string,
      "bucket": string,
      "object": string,
      "generation": long,
      "entity": string,
      "role": string,
      "email": string,
      "entityId": string,
      "domain": string,
      "projectTeam": {
        "projectNumber": string,
        "team": string
      },
      "etag": string
    }
  ],
  "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.	writable
acl[].bucket	string	The name of the bucket.
acl[].domain	string	The domain associated with the entity, if any.
acl[].email	string	The email address associated with the entity, if any.
acl[].entity	string	The entity holding the permission, in one of the following forms: user-userId user-email group-groupId group-email domain-domain project-team-projectId allUsers allAuthenticatedUsers Examples: The user [e-mail] would be [e-mail]. The group [e-mail] would be [e-mail]. To refer to all members of the G Suite for Business domain example.com, the entity would be domain-example.com.	writable
acl[].entityId	string	The ID for the entity, if any.
acl[].etag	string	HTTP 1.1 Entity tag for the access-control entry.
acl[].generation	long	The content generation of the object, if applied to an object.
acl[].id	string	The ID of the access-control entry.
acl[].kind	string	The kind of item this is. For object access control entries, this is always storage#objectAccessControl.
acl[].object	string	The name of the object, if applied to an object.
acl[].projectTeam	object	The project team associated with the entity, if any.
acl[].projectTeam.projectNumber	string	The project number.
acl[].projectTeam.team	string	The team. Acceptable values are: "editors" "owners" "viewers"
acl[].role	string	The access permission for the entity. Acceptable values are: "OWNER" "READER"	writable
acl[].selfLink	string	The link to this access-control entry.
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 this 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.
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.