Cara menggunakan OSS SDK untuk Go 2.0 mengunggah file lokal - Object Storage Service

Topik ini menjelaskan cara menggunakan modul Uploader dari Go SDK V2 untuk mengunggah file.

Catatan penggunaan

Kode contoh dalam topik ini menggunakan ID Wilayah cn-hangzhou untuk Wilayah China (Hangzhou). Secara default, titik akhir publik digunakan untuk mengakses sumber daya dalam bucket. Jika Anda ingin mengakses sumber daya bucket menggunakan layanan Alibaba Cloud lainnya di wilayah yang sama, gunakan titik akhir internal. Untuk informasi lebih lanjut tentang Wilayah dan titik akhir OSS, lihat Wilayah dan Titik Akhir.
Dalam topik ini, kredensial akses diambil dari variabel lingkungan. Untuk informasi lebih lanjut tentang cara mengonfigurasi kredensial akses, lihat Konfigurasikan Kredensial Akses.
Untuk mengunggah file besar, Anda harus memiliki izin oss:PutObject. Untuk informasi lebih lanjut, lihat Lampirkan Kebijakan Kustom ke Pengguna RAM.

Definisi metode

Pengenalan Uploader

Uploader di Go SDK V2 menyederhanakan unggahan file dengan menyediakan operasi tingkat tinggi yang menyembunyikan detail implementasi dasar.

Uploader menggunakan operasi unggah multi-bagian untuk membagi file besar atau aliran menjadi beberapa bagian kecil dan mengunggah bagian tersebut secara bersamaan guna meningkatkan performa.
Uploader juga menyediakan fitur unggah yang dapat dilanjutkan. Fitur ini mencatat status bagian yang telah selesai selama proses unggah. Jika unggahan file gagal karena masalah seperti gangguan jaringan atau pengecualian program, Anda dapat melanjutkan unggahan dari catatan titik henti berikutnya saat mencoba mengunggah file tersebut lagi.

Berikut adalah kode contoh yang menunjukkan cara menggunakan Uploader:

type Uploader struct {
  ...
}

// Membuat uploader baru.
func (c *Client) NewUploader(optFns ...func(*UploaderOptions)) *Uploader 

// Mengunggah aliran file.
func (u *Uploader) UploadFrom(ctx context.Context, request *PutObjectRequest, body io.Reader, optFns ...func(*UploaderOptions)) (*UploadResult, error)

// Mengunggah file lokal.
func (u *Uploader) UploadFile(ctx context.Context, request *PutObjectRequest, filePath string, optFns ...func(*UploaderOptions)) (*UploadResult, error)

Parameter permintaan

Parameter	Tipe	Deskripsi
ctx	context.Context	Konteks permintaan.
request	*PutObjectRequest	Parameter permintaan untuk mengunggah objek. Parameter ini sama dengan parameter operasi PutObject. Untuk informasi lebih lanjut, lihat PutObjectRequest.
body	io.Reader	Aliran untuk diunggah. Jika parameter body hanya mendukung tipe io.Reader, Anda harus menyangga data di memori sebelum dapat mengunggah data. Jika parameter body mendukung tipe io.Reader, io.Seeker, dan io.ReaderAt, Anda tidak perlu menyangga data di memori.
filePath	string	Path file lokal.
optFns	...func(*UploaderOptions)	(Opsional) Opsi konfigurasi.

Tabel berikut menjelaskan parameter umum dari UploaderOptions.

Parameter	Tipe	Deskripsi
PartSize	int64	Ukuran bagian. Nilai default adalah 6 MiB.
ParallelNum	int	Jumlah tugas unggah bersamaan. Nilai default adalah 3. Parameter ini menentukan batas konkurensi untuk satu panggilan, bukan batas konkurensi global.
LeavePartsOnError	bool	Menentukan apakah akan mempertahankan bagian yang diunggah ketika unggahan gagal. Secara default, bagian yang diunggah tidak dipertahankan.
EnableCheckpoint	bool	Menentukan apakah akan mengaktifkan fitur unggah yang dapat dilanjutkan. Secara default, fitur ini dinonaktifkan. Catatan Parameter EnableCheckpoint hanya valid untuk operasi UploadFile dan tidak didukung oleh operasi UploadFrom.
CheckpointDir	string	Path tempat file checkpoint disimpan. Contoh: /local/dir/. Parameter ini hanya valid ketika EnableCheckpoint diatur ke true.

Saat membuat instance Uploader menggunakan NewUploader, Anda dapat menentukan opsi konfigurasi untuk menyesuaikan perilaku unggah. Opsi ini dapat diatur untuk instance Uploader agar berlaku untuk semua unggahan, atau ditentukan untuk setiap operasi unggah individu.

Setel parameter konfigurasi untuk Uploader

u := client.NewUploader(func(uo *oss.UploaderOptions) {
  uo.PartSize = 10 * 1024 * 1024
})

Setel parameter konfigurasi untuk setiap permintaan unggah

