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 { CreateMultipartUploadOutput, CreateMultipartUploadRequest } from "../models/models_0"; import { S3ClientResolvedConfig, ServiceInputTypes, ServiceOutputTypes } from "../S3Client"; /** * @public * * The input for {@link CreateMultipartUploadCommand}. */ export interface CreateMultipartUploadCommandInput extends CreateMultipartUploadRequest { } /** * @public * * The output of {@link CreateMultipartUploadCommand}. */ export interface CreateMultipartUploadCommandOutput extends CreateMultipartUploadOutput, __MetadataBearer { } /** * @public *

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 UploadPart). 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 Multipart Upload Overview.

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 Aborting * Incomplete Multipart Uploads Using a Bucket Lifecycle Policy.

For information about the permissions required to use the multipart upload API, see * Multipart Upload and * Permissions.

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 Authenticating * Requests (Amazon Web Services Signature Version 4).

* *

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.

* *

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 UploadPart and UploadPartCopy requests must match the headers you used in the request to * initiate the upload by using CreateMultipartUpload.

To perform a multipart upload with encryption using an Amazon Web Services KMS key, the requester must * have permission to the kms:Decrypt and kms:GenerateDataKey* * 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 Multipart upload API * and permissions 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 Protecting * Data Using Server-Side Encryption.

Access Permissions

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:

*
Specify a canned ACL with the x-amz-acl request header. For * more information, see Canned ACL.
*
*
Specify access permissions explicitly with the * x-amz-grant-read, x-amz-grant-read-acp, * x-amz-grant-write-acp, and * x-amz-grant-full-control headers. These parameters map to * the set of permissions that Amazon S3 supports in an ACL. For more information, * see Access Control List (ACL) * Overview.
*

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

Server-Side- Encryption-Specific Request Headers

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.

*
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.
*
- *
  * x-amz-server-side-encryption *
  *
- *
  * x-amz-server-side-encryption-aws-kms-key-id *
  *
- *
  * x-amz-server-side-encryption-context *
  *
* *
If you specify x-amz-server-side-encryption:aws:kms, but * don't provide x-amz-server-side-encryption-aws-kms-key-id, * Amazon S3 uses the Amazon Web Services managed key in Amazon Web Services KMS to protect the data.
* * *
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.
* *
For more information about server-side encryption with KMS key (SSE-KMS), * see Protecting Data Using Server-Side Encryption with KMS keys.
*
*
Use customer-provided encryption keys – If you want to manage your own * encryption keys, provide all the following headers in the request.
*
- *
  * x-amz-server-side-encryption-customer-algorithm *
  *
- *
  * x-amz-server-side-encryption-customer-key *
  *
- *
  * x-amz-server-side-encryption-customer-key-MD5 *
  *
*
For more information about server-side encryption with KMS keys (SSE-KMS), * see Protecting Data Using Server-Side Encryption with KMS keys.
*

Access-Control-List (ACL)-Specific Request Headers

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 Using ACLs. With this * operation, you can grant access permissions using one of the following two * methods:

*
Specify a canned ACL (x-amz-acl) — 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 — 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 Access * Control List (ACL) Overview. In the header, you specify a list of * grantees who get the specific permission. To grant permissions explicitly, * use:
*
- *
  * x-amz-grant-read *
  *
- *
  * x-amz-grant-write *
  *
- *
  * x-amz-grant-read-acp *
  *
- *
  * x-amz-grant-write-acp *
  *
- *
  * x-amz-grant-full-control *
  *
*
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" *
*

The following operations are related to CreateMultipartUpload:

*
* UploadPart *
*
*
* CompleteMultipartUpload *
*
*
* AbortMultipartUpload *
*
*
* ListParts *
*
*
* ListMultipartUploads *
*

* @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 input = { // CreateMultipartUploadRequest * ACL: "private" || "public-read" || "public-read-write" || "authenticated-read" || "aws-exec-read" || "bucket-owner-read" || "bucket-owner-full-control", * Bucket: "STRING_VALUE", // required * CacheControl: "STRING_VALUE", * ContentDisposition: "STRING_VALUE", * ContentEncoding: "STRING_VALUE", * ContentLanguage: "STRING_VALUE", * ContentType: "STRING_VALUE", * Expires: new Date("TIMESTAMP"), * GrantFullControl: "STRING_VALUE", * GrantRead: "STRING_VALUE", * GrantReadACP: "STRING_VALUE", * GrantWriteACP: "STRING_VALUE", * Key: "STRING_VALUE", // required * Metadata: { // Metadata * "": "STRING_VALUE", * }, * ServerSideEncryption: "AES256" || "aws:kms", * StorageClass: "STANDARD" || "REDUCED_REDUNDANCY" || "STANDARD_IA" || "ONEZONE_IA" || "INTELLIGENT_TIERING" || "GLACIER" || "DEEP_ARCHIVE" || "OUTPOSTS" || "GLACIER_IR" || "SNOW", * WebsiteRedirectLocation: "STRING_VALUE", * SSECustomerAlgorithm: "STRING_VALUE", * SSECustomerKey: "STRING_VALUE", * SSECustomerKeyMD5: "STRING_VALUE", * SSEKMSKeyId: "STRING_VALUE", * SSEKMSEncryptionContext: "STRING_VALUE", * BucketKeyEnabled: true || false, * RequestPayer: "requester", * Tagging: "STRING_VALUE", * ObjectLockMode: "GOVERNANCE" || "COMPLIANCE", * ObjectLockRetainUntilDate: new Date("TIMESTAMP"), * ObjectLockLegalHoldStatus: "ON" || "OFF", * ExpectedBucketOwner: "STRING_VALUE", * ChecksumAlgorithm: "CRC32" || "CRC32C" || "SHA1" || "SHA256", * }; * const command = new CreateMultipartUploadCommand(input); * const response = await client.send(command); * ``` * * @param CreateMultipartUploadCommandInput - {@link CreateMultipartUploadCommandInput} * @returns {@link CreateMultipartUploadCommandOutput} * @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. * * * @example To initiate a multipart upload * ```javascript * // The following example initiates a multipart upload. * const input = { * "Bucket": "examplebucket", * "Key": "largeobject" * }; * const command = new CreateMultipartUploadCommand(input); * const response = await client.send(command); * /* response == * { * "Bucket": "examplebucket", * "Key": "largeobject", * "UploadId": "ibZBv_75gd9r8lH_gqXatLdxMVpAlj6ZQjEs.OwyF3953YdwbcQnMA2BLGn8Lx12fQNICtMw5KyteFeHw.Sjng--" * } * *\/ * // example id: to-initiate-a-multipart-upload-1481836794513 * ``` * */ export declare class CreateMultipartUploadCommand extends $Command { readonly input: CreateMultipartUploadCommandInput; static getEndpointParameterInstructions(): EndpointParameterInstructions; /** * @public */ constructor(input: CreateMultipartUploadCommandInput); /** * @internal */ resolveMiddleware(clientStack: MiddlewareStack, configuration: S3ClientResolvedConfig, options?: __HttpHandlerOptions): Handler; /** * @internal */ private serialize; /** * @internal */ private deserialize; }