Akses file-like hanya-baca (Python SDK V2) - Object Storage Service

Topik ini menjelaskan cara menggunakan metode File-Like yang disediakan oleh Object Storage Service (OSS) SDK for Python 2.0 untuk mengakses objek dalam sebuah bucket.

Catatan penggunaan

Kode contoh dalam topik ini menggunakan Wilayah China (Hangzhou) (cn-hangzhou) sebagai contoh. Titik akhir publik digunakan secara default. Jika Anda mengakses OSS dari layanan Alibaba Cloud lainnya di wilayah yang sama, gunakan titik akhir internal. Untuk informasi lebih lanjut tentang wilayah OSS dan titik akhir yang sesuai, lihat Wilayah dan Titik Akhir OSS.
Dalam topik ini, kredensial akses yang diperoleh dari variabel lingkungan digunakan. Untuk informasi lebih lanjut tentang cara mengonfigurasi kredensial akses, lihat Konfigurasikan Kredensial Akses.
Untuk mengunduh file, Anda harus memiliki izin oss:GetObject. Untuk informasi lebih lanjut, lihat Berikan Izin Kustom kepada Pengguna RAM.

Metode

Metode File-Like yang disediakan oleh OSS SDK untuk Python 2.0 memungkinkan Anda mengakses objek dalam bucket menggunakan metode ReadOnlyFile.

Metode ReadOnlyFile menyediakan mode aliran tunggal dan prafetch. Anda dapat menyesuaikan jumlah tugas paralel untuk meningkatkan kecepatan baca.
Antarmuka mencakup mekanisme rekoneksi bawaan untuk menangani pemutusan koneksi, yang meningkatkan ketahanan dalam lingkungan jaringan yang kompleks.

class ReadOnlyFile:
    ...


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

Parameter permintaan

Parameter	Tipe	Deskripsi
bucket	str	Nama bucket.
key	str	Nama objek.
version_id	str	Nomor versi objek yang ditentukan. Parameter ini valid hanya jika beberapa versi objek ada.
request_payer	str	Menentukan bahwa jika pay-by-requester diaktifkan, RequestPayer harus diatur ke requester.
**kwargs	Any	Opsional. Opsi yang ingin Anda konfigurasikan, yang bertipe Dictionary.

Opsi kwargs

Opsi	Tipe	Deskripsi
enable_prefetch	bool	Menentukan apakah akan mengaktifkan mode prafetch. Secara default, mode prafetch dinonaktifkan.
prefetch_num	int	Jumlah chunk yang diprefetch. Nilai default: 3. Opsi ini valid saat mode prafetch diaktifkan.
chunk_size	int	Ukuran setiap chunk yang diprefetch. Nilai default: 6. Unit: MiB. Opsi ini valid saat mode prafetch diaktifkan.
prefetch_threshold	int	Jumlah byte yang dibaca secara berurutan sebelum mode prafetch diaktifkan. Nilai default: 20. Unit: MiB. Opsi ini valid saat mode prafetch diaktifkan.
block_size	int	Ukuran sebuah chunk. Nilai default: Tidak ada.

Parameter respons

Parameter	Tipe	Deskripsi
file	ReadOnlyFile	Instance ReadOnlyFile.

Metode Umum ReadOnlyFile

Metode	Deskripsi
close(self)	Menutup handle file untuk melepaskan sumber daya seperti memori dan soket aktif.
read(self, n=None)	Membaca byte dengan panjang len(p) dari sumber data, menyimpan byte tersebut di p, dan mengembalikan jumlah byte yang dibaca serta kesalahan yang ditemui.
seek(self, pos, whence=0)	Menentukan offset untuk pembacaan atau penulisan berikutnya. Nilai valid untuk whence: 0: awal. 1: offset saat ini. 2: akhir.
Stat() (os.FileInfo, error)	Meminta informasi objek, termasuk ukuran objek, waktu modifikasi terakhir, dan metadata.

Penting

Catatan: Jika mode prafetch diaktifkan dan terjadi beberapa pembacaan tidak berurutan, mode aliran tunggal digunakan secara otomatis.

Contoh

Baca seluruh objek menggunakan mode aliran tunggal

import argparse
import alibabacloud_oss_v2 as oss

# Buat parser parameter baris perintah untuk mengurai argumen dari baris perintah.
parser = argparse.ArgumentParser(description="contoh membuka file")

# (Diperlukan) Tentukan parameter wilayah, yang menentukan wilayah tempat bucket berada. 
parser.add_argument('--region', help='Wilayah tempat bucket berada.', required=True)

# (Diperlukan) Tentukan parameter --bucket, yang menentukan nama bucket.
parser.add_argument('--bucket', help='Nama bucket.', required=True)

# (Opsional) Tentukan parameter --endpoint, yang menentukan titik akhir yang dapat digunakan layanan lain untuk mengakses OSS.
parser.add_argument('--endpoint', help='Nama domain yang dapat digunakan layanan lain untuk mengakses OSS')

# (Diperlukan) Tentukan parameter --key, yang menentukan nama objek.
parser.add_argument('--key', help='Nama objek.', required=True)


def main():
    # Menguraikan parameter baris perintah.
    args = parser.parse_args()

    // Dapatkan kredensial akses (AccessKey ID dan AccessKey secret) dari variabel lingkungan.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Muat konfigurasi default SDK.
    cfg = oss.config.load_default()

    # Tentukan penyedia kredensial.
    cfg.credentials_provider = credentials_provider

    # Tentukan wilayah tempat bucket berada.
    cfg.region = args.region

    # Jika titik akhir kustom diberikan, ubah parameter titik akhir.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Gunakan konfigurasi sebelumnya untuk menginisialisasi instance OSSClient.
    client = oss.Client(cfg)

    # Gunakan metode open_file untuk membuka objek dalam bucket.
    result = client.open_file(
        bucket=args.bucket,           # Nama bucket.
        key=args.key,                # Nama objek.
    )

    # Tampilkan objek, baca data, dan dekode ke format string.
    print(f'konten: {result.read().decode()}')

    # Menutup objek untuk melepaskan sumber daya.
    result.close()


