PutBucketWebsite - Configure static website hosting and redirection rules for OSS buckets - Object Storage Service

La operación PutBucketWebsite configura un bucket para el hosting de sitios web estáticos y establece las reglas de redirección (RoutingRule).

Notas de uso

Los sitios web estáticos se componen de contenido estático, incluidos scripts del lado del cliente como JavaScript. OSS no admite procesamiento del lado del servidor, como PHP, JSP o ASP.NET.

PutBucketWebsite requiere el permiso oss:PutBucketWebsite. Grant a custom access policy to a RAM user.
Funciones

Configura la página principal predeterminada, la página 404 predeterminada y las reglas de redirección (RoutingRule). Las reglas de redirección admiten redireccionamientos 3xx y retorno al origen basado en espejo.
Acceso a sitios web estáticos mediante nombres de dominio personalizados

Para acceder a un sitio web estático con un nombre de dominio personalizado, agregue un registro CNAME. Bind a custom domain name.
Páginas de índice y de error

Especifique una página de índice y una página de error. Ambas deben ser objetos dentro del bucket.
Acceso anónimo al dominio raíz

Una vez configurado el hosting de sitios web estáticos, OSS devuelve la página de índice para las solicitudes anónimas al dominio raíz. Las solicitudes firmadas al dominio raíz devuelven el resultado de la operación GetBucket (ListObjects).

Sintaxis de la solicitud

PUT /?website HTTP/1.1
Date: GMT Date
Content-Length: ContentLength
Content-Type: application/xml
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Authorization: SignatureValue

<?xml version="1.0" encoding="UTF-8"?>
<WebsiteConfiguration>
    <IndexDocument>
        <Suffix>index.html</Suffix>
    </IndexDocument>
    <ErrorDocument>
        <Key>errorDocument.html</Key>
        <HttpStatus>404</HttpStatus>
    </ErrorDocument>
</WebsiteConfiguration>

Encabezados de solicitud

DescribeRegions utiliza únicamente encabezados de solicitud comunes. Para obtener más información, consulte Common request headers.

Parámetros de solicitud

Contenido de WebsiteConfiguration

Nombre

Tipo

Obligatorio

Descripción

WebsiteConfiguration

Contenedor

Sí

El nodo raíz.

Nodo padre: Ninguna

Contenido de IndexDocument

Nombre	Tipo	Obligatorio	Descripción
IndexDocument	Contenedor	Condicional Debe especificar como mínimo uno de los siguientes contenedores: IndexDocument, ErrorDocument y RoutingRules.	El contenedor de la página principal predeterminada. Nodo padre: WebsiteConfiguration
Suffix	Cadena	Condicional Este parámetro es obligatorio si especifica el nodo padre IndexDocument.	La página principal predeterminada. OSS devuelve esta página para las solicitudes a URL que terminan con una barra diagonal (/). Nodo padre: IndexDocument
SupportSubDir	Cadena	No	Indica si se deben redirigir las solicitudes de un subdirectorio a la página de índice de dicho subdirectorio. Valores válidos: true: Redirige las solicitudes a la página de índice del subdirectorio. false (predeterminado): No redirige las solicitudes a la página de índice del subdirectorio. En su lugar, las solicitudes se redirigen a la página de índice del directorio raíz. Por ejemplo, si la página principal predeterminada es index.html y se envía una solicitud a `bucket.oss-cn-hangzhou.aliyuncs.com/subdir/`. Si establece SupportSubDir en false, la solicitud se redirige a `bucket.oss-cn-hangzhou.aliyuncs.com/index.html`. Si establece SupportSubDir en true, la solicitud se redirige a `bucket.oss-cn-hangzhou.aliyuncs.com/subdir/index.html`. Nodo padre: IndexDocument
Type	Enumeración	No	La acción a ejecutar cuando se configura la página principal predeterminada, el nombre del objeto accedido no termina con una barra diagonal (/) y el objeto no existe. Esta acción solo surte efecto cuando SupportSubDir se establece en true y se aplica después de RoutingRule y antes de ErrorFile. Por ejemplo, si la página principal predeterminada es index.html, se envía una solicitud para la ruta de archivo `bucket.oss-cn-hangzhou.aliyuncs.com/abc` y el objeto abc no existe. Las acciones para los diferentes valores de Type son las siguientes: 0 (predeterminado): Comprueba si existe abc/index.html. La ruta tiene el formato `Object + / + Homepage`. Si el objeto existe, OSS devuelve una redirección 302 a la ruta codificada en URL `/abc/`. La ruta tiene el formato `/ + Object + /`. Si el objeto no existe, OSS devuelve un error 404 y luego busca una página de error. 1: Devuelve un error 404 con el código de error NoSuchKey y luego busca una página de error. 2: Comprueba si existe abc/index.html. Si el objeto existe, se devuelve su contenido. Si el objeto no existe, OSS devuelve un error 404 y luego busca una página de error. Nodo padre: IndexDocument

