OSS Python SDK V2 を使用したファイルのアップロード方法 - Object Storage Service

このトピックでは、Python SDK V2 の新しい Uploader モジュールを使用してファイルをアップロードする方法について説明します。

注意事項

このトピックのサンプルコードは、中国 (杭州) リージョンのパブリックエンドポイントを使用しています。リージョン ID は cn-hangzhou です。同じリージョン内の他の Alibaba Cloud サービスから OSS にアクセスする場合は、内部エンドポイントを使用する必要があります。 OSS がサポートするリージョンとエンドポイントの詳細については、「OSS のリージョンとエンドポイント」をご参照ください。
アップロードを実行するには、oss:PutObject 権限が必要です。詳細については、「RAM ユーザーにカスタム権限を付与する」をご参照ください。

メソッド定義

アップロードマネージャの概要

Python SDK V2 の新しい Uploader モジュールは、ファイルのアップロードを簡素化するために、基礎となる実装の詳細を抽象化する統合アップロードメソッドを提供します。

Uploader は、マルチパートアップロード方式を使用して、ファイルまたはストリームを複数の部分に分割し、それらの部分を同時にアップロードします。このプロセスにより、アップロードのパフォーマンスが向上します。
Uploader は、再開可能なアップロード機能も提供します。アップロード中、Uploader は完了した部分のステータスを記録します。ネットワークエラーや予期しないプログラムの終了などの問題によってアップロードが中断された場合、記録されたブレークポイントからアップロードを再開できます。

次の表は、Uploader の一般的なメソッドについて説明しています。

class Uploader:
  ...

def uploader(self, **kwargs) -> Uploader:
  # ... アップローダーインスタンスを初期化します。
  ...

def upload_file(self, request: models.PutObjectRequest, filepath: str, **kwargs: Any) -> UploadResult:
  # ... ローカルファイルからアップロードします。
  ...
  
def upload_from(self, request: models.PutObjectRequest, reader: IO[bytes], **kwargs: Any) -> UploadResult:
  # ... ファイルストリームまたはファイルのようなオブジェクトからアップロードします。
  ...

リクエストパラメーター

パラメーター	タイプ	説明
request	PutObjectRequest	オブジェクトをアップロードするためのリクエストパラメーター。これらのパラメーターは、PutObject メソッドのパラメーターと同じです。詳細については、「PutObjectRequest」を参照してください。
reader	IO[bytes]	アップロードされるデータストリーム
filepath	str	ローカルファイルのパス
**kwargs	Any	(オプション) 任意のパラメーター。タイプは辞書です。

レスポンスパラメーター

タイプ	説明
UploadResult	オブジェクトのアップロードに対するレスポンスパラメーター。詳細については、「UploadResult」を参照してください。

client.uploader を使用してアップロードマネージャーインスタンスを初期化する場合、構成オプションを指定してアップロード動作をカスタマイズできます。また、これらのオプションを各アップロード API 呼び出しに指定して、特定のオブジェクトアップロードの動作をカスタマイズすることもできます。たとえば、パートサイズを指定できます。

アップローダーの構成パラメーターを設定する

uploader = client.uploader(part_size=10  * 1024 * 1024) # パートサイズを 10MB に設定します。

各アップロードリクエストの構成パラメーターを設定する

result = uploader.upload_file(oss.PutObjectRequest(
        bucket="example_bucket", # バケット名を指定します。
        key="example_key", # オブジェクト名を指定します。
    ),
    filepath="/local/dir/example", # アップロードするローカルファイルのパスを指定します。
    part_size=10 * 1024 * 1024, # パートサイズを 10MB に設定します。
)

次の表に、一般的な構成オプションを示します。

パラメーター	タイプ	説明
part_size	int	パートサイズを指定します。デフォルト値は 6 MiB です。
parallel_num	int	同時アップロードタスクの数を指定します。デフォルト値は 3 です。このパラメーターは、グローバルな同時実行性ではなく、単一の呼び出しの同時実行性を制限します。
leave_parts_on_error	bool	アップロードが失敗した場合に、アップロードされたパートを保持するかどうかを指定します。デフォルトでは、パートは保持されません。
enable_checkpoint	bool	再開可能なアップロードを有効にするかどうかを指定します。デフォルトでは、この機能は無効になっています。説明 enable_checkpoint パラメーターは、upload_file メソッドに対してのみ有効です。 upload_from メソッドは、このパラメーターをサポートしていません。
checkpoint_dir	str	レコードファイルが保存されるパスを指定します。例: /local/dir/。このパラメーターは、enable_checkpoint が true に設定されている場合にのみ有効です。

