読み取り専用のファイルライクアクセス (Python SDK V2) - Object Storage Service

このトピックでは、Python 2.0 向けの Object Storage Service (OSS) SDK が提供する File-Like メソッドを使用して、バケット内のオブジェクトにアクセスする方法について説明します。

使用上の注意

このトピックのサンプルコードでは、中国 (杭州) リージョン (cn-hangzhou) を例として使用します。デフォルトではパブリックエンドポイントが使用されます。同じリージョン内の他の Alibaba Cloud サービスから OSS にアクセスする場合は、内部エンドポイントを使用します。OSS リージョンとそれに対応するエンドポイントの詳細については、「OSS リージョンとエンドポイント」をご参照ください。
このトピックでは、環境変数から取得したアクセス認証情報を使用しています。アクセス認証情報の構成方法の詳細については、「アクセス認証情報を構成する」をご参照ください。
ファイルをダウンロードするには、oss:GetObject 権限が必要です。詳細については、「RAM ユーザーへのカスタム権限の付与」をご参照ください。

メソッド

OSS SDK for Python 2.0 が提供する File-Like メソッドを使用すると、ReadOnlyFile メソッドを使用してバケット内のオブジェクトにアクセスできます。

ReadOnlyFile メソッドは、シングルストリームモードとプリフェッチモードを提供します。並列タスク数を変更して読み取り速度を向上させることができます。
このインターフェイスには、接続切断を処理するための再接続メカニズムが組み込まれており、複雑なネットワーク環境での堅牢性が向上します。

class ReadOnlyFile:
    ...


def open_file(self, bucket: str, key: str, version_id: Optional[str] = None, request_payer: Optional[str] = None, **kwargs) -> ReadOnlyFile:
    ...

リクエストパラメーター

パラメーター	タイプ	説明
bucket	str	バケットの名前。
key	str	オブジェクトの名前。
version_id	str	指定したオブジェクトのバージョン番号。このパラメーターは、オブジェクトの複数のバージョンが存在する場合にのみ有効です。
request_payer	str	リクエスト元支払いモードが有効になっている場合、RequestPayer を requester に設定する必要があります。
**kwargs	Any	オプション。構成するオプション (Dictionary タイプ)。

kwargs のオプション

オプション	タイプ	説明
enable_prefetch	bool	プリフェッチモードを有効にするかどうかを指定します。デフォルトでは、プリフェッチモードは無効になっています。
prefetch_num	int	プリフェッチされるチャンクの数。デフォルト値：3。このオプションは、プリフェッチモードが有効になっている場合に有効です。
chunk_size	int	プリフェッチされる各チャンクのサイズ。デフォルト値：6。単位：MiB。このオプションは、プリフェッチモードが有効になっている場合に有効です。
prefetch_threshold	int	プリフェッチモードが有効になる前に順番に読み取られるバイト数。デフォルト値：20。単位：MiB。このオプションは、プリフェッチモードが有効になっている場合に有効です。
block_size	int	チャンクのサイズ。デフォルト値：なし。

レスポンスパラメーター

パラメーター	タイプ	説明
file	ReadOnlyFile	ReadOnlyFile インスタンス。

ReadOnlyFile の共通メソッド

メソッド	説明
close(self)	ファイルハンドルを閉じて、メモリやアクティブなソケットなどのリソースを解放します。
read(self, n=None)	データソースから長さ len(p) のバイトを読み取り、バイトを p に格納し、読み取られたバイト数と発生したエラーを返します。
seek(self, pos, whence=0)	次の読み取りまたは書き込みのオフセットを指定します。whence の有効な値：0：先頭。1：現在のオフセット。2：末尾。
Stat() (os.FileInfo, error)	オブジェクトサイズ、最終更新時刻、メタデータなどのオブジェクト情報をクエリします。

重要

注：プリフェッチモードが有効になっていて、複数の順序外れ読み取りが発生した場合、シングルストリームモードが自動的に使用されます。

例

シングルストリームモードを使用してオブジェクト全体を読み取る

import argparse
import alibabacloud_oss_v2 as oss

# コマンドラインから引数を解析するためのコマンドラインパラメーターパーサーを作成します。
parser = argparse.ArgumentParser(description="open file sample")

# (必須) リージョンパラメーターを指定します。これは、バケットが配置されているリージョンを指定します。
parser.add_argument('--region', help='バケットが配置されているリージョン。', required=True)

# (必須) --bucket パラメーターを指定します。これは、バケットの名前を指定します。
parser.add_argument('--bucket', help='バケットの名前。', required=True)

# (オプション) --endpoint パラメーターを指定します。これは、他のサービスが OSS にアクセスするために使用できるエンドポイントを指定します。
parser.add_argument('--endpoint', help='他のサービスが OSS にアクセスするために使用できるドメイン名')

# (必須) --key パラメーターを指定します。これは、オブジェクトの名前を指定します。
parser.add_argument('--key', help='オブジェクトの名前。', required=True)


