@aws-sdk/client-s3

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"; export interface CreateBucketCommandInput extends CreateBucketRequest { } export interface CreateBucketCommandOutput extends CreateBucketOutput, __MetadataBearer { } /** * 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 <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html">Bucket naming rules</a>. * If you want to create an Amazon S3 on Outposts bucket, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_CreateBucket.html">Create Bucket</a>. * 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 <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html#access-bucket-intro">Accessing a * bucket</a>. * <note> * If you send your create bucket request to the <code>s3.amazonaws.com</code> 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 <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html">Virtual hosting of buckets</a>. * </note> * * 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. * <important> * 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 <code>400</code> error and returns the * <code>InvalidBucketAclWithObjectOwnership</code> error code. For more information, * see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/about-object-ownership.html">Controlling object * ownership</a> in the Amazon S3 User Guide. * </important> * There are two ways to grant the appropriate permissions using the request headers. * <ul> * <li> * Specify a canned ACL using the <code>x-amz-acl</code> 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 <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#CannedACL">Canned ACL</a>. * </li> * <li> * Specify access permissions explicitly using the <code>x-amz-grant-read</code>, * <code>x-amz-grant-write</code>, <code>x-amz-grant-read-acp</code>, * <code>x-amz-grant-write-acp</code>, and <code>x-amz-grant-full-control</code> * headers. These headers map to the set of permissions Amazon S3 supports in an ACL. For * more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html">Access control list * (ACL) overview</a>. * You specify each grantee as a type=value pair, where the type is one of the * following: * <ul> * <li> * * <code>id</code> – if the value specified is the canonical user ID of an Amazon Web Services account * </li> * <li> * * <code>uri</code> – if you are granting permissions to a predefined * group * </li> * <li> * * <code>emailAddress</code> – if the value specified is the email address of * an Amazon Web Services account * <note> * Using email addresses to specify a grantee is only supported in the following Amazon Web Services Regions: * <ul> * <li> * US East (N. Virginia) * </li> * <li> * US West (N. California) * </li> * <li> * US West (Oregon) * </li> * <li> * Asia Pacific (Singapore) * </li> * <li> * Asia Pacific (Sydney) * </li> * <li> * Asia Pacific (Tokyo) * </li> * <li> * Europe (Ireland) * </li> * <li> * South America (São Paulo) * </li> * </ul> * For a list of all the Amazon S3 supported Regions and endpoints, see <a href="https://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region">Regions and Endpoints</a> in the Amazon Web Services General Reference. * </note> * </li> * </ul> * For example, the following <code>x-amz-grant-read</code> header grants the Amazon Web Services accounts identified by account IDs permissions to read object data and its metadata: * * <code>x-amz-grant-read: id="11112222333", id="444455556666" </code> * * </li> * </ul> * <note> * You can use either a canned ACL or specify access permissions explicitly. You cannot * do both. * </note> * * * Permissions * * In addition to <code>s3:CreateBucket</code>, the following permissions are required when your CreateBucket includes specific headers: * <ul> * <li> * * ACLs - If your <code>CreateBucket</code> 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 * <code>s3:CreateBucket</code> and <code>s3:PutBucketAcl</code> permissions are needed. If the ACL the * <code>CreateBucket</code> request is private or doesn't specify any ACLs, only <code>s3:CreateBucket</code> permission is needed. * </li> * <li> * * Object Lock - If * <code>ObjectLockEnabledForBucket</code> is set to true in your * <code>CreateBucket</code> request, * <code>s3:PutBucketObjectLockConfiguration</code> and * <code>s3:PutBucketVersioning</code> permissions are required. * </li> * <li> * * S3 Object Ownership - If your CreateBucket * request includes the the <code>x-amz-object-ownership</code> header, * <code>s3:PutBucketOwnershipControls</code> permission is required. * </li> * </ul> * The following operations are related to <code>CreateBucket</code>: * <ul> * <li> * * <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html">PutObject</a> * * </li> * <li> * * <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucket.html">DeleteBucket</a> * * </li> * </ul> * @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 command = new CreateBucketCommand(input); * const response = await client.send(command); * ``` * * @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. * */ export declare class CreateBucketCommand extends $Command<CreateBucketCommandInput, CreateBucketCommandOutput, S3ClientResolvedConfig> { readonly input: CreateBucketCommandInput; static getEndpointParameterInstructions(): EndpointParameterInstructions; constructor(input: CreateBucketCommandInput); /** * @internal */ resolveMiddleware(clientStack: MiddlewareStack<ServiceInputTypes, ServiceOutputTypes>, configuration: S3ClientResolvedConfig, options?: __HttpHandlerOptions): Handler<CreateBucketCommandInput, CreateBucketCommandOutput>; private serialize; private deserialize; }