ファイルアップロードマネージャーの完全なメソッド定義については、「Uploader」を参照してください。

サンプルコード

アップロードマネージャーを使用してローカルファイルをバケットにアップロードするには、次のコードを使用できます。

import argparse
import alibabacloud_oss_v2 as oss

# コマンドライン引数パーサーを作成し、スクリプトの目的 (ファイルアップロードのサンプル) を記述します。
parser = argparse.ArgumentParser(description="ファイルアップロードのサンプル")

# --region コマンドライン引数を追加します。これは、バケットが配置されているリージョンを指定する必須パラメーターです。
parser.add_argument('--region', help='バケットが配置されているリージョン。', required=True)
# --bucket コマンドライン引数を追加します。これは、ファイルをアップロードするバケットの名前を指定する必須パラメーターです。
parser.add_argument('--bucket', help='バケットの名前。', required=True)
# --endpoint コマンドライン引数を追加します。これは、他のサービスが OSS にアクセスするために使用できるドメイン名を指定するオプションパラメーターです。
parser.add_argument('--endpoint', help='他のサービスが OSS にアクセスするために使用できるドメイン名')
# --key コマンドライン引数を追加します。これは、OSS 内のオブジェクト (ファイル) のキーを指定する必須パラメーターです。
parser.add_argument('--key', help='オブジェクトの名前。', required=True)
# --file_path コマンドライン引数を追加します。これは、アップロードするローカルファイルのパスを指定する必須パラメーターです。例: "/Users/yourLocalPath/yourFileName"。
parser.add_argument('--file_path', help='アップロードファイルのパス。', required=True)

def main():
    # コマンドライン引数を解析して、ユーザーが指定した値を取得します。
    args = parser.parse_args()

    # ID 検証のために、環境変数から OSS にアクセスするために必要な認証情報をロードします。
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # SDK のデフォルト構成を使用して構成オブジェクトを作成し、資格情報プロバイダーを設定します。
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    
    # ユーザーが指定したコマンドライン引数に基づいて、構成オブジェクトのリージョン プロパティを設定します。
    cfg.region = args.region

    # カスタムエンドポイントが指定されている場合は、構成オブジェクトの endpoint プロパティを更新します。
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # 前述の構成を使用して OSS クライアントを初期化し、OSS との対話の準備をします。
    client = oss.Client(cfg)

    # ファイルアップロード用のオブジェクトを作成します。
    uploader = client.uploader()

    # メソッドを呼び出して、ファイルアップロード操作を実行します。
    result = uploader.upload_file(
        oss.PutObjectRequest(
            bucket=args.bucket,  # ターゲットバケットを指定します。
            key=args.key,        # OSS 内のファイル名を指定します。
        ),
        filepath=args.file_path  # ローカルファイルの場所を指定します。
    )

    # アップロード結果に関する情報 (ステータスコード、リクエスト ID、Content-MD5 など) を出力します。
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' content md5: {result.headers.get("Content-MD5")},'
          f' etag: {result.etag},'
          f' hash crc64: {result.hash_crc64},'
          f' version id: {result.version_id},'
          f' server time: {result.headers.get("x-oss-server-time")},'
          )

# このスクリプトが直接実行された場合は、main 関数を呼び出して処理ロジックを開始します。
if __name__ == "__main__":
    main()  # スクリプトのエントリポイント。プログラムフローはここから始まります。

シナリオ

アップロードマネージャーを使用して再開可能なアップロードを有効にする

再開可能なアップロードを有効にするには、次のコードを使用できます。

import argparse
import alibabacloud_oss_v2 as oss

# コマンドライン引数パーサーを作成し、スクリプトの目的 (ファイルアップロードのサンプル) を記述します。
parser = argparse.ArgumentParser(description="ファイルアップロードのサンプル")

# --region コマンドライン引数を追加します。これは、バケットが配置されているリージョンを指定する必須パラメーターです。
parser.add_argument('--region', help='バケットが配置されているリージョン。', required=True)
# --bucket コマンドライン引数を追加します。これは、ファイルをアップロードするバケットの名前を指定する必須パラメーターです。
parser.add_argument('--bucket', help='バケットの名前。', required=True)
# --endpoint コマンドライン引数を追加します。これは、他のサービスが OSS にアクセスするために使用できるドメイン名を指定するオプションパラメーターです。
parser.add_argument('--endpoint', help='他のサービスが OSS にアクセスするために使用できるドメイン名')
# --key コマンドライン引数を追加します。これは、OSS 内のオブジェクト (ファイル) のキーを指定する必須パラメーターです。
parser.add_argument('--key', help='オブジェクトの名前。', required=True)
# --file_path コマンドライン引数を追加します。これは、アップロードするローカルファイルのパスを指定する必須パラメーターです。例: "/Users/yourLocalPath/yourFileName"。
parser.add_argument('--file_path', help='アップロードファイルのパス。', required=True)


