Cara mengunduh file menggunakan OSS SDK untuk Go V2 - Object Storage Service

Topik ini menjelaskan cara mengunduh file menggunakan modul Pengunduh, sebuah fitur baru di Go SDK V2.

Catatan penggunaan

Kode contoh dalam topik ini menggunakan ID Wilayah cn-hangzhou dari Wilayah (Hangzhou) Tiongkok. Secara default, Titik akhir publik digunakan. Jika Anda ingin mengakses OSS dari produk Alibaba Cloud lainnya di wilayah yang sama, gunakan Titik akhir internal. Untuk informasi lebih lanjut tentang pemetaan antara wilayah OSS dan titik akhir, lihat Wilayah dan Titik Akhir.
Contoh-contoh dalam topik ini membaca kredensial akses dari variabel lingkungan. 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 Lampirkan Kebijakan Kustom ke Pengguna RAM.

Definisi metode

Fitur Pengunduh

Pengunduh adalah fitur baru di Go SDK V2 yang menyediakan operasi unduhan universal. Fitur ini mengabstraksi detail implementasi dari operasi tingkat bawah untuk memberikan cara yang nyaman dalam mengunduh file.

Pengunduh menggunakan Unduhan rentang untuk secara otomatis membagi file menjadi bagian-bagian yang lebih kecil dan mengunduh bagian-bagian tersebut secara bersamaan guna meningkatkan kinerja unduhan.
Pengunduh juga menyediakan fitur unduhan yang dapat dilanjutkan. Selama proses unduhan, status bagian yang telah selesai dicatat. Jika pengunduhan file gagal karena masalah seperti gangguan jaringan atau keluar program yang tidak terduga, Anda dapat melanjutkan unduhan dari catatan breakpoint.

Metode umum dari Pengunduh adalah sebagai berikut:

type Downloader struct {
  ...
}

// Membuat pengunduh baru.
func (c *Client) NewDownloader(optFns ...func(*DownloaderOptions)) *Downloader

// Mengunduh file.
func (d *Downloader) DownloadFile(ctx context.Context, request *GetObjectRequest, filePath string, optFns ...func(*DownloaderOptions)) (result *DownloadResult, err error)

Parameter permintaan

Parameter	Tipe	Deskripsi
ctx	context.Context	Konteks permintaan. Anda dapat menggunakan parameter ini untuk menetapkan periode waktu total untuk permintaan.
request	*GetObjectRequest	Parameter permintaan untuk Operasi API tertentu. Untuk informasi lebih lanjut, lihat GetObjectRequest.
filePath	string	Path file lokal.
optFns	...func(*DownloaderOptions)	(Opsional) Opsi konfigurasi.

Tabel berikut menjelaskan parameter umum dari DownloaderOption.

Parameter	Tipe	Deskripsi
PartSize	int64	Ukuran bagian. Nilai default adalah 6 MiB.
ParallelNum	int	Jumlah tugas unduhan bersamaan. Nilai default adalah 3. Parameter ini menentukan batas konkurensi untuk satu panggilan, bukan batas konkurensi global.
EnableCheckpoint	bool	Menentukan apakah akan mencatat informasi unduhan yang dapat dilanjutkan. Secara default, fitur ini dinonaktifkan.
CheckpointDir	string	Path tempat file rekaman disimpan. Contoh: /local/dir/. Parameter ini berlaku hanya ketika EnableCheckpoint diatur ke true.
VerifyData	bool	Menentukan apakah akan memverifikasi nilai CRC-64 dari data yang diunduh saat unduhan dilanjutkan. Secara default, nilai CRC-64 tidak diverifikasi. Parameter ini berlaku hanya ketika EnableCheckpoint diatur ke true.
UseTempFile	bool	Menentukan apakah akan menggunakan file sementara untuk unduhan. Secara default, file sementara digunakan. File pertama kali diunduh ke file sementara. Setelah unduhan berhasil, file sementara diubah namanya menjadi file objek.

