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, seeObject Name Requirements.
Every object in Cloud Storage resides in abucket. The object is owned by its original uploader, who will always retainOWNER permission on it.
In addition to theacl property, objects containobjectAccessControls, for use in fine-grained manipulation of an existing object's access controls.
To try out the methods for this resource, seeMethods.
Resource representations
{"kind":"storage#object","id":string,"selfLink":string,"mediaLink":string,"name":string,"bucket":string,"generation":"long","metageneration":"long","contentType":string,"storageClass":string,"size":"unsigned long","softDeleteTime":"datetime","restoreToken":string,"hardDeleteTime":"datetime","md5Hash":string,"contentEncoding":string,"contentDisposition":string,"contentLanguage":string,"cacheControl":string,"crc32c":string,"componentCount":integer,"etag":string,"kmsKeyName":string,"temporaryHold":boolean,"eventBasedHold":boolean,"retentionExpirationTime":"datetime","retention":{"retainUntilTime":"datetime","mode":string}"timeCreated":"datetime","timeFinalized":"datetime","updated":"datetime","timeDeleted":"datetime","timeStorageClassUpdated":"datetime","customTime":"datetime","metadata":{(key):string},"acl":[objectAccessControlsResource],"owner":{"entity":string,"entityId":string},"customerEncryption":{"encryptionAlgorithm":string,"keySha256":string}"contexts":{"custom":{(key):{"value":string,"createTime":"datetime","updateTime":"datetime"}}}}
| Property name | Value | Description | Notes |
|---|---|---|---|
acl[] | list | Access controls on the object, containing one or moreobjectAccessControls Resources. Only requests that use the If | 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 is"public, max-age=3600". | writable |
componentCount | integer | Returned forcomposite objects only. Number of non-composite objects in the composite object.componentCount includes non-composite objects that were part of any composite objects used tocompose 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 |
contexts | object | Contexts attached to an object, in key-value pairs. For more information about object contexts, seeObject contexts overview. | writable |
contexts.custom | object | User-provided object contexts. | writable |
contexts.custom.(key) | object | An individual object context. Context keys and their corresponding values must start with an alphanumeric character. They can contain any Unicode characters except single quotes ('), double quotes ("), backslashes (\), and forward slashes (/). Additionally, duplicate keys are prohibited. | writable |
contexts.custom.(key).value | string | The value associated with this context. This field holds the primary information for the given context key. | writable |
contexts.custom.(key).createTime | dateTime | The time when context was first added to thestorage#object inRFC 3339 format. | |
contexts.custom.(key).updateTime | dateTime | The time when context was last updated inRFC 3339 format. | |
crc32c | string | CRC32c checksum, as described inRFC 4960, Appendix B; encoded usingbase64 in big-endian byte order. For more information about using the CRC32c checksum, seeData validation. | 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 usingbase64. | |
customTime | datetime1 | A user-specified timestamp for the object inRFC 3339 format. Once set on an object,customTime cannot be removed and cannot be set to an earlier datetime. For more information, seecustom time metadata. | writable |
etag | string | HTTP 1.1Entity tag for the object. | |
eventBasedHold | boolean | Whether or not the object is subject to anevent-based hold. | writable |
generation | long1 | The content generation of this object. Used forobject versioning andsoft delete. | |
id | string | The ID of the object, including the bucket name, object name, and generation number. | |
kind | string | The kind of resource being described. 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 usingbase64. This field is not present forcomposite objects. For more information about using the MD5 hash, seeData validation. | writable |
mediaLink | string | A URL for downloading the object's data. You should generally use one of the otherJSON API endpoints instead. | |
metadata | object | User-provided metadata, in key-value pairs. | writable |
metadata.(key) | string | An individual metadata entry. | writable |
metageneration | long1 | 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 If | |
owner.entity | string | The entity, in the form"user-emailAddress". | |
owner.entityId | string | The ID for the entity. | |
restoreToken | string | Applicable in buckets withhierarchical namespace enabled. TherestoreToken is a universally unique identifier (UUID) associated with eachsoft-deleted object and can be used in requests to restore a soft-deleted object or retrieve its metadata.The | |
retention | object | The object'sretention configuration, which defines the earliest datetime that the object can be deleted or replaced. | writable |
retention.mode | string | The mode of the retention configuration, which can be eitherUnlocked orLocked. If set toLocked,retention.mode cannot be changed, the retention configuration cannot be removed, andretention.retainUntilTime cannot be reduced. | writable |
retention.retainUntilTime | datetime1 | The earliest time that the object can be deleted or replaced, inRFC 3339 format. This property has a maximum value of 3,155,760,000 seconds (100 years) from the current date and time. | writable |
retentionExpirationTime | datetime1 | The earliest time that the object can be deleted, which depends on anyretention configuration set for the object and anyretention policy set for the bucket that contains the object. The value forretentionExpirationTime is given inRFC 3339 format. | |
selfLink | string | A URL for this object. You should generally use one of the otherJSON API endpoints instead. | |
size | unsigned long1 | Content-Length of the data in bytes. | |
softDeleteTime | datetime | The time at which the object wassoft deleted. Only available for objects in buckets with a soft delete policy. | |
hardDeleteTime | datetime | The time at which a soft-deleted object is permanently deleted and can no longer be restored. The value is the sum of thesoftDeleteTime value and thesoftDeletePolicy.retentionDurationSeconds value of the bucket. Only available for objects in buckets with a soft delete policy. Note that thehardDeleteTime value is permanent once set and does not change in response tosoftDeletePolicy.retentionDurationSeconds changes. | |
storageClass | string | Storage class of the object. To change an object's storage class, useobjects rewrite. | writable |
temporaryHold | boolean | Whether or not the object is subject to atemporary hold. | writable |
timeCreated | datetime1 | The creation time of the object inRFC 3339 format. | |
timeFinalized | datetime1 | The finalization time of the object inRFC 3339 format. | |
timeDeleted | datetime1 | The deletion time of the object inRFC 3339 format. Returned if and only if this version of the object is no longer a live version, but remains in the bucket as anoncurrent version. | |
timeStorageClassUpdated | datetime1 | The time at which the object's storage class was last changed. When the object is initially created, it is set totimeCreated. | |
updated | datetime1 | Themodification time of the object metadata inRFC 3339 format. Set initially to object creation time and then updated whenever any metadata of the object changes. This includes changes made by a requester, such as modifying custom metadata, as well as changes made by Cloud Storage on behalf of a requester, such as changing the storage class based on an Object Lifecycle Configuration. |
Methods
Available methods for Objects resources are as follows:
- bulkRestore
- Asynchronously restores the soft-deleted objects in a bucket.
- 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
generationparameter 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, seeUploads and downloads.
- list
- Retrieves a list of objects matching the criteria.
- move
- Moves an object within a bucket withhierarchical namespace enabled.
- patch
- Updates a data blob's associated metadata. This method supportspatch semantics.
- restore
- Restores a soft-deleted object.
- 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 thereference page.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-17 UTC.