Contenido del documento de error

Nombre	Tipo	Obligatorio	Descripción
ErrorDocument	Contenedor	Condicional Debe especificar como mínimo uno de los siguientes contenedores: IndexDocument, ErrorDocument y RoutingRules.	El contenedor de la página de error 404. Nodo padre: WebsiteConfiguration
Key	Cadena	Condicional Este parámetro es obligatorio si especifica el nodo padre ErrorDocument.	La página de error. Se devuelve cuando el objeto solicitado no existe. Nodo padre: ErrorDocument
HttpStatus	Cadena	No	El código de estado HTTP que se devuelve junto con la página de error. Valores válidos: 200, 404 (predeterminado) Nodo padre: ErrorDocument

RoutingRules|RoutingRule|RuleNumber

Nombre	Tipo	Obligatorio	Descripción
RoutingRules	Contenedor	Condicional Debe especificar como mínimo uno de los siguientes contenedores: IndexDocument, ErrorDocument y RoutingRules.	El contenedor de las reglas de redirección. Nodo padre: WebsiteConfiguration
RoutingRule	Contenedor	No	Una regla de redirección o una regla de retorno al origen basada en espejo. Máximo: 20 reglas. Nodo padre: RoutingRules
RuleNumber	Entero positivo	Condicional Este parámetro es obligatorio si especifica el nodo padre RoutingRule.	El número de secuencia. OSS evalúa las reglas en orden ascendente y se detiene en la primera coincidencia. Nodo padre: RoutingRule

Contenido de Condition en RoutingRule

Nombre	Tipo	Obligatorio	Descripción
Condition	Contenedor	Condicional Este parámetro es obligatorio si especifica el nodo padre RoutingRule.	Las condiciones de coincidencia. Deben cumplirse todas las condiciones para que se ejecute la regla. Nodo padre: RoutingRule
KeyPrefixEquals	Cadena	No	La clave del objeto debe tener este prefijo para que se aplique la regla. Nodo padre: Condition
HttpErrorCodeReturnedEquals	Código de estado HTTP	No	El código de estado HTTP devuelto para el objeto solicitado que activa esta regla. Para el retorno al origen basado en espejo, establézcalo en 404. Nodo padre: Condition
IncludeHeader	Contenedor	No	La solicitud debe incluir el encabezado y el valor especificados para que se aplique la regla. Puede especificar hasta 10 encabezados. Nodo padre: Condition
Key	Cadena	Sí	Esta regla se aplica solo si la solicitud contiene el encabezado especificado y su valor coincide exactamente con el valor definido en Equals. Nodo padre: IncludeHeader
Equals	Cadena	No	El valor del encabezado de la solicitud. La regla se aplica solo si la solicitud incluye el encabezado especificado por Key y su valor coincide con este valor. Nodo padre: IncludeHeader
KeySuffixEquals	Cadena	No	La clave del objeto debe tener este sufijo para que se aplique la regla. El valor predeterminado está vacío, lo que significa que no se coincide con ningún sufijo. Nodo padre: Condition

Configuración de redirección

