Cara mengunggah file menggunakan Python SDK V2 - Object Storage Service

Topik ini menjelaskan cara menggunakan metode unggah sederhana untuk mengunggah satu file ke OSS. Metode ini sederhana dan cocok untuk pengunggahan file cepat ke penyimpanan cloud.

Penting

Kode contoh dalam topik ini menggunakan ID Wilayah cn-hangzhou untuk China (Hangzhou) sebagai contoh. Secara default, titik akhir publik digunakan. Jika Anda ingin mengakses OSS dari produk Alibaba Cloud lainnya di wilayah yang sama, Anda harus menggunakan titik akhir internal. Untuk informasi lebih lanjut tentang pemetaan antara Wilayah OSS dan titik akhir, lihat Wilayah dan Titik Akhir OSS.

Izin

Secara default, Akun Alibaba Cloud memiliki izin penuh. Pengguna RAM atau Peran RAM di bawah Akun Alibaba Cloud tidak memiliki izin apa pun secara default. Akun Alibaba Cloud atau administrator akun harus memberikan izin operasi melalui Kebijakan RAM atau Kebijakan Bucket.

API	Aksi	Definisi
PutObject	`oss:PutObject`	Mengunggah sebuah objek.
	`oss:PutObjectTagging`	Saat mengunggah sebuah objek, jika Anda menentukan tag objek melalui `x-oss-tagging`, izin ini diperlukan.
	`kms:GenerateDataKey`	Saat mengunggah sebuah objek, jika metadata objek berisi `X-Oss-Server-Side-Encryption: KMS`, kedua izin ini diperlukan.
	`kms:Decrypt`

Definisi metode

put_object(request: PutObjectRequest, **kwargs) → PutObjectResult

Parameter permintaan

Parameter	Tipe	Deskripsi
request	PutObjectRequest	Menentukan parameter permintaan, seperti daftar kontrol akses (ACL) objek, apakah melarang penimpaan (ForbidOverwrite), dan metadata kustom (Metadata). Untuk informasi lebih lanjut, lihat PutObjectRequest

Nilai kembali

Tipe	Deskripsi
PutObjectResult	Nilai kembali. Untuk informasi lebih lanjut, lihat PutObjectResult

Untuk definisi lengkap dari metode unggah sederhana, lihat put_object.

Unggah file lokal

Saat Anda mengunggah sebuah objek, jika objek dengan nama yang sama sudah ada di bucket dan Anda memiliki izin yang diperlukan, objek baru akan menimpa yang sudah ada.

Parameter umum untuk mengunggah file adalah sebagai berikut:

Parameter	Deskripsi
bucket_name	Nama bucket. Konvensi penamaan untuk bucket adalah sebagai berikut: Hanya dapat berisi huruf kecil, angka, dan tanda hubung (-). Harus dimulai dan diakhiri dengan huruf kecil atau angka. Panjangnya harus antara 3 dan 63 karakter.
object_name	Jalur lengkap objek. Jalur lengkap tidak dapat berisi nama bucket. Konvensi penamaan untuk objek adalah sebagai berikut: Harus dikodekan dalam format UTF-8. Panjangnya harus antara 1 dan 1.023 karakter. Tidak dapat dimulai dengan garis miring (/) atau backslash (\).

Anda dapat menggunakan metode put_object_from_file untuk mengunggah file lokal ke bucket tujuan.

import argparse
import alibabacloud_oss_v2 as oss

# Buat parser argumen baris perintah.
parser = argparse.ArgumentParser(description="put object from file sample")

# Tambahkan argumen baris perintah --region, yang menentukan wilayah tempat bucket berada. Argumen ini wajib.
parser.add_argument('--region', help='Wilayah tempat bucket berada.', required=True)

# Tambahkan argumen baris perintah --bucket, yang menentukan nama bucket. Argumen ini wajib.
parser.add_argument('--bucket', help='Nama bucket.', required=True)

# Tambahkan argumen baris perintah --endpoint, yang menentukan nama domain yang layanan lain gunakan untuk mengakses OSS. Argumen ini opsional.
parser.add_argument('--endpoint', help='Nama domain yang layanan lain gunakan untuk mengakses OSS')

# Tambahkan argumen baris perintah --key, yang menentukan nama objek. Argumen ini wajib.
parser.add_argument('--key', help='Nama objek.', required=True)

