Object Storage Service:Como configurar o comportamento de visualização no navegador para objetos do OSS?

curl -I "<your object URL>"

Cenário 1: Download forçado devido a uma política de segurança do OSS

Este cenário ocorre quando o cabeçalho de resposta contém x-oss-force-download: true.

• Causa: O OSS adiciona os cabeçalhos x-oss-force-download: true e Content-Disposition: attachment para impedir que certos tipos de arquivo (como HTML) sejam executados nos navegadores. Essa política se aplica ao acessar objetos por meio de um nome de domínio padrão do OSS ou de um endpoint de aceleração em buckets criados após uma data específica.

  Para obter mais informações sobre as políticas, consulte Apêndice: Referência rápida para regras de download forçado do OSS ao final deste tópico.

• Solução: Use um nome de domínio personalizado para acessar recursos do OSS

• Procedimento:

  1. Mapeie um domínio personalizado: Faça login no console do OSS. Na página Domain Names do bucket, mapeie seu nome de domínio personalizado que possua registro ICP.

  2. Configure um registro CNAME: No provedor do seu domínio, como o Alibaba Cloud DNS, adicione um registro CNAME que aponte seu nome de domínio personalizado para o endereço CNAME fornecido pelo OSS.

  3. Acesse o objeto com o novo domínio: Acesse o objeto pela URL do seu domínio personalizado. O objeto agora será visualizado diretamente.

Cenário 2: Download forçado devido às configurações de metadados do objeto

Esse caso acontece quando o cabeçalho de resposta contém Content-Disposition: attachment, mas não apresenta x-oss-force-download.

• Causa: O metadado Content-Disposition do objeto está definido como attachment, o que força o navegador a baixar o arquivo em vez de exibi-lo. Se essa configuração não for removida após uso temporário, todas as solicitações subsequentes acionarão um download.

• Solução: Altere o metadado Content-Disposition do objeto para inline

  • Modificação via console

    1. Faça login no OSS console e acesse a página Objects na seção Object Management do bucket de destino.

    2. Localize o objeto desejado. Clique em ┇ na coluna Actions e selecione Set Object Metadata.

    3. Na caixa de diálogo exibida, localize o campo Content-Disposition e altere seu valor para inline.

    4. Clique em OK para salve as configurações.

  • Modificação em lote usando ossutil

    # Set the Content-Disposition of a specific object to inline.
    ossutil set-props oss://your-bucket/your-object.pdf --content-disposition inline --metadata-directive update

Cenário 3: O navegador não consegue visualizar o objeto devido a um Content-Type incorreto

Esta situação ocorre quando o cabeçalho de resposta está normal, mas o navegador ainda assim baixa o objeto.

• Causa: O Content-Type (tipo MIME) do objeto está ausente ou incorreto. Por exemplo, uma imagem JPG com Content-Type definido como application/octet-stream será baixada porque o navegador não consegue identificar o tipo de arquivo.

• Solução: Defina o Content-Type correto para o objeto

  • Modificação via console

    1. Faça login no OSS console e acesse a página Objects na seção Object Management do bucket de destino.

    2. Localize o objeto desejado. Clique em ┇ na coluna Actions e selecione Set Object Metadata.

    3. Na caixa de diálogo exibida, localize o campo Content-Type e altere-o para o valor correto.

    4. Clique em OK para salve as configurações.

    Exemplos de Content-Type correto para tipos comuns de arquivo:

    • Imagens: image/jpeg, image/png, image/gif, image/webp

    • Vídeos: video/mp4

    • Documentos PDF: application/pdf

    • Arquivos HTML: text/html

    • Texto simples: text/plain

  • Modificação em lote usando ossutil

    # Set the Content-Type of a specific object to image/jpeg.
    ossutil set-props oss://your-bucket/your-object.jpg --content-type image/jpeg --metadata-directive update

  • Modificação usando o SDK CopyObject**

    Ao usar CopyObject para copiar um objeto, a diretiva de metadados COPY é utilizada por padrão. Essa diretiva copia os metadados do objeto de source para o objeto de destino exatamente como estão e não infere nem atualize automaticamente o Content-Type com base na extensão do nome do arquivo de destino. Nesse caso, se você especifique apenas o Content-Type na solicitação sem defina o x-oss-metadata-directive como REPLACE, a configuração não terá efeito e o objeto de destino manterá o Content-Type do objeto de source.

    Valores válidos para x-oss-metadata-directive:

    • COPY (padrão): copia os metadados do objeto de source e ignora metadados como Content-Type especificados na solicitação.

    • REPLACE: substitui os metadados do objeto de source pelos metadados especificados na solicitação.

    Ao chamar CopyObject, especifique tanto o Content-Type quanto o x-oss-metadata-directive: REPLACE para atualize o Content-Type do objeto de destino para o valor especificado. O código de exemplo a seguir utiliza o SDK para Python:

    import oss2
    
    # Initialize the bucket.
    auth = oss2.Auth('<your-access-key-id>', '<your-access-key-secret>')
    bucket = oss2.Bucket(auth, '<your-endpoint>', '<your-bucket-name>')
    
    # Set Content-Type and set the metadata directive to REPLACE when you copy an object.
    headers = {
        "Content-Type": "image/jpeg",
        "x-oss-metadata-directive": "REPLACE"
    }
    bucket.copy_object('<source-bucket-name>', 'source-object.png', 'target-object.jpg', headers=headers)

    Alternativamente, use o método update_object_meta para atualize diretamente o Content-Type de um objeto existente ou especifique o Content-Type ao fazer upload de um objeto usando put_object.

