PUT Bucket website
Description
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,
go to
Hosting Websites on Amazon S3 in the
Amazon Simple Storage Service Developer Guide.
This PUT
operation 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.
Requests
Syntax
PUT /?website HTTP/1.1 Host:
bucketname
.s3.amazonaws.com Date:date
Content-Length:ContentLength
Authorization:authorization string
(see Authenticating Requests (AWS Signature Version 4)) <WebsiteConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"><!-- website configuration information. -->
</WebsiteConfiguration>
Request Parameters
This implementation of the operation does not use request parameters.
Request Headers
This implementation of the operation uses only request headers that are common to all operations. For more information, see Common Request Headers.
Request Elements
You can use a website configuration to redirect all requests to the website endpoint of a bucket, or you can add routing rules that redirect only specific requests.
-
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.
Name Description Required WebsiteConfiguration
The root element for the website configuration
Type: Container
Ancestors: None
Yes RedirectAllRequestsTo
Describes the redirect behavior for every request to this bucket's website endpoint. If this element is present, no other siblings are allowed.
Type: Container
Ancestors: WebsiteConfiguration
Yes HostName
Name of the host where requests will be redirected.
Type: String
Ancestors: RedirectAllRequestsTo
Yes Protocol
Protocol to use (http, https) when redirecting requests. The default is the protocol that is used in the original request.
Type: String
Ancestors: RedirectAllRequestsTo
No -
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.
Name Description Required WebsiteConfiguration
Container for the request
Type: Container
Ancestors: None
Yes IndexDocument
Container for the
Suffix
element.Type: Container
Ancestors: WebsiteConfiguration
Yes Suffix
A suffix that is appended to a request that is for a directory on the website endpoint (e.g., if the suffix is index.html and you make a request to
samplebucket/images/
, the data that is returned will be for the object with the key name images/index.html)The suffix must not be empty and must not include a slash character.
Type: String
Ancestors: WebsiteConfiguration.IndexDocument
Yes ErrorDocument
Container for the
Key
elementType: Container
Ancestors: WebsiteConfiguration
No Key
The object key name to use when a 4XX class error occurs. This key identifies the page that is returned when such an error occurs.
Type: String
Ancestors: WebsiteConfiguration.ErrorDocument
Condition: Required when
ErrorDocument
is specified.Conditional RoutingRules
Container for a collection of RoutingRule elements.
Type: Container
Ancestors: WebsiteConfiguration
No RoutingRule
Container for one routing rule that identifies a condition and a redirect that applies when the condition is met.
Type: String
Ancestors: WebsiteConfiguration.RoutingRules
Condition: In a
RoutingRules
container, there must be at least one ofRoutingRule
element.Yes Condition
A container for describing a condition that must be met for the specified redirect to apply. For example:
-
If request is for pages in the
/docs
folder, redirect to the/documents
folder. -
If request results in HTTP error 4xx, redirect request to another host where you might process the error.
Type: Container
Ancestors: WebsiteConfiguration.RoutingRules.RoutingRule
No KeyPrefixEquals
The object key name prefix when the redirect is applied. For example, to redirect requests for
ExamplePage.html
, the key prefix will beExamplePage.html
. To redirect request for all pages with the prefixdocs/
, the key prefix will be/docs
, which identifies all objects in thedocs/
folder.Type: String
Ancestors: WebsiteConfiguration.RoutingRules.RoutingRule.Condition
Condition: Required when the parent element
Condition
is specified and siblingHttpErrorCodeReturnedEquals
is not specified. If both conditions are specified, both must be true for the redirect to be applied.Conditional HttpErrorCodeReturnedEquals
The HTTP error code when the redirect is applied. In the event of an error, if the error code equals this value, then the specified redirect is applied.
Type: String
Ancestors: WebsiteConfiguration.RoutingRules.RoutingRule.Condition
Condition: Required when parent element
Condition
is specified and siblingKeyPrefixEquals
is not specified. If both are specified, then both must be true for the redirect to be applied.Conditional Redirect
Container for redirect information. You can redirect requests to another host, to another page, or with another protocol. In the event of an error, you can specify a different error code to return.
Type: String
Ancestors: WebsiteConfiguration.RoutingRules.RoutingRule
Yes Protocol
The protocol to use in the redirect request.
Type: String
Ancestors: WebsiteConfiguration.RoutingRules.RoutingRule.Redirect
Valid Values: http, https
Condition: Not required if one of the siblings is present
No HostName
The host name to use in the redirect request.
Type: String
Ancestors: WebsiteConfiguration.RoutingRules.RoutingRule.Redirect
Condition: Not required if one of the siblings is present
No ReplaceKeyPrefixWith
The object key prefix to use in the redirect request. For example, to redirect requests for all pages with prefix
docs/
(objects in thedocs/
folder) todocuments/
, you can set acondition
block withKeyPrefixEquals
set todocs/
and in theRedirect
setReplaceKeyPrefixWith
to/documents
.Type: String
Ancestors: WebsiteConfiguration.RoutingRules.RoutingRule.Redirect
Condition: Not required if one of the siblings is present. Can be present only if
ReplaceKeyWith
is not provided.No ReplaceKeyWith
The specific object key to use in the redirect request. For example, redirect request to
error.html
.Type: String
Ancestors: WebsiteConfiguration.RoutingRules.RoutingRule.Redirect
Condition: Not required if one of the sibling is present. Can be present only if
ReplaceKeyPrefixWith
is not provided.No HttpRedirectCode
The HTTP redirect code to use on the response.
Type: String
Ancestors: WebsiteConfiguration.RoutingRules.RoutingRule.Redirect
Condition: Not required if one of the siblings is present.
No -
Responses
Response Headers
This implementation of the operation uses only response headers that are common to most responses. For more information, see Common Response Headers.
Response Elements
This implementation of the operation does not return response elements.
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.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>
Amazon S3 returns the following sample response.
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
.
PUT ?website HTTP/1.1 Host: www.example.com.s3.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>
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
. For more
information, go to Hosting
Websites on Amazon S3 in the Amazon Simple Storage Service Developer Guide.
Example 3: Configure bucket as a website and also 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 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.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 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 a object key prefix report-404/
in the redirect. For example,
if you request a page ExamplePage.html
and it results in a 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.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.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>