# Tambahkan argumen baris perintah --file_path, yang menentukan jalur file lokal untuk diunggah. Argumen ini wajib.
parser.add_argument('--file_path', help='Jalur file untuk diunggah.', required=True)

def main():
    # Parsing argumen baris perintah.
    args = parser.parse_args()

    # Muat kredensial dari variabel lingkungan untuk verifikasi identitas.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Muat konfigurasi default dari kit pengembangan perangkat lunak (SDK) dan atur penyedia kredensial.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Atur wilayah dalam konfigurasi.
    cfg.region = args.region

    # Jika argumen endpoint disediakan, atur endpoint dalam konfigurasi.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Buat klien OSS menggunakan konfigurasi yang ditentukan.
    client = oss.Client(cfg)

    # Eksekusi permintaan untuk mengunggah objek langsung dari file.
    # Tentukan nama bucket, nama objek, dan jalur file lokal.
    result = client.put_object_from_file(
        oss.PutObjectRequest(
            bucket=args.bucket,  # Nama bucket.
            key=args.key         # Nama objek.
        ),
        args.file_path          # Jalur file lokal.
    )

    # Cetak informasi hasil permintaan, termasuk kode status, ID permintaan, Content-MD5, ETag, hash CRC64 64-bit, ID versi, dan waktu respons server.
    print(f'kode status: {result.status_code},'
          f' ID permintaan: {result.request_id},'
          f' content md5: {result.content_md5},'
          f' etag: {result.etag},'
          f' hash crc64: {result.hash_crc64},'
          f' ID versi: {result.version_id},'
          f' waktu server: {result.headers.get("x-oss-server-time")},'
    )

# Titik masuk skrip. Fungsi utama dipanggil saat file dijalankan langsung.
if __name__ == "__main__":
    main()

Saat Anda menggunakan metode put_object untuk mengunggah file lokal, Anda harus membuka file dalam mode 'rb'. Ini memastikan bahwa byte stream asli diunggah bukan konten teks, yang mencegah kegagalan Pemeriksaan Redundansi Siklik (CRC).

import argparse
import alibabacloud_oss_v2 as oss

# Buat parser argumen baris perintah.
parser = argparse.ArgumentParser(description="put object from file sample")

# Tambahkan argumen baris perintah --region, yang menentukan wilayah tempat bucket berada. Argumen ini wajib.
parser.add_argument('--region', help='Wilayah tempat bucket berada.', required=True)

# Tambahkan argumen baris perintah --bucket, yang menentukan nama bucket. Argumen ini wajib.
parser.add_argument('--bucket', help='Nama bucket.', required=True)

# Tambahkan argumen baris perintah --endpoint, yang menentukan nama domain yang layanan lain gunakan untuk mengakses OSS. Argumen ini opsional.
parser.add_argument('--endpoint', help='Nama domain yang layanan lain gunakan untuk mengakses OSS')

# Tambahkan argumen baris perintah --key, yang menentukan nama objek. Argumen ini wajib.
parser.add_argument('--key', help='Nama objek.', required=True)

def main():
    # Parsing argumen baris perintah.
    args = parser.parse_args()

    # Muat kredensial dari variabel lingkungan untuk verifikasi identitas.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Muat konfigurasi default dari SDK dan atur penyedia kredensial.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Atur wilayah dalam konfigurasi.
    cfg.region = args.region

    # Jika argumen endpoint disediakan, atur endpoint dalam konfigurasi.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Buat klien OSS menggunakan konfigurasi yang ditentukan.
    client = oss.Client(cfg)

    # Eksekusi permintaan untuk mengunggah objek langsung dari file lokal.
    # Tentukan nama bucket, nama objek, dan jalur file lokal.
    with open('your-test-file.md', 'rb') as f:
    result = client.put_object(
        oss.PutObjectRequest(
            bucket=args.bucket,  # Nama bucket.
            key=args.key,        # Nama objek.
            body=f.read()        # Baca isi file.
        )
    )

    # Cetak informasi hasil permintaan, termasuk kode status, ID permintaan, Content-MD5, ETag, hash CRC64, ID versi, dan waktu respons server.
    print(f'kode status: {result.status_code},'
          f' ID permintaan: {result.request_id},'
          f' content md5: {result.content_md5},'
          f' etag: {result.etag},'
          f' hash crc64: {result.hash_crc64},'
          f' ID versi: {result.version_id},'
          f' waktu server: {result.headers.get("x-oss-server-time")},'
    )

