Object Storage Service:Customize the filename for downloading an OSS file

Regras de nomenclatura para objetos baixados

O nome de um objeto baixado segue as seguintes regras:

1. Parâmetro response-content-disposition: Se o download do objeto ocorrer por meio de uma URL assinada contendo o parâmetro response-content-disposition, o objeto baixado receberá o nome especificado por esse parâmetro, independentemente do valor do cabeçalho de metadados Content-Disposition.

2. Caso a URL pré-assinada não especifique o campo Content-Disposition, o sistema obterá o valor desse campo a partir dos metadados do arquivo.

3. Chave do objeto no OSS: Quando response-content-disposition e Content-Disposition não forem especificados, o objeto baixado manterá o mesmo nome da chave do objeto no OSS.

Especifique um nome para downloads específicos de um objeto usando uma URL assinada

Uma URL assinada concede acesso por tempo limitado a um objeto privado no OSS. Adicione o parâmetro response-content-disposition a uma URL assinada do objeto para especificar um nome diferente durante o download, sem precisar modificar o cabeçalho de metadados Content-Disposition do objeto.

Cenários

• Compartilhamento de objetos: Utilize uma URL assinada para compartilhar um objeto com outro usuário e especifique o nome exibido no momento do download. Assim, a chave original do seu objeto permanece oculta.

• Downloads personalizados: Empregue URLs assinadas para apresentar nomes personalizados dos objetos baixados a diferentes usuários. Por exemplo, personalize os nomes com base no nome de usuário ou no número do pedido.

• Testes e pré-visualizações: Permita que os usuários visualizem ou testem um arquivo sem alterar seu nome original ou o padrão de download.

Permissões

Para gerar uma URL assinada para o download de um objeto, é necessário ter a permissão oss:GetObject. Para mais informações, consulte Conceder políticas de acesso personalizadas a um usuário RAM.

Notas de uso

• Crie a URL assinada e especifique o parâmetro response-content-disposition. Esse parâmetro se aplica exclusivamente a essa URL.

• Certifique-se de especificar os nomes dos objetos com codificação URL para evitar erros causados por caracteres especiais.

• Toda URL assinada possui um período de validade e não pode ser utilizada após a expiração. Leve em conta esse período ao fornecer uma URL assinada aos usuários.

• Caso o cabeçalho de metadados Content-Disposition esteja especificado para um objeto e o download ocorra por meio de uma URL assinada contendo o parâmetro response-content-disposition, o sistema ignorará o cabeçalho Content-Disposition e utilizará o valor do parâmetro response-content-disposition como o nome do objeto baixado.

Código de exemplo

O código de exemplo a seguir, em Python, demonstra como especificar o parâmetro response-content-disposition durante a criação de uma URL assinada:

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from urllib.parse import quote

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())

# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', '<bucket_name>')

# Specify the full path of the object. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path. 
object_name = 'exampledir/exampleobject.txt'

# Create an object name that you want to display when the object is downloaded. You need to URL-encode the name. 
download_filename = quote('desired-filename.txt')

# Specify the name of the downloaded object. This name is the value of the Content-Disposition header in the response to the download request. 
params = {'response-content-disposition': f'attachment; filename="{download_filename}"'}

# Set the validity period of the signed URL to 3,600 seconds. 
# Set the slash_safe parameter to True to prevent OSS from identifying the forward slashes (/) in the full path of the object as escape characters. This lets you use the generated signed URL to download the object. 
url = bucket.sign_url('GET', object_name, 3600, params=params, slash_safe=True)

print ('Signed URL:', url)

Para ver códigos de exemplo em outras linguagens, consulte Compartilhar arquivos usando URLs de arquivo.

Defina nomes de arquivo para todos os downloads usando metadados do arquivo

O cabeçalho de metadados Content-Disposition especifica o nome padrão de um objeto durante o download. Caso deseje que um objeto tenha um novo nome em todas as solicitações de download, defina o cabeçalho de metadados Content-Disposition com o novo nome. O novo nome especificado pelo cabeçalho Content-Disposition se aplica a todas as solicitações de download que não contêm o parâmetro response-content-disposition.

Cenários

• Compartilhamento de dados a longo prazo: Quando a expectativa for baixar um objeto várias vezes com o mesmo nome, modifique o cabeçalho de metadados para atingir esse objetivo.

• Arquivamento: Em cenários de bibliotecas de documentos públicos ou centros de recursos, pode ser necessário que todos os documentos ou recursos possuam nomes fixos e descritivos, facilitando a identificação e o arquivamento.

• Atualizações regulares: Para que os usuários baixem a versão mais recente de documentações ou softwares atualizados frequentemente, usando a mesma URL e com um nome consistente, defina o cabeçalho de metadados da documentação ou do software no OSS.

Permissões

Para modificar os metadados do objeto, é necessário ter a permissão oss:PutObject. Para mais informações, consulte Conceder políticas de acesso personalizadas a um usuário RAM.

Notas de uso

• Leve em consideração os caracteres especiais que podem constar nos nomes dos objetos ao definir o cabeçalho Content-Disposition. Recomendamos o uso de codificação URL.

• A alteração no cabeçalho Content-Disposition ocorre por meio do método PUT, que sobrescreve os metadados existentes do objeto. Caso atualize apenas o cabeçalho Content-Disposition e mantenha os demais inalterados, consulte primeiro os metadados atuais do objeto, atualize o cabeçalho e, em seguida, utilize a coleção de metadados atualizada para iniciar a solicitação PUT.

• Para evitar um novo upload do objeto e reduzir o risco de sobrescrever dados existentes, recomendamos utilizar update_object_meta em vez de PutObject para atualizar os metadados.

Código de exemplo

O código de exemplo a seguir, em Python, demonstra como modificar o valor do cabeçalho Content-Disposition:

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from urllib.parse import quote

# Obtain access credentials from environment variables. Before you run this code, make sure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())

# Replace yourEndpoint with the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
# Enter the bucket name.
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', '<bucket_name>')

# Enter the full path of the object, for example, exampledir/exampleobject.txt. The full path cannot include the bucket name.
object_name = 'exampledir/exampleobject.txt'

# The filename you want users to see when they download the file. This name must be URL-encoded.
download_filename = quote('desired-filename.txt')

# Update the file metadata to set the filename for download.
# Note: This update operation replaces all of the object's metadata.
# If you want to keep other existing metadata,
# you must first get the current metadata, modify it, and then update it with the complete set of metadata.
headers = {'Content-Disposition': f'attachment; filename="{download_filename}"'}
bucket.update_object_meta(object_name, headers)

Para ver exemplos de código em outras linguagens de programação, consulte Gerenciar metadados de objetos.