Saat membuat instance Pengunduh, Anda dapat menentukan opsi konfigurasi untuk menyesuaikan perilaku unduhan defaultnya. Anda juga dapat menentukan opsi konfigurasi untuk setiap operasi unduhan guna menyesuaikan perilaku untuk unduhan tertentu.

Atur parameter konfigurasi untuk Pengunduh:

d := client.NewDownloader(func(do *oss.DownloaderOptions) {
  do.PartSize = 10 * 1024 * 1024
})

Atur parameter konfigurasi untuk setiap permintaan unduhan:

request := &oss.GetObjectRequest{Bucket: oss.Ptr("bucket"), Key: oss.Ptr("key")}
d.DownloadFile(context.TODO(), request, "/local/dir/example", func(do *oss.DownloaderOptions) {
  do.PartSize = 10 * 1024 * 1024
})

Kode contoh

Anda dapat menggunakan kode berikut untuk mengunduh file dari bucket ke perangkat lokal.

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Tentukan variabel global.
var (
	region     string // Wilayah penyimpanan.
	bucketName string // Nama bucket.
	objectName string // Nama objek.
)

// Fungsi init digunakan untuk menginisialisasi parameter baris perintah.
func init() {
	flag.StringVar(&region, "region", "", "Wilayah tempat bucket berada.")
	flag.StringVar(&bucketName, "bucket", "", "Nama bucket.")
	flag.StringVar(&objectName, "src-object", "", "Nama objek sumber.")
}

func main() {
	// Parsing parameter baris perintah.
	flag.Parse()

	// Periksa apakah nama bucket kosong.
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parameter tidak valid, nama bucket diperlukan")
	}

	// Periksa apakah wilayah kosong.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parameter tidak valid, wilayah diperlukan")
	}

	// Periksa apakah nama objek sumber kosong.
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parameter tidak valid, nama objek sumber diperlukan")
	}

	// Konfigurasikan klien OSS.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Buat klien OSS.
	client := oss.NewClient(cfg)

	// Buat pengunduh.
	d := client.NewDownloader()

	// Bangun permintaan untuk mendapatkan objek.
	request := &oss.GetObjectRequest{
		Bucket: oss.Ptr(bucketName), // Nama bucket.
		Key:    oss.Ptr(objectName), // Nama objek.
	}

	// Tentukan path file lokal.
	localFile := "local-file"

	// Jalankan permintaan untuk mengunduh file.
	result, err := d.DownloadFile(context.TODO(), request, localFile)
	if err != nil {
		log.Fatalf("gagal mengunduh file %v", err)
	}

	// Cetak pesan sukses.
	log.Printf("unduh file %s ke local-file berhasil, ukuran: %d", objectName, result.Written)
}

Skenario

Gunakan pengunduh untuk menetapkan ukuran bagian dan konkurensi

Kode berikut menunjukkan cara menetapkan ukuran bagian dan konkurensi menggunakan parameter DownloaderOptions.

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Tentukan variabel global.
var (
	region     string // Wilayah penyimpanan.
	bucketName string // Nama bucket.
	objectName string // Nama objek.
)

// Fungsi init digunakan untuk menginisialisasi parameter baris perintah.
func init() {
	flag.StringVar(&region, "region", "", "Wilayah tempat bucket berada.")
	flag.StringVar(&bucketName, "bucket", "", "Nama bucket.")
	flag.StringVar(&objectName, "src-object", "", "Nama objek sumber.")
}