# Titik masuk skrip. Fungsi utama dipanggil saat file dijalankan langsung.
if __name__ == "__main__":
    main()

Skenario umum

Unggah string

Anda dapat menggunakan kode berikut untuk mengunggah string ke bucket tujuan.

import argparse
import alibabacloud_oss_v2 as oss

# Buat parser argumen baris perintah.
parser = argparse.ArgumentParser(description="put object sample")
# Tambahkan argumen baris perintah --region, yang menentukan wilayah tempat bucket berada. Argumen ini wajib.
parser.add_argument('--region', help='Wilayah tempat bucket berada.', required=True)
# Tambahkan argumen baris perintah --bucket, yang menentukan nama bucket. Argumen ini wajib.
parser.add_argument('--bucket', help='Nama bucket.', required=True)
# Tambahkan argumen baris perintah --endpoint, yang menentukan nama domain yang layanan lain gunakan untuk mengakses OSS. Argumen ini opsional.
parser.add_argument('--endpoint', help='Nama domain yang layanan lain gunakan untuk mengakses OSS')
# Tambahkan argumen baris perintah --key, yang menentukan nama objek. Argumen ini wajib.
parser.add_argument('--key', help='Nama objek.', required=True)

def main():
    args = parser.parse_args()  # Parsing argumen baris perintah.

    # Muat kredensial dari variabel lingkungan untuk verifikasi identitas.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Muat konfigurasi default dari SDK dan atur penyedia kredensial.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    # Atur wilayah dalam konfigurasi.
    cfg.region = args.region
    # Jika argumen endpoint disediakan, atur endpoint dalam konfigurasi.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Buat klien OSS menggunakan konfigurasi yang ditentukan.
    client = oss.Client(cfg)

    # Definisikan string untuk diunggah.
    text_string = "Hello, OSS!"
    data = text_string.encode('utf-8')  # Enkode string menjadi byte string UTF-8.

    # Eksekusi permintaan untuk mengunggah objek. Tentukan nama bucket, nama objek, dan konten data.
    result = client.put_object(oss.PutObjectRequest(
        bucket=args.bucket,
        key=args.key,
        body=data,
    ))

    # Cetak kode status, ID permintaan, Content-MD5, ETag, hash CRC64, dan ID versi dari hasil permintaan untuk memeriksa apakah permintaan berhasil.
    print(f'kode status: {result.status_code},'
          f' ID permintaan: {result.request_id},'
          f' content md5: {result.content_md5},'
          f' etag: {result.etag},'
          f' hash crc64: {result.hash_crc64},'
          f' ID versi: {result.version_id},'
    )

if __name__ == "__main__":
    main()  # Titik masuk skrip. Fungsi utama dipanggil saat file dijalankan langsung.

Unggah larik byte

import argparse
import alibabacloud_oss_v2 as oss

# Buat parser argumen baris perintah.
parser = argparse.ArgumentParser(description="put object sample")
# Tambahkan argumen baris perintah --region, yang menentukan wilayah tempat bucket berada. Argumen ini wajib.
parser.add_argument('--region', help='Wilayah tempat bucket berada.', required=True)
# Tambahkan argumen baris perintah --bucket, yang menentukan nama bucket. Argumen ini wajib.
parser.add_argument('--bucket', help='Nama bucket.', required=True)
# Tambahkan argumen baris perintah --endpoint, yang menentukan nama domain yang layanan lain gunakan untuk mengakses OSS. Argumen ini opsional.
parser.add_argument('--endpoint', help='Nama domain yang layanan lain gunakan untuk mengakses OSS')
# Tambahkan argumen baris perintah --key, yang menentukan nama objek. Argumen ini wajib.
parser.add_argument('--key', help='Nama objek.', required=True)

def main():
    args = parser.parse_args()  # Parsing argumen baris perintah.

    # Muat kredensial dari variabel lingkungan untuk verifikasi identitas.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Muat konfigurasi default dari SDK dan atur penyedia kredensial.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    # Atur wilayah dalam konfigurasi.
    cfg.region = args.region
    # Jika argumen endpoint disediakan, atur endpoint dalam konfigurasi.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Buat klien OSS menggunakan konfigurasi yang ditentukan.
    client = oss.Client(cfg)

    # Definisikan konten data untuk diunggah.
    data = b'hello world'

    # Eksekusi permintaan untuk mengunggah objek. Tentukan nama bucket, nama objek, dan konten data.
    result = client.put_object(oss.PutObjectRequest(
        bucket=args.bucket,
        key=args.key,
        body=data,
    ))

    # Cetak kode status, ID permintaan, Content-MD5, ETag, hash CRC64, dan ID versi dari hasil permintaan untuk memeriksa apakah permintaan berhasil.
    print(f'kode status: {result.status_code},'
          f' ID permintaan: {result.request_id},'
          f' content md5: {result.content_md5},'
          f' etag: {result.etag},'
          f' hash crc64: {result.hash_crc64},'
          f' ID versi: {result.version_id},'
    )