def main():
    # コマンドラインパラメーターを解析します。
    args = parser.parse_args()

    // 環境変数からアクセス認証情報 (AccessKey ID と AccessKey シークレット) を取得します。
    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

    # 前述の構成を使用して、OSSClient インスタンスを初期化します。
    client = oss.Client(cfg)

    # open_file メソッドを使用して、バケット内のオブジェクトを開きます。
    result = client.open_file(
        bucket=args.bucket,           # バケットの名前。
        key=args.key,                # オブジェクトの名前。
    )

    # オブジェクトを表示し、データを読み取り、文字列形式にデコードします。
    print(f'content: {result.read().decode()}')

    # オブジェクトを閉じてリソースを解放します。
    result.close()


if __name__ == "__main__":
    main() # スクリプトが直接実行されたときに、スクリプトの main 関数にエントリポイントを指定します。
    main()

プリフェッチモードを使用してオブジェクト全体を読み取る

import argparse
import alibabacloud_oss_v2 as oss

# コマンドラインから引数を解析するためのコマンドラインパラメーターパーサーを作成します。
parser = argparse.ArgumentParser(description="open file sample")

# (必須) リージョンパラメーターを指定します。これは、バケットが配置されているリージョンを指定します。
parser.add_argument('--region', help='バケットが配置されているリージョン。', required=True)

# (必須) --bucket パラメーターを指定します。これは、バケットの名前を指定します。
parser.add_argument('--bucket', help='バケットの名前。', required=True)

# (オプション) --endpoint パラメーターを指定します。これは、他のサービスが OSS にアクセスするために使用できるエンドポイントを指定します。
parser.add_argument('--endpoint', help='他のサービスが OSS にアクセスするために使用できるドメイン名')

# (必須) --key パラメーターを指定します。これは、オブジェクトの名前を指定します。
parser.add_argument('--key', help='オブジェクトの名前。', required=True)


def main():
    # コマンドラインパラメーターを解析します。
    args = parser.parse_args()

    // 環境変数からアクセス認証情報 (AccessKey ID と AccessKey シークレット) を取得します。
    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

    # 前述の構成を使用して、OSSClient インスタンスを初期化します。
    client = oss.Client(cfg)

    # open_file メソッドを使用して、バケット内のオブジェクトを開きます。
    result = client.open_file(
        bucket=args.bucket,           # バケットの名前。
        key=args.key,                # オブジェクトの名前。
        enable_prefetch=True,        # プリフェッチモードを有効にするかどうかを指定します。デフォルト値：true。
   )

    # オブジェクトを表示し、データを読み取り、文字列形式にデコードします。
    print(f'content: {result.read().decode()}')

    # オブジェクトを閉じてリソースを解放します。
    result.close()


if __name__ == "__main__":
    main() # スクリプトが直接実行されたときに、スクリプトの main 関数にエントリポイントを指定します。
    main()

Seek メソッドを使用して特定の位置から残りのデータを読み取る

import argparse
import os
import io
import alibabacloud_oss_v2 as oss

# コマンドラインから引数を解析するためのコマンドラインパラメーターパーサーを作成します。
parser = argparse.ArgumentParser(description="open file sample")

# (必須) リージョンパラメーターを指定します。これは、バケットが配置されているリージョンを指定します。
parser.add_argument('--region', help='バケットが配置されているリージョン。', required=True)

# (必須) --bucket パラメーターを指定します。これは、バケットの名前を指定します。
parser.add_argument('--bucket', help='バケットの名前。', required=True)

# (オプション) --endpoint パラメーターを指定します。これは、他のサービスが OSS にアクセスするために使用できるエンドポイントを指定します。
parser.add_argument('--endpoint', help='他のサービスが OSS にアクセスするために使用できるドメイン名')

# (必須) --key パラメーターを指定します。これは、オブジェクトの名前を指定します。
parser.add_argument('--key', help='オブジェクトの名前。', required=True)


def main():
    # コマンドラインパラメーターを解析します。
    args = parser.parse_args()

    // 環境変数からアクセス認証情報 (AccessKey ID と AccessKey シークレット) を取得します。
    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

    # 前述の構成を使用して、OSSClient インスタンスを初期化します。
    client = oss.Client(cfg)

    // oss.ReadOnlyFile オブジェクトを初期化します。
    rf: oss.ReadOnlyFile = None

    # WITH ステートメントを使用してオブジェクトを開き、オブジェクトの読み取り操作が完了した後にリソースが自動的に閉じられるようにします。
    with client.open_file(args.bucket, args.key) as f:
        rf = f # オブジェクトを rf 変数に割り当てます。

        # ファイルポインターを指定した位置に移動します。この例では、ファイルポインターはオブジェクトの先頭に 1 バイトオフセットされています。
        f.seek(1, os.SEEK_SET)

        # オブジェクトの内容をメモリ内のバイトストリーム (BytesIO) に読み込みます。
        copied_stream = io.BytesIO(rf.read())

        # バイトストリームに書き込まれたデータの長さを表示します。
        print(f'written: {len(copied_stream.getvalue())}')

        # 読み取られた内容を表示します。バイトストリームは文字列形式にデコードされます。
        print(f'read: {copied_stream.getvalue()}')


if __name__ == "__main__":
    main() # スクリプトが直接実行されたときに、スクリプトの main 関数にエントリポイントを指定します。
    main()

Object Storage Service:読み取り専用のファイルライクアクセス (Python SDK V2)