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

Règles de dénomination des objets téléchargés

Le nom d'un objet téléchargé est déterminé selon les règles suivantes :

1. Paramètre response-content-disposition : si un objet est téléchargé via une URL signée contenant le paramètre response-content-disposition, l'objet téléchargé porte le nom spécifié par ce paramètre, quelle que soit la valeur de l'en-tête de métadonnées Content-Disposition.

2. Si une URL pré-signée ne spécifie pas le champ Content-Disposition, la valeur de ce champ est récupérée à partir des métadonnées du fichier.

3. Clé d'objet OSS : si les paramètres response-content-disposition et Content-Disposition ne sont pas spécifiés, l'objet téléchargé conserve le même nom que la clé d'objet dans OSS.

Spécifier un nom pour des téléchargements spécifiques d'un objet à l'aide d'une URL signée

Une URL signée accorde à un utilisateur un accès limité dans le temps à un objet privé dans OSS. Ajoutez le paramètre response-content-disposition à l'URL signée d'un objet afin de spécifier un nom différent pour cet objet lors de son téléchargement via cette URL, sans avoir besoin de modifier l'en-tête de métadonnées Content-Disposition de l'objet.

Scénarios

• Partage d'objets : utilisez une URL signée pour partager un objet avec un autre utilisateur et spécifiez le nom qui s'affichera lors du téléchargement par cet utilisateur. Votre clé d'objet originale n'est ainsi pas exposée.

• Téléchargements personnalisés : présentez des noms personnalisés pour les objets téléchargés à différents utilisateurs via des URL signées. Par exemple, personnalisez les noms des objets téléchargés en fonction du nom d'utilisateur ou du numéro de commande.

• Tests et aperçus : permettez aux utilisateurs de prévisualiser ou de tester un fichier sans modifier son nom de téléchargement original ou par défaut.

Autorisations

Pour générer une URL signée permettant de télécharger un objet, vous devez disposer de l'autorisation oss:GetObject. Pour plus d'informations, consultez la rubrique Accorder des stratégies d'accès personnalisées à un utilisateur RAM.

Notes d'utilisation

• Spécifiez le paramètre response-content-disposition lors de la création d'une URL signée. Ce paramètre s'applique uniquement à l'URL signée concernée.

• Veillez à spécifier des noms d'objets encodés en URL pour éviter les erreurs dues aux caractères spéciaux.

• Une URL signée possède une période de validité et ne peut plus être utilisée après son expiration. Tenez compte de cette durée de validité lorsque vous fournissez une URL signée aux utilisateurs.

• Si l'en-tête de métadonnées Content-Disposition est spécifié pour un objet et que celui-ci est téléchargé via une URL signée contenant le paramètre response-content-disposition, l'en-tête de métadonnées Content-Disposition est ignoré et la valeur du paramètre response-content-disposition est utilisée comme nom de l'objet téléchargé.

Exemple de code

L'exemple de code Python suivant illustre comment spécifier le paramètre response-content-disposition lors de la création d'une URL signée :

# -*- 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)

Pour des exemples de code dans d'autres langages, consultez la rubrique Partager des fichiers à l'aide d'URL de fichier.

Définir les noms de fichier pour tous les téléchargements à l'aide des métadonnées de fichier

L'en-tête de métadonnées Content-Disposition spécifie le nom par défaut d'un objet lors de son téléchargement. Pour qu'un objet porte un nouveau nom pour toutes les requêtes de téléchargement, définissez l'en-tête de métadonnées Content-Disposition sur ce nouveau nom. Le nouveau nom spécifié par l'en-tête Content-Disposition s'applique à toutes les requêtes de téléchargement qui ne contiennent pas le paramètre response-content-disposition.

Scénarios

• Partage de données à long terme : si un objet doit être téléchargé plusieurs fois avec le même nom à chaque fois, modifiez l'en-tête de métadonnées pour atteindre cet objectif.

• Archivage : dans le cadre de bibliothèques de documents publics ou de centres de ressources, il peut être nécessaire que tous les documents ou ressources portent des noms fixes et descriptifs pour faciliter leur identification et leur archivage.

• Mises à jour régulières : si vous souhaitez que les utilisateurs téléchargent la dernière version d'une documentation ou d'un logiciel mis à jour régulièrement via la même URL et avec un nom cohérent, définissez l'en-tête de métadonnées de la documentation ou du logiciel dans OSS.

Autorisations

Pour modifier les métadonnées d'un objet, vous devez disposer de l'autorisation oss:PutObject. Pour plus d'informations, consultez la rubrique Accorder des stratégies d'accès personnalisées à un utilisateur RAM.

Notes d'utilisation

• Tenez compte des caractères spéciaux susceptibles d'être inclus dans les noms d'objets lors de la définition de l'en-tête Content-Disposition. Nous vous recommandons d'utiliser l'encodage URL.

• La modification de l'en-tête Content-Disposition est effectuée via la méthode PUT, qui écrase les métadonnées existantes de l'objet. Si vous mettez uniquement à jour l'en-tête Content-Disposition d'un objet tout en conservant les autres en-têtes de métadonnées inchangés, vous devez interroger les métadonnées existantes de l'objet, mettre à jour l'en-tête, puis initier une requête PUT avec l'ensemble complet des métadonnées mises à jour.

• Pour éviter de recharger l'objet et réduire le risque d'écrasement des données existantes, nous vous recommandons d'utiliser update_object_meta plutôt que PutObject pour mettre à jour les métadonnées de l'objet.

Exemple de code

L'exemple de code Python suivant illustre comment modifier la valeur de l'en-tête 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)

Pour des exemples de code dans d'autres langages de programmation, consultez la rubrique Gérer les métadonnées des objets.