When creating a bucket, you can specify the geographic location for your bucket as well as the storage class of the bucket.
If you try to create a bucket with an invalid name you will get a
400 Bad Request status code
and the body of the error response will have InvalidBucketName in the
Code element.
You can only create a bucket in projects for which you have permission to
do so. For example, if you have the Storage Admin role on a project, you
have the required permission (storage.objects.create) to create buckets.
Also, because the bucket namespace is global, your bucket name must be unique
across the entire Cloud Storage namespace. If your bucket name is in
use, you get a 409 Conflict
status code and the bucket creation request fails. The body of the error
response contains BucketAlreadyExists in the Code element if the bucket
already exists in the namespace or it contains a BucketAlreadyOwnedByYou in
the Code element if the bucket is owned by you. For more information, see
Bucket naming guidelines and
Object naming guidelines.
Query string parameters
This request does not typically include query string parameters.
See signed URL query string parameters for information on the parameters you include when creating and using signed URLs.
Request headers
In addition to common request headers, the following can be used.
| Header | Description | Required |
|---|---|---|
x-goog-acl |
The predefined access control list (ACL) that you want to apply to the bucket. Do not use if you are using the acl query string parameter to apply ACLs. |
No |
x-goog-bucket-retention-period |
The time, in seconds, that objects in the bucket must be retained before they can be replaced or deleted. | No |
x-goog-project-id |
The project ID of a project. Required unless you have set the default project for interoperable access. | No |
Request body elements
The following request body elements are applicable when creating a bucket. If
you do not specify a request body, Cloud Storage creates a bucket in the
US location with a STANDARD storage class.
| Element | Description |
|---|---|
CreateBucketConfiguration |
Container for create body request. |
LocationConstraint |
A location for the bucket. |
StorageClass |
The storage class of the
bucket, such as STANDARD, NEARLINE,
COLDLINE, or ARCHIVE. |
Request syntax
PUT / HTTP/1.1 Host: BUCKET_NAME.storage.googleapis.com Date: DATE Content-Length: REQUEST_BODY_LENGTH Authorization: AUTHENTICATION_STRING x-goog-project-id: PROJECT_ID x-goog-acl: PREDEFINED_ACL x-goog-bucket-retention-period: TIME_IN_SECONDS <CreateBucketConfiguration> <LocationConstraint>LOCATION</LocationConstraint> <StorageClass>STORAGE_CLASS</StorageClass> </CreateBucketConfiguration>
Response headers
The request can return a variety of response headers depending on the request headers you use.
Response body elements
The response does not include an XML document in the response body.
Example
The following sample creates a Standard Storage bucket named acme-pets in the US location and in the specified project (no request body specified).
Request
PUT / HTTP/1.1 Host: acme-pets.storage.googleapis.com Date: Mon, 15 Feb 2008 21:30:39 GMT Content-Length: 0 x-goog-project-id: 123456789123 Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg <CreateBucketConfiguration> <StorageClass>STANDARD</StorageClass> </CreateBucketConfiguration>
Response
HTTP/1.1 200 OK Date: Mon, 15 Feb 2010 12:30:40 GMT Content-Length: 0