クイックスタート: Azure SDK for Go で Azure Cosmos DB for NoSQL を使用する
このクイックスタートでは、Azure SDK for Go を使って、基本的な Azure Cosmos DB for Table アプリケーションをデプロイします。 Azure Cosmos DB for Table はスキーマレス データ ストアであり、これによりアプリケーションは構造化されたテーブル データをクラウドに保存できます。 Azure SDK for Go を使用して、Azure Cosmos DB リソース内でテーブル、行を作成し、基本的なタスクを実行する方法を学習します。
API のリファレンス ドキュメント | ライブラリのソース コード | パッケージ (Go) | Azure Developer CLI
前提条件
- Azure Developer CLI
- Docker Desktop
-
Go1.21 以降
Azure アカウントをお持ちでない場合は、開始する前に無料アカウントを作成してください。
プロジェクトを初期化する
Azure Developer CLI (azd) を使用して、Azure Cosmos DB for Table アカウントを作成し、コンテナー化されたサンプル アプリケーションをデプロイします。 サンプル アプリケーションでは、クライアント ライブラリを使って、サンプル データの管理、作成、読み取り、クエリを実行します。
空のディレクトリでターミナルを開きます。
まだ認証されていない場合は、
azd auth loginを使用して Azure Developer CLI に対して認証します。 ツールによって指示された手順に従って、任意の Azure 資格情報を使って CLI に対して認証します。azd auth loginazd initを使ってプロジェクトを初期化します。azd init --template cosmos-db-nosql-go-quickstart初期化中に、一意の環境名を構成します。
azd upを使って、Azure Cosmos DB アカウントをデプロイします。 Bicep テンプレートは、サンプル Web アプリケーションもデプロイします。azd upこのプロビジョニング プロセス中に、サブスクリプション、目的の場所、ターゲット リソース グループを選択します。 プロビジョニング プロセスが完了するまで待ちます。 このプロセスには 5 分ほどかかる可能性があります。
Azure リソースのプロビジョニングが完了すると、実行中の Web アプリケーションへの URL が出力に含まれます。
Deploying services (azd deploy) (✓) Done: Deploying service web - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io> SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.コンソールで URL を使って、ブラウザーで Web アプリケーションに移動します。 実行中のアプリの出力を確認します。
クライアント ライブラリをインストールする
クライアント ライブラリは、azcosmos パッケージとして Go 経由で使用できます。
ターミナルを開き、
/srcフォルダーに移動します。cd ./srcazcosmosパッケージがまだインストールされていない場合は、go installを使ってインストールします。go install github.com/Azure/azure-sdk-for-go/sdk/data/azcosmosまた、
azidentityパッケージがまだインストールされていない場合はインストールします。go install github.com/Azure/azure-sdk-for-go/sdk/azidentitysrc/go.mod ファイルを開いて確認し、
github.com/Azure/azure-sdk-for-go/sdk/data/azcosmosおよびgithub.com/Azure/azure-sdk-for-go/sdk/azidentityエントリが両方とも存在することを確認してください。
オブジェクト モデル
| 名前 | 説明 |
|---|---|
CosmosClient |
このクラスは主要なクライアント クラスであり、アカウント全体のメタデータやデータベースを管理するために使われます。 |
CosmosDatabase |
このクラスはアカウント内のデータベースを表します。 |
CosmosContainer |
このクラスは主に、コンテナーまたはコンテナー内に格納されている項目の読み取り、更新、削除操作を実行するために使われます。 |
PartitionKey |
このクラスは論理パーティション キーを表します。 このクラスは、多くの一般的な操作とクエリに必要です。 |
コード例
テンプレートのサンプル コードでは、cosmicworks というデータベースと products というコンテナーを使います。
products コンテナーには、各製品の名前、カテゴリ、数量、一意識別子、販売フラグなどの詳細が含まれています。 コンテナーでは、論理パーティション キーとして /category プロパティを使います。
クライアントを認証する
このサンプルでは azcosmos.NewClient を使用して CosmosClient の新しいインスタンスを作成し、DefaultAzureCredential インスタンスを使用して認証します。
credential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
return err
}
clientOptions := azcosmos.ClientOptions{
EnableContentResponseOnWrite: true,
}
client, err := azcosmos.NewClient("<azure-cosmos-db-nosql-account-endpoint>", credential, &clientOptions)
if err != nil {
return err
}
データベースの取得
client.NewDatabase を使って、cosmicworks という既存のデータベースを取得します。
database, err := client.NewDatabase("cosmicworks")
if err != nil {
return err
}
コンテナーの取得
database.NewContainer を使って既存の products コンテナーを取得します。
container, err := database.NewContainer("products")
if err != nil {
return err
}
項目を作成する
JSON にシリアル化するすべてのメンバーを含む Go 型をビルドします。 この例では、型には一意識別子、カテゴリ、名前、数量、価格、販売のフィールドが含まれます。
type Item struct {
Id string `json:"id"`
Category string `json:"category"`
Name string `json:"name"`
Quantity int `json:"quantity"`
Price float32 `json:"price"`
Clearance bool `json:"clearance"`
}
container.UpsertItem を使ってコンテナー内に項目を作成します。 このメソッドは "アップサート" を行い、項目が既に存在する場合は、それを効果的に置き換えます。
item := Item {
Id: "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
Category: "gear-surf-surfboards",
Name: "Yamba Surfboard",
Quantity: 12,
Price: 850.00,
Clearance: false,
}
partitionKey := azcosmos.NewPartitionKeyString("gear-surf-surfboards")
context := context.TODO()
bytes, err := json.Marshal(item)
if err != nil {
return err
}
response, err := container.UpsertItem(context, partitionKey, bytes, nil)
if err != nil {
return err
}
項目を読み取る
一意識別子 (id) フィールドとパーティション キー フィールドの両方を使って、ポイント読み取り操作を実行できます。
container.ReadItem を使って、特定の項目を効率的に取得できます。
partitionKey := azcosmos.NewPartitionKeyString("gear-surf-surfboards")
context := context.TODO()
itemId := "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
response, err := container.ReadItem(context, partitionKey, itemId, nil)
if err != nil {
return err
}
if response.RawResponse.StatusCode == 200 {
read_item := Item{}
err := json.Unmarshal(response.Value, &read_item)
if err != nil {
return err
}
}
クエリ項目
container.NewQueryItemsPager を使って、コンテナー内の複数の項目に対してクエリを実行します。 次のパラメーター化クエリを使用して、指定されたカテゴリ内のすべての項目を検索します。
SELECT * FROM products p WHERE p.category = @category
partitionKey := azcosmos.NewPartitionKeyString("gear-surf-surfboards")
query := "SELECT * FROM products p WHERE p.category = @category"
queryOptions := azcosmos.QueryOptions{
QueryParameters: []azcosmos.QueryParameter{
{Name: "@category", Value: "gear-surf-surfboards"},
},
}
pager := container.NewQueryItemsPager(query, partitionKey, &queryOptions)
pager.NextPage を使用して結果の各ページをループすることにより、クエリのページ分割された結果を解析します。
pager.More を使用して、各ループの開始時に結果が残っているかどうかを判断します。
items := []Item{}
for pager.More() {
response, err := pager.NextPage(context.TODO())
if err != nil {
return err
}
for _, bytes := range response.Items {
item := Item{}
err := json.Unmarshal(bytes, &item)
if err != nil {
return err
}
items = append(items, item)
}
}
データを調査する
Azure Cosmos DB 用の Visual Studio Code 拡張機能を使用して、NoSQL データを探します。 次のようなコア データベース操作を実行できます。ただし、これらに限定されません:
- スクラップブックまたはクエリ エディターを使用したクエリの実行
- 項目の変更、更新、作成、削除
- 他のソースからのデータの一括インポート
- データベースとコンテナーの管理
詳細については、Visual Studio Code 拡張機能を使用して Azure Cosmos DB for NoSQL データを探す方法に関する記事を参照してください。
リソースをクリーンアップする
サンプル アプリケーションやリソースが不要になったら、対応するデプロイとすべてのリソースを削除します。
azd down