request := &oss.PutObjectRequest{Bucket: oss.Ptr("bucket"), Key: oss.Ptr("key")}
result, err := u.UploadFile(context.TODO(), request, "/local/dir/example", func(uo *oss.UploaderOptions) {
  uo.PartSize = 10 * 1024 * 1024
})

Contoh

Anda dapat menggunakan kode contoh berikut untuk mengunggah file lokal ke bucket menggunakan Uploader.

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, "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 kosong.
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parameter tidak valid, nama objek sumber diperlukan")
	}

	// Muat konfigurasi default dan atur penyedia kredensial dan wilayah.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

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

	// Buat uploader.
	u := client.NewUploader()

	// Tentukan path file lokal. Anda perlu mengganti path dengan path file lokal dan nama file yang sebenarnya.
	localFile := "/Users/yourLocalPath/yourFileName"

	// Unggah file.
	result, err := u.UploadFile(context.TODO(),
		&oss.PutObjectRequest{
			Bucket: oss.Ptr(bucketName),
			Key:    oss.Ptr(objectName)},
		localFile)
	if err != nil {
		log.Fatalf("gagal mengunggah file %v", err)
	}

	// Cetak hasil unggah.
	log.Printf("hasil unggah file:%#v\n", result)
}

Skenario umum

Aktifkan fitur unggah yang dapat dilanjutkan menggunakan uploader

Anda dapat menggunakan kode contoh berikut untuk mengaktifkan fitur unggah yang dapat dilanjutkan dengan menyetel parameter konfigurasi Uploader.

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, "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 kosong.
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parameter tidak valid, nama objek sumber diperlukan")
	}

	// Muat konfigurasi default dan atur penyedia kredensial dan wilayah.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

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

	// Buat uploader dan aktifkan fitur unggah yang dapat dilanjutkan.
	u := client.NewUploader(func(uo *oss.UploaderOptions) {
		uo.CheckpointDir = "/Users/yourLocalPath/checkpoint/" // Tentukan path untuk menyimpan file checkpoint.
		uo.EnableCheckpoint = true        // Aktifkan unggah yang dapat dilanjutkan.
	})

	// Tentukan path file lokal. Anda perlu mengganti path dengan path file lokal dan nama file yang sebenarnya.
	localFile := "/Users/yourLocalPath/yourFileName"

	// Unggah file.
	result, err := u.UploadFile(context.TODO(),
		&oss.PutObjectRequest{
			Bucket: oss.Ptr(bucketName),
			Key:    oss.Ptr(objectName)},
		localFile)
	if err != nil {
		log.Fatalf("gagal mengunggah file %v", err)
	}

	// Cetak hasil unggah.
	log.Printf("hasil unggah file:%#v\n", result)
}

Gunakan uploader untuk mengunggah aliran file lokal

Anda dapat menggunakan kode contoh berikut untuk mengunggah aliran file lokal menggunakan Uploader.

package main

import (
	"context"
	"flag"
	"io"
	"log"
	"os"

	"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, "object", "", "Nama objek.")
}

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 kosong.
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parameter tidak valid, nama objek diperlukan")
	}

	// Muat konfigurasi default dan atur penyedia kredensial dan wilayah.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

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

	// Buat uploader.
	u := client.NewUploader()

	// Ganti "/Users/yourLocalPath/yourFileName" dengan path file dan nama file yang sebenarnya, buka file lokal, dan buat instance io.Reader.
	file, err := os.Open("/Users/yourLocalPath/yourFileName")
	if err != nil {
		log.Fatalf("gagal membuka file lokal %v", err)
	}
	defer file.Close()

	var r io.Reader = file

	// Unggah aliran file.
	result, err := u.UploadFrom(context.TODO(),
		&oss.PutObjectRequest{
			Bucket: oss.Ptr(bucketName),
			Key:    oss.Ptr(objectName),
		},
		r, // Aliran file untuk diunggah.
	)

	if err != nil {
		log.Fatalf("gagal mengunggah aliran file %v", err)
	}

	// Cetak hasil unggah aliran file.
	log.Printf("unggah aliran file, etag: %v\n", oss.ToString(result.ETag))
}

Gunakan uploader untuk menyetel ukuran bagian dan konkurensi

Anda dapat menggunakan kode contoh berikut untuk menyetel ukuran bagian dan konkurensi dengan menyetel parameter konfigurasi Uploader.

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, "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 kosong.
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parameter tidak valid, nama objek sumber diperlukan")
	}

	// Muat konfigurasi default dan atur penyedia kredensial dan wilayah.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

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

	// Buat uploader.
	u := client.NewUploader(func(uo *oss.UploaderOptions) {
		uo.PartSize = 1024 * 1024 * 5     // Setel ukuran bagian menjadi 5 MB.
		uo.ParallelNum = 5                // Setel jumlah unggah bersamaan menjadi 5.
	})

	// Tentukan path file lokal. Anda perlu mengganti path dengan path file lokal dan nama file yang sebenarnya.
	localFile := "/Users/yourLocalPath/yourFileName"

	// Unggah file.
	result, err := u.UploadFile(context.TODO(),
		&oss.PutObjectRequest{
			Bucket: oss.Ptr(bucketName),
			Key:    oss.Ptr(objectName)},
		localFile)
	if err != nil {
		log.Fatalf("gagal mengunggah file %v", err)
	}

	// Cetak hasil unggah.
	log.Printf("hasil unggah file:%#v\n", result)
}

