PUT Bucket website¶
You can use this operation to create or update the website configuration of a bucket.
OBS allows you to store static web page resources such as HTML web pages, flash files, video files, and audio files to a bucket. When a client accesses these resources from the website endpoint of the bucket, the browser can directly resolve and present the resources to the client. This operation can be used to:
Redirect all requests to a website endpoint.
Add routing rules that redirect specific requests.
Only users granted the s3:PutBucketWebsite permission can set the bucket website configuration. By default, only the bucket owner can set the bucket website configuration. The bucket owner can allow other users to set the bucket website configuration by granting them the permission. After the bucket website configuration is set, it will take effect within two minutes.
Note
Avoid using periods (.) in the target bucket name. Otherwise, the client may fail to authenticate the certificate when you use HTTPS for access.
Request Syntax¶
PUT /?website HTTP/1.1
User-Agent: agent
Host: bucketname.obs.example.com
Accept: */*
Content-Length: length
Date: date
Authorization: authorization
Expect: expect
<WebsiteConfiguration>
<RedirectAllRequestsTo>
<HostName>hostName</HostName>
</RedirectAllRequestsTo>
</WebsiteConfiguration>
Request Parameters¶
This request involves no parameters.
Request Headers¶
This request uses common headers. For details about common request headers, see section Common Request Headers.
Request Elements¶
This request contains elements to specify the website configuration in the XML format. The elements differ for situations where users want to redirect all requests to a website endpoint and for when users want to add routing rules that redirect specific requests.
To redirect all websites requests sent to the bucket's website endpoint, add the elements as described in Table 1.
Element | Description | Remarks |
|---|---|---|
WebsiteConfiguration | Indicates the root element for the website configuration. Type: Container Ancestor: None | Mandatory |
RedirectAllRequestsTo | Describes the redirection behavior for every request to this bucket's website endpoint. If this element is present, no other siblings are allowed. Type: Container Ancestor: WebsiteConfiguration | Mandatory |
HostName | Indicates the name of the host where requests will be redirected. Type: String Ancestor: RedirectAllRequestsTo | Mandatory |
Protocol | Indicates the protocol (HTTP and HTTPS) used in redirecting requests. The default protocol is HTTP. Type: String Ancestor: RedirectAllRequestsTo | Optional |
To add routing rules that describe conditions for redirecting requests, add the elements as described in Table 2.
Element | Description | Remarks |
|---|---|---|
WebsiteConfiguration | Indicates the root element for the website configuration. Type: Container Ancestor: None | Mandatory |
IndexDocument | Indicates the container for the Suffix element. Type: Container Ancestor: WebsiteConfiguration | Mandatory |
Suffix | Indicates a suffix that is appended to a request initiated for a directory on the website endpoint. For example, if the suffix is index.html and you request for samplebucket/images/, the data that is returned will be for the object with the key name images/index.html in the samplebucket bucket. The suffix cannot be empty or contain slashes (/). Type: String Ancestor: IndexDocument | Mandatory |
ErrorDocument | Indicates the container for the Key element. Type: Container Ancestor: WebsiteConfiguration | Optional |
key | Indicates the object key that is used when a 4xx error occurs. This element identifies the page that is returned when a 4xx error occurs. Type: String Ancestor: ErrorDocument Condition: Required when ErrorDocument is specified. | Optional |
RoutingRules | Indicates the container for the RoutingRule element. Type: Container Ancestor: WebsiteConfiguration | Optional |
RoutingRule | Indicates the container for a routing rule that identifies a condition and a redirect applicable when the condition is met. Type: Container Ancestor: RoutingRules Condition: In a RoutingRules container, there must be at least one RoutingRule element. | Mandatory |
Condition | Indicates the container for describing a condition that must be met for the specified redirect to apply. Type: Container Ancestor: RoutingRule | Optional |
KeyPrefixEquals | Indicates the object key name prefix when the redirection is applied. For example:
Type: String Ancestor: Condition Condition: Required when the parent element HttpErrorCodeReturnedEquals is not specified. If two conditions are specified, both conditions must be true for the redirection to be applied. | Optional |
HttpErrorCodeReturnedEquals | Indicates the HTTP error code returned when the redirection is applied. The specified redirect is applied only when the error code returned equals to this value. For example:
Type: String Ancestor: Condition Condition: Required when parent element Condition is specified and sibling KeyPrefixEquals is not specified. If multiple conditions are specified, the redirection takes effect only after all conditions are met. | Optional |
Redirect | Indicates the container for redirect information. You can redirect requests to another host, to another web page, or with another protocol. You can specify an error code to be returned after an error. Type: Container Ancestor: RoutingRule | Mandatory |
Protocol | Indicates the protocol used in the redirection request. Type: String Ancestor: Redirect Valid Values: http, https Condition: Not required if one of the siblings is present. | Optional |
HostName | Indicates the host name used in the redirection request. Type: String Ancestor: Redirect Condition: Not required if one of the siblings is present. | Optional |
ReplaceKeyPrefixWith | Indicates the object key prefix used in the redirection request. For example:
Type: String Ancestor: Redirect Condition: Not required if one of the siblings is present. Can be present only if ReplaceKeyWith is not provided. | Optional |
ReplaceKeyWith | Indicates the object key used in the redirection request. For example, redirect requests to error.html. Type: String Ancestor: Redirect Condition: Not required if one of the siblings is present. Can be present only if ReplaceKeyPrefixWithis not provided. | Optional |
HttpRedirectCode | Indicates the HTTP status code returned after the redirection request. Type: String Ancestor: Redirect Condition: Not required if one of the siblings is present. | Optional |
Response Syntax¶
HTTP/1.1 status_code
Server: Server Name
x-amz-request-id: request id
x-amz-id-2: id
x-reserved: amazon, aws and amazon web services are trademarks or registered trademarks of Amazon Technologies, Inc
Date: date
Content-Length: length
Response Headers¶
This response uses common headers. For details about common response headers, see section Common Response Headers.
Response Elements¶
This response involves no elements.
Error Responses¶
No special error responses are returned. For details about error responses, see Table 1.
Example 1: Setting Website to Redirect All Requests¶
PUT /?website HTTP/1.1
User-Agent: curl/7.29.0
Host: bucketname.obs.example.com
Accept: */*
Date: Sat, 04 Jan 2014 06:22:20 +0000
Authorization: AWS C6630CD15B645CB8A3BA:NiQpK7VHqCx93B8k14LJMSZy8ng=
Content-Length: 198
Expect: 100-continue
<WebsiteConfiguration>
<RedirectAllRequestsTo>
<HostName>www.example.com</HostName>
</RedirectAllRequestsTo>
</WebsiteConfiguration>
Example 2: Setting Website to Add Routing Rules that Redirect Requests¶
PUT /?website HTTP/1.1
User-Agent: curl/7.29.0
Host: bucketname.obs.example.com
Accept: */*
Date: Sat, 04 Jan 2014 06:22:20 +0000
Authorization: AWS C6630CD15B645CB8A3BA:NiQpK7VHqCx93B8k14LJMSZy8ng=
Content-Length: 490
Expect: 100-continue
<WebsiteConfiguration>
<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>
Sample Response¶
HTTP/1.1 200 OK
Date: Sat, 04 Jan 2014 06:24:31 GMT
Server: OBS
x-amz-request-id: 90E2BA0A420C00000140ED7A369007A2
x-amz-id-2: t35S98JCFKUMswCPZCk+UTi/VOoiSenzi5J6wnoKCIMfXUsKYGgU5+daiWAYiY/8
x-reserved: amazon, aws and amazon web services are trademarks or registered trademarks of Amazon Technologies, Inc
Content-Type: text/xml
Content-Length: 0