クイックスタート: `gocql` クライアントを使用して Azure Cosmos DB for Apache Cassandra のデータを管理する Go アプリを構築する

[アーティクル]
08/15/2024

適用対象: Cassandra

Azure Cosmos DB は、マルチモデルデータベースサービスです。グローバルな分散と水平方向のスケーリング機能により、ドキュメントデータベースやテーブルデータベース、キーと値のデータベース、グラフデータベースをすばやく作成し、クエリを実行することができます。このクイックスタートでは、まず Azure Cosmos DB for Apache Cassandra アカウントを作成します。次に、Go アプリケーションを実行して、Cassandra キースペースとテーブルを作成し、いくつかの操作を実行します。この Go アプリでは、Go 言語用の Cassandra クライアントである gocql を使用します。

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料で作成できます。または、Azure サブスクリプションなしで、Azure Cosmos DB を無料で試すこともできます。
お使いのコンピューターに Go がインストールされていること。Go の実用的知識。
Git.

データベースアカウントの作成

データベースを作成するには、Azure Cosmos DB を含んだ Cassandra アカウントを事前に作成しておく必要があります。

Azure portal のメニューまたは [ホーム] ページで、 [リソースの作成] を選択します。
[新規] ページで、 [Azure Cosmos DB] を検索して選択します。
[Azure Cosmos DB] ページで、 [作成] を選択します。
[API] ページの [Cassandra] セクションで [作成] を選択します。

API によって、作成するアカウントの種類が決まります。 Azure Cosmos DB には、NoSQL (ドキュメントデータベース用)、Gremlin (グラフデータベース用)、MongoDB (ドキュメントデータベース用)、Azure Table、Cassandra の 5 種類の API が用意されています。 API ごとに別のアカウントを作成する必要があります。

このクイックスタートでは Cassandra 用 API で動作するテーブルを作成しているため、Cassandra を選択します。

Cassandra 用 API に関する詳細を確認してください。

[Azure Cosmos DB アカウントの作成] ページで、新しい Azure Cosmos DB アカウントの基本的な設定を入力します。

設定	値	説明
サブスクリプション	該当するサブスクリプション	この Azure Cosmos DB アカウントに使用する Azure サブスクリプションを選択します。
リソースグループ	新規作成アカウント名と同じ名前を入力します	[新規作成] を選択します。その後、自分のアカウントの新しいリソースグループの名前を入力します。簡略化のため、Azure Cosmos DB アカウント名と同じ名前を使用します。
アカウント名	一意の名前を入力します	自分の Azure Cosmos DB アカウントを識別するための一意の名前を入力します。アカウント URI は、一意のアカウント名に cassandra.cosmos.azure.com が追加されたものになります。アカウント名に使用できるのは、小文字、数字、ハイフン (-) のみで、長さは 3 文字から 31 文字の範囲にする必要があります。
場所	ユーザーに最も近いリージョン	Azure Cosmos DB アカウントをホストする地理的な場所を選択します。データに最も高速にアクセスできるよう、お客様のユーザーに最も近い場所を使用します。
容量モード	プロビジョニングスループットまたはサーバーレス	プロビジョニングスループットモードでアカウントを作成するには、 [Provisioned throughput](プロビジョニングスループット) を選択します。サーバーレスモードでアカウントを作成するには、 [サーバーレス] を選択します。
Apply Azure Cosmos DB free tier discount (Azure Cosmos DB Free レベル割引を適用する)	[適用] または [適用しない]	Azure Cosmos DB Free レベルのアカウントでは、最初の 1000 RU/s と 25 GB のストレージを無料でご利用いただけます。 Free レベルの詳細を確認してください。
合計アカウントスループットを制限する	アカウントのスループットを制限する場合に選択します	これは、アカウントの合計スループットを特定の値に制限する場合に便利です。

Note

Azure サブスクリプションにつき所有できる Free レベルの Azure Cosmos DB アカウントは 1 つまでです。また、アカウントの作成時にオプトインする必要があります。 Free レベルの割引を適用するオプションが表示されない場合は、サブスクリプション内の別のアカウントが Free レベルで既に有効になっていることを意味します。

Azure Cosmos DB for Apache Cassandra の新しいアカウントページ

