oss go sdk v2 を使用してファイルをアップロードする方法 - Object Storage Service

このトピックでは、Go SDK V2 の Uploader モジュールを使用してファイルをアップロードする方法について説明します。

使用上の注意

このトピックのサンプルコードでは、中国 (杭州) リージョンのリージョン ID cn-hangzhou を使用します。デフォルトでは、パブリックエンドポイントを使用してバケット内のリソースにアクセスします。同じリージョン内の他の Alibaba Cloud サービスを使用してバケットリソースにアクセスする場合は、内部エンドポイントを使用します。OSS のリージョンとエンドポイントの詳細については、「リージョンとエンドポイント」をご参照ください。
このトピックでは、アクセス資格情報は環境変数から取得されます。アクセス資格情報の設定方法の詳細については、「アクセス資格情報の設定」をご参照ください。
大きなファイルをアップロードするには、oss:PutObject 権限が必要です。詳細については、「RAM ユーザーへのカスタムポリシーのアタッチ」をご参照ください。

メソッド定義

アップローダーの概要

Go SDK V2 の Uploader は、基盤となる実装の詳細を隠す高レベルの操作を提供することで、ファイルのアップロードを簡素化します。

Uploader は、マルチパートアップロード操作を使用して、大きなファイルまたはストリームを複数の小さなパートに分割し、パフォーマンスを向上させるためにパートを同時にアップロードします。
Uploader は、再開可能なアップロード機能も提供します。この機能は、アップロードプロセス中に完了したパートのステータスを記録します。ネットワークの中断やプログラムの例外などの問題でファイルのアップロードが失敗した場合、次回ファイルをアップロードしようとするときに、ブレークポイントのレコードからアップロードを再開できます。

次のサンプルコードは、Uploader の使用方法を示しています。

type Uploader struct {
  ...
}

// 新しいアップローダーを作成します。
func (c *Client) NewUploader(optFns ...func(*UploaderOptions)) *Uploader 

// ファイルストリームをアップロードします。
func (u *Uploader) UploadFrom(ctx context.Context, request *PutObjectRequest, body io.Reader, optFns ...func(*UploaderOptions)) (*UploadResult, error)

// ローカルファイルをアップロードします。
func (u *Uploader) UploadFile(ctx context.Context, request *PutObjectRequest, filePath string, optFns ...func(*UploaderOptions)) (*UploadResult, error)

リクエストパラメーター

パラメーター	タイプ	説明
ctx	context.Context	リクエストのコンテキスト。
request	*PutObjectRequest	オブジェクトをアップロードするためのリクエストパラメーター。パラメーターは PutObject 操作のものと同じです。詳細については、「PutObjectRequest」をご参照ください。
body	io.Reader	アップロードするストリーム。 body パラメーターが io.Reader 型のみをサポートする場合、データをアップロードする前にメモリにデータをバッファリングする必要があります。 body パラメーターが io.Reader、io.Seeker、および io.ReaderAt 型をサポートする場合、メモリにデータをバッファリングする必要はありません。
filePath	string	ローカルファイルのパス。
optFns	...func(*UploaderOptions)	(オプション) 構成オプション。

次の表に、UploaderOptions の共通パラメーターを示します。

パラメーター	タイプ	説明
PartSize	int64	パートサイズ。デフォルト値は 6 MiB です。
ParallelNum	int	同時アップロードタスクの数。デフォルト値は 3 です。このパラメーターは、グローバルな同時実行数ではなく、単一の呼び出しの同時実行数の上限を指定します。
LeavePartsOnError	bool	アップロードが失敗したときにアップロードされたパートを保持するかどうかを指定します。デフォルトでは、アップロードされたパートは保持されません。
EnableCheckpoint	bool	再開可能なアップロード機能を有効にするかどうかを指定します。デフォルトでは、この機能は無効になっています。説明 EnableCheckpoint パラメーターは UploadFile 操作でのみ有効であり、UploadFrom 操作ではサポートされていません。
CheckpointDir	string	チェックポイントファイルを保存するパス。例: /local/dir/。このパラメーターは、EnableCheckpoint が true に設定されている場合にのみ有効です。

NewUploader を使用して Uploader をインスタンス化するときに、構成オプションを指定してアップロードの動作をカスタマイズできます。これらのオプションは、Uploader インスタンスに設定してすべてのアップロードに適用することも、個々のアップロード操作ごとに指定することもできます。

Uploader の構成パラメーターを設定する

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

各アップロードリクエストの構成パラメーターを設定する

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
})

例

次のサンプルコードを使用して、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"
)

// グローバル変数を定義します。
var (
	region     string // ストレージリージョン。
	bucketName string // バケット名。
	objectName string // オブジェクト名。
)

// init 関数は、コマンドラインパラメーターを初期化するために使用されます。
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
	flag.StringVar(&objectName, "object", "", "The name of the source object.")
}

func main() {
	// コマンドラインパラメーターを解析します。
	flag.Parse()

	// バケット名が空かどうかを確認します。
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	// リージョンが空かどうかを確認します。
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// オブジェクト名が空かどうかを確認します。
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, source object name required")
	}

	// デフォルトの構成をロードし、資格情報プロバイダーとリージョンを設定します。
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// OSS クライアントを作成します。
	client := oss.NewClient(cfg)

	// アップローダーを作成します。
	u := client.NewUploader()

	// ローカルファイルのパスを定義します。パスを実際のローカルファイルのパスとファイル名に置き換える必要があります。
	localFile := "/Users/yourLocalPath/yourFileName"

	// ファイルをアップロードします。
	result, err := u.UploadFile(context.TODO(),
		&oss.PutObjectRequest{
			Bucket: oss.Ptr(bucketName),
			Key:    oss.Ptr(objectName)},
		localFile)
	if err != nil {
		log.Fatalf("failed to upload file %v", err)
	}

	// アップロード結果を出力します。
	log.Printf("upload file result:%#v\n", result)
}

一般的なシナリオ

アップローダーを使用して再開可能なアップロード機能を有効にする

次のサンプルコードを使用して、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"
)

// グローバル変数を定義します。
var (
	region     string // ストレージリージョン。
	bucketName string // バケット名。
	objectName string // オブジェクト名。
)

// init 関数は、コマンドラインパラメーターを初期化するために使用されます。
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
	flag.StringVar(&objectName, "object", "", "The name of the source object.")
}

func main() {
	// コマンドラインパラメーターを解析します。
	flag.Parse()

	// バケット名が空かどうかを確認します。
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	// リージョンが空かどうかを確認します。
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// オブジェクト名が空かどうかを確認します。
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, source object name required")
	}

	// デフォルトの構成をロードし、資格情報プロバイダーとリージョンを設定します。
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// OSS クライアントを作成します。
	client := oss.NewClient(cfg)

	// アップローダーを作成し、再開可能なアップロード機能を有効にします。
	u := client.NewUploader(func(uo *oss.UploaderOptions) {
		uo.CheckpointDir = "/Users/yourLocalPath/checkpoint/" // チェックポイントファイルを保存するパスを指定します。
		uo.EnableCheckpoint = true        // 再開可能なアップロードを有効にします。
	})

	// ローカルファイルのパスを定義します。パスを実際のローカルファイルのパスとファイル名に置き換える必要があります。
	localFile := "/Users/yourLocalPath/yourFileName"

	// ファイルをアップロードします。
	result, err := u.UploadFile(context.TODO(),
		&oss.PutObjectRequest{
			Bucket: oss.Ptr(bucketName),
			Key:    oss.Ptr(objectName)},
		localFile)
	if err != nil {
		log.Fatalf("failed to upload file %v", err)
	}

	// アップロード結果を出力します。
	log.Printf("upload file result:%#v\n", result)
}

アップローダーを使用してローカルファイルストリームをアップロードする

次のサンプルコードを使用して、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"
)

// グローバル変数を定義します。
var (
	region     string // ストレージリージョン。
	bucketName string // バケット名。
	objectName string // オブジェクト名。
)

// init 関数は、コマンドラインパラメーターを初期化するために使用されます。
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
	flag.StringVar(&objectName, "object", "", "The name of the object.")
}

func main() {
	// コマンドラインパラメーターを解析します。
	flag.Parse()

	// バケット名が空かどうかを確認します。
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	// リージョンが空かどうかを確認します。
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// オブジェクト名が空かどうかを確認します。
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, object name required")
	}

	// デフォルトの構成をロードし、資格情報プロバイダーとリージョンを設定します。
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// OSS クライアントを作成します。
	client := oss.NewClient(cfg)

	// アップローダーを作成します。
	u := client.NewUploader()

	// "/Users/yourLocalPath/yourFileName" を実際のファイルパスとファイル名に置き換え、ローカルファイルを開き、io.Reader インスタンスを作成します。
	file, err := os.Open("/Users/yourLocalPath/yourFileName")
	if err != nil {
		log.Fatalf("failed to open local file %v", err)
	}
	defer file.Close()

	var r io.Reader = file

	// ファイルストリームをアップロードします。
	result, err := u.UploadFrom(context.TODO(),
		&oss.PutObjectRequest{
			Bucket: oss.Ptr(bucketName),
			Key:    oss.Ptr(objectName),
		},
		r, // アップロードするファイルストリーム。
	)

	if err != nil {
		log.Fatalf("failed to upload file stream %v", err)
	}

	// ファイルストリームのアップロード結果を出力します。
	log.Printf("upload file stream, etag: %v\n", oss.ToString(result.ETag))
}

アップローダーを使用してパートサイズと同時実行数を設定する

次のサンプルコードを使用して、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"
)

// グローバル変数を定義します。
var (
	region     string // ストレージリージョン。
	bucketName string // バケット名。
	objectName string // オブジェクト名。
)

// init 関数は、コマンドラインパラメーターを初期化するために使用されます。
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
	flag.StringVar(&objectName, "object", "", "The name of the source object.")
}

func main() {
	// コマンドラインパラメーターを解析します。
	flag.Parse()

	// バケット名が空かどうかを確認します。
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	// リージョンが空かどうかを確認します。
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// オブジェクト名が空かどうかを確認します。
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, source object name required")
	}

	// デフォルトの構成をロードし、資格情報プロバイダーとリージョンを設定します。
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// OSS クライアントを作成します。
	client := oss.NewClient(cfg)

	// アップローダーを作成します。
	u := client.NewUploader(func(uo *oss.UploaderOptions) {
		uo.PartSize = 1024 * 1024 * 5     // パートサイズを 5 MB に設定します。
		uo.ParallelNum = 5                // 同時アップロード数を 5 に設定します。
	})

	// ローカルファイルのパスを定義します。パスを実際のローカルファイルのパスとファイル名に置き換える必要があります。
	localFile := "/Users/yourLocalPath/yourFileName"

	// ファイルをアップロードします。
	result, err := u.UploadFile(context.TODO(),
		&oss.PutObjectRequest{
			Bucket: oss.Ptr(bucketName),
			Key:    oss.Ptr(objectName)},
		localFile)
	if err != nil {
		log.Fatalf("failed to upload file %v", err)
	}

	// アップロード結果を出力します。
	log.Printf("upload file result:%#v\n", result)
}

アップローダーを使用してアップロードコールバックを設定する

次のサンプルコードを使用して、ファイルのアップロード後にアプリケーションサーバーに通知します。

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"
)

// グローバル変数を定義します。
var (
	region     string // ストレージリージョン。
	bucketName string // バケット名。
	objectName string // オブジェクト名。
)

// init 関数は、コマンドラインパラメーターを初期化するために使用されます。
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
	flag.StringVar(&objectName, "object", "", "The name of the source object.")
}

