Object Storage Service:PutBucketWebsite

Observações de uso

Sites estáticos consistem em conteúdo estático, incluindo scripts do lado do cliente, como JavaScript. O OSS não oferece suporte a processamento no lado do servidor, como PHP, JSP ou ASP.NET.

• O PutBucketWebsite exige a permissão oss:PutBucketWebsite. Conceder uma política de acesso personalizada a um usuário RAM.

• Recursos

  Configura a página inicial padrão, a página 404 padrão e as regras de redirecionamento (RoutingRule). As regras de redirecionamento aceitam redirecionamentos 3xx e back-to-origin baseado em espelhamento.

• Acesso a sites estáticos com nomes de domínio personalizados

  Para acessar um site estático usando um nome de domínio personalizado, adicione um registro CNAME. Vincular um nome de domínio personalizado.

• Páginas de índice e de erro

  Especifique uma página de índice e uma página de erro. Ambas devem ser objetos no bucket.

• Acesso anônimo ao domínio raiz

  Após configurar a hospedagem de site estático, o OSS retorna a página de índice para solicitações anônimas ao domínio raiz. Solicitações assinadas ao domínio raiz retornam o resultado da operação GetBucket (ListObjects).

Sintaxe da solicitação

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>

Cabeçalhos da solicitação

O PutBucketWebsite utiliza apenas cabeçalhos de solicitação comuns. Para mais informações, consulte Cabeçalhos de solicitação comuns.

Parâmetros da solicitação

• Conteúdo de WebsiteConfiguration

  Nome	Tipo	Obrigatório	Descrição
  WebsiteConfiguration	Container	Sim	Nó raiz. Nó pai: Nenhum

• Conteúdo de IndexDocument

  Nome	Tipo	Obrigatório	Descrição
  IndexDocument	Container	Condicional Especifique pelo menos um dos seguintes containers: IndexDocument, ErrorDocument ou RoutingRules.	Container da página inicial padrão. Nó pai: WebsiteConfiguration
  Suffix	String	Condicional Parâmetro obrigatório se o nó pai IndexDocument for especificado.	Página inicial padrão. O OSS retorna esta página para solicitações a URLs que terminam com barra (/). Nó pai: IndexDocument
  SupportSubDir	String	Não	Indica se as solicitações para um subdiretório devem ser redirecionadas à página de índice desse subdiretório. Valores válidos: true: Redireciona solicitações à página de índice no subdiretório. false (padrão): Não redireciona solicitações à página de índice no subdiretório. Em vez disso, as solicitações são redirecionadas à página de índice no diretório raiz. Por exemplo, se a página inicial padrão for index.html e uma solicitação for enviada para bucket.oss-cn-hangzhou.aliyuncs.com/subdir/: ao definir SupportSubDir como false, a solicitação será redirecionada para bucket.oss-cn-hangzhou.aliyuncs.com/index.html; ao definir SupportSubDir como true, a solicitação será redirecionada para bucket.oss-cn-hangzhou.aliyuncs.com/subdir/index.html. Nó pai: IndexDocument
  Type	Enumeração	Não	Ação executada quando a página inicial padrão estiver definida, o nome do objeto acessado não terminar com barra (/) e o objeto não existir. Esta ação entra em vigor apenas quando SupportSubDir estiver definido como true e é aplicada após RoutingRule e antes de ErrorFile. Por exemplo, se a página inicial padrão for index.html, uma solicitação for enviada para o caminho de arquivo bucket.oss-cn-hangzhou.aliyuncs.com/abc e o objeto abc não existir, as ações para diferentes valores de Type serão: 0 (padrão): Verifica se abc/index.html existe. O caminho segue o formato Objeto + / + PáginaInicial. Se o objeto existir, o OSS retorna um redirecionamento 302 para o caminho codificado por URL /abc/. O caminho segue o formato / + Objeto + /. Se o objeto não existir, o OSS retorna um erro 404 e verifica se há uma página de erro. 1: Retorna um erro 404 com o código NoSuchKey e verifica se há uma página de erro. 2: Verifica se abc/index.html existe. Se o objeto existir, seu conteúdo é retornado. Caso contrário, o OSS retorna um erro 404 e verifica se há uma página de erro. Nó pai: IndexDocument

