feat(client-s3): Adding new params - Key and Prefix, to S3 API operat…

…ions for supporting S3 Access Grants. Note - These updates will not change any of the existing S3 API functionality.
aws · Nov 27, 2023 · ba36517 · ba36517
1 parent 648c9e7
commit ba36517
Show file tree

Hide file tree

Showing 23 changed files with 342 additions and 199 deletions.
diff --git a/clients/client-s3/src/commands/AbortMultipartUploadCommand.ts b/clients/client-s3/src/commands/AbortMultipartUploadCommand.ts
@@ -131,6 +131,7 @@ export class AbortMultipartUploadCommand extends $Command<
   public static getEndpointParameterInstructions(): EndpointParameterInstructions {
     return {
       Bucket: { type: "contextParams", name: "Bucket" },
+      Key: { type: "contextParams", name: "Key" },
       ForcePathStyle: { type: "clientContextParams", name: "forcePathStyle" },
       UseArnRegion: { type: "clientContextParams", name: "useArnRegion" },
       DisableMultiRegionAccessPoints: { type: "clientContextParams", name: "disableMultiregionAccessPoints" },

diff --git a/clients/client-s3/src/commands/CompleteMultipartUploadCommand.ts b/clients/client-s3/src/commands/CompleteMultipartUploadCommand.ts
@@ -267,6 +267,7 @@ export class CompleteMultipartUploadCommand extends $Command<
   public static getEndpointParameterInstructions(): EndpointParameterInstructions {
     return {
       Bucket: { type: "contextParams", name: "Bucket" },
+      Key: { type: "contextParams", name: "Key" },
       ForcePathStyle: { type: "clientContextParams", name: "forcePathStyle" },
       UseArnRegion: { type: "clientContextParams", name: "useArnRegion" },
       DisableMultiRegionAccessPoints: { type: "clientContextParams", name: "disableMultiregionAccessPoints" },

diff --git a/clients/client-s3/src/commands/CreateBucketCommand.ts b/clients/client-s3/src/commands/CreateBucketCommand.ts
@@ -196,39 +196,39 @@ export interface CreateBucketCommandOutput extends CreateBucketOutput, __Metadat
  * @throws {@link S3ServiceException}
  * <p>Base exception class for all service exceptions from S3 service.</p>
  *
- * @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/CreateMultipartUploadCommand.ts b/clients/client-s3/src/commands/CreateMultipartUploadCommand.ts
@@ -435,6 +435,7 @@ export class CreateMultipartUploadCommand extends $Command<
   public static getEndpointParameterInstructions(): EndpointParameterInstructions {
     return {
       Bucket: { type: "contextParams", name: "Bucket" },
+      Key: { type: "contextParams", name: "Key" },
       ForcePathStyle: { type: "clientContextParams", name: "forcePathStyle" },
       UseArnRegion: { type: "clientContextParams", name: "useArnRegion" },
       DisableMultiRegionAccessPoints: { type: "clientContextParams", name: "disableMultiregionAccessPoints" },

diff --git a/clients/client-s3/src/commands/DeleteObjectCommand.ts b/clients/client-s3/src/commands/DeleteObjectCommand.ts
@@ -130,6 +130,7 @@ export class DeleteObjectCommand extends $Command<
   public static getEndpointParameterInstructions(): EndpointParameterInstructions {
     return {
       Bucket: { type: "contextParams", name: "Bucket" },
+      Key: { type: "contextParams", name: "Key" },
       ForcePathStyle: { type: "clientContextParams", name: "forcePathStyle" },
       UseArnRegion: { type: "clientContextParams", name: "useArnRegion" },
       DisableMultiRegionAccessPoints: { type: "clientContextParams", name: "disableMultiregionAccessPoints" },

diff --git a/clients/client-s3/src/commands/DeleteObjectTaggingCommand.ts b/clients/client-s3/src/commands/DeleteObjectTaggingCommand.ts
@@ -86,39 +86,39 @@ export interface DeleteObjectTaggingCommandOutput extends DeleteObjectTaggingOut
  * @throws {@link S3ServiceException}
  * <p>Base exception class for all service exceptions from S3 service.</p>
  *
- * @example To remove tag set from an object
+ * @example To remove tag set from an object version
  * ```javascript
- * // The following example removes tag set associated with the specified object. If the bucket is versioning enabled, the operation removes tag set from the latest object version.
+ * // The following example removes tag set associated with the specified object version. The request specifies both the object key and object version.
  * const input = {
  *   "Bucket": "examplebucket",
- *   "Key": "HappyFace.jpg"
+ *   "Key": "HappyFace.jpg",
+ *   "VersionId": "ydlaNkwWm0SfKJR.T1b1fIdPRbldTYRI"
  * };
  * const command = new DeleteObjectTaggingCommand(input);
  * const response = await client.send(command);
  * /* response ==
  * {
- *   "VersionId": "null"
+ *   "VersionId": "ydlaNkwWm0SfKJR.T1b1fIdPRbldTYRI"
  * }
  * *\/
- * // example id: to-remove-tag-set-from-an-object-1483145342862
+ * // example id: to-remove-tag-set-from-an-object-version-1483145285913
  * ```
  *
- * @example To remove tag set from an object version
+ * @example To remove tag set from an object
  * ```javascript
- * // The following example removes tag set associated with the specified object version. The request specifies both the object key and object version.
+ * // The following example removes tag set associated with the specified object. If the bucket is versioning enabled, the operation removes tag set from the latest object version.
  * const input = {
  *   "Bucket": "examplebucket",
- *   "Key": "HappyFace.jpg",
- *   "VersionId": "ydlaNkwWm0SfKJR.T1b1fIdPRbldTYRI"
+ *   "Key": "HappyFace.jpg"
  * };
  * const command = new DeleteObjectTaggingCommand(input);
  * const response = await client.send(command);
  * /* response ==
  * {
- *   "VersionId": "ydlaNkwWm0SfKJR.T1b1fIdPRbldTYRI"
+ *   "VersionId": "null"
  * }
  * *\/
- * // example id: to-remove-tag-set-from-an-object-version-1483145285913
+ * // example id: to-remove-tag-set-from-an-object-1483145342862
  * ```
  *
  */

diff --git a/clients/client-s3/src/commands/DeleteObjectsCommand.ts b/clients/client-s3/src/commands/DeleteObjectsCommand.ts
@@ -146,20 +146,18 @@ export interface DeleteObjectsCommandOutput extends DeleteObjectsOutput, __Metad
  * @throws {@link S3ServiceException}
  * <p>Base exception class for all service exceptions from S3 service.</p>
  *
- * @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
@@ -171,31 +169,35 @@ 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
  * ```
  *
- * @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
@@ -207,19 +209,17 @@ 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
  * ```
  *
  */

diff --git a/clients/client-s3/src/commands/GetObjectAclCommand.ts b/clients/client-s3/src/commands/GetObjectAclCommand.ts
@@ -188,6 +188,7 @@ export class GetObjectAclCommand extends $Command<
   public static getEndpointParameterInstructions(): EndpointParameterInstructions {
     return {
       Bucket: { type: "contextParams", name: "Bucket" },
+      Key: { type: "contextParams", name: "Key" },
       ForcePathStyle: { type: "clientContextParams", name: "forcePathStyle" },
       UseArnRegion: { type: "clientContextParams", name: "useArnRegion" },
       DisableMultiRegionAccessPoints: { type: "clientContextParams", name: "disableMultiregionAccessPoints" },

diff --git a/clients/client-s3/src/commands/GetObjectCommand.ts b/clients/client-s3/src/commands/GetObjectCommand.ts
@@ -312,60 +312,61 @@ export interface GetObjectCommandOutput extends Omit<GetObjectOutput, "Body">, _
  * @throws {@link S3ServiceException}
  * <p>Base exception class for all service exceptions from S3 service.</p>
  *
- * @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": "Thu, 15 Dec 2016 01:19:41 GMT",
+ *   "ContentLength": "10",
+ *   "ContentRange": "bytes 0-9/43",
+ *   "ContentType": "text/plain",
+ *   "ETag": "\"0d94420ffd0bc68cd3d152506b97a9cc\"",
+ *   "LastModified": "Thu, 09 Oct 2014 22:57:28 GMT",
  *   "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": "Thu, 09 Oct 2014 22:57:28 GMT",
+ *   "ContentLength": "3191",
+ *   "ContentType": "image/jpeg",
+ *   "ETag": "\"6805f2cfc46c0f04559748bb039d69ae\"",
+ *   "LastModified": "Thu, 15 Dec 2016 01:19:41 GMT",
  *   "Metadata": {},
+ *   "TagCount": 2,
  *   "VersionId": "null"
  * }
  * *\/
- * // example id: to-retrieve-a-byte-range-of-an-object--1481832674603
+ * // example id: to-retrieve-an-object-1481827837012
  * ```
  *
  */
 export class GetObjectCommand extends $Command<GetObjectCommandInput, GetObjectCommandOutput, S3ClientResolvedConfig> {
   public static getEndpointParameterInstructions(): EndpointParameterInstructions {
     return {
       Bucket: { type: "contextParams", name: "Bucket" },
+      Key: { type: "contextParams", name: "Key" },
       ForcePathStyle: { type: "clientContextParams", name: "forcePathStyle" },
       UseArnRegion: { type: "clientContextParams", name: "useArnRegion" },
       DisableMultiRegionAccessPoints: { type: "clientContextParams", name: "disableMultiregionAccessPoints" },

diff --git a/clients/client-s3/src/commands/HeadObjectCommand.ts b/clients/client-s3/src/commands/HeadObjectCommand.ts
@@ -284,6 +284,7 @@ export class HeadObjectCommand extends $Command<
   public static getEndpointParameterInstructions(): EndpointParameterInstructions {
     return {
       Bucket: { type: "contextParams", name: "Bucket" },
+      Key: { type: "contextParams", name: "Key" },
       ForcePathStyle: { type: "clientContextParams", name: "forcePathStyle" },
       UseArnRegion: { type: "clientContextParams", name: "useArnRegion" },
       DisableMultiRegionAccessPoints: { type: "clientContextParams", name: "disableMultiregionAccessPoints" },