快速入門：將 Go 應用程式連線至適用於 MongoDB 的 Azure Cosmos DB

發行項
04/19/2024

適用於： MongoDB

Azure Cosmos DB 是多模型的資料庫服務，可讓您快速建立及查詢具有全域散發和水平調整功能的文件、資料表、索引鍵/值及圖形資料庫。在本快速入門中，您可以使用 Azure Cloud Shell 來建立和管理 Azure Cosmos DB 帳戶、從 GitHub 複製現有的範例應用程式，並將其設定為與 Azure Cosmos DB 搭配使用。

範例應用程式是以命令列為基礎的 todo 管理工具，以 Go 撰寫。適用於 MongoDB 的 Azure Cosmos DB API 與 MongoDB 有線通訊協定相容，因此任何 MongoDB 用戶端驅動程式都可以與其連線。此應用程式使用 MongoDB 的 Go 驅動程式，且其運作方式對於資料儲存在 Azure Cosmos DB 資料庫中的應用程式而言是透明的。

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立一個。或免費試用 Azure Cosmos DB (不需 Azure 訂用帳戶)。您也可以使用 Azure Cosmos DB 模擬器搭配連接字串 .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 終端機視窗 (例如 git bash)，並使用 cd 命令變更至要安裝範例應用程式的新資料夾。
```
cd "C:\git-samples"
```
執行下列命令來複製範例存放庫。此命令會在您的電腦上建立範例應用程式副本。
```
git clone https://github.com/Azure-Samples/cosmosdb-go-mongodb-quickstart
```

檢閱程式碼

此步驟是選擇性的。如果您想要了解應用程式的運作方式，可以檢閱下列程式碼片段。或是，您可以直接跳到執行應用程式。應用程式的配置如下所示：

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

下列程式碼片段全部取自 todo.go 檔案。

將 Go 應用程式連線到 Azure Cosmos DB

clientOptions 會封裝 Azure Cosmos DB 的連接字串，而該字串會使用環境變數傳入 (後續章節將詳加說明)。連線會使用 clientOptions 執行個體所傳到的 mongo.NewClient 進行初始化。 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)
    }

注意

請務必使用 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)
    }

我們會傳入 Todo 結構，其中包含描述和狀態（最初設定為 pending）：

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 進行更新。我們可以根據 _id 建立 bson.D 篩選器，並針對更新的資訊建立另一個篩選器；此案例中，這項資訊是新狀態 (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 以尋找版本。如果您需要安裝或升級，請參閱 [安裝 Azure CLI]。

如果您使用已安裝的 Azure CLI，請使用 az login 命令登入您的 Azure 訂用帳戶，並遵循螢幕上的指示。如果您是使用 Azure Cloud Shell，可以跳過此步驟。

az login

新增 Azure Cosmos DB 模組

如果您使用已安裝的 Azure CLI，請檢查 cosmosdb 是否已執行 az 命令來安裝元件。如果 cosmosdb 位於基底命令清單中，請繼續進行下一個命令。如果您是使用 Azure Cloud Shell，可以跳過此步驟。

如果 cosmosdb 不在基底命令清單中，請重新安裝 Azure CLI。

建立資源群組

使用 az group create 來建立資源群組。 Azure 資源群組是一個邏輯容器，其中會部署和管理 Azure 資源，例如 Web 應用程式、資料庫和記憶體帳戶。

下列範例會在西歐區域中建立一個資源群組。選擇資源群組的唯一名稱。

如果您使用 Azure Cloud Shell，請選取 [ 試用]，依照螢幕上的提示登入，然後將命令複製到命令提示字元中。

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

建立 Azure Cosmos DB 帳戶

使用 az cosmosdb create 命令來建立 Azure Cosmos DB 帳戶。

在下列命令中，請在您看見 <cosmosdb-name> 預留位置的地方，替代成您自己的唯一 Azure 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 會顯示類似下列範例的資訊。

注意

此範例會使用 JSON 作為 Azure CLI 輸出格式，這是預設值。若要使用另一種輸出格式，請參閱 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>@"

注意

ssl=true 選項很重要，因為 Azure Cosmos DB 需要設定此選項。如需詳細資訊，請參閱連接字串需求。

針對 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 ：

./todo --update 5e9fd6b1bcd2fa6bd267d4c4,completed

僅列出已完成的 todo

./todo --list completed

您應該會看到您剛才更新的：

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

在資料總管中檢視資料

Azure Cosmos DB 中儲存的資料可在 Azure 入口網站中進行檢視和查詢。

若要檢視、查詢及處理在前一個步驟中建立的使用者資料，請在 Web 瀏覽器中登入 Azure 入口網站。

在頂端的 [搜尋] 方塊中，輸入 Azure Cosmos DB。當您的 Azure Cosmos DB 帳戶刀鋒視窗開啟時，選取您的 Azure Cosmos DB 帳戶。在左側導覽中，選取 [資料總管]。在 [集合] 窗格中展開您的集合，然後您可以檢視集合中的文件、查詢資料，甚至是建立及執行預存程序、觸發程序和 UDF。

顯示新建立文件的數據總管

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 入口網站的 [搜尋] 列中，搜尋並選取 [資源群組]。
在該清單中，選取您在本快速入門中建立的資源群組。
在 [資源群組] 的 [概觀] 頁面中，選取 [刪除資源群組]。
在下個視窗中輸入要刪除的資源群組名稱，然後選取 [刪除]。

下一步

在本快速入門中，您已了解如何使用 Azure Cloud Shell 建立 Azure Cosmos DB for MongoDB 帳戶，以及如何建立和執行 Go 命令列應用程式以管理 todo。您現在可以將其他資料匯入 Azure Cosmos DB 帳戶中。

正在嘗試為遷移至 Azure Cosmos DB 進行容量規劃嗎？您可以使用現有資料庫叢集的相關資訊進行容量規劃。

如果您知道現有資料庫叢集中的虛擬核心和伺服器數目，請參閱使用虛擬核心或 vCPU 來估計要求單位
如果您知道目前資料庫工作負載的一般要求率，請參閱使用 Azure Cosmos DB 容量規劃工具來估計要求單位

將 MongoDB 資料匯入到 Azure Cosmos DB

快速入門：將 Go 應用程式 連線 至適用於 MongoDB 的 Azure Cosmos DB