From cdd51de3139dce0ac85a6ec568116bb9bc637bba Mon Sep 17 00:00:00 2001 From: awstools Date: Mon, 18 Mar 2024 18:14:21 +0000 Subject: [PATCH] feat(client-s3): Fix two issues with response root node names. --- codegen/sdk-codegen/aws-models/s3.json | 164 +++++++++++++++---------- 1 file changed, 102 insertions(+), 62 deletions(-) diff --git a/codegen/sdk-codegen/aws-models/s3.json b/codegen/sdk-codegen/aws-models/s3.json index a79b3ba2fda1..2843f9e4358b 100644 --- a/codegen/sdk-codegen/aws-models/s3.json +++ b/codegen/sdk-codegen/aws-models/s3.json @@ -19177,6 +19177,16 @@ "traits": { "smithy.api#documentation": "\n

This action creates an Amazon S3 bucket. To create an Amazon S3 on Outposts bucket, see \n CreateBucket\n .

\n \n

Creates a new S3 bucket. To create a bucket, you must set up Amazon S3 and have a\n valid Amazon Web Services Access Key ID to authenticate requests. Anonymous requests are never allowed to\n create buckets. By creating the bucket, you become the bucket owner.

\n

There are two types of buckets: general purpose buckets and directory buckets. For more\n information about these bucket types, see Creating, configuring, and\n working with Amazon S3 buckets in the Amazon S3 User Guide.

\n \n \n \n
\n
Permissions
\n
\n
    \n
  • \n

    \n General purpose bucket permissions - In addition to the s3:CreateBucket permission, the following permissions are\n required in a policy when your CreateBucket request includes specific\n headers:

    \n
      \n
    • \n

      \n Access control lists (ACLs) - In your CreateBucket request, if you specify an access control list (ACL) \n and set it to public-read, public-read-write,\n authenticated-read, or if you explicitly specify any other custom ACLs, both s3:CreateBucket and\n s3:PutBucketAcl permissions are required. In your CreateBucket request, if you set the ACL to private, \n or if you don't specify any ACLs, only the s3:CreateBucket permission is required.\n

      \n
      • \n
    • \n

      \n Object Lock - In your\n CreateBucket request, if you set \n x-amz-bucket-object-lock-enabled to true, the \n s3:PutBucketObjectLockConfiguration and\n s3:PutBucketVersioning permissions are required.

      \n
      • \n
    • \n

      \n S3 Object Ownership - If your\n CreateBucket request includes the\n x-amz-object-ownership header, then the\n s3:PutBucketOwnershipControls permission is required.

      \n \n

      To set an ACL on a bucket as part of a\n CreateBucket request, you must explicitly set S3\n Object Ownership for the bucket to a different value than the\n default, BucketOwnerEnforced. Additionally, if your\n desired bucket ACL grants public access, you must first create the\n bucket (without the bucket ACL) and then explicitly disable Block\n Public Access on the bucket before using PutBucketAcl\n to set the ACL. If you try to create a bucket with a public ACL,\n the request will fail.

      \n

      For the majority of modern use cases in S3, we recommend\n that you keep all Block Public Access settings enabled and keep\n ACLs disabled. If you would like to share data with users outside\n of your account, you can use bucket policies as needed. For more\n information, see Controlling ownership of objects and disabling ACLs for your\n bucket and Blocking public access to your Amazon S3 storage in\n the Amazon S3 User Guide.

      \n       \n
      • \n
    • \n

      \n S3 Block Public Access - If your\n specific use case requires granting public access to your S3 resources, you\n can disable Block Public Access. Specifically, you can create a new bucket with Block\n Public Access enabled, then separately call the \n DeletePublicAccessBlock\n API. To use this operation, you must have the\n s3:PutBucketPublicAccessBlock permission. For more information about S3 Block Public\n Access, see Blocking\n public access to your Amazon S3 storage in the\n Amazon S3 User Guide.

      \n
      • \n
    \n
    • \n
  • \n

    \n Directory bucket permissions - You must have the s3express:CreateBucket permission in an IAM identity-based policy instead of a bucket policy. Cross-account access to this API operation isn't supported. This operation can only be performed by the Amazon Web Services account that owns the resource. For more information about directory bucket policies and permissions, see Amazon Web Services Identity and Access Management (IAM) for S3 Express One Zone in the Amazon S3 User Guide.

    \n \n

    The permissions for ACLs, Object Lock, S3 Object Ownership, and S3 Block Public Access are not supported for directory buckets. \n For directory buckets, all Block Public Access settings are enabled at the bucket level and S3 \n Object Ownership is set to Bucket owner enforced (ACLs disabled). These settings can't be modified.\n

    \n

    For more information about permissions for creating and working with \n directory buckets, see Directory buckets in the Amazon S3 User Guide. \n For more information about supported S3 features for directory buckets, see Features of S3 Express One Zone in the Amazon S3 User Guide.

    \n     \n
    • \n
\n
\n
HTTP Host header syntax
\n
\n

\n Directory buckets - The HTTP Host header syntax is s3express-control.region.amazonaws.com.

\n
\n
\n

The following operations are related to CreateBucket:

\n ", "smithy.api#examples": [ + { + "title": "To create a bucket ", + "documentation": "The following example creates a bucket.", + "input": { + "Bucket": "examplebucket" + }, + "output": { + "Location": "/examplebucket" + } + }, { "title": "To create a bucket in a specific region", "documentation": "The following example creates a bucket. The request specifies an AWS region where to create the bucket.", @@ -19189,16 +19199,6 @@ "output": { "Location": "http://examplebucket..s3.amazonaws.com/" } - }, - { - "title": "To create a bucket ", - "documentation": "The following example creates a bucket.", - "input": { - "Bucket": "examplebucket" - }, - "output": { - "Location": "/examplebucket" - } } ], "smithy.api#http": { @@ -20641,14 +20641,6 @@ "traits": { "smithy.api#documentation": "

Removes an object from a bucket. The behavior depends on the bucket's versioning state:

\n \n \n
    \n
  • \n

    \n Directory buckets - S3 Versioning isn't enabled and supported for directory buckets. For this API operation, only the null value of the version ID is supported by directory buckets. You can only specify null \n to the versionId query parameter in the request.

    \n
    • \n
  • \n

    \n Directory buckets - 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 https://bucket_name.s3express-az_id.region.amazonaws.com/key-name\n . Path-style requests are not supported. For more information, see Regional and Zonal endpoints in the\n Amazon S3 User Guide.

    \n
    • \n
\n \n

To remove a specific version, you must use the versionId query parameter. Using this\n query parameter permanently deletes the version. If the object deleted is a delete marker, Amazon S3\n sets the response header x-amz-delete-marker to true.

\n

If the object you want to delete is in a bucket where the bucket versioning\n configuration is MFA Delete enabled, you must include the x-amz-mfa request\n header in the DELETE versionId request. Requests that include\n x-amz-mfa must use HTTPS. For more information about MFA Delete, see Using MFA Delete in the Amazon S3\n User Guide. To see sample\n requests that use versioning, see Sample\n Request.

\n \n

\n Directory buckets - MFA delete is not supported by directory buckets.

\n \n

You can delete objects by explicitly calling DELETE Object or calling \n (PutBucketLifecycle) to enable Amazon S3 to remove them for you. If you want to block\n users or accounts from removing or deleting objects from your bucket, you must deny them\n the s3:DeleteObject, s3:DeleteObjectVersion, and\n s3:PutLifeCycleConfiguration actions.

\n \n

\n Directory buckets - S3 Lifecycle is not supported by directory buckets.

\n \n
\n
Permissions
\n
\n
    \n
  • \n

    \n General purpose bucket permissions - The following permissions are required in your policies when your \n DeleteObjects request includes specific headers.

    \n
      \n
    • \n

      \n \n s3:DeleteObject\n - To delete an object from a bucket, you must always have the s3:DeleteObject permission.

      \n
      • \n
    • \n

      \n \n s3:DeleteObjectVersion\n - To delete a specific version of an object from a versioning-enabled bucket, you must have the s3:DeleteObjectVersion permission.

      \n
      • \n
    \n
    • \n
  • \n

    \n Directory bucket permissions - To grant access to this API operation on a directory bucket, we recommend that you use the \n CreateSession\n API operation for session-based authorization. Specifically, you grant the s3express:CreateSession permission to the directory bucket in a bucket policy or an IAM identity-based policy. Then, you make the CreateSession API call on the bucket to obtain a session token. With the session token in your request header, you can make API requests to this operation. After the session token expires, you make another CreateSession API call to generate a new session token for use. \nAmazon Web Services CLI or SDKs create session and refresh the session token automatically to avoid service interruptions when a session expires. For more information about authorization, see \n CreateSession\n .

    \n
    • \n
\n
\n
HTTP Host header syntax
\n
\n

\n Directory buckets - The HTTP Host header syntax is \n Bucket_name.s3express-az_id.region.amazonaws.com.

\n
\n
\n

The following action is related to DeleteObject:

\n ", "smithy.api#examples": [ - { - "title": "To delete an object (from a non-versioned bucket)", - "documentation": "The following example deletes an object from a non-versioned bucket.", - "input": { - "Bucket": "ExampleBucket", - "Key": "HappyFace.jpg" - } - }, { "title": "To delete an object", "documentation": "The following example deletes an object from an S3 bucket.", @@ -20657,6 +20649,14 @@ "Key": "objectkey.jpg" }, "output": {} + }, + { + "title": "To delete an object (from a non-versioned bucket)", + "documentation": "The following example deletes an object from a non-versioned bucket.", + "input": { + "Bucket": "ExampleBucket", + "Key": "HappyFace.jpg" + } } ], "smithy.api#http": { @@ -23529,7 +23529,8 @@ "target": "com.amazonaws.s3#ObjectLockLegalHold", "traits": { "smithy.api#documentation": "

The current legal hold status for the specified object.

", - "smithy.api#httpPayload": {} + "smithy.api#httpPayload": {}, + "smithy.api#xmlName": "LegalHold" } } }, @@ -24091,7 +24092,8 @@ "target": "com.amazonaws.s3#ObjectLockRetention", "traits": { "smithy.api#documentation": "

The container element for an object's retention settings.

", - "smithy.api#httpPayload": {} + "smithy.api#httpPayload": {}, + "smithy.api#xmlName": "Retention" } } }, @@ -24158,40 +24160,40 @@ "smithy.api#documentation": "\n

This operation is not supported by directory buckets.

\n \n

Returns the tag-set of an object. You send the GET request against the tagging\n subresource associated with the object.

\n

To use this operation, you must have permission to perform the\n s3:GetObjectTagging action. By default, the GET action returns information\n about current version of an object. For a versioned bucket, you can have multiple versions\n of an object in your bucket. To retrieve tags of any other version, use the versionId query\n parameter. You also need permission for the s3:GetObjectVersionTagging\n action.

\n

By default, the bucket owner has this permission and can grant this permission to\n others.

\n

For information about the Amazon S3 object tagging feature, see Object Tagging.

\n

The following actions are related to GetObjectTagging:

\n ", "smithy.api#examples": [ { - "title": "To retrieve tag set of an object", - "documentation": "The following example retrieves tag set of an object.", + "title": "To retrieve tag set of a specific object version", + "documentation": "The following example retrieves tag set of an object. The request specifies object version.", "input": { "Bucket": "examplebucket", - "Key": "HappyFace.jpg" + "Key": "exampleobject", + "VersionId": "ydlaNkwWm0SfKJR.T1b1fIdPRbldTYRI" }, "output": { - "VersionId": "null", + "VersionId": "ydlaNkwWm0SfKJR.T1b1fIdPRbldTYRI", "TagSet": [ { - "Value": "Value4", - "Key": "Key4" - }, - { - "Value": "Value3", - "Key": "Key3" + "Value": "Value1", + "Key": "Key1" } ] } }, { - "title": "To retrieve tag set of a specific object version", - "documentation": "The following example retrieves tag set of an object. The request specifies object version.", + "title": "To retrieve tag set of an object", + "documentation": "The following example retrieves tag set of an object.", "input": { "Bucket": "examplebucket", - "Key": "exampleobject", - "VersionId": "ydlaNkwWm0SfKJR.T1b1fIdPRbldTYRI" + "Key": "HappyFace.jpg" }, "output": { - "VersionId": "ydlaNkwWm0SfKJR.T1b1fIdPRbldTYRI", + "VersionId": "null", "TagSet": [ { - "Value": "Value1", - "Key": "Key1" + "Value": "Value4", + "Key": "Key4" + }, + { + "Value": "Value3", + "Key": "Key3" } ] } @@ -26635,6 +26637,44 @@ "traits": { "smithy.api#documentation": "\n

This operation is not supported by directory buckets.

\n \n

Returns metadata about all versions of the objects in a bucket. You can also use request\n parameters as selection criteria to return metadata about a subset of all the object\n versions.

\n \n

To use this operation, you must have permission to perform the\n s3:ListBucketVersions action. Be aware of the name difference.

\n \n \n

A 200 OK response can contain valid or invalid XML. Make sure to design\n your application to parse the contents of the response and handle it\n appropriately.

\n \n

To use this operation, you must have READ access to the bucket.

\n

The following operations are related to ListObjectVersions:

\n ", "smithy.api#examples": [ + { + "title": "To list object versions", + "documentation": "The following example return versions of an object with specific key name prefix. The request limits the number of items returned to two. If there are are more than two object version, S3 returns NextToken in the response. You can specify this token value in your next request to fetch next set of object versions.", + "input": { + "Bucket": "examplebucket", + "Prefix": "HappyFace.jpg" + }, + "output": { + "Versions": [ + { + "LastModified": "2016-12-15T01:19:41.000Z", + "VersionId": "null", + "ETag": "\"6805f2cfc46c0f04559748bb039d69ae\"", + "StorageClass": "STANDARD", + "Key": "HappyFace.jpg", + "Owner": { + "DisplayName": "owner-display-name", + "ID": "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc" + }, + "IsLatest": true, + "Size": 3191 + }, + { + "LastModified": "2016-12-13T00:58:26.000Z", + "VersionId": "PHtexPGjH2y.zBgT8LmB7wwLI2mpbz.k", + "ETag": "\"6805f2cfc46c0f04559748bb039d69ae\"", + "StorageClass": "STANDARD", + "Key": "HappyFace.jpg", + "Owner": { + "DisplayName": "owner-display-name", + "ID": "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc" + }, + "IsLatest": false, + "Size": 3191 + } + ] + } + }, { "title": "To list object versions", "documentation": "The following example returns versions of an object with specific key name prefix.", @@ -30539,17 +30579,30 @@ "smithy.api#documentation": "

Adds an object to a bucket.

\n \n
    \n
  • \n

    Amazon S3 never adds partial objects; if you receive a success response, Amazon S3 added the\n entire object to the bucket. You cannot use PutObject to only update a\n single piece of metadata for an existing object. You must put the entire object with\n updated metadata if you want to update some values.

    \n
    • \n
  • \n

    If your bucket uses the bucket owner enforced setting for Object Ownership, ACLs are disabled and no longer affect permissions. All\n objects written to the bucket by any account will be owned by the bucket owner.

    \n
    • \n
  • \n

    \n Directory buckets - 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 https://bucket_name.s3express-az_id.region.amazonaws.com/key-name\n . Path-style requests are not supported. For more information, see Regional and Zonal endpoints in the\n Amazon S3 User Guide.

    \n
    • \n
\n \n

Amazon S3 is a distributed system. If it receives multiple write requests for the same object\n simultaneously, it overwrites all but the last object written. However, Amazon S3 provides features that can modify this behavior:

\n \n
\n
Permissions
\n
\n
    \n
  • \n

    \n General purpose bucket permissions - The following permissions are required in your policies when your \n PutObject request includes specific headers.

    \n
      \n
    • \n

      \n \n s3:PutObject\n - To successfully complete the PutObject request, you must always have the s3:PutObject permission on a bucket to add an object\n to it.

      \n
      • \n
    • \n

      \n \n s3:PutObjectAcl\n - To successfully change the objects ACL of your PutObject request, you must have the s3:PutObjectAcl.

      \n
      • \n
    • \n

      \n \n s3:PutObjectTagging\n - To successfully set the tag-set with your PutObject request, you\n must have the s3:PutObjectTagging.

      \n
      • \n
    \n
    • \n
  • \n

    \n Directory bucket permissions - To grant access to this API operation on a directory bucket, we recommend that you use the \n CreateSession\n API operation for session-based authorization. Specifically, you grant the s3express:CreateSession permission to the directory bucket in a bucket policy or an IAM identity-based policy. Then, you make the CreateSession API call on the bucket to obtain a session token. With the session token in your request header, you can make API requests to this operation. After the session token expires, you make another CreateSession API call to generate a new session token for use. \nAmazon Web Services CLI or SDKs create session and refresh the session token automatically to avoid service interruptions when a session expires. For more information about authorization, see \n CreateSession\n .

    \n
    • \n
\n
\n
Data integrity with Content-MD5
\n
\n
    \n
  • \n

    \n General purpose bucket - To ensure that data is not corrupted traversing the network, use the\n Content-MD5 header. When you use this header, Amazon S3 checks the object\n against the provided MD5 value and, if they do not match, Amazon S3 returns an error. Alternatively, when the object's ETag is its MD5 digest, \n you can calculate the MD5 while putting the object to Amazon S3 and compare the returned ETag to\n the calculated MD5 value.

    \n
    • \n
  • \n

    \n Directory bucket - This functionality is not supported for directory buckets.

    \n
    • \n
\n
\n
HTTP Host header syntax
\n
\n

\n Directory buckets - The HTTP Host header syntax is \n Bucket_name.s3express-az_id.region.amazonaws.com.

\n
\n
\n

For more information about related Amazon S3 APIs, see the following:

\n ", "smithy.api#examples": [ { - "title": "To upload an object and specify server-side encryption and object tags", - "documentation": "The following example uploads an object. The request specifies the optional server-side encryption option. The request also specifies optional object tags. If the bucket is versioning enabled, S3 returns version ID in response.", + "title": "To upload an object", + "documentation": "The following example uploads an object to a versioning-enabled bucket. The source file is specified using Windows file syntax. S3 returns VersionId of the newly created object.", "input": { - "Body": "filetoupload", + "Body": "HappyFace.jpg", "Bucket": "examplebucket", - "Key": "exampleobject", + "Key": "HappyFace.jpg" + }, + "output": { + "VersionId": "tpf3zF08nBplQK1XLOefGskR7mGDwcDk", + "ETag": "\"6805f2cfc46c0f04559748bb039d69ae\"" + } + }, + { + "title": "To upload an object (specify optional headers)", + "documentation": "The following example uploads an object. The request specifies optional request headers to directs S3 to use specific storage class and use server-side encryption.", + "input": { + "Body": "HappyFace.jpg", + "Bucket": "examplebucket", + "Key": "HappyFace.jpg", "ServerSideEncryption": "AES256", - "Tagging": "key1=value1&key2=value2" + "StorageClass": "STANDARD_IA" }, "output": { - "VersionId": "Ri.vC6qVlA4dEnjgRV4ZHsHoFIjqEMNt", + "VersionId": "CG612hodqujkf8FaaNfp8U..FIhLROcp", "ETag": "\"6805f2cfc46c0f04559748bb039d69ae\"", "ServerSideEncryption": "AES256" } @@ -30585,19 +30638,6 @@ "ETag": "\"6805f2cfc46c0f04559748bb039d69ae\"" } }, - { - "title": "To upload an object", - "documentation": "The following example uploads an object to a versioning-enabled bucket. The source file is specified using Windows file syntax. S3 returns VersionId of the newly created object.", - "input": { - "Body": "HappyFace.jpg", - "Bucket": "examplebucket", - "Key": "HappyFace.jpg" - }, - "output": { - "VersionId": "tpf3zF08nBplQK1XLOefGskR7mGDwcDk", - "ETag": "\"6805f2cfc46c0f04559748bb039d69ae\"" - } - }, { "title": "To create an object.", "documentation": "The following example creates an object. If the bucket is versioning enabled, S3 returns version ID in response.", @@ -30612,17 +30652,17 @@ } }, { - "title": "To upload an object (specify optional headers)", - "documentation": "The following example uploads an object. The request specifies optional request headers to directs S3 to use specific storage class and use server-side encryption.", + "title": "To upload an object and specify server-side encryption and object tags", + "documentation": "The following example uploads an object. The request specifies the optional server-side encryption option. The request also specifies optional object tags. If the bucket is versioning enabled, S3 returns version ID in response.", "input": { - "Body": "HappyFace.jpg", + "Body": "filetoupload", "Bucket": "examplebucket", - "Key": "HappyFace.jpg", + "Key": "exampleobject", "ServerSideEncryption": "AES256", - "StorageClass": "STANDARD_IA" + "Tagging": "key1=value1&key2=value2" }, "output": { - "VersionId": "CG612hodqujkf8FaaNfp8U..FIhLROcp", + "VersionId": "Ri.vC6qVlA4dEnjgRV4ZHsHoFIjqEMNt", "ETag": "\"6805f2cfc46c0f04559748bb039d69ae\"", "ServerSideEncryption": "AES256" }