Object Storage Service:OSS SDK for Go 2.0

クイック統合

以下は、OSS SDK for Go 2.0 を統合するプロセスです。

環境準備

Go 1.18 以降が必要です。

go -version コマンドを使用して Go のバージョンを確認できます。ご利用の環境に Go がインストールされていない場合、またはバージョンが Go 1.18 より低い場合は、Golang をインストールしてください。

OSS SDK for Go のインストール

• プロジェクトディレクトリを作成し、Go モジュールを初期化します。

  mkdir oss-go-example && cd oss-go-example && go mod init oss-go-example

• 次のコマンドを実行して、OSS SDK for Go パッケージを取得します。以下のコード例が正常に実行されるように、最新バージョンを使用することを推奨します。

  go get github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss

• 次のコードを実行して、OSS SDK for Go 2.0 パッケージをインポートします。

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

クライアントの初期化

リージョンとエンドポイントを使用して OSSClient を初期化し、テストコードを実行します。

package main

import (
	"context"
	"log"
	"strings"

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

/*
Go SDK V2 クライアント初期化設定の説明：

1. 署名バージョン：Go SDK V2 はデフォルトで V4 署名を使用し、より高いセキュリティを提供します
2. リージョン設定：Client を初期化する際、リクエストを発信するリージョンの識別子として Alibaba Cloud の汎用リージョン ID を指定する必要があります
   このサンプルコードでは、中国 (杭州) リージョン ID：cn-hangzhou を使用します
   他のリージョン ID を照会するには、「OSS のリージョンとエンドポイント」をご参照ください
3. エンドポイント設定：
   - Endpoint パラメーターを通じて、サービスリクエストのアクセスドメイン名をカスタマイズできます
   - 指定しない場合、SDK はリージョン情報に基づいてパブリックネットワークのアクセスドメイン名を構築します
   - 例えば、リージョンが 'cn-hangzhou' の場合、構築されるアクセスドメイン名は 'https://oss-cn-hangzhou.aliyuncs.com' です
4. プロトコル設定：
   - SDK はアクセスドメイン名を構築する際に、デフォルトで HTTPS プロトコルを使用します
   - HTTP プロトコルを使用するには、ドメイン名を指定する際に HTTP を指定してください。例：'http://oss-cn-hangzhou.aliyuncs.com'
*/

func main() {
	// 方法 1：リージョンのみを指定 (推奨)
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou") // バケットが配置されているリージョンを指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョンを cn-hangzhou に設定します。SDK はリージョンに基づいて HTTPS アクセスドメイン名を自動的に構築します

	// 方法 2：リージョンとエンドポイントの両方を指定
	// cfg := oss.LoadDefaultConfig().
	//     WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
	//     WithRegion("cn-hangzhou").                                // バケットが配置されているリージョンを指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョンを cn-hangzhou に設定します
	//     WithEndpoint("https://oss-cn-hangzhou.aliyuncs.com")     // バケットが配置されているリージョンのパブリックエンドポイントを指定します。例えば、バケットが中国 (杭州) リージョンにある場合、エンドポイントを 'https://oss-cn-hangzhou.aliyuncs.com' に設定します

	// OSSClient インスタンスを作成します
	client := oss.NewClient(cfg)

	// アップロードしたい文字列を指定します
	body := strings.NewReader("hi oss")

	// オブジェクトをアップロードするリクエストを作成します
	request := &oss.PutObjectRequest{
		Bucket: oss.Ptr("Your Bucket Name"),      // バケット名
		Key:    oss.Ptr("Your Object Key"),       // オブジェクト名
		Body:   body,                             // アップロードする文字列コンテンツ
	}

	// リクエストを実行してオブジェクトをアップロードします
	result, err := client.PutObject(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to put object %v", err)
	}

	// オブジェクトアップロード操作の結果を表示します
	log.Printf("Status: %#v\n", result.Status)
	log.Printf("RequestId: %#v\n", result.ResultCommon.Headers.Get("X-Oss-Request-Id"))
	log.Printf("ETag: %#v\n", *result.ETag)
}

実行後、ファイルアップロードの成功結果が出力されます。

Status: "200 OK"
RequestId: "68746C5FE001B434303B90B6"
ETag: "B22E0DC370A7F7067FACF5F75D7FA385"

クライアント設定

カスタムドメイン名の使用

デフォルトの OSS ドメイン名でアクセスすると、ファイルへのアクセスが禁止されたり、ファイルのプレビューに失敗したりする問題が発生する可能性があります。デフォルトのバケットドメイン名にカスタムドメイン名をバインドすることで、ブラウザでファイルを直接プレビューできるだけでなく、CDN と組み合わせて高速配信することもできます。

package main

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

func main() {
	// バケットが配置されているリージョンを指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョンを cn-hangzhou に設定します
	// カスタムドメイン名を指定します。例：https://www.example-***.com
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou").
		WithEndpoint("https://www.example-***.com").
		WithUseCName(true) // CNAME を有効にするには、このパラメーターを true に設定します。そうしないと、カスタムドメイン名を使用できません

	// OSSClient インスタンスを作成します
	client := oss.NewClient(cfg)
	// クライアントを使用して後続の操作を実行します...
}

タイムアウト制御

package main

import (
	"time"

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

func main() {
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou").             // バケットが配置されているリージョンを指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョンを cn-hangzhou に設定します
		WithConnectTimeout(10 * time.Second).  // 接続タイムアウト期間を指定します。デフォルト値：5 秒
		WithReadWriteTimeout(30 * time.Second) // 読み書きタイムアウト期間を指定します。デフォルト値：10 秒

	// OSSClient インスタンスを作成します
	client := oss.NewClient(cfg)
	// クライアントを使用して後続の操作を実行します...
}

最大エラーリトライ回数

デフォルトでは、OSSClient はリクエスト例外が発生した場合に 3 回リトライします。

高い同時実行性や不安定なネットワークシナリオでは、WithRetryMaxAttempts を使用してリトライ回数を増やします。これにより、リクエストの成功率が向上します。

package main

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

func main() {
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou"). // バケットが配置されているリージョンを指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョンを cn-hangzhou に設定します
		WithRetryMaxAttempts(5)    // 最大リトライ回数を設定します。デフォルト値：3

	// OSSClient インスタンスを作成します
	client := oss.NewClient(cfg)
	// クライアントを使用して後続の操作を実行します...
}

HTTP/HTTPS プロトコル

WithDisableSSL(true) を使用して HTTPS プロトコルを無効にします。

package main

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

func main() {
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou"). // バケットが配置されているリージョンを指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョンを cn-hangzhou に設定します
		WithDisableSSL(true)       // HTTPS プロトコルを使用しないように設定します。デフォルトでは HTTPS が使用されます

	// OSSClient インスタンスを作成します
	client := oss.NewClient(cfg)

	// クライアントを使用して後続の操作を実行します...
}

プロキシサーバー

企業のセキュリティポリシーでは、パブリックネットワークへの直接アクセスが制限されることがよくあります。WithProxyHost を使用してプロキシサーバーを設定し、OSS にアクセスします。

package main

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

func main() {
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou").                                 // バケットが配置されているリージョンを指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョンを cn-hangzhou に設定します
		WithUserAgent("aliyun-sdk-go").                            // HTTP User-Agent ヘッダーを指定するユーザーエージェントを設定します
		WithProxyHost("http://user:passswd@proxy.example-***.com") // プロキシサーバーの IP を設定します。例："http://user:passswd@proxy.example-***.com"

	// OSSClient インスタンスを作成します
	client := oss.NewClient(cfg)
	// クライアントを使用して後続の操作を実行します...
}

内部エンドポイントの使用

アプリケーションが Elastic Compute Service (ECS) インスタンスにデプロイされており、ECS インスタンスと同じリージョンにあるバケット内の OSS データに頻繁にアクセスする必要がある場合は、内部エンドポイントを使用すると、ネットワーク遅延と帯域幅コストを大幅に削減できます。

package main

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

func main() 
	// 方法 1：リージョンを指定し、WithUseInternalEndpoint を true に設定します
	// バケットが配置されているリージョンを指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョンを cn-hangzhou に設定します
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou").
		WithUseInternalEndpoint(true)

	// 方法 2：リージョンとエンドポイントを直接指定します
	// バケットが配置されているリージョンを指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョンを cn-hangzhou に設定します
	// バケットが配置されているリージョンの内部エンドポイントを指定します。例えば、バケットが中国 (杭州) リージョンにある場合、エンドポイントを 'https://oss-cn-hangzhou-internal.aliyuncs.com' に設定します。HTTP プロトコルを使用するには、エンドポイントを 'http://oss-cn-hangzhou-internal.aliyuncs.com' に設定します
	// cfg := oss.LoadDefaultConfig().
	// 	WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
	// 	WithRegion("cn-hangzhou").
	// 	WithEndpoint("https://oss-cn-hangzhou-internal.aliyuncs.com")

	// OSSClient インスタンスを作成します
	client := oss.NewClient(cfg)

	// クライアントを使用して後続の操作を実行します...

}

アクセラレーションエンドポイントの使用

package main

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

func main() {
	// 方法 1：リージョンを指定し、WithUseAccelerateEndpoint を true に設定します
	// バケットが配置されているリージョンを指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョンを cn-hangzhou に設定します
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou").
		WithUseAccelerateEndpoint(true)

	// 方法 2：リージョンとエンドポイントを直接指定します
	// バケットが配置されているリージョンを指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョンを cn-hangzhou に設定します
	// バケットが配置されているリージョンのアクセラレーションエンドポイントを指定します。例えば、バケットが中国 (杭州) リージョンにある場合、エンドポイントを https://oss-accelerate.aliyuncs.com に設定します。HTTP プロトコルを使用するには、エンドポイントを http://oss-accelerate.aliyuncs.com に設定します
	// cfg := oss.LoadDefaultConfig().
	// 	WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
	// 	WithRegion("cn-hangzhou").
	// 	WithEndpoint("https://oss-accelerate.aliyuncs.com").

	// OSSClient インスタンスを作成します
	client := oss.NewClient(cfg)
	// クライアントを使用して後続の操作を実行します...
}

プライベートドメインの使用

package main

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

func main() {
	// バケットが配置されているリージョンを指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョンを cn-hangzhou に設定します
	// プライベートドメインを指定します。例：https://service.corp.example.com
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou").
		WithEndpoint("https://service.corp.example.com")

	// OSSClient インスタンスを作成します
	client := oss.NewClient(cfg)
	// クライアントを使用して後続の操作を実行します...
}

Alibaba Gov Cloud エンドポイントの使用

以下は、Alibaba Gov Cloud エンドポイントで OSSClient を設定する例です。

package main

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

func main() {
	// リージョンとエンドポイントを指定します
        // バケットが配置されているリージョンを指定します。例えば、バケットが中国北部 2 Ali Gov 1 リージョンにある場合、リージョンを cn-north-2-gov-1 に設定します
	// バケットが配置されているリージョンの内部エンドポイントを指定します。例えば、バケットが中国北部 2 Ali Gov 1 リージョンにある場合、エンドポイントを 'https://oss-cn-north-2-gov-1-internal.aliyuncs.com' に設定します
        // HTTP プロトコルを使用するには、エンドポイントを 'http://oss-cn-north-2-gov-1-internal.aliyuncs.com' に設定します
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-north-2-gov-1").
		WithEndpoint("https://oss-cn-north-2-gov-1-internal.aliyuncs.com")

	// OSSClient インスタンスを作成します
	client := oss.NewClient(cfg)
	// クライアントを使用して後続の操作を実行します...
}

CloudBox バケットへのアクセス

package main

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

func main() {
	// 方法 1：CloudBox ID を自動的に検出します
	// バケットが配置されているリージョンを指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョンを cn-hangzhou に設定します
	// エンドポイントを CloudBox バケットのデータドメイン名に設定します。例：http://cb-xxxxxx.cn-hangzhou.oss-cloudbox.aliyuncs.com
	// WithEnableAutoDetectCloudBoxId を true に設定して、CloudBox ID を自動的に検出します
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithEndpoint("http://cb-xxxxxx.cn-hangzhou.oss-cloudbox.aliyuncs.com").
		WithEnableAutoDetectCloudBoxId(true)

	// 方法 2：CloudBox ID を手動で設定します
	// バケットが配置されているリージョンを指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョンを cn-hangzhou に設定します
	// エンドポイントを CloudBox バケットのデータドメイン名に設定します。例：http://cb-xxxxxx.cn-hangzhou.oss-cloudbox.aliyuncs.com
	// CloudBox ID を手動で入力します。例：cb-xxxxxx
	// cfg := oss.LoadDefaultConfig().
	// 	WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
	// 	WithEndpoint("http://cb-xxxxxx.cn-hangzhou.oss-cloudbox.aliyuncs.com").
	// 	WithCloudBoxId("cb-xxxxxx")

	// OSSClient インスタンスを作成します
	client := oss.NewClient(cfg)
	// クライアントを使用して後続の操作を実行します...
}

カスタム HTTPClient

一般的な設定パラメーターがシナリオの要件を満たせない場合は、WithHTTPClient を使用してデフォルトの HTTP クライアントを置き換えます。

package main

import (
	"crypto/tls"
	"net/http"
	"time"

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

func main() {
	// 一般的なタイムアウト期間やその他のパラメーターを指定します
	transConfig := transport.Config{
		// 接続のタイムアウト期間を指定します。デフォルト値：5。単位：秒
		ConnectTimeout: oss.Ptr(10 * time.Second),
		// アプリケーションがデータを読み書きするタイムアウト期間を指定します。デフォルト値：10。単位：秒
		ReadWriteTimeout: oss.Ptr(20 * time.Second),
		// アイドル接続のタイムアウト期間を指定します。デフォルト値：50。単位：秒
		IdleConnectionTimeout: oss.Ptr(40 * time.Second),
		// ネットワーク接続の保持期間を指定します。デフォルト値：30。単位：秒
		KeepAliveTimeout: oss.Ptr(40 * time.Second),
		// HTTP リダイレクトを有効にするかどうかを指定します。デフォルトでは、HTTP リダイレクトは無効です
		EnabledRedirect: oss.Ptr(true),
	}

	// http.Transport の設定
	var transports []func(*http.Transport)
	// 最大接続数を指定します。デフォルト値：100
	transports = append(transports, transport.MaxConnections(200))
	// リクエストに Expect: 100-Continue ヘッダーが含まれている場合、リクエストヘッダーが完全に書き込まれた後、サーバーから返される最初のレスポンスヘッダーを待つ最大期間を示します。デフォルト値：1。単位：秒
	transports = append(transports, transport.ExpectContinueTimeout(2*time.Second))
	// Transport Layer Security (TLS) の最も古いバージョンを指定します。デフォルト値：TLS 1.2
	transports = append(transports, transport.TLSMinVersion(tls.VersionTLS13))
	// SSL 証明書検証をスキップするかどうかを指定します。デフォルトでは、SSL 証明書は検証されます
	transports = append(transports, transport.InsecureSkipVerify(true))
	// その他の Transport パラメーター設定については、https://pkg.go.dev/net/http#Transport をご参照ください
	// カスタム HTTP Client を作成します
	customClient := transport.NewHttpClient(&transConfig, transports...)

	cfg := oss.LoadDefaultConfig().
		WithHttpClient(customClient).
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou")

	// OSSClient インスタンスを作成します
	client := oss.NewClient(cfg)
	// クライアントを使用して後続の操作を実行します...
}

アクセス認証情報の設定

OSS は複数の認証情報初期化メソッドを提供しています。認証と権限付与の要件に基づいて、適切な初期化メソッドを選択してください。

RAM ユーザーの AK の使用

アプリケーションが外部からの攻撃を受けにくい安全で安定した環境にデプロイされており、OSS に長期間アクセスする必要がある場合は、Alibaba Cloud アカウントまたは RAM ユーザーの AccessKey ペアを使用して認証情報プロバイダーを初期化できます。AccessKey ペアは、AccessKey ID と AccessKey Secret で構成されます。この方法では、AccessKey ペアを手動でメンテナンスする必要があり、セキュリティリスクとメンテナンスの複雑さが増すことに注意してください。

package main

import (
	"log"

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

func main() {
	// 必要に応じて、バケットが配置されているリージョンの ID を指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョン ID を cn-hangzhou に設定します
	region := "cn-hangzhou"

	// RAM ユーザーの AccessKey ID と AccessKey Secret を指定します
	accessKeyID := "yourAccessKeyID"
	accessKeySecret := "yourAccessKeySecret"

	// NewStaticCredentialsProvider メソッドを使用して、AccessKey ID と AccessKey Secret を直接設定します
	provider := credentials.NewStaticCredentialsProvider(accessKeyID, accessKeySecret)

	// デフォルトの設定を読み込み、認証情報プロバイダーとリージョンを指定します
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(provider).
		WithRegion(region)

	// OSSClient インスタンスを作成します
	client := oss.NewClient(cfg)

	log.Printf("ossclient: %v", client)
}

STS 一時アクセス認証情報の使用

アプリケーションが一時的に OSS にアクセスする必要がある場合、Security Token Service (STS) から取得した一時アクセス認証情報を使用できます。これには、AccessKey ペアとセキュリティトークンが含まれます。この方法では、セキュリティトークンを手動でメンテナンスする必要があり、セキュリティリスクとメンテナンスの複雑さが増すことに注意してください。既存の STS トークンの有効期限が切れた後もアクセスを延長したい場合は、STS トークンを手動でリフレッシュする必要があります。

package main

import (
	"log"

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

func main() {
	// 必要に応じて、バケットが配置されているリージョンの ID を指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョン ID を cn-hangzhou に設定します
	region := "cn-hangzhou"

	// RAM ユーザーの AccessKey ID と AccessKey Secret ではなく、STS が提供する AccessKey ID、AccessKey Secret、および STS トークンを指定します
        // STS が提供する AccessKey ID は STS で始まります
	accessKeyID := "STS.****************"
	accessKeySecret := "yourAccessKeySecret"
	// STS トークン (SecurityToken) を指定します
	stsToken := "yourSecurityToken"

	// NewStaticCredentialsProvider メソッドを使用して、AccessKey ID、AccessKey Secret、および STS トークンを直接設定します
	provider := credentials.NewStaticCredentialsProvider(accessKeyID, accessKeySecret, stsToken)

	// デフォルトの設定を読み込み、認証情報プロバイダーとリージョンを指定します
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(provider).
		WithRegion(region)

	// OSSClient インスタンスを作成します
	client := oss.NewClient(cfg)

	log.Printf("ossclient: %v", client)
}

RAMRoleARN の使用

アプリケーションが別の Alibaba Cloud アカウントの OSS リソースにアクセスする必要がある場合など、アプリケーションに OSS へのアクセスを許可するには、RAMRoleARN を使用して認証情報プロバイダーを初期化できます。このメソッドの基盤となるロジックは、STS トークンを使用してアクセス認証情報を設定することです。Credentials ツールは、RAM ロールの ARN によって識別される RAM ロールに基づいて STS トークンを取得し、セッションが期限切れになる前に AssumeRole 操作を呼び出して STS トークンをリフレッシュします。さらに、policy に値を割り当てることで、RAM ロールをより小さな権限セットに制限できます。

1. 認証情報の依存関係を追加します。

   go get github.com/aliyun/credentials-go/credentials

2. アクセス認証情報を設定します。

   package main
   
   import (
   	"context"
   	"log"
   	"os"
   
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
   	openapicred "github.com/aliyun/credentials-go/credentials"
   )
   
   func main() {
   	// 必要に応じて、バケットが配置されているリージョンの ID を指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョン ID を cn-hangzhou に設定します
   	region := "cn-hangzhou"
   
   	config := new(openapicred.Config).
   		// 認証情報タイプを ram_role_arn に設定します
   		SetType("ram_role_arn").
   		// 環境変数から RAM ユーザーの AccessKey ID と AccessKey Secret を取得します
   		SetAccessKeyId(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")).
   		SetAccessKeySecret(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")).
   		// デフォルトでは、以下の操作のパラメーターの値は直接入力されます。環境変数を追加し、os.Getenv("<変数名>") を使用して対応するパラメーターを指定することもできます
   		// 環境変数から RAM ロールの ARN を取得します。ARN は、引き受けるロールの ID であり、acs:ram::$accountID:role/$roleName の形式です
   		SetRoleArn("ALIBABA_CLOUD_ROLE_ARN"). // デフォルトでは、RoleArn 環境変数の CNAME は ALIBABA_CLOUD_ROLE_ARN です
   		// 異なるトークンを区別するために、ロールのカスタムセッション名を指定します
   		SetRoleSessionName("ALIBABA_CLOUD_ROLE_SESSION_NAME"). // デフォルトでは、RoleSessionName 環境変数の CNAME は ALIBABA_CLOUD_ROLE_SESSION_NAME です
   		// オプション。セキュリティトークンの権限を指定します
   		SetPolicy("Policy").
   		// オプション。セキュリティトークンの有効期間を指定します
   		SetRoleSessionExpiration(3600)
   
   	arnCredential, gerr := openapicred.NewCredential(config)
   	provider := credentials.CredentialsProviderFunc(func(ctx context.Context) (credentials.Credentials, error) {
   		if gerr != nil {
   			return credentials.Credentials{}, gerr
   		}
   		cred, err := arnCredential.GetCredential()
   		if err != nil {
   			return credentials.Credentials{}, err
   		}
   		return credentials.Credentials{
   			AccessKeyID:     *cred.AccessKeyId,
   			AccessKeySecret: *cred.AccessKeySecret,
   			SecurityToken:   *cred.SecurityToken,
   		}, nil
   	})
   
   	// デフォルトの設定を読み込み、認証情報プロバイダーとリージョンを指定します
   	cfg := oss.LoadDefaultConfig().
   		WithCredentialsProvider(provider).
   		WithRegion(region)
   
   	// OSSClient インスタンスを作成します
   	client := oss.NewClient(cfg)
   	log.Printf("ossclient: %v", client)
   }
   

ECSRAMRole の使用

アプリケーションが ECS インスタンス、ECI インスタンス、または Container Service for Kubernetes (ACK) ワーカーノードで実行される場合、ECSRAMRole を使用して認証情報プロバイダーを初期化することを推奨します。このメソッドの基盤となるロジックは、STS トークンを使用することです。ECSRAMRole を使用すると、ロールを ECS インスタンス、ECI インスタンス、または ACK ワーカーノードに関連付けて、インスタンス内で STS トークンを自動的にリフレッシュできます。この方法では、AccessKey ペアや STS トークンを提供する必要がないため、これらの認証情報を手動で管理することに伴うリスクが排除されます。ECSRAMRole の取得方法の詳細については、「CreateRole - ロールの作成」をご参照ください。

1. 認証情報の依存関係を追加します。

   go get github.com/aliyun/credentials-go/credentials

2. アクセス認証情報を設定します。

   package main
   
   import (
   	"context"
   	"log"
   
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
   	openapicred "github.com/aliyun/credentials-go/credentials"
   )
   
   func main() {
   	// 必要に応じて、バケットが配置されているリージョンの ID を指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョン ID を cn-hangzhou に設定します
   	region := "cn-hangzhou"
   
   	config := new(openapicred.Config).
   		// 認証情報タイプを ecs_ram_role に設定します
   		SetType("ecs_ram_role").
   		// オプション。ロール名を指定します。ロール名を指定しない場合、OSS は自動的にロール名を取得します。リクエスト数を減らすために、ロール名を指定することを推奨します
   		SetRoleName("RoleName")
   
   	arnCredential, gerr := openapicred.NewCredential(config)
   	provider := credentials.CredentialsProviderFunc(func(ctx context.Context) (credentials.Credentials, error) {
   		if gerr != nil {
   			return credentials.Credentials{}, gerr
   		}
   		cred, err := arnCredential.GetCredential()
   		if err != nil {
   			return credentials.Credentials{}, err
   		}
   		return credentials.Credentials{
   			AccessKeyID:     *cred.AccessKeyId,
   			AccessKeySecret: *cred.AccessKeySecret,
   			SecurityToken:   *cred.SecurityToken,
   		}, nil
   	})
   
   	// デフォルトの設定を読み込み、認証情報プロバイダーとリージョンを指定します
   	cfg := oss.LoadDefaultConfig().
   		WithCredentialsProvider(provider).
   		WithRegion(region)
   
   	// OSSClient インスタンスを作成します
   	client := oss.NewClient(cfg)
   	log.Printf("ossclient: %v", client)
   }
   

OIDCRoleARN の使用

Container Service for Kubernetes (ACK) のワーカーノードに RAM ロールをアタッチすると、そのノード上の Pod 内のアプリケーションは、ECS インスタンスにデプロイされたアプリケーションと同様に、メタデータサービスからアタッチされたロールの Security Token Service (STS) トークンを取得できます。ただし、コンテナークラスターに信頼できないアプリケーション (顧客から提出されたコードが利用できないアプリケーションなど) がデプロイされている場合、これらのアプリケーションがワーカーノードにアタッチされた RAM ロールの STS トークンをメタデータサービスから取得することを望まない場合があります。クラウドリソースのセキュリティを確保し、これらの信頼できないアプリケーションが必要な STS トークンを安全に取得できるようにし、アプリケーションレベルで最小権限の原則を実装するには、RAM Roles for Service Account (RRSA) 機能を使用できます。このメソッドの基盤となるロジックは、STS トークンを使用することです。ACK は、異なるアプリケーション Pod に対して対応するサービスアカウント OpenID Connect (OIDC) トークンファイルを作成してマウントし、関連する設定情報を環境変数に注入します。Credentials ツールは、環境変数から設定情報を取得し、STS の AssumeRoleWithOIDC 操作を呼び出して、アタッチされたロールの STS トークンを取得します。この方法では、AccessKey (AK) ペアや STS トークンを提供する必要がないため、AK ペアや STS トークンを手動でメンテナンスすることに伴うリスクが排除されます。詳細については、「RRSA を使用して ServiceAccount の RAM 権限を設定し、Pod の権限を分離する」をご参照ください。

1. 認証情報の依存関係を追加します。

   go get github.com/aliyun/credentials-go/credentials

2. アクセス認証情報を設定します。

   package main
   
   import (
   	"context"
   	"log"
   
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
   	openapicred "github.com/aliyun/credentials-go/credentials"
   )
   
   func main() {
   	// 必要に応じて、バケットが配置されているリージョンの ID を指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョン ID を cn-hangzhou に設定します
   	region := "cn-hangzhou"
   
   	config := new(openapicred.Config).
   		// 認証情報タイプを oidc_role_arn に設定します
   		SetType("oidc_role_arn").
   		// OIDC IdP の ARN を指定します。ARN は acs:ram::account-id:oidc-provider/provider-name 形式です
   		SetOIDCProviderArn("OIDCProviderArn").
   		// OIDC トークンが保存されているファイルのパスを指定します
   		SetOIDCTokenFilePath("OIDCTokenFilePath").
   		// 異なるトークンを区別するために、ロールのカスタムセッション名を指定します
   		SetRoleSessionName("RoleSessionName"). // デフォルトでは、RoleSessionName 環境変数の CNAME は ALIBABA_CLOUD_ROLE_SESSION_NAME です
   		// オプション。RAM ロールのポリシーを指定します
   		SetPolicy("Policy").
   		// 引き受けるロールの ID である RAM ロールの ARN を指定します。フォーマット：acs:ram::113511544585****:oidc-provider/TestOidcProvider
   		SetRoleArn("RoleArn").
   		// セッションの有効期間を指定します
   		SetSessionExpiration(3600)
   
   	arnCredential, gerr := openapicred.NewCredential(config)
   	provider := credentials.CredentialsProviderFunc(func(ctx context.Context) (credentials.Credentials, error) {
   		if gerr != nil {
   			return credentials.Credentials{}, gerr
   		}
   		cred, err := arnCredential.GetCredential()
   		if err != nil {
   			return credentials.Credentials{}, err
   		}
   		return credentials.Credentials{
   			AccessKeyID:     *cred.AccessKeyId,
   			AccessKeySecret: *cred.AccessKeySecret,
   			SecurityToken:   *cred.SecurityToken,
   		}, nil
   	})
   
   	// デフォルトの設定を読み込み、認証情報プロバイダーとリージョンを指定します
   	cfg := oss.LoadDefaultConfig().
   		WithCredentialsProvider(provider).
   		WithRegion(region)
   
   	// OSSClient インスタンスを作成します
   	client := oss.NewClient(cfg)
   	log.Printf("ossclient: %v", client)
   }
   

カスタム認証情報プロバイダー

上記の認証情報設定方法がビジネス要件を満たさない場合は、アクセス認証情報を取得するために使用するメソッドを指定できます。次のメソッドがサポートされています。

1. credentials.CredentialsProviderFunc メソッドを使用

   package main
   
   import (
   	"context"
   	"log"
   
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
   )
   
   func main() {
   	// 必要に応じて、バケットが配置されているリージョンの ID を指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョン ID を cn-hangzhou に設定します
   	region := "cn-hangzhou"
   
   	// 認証情報プロバイダーを作成します
   	provider := credentials.CredentialsProviderFunc(func(ctx context.Context) (credentials.Credentials, error) {
   		// 長期的な認証情報を返します
   		return credentials.Credentials{AccessKeyID: "id", AccessKeySecret: "secret"}, nil
   		// 一時的な認証情報を返します
   		//return credentials.Credentials{AccessKeyID: "id", AccessKeySecret: "secret",    SecurityToken: "token"}, nil
   	})
   
   	// デフォルトの設定を読み込み、認証情報プロバイダーとリージョンを指定します
   	cfg := oss.LoadDefaultConfig().
   		WithCredentialsProvider(provider).
   		WithRegion(region)
   
   	// OSSClient インスタンスを作成します
   	client := oss.NewClient(cfg)
   	log.Printf("ossclient: %v", client)
   }
   

2. credentials.CredentialsProvider インターフェイスを実装

   package main
   
   import (
   	"context"
   	"log"
   
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
   )
   
   type CustomerCredentialsProvider struct {
   	// TODO
   }
   
   func NewCustomerCredentialsProvider() CustomerCredentialsProvider {
   	return CustomerCredentialsProvider{}
   }
   
   func (s CustomerCredentialsProvider) GetCredentials(_ context.Context) (credentials.Credentials, error) {
   	// 長期的な認証情報を返します
   	return credentials.Credentials{AccessKeyID: "id", AccessKeySecret: "secret"}, nil
   	// 一時的な認証情報を返します
   	//return credentials.Credentials{AccessKeyID: "id", AccessKeySecret: "secret",    SecurityToken: "token"}, nil
   }
   
   func main() {
   	// 必要に応じて、バケットが配置されているリージョンの ID を指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョン ID を cn-hangzhou に設定します
   	region := "cn-hangzhou"
   
   	// 認証情報プロバイダーを作成します
   	provider := NewCustomerCredentialsProvider()
   
   	// デフォルトの設定を読み込み、認証情報プロバイダーとリージョンを指定します
   	cfg := oss.LoadDefaultConfig().
   		WithCredentialsProvider(provider).
   		WithRegion(region)
   
   	// OSSClient インスタンスを作成します
   	client := oss.NewClient(cfg)
   	log.Printf("ossclient: %v", client)
   }
   

デフォルトの認証情報プロバイダーチェーンの使用

初期化メソッドを指定せずに Credentials クライアントを初期化すると、Credentials ツールはデフォルトの認証情報プロバイダーチェーンを使用します。デフォルトの認証情報プロバイダーチェーンのロジックの詳細については、「デフォルトの認証情報プロバイダーチェーン」をご参照ください。

package main

import (
	"context"
	"log"

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

func main() {
	// 必要に応じて、バケットが配置されているリージョンの ID を指定します。例えば、バケットが中国 (杭州) リージョンにある場合、リージョン ID を cn-hangzhou に設定します
	region := "cn-hangzhou"
	// パラメーターを nil に設定すると、デフォルトの認証情報プロバイダーチェーンが使用され、認証情報が自動的に取得されます
	arnCredential, gerr := credentials.NewCredential(nil)
	provider := osscred.CredentialsProviderFunc(func(ctx context.Context) (osscred.Credentials, error) {
		if gerr != nil {
			return osscred.Credentials{}, gerr
		}
		cred, err := arnCredential.GetCredential()
		if err != nil {
			return osscred.Credentials{}, err
		}

		return osscred.Credentials{
			AccessKeyID:     *cred.AccessKeyId,
			AccessKeySecret: *cred.AccessKeySecret,
			SecurityToken:   *cred.SecurityToken,
		}, nil
	})

	// デフォルトの設定を読み込み、認証情報プロバイダーとリージョンを指定します
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(provider).
		WithRegion(region)

	// OSSClient インスタンスを作成します
	client := oss.NewClient(cfg)
	log.Printf("ossclient: %v", client)
}

トラブルシューティング

Go SDK V2 を使用して OSS にアクセスする際にエラーが発生した場合、OSS は HTTP ステータスコード、エラーメッセージ、リクエスト ID、およびエラーコード (EC) を返します。EC は特定のエラー原因に対応しており、エラーのトラブルシューティングに使用できます。

サンプルコード

OSS Go SDK V2 は、参照または直接使用できるさまざまなサンプルコードを提供しています。