クイックスタート: Azure Cosmos DB for MongoDB に Go アプリケーションを接続する

[アーティクル]
03/29/2023

適用対象: MongoDB

Azure Cosmos DB は、マルチモデルデータベースサービスです。グローバルな分散と水平方向のスケーリング機能により、ドキュメントデータベースやテーブルデータベース、キーと値のデータベース、グラフデータベースをすばやく作成し、クエリを実行することができます。このクイックスタートでは、Azure Cloud Shell を利用して Azure Cosmos DB アカウントを作成し、管理し、GitHub から既存のサンプルアプリケーションをクローンし、Azure Cosmos DB と連動するようにそれを構成します。

サンプルアプリケーションは、Go で記述されたコマンドラインベースの todo 管理ツールです。 Azure Cosmos DB の MongoDB 用 API は MongoDB ワイヤプロトコルと互換性があり、あらゆる MongoDB クライアントドライバーでそれと接続できるようになります。このアプリケーションでは、Azure Cosmos DB データベースにデータが格納されることがアプリケーションでは意識されないよう、MongoDB 用 Go ドライバーが使用されます。

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料で作成できます。または、Azure サブスクリプションなしで、Azure Cosmos DB を無料で試すこともできます。 Azure Cosmos DB Emulator を使用することもできます。接続文字列には、.mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true を使用してください。
お使いのコンピューターに Go がインストールされていること。Go の実用的知識。
Git.

Azure Cloud Shell で Bash 環境を使用します。詳細については、「Azure Cloud Shell の Bash のクイックスタート」を参照してください。
CLI リファレンスコマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。
- ローカルインストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。認証プロセスを完了するには、ターミナルに表示される手順に従います。その他のサインインオプションについては、Azure CLI でのサインインに関するページを参照してください。
- 初回使用時にインストールを求められたら、Azure CLI 拡張機能をインストールします。拡張機能の詳細については、Azure CLI で拡張機能を使用する方法に関するページを参照してください。
- az version を実行し、インストールされているバージョンおよび依存ライブラリを検索します。最新バージョンにアップグレードするには、az upgrade を実行します。

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

次のコマンドを実行して、サンプルリポジトリを複製します。

コマンドプロンプトを開いて git-samples という名前の新しいフォルダーを作成し、コマンドプロンプトを閉じます。
```
mkdir "C:\git-samples"
```
git bash などの git ターミナルウィンドウを開いて、cd コマンドを使用して、サンプルアプリをインストールする新しいフォルダーに変更します。
```
cd "C:\git-samples"
```
次のコマンドを実行して、サンプルレポジトリを複製します。このコマンドは、コンピューター上にサンプルアプリのコピーを作成します。
```
git clone https://github.com/Azure-Samples/cosmosdb-go-mongodb-quickstart
```

コードの確認

この手順は省略可能です。このアプリケーションのしくみに関心をお持ちの場合は、次のスニペットをご確認ください。それ以外の場合は、「アプリケーションの実行」に進んでください。アプリケーションのレイアウトは次のようになっています。

.
├── go.mod
├── go.sum
└── todo.go

次のスニペットはすべて、todo.go ファイルからのものです。

Azure Cosmos DB への Go アプリの接続

clientOptions によって Azure Cosmos DB の接続文字列がカプセル化され、環境変数を使用して渡されます (後続のセクションで詳細を説明します)。接続は mongo.NewClient を利用して初期化されます。これには clientOptions インスタンスが渡されます。 Ping 関数が呼び出され、接続の成功が確認されます (フェイルファスト方式です)。

    ctx, cancel := context.WithTimeout(context.Background(), time.Second*10)
    defer cancel()

    clientOptions := options.Client().ApplyURI(mongoDBConnectionString).SetDirect(true)
    
    c, err := mongo.Connect(ctx, clientOptions)
    if err != nil {
        log.Fatalf("unable to initialize connection %v", err)
    }

    err = c.Ping(ctx, nil)
    if err != nil {
        log.Fatalf("unable to connect %v", err)
    }

Note

SetDirect(true) 構成の使用は重要です。これがないと、接続エラー unable to connect connection(cdb-ms-prod-<azure-region>-cm1.documents.azure.com:10255[-4]) connection is closed が発生します

`todo` 項目を作成する

todo を作成するため、mongo.Collection のハンドルを取得し、InsertOne 関数を呼び出します。