def main():
    # コマンドライン引数を解析して、ユーザーが指定した値を取得します。
    args = parser.parse_args()

    # ID 検証のために、環境変数から OSS にアクセスするために必要な認証情報をロードします。
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # SDK のデフォルト構成を使用して構成オブジェクトを作成し、資格情報プロバイダーを設定します。
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    
    # ユーザーが指定したコマンドライン引数に基づいて、構成オブジェクトのリージョン プロパティを設定します。
    cfg.region = args.region

    # カスタムエンドポイントが指定されている場合は、構成オブジェクトの endpoint プロパティを更新します。
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # 前述の構成を使用して OSS クライアントを初期化し、OSS との対話の準備をします。
    client = oss.Client(cfg)

    # ファイルアップロード用のオブジェクトを作成し、再開可能なアップロードを有効にし、ブレークポイントレコードファイルを保存するパスを指定します。
    uploader = client.uploader(enable_checkpoint=True, checkpoint_dir="/Users/yourLocalPath/checkpoint/") # 再開可能なアップロードを有効にし、チェックポイントディレクトリを指定します。

    # メソッドを呼び出して、ファイルアップロード操作を実行します。
    result = uploader.upload_file(
        oss.PutObjectRequest(
            bucket=args.bucket,  # ターゲットバケットを指定します。
            key=args.key,        # OSS 内のファイル名を指定します。
        ),
        filepath=args.file_path  # ローカルファイルの場所を指定します。
    )

    # アップロード結果に関する情報 (ステータスコード、リクエスト ID、Content-MD5 など) を出力します。
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' content md5: {result.headers.get("Content-MD5")},'
          f' etag: {result.etag},'
          f' hash crc64: {result.hash_crc64},'
          f' version id: {result.version_id},'
          f' server time: {result.headers.get("x-oss-server-time")},'
          )

# このスクリプトが直接実行された場合は、main 関数を呼び出して処理ロジックを開始します。
if __name__ == "__main__":
    main()  # スクリプトのエントリポイント。プログラムフローはここから始まります。

アップロードマネージャーを使用してローカルファイルストリームをアップロードする

アップロードマネージャーを使用してローカルファイルストリームをアップロードするには、次のコードを使用できます。

import argparse
import alibabacloud_oss_v2 as oss

# コマンドライン引数パーサーを作成し、スクリプトの目的 (ファイルからのアップロードのサンプル) を記述します。
parser = argparse.ArgumentParser(description="ファイルからのアップロードのサンプル")

# --region コマンドライン引数を追加します。これは、バケットが配置されているリージョンを指定する必須パラメーターです。
parser.add_argument('--region', help='バケットが配置されているリージョン。', required=True)
# --bucket コマンドライン引数を追加します。これは、ファイルをアップロードするバケットの名前を指定する必須パラメーターです。
parser.add_argument('--bucket', help='バケットの名前。', required=True)
# --endpoint コマンドライン引数を追加します。これは、他のサービスが OSS にアクセスするために使用できるドメイン名を指定するオプションパラメーターです。
parser.add_argument('--endpoint', help='他のサービスが OSS にアクセスするために使用できるドメイン名')
# --key コマンドライン引数を追加します。これは、OSS 内のオブジェクト (ファイル) のキーを指定する必須パラメーターです。
parser.add_argument('--key', help='オブジェクトの名前。', required=True)
# --file_path コマンドライン引数を追加します。これは、アップロードするローカルファイルのパスを指定する必須パラメーターです。例: "/Users/yourLocalPath/yourFileName"。
parser.add_argument('--file_path', help='アップロードファイルのパス。', required=True)