• Conteúdo do documento de erro

  Nome	Tipo	Obrigatório	Descrição
  ErrorDocument	Container	Condicional Especifique pelo menos um dos seguintes containers: IndexDocument, ErrorDocument ou RoutingRules.	Container da página de erro 404. Nó pai: WebsiteConfiguration
  Key	String	Condicional Parâmetro obrigatório se o nó pai ErrorDocument for especificado.	Página de erro. Retornada quando um objeto solicitado não existe. Nó pai: ErrorDocument
  HttpStatus	String	Não	Código de status HTTP retornado com a página de erro. Valores válidos: 200, 404 (padrão) Nó pai: ErrorDocument

• RoutingRules|RoutingRule|RuleNumber

  Nome	Tipo	Obrigatório	Descrição
  RoutingRules	Container	Condicional Especifique pelo menos um dos seguintes containers: IndexDocument, ErrorDocument ou RoutingRules.	Container das regras de redirecionamento. Nó pai: WebsiteConfiguration
  RoutingRule	Container	Não	Regra de redirecionamento ou regra de back-to-origin baseada em espelhamento. Máximo: 20 regras. Nó pai: RoutingRules
  RuleNumber	Inteiro positivo	Condicional Parâmetro obrigatório se o nó pai RoutingRule for especificado.	Número de sequência. O OSS corresponde às regras em ordem crescente e para na primeira correspondência. Nó pai: RoutingRule

• Conteúdo de Condition em RoutingRule

  Nome	Tipo	Obrigatório	Descrição
  Condition	Container	Condicional Parâmetro obrigatório se o nó pai RoutingRule for especificado.	Condições de correspondência. Todas as condições devem ser atendidas para executar a regra. Nó pai: RoutingRule
  KeyPrefixEquals	String	Não	Prefixo obrigatório na chave do objeto para aplicar a regra. Nó pai: Condition
  HttpErrorCodeReturnedEquals	Código de status HTTP	Não	Código de status HTTP retornado para o objeto solicitado que aciona esta regra. Para back-to-origin baseado em espelhamento, defina como 404. Nó pai: Condition
  IncludeHeader	Container	Não	A solicitação deve incluir o cabeçalho e o valor especificados para aplicar a regra. É possível especificar até 10 cabeçalhos. Nó pai: Condition
  Key	String	Sim	Esta regra se aplica apenas se a solicitação contiver o cabeçalho especificado e seu valor corresponder exatamente ao valor definido para Equals. Nó pai: IncludeHeader
  Equals	String	Não	Valor do cabeçalho da solicitação. A regra se aplica apenas se a solicitação incluir o cabeçalho especificado por Key e seu valor corresponder a este valor. Nó pai: IncludeHeader
  KeySuffixEquals	String	Não	Sufixo obrigatório na chave do objeto para aplicar a regra. O valor padrão é vazio, o que significa que nenhum sufixo é correspondido. Nó pai: Condition