func main() {
	// コマンドラインパラメーターを解析します。
	flag.Parse()

	// バケット名が空かどうかを確認します。
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	// リージョンが空かどうかを確認します。
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// オブジェクト名が空かどうかを確認します。
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, source object name required")
	}

	// デフォルトの構成をロードし、資格情報プロバイダーとリージョンを設定します。
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// OSS クライアントを作成します。
	client := oss.NewClient(cfg)

	// アップローダーを作成し、再開可能なアップロード機能を有効にします。
	u := client.NewUploader(func(uo *oss.UploaderOptions) {
		uo.PartSize = 1024 * 1024 * 5 // パートサイズを 5 MB に設定します。
		uo.ParallelNum = 5            // 同時アップロード数を 5 に設定します。
	})

	// ローカルファイルのパスを定義します。パスを実際のローカルファイルのパスに置き換える必要があります。
	localFile := "/Users/yourLocalPath/yourFileName"

	// コールバックパラメーターを定義します。
	callbackMap := map[string]string{
		"callbackUrl":      "https://example.com:23450/callback",                                                        // コールバックサーバーの URL を設定します。例: https://example.com:23450。
		"callbackBody":     "bucket=${bucket}&object=${object}&size=${size}&my_var_1=${x:my_var1}&my_var_2=${x:my_var2}", // コールバックリクエストの本文を設定します。
		"callbackBodyType": "application/x-www-form-urlencoded",                                                          // コールバックリクエストの本文のタイプを設定します。
	}

	// コールバックパラメーターを JSON に変換し、Base64 エンコーディングを実行してコールバックパラメーターとして渡します。
	callbackStr, err := json.Marshal(callbackMap)
	if err != nil {
		log.Fatalf("failed to marshal callback map: %v", err)
	}
	callbackBase64 := base64.StdEncoding.EncodeToString(callbackStr)

	// カスタムコールバックパラメーターを定義します。
	callbackVarMap := map[string]string{}
	callbackVarMap["x:my_var1"] = "thi is var 1"
	callbackVarMap["x:my_var2"] = "thi is var 2"

	// コールバックパラメーターを JSON に変換し、Base64 エンコーディングを実行してコールバックパラメーターとして渡します。
	callbackVarStr, err := json.Marshal(callbackVarMap)
	if err != nil {
		log.Fatalf("failed to marshal callback var: %v", err)
	}
	callbackVarBase64 := base64.StdEncoding.EncodeToString(callbackVarStr)

	// 大きなファイルをアップロードします。
	result, err := u.UploadFile(context.TODO(),
		&oss.PutObjectRequest{
			Bucket:      oss.Ptr(bucketName),
			Key:         oss.Ptr(objectName),
			Callback:    oss.Ptr(callbackBase64),    // コールバックパラメーターを指定します。
			CallbackVar: oss.Ptr(callbackVarBase64), // カスタムコールバックパラメーターを指定します。
		},
		localFile)
	if err != nil {
		log.Fatalf("failed to upload file %v", err)
	}

	// アップロード結果を出力します。
	log.Printf("upload file result:%#v\n", result)
}

アップローダーを使用して進捗横棒グラフを表示する

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"
)

// グローバル変数を定義します。
var (
	region     string // ストレージリージョン。
	bucketName string // バケット名。
	objectName string // オブジェクト名。
)

// init 関数は、コマンドラインパラメーターを初期化するために使用されます。
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
	flag.StringVar(&objectName, "object", "", "The name of the source object.")
}

func main() {
	// コマンドラインパラメーターを解析します。
	flag.Parse()

	// バケット名が空かどうかを確認します。
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	// リージョンが空かどうかを確認します。
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// オブジェクト名が空かどうかを確認します。
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, source object name required")
	}

	// デフォルトの構成をロードし、資格情報プロバイダーとリージョンを設定します。
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// OSS クライアントを作成します。
	client := oss.NewClient(cfg)

	// アップローダーを作成します。
	u := client.NewUploader(func(uo *oss.UploaderOptions) {
		uo.PartSize = 1024 * 1024 * 5 // パートサイズを 5 MB に設定します。
		uo.ParallelNum = 3            // 同時アップロード数を 3 に設定します。
	})

	// パスを実際のローカルファイルのパスに置き換えます。
	localFile := "/Users/yourLocalPath/yourFileName"

	// 大きなファイルをアップロードします。
	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)
			}, // 進捗状況のコールバック関数。この関数は、アップロードの進捗状況を表示するために使用されます。
		},
		localFile)
	if err != nil {
		log.Fatalf("failed to upload file %v", err)
	}

	// アップロード結果を出力します。
	log.Printf("upload file result:%#v\n", result)
}

Object Storage Service:Uploader (Go SDK V2)