This document gives an overview of the Cloud Storage XML API and is intended for developers. It assumes that you are familiar with web programming and you are comfortable creating applications that consume web services through HTTP requests.
As an alternative to creating HTTP requests and parsing responses manually using the XML API, you can use the Cloud Storage Client Libraries, the gsutil tool, or the Cloud Storage UI, Google Cloud Platform Console. If you are looking to store data for a mobile or web application, Firebase SDKs for Cloud Storage are the quickest way to get started.
Cloud Storage XML API is a RESTful interface that lets you manage Cloud Storage data in a programmatic way. As a RESTful API, it relies on method information and scoping information to define the operations to perform:
- Method information
- You specify the method information with standard HTTP methods, such as DELETE, GET, HEAD, and PUT.
- Scoping information
- You specify the scoping information with a publicly-accessible endpoint (URI) and various scoping parameters. In this case, the primary scoping parameter is a path to a resource, which consists of an object name (file name) and bucket name (container name). Used together, the object name, bucket name, and public URI create a unique URL to a given resource—a resource on which you can perform operations with HTTP methods. You can further scope your operations by using HTTP headers and query string parameters.
For detailed programming information about the Cloud Storage XML API, see the Reference Guide.
We recommend that you use HTTPS when reading or writing data to Cloud Storage so that your data is encrypted during transfer. Cloud Storage automatically encrypts your data before it is written to disk. For more information, see Encryption.
In practical terms, the Cloud Storage XML API provides a web interface for making HTTP requests and handling HTTP responses. Each request implements a standard HTTP method. The Cloud Storage XML API supports the following HTTP methods:
- GET Service—lists all of the buckets that you own.
- DELETE Bucket—deletes an empty bucket.
- GET Bucket—lists the contents of a bucket or retrieves the ACLs that are applied to a bucket.
- HEAD Bucket—indicates if a bucket exists and whether the requester has READ access to it.
- PUT Bucket—creates a bucket and changes the permissions on a bucket.
- DELETE Object—deletes an object.
- GET Object—downloads an object or retrieves the ACLs that are applied to an object.
- HEAD Object—lists the metadata for an object.
- POST Object—uploads an object by using HTML forms.
- PUT Object—uploads an object or applies new ACLs to an object.
You can use various HTTP request headers with each of these methods. The Cloud Storage XML API supports HTTP/1.1 request headers. It also supports several extension (custom) request headers, which have an
x-goog- prefix. Request header requirements vary depending on the kind of request you're making, but a few request headers are required for every request. The following table describes some frequently used request headers, including required headers:
||The authentication string for requests.||Required for all authenticated requests.|
||The cache control that you want to be used when someone retrieves an object.||Optional|
||The size of the request body (excluding headers) in bytes.||Required for all PUT and POST requests.|
||The MD5 digest of the request body. Cloud Storage can use this to check the integrity of a PUT operation.||Optional.|
||The MIME type of the request body, such as
||Recommended for requests that contain an entity body.|
||The date and time of the request||Required for all requests.|
||The URI for the request.||Required for all requests.|
||The predefined access control list (ACL) that you want to apply to a bucket or object.||Optional.|
||This header is deprecated. There is only one version of the XML API and a version is not required.||Deprecated.|
||The ID of the project you want to use.||Required for creating buckets or listing buckets when using the Cloud Storage XML API in non-interoperable use case. Not required when you are using the XML API for interoperability, such as for compatibility with Amazon S3. For more information, see Migrating from Amazon S3 to Google Cloud Storage.|
The Cloud Storage XML API also supports several query string parameters, which you can use to scope your requests. The query string parameters follow the HTTP path portion of the request and must be used in the following standard form:
The most frequently-used query string parameters include the following:
acl—used with PUT and GET requests to change or apply object or bucket permissions.
delimiter—used with list object requests to limit the scope of the returned list.
max-keys—used with list object requests to specify the maximum number of objects you want in the returned list.
marker—used with list object requests to specify which object you want the returned list to begin with.
prefix—used with list object requests to limit the number of objects that are returned in the list to only those with the given prefix.
location—used with GET requests to retrieve the geographical location of a bucket.
All requests to Cloud Storage must be authenticated, with the exception of requests made to anonymously accessible objects or buckets. For detailed information about how you set the Authorization headers for Cloud Storage requests, see Authentication.
Most Cloud Storage requests use the following URI for accessing buckets and objects:
You can scope this further by adding a bucket and object to the URI. The resulting URL can take two forms:
You can use the Cloud Storage URI with unsecured requests (HTTP) and secured requests (HTTPS) that
use secure sockets layer (SSL) encryption. Cloud Storage also provides other request endpoints, which
you must use if you are redirecting a request with a
CNAME alias or you are providing
authenticated browser downloads. In addition, there are custom endpoints that can be used for just
uploading or downloading data. For more information about these additional endpoints, see
A typical authenticated Cloud Storage request is shown in the following example. This request
retrieves a list of objects that are stored in a bucket named
request limits the list of objects to only those objects that have the prefix
GET /?prefix=/europe/france/ HTTP/1.1 Host: travel-maps.storage.googleapis.com Date: Wed, 17 Feb 2010 15:31:56 -0800 Content-Length: 0 x-goog-api-version: 2 Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
The Cloud Storage XML API returns standard HTTP/1.1 response headers and several extension (custom) response headers. The response headers vary according to the operation you perform. Some frequently used response headers are listed in the following table:
||The cache control setting for the response.|
||The size of the response body (excluding headers) in bytes.|
||The MIME type of the response body, such as
||The date and time of the response|
||An HTTP 1.1 entity tag, which you can use to determine whether an object has changed.|
Responses can also include a status code. Cloud Storage uses the standard HTTP/1.1 status codes. Error responses include an XML document in the response body, which contains information about the error conditions.
A typical Cloud Storage response is shown in the following example. This example is a response to a list bucket request. The bucket name is travel-maps and the request is scoped so that only objects with the prefix /europe/france/ are returned in the list.
HTTP/1.1 200 OK Content-Length: 4061 Content-Type: application/xml Date: Wed, 17 Feb 2010 23:31:57 GMT Cache-Control: private, max-age=0 <?xml version='1.0' encoding='utf-8'?> <ListBucketResult xmlns='http://doc.storage.googleapis.com/2010-03-01'> <Name>travel-maps</Name> <Prefix>/europe/france/</Prefix> <Marker></Marker> <IsTruncated>false</IsTruncated> <Contents> <Key>europe/france/cannes.jpg</Key> <LastModified>2010-02-17T22:11:12.487Z</LastModified> <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag> <Size>5061631</Size> <StorageClass>MULTI_REGIONAL</StorageClass> <Owner> <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID> <DisplayName></DisplayName> </Owner> </Contents> <Contents> <Key>europe/france/paris.jpg</Key> <LastModified>2010-02-17T22:09:57.457Z</LastModified> <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag> <Size>5061631</Size> <StorageClass>MULTI_REGIONAL</StorageClass> <Owner> <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID> <DisplayName></DisplayName> </Owner> </Contents> </ListBucketResult>