import { EndpointParameterInstructions } from "@aws-sdk/middleware-endpoint"; import { Command as $Command } from "@aws-sdk/smithy-client"; import { Handler, HttpHandlerOptions as __HttpHandlerOptions, MetadataBearer as __MetadataBearer, MiddlewareStack } from "@aws-sdk/types"; import { CreateBucketOutput, CreateBucketRequest } from "../models/models_0"; import { S3ClientResolvedConfig, ServiceInputTypes, ServiceOutputTypes } from "../S3Client"; /** * @public * * The input for {@link CreateBucketCommand}. */ export interface CreateBucketCommandInput extends CreateBucketRequest { } /** * @public * * The output of {@link CreateBucketCommand}. */ export interface CreateBucketCommandOutput extends CreateBucketOutput, __MetadataBearer { } /** * @public *

Creates a new S3 bucket. To create a bucket, you must register with Amazon S3 and have a * valid Amazon Web Services Access Key ID to authenticate requests. Anonymous requests are never allowed to * create buckets. By creating the bucket, you become the bucket owner.

Not every string is an acceptable bucket name. For information about bucket naming * restrictions, see Bucket naming * rules.

If you want to create an Amazon S3 on Outposts bucket, see Create Bucket.

By default, the bucket is created in the US East (N. Virginia) Region. You can * optionally specify a Region in the request body. You might choose a Region to optimize * latency, minimize costs, or address regulatory requirements. For example, if you reside in * Europe, you will probably find it advantageous to create buckets in the Europe (Ireland) * Region. For more information, see Accessing a * bucket.

* *

If you send your create bucket request to the s3.amazonaws.com endpoint, * the request goes to the us-east-1 Region. Accordingly, the signature calculations in * Signature Version 4 must use us-east-1 as the Region, even if the location constraint in * the request specifies another Region where the bucket is to be created. If you create a * bucket in a Region other than US East (N. Virginia), your application must be able to * handle 307 redirect. For more information, see Virtual hosting of * buckets.

* *

Access control lists (ACLs)

When creating a bucket using this operation, you can optionally configure the bucket ACL * to specify the accounts or groups that should be granted specific permissions on the * bucket.

* *

If your CreateBucket request sets bucket owner enforced for S3 Object Ownership and * specifies a bucket ACL that provides access to an external Amazon Web Services account, your request * fails with a 400 error and returns the * InvalidBucketAclWithObjectOwnership error code. For more information, * see Controlling object * ownership in the Amazon S3 User Guide.

* *

There are two ways to grant the appropriate permissions using the request * headers.

*
Specify a canned ACL using the x-amz-acl request header. Amazon S3 * supports a set of predefined ACLs, known as canned ACLs. Each * canned ACL has a predefined set of grantees and permissions. For more information, * see Canned ACL.
*
*
Specify access permissions explicitly using the x-amz-grant-read, * x-amz-grant-write, x-amz-grant-read-acp, * x-amz-grant-write-acp, and x-amz-grant-full-control * headers. These headers map to the set of permissions Amazon S3 supports in an ACL. For * more information, see Access control list (ACL) * overview.
*
You specify each grantee as a type=value pair, where the type is one of the * following:
*
- *
  * id – if the value specified is the canonical user ID of an * Amazon Web Services account
  *
- *
  * uri – if you are granting permissions to a predefined * group
  *
- *
  * emailAddress – if the value specified is the email address of * an Amazon Web Services account
  *
  *
  Using email addresses to specify a grantee is only supported in the following Amazon Web Services Regions:
  *
  - *
    US East (N. Virginia)
    *
  - *
    US West (N. California)
    *
  - *
    US West (Oregon)
    *
  - *
    Asia Pacific (Singapore)
    *
  - *
    Asia Pacific (Sydney)
    *
  - *
    Asia Pacific (Tokyo)
    *
  - *
    Europe (Ireland)
    *
  - *
    South America (São Paulo)
    *
  *
  For a list of all the Amazon S3 supported Regions and endpoints, see Regions and Endpoints in the Amazon Web Services General Reference.
  *
  *
*
For example, the following x-amz-grant-read header grants the Amazon Web Services accounts identified by account IDs permissions to read object data and its metadata:
*
* x-amz-grant-read: id="11112222333", id="444455556666" *
*

* *

You can use either a canned ACL or specify access permissions explicitly. You cannot * do both.

* *

Permissions

In addition to s3:CreateBucket, the following permissions are required when * your CreateBucket includes specific headers:

*
* ACLs - If your CreateBucket request * specifies ACL permissions and the ACL is public-read, public-read-write, * authenticated-read, or if you specify access permissions explicitly through any other * ACL, both s3:CreateBucket and s3:PutBucketAcl permissions * are needed. If the ACL the CreateBucket request is private or doesn't * specify any ACLs, only s3:CreateBucket permission is needed.
*
*
* Object Lock - If * ObjectLockEnabledForBucket is set to true in your * CreateBucket request, * s3:PutBucketObjectLockConfiguration and * s3:PutBucketVersioning permissions are required.
*
*
* S3 Object Ownership - If your CreateBucket * request includes the x-amz-object-ownership header, * s3:PutBucketOwnershipControls permission is required.
*

The following operations are related to CreateBucket:

*
* PutObject *
*
*
* DeleteBucket *
*

* @example * Use a bare-bones client and the command you need to make an API call. * ```javascript * import { S3Client, CreateBucketCommand } from "@aws-sdk/client-s3"; // ES Modules import * // const { S3Client, CreateBucketCommand } = require("@aws-sdk/client-s3"); // CommonJS import * const client = new S3Client(config); * const input = { // CreateBucketRequest * ACL: "private" || "public-read" || "public-read-write" || "authenticated-read", * Bucket: "STRING_VALUE", // required * CreateBucketConfiguration: { // CreateBucketConfiguration * LocationConstraint: "af-south-1" || "ap-east-1" || "ap-northeast-1" || "ap-northeast-2" || "ap-northeast-3" || "ap-south-1" || "ap-southeast-1" || "ap-southeast-2" || "ap-southeast-3" || "ca-central-1" || "cn-north-1" || "cn-northwest-1" || "EU" || "eu-central-1" || "eu-north-1" || "eu-south-1" || "eu-west-1" || "eu-west-2" || "eu-west-3" || "me-south-1" || "sa-east-1" || "us-east-2" || "us-gov-east-1" || "us-gov-west-1" || "us-west-1" || "us-west-2", * }, * GrantFullControl: "STRING_VALUE", * GrantRead: "STRING_VALUE", * GrantReadACP: "STRING_VALUE", * GrantWrite: "STRING_VALUE", * GrantWriteACP: "STRING_VALUE", * ObjectLockEnabledForBucket: true || false, * ObjectOwnership: "BucketOwnerPreferred" || "ObjectWriter" || "BucketOwnerEnforced", * }; * const command = new CreateBucketCommand(input); * const response = await client.send(command); * // { // CreateBucketOutput * // Location: "STRING_VALUE", * // }; * * ``` * * @param CreateBucketCommandInput - {@link CreateBucketCommandInput} * @returns {@link CreateBucketCommandOutput} * @see {@link CreateBucketCommandInput} for command's `input` shape. * @see {@link CreateBucketCommandOutput} for command's `response` shape. * @see {@link S3ClientResolvedConfig | config} for S3Client's `config` shape. * * @throws {@link BucketAlreadyExists} (client fault) *

The requested bucket name is not available. The bucket namespace is shared by all users * of the system. Select a different name and try again.

* * @throws {@link BucketAlreadyOwnedByYou} (client fault) *

The bucket you tried to create already exists, and you own it. Amazon S3 returns this error * in all Amazon Web Services Regions except in the North Virginia Region. For legacy compatibility, if you * re-create an existing bucket that you already own in the North Virginia Region, Amazon S3 * returns 200 OK and resets the bucket access control lists (ACLs).

* * @throws {@link S3ServiceException} *

Base exception class for all service exceptions from S3 service.

* * @example To create a bucket * ```javascript * // The following example creates a bucket. * const input = { * "Bucket": "examplebucket" * }; * const command = new CreateBucketCommand(input); * const response = await client.send(command); * /* response == * { * "Location": "/examplebucket" * } * *\/ * // example id: to-create-a-bucket--1472851826060 * ``` * * @example To create a bucket in a specific region * ```javascript * // The following example creates a bucket. The request specifies an AWS region where to create the bucket. * const input = { * "Bucket": "examplebucket", * "CreateBucketConfiguration": { * "LocationConstraint": "eu-west-1" * } * }; * const command = new CreateBucketCommand(input); * const response = await client.send(command); * /* response == * { * "Location": "http://examplebucket..s3.amazonaws.com/" * } * *\/ * // example id: to-create-a-bucket-in-a-specific-region-1483399072992 * ``` * */ export declare class CreateBucketCommand extends $Command { readonly input: CreateBucketCommandInput; static getEndpointParameterInstructions(): EndpointParameterInstructions; /** * @public */ constructor(input: CreateBucketCommandInput); /** * @internal */ resolveMiddleware(clientStack: MiddlewareStack, configuration: S3ClientResolvedConfig, options?: __HttpHandlerOptions): Handler; /** * @internal */ private serialize; /** * @internal */ private deserialize; }