@aws-sdk/client-s3 3.460.0 → 3.462.0

package/dist-types/commands/CopyObjectCommand.d.ts

@@ -31,213 +31,141 @@ export interface CopyObjectCommandOutput extends CopyObjectOutput, __MetadataBea
  *             (UploadPartCopy) API. For more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/CopyingObjctsUsingRESTMPUapi.html">Copy Object Using the
  *                REST Multipart Upload API</a>.</p>
  *          </note>
- *          <p>All copy requests must be authenticated. Additionally, you must have
- *             <i>read</i> access to the source object and <i>write</i>
- *          access to the destination bucket. For more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html">REST Authentication</a>. Both the
- *          Region that you want to copy the object from and the Region that you want to copy the
- *          object to must be enabled for your account.</p>
- *          <p>A copy request might return an error when Amazon S3 receives the copy request or while Amazon S3
- *          is copying the files. If the error occurs before the copy action starts, you receive a
- *          standard Amazon S3 error. If the error occurs during the copy operation, the error response is
- *          embedded in the <code>200 OK</code> response. This means that a <code>200 OK</code>
- *          response can contain either a success or an error. If you call the S3 API directly, make
- *          sure to design your application to parse the contents of the response and handle it
- *          appropriately. If you use Amazon Web Services SDKs, SDKs handle this condition. The SDKs detect the
- *          embedded error and apply error handling per your configuration settings (including
- *          automatically retrying the request as appropriate). If the condition persists, the SDKs
- *          throws an exception (or, for the SDKs that don't use exceptions, they return the
- *          error).</p>
- *          <p>If the copy is successful, you receive a response with information about the copied
- *          object.</p>
+ *          <p>You can copy individual objects between general purpose buckets, between directory buckets, and
+ *          between general purpose buckets and directory buckets.</p>
  *          <note>
- *             <p>If the request is an HTTP 1.1 request, the response is chunk encoded. If it were not,
- *             it would not contain the content-length, and you would need to read the entire
- *             body.</p>
+ *             <p>
+ *                <b>Directory buckets </b> - For directory buckets, you must make requests for this API operation to the Zonal endpoint. These endpoints support virtual-hosted-style requests in the format <code>https://<i>bucket_name</i>.s3express-<i>az_id</i>.<i>region</i>.amazonaws.com/<i>key-name</i>
+ *                </code>. Path-style requests are not supported. For more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-Regions-and-Zones.html">Regional and Zonal endpoints</a> in the
+ *     <i>Amazon S3 User Guide</i>.</p>
  *          </note>
- *          <p>The copy request charge is based on the storage class and Region that you specify for
- *          the destination object. The request can also result in a data retrieval charge for the
- *          source if the source storage class bills for data retrieval. For pricing information, see
- *             <a href="http://aws.amazon.com/s3/pricing/">Amazon S3 pricing</a>.</p>
+ *          <p>Both the
+ *       Region that you want to copy the object from and the Region that you want to copy the
+ *       object to must be enabled for your account.</p>
  *          <important>
  *             <p>Amazon S3 transfer acceleration does not support cross-Region copies. If you request a
- *             cross-Region copy using a transfer acceleration endpoint, you get a 400 <code>Bad
+ *             cross-Region copy using a transfer acceleration endpoint, you get a <code>400 Bad
  *                Request</code> error. For more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/transfer-acceleration.html">Transfer
- *             Acceleration</a>.</p>
+ *                   Acceleration</a>.</p>
  *          </important>
  *          <dl>
- *             <dt>Metadata</dt>
+ *             <dt>Authentication and authorization</dt>
  *             <dd>