if __name__ == "__main__":
    main()  # Titik masuk skrip. Fungsi utama dipanggil saat file dijalankan langsung.

Unggah aliran jaringan

Anda dapat menggunakan kode berikut untuk mengunggah aliran jaringan ke bucket tujuan.

import argparse
import requests
import alibabacloud_oss_v2 as oss

# Buat parser argumen baris perintah.
parser = argparse.ArgumentParser(description="put object sample")
# Tambahkan argumen baris perintah --region, yang menentukan wilayah tempat bucket berada. Argumen ini wajib.
parser.add_argument('--region', help='Wilayah tempat bucket berada.', required=True)
# Tambahkan argumen baris perintah --bucket, yang menentukan nama bucket. Argumen ini wajib.
parser.add_argument('--bucket', help='Nama bucket.', required=True)
# Tambahkan argumen baris perintah --endpoint, yang menentukan nama domain yang layanan lain gunakan untuk mengakses OSS. Argumen ini opsional.
parser.add_argument('--endpoint', help='Nama domain yang layanan lain gunakan untuk mengakses OSS')
# Tambahkan argumen baris perintah --key, yang menentukan nama objek. Argumen ini wajib.
parser.add_argument('--key', help='Nama objek.', required=True)

def main():
    args = parser.parse_args()  # Parsing argumen baris perintah.

    # Muat kredensial dari variabel lingkungan untuk verifikasi identitas.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Muat konfigurasi default dari SDK dan atur penyedia kredensial.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    # Atur wilayah dalam konfigurasi.
    cfg.region = args.region
    # Jika argumen endpoint disediakan, atur endpoint dalam konfigurasi.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Buat klien OSS menggunakan konfigurasi yang ditentukan.
    client = oss.Client(cfg)

    # Kirim permintaan HTTP GET untuk mendapatkan konten respons.
    response = requests.get('http://www.aliyun.com')

    # Eksekusi permintaan untuk mengunggah objek. Tentukan nama bucket, nama objek, dan konten data.
    result = client.put_object(oss.PutObjectRequest(
        bucket=args.bucket,
        key=args.key,
        body=response.content,
    ))

    # Cetak kode status, ID permintaan, Content-MD5, ETag, hash CRC64, dan ID versi dari hasil permintaan untuk memeriksa apakah permintaan berhasil.
    print(f'kode status: {result.status_code},'
          f' ID permintaan: {result.request_id},'
          f' content md5: {result.content_md5},'
          f' etag: {result.etag},'
          f' hash crc64: {result.hash_crc64},'
          f' ID versi: {result.version_id},'
    )

if __name__ == "__main__":
    main()  # Titik masuk skrip. Fungsi utama dipanggil saat file dijalankan langsung.

Unggah file dan konfigurasikan callback

Kode sampel berikut menunjukkan cara memberi tahu server aplikasi setelah file diunggah.

import base64
import argparse
import alibabacloud_oss_v2 as oss

parser = argparse.ArgumentParser(description="put object sample")

# Tambahkan parameter yang diperlukan.
parser.add_argument('--region', help='Wilayah tempat bucket berada.', required=True)
parser.add_argument('--bucket', help='Nama bucket.', required=True)
parser.add_argument('--endpoint', help='Nama domain yang layanan lain gunakan untuk mengakses OSS')
parser.add_argument('--key', help='Nama objek.', required=True)
parser.add_argument('--call_back_url', help='Alamat server callback.', required=True)


