Description¶

You can use this operation to determine if a bucket exists and if you have permission to access it. The action returns a200OK HTTP status code if the bucket exists and you have permission to access it. You can make aHeadBucket call on any bucket name to any Region in the partition, and regardless of the permissions on the bucket, you will receive a response header with the correct bucket location so that you can then make a proper, signed request to the appropriate Regional endpoint.

Amazon Web Services CLI or SDKs handles authentication and authorization on your behalf.

Permissions

• General purpose bucket permissions - To use this operation, you must have permissions to perform thes3:ListBucket action. The bucket owner has this permission by default and can grant this permission to others. For more information about permissions, seeManaging access permissions to your Amazon S3 resources in theAmazon S3 User Guide .

• Directory bucket permissions - You must have the **s3express:CreateSession ** permission in theAction element of a policy. By default, the session is in theReadWrite mode. If you want to restrict the access, you can explicitly set thes3express:SessionMode condition key toReadOnly on the bucket. For more information about example bucket policies, seeExample bucket policies for S3 Express One Zone andAmazon Web Services Identity and Access Management (IAM) identity-based policies for S3 Express One Zone in theAmazon S3 User Guide .

  HTTP Host header syntax

Directory buckets - The HTTP Host header syntax is ``Bucket-name .s3express-zone-id .*region-code* .amazonaws.com`` .

See also:AWS API Documentation

Synopsis¶

head-bucket--bucket<value>[--expected-bucket-owner<value>][--cli-input-json|--cli-input-yaml][--generate-cli-skeleton<value>][--debug][--endpoint-url<value>][--no-verify-ssl][--no-paginate][--output<value>][--query<value>][--profile<value>][--region<value>][--version<value>][--color<value>][--no-sign-request][--ca-bundle<value>][--cli-read-timeout<value>][--cli-connect-timeout<value>][--cli-binary-format<value>][--no-cli-pager][--cli-auto-prompt][--no-cli-auto-prompt]

Options¶

--bucket (string) [required]

The bucket name.

Directory buckets - When you use this operation with a directory bucket, you must use virtual-hosted-style requests in the format ``Bucket-name .s3express-zone-id .*region-code* .amazonaws.com`` . Path-style requests are not supported. Directory bucket names must be unique in the chosen Zone (Availability Zone or Local Zone). Bucket names must follow the format ``bucket-base-name –zone-id –x-s3`` (for example, ``amzn-s3-demo-bucket –usw2-az1 –x-s3`` ). For information about bucket naming restrictions, seeDirectory bucket naming rules in theAmazon S3 User Guide .

Access points - When you use this action with an access point for general purpose buckets, you must provide the alias of the access point in place of the bucket name or specify the access point ARN. When you use this action with an access point for directory buckets, you must provide the access point name in place of the bucket name. When using the access point ARN, you must direct requests to the access point hostname. The access point hostname takes the formAccessPointName -AccountId .s3-accesspoint.*Region* .amazonaws.com. When using this action with an access point through the Amazon Web Services SDKs, you provide the access point ARN in place of the bucket name. For more information about access point ARNs, seeUsing access points in theAmazon S3 User Guide .

Object Lambda access points - When you use this API operation with an Object Lambda access point, provide the alias of the Object Lambda access point in place of the bucket name. If the Object Lambda access point alias in a request is not valid, the error codeInvalidAccessPointAliasError is returned. For more information aboutInvalidAccessPointAliasError , seeList of Error Codes .

Note

Object Lambda access points are not supported by directory buckets.

S3 on Outposts - When you use this action with S3 on Outposts, you must direct requests to the S3 on Outposts hostname. The S3 on Outposts hostname takes the form ``AccessPointName -AccountId .*outpostID* .s3-outposts.*Region* .amazonaws.com`` . When you use this action with S3 on Outposts, the destination bucket must be the Outposts access point ARN or the access point alias. For more information about S3 on Outposts, seeWhat is S3 on Outposts? in theAmazon S3 User Guide .

--expected-bucket-owner (string)

The account ID of the expected bucket owner. If the account ID that you provide does not match the actual owner of the bucket, the request fails with the HTTP status code403Forbidden (access denied).