[グローバル分散] タブで、次の詳細を構成します。このクイックスタートでは、既定値のままでかまいません。

設定	値	説明
geo 冗長性	無効化	リージョンをペアリージョンとペアリングすることによる、アカウントでのグローバル配信を有効または無効にします。アカウントには、後でさらにリージョンを追加できます。
マルチリージョン書き込み	無効化	マルチリージョン書き込み機能を使用すると、世界中のデータベースとコンテナーで、プロビジョニングされたスループットを利用できます。
可用性ゾーン	無効にする	Availability Zones は、Azure リージョン内の分離された場所です。それぞれのゾーンは、独立した電源、冷却手段、ネットワークを備えた 1 つまたは複数のデータセンターで構成されています。

Note

[Capacity mode](容量モード) として [サーバーレス] を選択した場合、以下のオプションは利用できません。

Apply Free Tier Discount (Free レベルの割引の適用)
geo 冗長性
マルチリージョンライター

必要に応じて、次のタブで追加の詳細を構成できます。
- [ネットワーク] - 仮想ネットワークからのアクセスを構成します。
- [バックアップポリシー] - 定期的または継続的のいずれかのバックアップポリシーを構成します。
- [暗号化] - サービスマネージドキーまたはカスタマーマネージドキーのいずれかを使用します。
- [タグ] - タグは名前と値のペアで、同じタグを複数のリソースやリソースグループに適用することでリソースを分類したり、統合した請求を表示したりできるようにします。
[Review + create](レビュー + 作成) を選択します。
アカウントの設定を確認し、 [作成] を選択します。アカウントの作成には数分かかります。ポータルページに "デプロイが完了しました" と表示されるまで待ちます。
[リソースに移動] を選択し、Azure Cosmos DB アカウントページに移動します。

サンプルアプリケーションの複製

最初に、GitHub からアプリケーションを複製します。