• Configuração de redirecionamento

  Nome	Tipo	Obrigatório	Descrição
  Redirect	Container	Condicional Parâmetro obrigatório se o nó pai RoutingRule for especificado.	Ação executada quando a regra for correspondida. Nó pai: RoutingRule
  RedirectType	String	Condicional Parâmetro obrigatório se o nó pai Redirect for especificado.	Tipo de redirecionamento. Valores válidos: Mirror: back-to-origin baseado em espelhamento. External: redirecionamento externo. O OSS retorna um redirecionamento 3xx para outro endereço. AliCDN: redirecionamento do Alibaba Cloud CDN. Usado para o Alibaba Cloud CDN. Diferente de um redirecionamento externo, o OSS adiciona um cabeçalho extra à solicitação. Quando o Alibaba Cloud CDN detecta esse cabeçalho, ele redireciona a solicitação para o endereço especificado e retorna os dados recuperados ao usuário, em vez de retornar uma solicitação de redirecionamento 3xx. Nó pai: Redirect
  PassQueryString	Booleano	Não	Indica se a string de consulta da solicitação original deve ser incluída no redirecionamento ou na solicitação de back-to-origin. Por exemplo, se um usuário enviar uma solicitação com a string de consulta ?a=b&c=d, definir PassQueryString como true e a regra especificar um redirecionamento 302, o cabeçalho Location na resposta incluirá a string de consulta, como Location:example.com?a=b&c=d. Se a regra especificar back-to-origin baseado em espelhamento, a solicitação de back-to-origin também incluirá a string de consulta. Valores válidos: true, false (padrão) Nó pai: Redirect
  MirrorURL	String	Condicional Parâmetro obrigatório se RedirectType estiver definido como Mirror.	Endereço do servidor de origem para back-to-origin baseado em espelhamento. Entra em vigor apenas quando RedirectType é Mirror. O endereço deve começar com http:// ou https:// e terminar com barra (/). O OSS anexa o nome do objeto a este endereço para criar a URL de back-to-origin. Por exemplo, se o objeto solicitado for myobject e você definir este parâmetro como http://example.com/, a URL de back-to-origin será http://example.com/myobject. Se você definir este parâmetro como http://example.com/dir1/, a URL de back-to-origin será http://example.com/dir1/myobject. Nó pai: Redirect
  MirrorPassQueryString	Booleano	Não	Semelhante a PassQueryString, mas com prioridade maior. Entra em vigor apenas quando RedirectType é Mirror. Valor padrão: false Nó pai: Redirect
  MirrorFollowRedirect	Booleano	Não	Indica se os redirecionamentos 3xx do servidor de origem devem ser seguidos. Entra em vigor apenas quando RedirectType é Mirror. Por exemplo, o servidor de origem retorna um redirecionamento 302 com um cabeçalho Location. Se você definir este parâmetro como true, o OSS enviará uma nova solicitação para o endereço especificado no cabeçalho Location. No máximo 10 redirecionamentos são seguidos. Se o número de redirecionamentos exceder 10, a solicitação de back-to-origin falhará. Se você definir este parâmetro como false, o OSS retornará o redirecionamento 302 e passará o cabeçalho Location para o cliente. Valor padrão: true Nó pai: Redirect
  MirrorCheckMd5	Booleano	Não	Indica se o hash MD5 do corpo da resposta do servidor de origem deve ser verificado. Entra em vigor apenas quando RedirectType é Mirror. Quando MirrorCheckMd5 é true e a resposta de origem inclui um cabeçalho Content-Md5, o OSS verifica os dados obtidos em relação ao valor do cabeçalho. Dados incompatíveis não são salvos. Valor padrão: false Nó pai: Redirect
  MirrorHeaders	Container	Não	Cabeçalhos a serem incluídos na solicitação de back-to-origin. Entra em vigor apenas quando RedirectType é Mirror. Nó pai: Redirect
  PassAll	Booleano	Não	Indica se todos os cabeçalhos da solicitação devem ser passados para o servidor de origem, exceto os seguintes. Entra em vigor apenas quando RedirectType é Mirror. Cabeçalhos como content-length, authorization2, authorization, range e date Cabeçalhos que começam com oss-, x-oss- ou x-drs- Valor padrão: false Nó pai: MirrorHeaders
  Pass	String	Não	Cabeçalhos específicos a serem passados para o servidor de origem. Entra em vigor apenas quando RedirectType é Mirror. Cada cabeçalho pode ter até 1.024 bytes e conter apenas dígitos (0-9), letras (a-z, A-Z) e hifens (-). É possível especificar até 10 cabeçalhos. Nó pai: MirrorHeaders
  Remove	String	Não	Cabeçalhos específicos proibidos de serem passados para o servidor de origem. Entra em vigor apenas quando RedirectType é Mirror. Cada cabeçalho tem comprimento máximo de 1.024 bytes e usa o mesmo conjunto de caracteres que Pass. É possível especificar até 10 cabeçalhos. Este parâmetro é normalmente usado com PassAll. Nó pai: MirrorHeaders
  Set	Container	Não	Define um cabeçalho a ser incluído na solicitação de back-to-origin, independentemente de a solicitação original o conter. Entra em vigor apenas quando RedirectType é Mirror. Você pode atribuir este container a no máximo 10 grupos. Nó pai: MirrorHeaders
  Key	String	Condicional Parâmetro obrigatório se o nó pai Set for especificado.	Chave do cabeçalho a ser definida. A chave pode ter até 1.024 bytes e conter apenas dígitos (0-9), letras (a-z, A-Z) e hifens (-). Entra em vigor apenas quando RedirectType é Mirror. Nó pai: Set
  Value	String	Condicional Parâmetro obrigatório se o nó pai Set for especificado.	Valor do cabeçalho a ser definido. O valor pode ter até 1.024 bytes e não pode conter \r\n. Entra em vigor apenas quando RedirectType é Mirror. Nó pai: Set
  Protocol	String	Não	Protocolo usado para o redirecionamento. Entra em vigor apenas quando RedirectType é External ou AliCDN. Por exemplo, se o objeto solicitado for test, você definir o destino do redirecionamento como example.com e definir Protocol como https, o cabeçalho Location será https://example.com/test. Valores válidos: http, https. Nó pai: Redirect
  HostName	String	Não	Nome de domínio usado para o redirecionamento. O nome de domínio deve ser válido. Por exemplo, se o objeto solicitado for test, você definir Protocol como https e definir HostName como example.com, o cabeçalho Location será https://example.com/test. Nó pai: Redirect
  ReplaceKeyPrefixWith	String	Não	String usada para substituir o prefixo da chave do objeto durante o redirecionamento. Se o prefixo estiver vazio, esta string será inserida no início da chave do objeto. Nota Você pode especificar ReplaceKeyWith ou ReplaceKeyPrefixWith, mas não ambos. Por exemplo, se o objeto solicitado for abc/test.txt, você definir KeyPrefixEquals como abc/ e definir ReplaceKeyPrefixWith como def/, o cabeçalho Location será http://example.com/def/test.txt. Nó pai: Redirect
  EnableReplacePrefix	Booleano	Não	Se este parâmetro for definido como true, o prefixo do objeto será substituído pelo valor de ReplaceKeyPrefixWith. Se este parâmetro não for especificado ou estiver vazio, o prefixo do objeto será truncado. Nota Você não pode definir este parâmetro como true se o parâmetro ReplaceKeyWith não estiver vazio. Valor padrão: false Nó pai: Redirect
  ReplaceKeyWith	String	Não	Substitui toda a chave do objeto durante o redirecionamento. Use a variável ${key} para referenciar a chave original do objeto. Por exemplo, se o objeto solicitado for test e você definir ReplaceKeyWith como prefix/${key}.suffix, o cabeçalho Location será http://example.com/prefix/test.suffix. Nó pai: Redirect
  HttpRedirectCode	Código de status HTTP	Não	Código de status HTTP retornado para o redirecionamento. Entra em vigor apenas quando RedirectType é External ou AliCDN. Valores válidos: 301 (padrão), 302, 307. Nó pai: Redirect

Cabeçalhos da resposta

A resposta contém apenas cabeçalhos de resposta comuns. Para mais informações, consulte Cabeçalhos de resposta comuns.

Exemplos

• Exemplo de solicitação

  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>

• Exemplo de resposta

  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

• Exemplo 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

• Java

• Python

• Go V2

• C++

• PHP V2

• C

• .NET

• Node.js

CLI (ossutil)

Comando ossutil: put-bucket-website.

Códigos de erro