Comment télécharger des fichiers à l'aide du SDK Python OSS V2 - Object Storage Service

Remarques d'utilisation

Les exemples de code de cette rubrique utilisent la région Chine (Hangzhou), dont l'ID est cn-hangzhou. Par défaut, un endpoint public est utilisé. Si vous accédez à OSS depuis d'autres services Alibaba Cloud situés dans la même région, utilisez un endpoint interne. Pour plus d'informations sur les régions et les endpoints pris en charge par OSS, consultez Régions et endpoints.
Pour télécharger un fichier, vous devez disposer de l'autorisation oss:GetObject. Pour plus d'informations, consultez Attacher une politique personnalisée à un utilisateur RAM.

Définition de la méthode

Fonctionnalités du Downloader

Le module Downloader du SDK Python V2 simplifie le téléchargement de fichiers en masquant les détails d'implémentation sous-jacents.

Le module Downloader divise automatiquement un fichier en parties plus petites et les télécharge en parallèle, ce qui améliore les performances de téléchargement.
Le module Downloader propose également la fonctionnalité de reprise après interruption. La progression du téléchargement est enregistrée ; ainsi, si le téléchargement est interrompu par des pannes réseau ou des arrêts inattendus du programme, vous pouvez reprendre l'opération au dernier point d'arrêt.

Le code suivant présente les méthodes courantes du module Downloader :

class Downloader:
  ...

def downloader(self, **kwargs) -> Downloader:
  ...

def download_file(self, request: models.GetObjectRequest, filepath: str, **kwargs: Any) -> DownloadResult:
  ...
  
def download_to(self, request: models.GetObjectRequest, writer: IO[bytes], **kwargs: Any) -> DownloadResult:
  ...

Paramètres de requête

Paramètre

Type

Description

request

GetObjectRequest

Les paramètres de requête pour le téléchargement d'un objet. Ces paramètres sont identiques à ceux de la méthode GetObject. Pour plus d'informations, consultez GetObjectRequest

filepath

str

Le chemin d'accès au fichier local.

writer

IO[bytes]

Le flux de téléchargement.

**kwargs

Any

(Facultatif) Paramètre arbitraire. Type : dictionnaire

Paramètres de réponse

Type

Description

DownloadResult

Les paramètres de réponse pour le téléchargement d'un objet. Pour plus d'informations, consultez DownloadResult

Vous pouvez spécifier des options de configuration lors de l'initialisation d'une instance de downloader ou pour chaque appel de téléchargement. Par exemple, vous pouvez définir la taille des parties comme suit :

Définissez les paramètres de configuration du downloader.
```
downloader = client.downloader(part_size=1024 * 1024)
```

Définissez les paramètres de configuration pour chaque requête de téléchargement.

result = downloader.download_file(oss.GetObjectRequest(
    bucket="example_bucket",
    key="example_key",
),
    filepath="/local/dir/example",
    part_size=10 * 1024 * 1024,
)

Le tableau suivant décrit les options de configuration courantes.

Paramètre

Type

Description

part_size

int

Spécifie la taille des parties. La valeur par défaut est de 6 MiB.

parallel_num

int

Le nombre de tâches de téléchargement simultanées. Valeur par défaut : 3. Il s'agit de la limite de concurrence pour un seul appel, et non de la limite de concurrence globale.

enable_checkpoint

bool

Indique s'il faut activer la fonctionnalité de reprise après interruption. Par défaut, cette fonctionnalité est désactivée.

checkpoint_dir

str

Spécifie le chemin d'accès pour enregistrer le fichier de suivi. Exemple : /local/dir/. Ce paramètre n'est valide que si enable_checkpoint est défini sur True.

verify_data

bool

Indique s'il faut vérifier la valeur CRC-64 des données téléchargées lors de la reprise du téléchargement. Par défaut, la valeur n'est pas vérifiée. Ce paramètre n'est valide que si enable_checkpoint est défini sur True.

use_temp_file

bool

Indique s'il faut utiliser un fichier temporaire pendant le téléchargement. Activé par défaut. Les données sont d'abord écrites dans un fichier temporaire, puis renommées vers le fichier cible une fois le téléchargement réussi.

Pour plus d'informations sur la définition de la méthode du gestionnaire de téléchargement de fichiers, consultez Downloader.

Exemple de code

Utilisez le code suivant pour télécharger un fichier depuis un bucket vers un appareil local.

import argparse
import alibabacloud_oss_v2 as oss

# Create a command-line argument parser and describe the purpose of the script: download file sample.
parser = argparse.ArgumentParser(description="download file sample")