Nombre	Tipo	Obligatorio	Descripción
Redirect	Contenedor	Condicional Este parámetro es obligatorio si especifica el nodo padre RoutingRule.	La acción a ejecutar cuando se cumple la regla. Nodo padre: RoutingRule
RedirectType	Cadena	Condicional Este parámetro es obligatorio si especifica el nodo padre Redirect.	El tipo de redirección. Valores válidos: Mirror: Retorno al origen basado en espejo. External: Redirección externa. OSS devuelve una redirección 3xx a otra dirección. AliCDN: Redirección de Alibaba Cloud CDN. Este tipo se utiliza para Alibaba Cloud CDN. A diferencia de una redirección externa, OSS agrega un encabezado adicional a la solicitud. Cuando Alibaba Cloud CDN detecta este encabezado, redirige la solicitud a la dirección especificada y devuelve los datos recuperados al usuario, en lugar de devolverle una solicitud de redirección 3xx. Nodo padre: Redirect
PassQueryString	Booleano	No	Indica si se debe incluir la cadena de consulta de la solicitud original en la solicitud de redirección o de retorno al origen. Por ejemplo, un usuario envía una solicitud con la cadena de consulta `?a=b&c=d`. Si establece PassQueryString en true y la regla especifica una redirección 302, el encabezado Location en la respuesta incluye la cadena de consulta, como `Location:example.com?a=b&c=d`. Si la regla especifica un retorno al origen basado en espejo, la solicitud de retorno al origen también incluye la cadena de consulta. Valores válidos: true, false (predeterminado) Nodo padre: Redirect
MirrorURL	Cadena	Condicional Este parámetro es obligatorio si RedirectType se establece en Mirror.	La dirección del servidor de origen para el retorno al origen basado en espejo. Solo surte efecto cuando RedirectType es Mirror. La dirección debe comenzar con http:// o https:// y terminar con una barra diagonal (/). OSS anexa el nombre del objeto a esta dirección para crear la URL de retorno al origen. Por ejemplo, si el objeto solicitado es myobject y establece este parámetro en `http://example.com/`, la URL de retorno al origen es `http://example.com/myobject`. Si establece este parámetro en `http://example.com/dir1/`, la URL de retorno al origen es `http://example.com/dir1/myobject`. Nodo padre: Redirect
MirrorPassQueryString	Booleano	No	Igual que PassQueryString pero con mayor prioridad. Solo surte efecto cuando RedirectType es Mirror. Valor predeterminado: false Nodo padre: Redirect
MirrorFollowRedirect	Booleano	No	Indica si se deben seguir las redirecciones 3xx del servidor de origen. Solo surte efecto cuando RedirectType es Mirror. Por ejemplo, el servidor de origen devuelve una redirección 302 con un encabezado Location. Si establece este parámetro en true, OSS envía una nueva solicitud a la dirección especificada en el encabezado Location. Se sigue un máximo de 10 redirecciones. Si el número de redirecciones supera 10, la solicitud de retorno al origen falla. Si establece este parámetro en false, OSS devuelve la redirección 302 y pasa el encabezado Location al cliente. Valor predeterminado: true Nodo padre: Redirect
MirrorCheckMd5	Booleano	No	Indica si se debe verificar el hash MD5 del cuerpo de respuesta del servidor de origen. Solo surte efecto cuando RedirectType es Mirror. Cuando MirrorCheckMd5 es true y la respuesta de origen incluye un encabezado Content-Md5, OSS verifica los datos obtenidos con respecto al valor del encabezado. Los datos que no coincidan no se guardan. Valor predeterminado: false Nodo padre: Redirect
MirrorHeaders	Contenedor	No	Encabezados que se incluirán en la solicitud de retorno al origen. Solo surte efecto cuando RedirectType es Mirror. Nodo padre: Redirect
PassAll	Booleano	No	Indica si se deben pasar todos los encabezados de solicitud al servidor de origen, excepto los siguientes. Solo surte efecto cuando RedirectType es Mirror. Encabezados como content-length, authorization2, authorization, range y date Encabezados que comienzan con oss-, x-oss- o x-drs- Valor predeterminado: false Nodo padre: MirrorHeaders
Pass	Cadena	No	Los encabezados específicos que se pasarán al servidor de origen. Solo surte efecto cuando RedirectType es Mirror. Cada encabezado puede tener una longitud máxima de 1,024 bytes y solo puede contener dígitos (0-9), letras (a-z, A-Z) y guiones (-). Puede especificar hasta 10 encabezados. Nodo padre: MirrorHeaders
Remove	Cadena	No	Los encabezados específicos cuyo paso al servidor de origen se prohibirá. Solo surte efecto cuando RedirectType es Mirror. Cada encabezado tiene una longitud máxima de 1024 bytes y utiliza el mismo conjunto de caracteres que Pass. Puede especificar hasta 10 encabezados. Este parámetro se usa normalmente junto con PassAll. Nodo padre: MirrorHeaders
Set	Contenedor	No	Establece un encabezado para incluir en la solicitud de retorno al origen, independientemente de si la solicitud original lo contenía. Solo surte efecto cuando RedirectType es Mirror. Puede asignar este contenedor a un máximo de 10 grupos. Nodo padre: MirrorHeaders
Key	Cadena	Condicional Este parámetro es obligatorio si especifica el nodo padre Set.	La clave del encabezado a establecer. La clave puede tener una longitud máxima de 1,024 bytes y solo puede contener dígitos (0-9), letras (a-z, A-Z) y guiones (-). Solo surte efecto cuando RedirectType es Mirror. Nodo padre: Set
Value	Cadena	Condicional Este parámetro es obligatorio si especifica el nodo padre Set.	El valor del encabezado a establecer. El valor puede tener una longitud máxima de 1,024 bytes y no puede contener `\r\n`. Solo surte efecto cuando RedirectType es Mirror. Nodo padre: Set
Protocol	Cadena	No	El protocolo a utilizar para la redirección. Solo surte efecto cuando RedirectType es External o AliCDN. Por ejemplo, si el objeto solicitado es test, establece el destino de redirección en `example.com` y configura Protocol en https, el encabezado Location será `https://example.com/test`. Valores válidos: http, https. Nodo padre: Redirect
HostName	Cadena	No	El nombre de dominio a utilizar para la redirección. El nombre de dominio debe ser válido. Por ejemplo, si el objeto solicitado es test, configura Protocol en https y establece HostName en `example.com`, el encabezado Location será `https://example.com/test`. Nodo padre: Redirect
ReplaceKeyPrefixWith	Cadena	No	La cadena con la que se reemplazará el prefijo de la clave del objeto durante la redirección. Si el prefijo está vacío, esta cadena se inserta al principio de la clave del objeto. Nota Puede especificar ReplaceKeyWith o ReplaceKeyPrefixWith, pero no ambos. Por ejemplo, si el objeto solicitado es abc/test.txt, establece KeyPrefixEquals en abc/ y configura ReplaceKeyPrefixWith en def/, el encabezado Location será `http://example.com/def/test.txt`. Nodo padre: Redirect
EnableReplacePrefix	Booleano	No	Si este parámetro se establece en true, el prefijo del objeto se reemplaza con el valor de ReplaceKeyPrefixWith. Si este parámetro no se especifica o está vacío, el prefijo del objeto se trunca. Nota No puede establecer este parámetro en true si el parámetro ReplaceKeyWith no está vacío. Valor predeterminado: false Nodo padre: Redirect
ReplaceKeyWith	Cadena	No	Reemplaza toda la clave del objeto durante la redirección. Utilice la variable ${key} para hacer referencia a la clave original del objeto. Por ejemplo, si el objeto solicitado es test y establece ReplaceKeyWith en `prefix/${key}.suffix`, el encabezado Location será `http://example.com/prefix/test.suffix`. Nodo padre: Redirect
HttpRedirectCode	Código de estado HTTP	No	El código de estado HTTP a devolver para la redirección. Solo surte efecto cuando RedirectType es External o AliCDN. Valores válidos: 301 (predeterminado), 302, 307. Nodo padre: Redirect

