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, "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 } }
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:
|
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:
|
|
acl[].role |
string |
The access permission for the entity.
Acceptable values are:
|
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 and are limited to a count of 1024, counting 1 for each non-composite component object and componentCount for each composite component 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. | |
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 . |
|
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. | |
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 |
timeCreated |
datetime |
The creation time of the object in RFC 3339 format. | |
timeDeleted |
datetime |
The deletion time of the object in RFC 3339 format. Will be returned if and only if this version of the object has been deleted. | |
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.