Object Storage Service:単純ダウンロード (Go SDK V2)

オブジェクトをダウンロードする際、最終更新日時または ETag に基づいて条件を指定できます。指定された条件が満たされた場合にのみオブジェクトがダウンロードされます。それ以外の場合は、エラーが返されます。条件付きダウンロードは、不要なネットワークトラフィックとリソース消費を削減し、ダウンロード効率を向上させます。

次の表に、OSS がサポートする条件を示します。

次のサンプルコードは、条件付きダウンロードを実行する方法を示しています。

package main

import (
	"context"
	"flag"
	"log"
	"net/http"
	"time"

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

	// ローカルファイルのパスを指定します。
	localFile := "download.file"

	// オブジェクトが 2024 年 10 月 21 日 18:43:02 に最終更新されたと仮定します。入力した UTC 時刻がこの時刻より前の場合、IfModifiedSince 条件が満たされ、ダウンロードがトリガーされます。
	date := time.Date(2024, time.October, 21, 18, 43, 2, 0, time.UTC)

	// ETag が "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" であると仮定します。入力した ETag がオブジェクトの ETag と同じ場合、IfMatch 条件が満たされ、ダウンロードがトリガーされます。
	etag := "\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\""

	// オブジェクトをローカルファイルにダウンロードするリクエストを作成します。
	getRequest := &oss.GetObjectRequest{
		Bucket:          oss.Ptr(bucketName),                   // バケットの名前。
		Key:             oss.Ptr(objectName),                   // オブジェクトの名前。
		IfModifiedSince: oss.Ptr(date.Format(http.TimeFormat)), // IfModifiedSince パラメーターを指定します。
		IfMatch:         oss.Ptr(etag),                         // IfMatch パラメーターを指定します。
	}

	// オブジェクトをローカルファイルにダウンロードし、結果を処理します。
	result, err := client.GetObjectToFile(context.TODO(), getRequest, localFile)
	if err != nil {
		log.Fatalf("failed to get object to file %v", err)
	}

	log.Printf("get object to 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 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)

	// ローカルファイルのパスを指定します。
	localFile := "download.file"

	// オブジェクトをローカルファイルにダウンロードするリクエストを作成します。
	getRequest := &oss.GetObjectRequest{
		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)
		}, // 進行状況のコールバック関数。ダウンロードの進行状況を表示します。
	}

	// オブジェクトをローカルファイルにダウンロードし、結果を処理します。
	result, err := client.GetObjectToFile(context.TODO(), getRequest, localFile)
	if err != nil {
		log.Fatalf("failed to get object to file %v", err)
	}

	log.Printf("get object to file result:%#v\n", result)
}

package main

import (
	"context"
	"flag"
	"fmt"
	"log"
	"os"
	"path/filepath"
	"strings"
	"sync"
	"time"

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

// グローバル変数を定義します。
var (
	region     string // バケットが配置されているリージョン。
	bucketName string // バケットの名前。
	prefix     string // オブジェクトのプレフィックス (フォルダパス)。
	localDir   string // ローカルのダウンロードディレクトリ。
	maxWorkers int    // 最大同時実行数。
	maxKeys    int    // 一度にリストするオブジェクトの最大数。
)

// DownloadTask: ダウンロードタスクの構造体。
type DownloadTask struct {
	ObjectKey string
	LocalPath string
	Size      int64
}

// DownloadResult: ダウンロード結果の構造体。
type DownloadResult struct {
	ObjectKey string
	Success   bool
	Error     error
	Size      int64
}

// 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(&prefix, "prefix", "", "The prefix (folder path) to download.")
	flag.StringVar(&localDir, "local-dir", "./downloads", "Local directory to save downloaded files.")
	flag.IntVar(&maxWorkers, "workers", 5, "Maximum number of concurrent downloads.")
	flag.IntVar(&maxKeys, "max-keys", 1000, "Maximum number of objects to list at once.")
}

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 prefix != "" && !strings.HasSuffix(prefix, "/") {
		prefix += "/"
	}

	// ローカルのダウンロードディレクトリを作成します。
	if err := os.MkdirAll(localDir, 0755); err != nil {
		log.Fatalf("failed to create local directory: %v", err)
	}

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

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

	fmt.Printf("Start batch download. Bucket: %s, Prefix: %s, Local directory: %s\n", bucketName, prefix, localDir)

	// ダウンロードするすべてのオブジェクトをリストします。
	tasks, err := listObjects(client, bucketName, prefix)
	if err != nil {
		log.Fatalf("failed to list objects: %v", err)
	}

	if len(tasks) == 0 {
		fmt.Println("No files to download are found.")
		return
	}

	fmt.Printf("Found %d files to download\n", len(tasks))

	// バッチダウンロードを実行します。
	results := batchDownload(client, tasks, maxWorkers)

	// ダウンロード結果をカウントします。
	var successCount, failCount int
	var totalSize int64
	for _, result := range results {
		if result.Success {
			successCount++
			totalSize += result.Size
		} else {
			failCount++
			fmt.Printf("Download failed: %s, Error: %v\n", result.ObjectKey, result.Error)
		}
	}

	fmt.Printf("\nDownload complete! Succeeded: %d, Failed: %d, Total size: %s\n",
		successCount, failCount, formatBytes(totalSize))
}

