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:
You specify the method information with standard HTTP methods, such as
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 and bucket name. Used together, the object name, bucket name, and public URI create a unique URL to a given resource. You use HTTP methods to perform operations on these resources. 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.
Access to Cloud Storage through the XML API is useful when you are working with tools and libraries that must work across different storage providers, or when you are migrating from another storage provider to Cloud Storage. In the latter case, you only need to make a few simple changes to your existing tools and libraries to begin sending requests to Cloud Storage. For more information about migrating to Cloud Storage, see Migrating from Amazon S3 to Google Cloud Storage.
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. See XML API Reference Methods for a complete list of the HTTP methods that the Cloud Storage XML API supports.
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
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.|
||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:
GETrequests 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.
GETrequests 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 Request Endpoints.
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
travel-maps. The 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
and the request is scoped so that only objects with the prefix
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>