- *                <p>When copying an object, you can preserve all metadata (the default) or specify
- *                   new metadata. However, the access control list (ACL) is not preserved and is set
- *                   to private for the user making the request. To override the default ACL setting,
- *                   specify a new ACL when generating a copy request. For more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/S3_ACLs_UsingACLs.html">Using
- *                      ACLs</a>. </p>
- *                <p>To specify whether you want the object metadata copied from the source object
- *                   or replaced with metadata provided in the request, you can optionally add the
- *                      <code>x-amz-metadata-directive</code> header. When you grant permissions, you
- *                   can use the <code>s3:x-amz-metadata-directive</code> condition key to enforce
- *                   certain metadata behavior when objects are uploaded. For more information, see
- *                      <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/amazon-s3-policy-keys.html">Specifying Conditions in a
- *                      Policy</a> in the <i>Amazon S3 User Guide</i>. For a complete list
- *                   of Amazon S3-specific condition keys, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/list_amazons3.html">Actions, Resources, and Condition
- *                      Keys for Amazon S3</a>.</p>
- *                <note>
- *                   <p>
- *                      <code>x-amz-website-redirect-location</code> is unique to each object and
- *                      must be specified in the request headers to copy the value.</p>
- *                </note>
+ *                <p>All <code>CopyObject</code> requests must be authenticated and signed by using IAM credentials (access key ID and secret access key for the IAM identities). All headers with the <code>x-amz-</code> prefix, including
+ *                         <code>x-amz-copy-source</code>, must be signed. For more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html">REST Authentication</a>.</p>
+ *                <p>
+ *                   <b>Directory buckets</b> - You must use the IAM credentials to authenticate and authorize your access to the <code>CopyObject</code> API operation, instead of using the
+ *                   temporary security credentials through the <code>CreateSession</code> API operation.</p>
+ *                <p>Amazon Web Services CLI or SDKs handles authentication and authorization on your behalf.</p>
  *             </dd>
- *             <dt>x-amz-copy-source-if Headers</dt>
+ *             <dt>Permissions</dt>
  *             <dd>
- *                <p>To only copy an object under certain conditions, such as whether the
- *                      <code>Etag</code> matches or whether the object was modified before or after a
- *                   specified date, use the following request parameters:</p>
- *                <ul>
- *                   <li>
- *                      <p>
- *                         <code>x-amz-copy-source-if-match</code>
- *                      </p>
- *                   </li>
- *                   <li>
- *                      <p>
- *                         <code>x-amz-copy-source-if-none-match</code>
- *                      </p>
- *                   </li>
- *                   <li>
- *                      <p>
- *                         <code>x-amz-copy-source-if-unmodified-since</code>
- *                      </p>
- *                   </li>
- *                   <li>
- *                      <p>
- *                         <code>x-amz-copy-source-if-modified-since</code>
- *                      </p>
- *                   </li>
- *                </ul>
- *                <p> If both the <code>x-amz-copy-source-if-match</code> and
- *                      <code>x-amz-copy-source-if-unmodified-since</code> headers are present in the
- *                   request and evaluate as follows, Amazon S3 returns <code>200 OK</code> and copies the
- *                   data:</p>
+ *                <p>You must have
+ *                   <i>read</i> access to the source object and <i>write</i>
+ *                   access to the destination bucket.</p>
  *                <ul>
  *                   <li>
  *                      <p>
- *                         <code>x-amz-copy-source-if-match</code> condition evaluates to
- *                         true</p>
+ *                         <b>General purpose bucket permissions</b> -
+ *                         You must have permissions in an IAM policy based on the source and destination
+ *                         bucket types in a <code>CopyObject</code> operation.</p>
+ *                      <ul>
+ *                         <li>
+ *                            <p>If the source object is in a general purpose bucket, you must have
+ *                                  <b>
+ *                                  <code>s3:GetObject</code>
+ *                               </b>
+ *                               permission to read the source object that is being copied. </p>
+ *                         </li>
+ *                         <li>
+ *                            <p>If the destination bucket is a general purpose bucket, you must have
+ *                                  <b>
+ *                                  <code>s3:PubObject</code>
+ *                               </b>
+ *                               permission to write the object copy to the destination bucket. </p>
+ *                         </li>
+ *                      </ul>
  *                   </li>
  *                   <li>
  *                      <p>
