Skip to content

Commit

Permalink
docs(client-s3): Documentation updates for Amazon S3
Browse files Browse the repository at this point in the history
  • Loading branch information
awstools committed Mar 31, 2023
1 parent 4a0bb37 commit a9dc788
Show file tree
Hide file tree
Showing 87 changed files with 2,796 additions and 2,460 deletions.
1,413 changes: 751 additions & 662 deletions clients/client-s3/src/S3.ts
View file

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions clients/client-s3/src/commands/AbortMultipartUploadCommand.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,8 @@ export interface AbortMultipartUploadCommandOutput extends AbortMultipartUploadO
* <p>To verify that all parts have been removed, so you don't get charged for the part
* storage, you should call the <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html">ListParts</a> action and ensure that
* the parts list is empty.</p>
* <p>For information about permissions required to use the multipart upload, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/mpuAndPermissions.html">Multipart Upload and
* Permissions</a>.</p>
* <p>For information about permissions required to use the multipart upload, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/mpuAndPermissions.html">Multipart Upload
* and Permissions</a>.</p>
* <p>The following operations are related to <code>AbortMultipartUpload</code>:</p>
* <ul>
* <li>
Expand Down
36 changes: 22 additions & 14 deletions clients/client-s3/src/commands/CompleteMultipartUploadCommand.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,28 +45,36 @@ export interface CompleteMultipartUploadCommandOutput extends CompleteMultipartU
* <p>Completes a multipart upload by assembling previously uploaded parts.</p>
* <p>You first initiate the multipart upload and then upload all parts using the <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html">UploadPart</a>
* operation. After successfully uploading all relevant parts of an upload, you call this
* action to complete the upload. Upon receiving this request, Amazon S3 concatenates all
* the parts in ascending order by part number to create a new object. In the Complete
* Multipart Upload request, you must provide the parts list. You must ensure that the parts
* list is complete. This action concatenates the parts that you provide in the list. For
* each part in the list, you must provide the part number and the <code>ETag</code> value,
* returned after that part was uploaded.</p>
* action to complete the upload. Upon receiving this request, Amazon S3 concatenates all the
* parts in ascending order by part number to create a new object. In the Complete Multipart
* Upload request, you must provide the parts list. You must ensure that the parts list is
* complete. This action concatenates the parts that you provide in the list. For each part in
* the list, you must provide the part number and the <code>ETag</code> value, returned after
* that part was uploaded.</p>
* <p>Processing of a Complete Multipart Upload request could take several minutes to
* complete. After Amazon S3 begins processing the request, it sends an HTTP response header that
* specifies a 200 OK response. While processing is in progress, Amazon S3 periodically sends white
* space characters to keep the connection from timing out. Because a request could fail after
* the initial 200 OK response has been sent, it is important that you check the response body
* to determine whether the request succeeded.</p>
* space characters to keep the connection from timing out. A request could fail after the
* initial 200 OK response has been sent. 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>Note that if <code>CompleteMultipartUpload</code> fails, applications should be prepared
* to retry the failed requests. For more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/ErrorBestPractices.html">Amazon S3 Error Best Practices</a>.</p>
* to retry the failed requests. For more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/ErrorBestPractices.html">Amazon S3 Error Best
* Practices</a>.</p>
* <important>
* <p>You cannot use <code>Content-Type: application/x-www-form-urlencoded</code> with Complete
* Multipart Upload requests. Also, if you do not provide a <code>Content-Type</code> header, <code>CompleteMultipartUpload</code> returns a 200 OK response.</p>
* <p>You cannot use <code>Content-Type: application/x-www-form-urlencoded</code> with
* Complete Multipart Upload requests. Also, if you do not provide a
* <code>Content-Type</code> header, <code>CompleteMultipartUpload</code> returns a 200
* OK response.</p>
* </important>
* <p>For more information about multipart uploads, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/uploadobjusingmpu.html">Uploading Objects Using Multipart
* Upload</a>.</p>
* <p>For information about 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>.</p>
* <p>For information about 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>.</p>
* <p>
* <code>CompleteMultipartUpload</code> has the following special errors:</p>
* <ul>
Expand Down
83 changes: 53 additions & 30 deletions clients/client-s3/src/commands/CopyObjectCommand.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,15 +52,20 @@ export interface CopyObjectCommandOutput extends CopyObjectOutput, __MetadataBea
* </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>
* 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. Design your application to parse the
* contents of the response and handle it appropriately.</p>
* 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>
* <note>
Expand All @@ -73,7 +78,8 @@ export interface CopyObjectCommandOutput extends CopyObjectOutput, __MetadataBea
* <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
* Request</code> error. For more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/transfer-acceleration.html">Transfer Acceleration</a>.</p>
* Request</code> error. For more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/transfer-acceleration.html">Transfer
* Acceleration</a>.</p>
* </important>
* <p>
* <b>Metadata</b>
Expand All @@ -90,6 +96,11 @@ export interface CopyObjectCommandOutput extends CopyObjectOutput, __MetadataBea
* 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>
* <b>x-amz-copy-source-if Headers</b>
* </p>
Expand Down Expand Up @@ -154,14 +165,27 @@ export interface CopyObjectCommandOutput extends CopyObjectOutput, __MetadataBea
* <p>
* <b>Server-side encryption</b>
* </p>
* <p>When you perform a CopyObject operation, you can optionally use the appropriate encryption-related
* headers to encrypt the object using server-side encryption with Amazon Web Services managed encryption keys
* (SSE-S3 or SSE-KMS) or a customer-provided encryption key. With server-side encryption, Amazon S3
* encrypts your data as it writes it to disks in its data centers and decrypts the data when
* you access it. 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>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 an Key Management Service (KMS) key (SSE-KMS), or a customer-provided encryption key (SSE-C),
* Amazon S3 uses the corresponding KMS key, or a customer-provided key to encrypt the target
* object copy. When you perform a CopyObject 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 it 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>
* <b>Access Control List (ACL)-Specific Request
* Headers</b>
Expand All @@ -173,29 +197,29 @@ export interface CopyObjectCommandOutput extends CopyObjectOutput, __MetadataBea
* 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 PUT requests that don't specify an ACL or PUT 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>
* S3 Object Ownership, ACLs are disabled and no longer affect permissions. Buckets that use
* this setting only accept PUT requests that don't specify an ACL or PUT 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>
* 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>
* <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>
* <p>
* <b>Checksums</b>
* </p>
* <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 may optionally specify a different checksum
* algorithm to use with the <code>x-amz-checksum-algorithm</code> header.</p>
* <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 may optionally specify a different
* checksum algorithm to use with the <code>x-amz-checksum-algorithm</code> header.</p>
* <p>
* <b>Storage Class Options</b>
* </p>
* <p>You can use the <code>CopyObject</code> action to change the storage class of an
* object that is already stored in Amazon S3 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>You can use the <code>CopyObject</code> action to change the storage class of an object
* that is already stored in Amazon S3 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>
* <b>Versioning</b>
* </p>
Expand Down Expand Up @@ -224,8 +248,7 @@ export interface CopyObjectCommandOutput extends CopyObjectOutput, __MetadataBea
* </p>
* </li>
* </ul>
* <p>For more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/CopyingObjectsExamples.html">Copying
* Objects</a>.</p>
* <p>For more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/CopyingObjectsExamples.html">Copying Objects</a>.</p>
* @example
* Use a bare-bones client and the command you need to make an API call.
* ```javascript
Expand Down
Loading

0 comments on commit a9dc788

Please sign in to comment.