feat(client-s3): Amazon Simple Storage Service / Features: Add suppor…

…t for ETag based conditional writes in PutObject and CompleteMultiPartUpload APIs to prevent unintended object modifications.
aws · Nov 25, 2024 · 453f462 · 453f462
1 parent 4a7eea0
commit 453f462
Show file tree

Hide file tree

Showing 12 changed files with 173 additions and 129 deletions.
diff --git a/clients/client-s3/src/commands/CompleteMultipartUploadCommand.ts b/clients/client-s3/src/commands/CompleteMultipartUploadCommand.ts
@@ -232,6 +232,7 @@ export interface CompleteMultipartUploadCommandOutput extends CompleteMultipartU
  *   ChecksumSHA256: "STRING_VALUE",
  *   RequestPayer: "requester",
  *   ExpectedBucketOwner: "STRING_VALUE",
+ *   IfMatch: "STRING_VALUE",
  *   IfNoneMatch: "STRING_VALUE",
  *   SSECustomerAlgorithm: "STRING_VALUE",
  *   SSECustomerKey: "STRING_VALUE",

diff --git a/clients/client-s3/src/commands/CreateBucketCommand.ts b/clients/client-s3/src/commands/CreateBucketCommand.ts
@@ -234,39 +234,39 @@ export interface CreateBucketCommandOutput extends CreateBucketOutput, __Metadat
  * <p>Base exception class for all service exceptions from S3 service.</p>
  *
  * @public
- * @example To create a bucket in a specific region
+ * @example To create a bucket
  * ```javascript
- * // The following example creates a bucket. The request specifies an AWS region where to create the bucket.
+ * // The following example creates a bucket.
  * const input = {
- *   "Bucket": "examplebucket",
- *   "CreateBucketConfiguration": {
- *     "LocationConstraint": "eu-west-1"
- *   }
+ *   "Bucket": "examplebucket"
  * };
  * const command = new CreateBucketCommand(input);
  * const response = await client.send(command);
  * /* response ==
  * {
- *   "Location": "http://examplebucket.<Region>.s3.amazonaws.com/"
+ *   "Location": "/examplebucket"
  * }
  * *\/
- * // example id: to-create-a-bucket-in-a-specific-region-1483399072992
+ * // example id: to-create-a-bucket--1472851826060
  * ```
  *
- * @example To create a bucket
+ * @example To create a bucket in a specific region
  * ```javascript
- * // The following example creates a bucket.
+ * // The following example creates a bucket. The request specifies an AWS region where to create the bucket.
  * const input = {
- *   "Bucket": "examplebucket"
+ *   "Bucket": "examplebucket",
+ *   "CreateBucketConfiguration": {
+ *     "LocationConstraint": "eu-west-1"
+ *   }
  * };
  * const command = new CreateBucketCommand(input);
  * const response = await client.send(command);
  * /* response ==
  * {
- *   "Location": "/examplebucket"
+ *   "Location": "http://examplebucket.<Region>.s3.amazonaws.com/"
  * }
  * *\/
- * // example id: to-create-a-bucket--1472851826060
+ * // example id: to-create-a-bucket-in-a-specific-region-1483399072992
  * ```
  *
  */

diff --git a/clients/client-s3/src/commands/DeleteObjectCommand.ts b/clients/client-s3/src/commands/DeleteObjectCommand.ts
@@ -157,28 +157,28 @@ export interface DeleteObjectCommandOutput extends DeleteObjectOutput, __Metadat
  * <p>Base exception class for all service exceptions from S3 service.</p>
  *
  * @public
- * @example To delete an object (from a non-versioned bucket)
+ * @example To delete an object
  * ```javascript
- * // The following example deletes an object from a non-versioned bucket.
+ * // The following example deletes an object from an S3 bucket.
  * const input = {
- *   "Bucket": "ExampleBucket",
- *   "Key": "HappyFace.jpg"
+ *   "Bucket": "examplebucket",
+ *   "Key": "objectkey.jpg"
  * };
  * const command = new DeleteObjectCommand(input);
  * await client.send(command);
- * // example id: to-delete-an-object-from-a-non-versioned-bucket-1481588533089
+ * // example id: to-delete-an-object-1472850136595
  * ```
  *
