PutBucketWebsite
Note
This operation is not supported by directory buckets.
Sets the configuration of the website that is specified in the website
subresource. To configure a bucket as a website, you can add this subresource on the bucket
with website configuration information such as the file name of the index document and any
redirect rules. For more information, see Hosting Websites on Amazon S3.
This PUT action requires the S3:PutBucketWebsite
permission. By default,
only the bucket owner can configure the website attached to a bucket; however, bucket
owners can allow other users to set the website configuration by writing a bucket policy
that grants them the S3:PutBucketWebsite
permission.
To redirect all website requests sent to the bucket's website endpoint, you add a website configuration with the following elements. Because all requests are sent to another website, you don't need to provide index document name for the bucket.
-
WebsiteConfiguration
-
RedirectAllRequestsTo
-
HostName
-
Protocol
If you want granular control over redirects, you can use the following elements to add routing rules that describe conditions for redirecting requests and information about the redirect destination. In this case, the website configuration must provide an index document for the bucket, because some requests might not be redirected.
-
WebsiteConfiguration
-
IndexDocument
-
Suffix
-
ErrorDocument
-
Key
-
RoutingRules
-
RoutingRule
-
Condition
-
HttpErrorCodeReturnedEquals
-
KeyPrefixEquals
-
Redirect
-
Protocol
-
HostName
-
ReplaceKeyPrefixWith
-
ReplaceKeyWith
-
HttpRedirectCode
Amazon S3 has a limitation of 50 routing rules per website configuration. If you require more than 50 routing rules, you can use object redirect. For more information, see Configuring an Object Redirect in the Amazon S3 User Guide.
The maximum request length is limited to 128 KB.
Request Syntax
PUT /?website HTTP/1.1
Host: Bucket
.s3.amazonaws.com
Content-MD5: ContentMD5
x-amz-sdk-checksum-algorithm: ChecksumAlgorithm
x-amz-expected-bucket-owner: ExpectedBucketOwner
<?xml version="1.0" encoding="UTF-8"?>
<WebsiteConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<ErrorDocument>
<Key>string
</Key>
</ErrorDocument>
<IndexDocument>
<Suffix>string
</Suffix>
</IndexDocument>
<RedirectAllRequestsTo>
<HostName>string
</HostName>
<Protocol>string
</Protocol>
</RedirectAllRequestsTo>
<RoutingRules>
<RoutingRule>
<Condition>
<HttpErrorCodeReturnedEquals>string
</HttpErrorCodeReturnedEquals>
<KeyPrefixEquals>string
</KeyPrefixEquals>
</Condition>
<Redirect>
<HostName>string
</HostName>
<HttpRedirectCode>string
</HttpRedirectCode>
<Protocol>string
</Protocol>
<ReplaceKeyPrefixWith>string
</ReplaceKeyPrefixWith>
<ReplaceKeyWith>string
</ReplaceKeyWith>
</Redirect>
</RoutingRule>
</RoutingRules>
</WebsiteConfiguration>
URI Request Parameters
The request uses the following URI parameters.
- Bucket
-
The bucket name.
Required: Yes
- Content-MD5
-
The base64-encoded 128-bit MD5 digest of the data. You must use this header as a message integrity check to verify that the request body was not corrupted in transit. For more information, see RFC 1864
. For requests made using the AWS Command Line Interface (CLI) or AWS SDKs, this field is calculated automatically.
- x-amz-expected-bucket-owner
-
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 code
403 Forbidden
(access denied). - x-amz-sdk-checksum-algorithm
-
Indicates the algorithm used to create the checksum for the object when you use the SDK. This header will not provide any additional functionality if you don't use the SDK. When you send this header, there must be a corresponding
x-amz-checksum
orx-amz-trailer
header sent. Otherwise, Amazon S3 fails the request with the HTTP status code400 Bad Request
. For more information, see Checking object integrity in the Amazon S3 User Guide.If you provide an individual checksum, Amazon S3 ignores any provided
ChecksumAlgorithm
parameter.Valid Values:
CRC32 | CRC32C | SHA1 | SHA256
Request Body
The request accepts the following data in XML format.
- WebsiteConfiguration
-
Root level tag for the WebsiteConfiguration parameters.
Required: Yes
- ErrorDocument
-
The name of the error document for the website.
Type: ErrorDocument data type
Required: No
- IndexDocument
-
The name of the index document for the website.
Type: IndexDocument data type
Required: No
- RedirectAllRequestsTo
-
The redirect behavior for every request to this bucket's website endpoint.
Important
If you specify this property, you can't specify any other property.
Type: RedirectAllRequestsTo data type
Required: No
- RoutingRules
-
Rules that define when a redirect is applied and the redirect behavior.
Type: Array of RoutingRule data types
Required: No
Response Syntax
HTTP/1.1 200
Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Examples
Example 1: Configure bucket as a website (add website configuration)
The following request configures a bucket example.com as a website. The configuration in the request specifies index.html as the index document. It also specifies the optional error document, SomeErrorDocument.html.
PUT ?website HTTP/1.1 Host: example.com.s3.<Region>.amazonaws.com Content-Length: 256 Date: Thu, 27 Jan 2011 12:00:00 GMT Authorization: signatureValue <WebsiteConfiguration xmlns='http://s3.amazonaws.com/doc/2006-03-01/'> <IndexDocument> <Suffix>index.html</Suffix> </IndexDocument> <ErrorDocument> <Key>SomeErrorDocument.html</Key> </ErrorDocument> </WebsiteConfiguration>
Sample Response
This example illustrates one usage of PutBucketWebsite.
HTTP/1.1 200 OK x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo x-amz-request-id: 80CD4368BD211111 Date: Thu, 27 Jan 2011 00:00:00 GMT Content-Length: 0 Server: AmazonS3
Example 2: Configure bucket as a website but redirect all requests
The following request configures a bucket www.example.com
as a
website. However, the configuration specifies that all GET requests for the
www.example.com bucket's website endpoint will be redirected to host example.com.
This redirect can be useful when you want to serve requests for both
http://www.example.com
and http://example.com
, but you
want to maintain the website content in only one bucket, in this case,
example.com
.
PUT ?website HTTP/1.1 Host: www.example.com.s3.<Region>.amazonaws.com Content-Length: length-value Date: Thu, 27 Jan 2011 12:00:00 GMT Authorization: signatureValue <WebsiteConfiguration xmlns='http://s3.amazonaws.com/doc/2006-03-01/'> <RedirectAllRequestsTo> <HostName>example.com</HostName> </RedirectAllRequestsTo> </WebsiteConfiguration>
Example 3: Configure bucket as a website and specify optional redirection rules
Example 1 is the simplest website configuration. It configures a bucket as a website by providing only an index document and an error document. You can further customize the website configuration by adding routing rules that redirect requests for one or more objects. For example, suppose that your bucket contained the following objects:
-
index.html
-
docs/article1.html
-
docs/article2.html
If you decided to rename the folder from docs/
to
documents/
, you would need to redirect requests for prefix
/docs
to documents/
. For example, a request for
docs/article1.html will need to be redirected to documents/article1.html.
In this case, you update the website configuration and add a routing rule as shown in the following request.
PUT ?website HTTP/1.1 Host: www.example.com.s3.<Region>.amazonaws.com Content-Length: length-value Date: Thu, 27 Jan 2011 12:00:00 GMT Authorization: signatureValue <WebsiteConfiguration xmlns='http://s3.amazonaws.com/doc/2006-03-01/'> <IndexDocument> <Suffix>index.html</Suffix> </IndexDocument> <ErrorDocument> <Key>Error.html</Key> </ErrorDocument> <RoutingRules> <RoutingRule> <Condition> <KeyPrefixEquals>docs/</KeyPrefixEquals> </Condition> <Redirect> <ReplaceKeyPrefixWith>documents/</ReplaceKeyPrefixWith> </Redirect> </RoutingRule> </RoutingRules> </WebsiteConfiguration>
Example 4: Configure a bucket as a website and redirect errors
You can use a routing rule to specify a condition that checks for a specific HTTP
error code. When a page request results in this error, you can optionally reroute
requests. For example, you might route requests to another host and optionally
process the error. The routing rule in the following requests redirects requests to
an EC2 instance in the event of an HTTP error 404. For illustration, the redirect
also inserts an object key prefix report-404/
in the redirect. For
example, if you request a page ExamplePage.html
and it results in an
HTTP 404 error, the request is routed to a page report-404/testPage.html
on the specified EC2 instance. If there is no routing rule and the HTTP error 404
occurred, then Error.html
would be returned.
PUT ?website HTTP/1.1 Host: www.example.com.s3.<Region>.amazonaws.com Content-Length: 580 Date: Thu, 27 Jan 2011 12:00:00 GMT Authorization: signatureValue <WebsiteConfiguration xmlns='http://s3.amazonaws.com/doc/2006-03-01/'> <IndexDocument> <Suffix>index.html</Suffix> </IndexDocument> <ErrorDocument> <Key>Error.html</Key> </ErrorDocument> <RoutingRules> <RoutingRule> <Condition> <HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals > </Condition> <Redirect> <HostName>ec2-11-22-333-44.compute-1.amazonaws.com</HostName> <ReplaceKeyPrefixWith>report-404/</ReplaceKeyPrefixWith> </Redirect> </RoutingRule> </RoutingRules> </WebsiteConfiguration>
Example 5: Configure a bucket as a website and redirect folder requests to a page
Suppose you have the following pages in your bucket:
-
images/photo1.jpg
-
images/photo2.jpg
-
images/photo3.jpg
Now you want to route requests for all pages with the images/ prefix to go to a single page, errorpage.html. You can add a website configuration to your bucket with the routing rule shown in the following request.
PUT ?website HTTP/1.1 Host: www.example.com.s3.<Region>.amazonaws.com Content-Length: 481 Date: Thu, 27 Jan 2011 12:00:00 GMT Authorization: signatureValue <WebsiteConfiguration xmlns='http://s3.amazonaws.com/doc/2006-03-01/'> <IndexDocument> <Suffix>index.html</Suffix> </IndexDocument> <ErrorDocument> <Key>Error.html</Key> </ErrorDocument> <RoutingRules> <RoutingRule> <Condition> <KeyPrefixEquals>images/</KeyPrefixEquals> </Condition> <Redirect> <ReplaceKeyWith>errorpage.html</ReplaceKeyWith> </Redirect> </RoutingRule> </RoutingRules> </WebsiteConfiguration>
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: