cara melakukan unggah tambahan menggunakan go sdk v2 - Object Storage Service

Unggah tambahan memungkinkan Anda menambahkan konten langsung ke akhir objek yang dapat ditambahkan yang sudah ada. Topik ini menjelaskan cara melakukan unggah tambahan menggunakan OSS SDK untuk Go.

Catatan penggunaan

Kode contoh dalam topik ini menggunakan ID Wilayah cn-hangzhou untuk Wilayah Tiongkok (Hangzhou). Secara default, Endpoint publik digunakan untuk mengakses sumber daya di bucket. Jika Anda ingin mengakses sumber daya di bucket menggunakan layanan Alibaba Cloud lainnya di wilayah yang sama dengan lokasi bucket, Anda dapat menggunakan Endpoint internal. Untuk informasi lebih lanjut tentang Wilayah dan endpoint OSS, lihat Wilayah dan Endpoint.
Dalam topik ini, kredensial akses dibaca dari variabel lingkungan. Untuk informasi lebih lanjut tentang cara mengonfigurasi kredensial akses, lihat Konfigurasikan Kredensial Akses.
Jika file tempat Anda ingin menambahkan konten tidak ada, objek yang dapat ditambahkan akan dibuat saat Anda memanggil operasi API unggah tambahan.
Jika file tempat Anda ingin menambahkan konten ada:
- Jika file tersebut adalah objek yang dapat ditambahkan dan posisi tambahan yang ditentukan sama dengan panjang saat ini dari file, konten akan ditambahkan ke akhir file.
- Jika file tersebut adalah objek yang dapat ditambahkan tetapi posisi tambahan yang ditentukan tidak sama dengan panjang saat ini dari file, pengecualian PositionNotEqualToLength akan dilemparkan.
- Jika file tersebut bukan objek yang dapat ditambahkan, seperti objek normal yang diunggah menggunakan unggah sederhana, pengecualian ObjectNotAppendable akan dilemparkan.

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

AppendObject

oss:PutObject

Anda dapat memanggil operasi ini untuk mengunggah objek dengan menambahkan objek ke objek yang sudah ada.

oss:PutObjectTagging

Saat mengunggah objek dengan menambahkan objek ke objek yang sudah ada, jika Anda menentukan tag objek melalui x-oss-tagging, izin ini diperlukan.

Definisi metode

Untuk skenario unggah tambahan, OSS SDK untuk Go menyediakan operasi baru AppendFile untuk mensimulasikan perilaku membaca dan menulis file untuk objek dalam bucket. Tabel berikut menjelaskan operasi AppendFile dan AppendObject.

Nama operasi

Deskripsi

Client.AppendObject

Menjalankan unggah tambahan. Objek akhir dapat berukuran hingga 5 GiB.

Mendukung pemeriksaan integritas data CRC-64 (diaktifkan secara default).

Mendukung bilah kemajuan.

Badan permintaan bertipe io.Reader. Jika tipe io.Seeker didukung, retransmisi tersedia setelah kegagalan. Operasi ini tidak idempoten, dan retransmisi mungkin gagal.

Client.AppendFile

Memberikan kemampuan yang sama dengan operasi Client.AppendObject.

Mengoptimalkan toleransi kesalahan untuk kegagalan retransmisi.

Termasuk operasi AppendOnlyFile.

AppendOnlyFile.Write

AppendOnlyFile.WriteFrom

API Unggah Tambahan Premium: AppendFile

Anda dapat memanggil operasi AppendFile untuk mengunggah data dengan menambahkannya. Jika objek tidak ada, objek yang dapat ditambahkan dibuat. Jika objek ada tetapi bukan objek yang dapat ditambahkan, kesalahan akan dikembalikan.

Kode contoh berikut memberikan contoh cara mendefinisikan operasi AppendFile.

type AppendOnlyFile struct {
...
}

func (c *Client) AppendFile(ctx context.Context, bucket string, key string, optFns ...func(*AppendOptions)) (*AppendOnlyFile, error)

Parameter permintaan

Parameter	Tipe	Deskripsi
ctx	context.Context	Konteks permintaan.
bucket	string	Nama bucket.
key	string	Nama objek.
optFns	...func(*AppendOptions)	Opsional. Opsi konfigurasi untuk menambahkan file.

Tabel berikut menjelaskan parameter AppendOptions.

Parameter	Tipe	Deskripsi
RequestPayer	*string	Jika mode bayar-per-permintaan diaktifkan, atur parameter ini ke 'requester'.
CreateParameter	*AppendObjectRequest	Digunakan untuk menyetel metadata objek selama unggah pertama. Metadata mencakup ContentType, Metadata, izin, dan kelas penyimpanan. Untuk informasi lebih lanjut, lihat AppendObjectRequest.

Nilai kembali

Nilai kembali	Tipe	Deskripsi
file	*AppendOnlyFile	Instans file yang dapat ditambahkan. Parameter ini valid hanya jika err adalah nil. Untuk informasi lebih lanjut, lihat AppendOnlyFile.
err	error	Status membuka file yang dapat ditambahkan. Jika operasi gagal, err tidak nil.

Tabel berikut menjelaskan operasi AppendOnlyFile.

Nama operasi	Deskripsi
Close() error	Menutup handle file untuk melepaskan sumber daya.
Write(b []byte) (int, error)	Menulis data di b ke aliran data dan mengembalikan jumlah byte yang ditulis serta kesalahan apa pun yang ditemui.
WriteFrom(r io.Reader) (int64, error)	Menulis data di r ke aliran data dan mengembalikan jumlah byte yang ditulis serta kesalahan apa pun yang ditemui.
Stat() (os.FileInfo, error)	Mendapatkan informasi objek, termasuk ukuran objek, waktu modifikasi terakhir, dan metadata.

API Unggah Tambahan Dasar: AppendObject

func (c *Client) AppendObject(ctx context.Context, request *AppendObjectRequest, optFns ...func(*Options)) (*AppendObjectResult, error)

Parameter permintaan

Parameter	Tipe	Deskripsi
ctx	context.Context	Konteks permintaan, yang dapat digunakan untuk menyetel total periode timeout permintaan.
request	*AppendObjectRequest	Parameter permintaan untuk operasi API tertentu. Untuk informasi lebih lanjut, lihat AppendObjectRequest.
optFns	...func(*Options)	Opsional. Parameter konfigurasi tingkat operasi. Untuk informasi lebih lanjut, lihat Options.

Nilai kembali

Nilai kembali	Tipe	Deskripsi
result	*AppendObjectResult	Nilai kembali operasi API. Parameter ini valid hanya jika err adalah nil. Untuk informasi lebih lanjut, lihat AppendObjectResult.
err	error	Status permintaan. Jika permintaan gagal, err tidak nil.

Kode contoh

Gunakan AppendFile untuk melakukan unggah tambahan

package main

import (
	"context"
	"flag"
	"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 penyimpanan 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")
	}

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

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

	// Buat instans file yang dapat ditambahkan.
	f, err := client.AppendFile(context.TODO(),
		bucketName,
		objectName,
		func(ao *oss.AppendOptions) {
			ao.CreateParameter = &oss.AppendObjectRequest{
				Acl: oss.ObjectACLPrivate, // Setel izin akses objek menjadi privat.
				Metadata: map[string]string{
					"user": "jack", // Setel metadata objek.
				},
				Tagging: oss.Ptr("key=value"), // Setel tag untuk objek.
			}
		})

	if err != nil {
		log.Fatalf("gagal menambahkan file %v", err)
	}
	defer f.Close() // Pastikan aliran data ditutup saat fungsi berakhir.

	// Buka file lokal example1.txt.
	lf, err := os.Open("/local/dir/example1.txt")
	if err != nil {
		log.Fatalf("gagal membuka file lokal %v", err)
	}

	// Tambahkan isi example1.txt ke objek OSS.
	_, err = f.WriteFrom(lf)
	if err != nil {
		log.Fatalf("gagal menambahkan file %v", err)
	}
	lf.Close() // Tutup file lokal.

	// Buka file lokal example2.txt.
	lf, err = os.Open("/local/dir/example2.txt")
	if err != nil {
		log.Fatalf("gagal membuka file lokal %v", err)
	}

	// Tambahkan isi example2.txt ke objek OSS.
	_, err = f.WriteFrom(lf)
	if err != nil {
		log.Fatalf("gagal menambahkan file %v", err)
	}
	lf.Close() // Tutup file lokal.

	// Baca isi file lokal example3.txt.
	lb, err := os.ReadFile("/local/dir/example3.txt")
	if err != nil {
		log.Fatalf("gagal membaca file lokal %v", err)
	}

	// Tambahkan isi example3.txt ke objek OSS.
	_, err = f.Write(lb)
	if err != nil {
		log.Fatalf("gagal menambahkan file %v", err)
	}

	// Cetak informasi log tentang unggah tambahan yang berhasil.
	log.Printf("file berhasil ditambahkan")
}

Gunakan AppendObject untuk melakukan unggah tambahan

package main

import (
	"context"
	"flag"
	"log"
	"strings"

	"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
	bucketName string
	objectName string
)

// 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()

	// Tentukan posisi awal untuk unggah tambahan.
	var (
		position = int64(0)
	)

	// 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 setel penyedia kredensial dan wilayah.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

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

	// Tentukan konten untuk ditambahkan.
	content := "hi append object"

	// Buat permintaan AppendObject.
	request := &oss.AppendObjectRequest{
		Bucket:   oss.Ptr(bucketName),
		Key:      oss.Ptr(objectName),
		Position: oss.Ptr(position),
		Body:     strings.NewReader(content),
	}

	// Jalankan permintaan AppendObject dan proses hasilnya.
	// Posisi untuk unggah tambahan pertama adalah 0. Nilai kembali berisi posisi untuk unggah tambahan berikutnya.
	result, err := client.AppendObject(context.TODO(), request)
	if err != nil {
		log.Fatalf("gagal menambahkan objek %v", err)
	}

	// Buat permintaan AppendObject kedua.
	request = &oss.AppendObjectRequest{
		Bucket:   oss.Ptr(bucketName),
		Key:      oss.Ptr(objectName),
		Position: oss.Ptr(result.NextPosition), // Dapatkan NextPosition dari nilai kembali permintaan AppendObject pertama.
		Body:     strings.NewReader("hi append object"),
	}

	// Jalankan permintaan AppendObject kedua dan proses hasilnya.
	result, err = client.AppendObject(context.TODO(), request)
	if err != nil {
		log.Fatalf("gagal menambahkan objek %v", err)
	}

	log.Printf("hasil objek tambahan:%#v\n", result)
}

Skenario umum

Lakukan unggah tambahan dan tampilkan bilah kemajuan

package main

import (
	"context"
	"flag"
	"fmt"
	"log"
	"strings"

	"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
	bucketName string
	objectName string
)

// 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()

	// Tentukan posisi awal untuk unggah tambahan.
	var (
		position = int64(0)
	)

	// 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 setel penyedia kredensial dan wilayah.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

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

	// Tentukan konten untuk ditambahkan.
	content := "hi append object"

	// Buat permintaan AppendObject.
	request := &oss.AppendObjectRequest{
		Bucket:   oss.Ptr(bucketName),
		Key:      oss.Ptr(objectName),
		Position: oss.Ptr(position),
		Body:     strings.NewReader(content),
		ProgressFn: func(increment, transferred, total int64) {
			fmt.Printf("increment:%v, transferred:%v, total:%v\n", increment, transferred, total)
		}, // Fungsi callback kemajuan, digunakan untuk menampilkan kemajuan unggah.
	}

	// Jalankan permintaan AppendObject pertama dan proses hasilnya.
	// Posisi untuk unggah tambahan pertama adalah 0. Nilai kembali berisi posisi untuk unggah tambahan berikutnya.
	result, err := client.AppendObject(context.TODO(), request)
	if err != nil {
		log.Fatalf("gagal menambahkan objek %v", err)
	}

	// Buat permintaan AppendObject kedua.
	request = &oss.AppendObjectRequest{
		Bucket:   oss.Ptr(bucketName),
		Key:      oss.Ptr(objectName),
		Position: oss.Ptr(result.NextPosition), // Dapatkan NextPosition dari nilai kembali permintaan AppendObject pertama.
		Body:     strings.NewReader("hi append object"),
		ProgressFn: func(increment, transferred, total int64) {
			fmt.Printf("increment:%v, transferred:%v, total:%v\n", increment, transferred, total)
		}, // Fungsi callback kemajuan, digunakan untuk menampilkan kemajuan unggah.
	}

	// Jalankan permintaan AppendObject kedua dan proses hasilnya.
	result, err = client.AppendObject(context.TODO(), request)
	if err != nil {
		log.Fatalf("gagal menambahkan objek %v", err)
	}

	// Cetak versionId dari objek yang ditambahkan.
	log.Printf("hasil objek tambahan:%#v\n", *result.VersionId)
}

Referensi

Untuk kode contoh lengkap untuk unggah tambahan, lihat Contoh GitHub dan Panduan Pengembang.
Untuk informasi lebih lanjut tentang operasi API premium untuk unggah tambahan, lihat AppendFile.
Untuk informasi lebih lanjut tentang operasi API dasar untuk unggah tambahan, lihat AppendObject.