- *                         <code>x-amz-copy-source-if-unmodified-since</code> condition evaluates to
- *                         false</p>
+ *                         <b>Directory bucket permissions</b> -
+ *                         You must have permissions in a bucket policy or an IAM identity-based policy based on the source and destination
+ *                         bucket types in a <code>CopyObject</code> operation.</p>
+ *                      <ul>
+ *                         <li>
+ *                            <p>If the source object that you want to copy is in a
+ *                               directory bucket, you must have the <b>
+ *                                  <code>s3express:CreateSession</code>
+ *                               </b> permission in
+ *                               the <code>Action</code> element of a policy to read the object. By default, the session is in the <code>ReadWrite</code> mode. If you want to restrict the access, you can explicitly set the <code>s3express:SessionMode</code> condition key to <code>ReadOnly</code> on the copy source bucket.</p>
+ *                         </li>
+ *                         <li>
+ *                            <p>If the copy destination is a directory bucket, you must have the <b>
+ *                                  <code>s3express:CreateSession</code>
+ *                               </b> permission in the
+ *                                  <code>Action</code> element of a policy to write the object
+ *                               to the destination. The <code>s3express:SessionMode</code> condition
+ *                               key can't be set to <code>ReadOnly</code> on the copy destination bucket. </p>
+ *                         </li>
+ *                      </ul>
+ *                      <p>For example policies, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-security-iam-example-bucket-policies.html">Example bucket policies for S3 Express One Zone</a> and <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-security-iam-identity-policies.html">Amazon Web Services Identity and Access Management (IAM) identity-based policies for S3 Express One Zone</a> in the
+ *                            <i>Amazon S3 User Guide</i>.</p>
  *                   </li>
  *                </ul>
- *                <p>If both the <code>x-amz-copy-source-if-none-match</code> and
- *                      <code>x-amz-copy-source-if-modified-since</code> headers are present in the
- *                   request and evaluate as follows, Amazon S3 returns the <code>412 Precondition
- *                      Failed</code> response code:</p>
+ *             </dd>
+ *             <dt>Response and special errors</dt>
+ *             <dd>
+ *                <p>When the request is an HTTP 1.1 request, the response is chunk encoded.
+ *                   When the request is not an HTTP 1.1 request, the response would not contain the <code>Content-Length</code>.
+ *                   You always need to read the entire response body to check if the copy succeeds.
+ *                   to keep the connection alive while we copy the data. </p>
  *                <ul>
  *                   <li>
- *                      <p>
- *                         <code>x-amz-copy-source-if-none-match</code> condition evaluates to
- *                         false</p>
+ *                      <p>If the copy is successful, you receive a response with information about the copied
+ *                      object.</p>
  *                   </li>
  *                   <li>
- *                      <p>
- *                         <code>x-amz-copy-source-if-modified-since</code> condition evaluates to
- *                         true</p>
+ *                      <p>A copy request might return an error when Amazon S3 receives the copy request or while Amazon S3
+ *                         is copying the files. A <code>200 OK</code> response can contain either a success or an error.</p>
+ *                      <ul>
+ *                         <li>
+ *                            <p>If the error occurs before the copy action starts, you receive a
+ *                            standard Amazon S3 error.</p>
+ *                         </li>
+ *                         <li>
+ *                            <p>If the error occurs during the copy operation, the error response is
+ *                            embedded in the <code>200 OK</code> response. For example, in a cross-region copy, you
+ *                            may encounter throttling and receive a <code>200 OK</code> response.
+ *                            For more information, see <a href="repost.aws/knowledge-center/s3-resolve-200-internalerror">Resolve
+ *                            the Error 200 response when copying objects to Amazon S3</a>.
+ *                            The <code>200 OK</code> status code means the copy was accepted, but
+ *                            it doesn't mean the copy is complete. Another example is
+ *                            when you disconnect from Amazon S3 before the copy is complete, Amazon S3 might cancel the copy and you may receive a <code>200 OK</code> response.
+ *                            You must stay connected to Amazon S3 until the entire response is successfully received and processed.</p>
+ *                            <p>If you call this API operation directly, make
+ *                               sure to design your application to parse the content of the response and handle it
+ *                               appropriately. If you use Amazon Web Services SDKs, SDKs handle this condition. The SDKs detect the
+ *                               embedded error and apply error handling per your configuration settings (including
+ *                               automatically retrying the request as appropriate). If the condition persists, the SDKs
+ *                               throw an exception (or, for the SDKs that don't use exceptions, they return an
+ *                               error).</p>
+ *                         </li>
+ *                      </ul>
  *                   </li>
  *                </ul>
