クイックスタート: Apache Cassandra 向け Go 用 Azure Cosmos DB クライアント ライブラリ

Go 用 Azure Cosmos DB for Apache Cassandra クライアント ライブラリを使用して、非構造化データの格納、管理、クエリを実行します。 このガイドの手順に従って、新しいアカウントの作成、Go クライアント ライブラリのインストール、アカウントへの接続、一般的な操作の実行、最終的なサンプル データのクエリを実行します。

API リファレンス ドキュメント | ライブラリのソース コード | パッケージ (Go)

[前提条件]

• Azure サブスクリプション

  • Azure サブスクリプションをお持ちでない場合は、開始する前に 無料アカウント を作成してください。

• Azure Cloud Shell の Azure CLI の最新バージョン。

  • CLI 参照コマンドをローカルで実行する場合は、 az login コマンドを使用して Azure CLI にサインインします。

• Go 1.24 以降

セットアップ中

まず、このガイドのアカウントと開発環境を設定します。 このセクションでは、アカウントの作成、資格情報の取得、開発環境の準備のプロセスについて説明します。

アカウントを作成する

まず、Apache Cassandra アカウント用の API を作成します。 アカウントが作成されたら、キースペースとテーブル リソースを作成します。

資格情報の取得

ここで、最近作成したアカウントへの接続を作成するために使用するクライアント ライブラリのパスワードを取得します。

開発環境の準備

次に、新しいプロジェクトとクライアント ライブラリを使用して開発環境を構成します。 この手順は、このガイドの残りの部分に進む前に必要な最後の前提条件です。

1. 空のディレクトリから開始します。

2. 新しい Go モジュールを作成します。

   go mod init quickstart
   

3. Go から github.com/apache/cassandra-gocql-driver/v2 パッケージをインポートします。

   go get github.com/apache/cassandra-gocql-driver/v2
   

4. main.go ファイルを作成します。

5. Go アプリケーションの定型句を追加します。

   package main
   
   func main() {    
   }
   

   Von Bedeutung

   このガイドの残りの手順では、 main 関数内にコードを追加することを前提としています。

オブジェクト モデル

コード例

• クライアントの認証
• データのアップサート
• データの読み取り
• データのクエリ

クライアントの認証

まず、このガイドで前に収集した資格情報を使用してクライアントを認証します。

1. 統合開発環境 (IDE) で main.go ファイルを開きます。

2. main関数内で、github.com/apache/cassandra-gocql-driver/v2 パッケージと共に次のパッケージをインポートします。

   • context
   • crypto/tls

   import (
       "context"
       "crypto/tls"
       "github.com/apache/cassandra-gocql-driver/v2"
   )
   

3. このガイドで前に収集した資格情報の文字列変数を作成します。 変数に username、 password、および contactPointという名前を付けます。

   username := "<username>"
   password := "<password>"
   contactPoint := "<contact-point>"
   

4. 前の手順で指定した資格情報を使用して、 PasswordAuthenticator の種類のインスタンスを構成します。 結果を authentication という名前の変数に格納します。

   authentication := gocql.PasswordAuthenticator{
       Username: username,
       Password: password,
   }
   

5. トランスポート層セキュリティ (TLS) 1.2 の最小バージョンとターゲット サーバー名としてcontactPoint変数を使用して、SslOptionsのインスタンスを構成します。 結果を sslOptions という名前の変数に格納します。

   sslOptions := &gocql.SslOptions{
       Config: &tls.Config{
           MinVersion: tls.VersionTLS12,
           ServerName: contactPoint,
       },
   }
   

6. NewClusterとcontactPoint変数を使用して、新しいクラスター仕様を作成します。

   cluster := gocql.NewCluster(contactPoint)
   

7. 前の手順で作成した資格情報と構成変数を使用して、クラスター仕様オブジェクトを構成します。

   cluster.SslOpts = sslOptions
   cluster.Authenticator = authentication
   

8. これらの静的値を使用して、クラスター仕様オブジェクトの残りの部分を構成します。

   cluster.Keyspace = "cosmicworks"
   cluster.Port = 10350
   cluster.ProtoVersion = 4    
   

9. CreateSessionを使用してクラスターに接続する新しいセッションを作成します。

   session, _ := cluster.CreateSession()
   

10. main関数が戻った後でClose関数を呼び出すようにセッションを構成します。

    defer session.Close()
    

11. 新しい Background コンテキスト オブジェクトを作成し、 ctx 変数に格納します。

    ctx := context.Background()
    

データをアップサートする

次に、新しいデータをテーブルにアップサートします。 アップサートにより、同じデータがテーブルに既に存在するかどうかに応じて、データが適切に作成または置換されます。

1. このガイドで前に作成したテーブルに対応するフィールドを使用して、 Product という名前の新しい型を定義します。

   type Product struct {
       id        string
       name      string
       category  string
       quantity  int
       clearance bool
   }
   

   ヒント

   Go では、この種類を別のファイルに作成することも、既存のファイルの末尾に作成することもできます。

2. Product型の新しいオブジェクトを作成します。 オブジェクトを product という名前の変数に格納します。

   product := Product {
       id:        "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
       name:      "Yamba Surfboard",
       category:  "gear-surf-surfboards",
       quantity:  12,
       clearance: false,
   }
   

3. 新しい行を挿入するための Cassandra クエリ言語 (CQL) クエリを使用して、 insertQuery という名前の新しい文字列変数を作成します。

   insertQuery := `
       INSERT INTO
           product (id, name, category, quantity, clearance)
       VALUES
           (?, ?, ?, ?, ?)
   `
   

4. クエリを実行するには、 Query 関数と ExecContext 関数を使用します。 product変数のさまざまなプロパティをクエリ パラメーターとして渡します。

   _ = session.Query(
       insertQuery,
       product.id, 
       product.name, 
       product.category, 
       product.quantity, 
       product.clearance,
   ).ExecContext(ctx)
   

データの読み取り

次に、テーブルにアップサートされたデータを読み取る。

1. 同じid フィールドを持つ項目と一致する CQL クエリを使用して、readQueryという名前の新しい文字列変数を作成します。

   readQuery := `
       SELECT
           id,
           name,
           category,
           quantity,
           clearance
       FROM
           product
       WHERE id = ?
       LIMIT 1
   `
   

2. このガイドで前に作成した製品と同じ値を使用して、 id という名前の文字列変数を作成します。

   id := "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" 
   

3. この操作の結果を格納する matchedProduct という名前の別の変数を作成します。

   var matchedProduct Product
   

4. Query、Consistency、IterContext、およびScan関数を一緒に使用して、クエリに一致する単一の項目を検索し、そのプロパティをmatchedProduct変数に割り当てます。

   session.Query(
       readQuery,
       &id,
   ).Consistency(gocql.One).IterContext(ctx).Scan(
       &matchedProduct.id,
       &matchedProduct.name,
       &matchedProduct.category,
       &matchedProduct.quantity,
       &matchedProduct.clearance,
   )
   

データのクエリを実行する

最後に、クエリを使用して、テーブル内の特定のフィルターに一致するすべてのデータを検索します。

1. findQueryおよびcategoryという名前の文字列変数を作成し、CQLクエリと必須パラメーターを設定します。

   findQuery := `
       SELECT
           id,
           name,
           category,
           quantity,
           clearance
       FROM
           product
       WHERE
           category = ?
       ALLOW FILTERING
   `
   
   category := "gear-surf-surfboards"
   

2. Query、Consistency、IterContext、およびScanner関数を一緒に使用して、クエリに一致する複数の項目を反復処理できるスキャナーを作成します。

   queriedProducts := session.Query(
       findQuery, 
       &category,
   ).Consistency(gocql.All).IterContext(ctx).Scanner()
   

3. Next関数とScan関数を使用してクエリ結果を反復処理し、各結果のプロパティを内部queriedProduct変数に割り当てます。

   for queriedProducts.Next() {
       var queriedProduct Product
       queriedProducts.Scan(
           &queriedProduct.id,
           &queriedProduct.name,
           &queriedProduct.category,
           &queriedProduct.quantity,
           &queriedProduct.clearance,
       )
       // Do something here with each result
   }
   

コードを実行する

アプリケーション ディレクトリのターミナルを使用して、新しく作成したアプリケーションを実行します。

go run .

リソースをクリーンアップする

ここで、最近作成したアカウントへの接続を作成するために使用するクライアント ライブラリのパスワードを取得します。

次のステップ