Object Storage Service:オブジェクトをファイルとしてダウンロードする

バケットから単一のオブジェクトをダウンロードする場合、オブジェクトの最終更新時刻または ETag に基づいて条件を指定できます。これらの条件が満たされた場合にのみ、オブジェクトがダウンロードされます。そうでない場合は、エラーが返され、ダウンロード操作はトリガーされません。これにより、不要なネットワーク転送とリソース消費が削減され、ダウンロード効率が向上します。

次の表に、使用可能な条件を示します。

次のサンプルコードは、条件付きダウンロードを実装する方法の例を示しています。

import argparse
import alibabacloud_oss_v2 as oss
from datetime import datetime, timezone

# Create a parser for parsing command-line arguments and describe the purpose of the script.
parser = argparse.ArgumentParser(description="get object to file sample")

# Specify the --region parameter to indicate the region in which the bucket is located. This parameter is required.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# Specify the --bucket parameter to indicate the name of the bucket in which the object is stored. This parameter is required.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# Specify the --endpoint parameter to indicate the endpoint of the region in which the bucket is located. This parameter is optional.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# Specify the --key parameter to indicate the name of the object. This parameter is required.
parser.add_argument('--key', help='The name of the object.', required=True)
# Specify the --file_path parameter to indicate the path to which the object is downloaded. This parameter is required.
parser.add_argument('--file_path', help='The path of the file to save the downloaded content.', required=True)

def main():
    # Parse the command-line parameters to obtain the specified values.
    args = parser.parse_args()

    # Obtain access credentials from environment variables for authentication.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Use the default configuration to create a configuration object (cfg) and specify the credential provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    
    # Set the region attribute of the cfg object to the region in the parser.
    cfg.region = args.region

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

    # Use the preceding configuration to initialize the OSSClient instance.
    client = oss.Client(cfg)

    # Define if_modified_since time.
    # Only objects modified after this time will be returned.
    if_modified_since = datetime(2024, 10, 1, 12, 0, 0, tzinfo=timezone.utc)

    # Assuming the ETag is DA5223EFCD7E0353BE08866700000000, if the specified ETag matches the ETag of the object, the IfMatch condition is met and the download will be triggered.
    etag = "\"DA5223EFCD7E0353BE08866700000000\""

    # Execute the request to download the object and save it to a local file.
    result = client.get_object_to_file(
        oss.GetObjectRequest(
            bucket=args.bucket,  # Specify the name of the bucket.
            key=args.key,        # Specify the object key.
            if_modified_since=if_modified_since,  # Only objects modified after the specified time will be returned.
            if_match=etag,       # Only objects with matching ETag will be returned.
        ),
        args.file_path  # Specify the local path to save the downloaded file.
    )

    # Display the response information, including status code, request ID, etc.
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' content length: {result.content_length},'
          f' content range: {result.content_range},'
          f' content type: {result.content_type},'
          f' etag: {result.etag},'
          f' last modified: {result.last_modified},'
          f' content md5: {result.content_md5},'
          f' cache control: {result.cache_control},'
          f' content disposition: {result.content_disposition},'
          f' content encoding: {result.content_encoding},'
          f' expires: {result.expires},'
          f' hash crc64: {result.hash_crc64},'
          f' storage class: {result.storage_class},'
          f' object type: {result.object_type},'
          f' version id: {result.version_id},'
          f' tagging count: {result.tagging_count},'
          f' server side encryption: {result.server_side_encryption},'
          f' server side data encryption: {result.server_side_data_encryption},'
          f' next append position: {result.next_append_position},'
          f' expiration: {result.expiration},'
          f' restore: {result.restore},'
          f' process status: {result.process_status},'
          f' delete marker: {result.delete_marker},'
          f' server time: {result.headers.get("x-oss-server-time")},'
    )

# Call the main function to start the processing logic when the script is directly run.
if __name__ == "__main__":
    main()  # Specify the entry point of the script. The control flow starts here.

オブジェクトをダウンロードするときは、プログレスバーを使用してダウンロードの進捗状況をリアルタイムで監視できます。進捗状況の監視は、ダウンロードタスクの完了に時間がかかる場合に、タスクが停止しているかどうかを確認するのに役立ちます。

次のサンプルコードは、get_object_to_file を使用してオブジェクトをローカルファイルにダウンロードするときに、プログレスバーを使用してダウンロードの進捗状況を表示する方法を示しています。

import argparse
import alibabacloud_oss_v2 as oss

# Create a parser for parsing command-line arguments and describe the purpose of the script.
parser = argparse.ArgumentParser(description="get object sample")