コマンドプロンプトを開き、git-samples という名前の新しいフォルダーを作成します。
```
md "C:\git-samples"
```
Git ターミナルウィンドウ (Git Bash など) を開きます。 cd コマンドを使用して新しいフォルダーに移動し、サンプルアプリをインストールします。
```
cd "C:\git-samples"
```
次のコマンドを実行して、サンプルレポジトリを複製します。このコマンドは、コンピューター上にサンプルアプリのコピーを作成します。
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-go-getting-started.git
```

コードの確認

この手順は省略可能です。コードでデータベースリソースを作成する方法に関心がある場合は、次のコードスニペットで確認できます。それ以外の場合は、「アプリケーションの実行」に進んでください

GetSession 関数 (utils\utils.go の一部) は、挿入、検索などのクラスター操作を実行するために使用される *gocql.Session を返します。

func GetSession(cosmosCassandraContactPoint, cosmosCassandraPort, cosmosCassandraUser, cosmosCassandraPassword string) *gocql.Session {
    clusterConfig := gocql.NewCluster(cosmosCassandraContactPoint)
    port, err := strconv.Atoi(cosmosCassandraPort)
    
    clusterConfig.Authenticator = gocql.PasswordAuthenticator{Username: cosmosCassandraUser, Password: cosmosCassandraPassword}
    clusterConfig.Port = port
    clusterConfig.SslOpts = &gocql.SslOptions{Config: &tls.Config{MinVersion: tls.VersionTLS12}}
    clusterConfig.ProtoVersion = 4
    
    session, err := clusterConfig.CreateSession()
    ...
    return session
}

Azure Cosmos DB Cassandra ホストが gocql.NewCluster 関数に渡されて *gocql.ClusterConfig 構造体が取得され、ユーザー名、パスワード、ポート、および適切な TLS バージョン (HTTPS、SSL、TLS 暗号化のセキュリティ要件) を使用するように構成されます

次に、GetSession 関数が main 関数 (main.go) から呼び出されます。

func main() {
    session := utils.GetSession(cosmosCassandraContactPoint, cosmosCassandraPort, cosmosCassandraUser, cosmosCassandraPassword)
    defer session.Close()
    ...
}

接続情報と資格情報は、環境変数の形式で受け取られます (init メソッドで解決されます)

func init() {
    cosmosCassandraContactPoint = os.Getenv("COSMOSDB_CASSANDRA_CONTACT_POINT")
    cosmosCassandraPort = os.Getenv("COSMOSDB_CASSANDRA_PORT")
    cosmosCassandraUser = os.Getenv("COSMOSDB_CASSANDRA_USER")
    cosmosCassandraPassword = os.Getenv("COSMOSDB_CASSANDRA_PASSWORD")

    if cosmosCassandraContactPoint == "" || cosmosCassandraUser == "" || cosmosCassandraPassword == "" {
        log.Fatal("missing mandatory environment variables")
    }
}

これは、その後、Azure Cosmos DB で keyspace と table の作成から始まるさまざまな操作 (operations\setup.go の一部) を実行するために使用されます。

DropKeySpaceIfExists 関数は、名前が示すように、keyspace が存在する場合にのみこれを削除します。

const dropKeyspace = "DROP KEYSPACE IF EXISTS %s"

func DropKeySpaceIfExists(keyspace string, session *gocql.Session) {
    err := utils.ExecuteQuery(fmt.Sprintf(dropKeyspace, keyspace), session)
    if err != nil {
        log.Fatal("Failed to drop keyspace", err)
    }
    log.Println("Keyspace dropped")
}

CreateKeySpace 関数は、keyspace (user_profile) を作成するために使用されています

const createKeyspace = "CREATE KEYSPACE %s WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 }"

func CreateKeySpace(keyspace string, session *gocql.Session) {
    err := utils.ExecuteQuery(fmt.Sprintf(createKeyspace, keyspace), session)
    if err != nil {
        log.Fatal("Failed to create keyspace", err)
    }
    log.Println("Keyspace created")
}

これに続いて、テーブルの作成を行います (user)。これは、CreateUserTable 関数によって処理されます

const createTable = "CREATE TABLE %s.%s (user_id int PRIMARY KEY, user_name text, user_bcity text)"

func CreateUserTable(keyspace, table string, session *gocql.Session) {
    err := session.Query(fmt.Sprintf(createTable, keyspace, table)).Exec()
    if err != nil {
        log.Fatal("failed to create table ", err)
    }
    log.Println("Table created")
}

キースペースとテーブルが作成されたら、CRUD 操作 (operations\crud.go の一部) を呼び出します。

InsertUser は、User を作成するために使用されています。 Bind を使用して、ユーザー情報 (ID、名前、および都市) をクエリ引数として設定しています

const createQuery = "INSERT INTO %s.%s (user_id, user_name , user_bcity) VALUES (?,?,?)"

func InsertUser(keyspace, table string, session *gocql.Session, user model.User) {
    err := session.Query(fmt.Sprintf(createQuery, keyspace, table)).Bind(user.ID, user.Name, user.City).Exec()
    if err != nil {
        log.Fatal("Failed to create user", err)
    }
    log.Println("User created")
}

FindUser は、特定のユーザー ID を使用してユーザー (model\user.go) を検索するために使用されています。一方、Scan は、(Cassandra によって返される) ユーザー属性を個々の変数 (userid、name、city) にバインドしています。これは、検索クエリの結果として取得した結果を使用する方法の 1 つにすぎません

const selectQuery = "SELECT * FROM %s.%s where user_id = ?"

func FindUser(keyspace, table string, id int, session *gocql.Session) model.User {
    var userid int
    var name, city string
    err := session.Query(fmt.Sprintf(selectQuery, keyspace, table)).Bind(id).Scan(&userid, &name, &city)

    if err != nil {
        if err == gocql.ErrNotFound {
            log.Printf("User with id %v does not exist\n", id)
        } else {
            log.Printf("Failed to find user with id %v - %v\n", id, err)
        }
    }
    return model.User{ID: userid, Name: name, City: city}
}

FindAllUsers は、すべてのユーザーをフェッチするために使用されています。 SliceMap は、map のスライスの形式ですべてのユーザーの情報を取得するための略記として使用されています。各 map は、列名 (たとえば、user_id) をキーとしてそれぞれの値が含まれる、キーと値のペアと考えてください。

const findAllUsersQuery = "SELECT * FROM %s.%s"

func FindAllUsers(keyspace, table string, session *gocql.Session) []model.User {
    var users []model.User
    results, _ := session.Query(fmt.Sprintf(findAllUsersQuery, keyspace, table)).Iter().SliceMap()

    for _, u := range results {
        users = append(users, mapToUser(u))
    }
    return users
}

ユーザー情報の各 map は、mapToUser 関数を使用して User に変換されます。この関数では、単にそれぞれの列から値を抽出し、それを使用して User 構造体のインスタンスを作成します

func mapToUser(m map[string]interface{}) model.User {
    id, _ := m["user_id"].(int)
    name, _ := m["user_name"].(string)
    city, _ := m["user_bcity"].(string)

    return model.User{ID: id, Name: name, City: city}
}

アプリケーションの実行

既に説明したように、このアプリケーションは、接続と資格情報を環境変数の形式で受け取ります。

Azure portal の Azure Cosmos DB アカウントで、 [接続文字列] を選択します。

次の属性 (CONTACT POINT、PORT、USERNAME、および PRIMARY PASSWORD) の値をコピーし、それをそれぞれの環境変数に設定します

set COSMOSDB_CASSANDRA_CONTACT_POINT=<value for "CONTACT POINT">
set COSMOSDB_CASSANDRA_PORT=<value for "PORT">
set COSMOSDB_CASSANDRA_USER=<value for "USERNAME">
set COSMOSDB_CASSANDRA_PASSWORD=<value for "PRIMARY PASSWORD">

ターミナルウィンドウで、適切なフォルダーに移動します。次に例を示します。

cd "C:\git-samples\azure-cosmosdb-cassandra-go-getting-started"

ターミナルで、次のコマンドを実行してアプリケーションを開始します。

go run main.go

ターミナルウィンドウに、キースペースとテーブルの設定、ユーザーの作成など、さまざまな操作の通知が表示されます。
Azure portal で Data Explorer を開き、この新しいデータのクエリ、変更、操作を行います。

Azure Portal での SLA の確認

Azure portal では、Azure Cosmos DB アカウントのスループット、ストレージ、可用性、待ち時間、一貫性が監視されます。 Azure Cosmos DB サービスレベルアグリーメント (SLA) に関連付けられたメトリックのグラフに、実際のパフォーマンスと比較された SLA の値が示されます。この一連のメトリックによって、SLA の監視が透明化されます。

メトリックと SLA を確認するには:

Azure Cosmos DB アカウントのナビゲーションメニューで [メトリック] を選びます。
[遅延時間] など、タブを選択し、右側で期間を選択します。グラフ上の [実際] と [SLA] の線を比較します。
他のタブでメトリックを確認します。

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

アプリと Azure Cosmos DB アカウントの使用を完了したら、それ以上料金がかからないように、作成した Azure リソースを削除できます。リソースを削除するには、次の手順に従います。

Azure portal の検索バーで、「リソースグループ」を検索して選択します。
一覧から、このクイックスタートで作成したリソースグループを選択します。
リソースグループの [概要] ページで、[リソースグループの削除] を選択します。
次のウィンドウで、削除するリソースグループの名前を入力し、[削除] を選択します。

次のステップ

このクイックスタートでは、Cassandra 用 API を使用して Azure Cosmos DB アカウントを作成する方法と、Cassandra データベースとコンテナーを作成する Go アプリの実行方法について説明しました。これで、Azure Cosmos DB アカウントに追加のデータをインポートできるようになりました。

Azure Cosmos DB への Cassandra データのインポート

次の方法で共有

クイックスタート: `gocql` クライアントを使用して Azure Cosmos DB for Apache Cassandra のデータを管理する Go アプリを構築する

前提条件

データベースアカウントの作成

サンプルアプリケーションの複製

コードの確認

アプリケーションの実行

Azure Portal での SLA の確認

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

次のステップ

フィードバック

その他のリソース

次の方法で共有

クイックスタート: gocql クライアントを使用して Azure Cosmos DB for Apache Cassandra のデータを管理する Go アプリを構築する

前提条件

データベース アカウントの作成

サンプル アプリケーションの複製

コードの確認

アプリケーションの実行

Azure Portal での SLA の確認

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

次のステップ

フィードバック

その他のリソース

クイックスタート: `gocql` クライアントを使用して Azure Cosmos DB for Apache Cassandra のデータを管理する Go アプリを構築する

データベースアカウントの作成

サンプルアプリケーションの複製