- *                <note>
- *                   <p>All headers with the <code>x-amz-</code> prefix, including
- *                         <code>x-amz-copy-source</code>, must be signed.</p>
- *                </note>
  *             </dd>
- *             <dt>Server-side encryption</dt>
+ *             <dt>Charge</dt>
  *             <dd>
- *                <p>Amazon S3 automatically encrypts all new objects that are copied to an S3 bucket.
- *                   When copying an object, if you don't specify encryption information in your copy
- *                   request, the encryption setting of the target object is set to the default
- *                   encryption configuration of the destination bucket. By default, all buckets have a
- *                   base level of encryption configuration that uses server-side encryption with Amazon S3
- *                   managed keys (SSE-S3). If the destination bucket has a default encryption
- *                   configuration that uses server-side encryption with Key Management Service (KMS) keys
- *                   (SSE-KMS), dual-layer server-side encryption with Amazon Web Services KMS keys (DSSE-KMS), or
- *                   server-side encryption with customer-provided encryption keys (SSE-C), Amazon S3 uses
- *                   the corresponding KMS key, or a customer-provided key to encrypt the target
- *                   object copy.</p>
- *                <p>When you perform a <code>CopyObject</code> operation, if you want to use a
- *                   different type of encryption setting for the target object, you can use other
- *                   appropriate encryption-related headers to encrypt the target object with a
- *                   KMS key, an Amazon S3 managed key, or a customer-provided key. With server-side
- *                   encryption, Amazon S3 encrypts your data as it writes your data to disks in its data
- *                   centers and decrypts the data when you access it. If the encryption setting in
- *                   your request is different from the default encryption configuration of the
- *                   destination bucket, the encryption setting in your request takes precedence. If
- *                   the source object for the copy is stored in Amazon S3 using SSE-C, you must provide the
- *                   necessary encryption information in your request so that Amazon S3 can decrypt the
- *                   object for copying. For more information about server-side encryption, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/serv-side-encryption.html">Using
- *                      Server-Side Encryption</a>.</p>
- *                <p>If a target object uses SSE-KMS, you can enable an S3 Bucket Key for the
- *                   object. For more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/bucket-key.html">Amazon S3 Bucket Keys</a> in the
- *                      <i>Amazon S3 User Guide</i>.</p>
+ *                <p>The copy request charge is based on the storage class and Region that you specify for
+ *                   the destination object. The request can also result in a data retrieval charge for the
+ *                   source if the source storage class bills for data retrieval. For pricing information, see
+ *                   <a href="http://aws.amazon.com/s3/pricing/">Amazon S3 pricing</a>.</p>
  *             </dd>
- *             <dt>Access Control List (ACL)-Specific Request Headers</dt>
+ *             <dt>HTTP Host header syntax</dt>
  *             <dd>