func create(desc string) {
    c := connect()
    ctx := context.Background()
    defer c.Disconnect(ctx)

    todoCollection := c.Database(database).Collection(collection)
    r, err := todoCollection.InsertOne(ctx, Todo{Description: desc, Status: statusPending})
    if err != nil {
        log.Fatalf("failed to add todo %v", err)
    }

説明と状態 (これは最初は pending に設定されています) を含む Todo 構造体を渡します。

type Todo struct {
    ID          primitive.ObjectID `bson:"_id,omitempty"`
    Description string             `bson:"description"`
    Status      string             `bson:"status"`
}

`todo` 項目を一覧表示する

条件に基づいて TODO を一覧表示できます。フィルター条件をカプセル化する目的で bson.D が作成されます。

func list(status string) {
    .....
    var filter interface{}
    switch status {
    case listAllCriteria:
        filter = bson.D{}
    case statusCompleted:
        filter = bson.D{{statusAttribute, statusCompleted}}
    case statusPending:
        filter = bson.D{{statusAttribute, statusPending}}
    default:
        log.Fatal("invalid criteria for listing todo(s)")
    }

Find はフィルターに基づいてドキュメントを検索するために使用され、結果は Todo のスライスに変換されます。

    todoCollection := c.Database(database).Collection(collection)
    rs, err := todoCollection.Find(ctx, filter)
    if err != nil {
        log.Fatalf("failed to list todo(s) %v", err)
    }
    var todos []Todo
    err = rs.All(ctx, &todos)
    if err != nil {
        log.Fatalf("failed to list todo(s) %v", err)
    }

最後に、情報は表形式でレンダリングされます。

    todoTable := [][]string{}

    for _, todo := range todos {
        s, _ := todo.ID.MarshalJSON()
        todoTable = append(todoTable, []string{string(s), todo.Description, todo.Status})
    }

    table := tablewriter.NewWriter(os.Stdout)
    table.SetHeader([]string{"ID", "Description", "Status"})

    for _, v := range todoTable {
        table.Append(v)
    }
    table.Render()

`todo` 項目を更新する

todo はその _id に基づいて更新できます。 bson.D フィルターが _id に基づいて作成され、更新された情報に対して別のフィルターが作成されます。更新された情報とは、この場合、新しい状態です (completed または pending)。最後に、フィルターと更新後のドキュメントを指定して UpdateOne 関数が呼び出されます。

func update(todoid, newStatus string) {
....
    todoCollection := c.Database(database).Collection(collection)
    oid, err := primitive.ObjectIDFromHex(todoid)
    if err != nil {
        log.Fatalf("failed to update todo %v", err)
    }
    filter := bson.D{{"_id", oid}}
    update := bson.D{{"$set", bson.D{{statusAttribute, newStatus}}}}
    _, err = todoCollection.UpdateOne(ctx, filter, update)
    if err != nil {
        log.Fatalf("failed to update todo %v", err)
    }

`todo` を削除する

todo はその _id に基づいて削除され、bson.D インスタンスの形式でカプセル化されます。ドキュメントを削除する目的で DeleteOne が呼び出されます。

func delete(todoid string) {
....
    todoCollection := c.Database(database).Collection(collection)
    oid, err := primitive.ObjectIDFromHex(todoid)
    if err != nil {
        log.Fatalf("invalid todo ID %v", err)
    }
    filter := bson.D{{"_id", oid}}
    _, err = todoCollection.DeleteOne(ctx, filter)
    if err != nil {
        log.Fatalf("failed to delete todo %v", err)
    }
}

アプリケーションのビルド

アプリケーションをクローンしたディレクトリに移動し、アプリケーションをビルドします (go build を使用)。

cd monogdb-go-quickstart
go build -o todo

アプリケーションが適切にビルドされたことを確認します。

./todo --help

Azure Cosmos DB を設定する

CLI をローカルにインストールして使用することを選択した場合、このトピックでは、Azure CLI のバージョン 2.0 以降を実行している必要があります。バージョンを確認するには、az --version を実行します。インストールまたはアップグレードする必要がある場合は、[Install Azure CLI] のインストールに関するページを参照してください。

インストールされた Azure CLI を使用する場合は、az login コマンドで Azure サブスクリプションにサインインし、画面上の指示に従います。 Azure Cloud Shell を使用する場合は、この手順を省略できます。

az login

Azure Cosmos DB モジュールを追加する

インストールされた Azure CLI を使用する場合は、az コマンドを実行して、cosmosdb コンポーネントが既にインストールされているかどうかを調べます。 cosmosdb が基本コマンドの一覧にある場合は、次のコマンドに進みます。 Azure Cloud Shell を使用する場合は、この手順を省略できます。

cosmosdb が基本コマンドのリストにない場合は、Azure CLI を再インストールします。

リソースグループの作成

az group create でリソースグループを作成します。 Azure リソースグループとは、Web アプリ、データベース、ストレージアカウントなどの Azure リソースのデプロイと管理に使用する論理コンテナーです。

次の例は、西ヨーロッパリージョンにリソースグループを作成します。リソースグループには一意の名前を選択します。

Azure Cloud Shell を使用する場合は、[試してみる] を選択し、画面のプロンプトに従ってログインしてから、コマンドをコマンドプロンプトにコピーします。

az group create --name myResourceGroup --location "West Europe"

Azure Cosmos DB アカウントを作成する

az cosmosdb create コマンドを使用して Azure Cosmos DB アカウントを作成します。

次のコマンドの <cosmosdb-name> プレースホルダーを独自の一意の Cosmos DB アカウント名に置き換えます。この一意の名前は、Azure Cosmos DB エンドポイント (https://<cosmosdb-name>.documents.azure.com/) の一部として使用されます。そのため、この名前は Azure のすべての Azure Cosmos DB アカウントで一意である必要があります。

az cosmosdb create --name <cosmosdb-name> --resource-group myResourceGroup --kind MongoDB

--kind MongoDB パラメーターにより、MongoDB のクライアント接続が有効になります。

Azure Cosmos DB アカウントが作成されると、Azure CLI によって次の例のような情報が表示されます。

Note

この例では、Azure CLI の出力形式として JSON を使用しています (既定)。別の出力形式を使用する場合は、「Azure CLI コマンドの出力形式」を参照してください。

{
  "databaseAccountOfferType": "Standard",
  "documentEndpoint": "https://<cosmosdb-name>.documents.azure.com:443/",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Document
DB/databaseAccounts/<cosmosdb-name>",
  "kind": "MongoDB",
  "location": "West Europe",
  "name": "<cosmosdb-name>",
  "readLocations": [
    {
      "documentEndpoint": "https://<cosmosdb-name>-westeurope.documents.azure.com:443/",
      "failoverPriority": 0,
      "id": "<cosmosdb-name>-westeurope",
      "locationName": "West Europe",
      "provisioningState": "Succeeded"
    }
  ],
  "resourceGroup": "myResourceGroup",
  "type": "Microsoft.DocumentDB/databaseAccounts",
  "writeLocations": [
    {
      "documentEndpoint": "https://<cosmosdb-name>-westeurope.documents.azure.com:443/",
      "failoverPriority": 0,
      "id": "<cosmosdb-name>-westeurope",
      "locationName": "West Europe",
      "provisioningState": "Succeeded"
    }
  ]
}

データベースキーの取得

Azure Cosmos DB データベースに接続するには、データベースキーが必要です。 az cosmosdb keys list コマンドを使用して、プライマリキーを取得します。

az cosmosdb keys list --name <cosmosdb-name> --resource-group myResourceGroup --query "primaryMasterKey"

Azure CLI によって次の例のような情報が出力されます。

"RUayjYjixJDWG5xTqIiXjC..."

アプリケーションの構成

接続文字列、MongoDB データベース、コレクション名を環境変数としてエクスポートします。

export MONGODB_CONNECTION_STRING="mongodb://<COSMOSDB_ACCOUNT_NAME>:<COSMOSDB_PASSWORD>@<COSMOSDB_ACCOUNT_NAME>.documents.azure.com:10255/?ssl=true&replicaSet=globaldb&maxIdleTimeMS=120000&appName=@<COSMOSDB_ACCOUNT_NAME>@"

Note

Azure Cosmos DB の要件上、ssl=true オプションは重要です。詳細については、「接続文字列の要件」を参照してください。

MONGODB_CONNECTION_STRING 環境変数については、<COSMOSDB_ACCOUNT_NAME> と <COSMOSDB_PASSWORD> のプレースホルダーを置き換えます。

<COSMOSDB_ACCOUNT_NAME>:作成した Azure Cosmos DB アカウントの名前
<COSMOSDB_PASSWORD>:前の手順で抽出したデータベースキー

export MONGODB_DATABASE=todo-db
export MONGODB_COLLECTION=todos

MONGODB_DATABASE と MONGODB_COLLECTION の値は自分で選択できます。あるいはそのままにすることもできます。

アプリケーションの実行

todo を作成するには

./todo --create "Create an Azure Cosmos DB database account"

成功した場合、新しく作成したドキュメントの MongoDB _id で出力が表示されるはずです。

added todo ObjectID("5e9fd6befd2f076d1f03bd8a")

別の todo を作成します

./todo --create "Get the MongoDB connection string using the Azure CLI"

すべての todo を一覧表示します

./todo --list all

追加したものが次のような表形式で表示されるはずです。

+----------------------------+--------------------------------+-----------+
|             ID             |          DESCRIPTION           |  STATUS   |
+----------------------------+--------------------------------+-----------+
| "5e9fd6b1bcd2fa6bd267d4c4" | Create an Azure Cosmos DB      | pending   |
|                            | database account               |           |
| "5e9fd6befd2f076d1f03bd8a" | Get the MongoDB connection     | pending   |
|                            | string using the Azure CLI     |           |
+----------------------------+--------------------------------+-----------+

todo の状態を更新するには (たとえば、completed 状態に変更する)、todo ID を使用します。

./todo --update 5e9fd6b1bcd2fa6bd267d4c4,completed

完了した todo のみを一覧表示します

./todo --list completed

更新したばかりのものが表示されるはずです。

+----------------------------+--------------------------------+-----------+
|             ID             |          DESCRIPTION           |  STATUS   |
+----------------------------+--------------------------------+-----------+
| "5e9fd6b1bcd2fa6bd267d4c4" | Create an Azure Cosmos DB      | completed |
|                            | database account               |           |
+----------------------------+--------------------------------+-----------+

データエクスプローラーにデータを表示する

Azure Cosmos DB に格納されているデータは、Azure portal で表示したり、照会したりできます。

前の手順で作成されたユーザーデータを、表示、クエリ、操作するには、Web ブラウザーで Azure Portal にログインします。

上部の検索ボックスに、「Azure Cosmos DB」と入力します。 [Azure Cosmos DB アカウント] ブレードが開いたら、自分の Azure Cosmos DB アカウントを選択します。左側のナビゲーションで、 [データエクスプローラー] を選択します。 [コレクション] ウィンドウでコレクションを展開します。これで、コレクション内のドキュメントの表示とデータのクエリを実行でき、ストアドプロシージャ、トリガー、および UDF の作成と実行も行うことができます。

新しく作成したドキュメントが表示されているデータエクスプローラー

ID を利用して todo を削除します。

./todo --delete 5e9fd6b1bcd2fa6bd267d4c4,completed

todo をリストして確認します。

./todo --list all

先ほど削除した todo は表示から消えているはずです。

+----------------------------+--------------------------------+-----------+
|             ID             |          DESCRIPTION           |  STATUS   |
+----------------------------+--------------------------------+-----------+
| "5e9fd6befd2f076d1f03bd8a" | Get the MongoDB connection     | pending   |
|                            | string using the Azure CLI     |           |
+----------------------------+--------------------------------+-----------+

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

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

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

次のステップ

このクイックスタートでは、Azure Cloud Shell を使用して Azure Cosmos DB for MongoDB アカウントを作成し、Go コマンドラインアプリを作成して実行し、todo を管理する方法について説明しました。これで、Azure Cosmos DB アカウントに追加のデータをインポートできるようになりました。

Azure Cosmos DB への移行のための容量計画を実行しようとしていますか? 容量計画のために、既存のデータベースクラスターに関する情報を使用できます。

既存のデータベースクラスター内の仮想コアとサーバーの数のみがわかっている場合は、仮想コア数または仮想 CPU 数を使用した要求ユニットの見積もりに関するページを参照してください
現在のデータベースワークロードに対する通常の要求レートがわかっている場合は、Azure Cosmos DB Capacity Planner を使用した要求ユニットの見積もりに関するページを参照してください

MongoDB データを Azure Cosmos DB にインポートする

クイックスタート: Azure Cosmos DB for MongoDB に Go アプリケーションを接続する

前提条件

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

コードの確認

Azure Cosmos DB への Go アプリの接続

todo 項目を作成する

todo 項目を一覧表示する

todo 項目を更新する

todo を削除する

アプリケーションのビルド

Azure Cosmos DB を設定する

Azure へのサインイン

Azure Cosmos DB モジュールを追加する

リソース グループの作成

Azure Cosmos DB アカウントを作成する

データベース キーの取得

アプリケーションの構成

接続文字列、MongoDB データベース、コレクション名を環境変数としてエクスポートします。

アプリケーションの実行

データ エクスプローラーにデータを表示する

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

次のステップ

その他のリソース

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

`todo` 項目を作成する

`todo` 項目を一覧表示する

`todo` 項目を更新する

`todo` を削除する

リソースグループの作成

データベースキーの取得

データエクスプローラーにデータを表示する