# Add the command-line argument --region, which indicates the region where the bucket is located. This argument is required.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# Add the command-line argument --bucket, which indicates the name of the bucket from which you want to download the file. This argument is required.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# Add the command-line argument --endpoint, which indicates the domain name that other services can use to access OSS. This argument is optional.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# Add the command-line argument --key, which indicates the key of the object (file) in OSS. This argument is required.
parser.add_argument('--key', help='The name of the object.', required=True)
# Add the command-line argument --file_path, which indicates the local path to save the downloaded file. This argument is required. For example, "/Users/yourLocalPath/yourFileName".
parser.add_argument('--file_path', help='The path to save the downloaded file.', required=True)

def main():
    # Parse the command-line arguments to obtain the values entered by the user.
    args = parser.parse_args()

    # Load the authentication information required to access OSS from environment variables for identity verification.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Use the default configurations of the SDK to create a configuration object and set the authentication provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    
    # Set the region property of the configuration object based on the command-line arguments provided by the user.
    cfg.region = args.region

    # If a custom endpoint is provided, update the endpoint property of the configuration object.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the preceding configurations to initialize the OSS client to interact with OSS.
    client = oss.Client(cfg)

    # Create an object for downloading files.
    downloader = client.downloader()

    # Call the method to perform the file download operation.
    result = downloader.download_file(
        oss.GetObjectRequest(
            bucket=args.bucket,  # Specify the destination bucket.
            key=args.key,        # Specify the name of the file in OSS.
        ),
        filepath=args.file_path  # Specify the local path to save the downloaded file.
    )

    # Print information about the download result, including the number of bytes written.
    print(f'written: {result.written}')

# When this script is directly executed, call the main function to start the processing logic.
if __name__ == "__main__":
    main()  # The entry point of the script, where the program flow starts.

Scénarios courants

Utiliser le downloader pour définir la taille des parties et la concurrence

Utilisez le code suivant pour configurer le downloader afin de définir la taille des parties et le niveau de concurrence.

import argparse
import alibabacloud_oss_v2 as oss

# Create a command-line argument parser and describe the purpose of the script: download file sample.
parser = argparse.ArgumentParser(description="download file sample")

# Add the command-line argument --region, which indicates the region where the bucket is located. This argument is required.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# Add the command-line argument --bucket, which indicates the name of the bucket from which you want to download the file. This argument is required.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# Add the command-line argument --endpoint, which indicates the domain name that other services can use to access OSS. This argument is optional.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# Add the command-line argument --key, which indicates the key of the object (file) in OSS. This argument is required.
parser.add_argument('--key', help='The name of the object.', required=True)
# Add the command-line argument --file_path, which indicates the local path to save the downloaded file. This argument is required. For example, "/Users/yourLocalPath/yourFileName".
parser.add_argument('--file_path', help='The path to save the downloaded file.', required=True)

def main():
    # Parse the command-line arguments to obtain the values entered by the user.
    args = parser.parse_args()

    # Load the authentication information required to access OSS from environment variables for identity verification.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Use the default configurations of the SDK to create a configuration object and set the authentication provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    
    # Set the region property of the configuration object based on the command-line arguments provided by the user.
    cfg.region = args.region

    # If a custom endpoint is provided, update the endpoint property of the configuration object.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the preceding configurations to initialize the OSS client to interact with OSS.
    client = oss.Client(cfg)

    # Create an object for downloading files and set advanced options.
    downloader = client.downloader(
        part_size=1024 * 1024,  # Set the size of each part to 1 MB.
        parallel_num=5,         # Set the number of concurrent download threads to 5.
        block_size=1024 * 1024  # Set the size of the data block read each time to 1 MB.
    )

    # Call the method to perform the file download operation.
    result = downloader.download_file(
        oss.GetObjectRequest(
            bucket=args.bucket,  # Specify the destination bucket.
            key=args.key,        # Specify the name of the file in OSS.
        ),
        filepath=args.file_path  # Specify the local path to save the downloaded file.
    )

    # Print information about the download result, including the number of bytes written.
    print(f'written: {result.written}')

# When this script is directly executed, call the main function to start the processing logic.
if __name__ == "__main__":
    main()  # The entry point of the script, where the program flow starts.

Utiliser le downloader pour activer la reprise après interruption

Utilisez le code suivant pour configurer le downloader afin d'activer la fonctionnalité de reprise après interruption.

import argparse
import alibabacloud_oss_v2 as oss

# Create a command-line argument parser and describe the purpose of the script: download file sample.
parser = argparse.ArgumentParser(description="download file sample")

# Add the command-line argument --region, which indicates the region where the bucket is located. This argument is required.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# Add the command-line argument --bucket, which indicates the name of the bucket from which you want to download the file. This argument is required.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# Add the command-line argument --endpoint, which indicates the domain name that other services can use to access OSS. This argument is optional.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# Add the command-line argument --key, which indicates the key of the object (file) in OSS. This argument is required.
parser.add_argument('--key', help='The name of the object.', required=True)
# Add the command-line argument --file_path, which indicates the local path to save the downloaded file. This argument is required. For example, "/Users/yourLocalPath/yourFileName".
parser.add_argument('--file_path', help='The path to save the downloaded file.', required=True)