- *                <p>When copying an object, you can optionally use headers to grant ACL-based
- *                   permissions. 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 that are defined by Amazon S3. These permissions
- *                   are then added to the ACL on the object. For more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html">Access Control
- *                      List (ACL) Overview</a> and <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-using-rest-api.html">Managing ACLs Using the REST
- *                      API</a>. </p>
- *                <p>If the bucket that you're copying objects to uses the bucket owner enforced
- *                   setting for S3 Object Ownership, ACLs are disabled and no longer affect
- *                   permissions. Buckets that use this setting only accept <code>PUT</code> requests
- *                   that don't specify an ACL or <code>PUT</code> requests that specify bucket owner
- *                   full control ACLs, such as the <code>bucket-owner-full-control</code> canned ACL
- *                   or an equivalent form of this ACL expressed in the XML format.</p>
- *                <p>For more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/about-object-ownership.html"> Controlling
- *                      ownership of objects and disabling ACLs</a> in the
- *                      <i>Amazon S3 User Guide</i>.</p>
- *                <note>
- *                   <p>If your bucket uses the bucket owner enforced setting for Object Ownership,
- *                      all objects written to the bucket by any account will be owned by the bucket
- *                      owner.</p>
- *                </note>
- *             </dd>
- *             <dt>Checksums</dt>
- *             <dd>
- *                <p>When copying an object, if it has a checksum, that checksum will be copied to
- *                   the new object by default. When you copy the object over, you can optionally
- *                   specify a different checksum algorithm to use with the
- *                      <code>x-amz-checksum-algorithm</code> header.</p>
- *             </dd>
- *             <dt>Storage Class Options</dt>
- *             <dd>
- *                <p>You can use the <code>CopyObject</code> action to change the storage class of
- *                   an object that is already stored in Amazon S3 by using the <code>StorageClass</code>
- *                   parameter. For more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/storage-class-intro.html">Storage Classes</a> in
- *                   the <i>Amazon S3 User Guide</i>.</p>
- *                <p>If the source object's storage class is GLACIER or
- *                      DEEP_ARCHIVE, or the object's storage class is
- *                      INTELLIGENT_TIERING and it's <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/intelligent-tiering-overview.html#intel-tiering-tier-definition"> S3 Intelligent-Tiering access tier</a> is
- *                   Archive Access or Deep Archive Access, you must restore a copy of this object
- *                   before you can use it as a source object for the copy operation. For more
- *                   information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html">RestoreObject</a>. For
- *                   more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/CopyingObjectsExamples.html">Copying
- *                   Objects</a>.</p>
- *             </dd>
- *             <dt>Versioning</dt>
- *             <dd>
- *                <p>By default, <code>x-amz-copy-source</code> header identifies the current
- *                   version of an object to copy. If the current version is a delete marker, Amazon S3
- *                   behaves as if the object was deleted. To copy a different version, use the
- *                      <code>versionId</code> subresource.</p>
- *                <p>If you enable versioning on the target bucket, Amazon S3 generates a unique version
- *                   ID for the object being copied. This version ID is different from the version ID
- *                   of the source object. Amazon S3 returns the version ID of the copied object in the
- *                      <code>x-amz-version-id</code> response header in the response.</p>
- *                <p>If you do not enable versioning or suspend it on the target bucket, the version
- *                   ID that Amazon S3 generates is always null.</p>
+ *                <p>
+ *                   <b>Directory buckets </b> - The HTTP Host header syntax is <code>
+ *                      <i>Bucket_name</i>.s3express-<i>az_id</i>.<i>region</i>.amazonaws.com</code>.</p>
  *             </dd>
  *          </dl>
  *          <p>The following operations are related to <code>CopyObject</code>:</p>
@@ -285,7 +213,7 @@ export interface CopyObjectCommandOutput extends CopyObjectOutput, __MetadataBea
  *   MetadataDirective: "COPY" || "REPLACE",
  *   TaggingDirective: "COPY" || "REPLACE",
  *   ServerSideEncryption: "AES256" || "aws:kms" || "aws:kms:dsse",
- *   StorageClass: "STANDARD" || "REDUCED_REDUNDANCY" || "STANDARD_IA" || "ONEZONE_IA" || "INTELLIGENT_TIERING" || "GLACIER" || "DEEP_ARCHIVE" || "OUTPOSTS" || "GLACIER_IR" || "SNOW",
+ *   StorageClass: "STANDARD" || "REDUCED_REDUNDANCY" || "STANDARD_IA" || "ONEZONE_IA" || "INTELLIGENT_TIERING" || "GLACIER" || "DEEP_ARCHIVE" || "OUTPOSTS" || "GLACIER_IR" || "SNOW" || "EXPRESS_ONEZONE",
  *   WebsiteRedirectLocation: "STRING_VALUE",
  *   SSECustomerAlgorithm: "STRING_VALUE",
  *   SSECustomerKey: "STRING_VALUE",