Go で Backblaze からファイルを効率的にインポートする方法
この例では、既存の Backblaze B2 バケットのプレフィックスに一致するファイルを、新しい非公開のローカルディレクトリにインポートします。Blazer のページ分割対応 Native API クライアントを使用し、各ファイルのサイズとファイル全体の SHA-1 を検証してからローカルに公開します。連番のファイル名を使うことで、リモートキーがファイルシステムのパスに入り込むのを防ぎます。
Backblaze B2 API の概要
元の kurin/blazer リポジトリは、すでにメンテナンスされていません。後継は Backblaze の Blazer リポジトリです。この例では、現在のタグ付きリリースである v0.8.0に固定します。このリリースは Native API v3 を使用します。既存バケット向けの Native API 連携の例です。Blazer のメンテナーは、この API が不要な連携には S3 クライアントを推奨しています。
既存の v3 対応アプリケーションキーを使用してください。Multi-Bucket Application Keys は v4 認証を必要とするため、選択したバケットが一つだけでも、このリリースでは使用できません。Backblaze の API バージョンポリシーでは、この違いと旧 API バージョンの継続サポートについて説明しています。
Backblaze のファイルインポート用 Go 環境の設定
以下のコマンドは Linux 上の Bash を使用し、Go 1.27.3 で動作確認しています。Go のダウンロードページから、Go 1.27 系列の最新セキュリティパッチをインストールしてください。B2 パッケージには、外部のランタイム依存関係はありません。
書き込み可能なディレクトリで、以下を貼り付けて実行してください。サブシェルを使うため現在のディレクトリは変わらず、失敗時には停止します。既存の backblaze-import ディレクトリは変更しません。GOWORK=off により、上位の Go ワークスペースがこの独立したプロジェクトに影響しないようにします。
(
command -v go >/dev/null &&
mkdir backblaze-import &&
cd backblaze-import &&
GOWORK=off GOTOOLCHAIN=local go mod init backblaze-import &&
GOWORK=off GOTOOLCHAIN=local go get github.com/Backblaze/blazer/b2@v0.8.0
)
Go SDK による Backblaze B2 への接続
シークレットマネージャーまたはシェル環境を使い、B2_KEY_ID にアプリケーションキー ID、B2_APPLICATION_KEY にそのシークレットを設定してください。キーには、既存バケットへのアクセス権と listBuckets、listFiles、readFiles の権限が必要です。バケットの検索にはバケット名を渡すため、単一バケット用のキーでも動作します。キーでファイル名を制限している場合、B2_PREFIX もその制限内に収める必要があります。認証情報の最初の引数は、バケット ID ではなくキー ID です。バケット検索の要件を参照してください。
B2_BUCKET にバケット名、B2_PREFIX に空でないプレフィックス、LOCAL_PARENT に既存の書き込み可能なローカルディレクトリを設定してください。仮想フォルダーを選択するときは、末尾に / を含めてください。invoices/ は invoices-old/ を対象に含めません。インポート対象のオブジェクトはバケット内に存在し、メタデータにファイル全体の SHA-1 が含まれている必要があります。コマンドの実行中は、このプレフィックスに一致する内容を変更しないでください。
Go による基本的なファイルインポート機能の実装
以下のプログラム全体を backblaze-import/main.go として保存してください。各ダウンロードはメタデータのサイズと SHA-1 で検証し、同期して閉じた後、同じ非公開ディレクトリ内で名前を変更します。ここでの SHA-1 は転送の整合性を確認するもので、ファイルの作成者を証明する署名ではありません。
package main
import (
"context"
"crypto/sha1"
"encoding/hex"
"errors"
"fmt"
"io"
"os"
"os/signal"
"path/filepath"
"strings"
"time"
"github.com/Backblaze/blazer/b2"
)
func importObject(ctx context.Context, object *b2.Object, directory string, number int) error {
attrs, err := object.Attrs(ctx)
if err != nil {
return err
}
digest, err := hex.DecodeString(attrs.SHA1)
if err != nil || len(digest) != sha1.Size || attrs.Size < 0 {
return errors.New("object needs a whole-file SHA-1; large files without one are unsupported")
}
reader := object.NewReader(ctx)
reader.ConcurrentDownloads = 1
reader.ChunkSize = 1 << 20
defer reader.Close()
tmp, err := os.CreateTemp(directory, ".import-")
if err != nil {
return err
}
defer os.Remove(tmp.Name())
defer tmp.Close()
hash := sha1.New()
n, err := io.Copy(io.MultiWriter(tmp, hash), io.LimitReader(reader, attrs.Size+1))
if err != nil {
return err
}
if n != attrs.Size || hex.EncodeToString(hash.Sum(nil)) != strings.ToLower(attrs.SHA1) {
return errors.New("object changed or download integrity check failed")
}
if err := reader.Close(); err != nil {
return err
}
if err := tmp.Sync(); err != nil {
return err
}
if err := tmp.Close(); err != nil {
return err
}
if err := ctx.Err(); err != nil {
return err
}
// Remote names never become local paths; even ../ and absolute keys stay contained.
name := fmt.Sprintf("%06d.bin", number)
if err := os.Rename(tmp.Name(), filepath.Join(directory, name)); err != nil {
return err
}
fmt.Printf("%s\t%q\t%d bytes\n", name, object.Name(), n)
return nil
}
func importPrefix(ctx context.Context, client *b2.Client, bucketName, prefix, parent string) (string, error) {
bucket, err := client.Bucket(ctx, bucketName)
if err != nil {
return "", err
}
if bucket == nil {
return "", errors.New("bucket lookup returned no bucket")
}
directory, err := os.MkdirTemp(parent, "b2-import-")
if err != nil {
return "", err
}
// Keep successful files after a later error. Never erase an earlier import.
iterator := bucket.List(ctx, b2.ListPrefix(prefix), b2.ListPageSize(2))
number := 0
for iterator.Next() {
if err := ctx.Err(); err != nil {
return directory, err
}
number++
if err := importObject(ctx, iterator.Object(), directory, number); err != nil {
return directory, fmt.Errorf("object %d: %w", number, err)
}
}
if err := iterator.Err(); err != nil {
return directory, err
}
if err := ctx.Err(); err != nil {
return directory, err
}
fmt.Printf("Imported %d verified files\n", number)
return directory, nil
}
func run() error {
if len(os.Args) != 4 {
return errors.New("usage: backblaze-import BUCKET PREFIX EXISTING_LOCAL_PARENT")
}
if os.Args[1] == "" || os.Args[2] == "" {
return errors.New("bucket and prefix must be nonempty")
}
keyID, key := os.Getenv("B2_KEY_ID"), os.Getenv("B2_APPLICATION_KEY")
if keyID == "" || key == "" {
return errors.New("set B2_KEY_ID and B2_APPLICATION_KEY")
}
timeout := 30 * time.Minute
if value := os.Getenv("B2_IMPORT_TIMEOUT"); value != "" {
var err error
timeout, err = time.ParseDuration(value)
if err != nil || timeout <= 0 {
return errors.New("B2_IMPORT_TIMEOUT must be a positive duration, such as 30m")
}
}
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
defer stop()
ctx, cancel := context.WithTimeout(ctx, timeout)
defer cancel()
client, err := b2.NewClient(ctx, keyID, key)
if err != nil {
return err
}
directory, err := importPrefix(ctx, client, os.Args[1], os.Args[2], os.Args[3])
if directory != "" {
fmt.Fprintln(os.Stderr, "Import directory:", directory)
}
return err
}
func main() {
if err := run(); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
}
(
cd backblaze-import &&
GOWORK=off GOTOOLCHAIN=local go build -o backblaze-import . &&
./backblaze-import "${B2_BUCKET:?Set B2_BUCKET}" "${B2_PREFIX:?Set B2_PREFIX}" "${LOCAL_PARENT:?Set LOCAL_PARENT}"
)
コマンドはインポート先ディレクトリを標準エラー出力に表示します。標準出力には、各連番ファイルに対応する引用符付きの B2 キーとバイト数を表示し、成功時には最後に Imported N verified files を表示します。終了ステータスがゼロなら、一覧取得で返されたすべてのオブジェクトが検証に合格したことを示します。プレフィックスに一致するオブジェクトがなければ、ファイル数ゼロのインポートとして成功します。元の名前が必要な場合は、この対応表をファイルと一緒に保管してください。
ディレクトリとバッチインポートのベストプラクティス
B2 のオブジェクト名はキーであり、信頼できるファイルシステムのパスではありません。この例では連番の .bin ファイルを書き込み、各ローカルファイル名と引用符付きのリモートキーの対応表を出力します。そのため、../report や /absolute/path という名前のオブジェクトでも、新しいインポート先ディレクトリの外には書き込めません。イテレーターは後続ページを自動取得します。反復処理の後には iterator.Err() を確認する必要があります。この例では、少数のオブジェクトでもページ分割を試せるよう、ページごとに二つの名前を要求します。大きなページより一覧取得リクエストは増えますが、インポートするオブジェクト数は制限しません。
エラー処理とデバッグによる円滑なファイル転送
Blazer は、HTTP リトライの分類とトークンの更新を内部で処理します。その外側に無条件のリトライループを追加しないでください。権限不足やバケットが存在しない場合は、エラーを返す必要があります。すべての SDK 呼び出しは、全体で三十分の期限を持つキャンセル可能なコンテキストを共有します。この期限には、認証、ストリーミングされる本文、SDK のバックオフ待機も含まれます。転送が遅い場合は、ファイルサイズに関係なく期限に達することがあります。失敗したオブジェクトの一時ファイルは削除しますが、それ以前に成功したオブジェクトは残ります。インポート全体に別の期限が必要な場合は、コマンドを実行する前に
B2_IMPORT_TIMEOUT を 2h などの正の Go の期間値に設定してください。実行可能ファイルのビルドは、このタイマーの開始前に行います。
大容量ファイル転送の進捗追跡
プログラムは、検証済みファイルごとに一つの完了レコードを出力します。それまでに受信したバイトを、インポート完了として扱うことはありません。B2 の大容量ファイル用インターフェースでアップロードされたオブジェクトには、ファイル全体の SHA-1 がない場合があります。この例では、未検証データを検証済みと報告せず、明示的に失敗します。
よくある問題とトラブルシューティングのヒント
インポート中は、インポート元のプレフィックスに一致する内容を変更しないでください。一覧取得は、変化するバケットのアトミックなスナップショットではありません。サイズとチェックサムの検証は各ダウンロード中の内容変更を検出しますが、一覧自体を固定するものではありません。
メモリ管理
SDK のリーダーは、同時ダウンロード数を一つとし、1 MiB のチャンクを使用します。ファイルはバイトスライスに蓄積せず、ディスクにストリーミングします。オブジェクトは一度に一つだけ処理し、成功時も失敗時も各リーダーを閉じます。
レート制限
オブジェクトを順次処理することで、リクエストの並行数を制限します。固定したバージョンのクライアントは、リトライ可能な応答に対してバックオフを適用します。待機時間の合計は、コンテキスト全体の期限で制限されます。アカウントが継続的にスロットリングされる場合は、処理量を減らすか、制限を解消した後に改めて実行してください。
ネットワーク切断への対応
Ctrl+C は、実際の SDK リクエストとリトライ待機をキャンセルします。ダウンロードによる書き込みを続けたまま goroutine を放置する方式ではありません。後で再実行すると、前のバッチの部分的な結果を上書きせず、新しいインポート先ディレクトリを作成します。
オブジェクトの順次ダウンロードの維持
測定結果からオブジェクトの並列インポートが妥当と判断できない限り、このバッチループは順次処理のままにしてください。SDK は、Reader.ConcurrentDownloads を通じて、上限付きのチャンク並行処理をすでに提供しています。この値を増やすとメモリ消費とリクエスト負荷も増えますが、アカウント全体のリクエストレート制限にはなりません。
バケットのプロビジョニングの分離
ローカル出力を作成する前に、既存のバケットを解決してください。バケットが存在しない場合や権限が不足する場合はエラーを返し、nil バケットも防御的に拒否します。バケットの作成とライフサイクルの変更は、別のプロビジョニング処理で行います。これにより、インポート時の入力ミスによって意図しないリソースが作成されるのを防ぎます。
次のステップの選択
Go アプリケーションで B2 の Native API から検証済みのローカルコピーを取得する場合は、このコマンドを使用してください。次にホスト型の処理ワークフローを利用する場合は、Transloadit のファイルインポートサービスで、利用可能なインポート方法を確認できます。