- * @example To delete an object
+ * @example To delete an object (from a non-versioned bucket)
  * ```javascript
- * // The following example deletes an object from an S3 bucket.
+ * // The following example deletes an object from a non-versioned bucket.
  * const input = {
- *   "Bucket": "examplebucket",
- *   "Key": "objectkey.jpg"
+ *   "Bucket": "ExampleBucket",
+ *   "Key": "HappyFace.jpg"
  * };
  * const command = new DeleteObjectCommand(input);
  * await client.send(command);
- * // example id: to-delete-an-object-1472850136595
+ * // example id: to-delete-an-object-from-a-non-versioned-bucket-1481588533089
  * ```
  *
  */

diff --git a/clients/client-s3/src/commands/DeleteObjectsCommand.ts b/clients/client-s3/src/commands/DeleteObjectsCommand.ts
@@ -227,18 +227,20 @@ export interface DeleteObjectsCommandOutput extends DeleteObjectsOutput, __Metad
  * <p>Base exception class for all service exceptions from S3 service.</p>
  *
  * @public
- * @example To delete multiple objects from a versioned bucket
+ * @example To delete multiple object versions from a versioned bucket
  * ```javascript
- * // The following example deletes objects from a bucket. The bucket is versioned, and the request does not specify the object version to delete. In this case, all versions remain in the bucket and S3 adds a delete marker.
+ * // The following example deletes objects from a bucket. The request specifies object versions. S3 deletes specific object versions and returns the key and versions of deleted objects in the response.
  * const input = {
  *   "Bucket": "examplebucket",
  *   "Delete": {
  *     "Objects": [
  *       {
- *         "Key": "objectkey1"
+ *         "Key": "HappyFace.jpg",
+ *         "VersionId": "2LWg7lQLnY41.maGB5Z6SWW.dcq0vx7b"
  *       },
  *       {
- *         "Key": "objectkey2"
+ *         "Key": "HappyFace.jpg",
+ *         "VersionId": "yoz3HB.ZhCS_tKVEmIOr7qYyyAaZSKVd"
  *       }
  *     ],
  *     "Quiet": false
@@ -250,35 +252,31 @@ export interface DeleteObjectsCommandOutput extends DeleteObjectsOutput, __Metad
  * {
  *   "Deleted": [
  *     {
- *       "DeleteMarker": "true",
- *       "DeleteMarkerVersionId": "A._w1z6EFiCF5uhtQMDal9JDkID9tQ7F",
- *       "Key": "objectkey1"
+ *       "Key": "HappyFace.jpg",
+ *       "VersionId": "yoz3HB.ZhCS_tKVEmIOr7qYyyAaZSKVd"
  *     },
  *     {
- *       "DeleteMarker": "true",
- *       "DeleteMarkerVersionId": "iOd_ORxhkKe_e8G8_oSGxt2PjsCZKlkt",
- *       "Key": "objectkey2"
+ *       "Key": "HappyFace.jpg",
+ *       "VersionId": "2LWg7lQLnY41.maGB5Z6SWW.dcq0vx7b"
  *     }
  *   ]
  * }
  * *\/
- * // example id: to-delete-multiple-objects-from-a-versioned-bucket-1483146248805
+ * // example id: to-delete-multiple-object-versions-from-a-versioned-bucket-1483147087737
  * ```
  *
- * @example To delete multiple object versions from a versioned bucket
+ * @example To delete multiple objects from a versioned bucket
  * ```javascript
- * // The following example deletes objects from a bucket. The request specifies object versions. S3 deletes specific object versions and returns the key and versions of deleted objects in the response.
+ * // The following example deletes objects from a bucket. The bucket is versioned, and the request does not specify the object version to delete. In this case, all versions remain in the bucket and S3 adds a delete marker.
  * const input = {
  *   "Bucket": "examplebucket",
  *   "Delete": {
  *     "Objects": [
  *       {
- *         "Key": "HappyFace.jpg",
- *         "VersionId": "2LWg7lQLnY41.maGB5Z6SWW.dcq0vx7b"
+ *         "Key": "objectkey1"
  *       },
  *       {
- *         "Key": "HappyFace.jpg",
- *         "VersionId": "yoz3HB.ZhCS_tKVEmIOr7qYyyAaZSKVd"
+ *         "Key": "objectkey2"
  *       }
  *     ],
  *     "Quiet": false
@@ -290,17 +288,19 @@ export interface DeleteObjectsCommandOutput extends DeleteObjectsOutput, __Metad
  * {
  *   "Deleted": [
  *     {
- *       "Key": "HappyFace.jpg",
- *       "VersionId": "yoz3HB.ZhCS_tKVEmIOr7qYyyAaZSKVd"
+ *       "DeleteMarker": "true",
+ *       "DeleteMarkerVersionId": "A._w1z6EFiCF5uhtQMDal9JDkID9tQ7F",
+ *       "Key": "objectkey1"
  *     },
  *     {
- *       "Key": "HappyFace.jpg",
- *       "VersionId": "2LWg7lQLnY41.maGB5Z6SWW.dcq0vx7b"
+ *       "DeleteMarker": "true",
+ *       "DeleteMarkerVersionId": "iOd_ORxhkKe_e8G8_oSGxt2PjsCZKlkt",
+ *       "Key": "objectkey2"
  *     }
  *   ]
  * }
  * *\/
- * // example id: to-delete-multiple-object-versions-from-a-versioned-bucket-1483147087737
+ * // example id: to-delete-multiple-objects-from-a-versioned-bucket-1483146248805
  * ```
  *
  */