if __name__ == "__main__":
    main() # Tentukan titik masuk dalam fungsi utama skrip saat skrip dijalankan langsung.
    main()

Baca seluruh objek menggunakan mode pra-ambil

import argparse
import alibabacloud_oss_v2 as oss

# Buat parser parameter baris perintah untuk mengurai argumen dari baris perintah.
parser = argparse.ArgumentParser(description="contoh membuka file")

# (Diperlukan) Tentukan parameter wilayah, yang menentukan wilayah tempat bucket berada. 
parser.add_argument('--region', help='Wilayah tempat bucket berada.', required=True)

# (Diperlukan) Tentukan parameter --bucket, yang menentukan nama bucket.
parser.add_argument('--bucket', help='Nama bucket.', required=True)

# (Opsional) Tentukan parameter --endpoint, yang menentukan titik akhir yang dapat digunakan layanan lain untuk mengakses OSS.
parser.add_argument('--endpoint', help='Nama domain yang dapat digunakan layanan lain untuk mengakses OSS')

# (Diperlukan) Tentukan parameter --key, yang menentukan nama objek.
parser.add_argument('--key', help='Nama objek.', required=True)


def main():
    # Menguraikan parameter baris perintah.
    args = parser.parse_args()

    // Dapatkan kredensial akses (AccessKey ID dan AccessKey secret) dari variabel lingkungan.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Muat konfigurasi default SDK.
    cfg = oss.config.load_default()

    # Tentukan penyedia kredensial.
    cfg.credentials_provider = credentials_provider

    # Tentukan wilayah tempat bucket berada.
    cfg.region = args.region

    # Jika titik akhir kustom diberikan, ubah parameter titik akhir.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Gunakan konfigurasi sebelumnya untuk menginisialisasi instance OSSClient.
    client = oss.Client(cfg)

    # Gunakan metode open_file untuk membuka objek dalam bucket.
    result = client.open_file(
        bucket=args.bucket,           # Nama bucket.
        key=args.key,                # Nama objek.
        enable_prefetch=True,        # Tentukan apakah akan mengaktifkan mode prafetch. Nilai default: true.
   )

    # Tampilkan objek, baca data, dan dekode ke format string.
    print(f'konten: {result.read().decode()}')

    # Menutup objek untuk melepaskan sumber daya.
    result.close()


if __name__ == "__main__":
    main() # Tentukan titik masuk dalam fungsi utama skrip saat skrip dijalankan langsung.
    main()

Baca data tersisa dari posisi tertentu menggunakan metode Seek

import argparse
import os
import io
import alibabacloud_oss_v2 as oss

# Buat parser parameter baris perintah untuk mengurai argumen dari baris perintah.
parser = argparse.ArgumentParser(description="contoh membuka file")

# (Diperlukan) Tentukan parameter wilayah, yang menentukan wilayah tempat bucket berada. 
parser.add_argument('--region', help='Wilayah tempat bucket berada.', required=True)

# (Diperlukan) Tentukan parameter --bucket, yang menentukan nama bucket.
parser.add_argument('--bucket', help='Nama bucket.', required=True)

# (Opsional) Tentukan parameter --endpoint, yang menentukan titik akhir yang dapat digunakan layanan lain untuk mengakses OSS.
parser.add_argument('--endpoint', help='Nama domain yang dapat digunakan layanan lain untuk mengakses OSS')

# (Diperlukan) Tentukan parameter --key, yang menentukan nama objek.
parser.add_argument('--key', help='Nama objek.', required=True)


def main():
    # Menguraikan parameter baris perintah.
    args = parser.parse_args()

    // Dapatkan kredensial akses (AccessKey ID dan AccessKey secret) dari variabel lingkungan.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Muat konfigurasi default SDK.
    cfg = oss.config.load_default()

    # Tentukan penyedia kredensial.
    cfg.credentials_provider = credentials_provider

    # Tentukan wilayah tempat bucket berada.
    cfg.region = args.region

    # Jika titik akhir kustom diberikan, ubah parameter titik akhir.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Gunakan konfigurasi sebelumnya untuk menginisialisasi instance OSSClient.
    client = oss.Client(cfg)

    // Inisialisasi objek oss.ReadOnlyFile.
    rf: oss.ReadOnlyFile = None

    # Gunakan pernyataan WITH untuk membuka objek dan pastikan sumber daya ditutup secara otomatis setelah operasi pembacaan objek selesai.
    with client.open_file(args.bucket, args.key) as f:
        rf = f # Tetapkan objek ke variabel rf.

        # Pindahkan pointer file ke posisi yang ditentukan. Dalam contoh ini, pointer file adalah 1 byte offset dari awal objek.
        f.seek(1, os.SEEK_SET)

        # Baca konten objek ke aliran byte (BytesIO) di memori.
        copied_stream = io.BytesIO(rf.read())

        # Tampilkan panjang data yang ditulis ke aliran byte.
        print(f'ditulis: {len(copied_stream.getvalue())}')

        # Tampilkan konten yang dibaca. Aliran byte didekode ke format string.
        print(f'dibaca: {copied_stream.getvalue()}')


if __name__ == "__main__":
    main() # Tentukan titik masuk dalam fungsi utama skrip saat skrip dijalankan langsung.
    main()

Referensi

Untuk informasi lebih lanjut tentang File-Like, kunjungi File-Like.