def main():
    # コマンドライン引数を解析して、ユーザーが指定した値を取得します。
    args = parser.parse_args()

    # ID 検証のために、環境変数から OSS にアクセスするために必要な認証情報をロードします。
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # SDK のデフォルト構成を使用して構成オブジェクトを作成し、資格情報プロバイダーを設定します。
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    
    # ユーザーが指定したコマンドライン引数に基づいて、構成オブジェクトのリージョン プロパティを設定します。
    cfg.region = args.region

    # カスタムエンドポイントが指定されている場合は、構成オブジェクトの endpoint プロパティを更新します。
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # 前述の構成を使用して OSS クライアントを初期化し、OSS との対話の準備をします。
    client = oss.Client(cfg)

    # ファイルアップロード用のオブジェクトを作成します。
    uploader = client.uploader()

    # ローカルファイルをバイナリモードで読み取り用に開きます。
    with open(file=args.file_path, mode='rb') as f: # ファイルを読み取り専用バイナリモードで開きます。
        # メソッドを呼び出して、ファイルアップロード操作を実行します。
        result = uploader.upload_from(
            oss.PutObjectRequest(
                bucket=args.bucket,  # ターゲットバケットを指定します。
                key=args.key,        # OSS 内のファイル名を指定します。
            ),
            reader=f  # ファイルリーダーを渡します。
        )

        # アップロード結果に関する情報 (ステータスコード、リクエスト ID、Content-MD5 など) を出力します。
        print(f'status code: {result.status_code},'
              f' request id: {result.request_id},'
              f' content md5: {result.headers.get("Content-MD5")},'
              f' etag: {result.etag},'
              f' hash crc64: {result.hash_crc64},'
              f' version id: {result.version_id},'
              f' server time: {result.headers.get("x-oss-server-time")},'
              )

# このスクリプトが直接実行された場合は、main 関数を呼び出して処理ロジックを開始します。
if __name__ == "__main__":
    main()  # スクリプトのエントリポイント。プログラムフローはここから始まります。

アップロードマネージャーを使用してパートサイズと同時実行性を設定する

パートサイズと同時実行性を指定するには、次のコードを使用できます。

import argparse
import alibabacloud_oss_v2 as oss

# コマンドライン引数パーサーを作成し、スクリプトの目的 (ファイルアップロードのサンプル) を記述します。
parser = argparse.ArgumentParser(description="ファイルアップロードのサンプル")

# --region コマンドライン引数を追加します。これは、バケットが配置されているリージョンを指定する必須パラメーターです。
parser.add_argument('--region', help='バケットが配置されているリージョン。', required=True)
# --bucket コマンドライン引数を追加します。これは、ファイルをアップロードするバケットの名前を指定する必須パラメーターです。
parser.add_argument('--bucket', help='バケットの名前。', required=True)
# --endpoint コマンドライン引数を追加します。これは、他のサービスが OSS にアクセスするために使用できるドメイン名を指定するオプションパラメーターです。
parser.add_argument('--endpoint', help='他のサービスが OSS にアクセスするために使用できるドメイン名')
# --key コマンドライン引数を追加します。これは、OSS 内のオブジェクト (ファイル) のキーを指定する必須パラメーターです。
parser.add_argument('--key', help='オブジェクトの名前。', required=True)
# --file_path コマンドライン引数を追加します。これは、アップロードするローカルファイルのパスを指定する必須パラメーターです。例: "/Users/yourLocalPath/yourFileName"。
parser.add_argument('--file_path', help='アップロードファイルのパス。', required=True)

def main():
    # コマンドライン引数を解析して、ユーザーが指定した値を取得します。
    args = parser.parse_args()

    # ID 検証のために、環境変数から OSS にアクセスするために必要な認証情報をロードします。
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # SDK のデフォルト構成を使用して構成オブジェクトを作成し、資格情報プロバイダーを設定します。
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    
    # ユーザーが指定したコマンドライン引数に基づいて、構成オブジェクトのリージョン プロパティを設定します。
    cfg.region = args.region

    # カスタムエンドポイントが指定されている場合は、構成オブジェクトの endpoint プロパティを更新します。
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # 前述の構成を使用して OSS クライアントを初期化し、OSS との対話の準備をします。
    client = oss.Client(cfg)

    # ファイルアップロード用のオブジェクトを作成し、パートサイズと同時実行性を設定します。
    uploader = client.uploader(
        part_size=100 * 1024,  # パートサイズを 100 KB に設定します。
        parallel_num=5,        # 同時実行性を 5 に設定します。
        leave_parts_on_error=True  # エラーが発生した場合にアップロードされたパートを保持します。
    )

    # メソッドを呼び出して、ファイルアップロード操作を実行します。
    result = uploader.upload_file(
        oss.PutObjectRequest(
            bucket=args.bucket,  # ターゲットバケットを指定します。
            key=args.key,        # OSS 内のファイル名を指定します。
        ),
        filepath=args.file_path  # ローカルファイルの場所を指定します。
    )

    # アップロード結果に関する情報 (ステータスコード、リクエスト ID、Content-MD5 など) を出力します。
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' content md5: {result.headers.get("Content-MD5")},'
          f' etag: {result.etag},'
          f' hash crc64: {result.hash_crc64},'
          f' version id: {result.version_id},'
          f' server time: {result.headers.get("x-oss-server-time")},'
          )