# Specify the --region parameter to indicate the region in which the bucket is located. This parameter is required.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# Specify the --bucket parameter to indicate the name of the bucket in which the object is stored. This parameter is required.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# Specify the --endpoint parameter to indicate the endpoint of the region in which the bucket is located. This parameter is optional.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# Specify the --key parameter to indicate the name of the object. This parameter is required. 
parser.add_argument('--key', help='The name of the object.', required=True)

def main():
    # Parse the command-line parameters to obtain the specified values.
    args = parser.parse_args()

    # Obtain access credentials from environment variables for authentication.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Use the default configuration to create a configuration object (cfg) and specify the credential provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Set the region attribute of the cfg object to the region in the parser.
    cfg.region = args.region

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

    # Use the preceding configuration to initialize the OSSClient instance.
    client = oss.Client(cfg)

    # Define a dictionary variable progress_state to store the download progress status, with an initial value of 0.
    progress_state = {'saved': 0}
    
    # Define the progress callback function _progress_fn.
    def _progress_fn(n, written, total):
        # Use a dictionary to store the accumulated written bytes.
        progress_state['saved'] += n

        # Calculate the current download percentage by dividing the number of bytes written by the total bytes and truncating the result to an integer.
        rate = int(100 * (float(written) / float(total)))

        # Print the current download progress. Use \r to return to the start of the line, achieving real-time refresh in the terminal.
        # end='' suppresses line breaks, enabling subsequent prints to overwrite the current line.
        print(f'\r{rate}% ', end='')

    # Execute the request to download the object, and specify the bucket name, object name and the progress callback function.
    result = client.get_object_to_file(
        oss.GetObjectRequest(
            bucket=args.bucket,  # Specify the name of the bucket.
            key=args.key,        # Specify the object key.
            progress_fn=_progress_fn, # Specify the progress callback function.
        ),
        "/local/dir/example", # Specify the local path to save the file.
    )

    # Display the response information.
    print(vars(result))

# Call the main function to start the processing logic when the script is directly run.
if __name__ == "__main__":
    main()  # Specify the entry point of the script. The control flow starts here.

次のサンプルコードは、get_object を使用してオブジェクトをストリーミングするときに、プログレスバーを使用してダウンロードの進捗状況を表示する方法を示しています。

import argparse
import alibabacloud_oss_v2 as oss
import os

# Create a command-line parameter parser.
parser = argparse.ArgumentParser(description="get object sample")

# Specify the --region parameter to indicate the region in which the bucket is located. This parameter is required.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# Specify the --bucket parameter to indicate the name of the bucket. This command line parameter is required.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# Specify the --endpoint parameter to indicate the endpoint of the region in which the bucket is located. This parameter is optional.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# Specify the --key parameter to indicate the name of the object. This parameter is required.
parser.add_argument('--key', help='The name of the object.', required=True)

def main():
    # Parse the command line parameters.
    args = parser.parse_args()

    # Obtain access credentials from environment variables for authentication.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Load the default configuration of the SDK and specify the credential provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Specify the region in which the bucket is located.
    cfg.region = args.region

    # If an endpoint is provided, specify the endpoint in the configuration object.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the configuration to create an OSSClient instance.
    client = oss.Client(cfg)

    # Execute the request to download the object, and specify the bucket name and object name.
    result = client.get_object(oss.GetObjectRequest(
        bucket=args.bucket,  # Specify the name of the bucket.
        key=args.key,  # Specify the object key.
    ))

    # Get the total size of the file in bytes from the object response result.
    total_size = result.content_length

    # Initialize the progress counter to 0, used to record the amount of data downloaded.
    progress_save_n = 0

    # Iterate through data blocks in the response body to implement block-by-block data reading.
    for d in result.body.iter_bytes():
        # Accumulate the length of the current data block into the total downloaded amount.
        progress_save_n += len(d)

        # Calculate the current download percentage by computing the ratio of the downloaded amount to the total size and rounding to the nearest integer.
        rate = int(100 * (float(progress_save_n) / float(total_size)))

        # Print the current download progress. Utilize \r (carriage return) to reposition the cursor at the beginning of the line, enabling real-time progress updates within the command-line interface.
        # end='' suppresses line breaks, enabling subsequent prints to overwrite the current line.
        print(f'\r{rate}% ', end='')

    # Print all attributes of the result object for debugging purposes or to examine the complete response content.
    print(vars(result))


# Call the main function to start the processing logic when the script is directly run.
if __name__ == "__main__":
    main()  # Specify the entry point of the script. The control flow starts here.