Gunakan uploader untuk menyetel callback unggah

Gunakan kode contoh berikut untuk memberi tahu server aplikasi setelah file diunggah.

package main

import (
	"context"
	"encoding/base64"
	"encoding/json"
	"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, "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 kosong.
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parameter tidak valid, nama objek sumber diperlukan")
	}

	// Muat konfigurasi default dan atur penyedia kredensial dan wilayah.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

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

	// Buat uploader dan aktifkan fitur unggah yang dapat dilanjutkan.
	u := client.NewUploader(func(uo *oss.UploaderOptions) {
		uo.PartSize = 1024 * 1024 * 5 // Setel ukuran bagian menjadi 5 MB.
		uo.ParallelNum = 5            // Setel jumlah unggah bersamaan menjadi 5.
	})

	// Tentukan path file lokal. Anda perlu mengganti path dengan path file lokal Anda yang sebenarnya.
	localFile := "/Users/yourLocalPath/yourFileName"

	// Tentukan parameter callback.
	callbackMap := map[string]string{
		"callbackUrl":      "https://example.com:23450/callback",                                                        // Setel URL server callback. Contoh: https://example.com:23450.
		"callbackBody":     "bucket=${bucket}&object=${object}&size=${size}&my_var_1=${x:my_var1}&my_var_2=${x:my_var2}", // Setel badan permintaan callback.
		"callbackBodyType": "application/x-www-form-urlencoded",                                                          // Setel tipe badan permintaan callback.
	}

	// Konversi parameter callback ke JSON lalu lakukan pengkodean Base64 untuk melewatinya sebagai parameter callback.
	callbackStr, err := json.Marshal(callbackMap)
	if err != nil {
		log.Fatalf("gagal melakukan marshal pada peta callback: %v", err)
	}
	callbackBase64 := base64.StdEncoding.EncodeToString(callbackStr)

	// Tentukan parameter callback kustom.
	callbackVarMap := map[string]string{}
	callbackVarMap["x:my_var1"] = "ini adalah var 1"
	callbackVarMap["x:my_var2"] = "ini adalah var 2"

	// Konversi parameter callback ke JSON lalu lakukan pengkodean Base64 untuk melewatinya sebagai parameter callback.
	callbackVarStr, err := json.Marshal(callbackVarMap)
	if err != nil {
		log.Fatalf("gagal melakukan marshal pada var callback: %v", err)
	}
	callbackVarBase64 := base64.StdEncoding.EncodeToString(callbackVarStr)

	// Unggah file besar.
	result, err := u.UploadFile(context.TODO(),
		&oss.PutObjectRequest{
			Bucket:      oss.Ptr(bucketName),
			Key:         oss.Ptr(objectName),
			Callback:    oss.Ptr(callbackBase64),    // Tentukan parameter callback.
			CallbackVar: oss.Ptr(callbackVarBase64), // Tentukan parameter callback kustom.
		},
		localFile)
	if err != nil {
		log.Fatalf("gagal mengunggah file %v", err)
	}

	// Cetak hasil unggah.
	log.Printf("hasil unggah file:%#v\n", result)
}

Gunakan uploader untuk menampilkan grafik bilah kemajuan

package main

import (
	"context"
	"flag"
	"fmt"
	"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, "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 kosong.
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parameter tidak valid, nama objek sumber diperlukan")
	}

	// Muat konfigurasi default dan atur penyedia kredensial dan wilayah.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

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

	// Buat uploader.
	u := client.NewUploader(func(uo *oss.UploaderOptions) {
		uo.PartSize = 1024 * 1024 * 5 // Setel ukuran bagian menjadi 5 MB.
		uo.ParallelNum = 3            // Setel jumlah unggah bersamaan menjadi 3.
	})

	// Ganti path dengan path file lokal Anda yang sebenarnya.
	localFile := "/Users/yourLocalPath/yourFileName"

	// Unggah file besar.
	result, err := u.UploadFile(context.TODO(),
		&oss.PutObjectRequest{
			Bucket: oss.Ptr(bucketName),
			Key:    oss.Ptr(objectName),
			ProgressFn: func(increment, transferred, total int64) {
				fmt.Printf("increment:%v, transferred:%v, total:%v\n", increment, transferred, total)
			}, // Fungsi callback untuk kemajuan. Fungsi ini digunakan untuk menampilkan kemajuan unggah.
		},
		localFile)
	if err != nil {
		log.Fatalf("gagal mengunggah file %v", err)
	}

	// Cetak hasil unggah.
	log.Printf("hasil unggah file:%#v\n", result)
}

Referensi

Untuk informasi lebih lanjut tentang Uploader, lihat Panduan Pengembang.
Untuk informasi lebih lanjut tentang operasi API yang dapat Anda gunakan untuk mengunggah file besar, lihat UploadFrom dan UploadFile.