diff --git a/clients/client-s3/src/commands/GetObjectCommand.ts b/clients/client-s3/src/commands/GetObjectCommand.ts
@@ -311,53 +311,53 @@ export interface GetObjectCommandOutput extends Omit<GetObjectOutput, "Body">, _
  * <p>Base exception class for all service exceptions from S3 service.</p>
  *
  * @public
- * @example To retrieve an object
+ * @example To retrieve a byte range of an object
  * ```javascript
- * // The following example retrieves an object for an S3 bucket.
+ * // The following example retrieves an object for an S3 bucket. The request specifies the range header to retrieve a specific byte range.
  * const input = {
  *   "Bucket": "examplebucket",
- *   "Key": "HappyFace.jpg"
+ *   "Key": "SampleFile.txt",
+ *   "Range": "bytes=0-9"
  * };
  * const command = new GetObjectCommand(input);
  * const response = await client.send(command);
  * /* response ==
  * {
  *   "AcceptRanges": "bytes",
- *   "ContentLength": "3191",
- *   "ContentType": "image/jpeg",
- *   "ETag": "\"6805f2cfc46c0f04559748bb039d69ae\"",
- *   "LastModified": "2016-12-15T01:19:41.000Z",
+ *   "ContentLength": "10",
+ *   "ContentRange": "bytes 0-9/43",
+ *   "ContentType": "text/plain",
+ *   "ETag": "\"0d94420ffd0bc68cd3d152506b97a9cc\"",
+ *   "LastModified": "2014-10-09T22:57:28.000Z",
  *   "Metadata": {},
- *   "TagCount": 2,
  *   "VersionId": "null"
  * }
  * *\/
- * // example id: to-retrieve-an-object-1481827837012
+ * // example id: to-retrieve-a-byte-range-of-an-object--1481832674603
  * ```
  *
- * @example To retrieve a byte range of an object
+ * @example To retrieve an object
  * ```javascript
- * // The following example retrieves an object for an S3 bucket. The request specifies the range header to retrieve a specific byte range.
+ * // The following example retrieves an object for an S3 bucket.
  * const input = {
  *   "Bucket": "examplebucket",
- *   "Key": "SampleFile.txt",
- *   "Range": "bytes=0-9"
+ *   "Key": "HappyFace.jpg"
  * };
  * const command = new GetObjectCommand(input);
  * const response = await client.send(command);
  * /* response ==
  * {
  *   "AcceptRanges": "bytes",
- *   "ContentLength": "10",
- *   "ContentRange": "bytes 0-9/43",
- *   "ContentType": "text/plain",
- *   "ETag": "\"0d94420ffd0bc68cd3d152506b97a9cc\"",
- *   "LastModified": "2014-10-09T22:57:28.000Z",
+ *   "ContentLength": "3191",
+ *   "ContentType": "image/jpeg",
+ *   "ETag": "\"6805f2cfc46c0f04559748bb039d69ae\"",
+ *   "LastModified": "2016-12-15T01:19:41.000Z",
  *   "Metadata": {},
+ *   "TagCount": 2,
  *   "VersionId": "null"
  * }
  * *\/
- * // example id: to-retrieve-a-byte-range-of-an-object--1481832674603
+ * // example id: to-retrieve-an-object-1481827837012
  * ```
  *
  */