def main():
    # Parse the command-line arguments to obtain the values entered by the user.
    args = parser.parse_args()

    # Load the authentication information required to access OSS from environment variables for identity verification.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Use the default configurations of the SDK to create a configuration object and set the authentication provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    
    # Set the region property of the configuration object based on the command-line arguments provided by the user.
    cfg.region = args.region

    # If a custom endpoint is provided, update the endpoint property of the configuration object.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the preceding configurations to initialize the OSS client to interact with OSS.
    client = oss.Client(cfg)

    # Create an object for downloading files and set advanced options.
    downloader = client.downloader(
        use_temp_file=True,            # Use a temporary file.
        enable_checkpoint=True,        # Enable resumable download.
        checkpoint_dir=args.file_path, # The directory to save the resumable download record file.
        verify_data=True               # Specifies whether to verify data.
    )

    # Call the method to perform the file download operation.
    result = downloader.download_file(
        oss.GetObjectRequest(
            bucket=args.bucket,  # Specify the destination bucket.
            key=args.key,        # Specify the name of the file in OSS.
        ),
        filepath=args.file_path  # Specify the local path to save the downloaded file.
    )

    # Print information about the download result, including the number of bytes written.
    print(f'written: {result.written}')

# When this script is directly executed, call the main function to start the processing logic.
if __name__ == "__main__":
    main()  # The entry point of the script, where the program flow starts.

Utiliser le downloader et afficher une barre de progression

L'exemple de code suivant montre comment afficher une barre de progression lors du téléchargement d'un fichier avec le downloader.

import argparse
import alibabacloud_oss_v2 as oss

# Create a command-line argument parser and describe the purpose of the script: download file sample.
parser = argparse.ArgumentParser(description="download file sample")

# Add the command-line argument --region, which indicates the region where the bucket is located. This argument is required.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# Add the command-line argument --bucket, which indicates the name of the bucket from which you want to download the file. This argument is required.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# Add the command-line argument --endpoint, which indicates the domain name that other services can use to access OSS. This argument is optional.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# Add the command-line argument --key, which indicates the key of the object (file) in OSS. This argument is required.
parser.add_argument('--key', help='The name of the object.', required=True)
# Add the command-line argument --file_path, which indicates the local path to save the downloaded file. This argument is required. For example, "/Users/yourLocalPath/yourFileName".
parser.add_argument('--file_path', help='The path to save the downloaded file.', required=True)

def main():
    # Parse the command-line arguments to obtain the values entered by the user.
    args = parser.parse_args()

    # Load the authentication information required to access OSS from environment variables for identity verification.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Use the default configurations of the SDK to create a configuration object and set the authentication provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Set the region property of the configuration object based on the command-line arguments provided by the user.
    cfg.region = args.region

    # If a custom endpoint is provided, update the endpoint property of the configuration object.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the preceding configurations to initialize the OSS client to interact with OSS.
    client = oss.Client(cfg)

    # Create an object for downloading files.
    downloader = client.downloader()

    # Define a dictionary variable progress_state to save the download progress status. The initial value is 0.
    progress_state = {'saved': 0}

    # Define the progress callback function _progress_fn.
    def _progress_fn(n, written, total):
        # Use a dictionary to store the cumulative number of bytes written.
        progress_state['saved'] += n

        # Calculate the current download percentage. The value is obtained by dividing the number of written bytes by the total number of bytes and rounding down to the nearest integer.
        rate = int(100 * (float(written) / float(total)))

        # Print the current download progress. \r indicates returning to the beginning of the line to implement real-time refresh in the command line.
        # end='' indicates that no line break is added, so that the next print overwrites the current line.
        print(f'\rDownload progress: {rate}% ', end='')

    # Call the method to perform the file download operation.
    result = downloader.download_file(
        oss.GetObjectRequest(
            bucket=args.bucket,  # Specify the destination bucket.
            key=args.key,        # Specify the name of the file in OSS.
            progress_fn=_progress_fn,  # Set the progress callback function.
        ),
        filepath=args.file_path  # Specify the local path to save the downloaded file.
    )

    # Print information about the download result, including the number of bytes written.
    print(f'written: {result.written}')

# When this script is directly executed, call the main function to start the processing logic.
if __name__ == "__main__":
    main()  # The entry point of the script, where the program flow starts.

Références

Pour plus d'informations sur le gestionnaire de téléchargement, consultez Guide du développeur.
Pour obtenir l'exemple de code complet relatif au gestionnaire de téléchargement, consultez download_file.py.