Objects

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

Every object in 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",
  "customTime": "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. Only requests that use the `"projection=full"` query parameter return this field in the response. If `iamConfiguration.uniformBucketLevelAccess.enabled` is set to `true`, this field does not apply, and requests that specify it 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`	Returned for composite objects only. Number of non-composite objects in the composite object. `componentCount` includes non-composite objects that were part of any composite objects used to compose the current object.
`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; encoded using base64.
`customTime`	`datetime`¹	A user-specified timestamp for the object in RFC 3339 format. Once set on an object, `customTime` cannot be removed and cannot be set to an earlier datetime. For more information, see custom time metadata.	writable
`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. This field is not present for composite objects. 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 is always the uploader of the object. Only requests that use the `"projection=full"` query parameter return this field in the response. If `iamConfiguration.uniformBucketLevelAccess.enabled` is set to `true`, this field does not apply.
`owner.entity`	`string`	The entity, in the form `"user-emailAddress"`.
`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 a noncurrent version.
`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.

¹ This property is a string formatted as the specified value type.

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 more information about writing data to Cloud Storage, see Uploads and downloads.
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.

For information about status and error codes returned by these APIs, see the reference page.