def main():

    args = parser.parse_args()

    # Muat kredensial dari variabel lingkungan.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Konfigurasikan klien SDK.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Buat klien OSS.
    client = oss.Client(cfg)

    # Konten untuk diunggah (string).
    data = 'hello world'

    # Bangun parameter callback (callback): Tentukan alamat webhook dan badan permintaan callback, dan gunakan enkode Base64.
    callback=base64.b64encode(str('{\"callbackUrl\":\"' + args.call_back_url + '\",\"callbackBody\":\"bucket=${bucket}&object=${object}&my_var_1=${x:var1}&my_var_2=${x:var2}\"}').encode()).decode()
    # Bangun variabel kustom (callback-var) dan gunakan enkode Base64.
    callback_var=base64.b64encode('{\"x:var1\":\"value1\",\"x:var2\":\"value2\"}'.encode()).decode()

    # Mulai permintaan unggah yang mencakup parameter callback.
    result = client.put_object(oss.PutObjectRequest(
        bucket=args.bucket,
        key=args.key,
        body=data,
        callback=callback,
        callback_var=callback_var,
    ))
    # Cetak hasil yang dikembalikan, termasuk kode status dan ID permintaan.
    print(vars(result))


if __name__ == "__main__":
    main()

Unggah file dan tampilkan bilah kemajuan

Kode sampel berikut menunjukkan cara menggunakan bilah kemajuan untuk menampilkan kemajuan unggah file lokal.

import argparse
import alibabacloud_oss_v2 as oss

# Buat parser argumen baris perintah.
parser = argparse.ArgumentParser(description="put object sample")
# Tambahkan argumen baris perintah --region, yang menentukan wilayah tempat bucket berada. Argumen ini wajib.
parser.add_argument('--region', help='Wilayah tempat bucket berada.', required=True)
# Tambahkan argumen baris perintah --bucket, yang menentukan nama bucket. Argumen ini wajib.
parser.add_argument('--bucket', help='Nama bucket.', required=True)
# Tambahkan argumen baris perintah --endpoint, yang menentukan nama domain yang layanan lain gunakan untuk mengakses OSS. Argumen ini opsional.
parser.add_argument('--endpoint', help='Nama domain yang layanan lain gunakan untuk mengakses OSS')
# Tambahkan argumen baris perintah --key, yang menentukan nama objek. Argumen ini wajib.
parser.add_argument('--key', help='Nama objek.', required=True)

def main():
    args = parser.parse_args()  # Parsing argumen baris perintah.

    # Muat kredensial dari variabel lingkungan untuk verifikasi identitas.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Muat konfigurasi default dari SDK dan atur penyedia kredensial.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    # Atur wilayah dalam konfigurasi.
    cfg.region = args.region
    # Jika argumen endpoint disediakan, atur endpoint dalam konfigurasi.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Buat klien OSS menggunakan konfigurasi yang ditentukan.
    client = oss.Client(cfg)

    # Definisikan variabel kamus bernama progress_state untuk menyimpan status kemajuan unggah. Nilai awalnya adalah 0.
    progress_state = {'saved': 0}
    def _progress_fn(n, written, total):
        # Gunakan kamus untuk menyimpan jumlah byte tertulis kumulatif untuk menghindari penggunaan variabel global.
        progress_state['saved'] += n

        # Hitung persentase unggah saat ini. Bagi jumlah byte tertulis dengan jumlah byte total dan bulatkan hasilnya ke bawah.
        rate = int(100 * (float(written) / float(total)))

        # Cetak kemajuan unggah saat ini. \r menunjukkan kembali ke awal baris untuk mengimplementasikan refresh real-time di baris perintah.
        # end='' menunjukkan bahwa tidak ada baris baru yang ditambahkan, sehingga cetakan berikutnya menimpa baris saat ini.
        print(f'\rKemajuan unggah: {rate}% ', end='')

    # Eksekusi permintaan untuk mengunggah objek. Tentukan nama bucket, nama objek, dan konten data.
    result = client.put_object_from_file(oss.PutObjectRequest(
            bucket=args.bucket,
            key=args.key,
            progress_fn=_progress_fn,
        ),
        "/local/dir/example", # Tentukan jalur file lokal.
    )

    # Cetak kode status, ID permintaan, Content-MD5, ETag, hash CRC64, dan ID versi dari hasil permintaan untuk memeriksa apakah permintaan berhasil.
    print(f'kode status: {result.status_code},'
          f' ID permintaan: {result.request_id},'
          f' content md5: {result.content_md5},'
          f' etag: {result.etag},'
          f' hash crc64: {result.hash_crc64},'
          f' ID versi: {result.version_id},'
    )

if __name__ == "__main__":
    main()  # Titik masuk skrip. Fungsi utama dipanggil saat file dijalankan langsung.

Referensi

Untuk kode sampel lengkap unggah sederhana, lihat put_object.py.