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 15, 2024
1 parent 584dcdf commit 65377c8
Show file tree
Hide file tree
Showing 12 changed files with 172 additions and 218 deletions.
2 changes: 1 addition & 1 deletion clients/client-s3/src/commands/CompleteMultipartUploadCommand.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ export interface CompleteMultipartUploadCommandOutput extends CompleteMultipartU
* 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>
* <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
* to retry any failed requests (including 500 error responses). 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 can't use <code>Content-Type: application/x-www-form-urlencoded</code> for the
Expand Down
10 changes: 6 additions & 4 deletions clients/client-s3/src/commands/CopyObjectCommand.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,9 @@ export interface CopyObjectCommandOutput extends CopyObjectOutput, __MetadataBea
* </note>
* <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>
* object to must be enabled for your account. For more information about how to enable a Region for your account, see <a href="https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html#manage-acct-regions-enable-standalone">Enable
* or disable a Region for standalone accounts</a> in the
* <i>Amazon Web Services Account Management Guide</i>.</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 <code>400 Bad
Expand Down Expand Up @@ -91,7 +93,7 @@ export interface CopyObjectCommandOutput extends CopyObjectOutput, __MetadataBea
* <li>
* <p>If the destination bucket is a general purpose bucket, you must have
* <b>
* <code>s3:PubObject</code>
* <code>s3:PutObject</code>
* </b>
* permission to write the object copy to the destination bucket. </p>
* </li>
Expand Down Expand Up @@ -147,7 +149,7 @@ export interface CopyObjectCommandOutput extends CopyObjectOutput, __MetadataBea
* <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
* For more information, see <a href="https://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
Expand All @@ -169,7 +171,7 @@ export interface CopyObjectCommandOutput extends CopyObjectOutput, __MetadataBea
* <dd>
* <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
* source if the source storage class bills for data retrieval. If the copy source is in a different region, the data transfer is billed to the copy source account. For pricing information, see
* <a href="http://aws.amazon.com/s3/pricing/">Amazon S3 pricing</a>.</p>
* </dd>
* <dt>HTTP Host header syntax</dt>
Expand Down
23 changes: 16 additions & 7 deletions clients/client-s3/src/commands/CreateBucketCommand.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -94,13 +94,22 @@ export interface CreateBucketCommandOutput extends CreateBucketOutput, __Metadat
* <code>x-amz-object-ownership</code> header, then the
* <code>s3:PutBucketOwnershipControls</code> permission is required.</p>
* <important>
* <p>If your <code>CreateBucket</code> request sets <code>BucketOwnerEnforced</code> for
* Amazon 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/object-ownership-existing-bucket.html">Setting Object
* Ownership on an existing bucket </a> in the <i>Amazon S3 User Guide</i>.
* </p>
* <p> To set an ACL on a bucket as part of a
* <code>CreateBucket</code> request, you must explicitly set S3
* Object Ownership for the bucket to a different value than the
* default, <code>BucketOwnerEnforced</code>. Additionally, if your
* desired bucket ACL grants public access, you must first create the
* bucket (without the bucket ACL) and then explicitly disable Block
* Public Access on the bucket before using <code>PutBucketAcl</code>
* to set the ACL. If you try to create a bucket with a public ACL,
* the request will fail. </p>
* <p> For the majority of modern use cases in S3, we recommend
* that you keep all Block Public Access settings enabled and keep
* ACLs disabled. If you would like to share data with users outside
* of your account, you can use bucket policies as needed. 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 for your
* bucket </a> and <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-control-block-public-access.html">Blocking public access to your Amazon S3 storage </a> in
* the <i>Amazon S3 User Guide</i>. </p>
* </important>
* </li>
* <li>
Expand Down
11 changes: 6 additions & 5 deletions clients/client-s3/src/commands/DeleteObjectCommand.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,12 +30,13 @@ export interface DeleteObjectCommandOutput extends DeleteObjectOutput, __Metadat
* <p>Removes an object from a bucket. The behavior depends on the bucket's versioning state: </p>
* <ul>
* <li>
* <p>If versioning is enabled, the operation removes the null version (if there is one) of an object and inserts a delete marker,
* which becomes the latest version of the object. If there isn't a null version, Amazon S3 does
* not remove any objects but will still respond that the command was successful.</p>
* <p>If bucket versioning is not enabled, the operation permanently deletes the object.</p>
* </li>
* <li>
* <p>If versioning is suspended or not enabled, the operation permanently deletes the object.</p>
* <p>If bucket versioning is enabled, the operation inserts a delete marker, which becomes the current version of the object. To permanently delete an object in a versioned bucket, you must include the object’s <code>versionId</code> in the request. For more information about versioning-enabled buckets, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/DeletingObjectVersions.html">Deleting object versions from a versioning-enabled bucket</a>.</p>
* </li>
* <li>
* <p>If bucket versioning is suspended, the operation removes the object that has a null <code>versionId</code>, if there is one, and inserts a delete marker that becomes the current version of the object. If there isn't an object with a null <code>versionId</code>, and all versions of the object have a <code>versionId</code>, Amazon S3 does not remove the object and only inserts a delete marker. To permanently delete an object that has a <code>versionId</code>, you must include the object’s <code>versionId</code> in the request. For more information about versioning-suspended buckets, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/DeletingObjectsfromVersioningSuspendedBuckets.html">Deleting objects from versioning-suspended buckets</a>.</p>
* </li>
* </ul>
* <note>
Expand Down Expand Up @@ -95,7 +96,7 @@ export interface DeleteObjectCommandOutput extends DeleteObjectOutput, __Metadat
* <p>
* <b>
* <code>s3:DeleteObjectVersion</code>
* </b> - To delete a specific version of an object from a versiong-enabled bucket, you must have the <code>s3:DeleteObjectVersion</code> permission.</p>
* </b> - To delete a specific version of an object from a versioning-enabled bucket, you must have the <code>s3:DeleteObjectVersion</code> permission.</p>
* </li>
* </ul>
* </li>
Expand Down
6 changes: 3 additions & 3 deletions clients/client-s3/src/commands/GetBucketLifecycleConfigurationCommand.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,12 +36,12 @@ export interface GetBucketLifecycleConfigurationCommandOutput
* <p>This operation is not supported by directory buckets.</p>
* </note>
* <note>
* <p>Bucket lifecycle configuration now supports specifying a lifecycle rule using an
* object key name prefix, one or more object tags, or a combination of both. Accordingly,
* <p>Bucket lifecycle configuration now supports specifying a lifecycle rule using an object key name prefix, one or more object tags, object size, or any combination of these. Accordingly, this section describes the latest API. The previous version of the API supported filtering based only on an object key name prefix, which is supported for backward compatibility.
* For the related API description, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLifecycle.html">GetBucketLifecycle</a>. Accordingly,
* this section describes the latest API. The response describes the new filter element
* that you can use to specify a filter to select a subset of objects to which the rule
* applies. If you are using a previous version of the lifecycle configuration, it still
* works. For the earlier action, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLifecycle.html">GetBucketLifecycle</a>.</p>
* works. For the earlier action, </p>
* </note>
* <p>Returns the lifecycle configuration information set on the bucket. For information about
* lifecycle configuration, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/object-lifecycle-mgmt.html">Object Lifecycle
Expand Down
2 changes: 1 addition & 1 deletion clients/client-s3/src/commands/HeadBucketCommand.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ export interface HeadBucketCommandOutput extends HeadBucketOutput, __MetadataBea
* <p>If the bucket does not exist or you do not have permission to access it, the
* <code>HEAD</code> request returns a generic <code>400 Bad Request</code>, <code>403
* Forbidden</code> or <code>404 Not Found</code> code. A message body is not included, so
* you cannot determine the exception beyond these error codes.</p>
* you cannot determine the exception beyond these HTTP response codes.</p>
* <note>
* <p>
* <b>Directory buckets </b> - 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</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
Expand Down
11 changes: 3 additions & 8 deletions clients/client-s3/src/commands/PutBucketLifecycleConfigurationCommand.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,11 +40,8 @@ export interface PutBucketLifecycleConfigurationCommandOutput extends __Metadata
* lifecycle configuration. For information about lifecycle configuration, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html">Managing
* your storage lifecycle</a>.</p>
* <note>
* <p>Bucket lifecycle configuration now supports specifying a lifecycle rule using an
* object key name prefix, one or more object tags, or a combination of both. Accordingly,
* this section describes the latest API. The previous version of the API supported
* filtering based only on an object key name prefix, which is supported for backward
* compatibility. For the related API description, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketLifecycle.html">PutBucketLifecycle</a>.</p>
* <p>Bucket lifecycle configuration now supports specifying a lifecycle rule using an object key name prefix, one or more object tags, object size, or any combination of these. Accordingly, this section describes the latest API. The previous version of the API supported filtering based only on an object key name prefix, which is supported for backward compatibility.
* For the related API description, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketLifecycle.html">PutBucketLifecycle</a>.</p>
* </note>
* <dl>
* <dt>Rules</dt>
Expand All @@ -55,9 +52,7 @@ export interface PutBucketLifecycleConfigurationCommandOutput extends __Metadata
* Each rule consists of the following:</p>
* <ul>
* <li>
* <p>A filter identifying a subset of objects to which the rule applies. The
* filter can be based on a key name prefix, object tags, or a combination of
* both.</p>
* <p>A filter identifying a subset of objects to which the rule applies. The filter can be based on a key name prefix, object tags, object size, or any combination of these.</p>
* </li>
* <li>
* <p>A status indicating whether the rule is in effect.</p>
Expand Down
61 changes: 1 addition & 60 deletions clients/client-s3/src/commands/RestoreObjectCommand.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,10 +37,6 @@ export interface RestoreObjectCommandOutput extends RestoreObjectOutput, __Metad
* <ul>
* <li>
* <p>
* <code>select</code> - Perform a select query on an archived object</p>
* </li>
* <li>
* <p>
* <code>restore an archive</code> - Restore an archived object</p>
* </li>
* </ul>
Expand All @@ -65,60 +61,6 @@ export interface RestoreObjectCommandOutput extends RestoreObjectOutput, __Metad
* </p>
* </li>
* </ul>
* <p>Define the SQL expression for the <code>SELECT</code> type of restoration for your query
* in the request body's <code>SelectParameters</code> structure. You can use expressions like
* the following examples.</p>
* <ul>
* <li>
* <p>The following expression returns all records from the specified object.</p>
* <p>
* <code>SELECT * FROM Object</code>
* </p>
* </li>
* <li>
* <p>Assuming that you are not using any headers for data stored in the object, you can
* specify columns with positional headers.</p>
* <p>
* <code>SELECT s._1, s._2 FROM Object s WHERE s._3 > 100</code>
* </p>
* </li>
* <li>
* <p>If you have headers and you set the <code>fileHeaderInfo</code> in the
* <code>CSV</code> structure in the request body to <code>USE</code>, you can
* specify headers in the query. (If you set the <code>fileHeaderInfo</code> field to
* <code>IGNORE</code>, the first row is skipped for the query.) You cannot mix
* ordinal positions with header column names. </p>
* <p>
* <code>SELECT s.Id, s.FirstName, s.SSN FROM S3Object s</code>
* </p>
* </li>
* </ul>
* <p>When making a select request, you can also do the following:</p>
* <ul>
* <li>
* <p>To expedite your queries, specify the <code>Expedited</code> tier. For more
* information about tiers, see "Restoring Archives," later in this topic.</p>
* </li>
* <li>
* <p>Specify details about the data serialization format of both the input object that
* is being queried and the serialization of the CSV-encoded query results.</p>
* </li>
* </ul>
* <p>The following are additional important facts about the select feature:</p>
* <ul>
* <li>
* <p>The output results are new Amazon S3 objects. Unlike archive retrievals, they are
* stored until explicitly deleted-manually or through a lifecycle configuration.</p>
* </li>
* <li>
* <p>You can issue more than one select request on the same Amazon S3 object. Amazon S3 doesn't
* duplicate requests, so avoid issuing duplicate requests.</p>
* </li>
* <li>
* <p> Amazon S3 accepts a select request even if the object has already been restored. A
* select request doesn’t return error response <code>409</code>.</p>
* </li>
* </ul>
* <dl>
* <dt>Permissions</dt>
* <dd>
Expand Down Expand Up @@ -234,8 +176,7 @@ export interface RestoreObjectCommandOutput extends RestoreObjectOutput, __Metad
* </li>
* <li>
* <p>
* <i>Cause: Object restore is already in progress. (This error
* does not apply to SELECT type requests.)</i>
* <i>Cause: Object restore is already in progress.</i>
* </p>
* </li>
* <li>
Expand Down
2 changes: 1 addition & 1 deletion clients/client-s3/src/commands/UploadPartCopyCommand.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ export interface UploadPartCopyCommandOutput extends UploadPartCopyOutput, __Met
* </li>
* <li>
* <p>If the destination bucket is a general purpose bucket, you must have the <b>
* <code>s3:PubObject</code>
* <code>s3:PutObject</code>
* </b> permission to write the object copy to the destination bucket.
* </p>
* </li>
Expand Down
Loading

0 comments on commit 65377c8

Please sign in to comment.