Encabezados de respuesta

La respuesta contiene únicamente encabezados de respuesta comunes. Para obtener más información, consulte Common response headers.

Ejemplos

Ejemplo de solicitud

PUT /?website HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Length: 209
Date: Thu, 17 Apr 2025 03:21:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

<?xml version="1.0" encoding="UTF-8"?>
<WebsiteConfiguration>
  <IndexDocument>
    <Suffix>index.html</Suffix>
      <SupportSubDir>true</SupportSubDir>
      <Type>0</Type>
  </IndexDocument>
  <ErrorDocument>
    <Key>error.html</Key>
    <HttpStatus>404</HttpStatus>
  </ErrorDocument>
</WebsiteConfiguration>

Ejemplo de respuesta

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906008B
Date: Fri, 04 May 2012 03:21:12 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS

Ejemplo completo

PUT /?website HTTP/1.1
Date: Thu, 17 Apr 2025 09:03:18 GMT
Content-Length: 2064
Host: test.oss-cn-hangzhou-internal.aliyuncs.com
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
User-Agent: aliyun-sdk-python-test/0.4.0

<WebsiteConfiguration>
  <IndexDocument>
    <Suffix>index.html</Suffix>
    <SupportSubDir>true</SupportSubDir>
    <Type>0</Type>
  </IndexDocument>
  <ErrorDocument>
    <Key>error.html</Key>
    <HttpStatus>404</HttpStatus>
  </ErrorDocument>
  <RoutingRules>
    <RoutingRule>
      <RuleNumber>1</RuleNumber>
      <Condition>
        <KeyPrefixEquals>abc/</KeyPrefixEquals>
        <HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals>
      </Condition>
      <Redirect>
        <RedirectType>Mirror</RedirectType>
        <PassQueryString>true</PassQueryString>
        <MirrorURL>http://example.com/</MirrorURL>   
        <MirrorPassQueryString>true</MirrorPassQueryString>
        <MirrorFollowRedirect>true</MirrorFollowRedirect>
        <MirrorCheckMd5>false</MirrorCheckMd5>
        <MirrorHeaders>
          <PassAll>true</PassAll>
          <Pass>myheader-key1</Pass>
          <Pass>myheader-key2</Pass>
          <Remove>myheader-key3</Remove>
          <Remove>myheader-key4</Remove>
          <Set>
            <Key>myheader-key5</Key>
            <Value>myheader-value5</Value>
          </Set>
        </MirrorHeaders>
      </Redirect>
    </RoutingRule>
    <RoutingRule>
      <RuleNumber>2</RuleNumber>
      <Condition>
        <KeyPrefixEquals>abc/</KeyPrefixEquals>
        <HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals>
        <IncludeHeader>
          <Key>host</Key>
          <Equals>test.oss-cn-beijing-internal.aliyuncs.com</Equals>
        </IncludeHeader>
      </Condition>
      <Redirect>
        <RedirectType>AliCDN</RedirectType>
        <Protocol>http</Protocol>
        <HostName>example.com</HostName>
        <PassQueryString>false</PassQueryString>
        <ReplaceKeyWith>prefix/${key}.suffix</ReplaceKeyWith>
        <HttpRedirectCode>301</HttpRedirectCode>
      </Redirect>
    </RoutingRule>
    <RoutingRule>
      <Condition>
        <HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals>
      </Condition>
      <RuleNumber>3</RuleNumber>
      <Redirect>
        <ReplaceKeyWith>prefix/${key}</ReplaceKeyWith>
        <HttpRedirectCode>302</HttpRedirectCode>
        <EnableReplacePrefix>false</EnableReplacePrefix>
        <PassQueryString>false</PassQueryString>
        <Protocol>http</Protocol>
        <HostName>example.com</HostName>
        <RedirectType>External</RedirectType>
      </Redirect>
    </RoutingRule>
  </RoutingRules>
</WebsiteConfiguration>

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Fri, 27 Jul 2018 09:03:18 GMT
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 5B5ADFD6ED3CC49176CBE29D
x-oss-server-time: 47

SDK

CLI (ossutil)

Comando de ossutil: put-bucket-website.

Códigos de error

Código de error	Código de estado HTTP	Descripción
InvalidDigest	400	El valor del encabezado Content-MD5 no coincide con el hash MD5 que OSS calculó para el cuerpo de la solicitud.