// listObjects は、バケット内で指定されたプレフィックスを持つすべてのオブジェクトをリストします。
func listObjects(client *oss.Client, bucketName, prefix string) ([]DownloadTask, error) {
	var tasks []DownloadTask
	var continuationToken *string

	for {
		// オブジェクトをリストするリクエストを作成します。
		request := &oss.ListObjectsV2Request{
			Bucket:            oss.Ptr(bucketName),
			Prefix:            oss.Ptr(prefix),
			MaxKeys:           int32(maxKeys),
			ContinuationToken: continuationToken,
		}

		// リスト操作を実行します。
		result, err := client.ListObjectsV2(context.TODO(), request)
		if err != nil {
			return nil, fmt.Errorf("failed to list objects: %w", err)
		}

		// リスト結果を処理します。
		for _, obj := range result.Contents {
			// フォワードスラッシュ (/) で終わり、サイズが 0 のフォルダオブジェクトをスキップします。
			if strings.HasSuffix(*obj.Key, "/") && obj.Size == 0 {
				continue
			}

			// ローカルファイルパスを計算します。
			relativePath := strings.TrimPrefix(*obj.Key, prefix)
			localPath := filepath.Join(localDir, relativePath)

			tasks = append(tasks, DownloadTask{
				ObjectKey: *obj.Key,
				LocalPath: localPath,
				Size:      obj.Size,
			})
		}

		// さらにオブジェクトがあるかどうかを確認します。
		if result.NextContinuationToken == nil {
			break
		}
		continuationToken = result.NextContinuationToken
	}

	return tasks, nil
}

// batchDownload はバッチダウンロードを実行します。
func batchDownload(client *oss.Client, tasks []DownloadTask, maxWorkers int) []DownloadResult {
	taskChan := make(chan DownloadTask, len(tasks))
	resultChan := make(chan DownloadResult, len(tasks))

	// ワーカーコルーチンを開始します。
	var wg sync.WaitGroup
	for i := 0; i < maxWorkers; i++ {
		wg.Add(1)
		go downloadWorker(client, bucketName, taskChan, resultChan, &wg)
	}

	// ダウンロードタスクを送信します。
	go func() {
		for _, task := range tasks {
			taskChan <- task
		}
		close(taskChan)
	}()

	// すべてのワーカーコルーチンが完了するのを待ちます。
	go func() {
		wg.Wait()
		close(resultChan)
	}()

	// 結果を収集し、進行状況を表示します。
	var results []DownloadResult
	completed := 0
	total := len(tasks)

	for result := range resultChan {
		results = append(results, result)
		completed++

		if result.Success {
			fmt.Printf("✓ [%d/%d] %s (%s)\n",
				completed, total, result.ObjectKey, formatBytes(result.Size))
		} else {
			fmt.Printf("✗ [%d/%d] %s - Error: %v\n",
				completed, total, result.ObjectKey, result.Error)
		}
	}

	return results
}

// downloadWorker: ダウンロードワーカーコルーチン。
func downloadWorker(client *oss.Client, bucketName string, taskChan <-chan DownloadTask,
	resultChan chan<- DownloadResult, wg *sync.WaitGroup) {
	defer wg.Done()

	for task := range taskChan {
		result := DownloadResult{
			ObjectKey: task.ObjectKey,
			Size:      task.Size,
		}

		// ローカルファイルディレクトリを作成します。
		if err := os.MkdirAll(filepath.Dir(task.LocalPath), 0755); err != nil {
			result.Error = fmt.Errorf("failed to create directory: %w", err)
			resultChan <- result
			continue
		}

		// ファイルが存在し、同じサイズであるかどうかを確認します。
		if fileInfo, err := os.Stat(task.LocalPath); err == nil {
			if fileInfo.Size() == task.Size {
				result.Success = true
				resultChan <- result
				continue
			}
		}

		// ダウンロードリクエストを作成します。
		getRequest := &oss.GetObjectRequest{
			Bucket: oss.Ptr(bucketName),
			Key:    oss.Ptr(task.ObjectKey),
		}

		// ダウンロードを実行します。
		ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
		_, err := client.GetObjectToFile(ctx, getRequest, task.LocalPath)
		cancel()

		if err != nil {
			result.Error = err
		} else {
			result.Success = true
		}

		resultChan <- result
	}
}

// formatBytes はバイト数を人間が読める形式にフォーマットします。
func formatBytes(bytes int64) string {
	const unit = 1024
	if bytes < unit {
		return fmt.Sprintf("%d B", bytes)
	}
	div, exp := int64(unit), 0
	for n := bytes / unit; n >= unit; n /= unit {
		div *= unit
		exp++
	}
	return fmt.Sprintf("%.1f %cB", float64(bytes)/float64(div), "KMGTPE"[exp])
}

使用方法

# テストコードを実行可能ファイルにコンパイルします。
go build -o oss-batch-download main.go

# 指定したフォルダをダウンロードします。
./oss-batch-download -region oss-cn-hangzhou -bucket my-bucket -prefix images/2024/

# ローカルディレクトリと同時実行数をカスタマイズします。
./oss-batch-download -region oss-cn-hangzhou -bucket my-bucket -prefix documents/ -local-dir ./downloads -workers 10

# バケット全体をダウンロードします。
./oss-batch-download -region oss-cn-hangzhou -bucket my-bucket -prefix ""

出力例

プログラムを実行すると、詳細なダウンロードの進行状況が表示されます。

Start batch download. Bucket: my-bucket, Prefix: images/2024/, Local directory: ./downloads
Found 150 files to download
✓ [1/150] images/2024/photo1.jpg (2.3 MB)
✓ [2/150] images/2024/photo2.png (1.8 MB)
...
Download complete! Succeeded: 148, Failed: 2, Total size: 1.2 GB