Cenário 4: Falha na visualização porque uma política de bucket impõe HTTPS

Esse cenário ocorre quando uma solicitação via HTTP retorna o erro 403 AccessDenied com a mensagem Access denied by bucket policy.. O objeto não é visualizado nem baixado, sendo retornado normalmente apenas quando solicitado via HTTPS.

• Causa: A política do bucket contém a condição acs:SecureTransport, que nega solicitações não enviadas via HTTPS. Uma solicitação HTTP para a URL do objeto é rejeitada pela política do bucket antes que o objeto seja retornado, impedindo a visualização no navegador. Solicitações que usam um nome de domínio personalizado estão sujeitas à mesma política de bucket que as solicitações feitas pelo nome de domínio padrão do OSS.

• Confirme a causa:

  1. Faça login no OSS console. Clique em bucket de destino. No painel de navegação à esquerda, clique em Access Control > Bucket Policy

  2. Verifique se a lista de políticas contém alguma política cuja Condition limite o método de acesso a HTTP e cujo Effect seja Deny.

  3. Como alternativa, consulte a política do bucket pela linha de comando:

     aliyun ossutil api get-bucket-policy --bucket <bucket-name>

• Solução 1 (Recomendada): Acesse o objeto via HTTPS. Substitua http:// por https:// na URL do objeto e solicite-o novamente. Assim, o objeto será visualizado no navegador e o bucket continuará a negar solicitações HTTP.

• Solução 2: Modifique a política do bucket. Se o seu negócio exigir acesso HTTP, no painel de navegação à esquerda, clique em Access Control > Bucket Policy e remova ou modifique a política que contém a condição acs:SecureTransport. Permitir solicitações HTTP significa que os dados serão transmitidos em texto simples, o que reduz a segurança da transmissão. Avalie o impacto antes de alterar a política.

Alterações nos metadados não surtem efeito: Verifique o cache da CDN

Se você utilizar a CDN para acelerar o acesso ao OSS, alterações de metadados como Content-Type ou Content-Disposition podem não ter efeito imediato porque os nós da CDN ainda servem a versão em cache.

Solução: Limpe o cache da CDN para a URL do arquivo modificado no console da CDN. Atualizar e pré-carregar recursos.

Como forçar o download de um objeto em vez de visualizá-lo?

Para sempre forçar o download quando usuários acessarem um arquivo, utilize um dos métodos a seguir.

• Método 1 (Recomendado): Configure no OSS. Defina o metadado Content-Disposition do arquivo como attachment, conforme descrito em Cenário 2. Ideal para configurações permanentes e individuais por arquivo.

• Método 2: Configure na CDN. Adicione Content-Disposition: attachment como cabeçalho de resposta de saída em Cache no console da CDN. Isso evita a modificação do arquivo de source e permite configuração em lote por caminho ou tipo de arquivo.

O navegador não suporta o formato de arquivo para visualização

Navegadores não conseguem visualizar certos formatos profissionais, como .psd, .ai e .sketch. Esses arquivos são baixados independentemente das configurações do OSS e da CDN.

Solução: Instale uma extensão de navegador compatível com o formato ou utilize um service de visualização de documentos, como Visualização online do WebOffice.

Nomes de domínio padrão do OSS

Endpoints de aceleração