# このスクリプトが直接実行された場合は、main 関数を呼び出して処理ロジックを開始します。
if __name__ == "__main__":
    main()  # スクリプトのエントリポイント。プログラムフローはここから始まります。

アップロードマネージャーを使用してアップロードコールバックを構成する

ファイルのアップロード後にアプリケーションサーバーに通知する場合は、次のサンプルコードを使用します。

import argparse
import base64
import alibabacloud_oss_v2 as oss

# コマンドライン引数パーサーを作成し、スクリプトの目的 (ファイルアップロードのサンプル) を記述します。
parser = argparse.ArgumentParser(description="ファイルアップロードのサンプル")

# --region コマンドライン引数を追加します。これは、バケットが配置されているリージョンを指定する必須パラメーターです。
parser.add_argument('--region', help='バケットが配置されているリージョン。', required=True)
# --bucket コマンドライン引数を追加します。これは、ファイルをアップロードするバケットの名前を指定する必須パラメーターです。
parser.add_argument('--bucket', help='バケットの名前。', required=True)
# --endpoint コマンドライン引数を追加します。これは、他のサービスが OSS にアクセスするために使用できるドメイン名を指定するオプションパラメーターです。
parser.add_argument('--endpoint', help='他のサービスが OSS にアクセスするために使用できるドメイン名')
# --key コマンドライン引数を追加します。これは、OSS 内のオブジェクト (ファイル) のキーを指定する必須パラメーターです。
parser.add_argument('--key', help='オブジェクトの名前。', required=True)
# --file_path コマンドライン引数を追加します。これは、アップロードするローカルファイルのパスを指定する必須パラメーターです。
parser.add_argument('--file_path', help='アップロードファイルのパス。', required=True)


def main():
    # コマンドライン引数を解析して、ユーザーが指定した値を取得します。
    args = parser.parse_args()

    # ID 検証のために、環境変数から OSS にアクセスするために必要な認証情報をロードします。
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # SDK のデフォルト構成を使用して構成オブジェクトを作成し、資格情報プロバイダーを設定します。
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # ユーザーが指定したコマンドライン引数に基づいて、構成オブジェクトのリージョン プロパティを設定します。
    cfg.region = args.region

    # カスタムエンドポイントが指定されている場合は、構成オブジェクトの endpoint プロパティを更新します。
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # 前述の構成を使用して OSS クライアントを初期化し、OSS との対話の準備をします。
    client = oss.Client(cfg)

    # ファイルアップロード用のアップローダーオブジェクトを作成します。
    uploader = client.uploader()

    # Webhook アドレスを定義します。
    call_back_url = "http://www.example.com/callback" # コールバック URL を設定します。
    # コールバックパラメーター (callback) を構築します。Webhook アドレスとコールバックのリクエスト本文を指定し、Base64 でエンコードします。
    callback=base64.b64encode(str('{\"callbackUrl\":\"' + call_back_url + '\",\"callbackBody\":\"bucket=${bucket}&object=${object}&my_var_1=${x:var1}&my_var_2=${x:var2}\"}').encode()).decode() # コールバックパラメーターを設定します。
    # カスタム変数 (callback-var) を構築し、Base64 でエンコードします。
    callback_var=base64.b64encode('{\"x:var1\":\"value1\",\"x:var2\":\"value2\"}'.encode()).decode() # コールバック変数を設定します。

    # メソッドを呼び出して、ファイルアップロード操作を実行します。
    result = uploader.upload_file(
        oss.PutObjectRequest(
            bucket=args.bucket,  # ターゲットバケットを指定します。
            key=args.key,        # OSS 内のファイル名を指定します。
            callback=callback, # コールバックパラメーターを設定します。
            callback_var=callback_var, # コールバック変数を設定します。
        ),
        filepath=args.file_path,  # ローカルファイルの場所を指定します。
    )

    # アップロード結果に関する情報 (ステータスコード、リクエスト ID、Content-MD5 など) を出力します。
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' content md5: {result.headers.get("Content-MD5")},'
          f' etag: {result.etag},'
          f' hash crc64: {result.hash_crc64},'
          f' version id: {result.version_id},'
          f' server time: {result.headers.get("x-oss-server-time")},'
          )

# このスクリプトが直接実行された場合は、main 関数を呼び出して処理ロジックを開始します。
if __name__ == "__main__":
    main()  # スクリプトのエントリポイント。プログラムフローはここから始まります。

Object Storage Service:ファイルアップロードマネージャ (Python SDK V2)