@aws-sdk/client-s3

import { Command as $Command } from "@aws-sdk/smithy-client"; import { Handler, HttpHandlerOptions as __HttpHandlerOptions, MetadataBearer as __MetadataBearer, MiddlewareStack } from "@aws-sdk/types"; import { CreateMultipartUploadOutput, CreateMultipartUploadRequest } from "../models/models_0"; import { S3ClientResolvedConfig, ServiceInputTypes, ServiceOutputTypes } from "../S3Client"; export interface CreateMultipartUploadCommandInput extends CreateMultipartUploadRequest { } export interface CreateMultipartUploadCommandOutput extends CreateMultipartUploadOutput, __MetadataBearer { } /** * This action initiates a multipart upload and returns an upload ID. This upload ID is * used to associate all of the parts in the specific multipart upload. You specify this * upload ID in each of your subsequent upload part requests (see <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html">UploadPart</a>). You also include this * upload ID in the final request to either complete or abort the multipart upload * request. * * For more information about multipart uploads, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/mpuoverview.html">Multipart Upload Overview</a>. * * If you have configured a lifecycle rule to abort incomplete multipart uploads, the * upload must complete within the number of days specified in the bucket lifecycle * configuration. Otherwise, the incomplete multipart upload becomes eligible for an abort * action and Amazon S3 aborts the multipart upload. For more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/mpuoverview.html#mpu-abort-incomplete-mpu-lifecycle-config">Aborting * Incomplete Multipart Uploads Using a Bucket Lifecycle Policy</a>. * * For information about the permissions required to use the multipart upload API, see * <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/mpuAndPermissions.html">Multipart Upload and * Permissions</a>. * * For request signing, multipart upload is just a series of regular requests. You initiate * a multipart upload, send one or more requests to upload parts, and then complete the * multipart upload process. You sign each request individually. There is nothing special * about signing multipart upload requests. For more information about signing, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html">Authenticating * Requests (Amazon Web Services Signature Version 4)</a>. * * <note> * After you initiate a multipart upload and upload one or more parts, to stop being * charged for storing the uploaded parts, you must either complete or abort the multipart * upload. Amazon S3 frees up the space used to store the parts and stop charging you for * storing them only after you either complete or abort a multipart upload. * </note> * * You can optionally request server-side encryption. For server-side encryption, Amazon S3 * encrypts your data as it writes it to disks in its data centers and decrypts it when you * access it. You can provide your own encryption key, or use Amazon Web Services KMS keys or Amazon S3-managed encryption keys. If you choose to provide * your own encryption key, the request headers you provide in <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html">UploadPart</a> and <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPartCopy.html">UploadPartCopy</a> requests must match the headers you used in the request to * initiate the upload by using <code>CreateMultipartUpload</code>. * To perform a multipart upload with encryption using an Amazon Web Services KMS key, the requester must * have permission to the <code>kms:Decrypt</code> and <code>kms:GenerateDataKey*</code> * actions on the key. These permissions are required because Amazon S3 must decrypt and read data * from the encrypted file parts before it completes the multipart upload. For more * information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html#mpuAndPermissions">Multipart upload API * and permissions</a> in the Amazon S3 User Guide. * * If your Identity and Access Management (IAM) user or role is in the same Amazon Web Services account * as the KMS key, then you must have these permissions on the key policy. If your IAM * user or role belongs to a different account than the key, then you must have the * permissions on both the key policy and your IAM user or role. * * * For more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/serv-side-encryption.html">Protecting * Data Using Server-Side Encryption</a>. * * <dl> * <dt>Access Permissions</dt> * <dd> * When copying an object, you can optionally specify the accounts or groups that * should be granted specific permissions on the new object. There are two ways to * grant the permissions using the request headers: * <ul> * <li> * Specify a canned ACL with the <code>x-amz-acl</code> request header. 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 with the * <code>x-amz-grant-read</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 parameters map to * the set of permissions that Amazon S3 supports in an ACL. For more information, * see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html">Access Control List (ACL) * Overview</a>. * </li> * </ul> * You can use either a canned ACL or specify access permissions explicitly. You * cannot do both. * </dd> * <dt>Server-Side- Encryption-Specific Request Headers</dt> * <dd> * You can optionally tell Amazon S3 to encrypt data at rest using server-side * encryption. Server-side encryption is for data encryption at rest. Amazon S3 encrypts * your data as it writes it to disks in its data centers and decrypts it when you * access it. The option you use depends on whether you want to use Amazon Web Services managed * encryption keys or provide your own encryption key. * <ul> * <li> * Use encryption keys managed by Amazon S3 or customer managed key stored * in Amazon Web Services Key Management Service (Amazon Web Services KMS) – If you want Amazon Web Services to manage the keys * used to encrypt data, specify the following headers in the request. * <ul> * <li> * * <code>x-amz-server-side-encryption</code> * * </li> * <li> * * <code>x-amz-server-side-encryption-aws-kms-key-id</code> * * </li> * <li> * * <code>x-amz-server-side-encryption-context</code> * * </li> * </ul> * <note> * If you specify <code>x-amz-server-side-encryption:aws:kms</code>, but * don't provide <code>x-amz-server-side-encryption-aws-kms-key-id</code>, * Amazon S3 uses the Amazon Web Services managed key in Amazon Web Services KMS to protect the data. * </note> * <important> * All GET and PUT requests for an object protected by Amazon Web Services KMS fail if * you don't make them with SSL or by using SigV4. * </important> * For more information about server-side encryption with KMS key (SSE-KMS), * see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingKMSEncryption.html">Protecting Data Using Server-Side Encryption with KMS keys</a>. * </li> * <li> * Use customer-provided encryption keys – If you want to manage your own * encryption keys, provide all the following headers in the request. * <ul> * <li> * * <code>x-amz-server-side-encryption-customer-algorithm</code> * * </li> * <li> * * <code>x-amz-server-side-encryption-customer-key</code> * * </li> * <li> * * <code>x-amz-server-side-encryption-customer-key-MD5</code> * * </li> * </ul> * For more information about server-side encryption with KMS keys (SSE-KMS), * see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingKMSEncryption.html">Protecting Data Using Server-Side Encryption with KMS keys</a>. * </li> * </ul> * </dd> * <dt>Access-Control-List (ACL)-Specific Request Headers</dt> * <dd> * You also can use the following access control–related headers with this * operation. By default, all objects are private. Only the owner has full access * control. When adding a new object, you can grant permissions to individual Amazon Web Services accounts or to predefined groups defined by Amazon S3. These permissions are then added * to the access control list (ACL) on the object. For more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/S3_ACLs_UsingACLs.html">Using ACLs</a>. With this * operation, you can grant access permissions using one of the following two * methods: * <ul> * <li> * Specify a canned ACL (<code>x-amz-acl</code>) — 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 — To explicitly grant access * permissions to specific Amazon Web Services accounts or groups, use the following headers. * Each header maps to specific permissions that Amazon S3 supports in an ACL. For * more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html">Access * Control List (ACL) Overview</a>. In the header, you specify a list of * grantees who get the specific permission. To grant permissions explicitly, * use: * <ul> * <li> * * <code>x-amz-grant-read</code> * * </li> * <li> * * <code>x-amz-grant-write</code> * * </li> * <li> * * <code>x-amz-grant-read-acp</code> * * </li> * <li> * * <code>x-amz-grant-write-acp</code> * * </li> * <li> * * <code>x-amz-grant-full-control</code> * * </li> * </ul> * 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> * * </dd> * </dl> * * The following operations are related to <code>CreateMultipartUpload</code>: * <ul> * <li> * * <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html">UploadPart</a> * * </li> * <li> * * <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html">CompleteMultipartUpload</a> * * </li> * <li> * * <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html">AbortMultipartUpload</a> * * </li> * <li> * * <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html">ListParts</a> * * </li> * <li> * * <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html">ListMultipartUploads</a> * * </li> * </ul> * @example * Use a bare-bones client and the command you need to make an API call. * ```javascript * import { S3Client, CreateMultipartUploadCommand } from "@aws-sdk/client-s3"; // ES Modules import * // const { S3Client, CreateMultipartUploadCommand } = require("@aws-sdk/client-s3"); // CommonJS import * const client = new S3Client(config); * const command = new CreateMultipartUploadCommand(input); * const response = await client.send(command); * ``` * * @see {@link CreateMultipartUploadCommandInput} for command's `input` shape. * @see {@link CreateMultipartUploadCommandOutput} for command's `response` shape. * @see {@link S3ClientResolvedConfig | config} for S3Client's `config` shape. * */ export declare class CreateMultipartUploadCommand extends $Command<CreateMultipartUploadCommandInput, CreateMultipartUploadCommandOutput, S3ClientResolvedConfig> { readonly input: CreateMultipartUploadCommandInput; constructor(input: CreateMultipartUploadCommandInput); /** * @internal */ resolveMiddleware(clientStack: MiddlewareStack<ServiceInputTypes, ServiceOutputTypes>, configuration: S3ClientResolvedConfig, options?: __HttpHandlerOptions): Handler<CreateMultipartUploadCommandInput, CreateMultipartUploadCommandOutput>; private serialize; private deserialize; }