func main() {
	// Parsing parameter baris perintah.
	flag.Parse()

	// Periksa apakah nama bucket kosong.
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parameter tidak valid, nama bucket diperlukan")
	}

	// Periksa apakah wilayah kosong.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parameter tidak valid, wilayah diperlukan")
	}

	// Periksa apakah nama objek sumber kosong.
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parameter tidak valid, nama objek sumber diperlukan")
	}

	// Konfigurasikan klien OSS.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Buat klien OSS.
	client := oss.NewClient(cfg)

	// Buat pengunduh.
	d := client.NewDownloader()

	// Bangun permintaan untuk mendapatkan objek.
	request := &oss.GetObjectRequest{
		Bucket: oss.Ptr(bucketName), // Nama bucket.
		Key:    oss.Ptr(objectName), // Nama objek.
	}

	// Tentukan path file lokal.
	localFile := "local-file"

	// Atur parameter konfigurasi untuk pengunduh.
	downloaderOptions := func(do *oss.DownloaderOptions) {
		do.PartSize = 20 * 1024 * 1024 // Tentukan ukuran bagian sebagai 20 MiB.
		do.ParallelNum = 6            // Tentukan jumlah tugas unduhan bersamaan sebagai 6.
	}

	// Jalankan permintaan untuk mengunduh file.
	result, err := d.DownloadFile(context.TODO(), request, localFile, downloaderOptions)
	if err != nil {
		log.Fatalf("gagal mengunduh file %v", err)
	}

	// Cetak pesan sukses.
	log.Printf("unduh file %s ke local-file berhasil, ukuran: %d", objectName, result.Written)
}

Gunakan pengunduh untuk mengaktifkan fitur unduhan yang dapat dilanjutkan

Kode berikut menunjukkan cara mengaktifkan fitur unduhan yang dapat dilanjutkan menggunakan parameter DownloaderOptions.

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Tentukan variabel global.
var (
	region     string // Wilayah penyimpanan.
	bucketName string // Nama bucket.
	objectName string // Nama objek.
)

// Fungsi init digunakan untuk menginisialisasi parameter baris perintah.
func init() {
	flag.StringVar(&region, "region", "", "Wilayah tempat bucket berada.")
	flag.StringVar(&bucketName, "bucket", "", "Nama bucket.")
	flag.StringVar(&objectName, "src-object", "", "Nama objek sumber.")
}

func main() {
	// Parsing parameter baris perintah.
	flag.Parse()

	// Periksa apakah nama bucket kosong.
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parameter tidak valid, nama bucket diperlukan")
	}

	// Periksa apakah wilayah kosong.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parameter tidak valid, wilayah diperlukan")
	}

	// Periksa apakah nama objek sumber kosong.
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parameter tidak valid, nama objek sumber diperlukan")
	}

	// Konfigurasikan klien OSS.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Buat klien OSS.
	client := oss.NewClient(cfg)

	// Buat pengunduh.
	d := client.NewDownloader()

	// Bangun permintaan untuk mendapatkan objek.
	request := &oss.GetObjectRequest{
		Bucket: oss.Ptr(bucketName), // Nama bucket.
		Key:    oss.Ptr(objectName), // Nama objek.
	}

	// Tentukan path file lokal.
	localFile := "local-file"

	// Atur opsi pengunduh.
	downloaderOptions := func(do *oss.DownloaderOptions) {
		do.EnableCheckpoint = true        // Aktifkan pencatatan informasi unduhan yang dapat dilanjutkan.
		do.CheckpointDir = "./checkpoint" // Tentukan direktori tempat informasi unduhan yang dapat dilanjutkan disimpan.
		do.UseTempFile = true             // Gunakan file sementara untuk unduhan.
	}

	// Jalankan permintaan untuk mengunduh file.
	result, err := d.DownloadFile(context.TODO(), request, localFile, downloaderOptions)
	if err != nil {
		log.Fatalf("gagal mengunduh file %v", err)
	}

	// Cetak pesan sukses.
	log.Printf("unduh file %s ke local-file berhasil, ukuran: %d", objectName, result.Written)
}

Referensi

Untuk informasi lebih lanjut tentang pengunduh, lihat Panduan Pengembang.
Untuk informasi lebih lanjut tentang operasi API untuk unduhan file, lihat DownloadFile.