Go クライアント ライブラリのAzure SDKを使用して、Azure サービスに格納されているデータをプログラムで操作する方法について説明します。 管理ライブラリとクライアント ライブラリの連携の概要については、「 Go 管理ライブラリのAzure SDKの概要を参照してください。 この記事では、リソースが既に存在した後に使用する Go データ プレーン パターンに焦点を当て、プロビジョニングと構成作業のための コントロール プレーン操作 を示します。
Azure データ プレーンとは
Azure データ プレーンは、BLOB のアップロード、メッセージの送信、データベースのクエリ、シークレットの取得など、Azure サービス内のデータを操作するために使用する API のセットです。 コントロール プレーンはリソースをプロビジョニングして構成しますが、データ プレーンは実行時にアプリケーション コードが呼び出すものです。 一般的な Go ワークフローは、セットアップまたは自動化でコントロール プレーン コードを 1 回使用し、毎日実行されるアプリケーション パスにデータ プレーン クライアントを保持することです。
Azure SDK for Go は、
-
azidentityパッケージを使用して認証します。 - サービス エンドポイントまたは接続文字列を使用して、型指定されたクライアントを作成します。
- クライアントでメソッドを呼び出して、データの読み取り、書き込み、または処理を行います。
- ページ分割された結果とエラーを処理します。
Go データ プレーン操作の一般的なシナリオは次のとおりです。
- Blob Storageからのファイルのアップロードとダウンロード
- Service Bus または Event Hubs を使用したメッセージの送受信
- Cosmos DB でのドキュメントの格納とクエリ
- Key Vaultからシークレット、キー、証明書を取得する
- Application Insights を使用したアプリケーションのパフォーマンスの監視
認証
データ プレーン操作では、コントロール プレーン操作に使用されるazidentity パッケージと同じ資格情報の種類がサポートされます。 すべての資格情報の種類は、 azcore.TokenCredential インターフェイスを実装するため、クライアント コードを変更せずに入れ替えることができます。
データ プレーン クライアントは、サブスクリプション ID ではなく、サービス エンドポイント (URL または名前空間) と資格情報を取得します。
// Create credential that auto-discovers authentication
cred, err := azidentity.NewDefaultAzureCredential(nil)
// Blob Storage - pass the storage account URL
blobClient, err := azblob.NewClient("https://mystorageaccount.blob.core.windows.net/", cred, nil)
// Key Vault secrets - pass the vault URL
secretClient, err := azsecrets.NewClient("https://mykeyvault.vault.azure.net/", cred, nil)
// Service Bus - pass the fully qualified namespace
sbClient, err := azservicebus.NewClient("mynamespace.servicebus.windows.net", cred, nil)
一部のサービスでは、トークンベースの認証が使用できない環境の接続文字列もサポートされています。
// Connection string authentication (when token auth is not available)
client, err := azservicebus.NewClientFromConnectionString(connectionString, nil)
Azureで実行されている運用ワークロードの場合は、マネージド ID を使用します。 ローカル開発の場合、 DefaultAzureCredential は、 az login、環境変数、またはその他のソースから資格情報を自動的に検出します。
資格情報の種類とベスト プラクティスに関する完全なガイドについては、Authentication with the Azure SDK for Go および azidentity パッケージのドキュメントを参照してください。
改ページ
多くのデータプレーン操作では、サイズが大きくなる可能性のあるコレクションが返されます。 SDK では、次の操作にページングパターンが使用されます。
// Create a pager for listing large result sets
pager := client.NewListSecretPropertiesPager(nil)
// Iterate through pages until no more results
for pager.More() {
page, err := pager.NextPage(ctx)
if err != nil {
return err
}
for _, item := range page.Value {
fmt.Println(*item.ID)
}
}
*Pager型を返すメソッドは、すべてのデータ プレーン パッケージで同じ反復パターンに従います。
改ページやその他の一般的なパターンの詳細については、go のAzure SDKの
エラー処理
データ プレーン操作では、特定のエラー コードを調べることができる構造化エラーが返されます。
import "github.com/Azure/azure-sdk-for-go/sdk/azcore"
// Check if the error is an Azure service error with structured details
var respErr *azcore.ResponseError
if errors.As(err, &respErr) {
fmt.Printf("Error code: %s\n", respErr.ErrorCode)
fmt.Printf("Status code: %d\n", respErr.StatusCode)
}
一般的なデータ プレーンのエラー コードには、 BlobNotFound、 MessageLockLost、 SecretNotFound、および RequestEntityTooLargeが含まれます。 エラー コードの完全な一覧については、各サービスのドキュメントを参照してください。
BLOB のアップロードの例
この例では、運用対応のパターンを示します。 DefaultAzureCredentialを使用して認証する、BLOB クライアントを作成する、タイムアウトでデータをアップロードする、検証する。 このパターンは、すべてのデータ プレーン クライアントに適用されます。 サービス エンドポイントとクライアントの種類をスワップして、Service Bus、Event Hubs、Cosmos DB、またはKey Vaultに合わせて調整します。
package main
import (
"context"
"fmt"
"log"
"time"
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
"github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
)
func main() {
accountURL := "https://<storage-account-name>.blob.core.windows.net/"
containerName := "demo"
blobName := "hello.txt"
data := []byte("hello from Go")
// Create credential that auto-discovers authentication
cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
log.Fatalf("failed to create credential: %v", err)
}
// Set a timeout to prevent hanging on network issues
ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
defer cancel()
// Create a client for the storage account
client, err := azblob.NewClient(accountURL, cred, nil)
if err != nil {
log.Fatalf("failed to create blob client: %v", err)
}
// Upload data directly from a byte slice
_, err = client.UploadBuffer(ctx, containerName, blobName, data, nil)
if err != nil {
log.Fatalf("failed to upload blob: %v", err)
}
fmt.Printf("uploaded %s to container %s\n", blobName, containerName)
}
ブロブ ストレージ
azblob パッケージは、非常にスケーラブルなオブジェクト ストレージ サービスであるAzure Blob Storageへのデータ プレーン アクセスを提供します。 このパッケージは、実行時にアプリケーションがデータの読み取りと書き込みに使用するパッケージです。 ストレージ アカウントとコンテナーをプロビジョニングするには、個別の armstorage コントロール プレーン パッケージを使用します。
これを使用して、ファイルとドキュメントのアップロードとダウンロード、BLOB とコンテナーの一覧表示と管理、メタデータとコンテンツのプロパティの設定、大規模なファイルの並列アップロードの実装、データ処理パイプラインの構築を行います。
go get github.com/Azure/azure-sdk-for-go/sdk/storage/azblob
開始するには、クイックスタート: Go 用 Azure Blob Storage クライアント モジュールを参照してください。
パッケージのドキュメントについては、azblob パッケージ リファレンスを参照してください。
Cosmos DB
azcosmos パッケージは、グローバルに分散されたマルチモデル データベースである Azure Cosmos DB へのデータ プレーン アクセスを提供します。 これを使用して、待機時間の短い読み取りと書き込みを任意の規模で必要とするアプリケーションを構築します。
これを使用して、ドキュメントに対する CRUD 操作の実行、コンテナーに対する SQL クエリの実行、効率的なデータ アクセスのためのパーティション分割戦略の管理、大規模な結果セットに対する改ページ処理の処理、複数項目のバッチ操作の実行を行います。
go get github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos
開始するには、「
パッケージのドキュメントについては、azcosmos パッケージ リファレンスを参照してください。
Event Hubs
azeventhubs パッケージは、Azure Event Hubsへのデータ プレーン アクセスを提供します。これは、高スループットのイベント ストリーミングのためのリアルタイム データ インジェスト サービスです。
これを使用して、効率的なスループットを実現するバッチ処理を使用したイベントの送信、コンシューマー グループを使用したイベントの受信と処理、パーティションの割り当てとチェックポイント処理の管理、並べ替えの保証のためのパーティション キーを使用したイベントのルーティング、ログ インジェストとテレメトリ パイプラインの構築を行います。
go get github.com/Azure/azure-sdk-for-go/sdk/messaging/azeventhubs
開始するには、「 クイック スタート: Go を使用して Event Hubs との間でイベントを送信または受信する」を参照してください。
パッケージのドキュメントについては、azeventhubs パッケージ リファレンスを参照してください。
Key Vault
azsecrets、azkeys、および azcertificates パッケージは、Azure Key Vaultへのデータ プレーン アクセスを提供します。 これらのパッケージは、アプリケーションが実行時にシークレットを取得し、暗号化操作を実行するために使用します。 ボールト インスタンスをプロビジョニングおよび構成するには、個別の armkeyvault コントロール プレーン パッケージを使用します。
シークレットの取得と設定 (データベース パスワード、API キー)、署名と暗号化のための暗号化キーの作成と管理、自動更新による TLS/SSL 証明書の管理、シークレット バージョンの追跡、ローテーション戦略の実装、待機時間と API 呼び出しを減らすシークレットのキャッシュを行うために使用します。
go get github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azsecrets
go get github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azkeys
go get github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azcertificates
Key Vaultの使用を開始するには、Quickstart: Azure Key Vault の Go 証明書クライアント ライブラリを参照してください。
パッケージのドキュメントについては、azsecrets、azkeys、および azcertificates パッケージ参照を参照してください。
Service Bus
azservicebus パッケージは、Azure Service Bus (信頼性の高い非同期通信用のフル マネージド メッセージ ブローカー) へのデータ プレーン アクセスを提供します。
これを使用して、ポイントツーポイント通信向けのキューでメッセージを送受信し、ファンアウトパターン用のトピックの発行とサブスクライブを行い、効率的なスループットのためにメッセージをバッチで送信し、将来の配信のスケジュールを設定し、メッセージの完了および破棄によって長期ポーリング消費者を実装します。
go get github.com/Azure/azure-sdk-for-go/sdk/messaging/azservicebus
Azure Service Busの概要については、「Quickstart: Azure Service Bus キューとの間でメッセージを送受信する (Go)を参照してください。
パッケージのドキュメントについては、azservicebus パッケージ リファレンスを参照してください。
Application Insights
ApplicationInsights-Go モジュールは、Azure アプリケーション Insights - Azure のアプリケーション パフォーマンス監視 (APM) サービスとのテレメトリ統合を提供します。
これを使用して、カスタム イベントとメトリックの追跡、API の応答時間とエラーの監視、サービス間での分散トレースの実装、コンテキスト プロパティを使用した例外のログ記録、サンプリングによるテレメトリ ボリュームの制御を行います。
go get github.com/microsoft/ApplicationInsights-Go
サービスのドキュメントについては、 Application Insights の概要を参照してください。