--cli-input-json |--cli-input-yaml (string)Reads arguments from the JSON string provided. The JSON string follows the format provided by--generate-cli-skeleton. If other arguments are provided on the command line, those values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally. This may not be specified along with--cli-input-yaml.

--generate-cli-skeleton (string)Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the valueinput, prints a sample input JSON that can be used as an argument for--cli-input-json. Similarly, if providedyaml-input it will print a sample input YAML that can be used with--cli-input-yaml. If provided with the valueoutput, it validates the command inputs and returns a sample output JSON for that command. The generated JSON skeleton is not stable between versions of the AWS CLI and there are no backwards compatibility guarantees in the JSON skeleton generated.

Global Options¶

--debug (boolean)

Turn on debug logging.

--endpoint-url (string)

Override command’s default URL with the given URL.

--no-verify-ssl (boolean)

By default, the AWS CLI uses SSL when communicating with AWS services. For each SSL connection, the AWS CLI will verify SSL certificates. This option overrides the default behavior of verifying SSL certificates.

--no-paginate (boolean)

Disable automatic pagination. If automatic pagination is disabled, the AWS CLI will only make one call, for the first page of results.

--output (string)

The formatting style for command output.

• json
• text
• table
• yaml
• yaml-stream

--query (string)

A JMESPath query to use in filtering the response data.

--profile (string)

Use a specific profile from your credential file.

--region (string)

The region to use. Overrides config/env settings.

--version (string)

Display the version of this tool.

--color (string)

Turn on/off color output.

• on
• off
• auto

--no-sign-request (boolean)

Do not sign requests. Credentials will not be loaded if this argument is provided.

--ca-bundle (string)

The CA certificate bundle to use when verifying SSL certificates. Overrides config/env settings.

--cli-read-timeout (int)

The maximum socket read time in seconds. If the value is set to 0, the socket read will be blocking and not timeout. The default value is 60 seconds.

--cli-connect-timeout (int)

The maximum socket connect time in seconds. If the value is set to 0, the socket connect will be blocking and not timeout. The default value is 60 seconds.

--cli-binary-format (string)

The formatting style to be used for binary blobs. The default format is base64. The base64 format expects binary blobs to be provided as a base64 encoded string. The raw-in-base64-out format preserves compatibility with AWS CLI V1 behavior and binary values must be passed literally. When providing contents from a file that map to a binary blobfileb:// will always be treated as binary and use the file contents directly regardless of thecli-binary-format setting. When usingfile:// the file contents will need to properly formatted for the configuredcli-binary-format.

• base64
• raw-in-base64-out

--no-cli-pager (boolean)

Disable cli pager for output.

--cli-auto-prompt (boolean)

Automatically prompt for CLI input parameters.

--no-cli-auto-prompt (boolean)

Disable automatically prompt for CLI input parameters.

Examples¶

The following command verifies access to a bucket namedamzn-s3-demo-bucket:

awss3apihead-bucket--bucketamzn-s3-demo-bucket

If the bucket exists and you have access to it, no output is returned. Otherwise, an error message will be shown. For example:

Aclienterror(404)occurredwhencallingtheHeadBucketoperation:NotFound

Output¶

BucketArn -> (string)

The Amazon Resource Name (ARN) of the S3 bucket. ARNs uniquely identify Amazon Web Services resources across all of Amazon Web Services.

Note

This parameter is only supported for S3 directory buckets. For more information, seeUsing tags with directory buckets .

Constraints:

• min:1
• max:128
• pattern:arn:[^:]+:(s3|s3express):.*

BucketLocationType -> (string)

The type of location where the bucket is created.

Note

This functionality is only supported by directory buckets.

Possible values:

• AvailabilityZone
• LocalZone

BucketLocationName -> (string)

The name of the location where the bucket will be created.

For directory buckets, the Zone ID of the Availability Zone or the Local Zone where the bucket is created. An example Zone ID value for an Availability Zone isusw2-az1 .

Note

This functionality is only supported by directory buckets.

BucketRegion -> (string)

The Region that the bucket is located.

Constraints:

• min:0
• max:20

AccessPointAlias -> (boolean)

Indicates whether the bucket name used in the request is an access point alias.

Note

For directory buckets, the value of this field isfalse .