使用 Azure Cosmos DB for MongoDB 建立帳戶、資料庫和集合

8 分鐘

Azure Cosmos DB 是完全受控的平台即服務 (PaaS)。若要使用此服務，我們必須先在訂用帳戶下建立 Azure Cosmos DB 帳戶。建立帳戶之後，就可以在其中新增資料庫、集合和文件。

我們會探討幾種方法，以建立各種 Azure Cosmos DB for MongoDB 模型元素。

使用 Azure 入口網站，為 Azure Cosmos DB for MongoDB 建立帳戶、資料庫和容器

建立 Azure Cosmos DB 帳戶及其元素的其中一種方法，就是使用 Azure 入口網站。在此範例中，我們會使用 Azure 入口網站，並透過 Azure Cosmos DB for MongoDB 來建立 Azure Cosmos DB 帳戶。接著，我們會新增資料庫與集合。我們目前不需擔心如何填寫更進階的設定，這會在稍後的課程模組中詳細介紹。針對此範例，讓我們只檢閱 [基本] 索引標籤。讓我們建立帳戶及其元素。

建立 Azure Cosmos DB for MongoDB 帳戶

在 Azure 入口網站中，選取 [+ 建立資源]，然後選取 [Azure Cosmos DB] 和 [建立]。
選取 [Azure Cosmos DB for MongoDB]。
輸入下列參數。
- 訂閱 - 您目前的 Azure 訂閱。
- 資源群組 - 用來建立 Azure Cosmos DB 帳戶的全新或現有 Azure 資源群組。
- 帳戶名稱 - 為 Azure Cosmos DB 帳戶建立的不重複名稱。此名稱不可與 Azure 中的其他名稱重複。您的帳戶 URI 會在帳戶名稱後附加 mongo.cosmos.azure.com。
- 位置 - 裝載您的 Azure Cosmos DB 帳戶的地理位置。一般來說，您應該選取靠近使用者或應用程式的位置。
- 容量模式 - 如上個單元所述，您可以選取帳戶以使用 [已佈建的輸送量] 或 [無伺服器]。在此範例中，請選取 [已佈建的輸送量]。
- 套用免費階層折扣 - 在此範例中，請選取 [不套用]。
- 限制帳戶總輸送量 - 在此範例中，請保持「未核取」的狀態。
- 版本 - 選取 [4.0]。
注意

若要充分利用支援的功能，建議您盡可能使用 3.6 以上的版本。
選取 [檢閱 + 建立]，成功驗證後請選取 [建立]。

注意

建立 Azure Cosmos DB 帳戶可能需要數分鐘。

為 Azure Cosmos DB for MongoDB 建立資料庫和容器

在 Azure 入口網站中建立資料庫和容器非常簡單，我們先來建立資料庫吧。

在 [Azure Cosmos DB for MongoDB 帳戶] 左側功能表上，選取 [資料總管]。
選取 [新增集合] 圖示右側的下拉式清單，然後選取 [新增資料庫]。
在 [資料庫識別碼] 文字方塊中，為您的資料庫建立新名稱。
雖然我們可以在 [新增資料庫] 對話方塊中定義 [佈建輸送量]，但在大多數情況下，您將在容器層級選取已佈建的輸送量。在此範例中，我們會「取消核取」 [佈建輸送量] 核取方塊，然後選取 [確定]。

我們現在應會在 [MONGO API] 區段下看到新資料庫。該來建立新集合了。
選取 [新增集合] 圖示。
在 [新增集合] 對話方塊中輸入下列參數。
- 資料庫名稱 - 您會在這裡看到兩個選項：[建立新項目] 或 [使用現有項目]。此選項可讓您在建立新集合時建立新的資料庫。由於我們已在先前的步驟中建立了新的資料庫，因此請選取 [使用現有項目]，然後從下拉式選項中選擇資料庫名稱。
- 集合識別碼 - 此參數是您提供給集合的名稱。
- 分區化 - 我們通常會選取 [已分區]。此選項可讓 Azure Cosmos DB 根據「分區索引鍵」，建立跨多個租用戶分區的容器。 Azure Cosmos DB 可透過大型容器，將您的租用戶分散到多個實體節點以擴大規模。我們會在設計課程模組中更詳細地討論分區化。選取 [分區化]。
  - 分區索引鍵 - 選取 [分區化] 將需要您新增分區索引鍵。此索引鍵是定義您的資料分割策略的資料分割索引鍵。例如，在 IoT (物聯網) 集合中，它可能是 /deviceid 或 /region，視您選擇的資料分割策略而定。我們會在設計課程模組中更詳細地討論分割策略。
  - [此集合的佈建專用輸送量] 核取方塊 - 您通常會將集合的輸送量佈建為 [自動調整] 或 [手動]。此設定可讓您更妥善地控制個別集合的成本。我們會在設計課程模組中更詳細地討論輸送量。現在，請勾選核取方塊，然後選取 [自動調整]。
  - [集合輸送量] 或 [集合最大 RU/秒] - 視您選取 [手動] 或 [自動調整] 而定，您必須分別輸入 [集合輸送量] 或 [集合最大 RU/秒]，也就是輸送量模式。主要差異在於，在 [手動] 模式中，無論您是否使用，都會向您就所選的 RU/秒收費。 [自動調整] 只會向您就所選的最大 RU/秒收費。無論哪種情況，您的集合都會在輸送量達到所選值時開始節流。針對此範例，請保留預先定義的數值即可。
  - 分析存放區 - Azure Cosmos DB 分析存放區超出本課程的學習範圍。如需該主題的詳細資訊，請檢閱什麼是 Azure Cosmos DB 分析存放區一文。
  - 進階/索引 - 我們將在設計課程模組中更詳細地討論索引。將核取方塊保持核取狀態。

我們現在應已有了資料庫和要連線的集合。在下個單元中，我們將進一步詳細說明如何連線至 Azure Cosmos DB for MongoDB 帳戶。在這之前，我們先來檢閱另一種建立 Azure Cosmos DB for MongoDB 資料庫和集合的方式。

建立或連線至 Azure Cosmos DB for MongoDB 資料庫和集合

您應該能使用 Java、Python、Node.js、.NET 或其他採用 MongoDB 驅動程式的程式設計語言，來建立或連線至 Azure Cosmos DB for MongoDB 帳戶。我們將為您介紹一些函式，方便您使用不同語言來建立這些元素。在本課程模組的開頭，我們說明開發人員可以繼續使用 MongoDB 驅動程式、SDK 和他們熟悉的工具，來連線到 Azure Cosmos DB 並建立應用程式。我們會使用這些驅動程式及其屬性和方法，針對 Azure Cosmos DB for MongoDB 帳戶撰寫存取和作業的程式。

建立或連線至 Azure Cosmos DB for MongoDB 資料庫

您可以使用喜歡的開發工具來建立 Azure Cosmos DB for MongoDB 應用程式。我們會針對每個相關的程式設計語言，使用 MongoDB 驅動程式來建立資料庫和集合。我們來檢閱可用來連線至 Azure Cosmos DB for MongoDB 帳戶及「產品」資料庫的程式碼。

Node.js

import { DefaultAzureCredential, ClientSecretCredential } from "@azure/identity";
const { MongoClient, ObjectId } = require('mongodb');
import axios from "axios";

async function main() {
  // Environment variables
  const endpoint = process.env.AZURE_COSMOS_RESOURCEENDPOINT;
  const listConnectionStringUrl = process.env.AZURE_COSMOS_LISTCONNECTIONSTRINGURL;
  const scope = process.env.AZURE_COSMOS_SCOPE;

  // Uncomment the corresponding lines for the authentication type you want to use.
  // For system-assigned managed identity.
  // const credential = new DefaultAzureCredential();

  // For user-assigned managed identity.
  // const clientId = process.env.AZURE_COSMOS_CLIENTID;
  // const credential = new DefaultAzureCredential({
  //     managedIdentityClientId: clientId
  // });

  // For service principal.
  // const tenantId = process.env.AZURE_COSMOS_TENANTID;
  // const clientId = process.env.AZURE_COSMOS_CLIENTID;
  // const clientSecret = process.env.AZURE_COSMOS_CLIENTSECRET;
  // const credential = new ClientSecretCredential(tenantId, clientId, clientSecret);

  // Acquire the access token
  const accessToken = await credential.getToken(scope);

  // Get the connection string
  const config = {
    method: 'post',
    url: listConnectionStringUrl,
    headers: {
        'Authorization': 'Bearer ${accessToken.token}'
    }
  };
  const response = await axios(config);
  const keysDict = response.data;
  const connectionString = keysDict['connectionStrings'][0]['connectionString'];

  // Connect to Azure Cosmos DB for MongoDB
  const client = new MongoClient(connectionString);

  try {
    // Open the connection
    await client.connect();

    // Connect to the database "products"
    const ProductDatabase = client.db('products');

    // Add code to connect to a collection and add an entry here
  } catch (err) {
    console.error("An error occurred:", err);
  } finally {
    // Close the connection
    await client.close();
  }
}

main().catch((err) => console.error("Unhandled error:", err));

Java

package com.fabrikam;

import com.mongodb.MongoClient;
import com.mongodb.MongoClientURI;
import com.mongodb.client.MongoCollection;
import com.mongodb.client.MongoDatabase;
import com.mongodb.client.model.Filters;
import javax.net.ssl.*;
import java.net.InetSocketAddress;
import com.azure.identity.*;
import com.azure.core.credential.*;
import java.net.http.*;
import java.net.URI;

public class App {
  public static void main(String[] args) {
    // Environment variables
    String endpoint = System.getenv("AZURE_COSMOS_RESOURCEENDPOINT");
    String listConnectionStringUrl = System.getenv("AZURE_COSMOS_LISTCONNECTIONSTRINGURL");
    String scope = System.getenv("AZURE_COSMOS_SCOPE");

    // Uncomment the corresponding lines for the authentication type you want to use.
    // For system-assigned managed identity.
    // DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder().build();

    // For user-assigned managed identity.
    // DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder()
    //     .managedIdentityClientId(System.getenv("AZURE_COSMOS_CLIENTID"))
    //     .build();

    // For service principal.
    // ClientSecretCredential defaultCredential = new ClientSecretCredentialBuilder()
    //     .clientId(System.getenv("AZURE_COSMOS_CLIENTID"))
    //     .clientSecret(System.getenv("AZURE_COSMOS_CLIENTSECRET"))
    //     .tenantId(System.getenv("AZURE_COSMOS_TENANTID"))
    //     .build();

    MongoClient mongoClient = null;

    try {
      // Acquire the access token
      AccessToken accessToken = defaultCredential
          .getToken(new TokenRequestContext().addScopes(scope))
          .block();
      String token = accessToken.getToken();

      // Retrieve the connection string
      HttpClient client = HttpClient.newBuilder().build();
      HttpRequest request = HttpRequest.newBuilder()
          .uri(new URI(listConnectionStringUrl))
          .header("Authorization", "Bearer " + token)
          .POST(HttpRequest.BodyPublishers.noBody())
          .build();
      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

      JSONParser parser = new JSONParser();
      JSONObject responseBody = parser.parse(response.body());
      List<Map<String, String>> connectionStrings = responseBody.get("connectionStrings");
      String connectionString = connectionStrings.get(0).get("connectionString");

      // Connect to Azure Cosmos DB for MongoDB
      MongoClientURI uri = new MongoClientURI(connectionString);
      mongoClient = new MongoClient(uri);

      // Connect to the database
      MongoDatabase ProductDatabase = mongoClient.getDatabase("products");

      // Add code to connect to a collection and add an entry here

    } catch (Exception e) {
      e.printStackTrace();
    } finally {
      if (mongoClient != null) {
        mongoClient.close();
      }
    }
  }
}

Python

import os
import pymongo
import requests
from azure.identity import ManagedIdentityCredential, ClientSecretCredential

# Environment variables
endpoint = os.getenv('AZURE_COSMOS_RESOURCEENDPOINT')
listConnectionStringUrl = os.getenv('AZURE_COSMOS_LISTCONNECTIONSTRINGURL')
scope = os.getenv('AZURE_COSMOS_SCOPE')

# Uncomment the following lines corresponding to the authentication type you want to use.
# For system-assigned managed identity
# cred = ManagedIdentityCredential()

# For user-assigned managed identity
# managed_identity_client_id = os.getenv('AZURE_COSMOS_CLIENTID')
# cred = ManagedIdentityCredential(client_id=managed_identity_client_id)

# For service principal
# tenant_id = os.getenv('AZURE_COSMOS_TENANTID')
# client_id = os.getenv('AZURE_COSMOS_CLIENTID')
# client_secret = os.getenv('AZURE_COSMOS_CLIENTSECRET')
# cred = ClientSecretCredential(tenant_id=tenant_id, client_id=client_id, client_secret=client_secret)

# Get the connection string
session = requests.Session()
token = cred.get_token(scope)
response = session.post(listConnectionStringUrl, headers={"Authorization": "Bearer {}".format(token.token)})
keys_dict = response.json()
conn_str = keys_dict["connectionStrings"][0]["connectionString"]

# Connect to Azure Cosmos DB for MongoDB
client = pymongo.MongoClient(conn_str)

# To connect to the database, use the connection variable ("client" in this case), and the database name
ProductDatabase = client["products"]

# Add code to connect to a collection and add an entry here

using MongoDB.Driver;
using Azure.Identity;
using Azure.Core;
using System;
using System.Net.Http;
using System.Text.Json;
using System.Collections.Generic;
using System.Threading.Tasks;

public class Products
{
  public int ProductId { get; set; }
  public string name { get; set; }
}

class test
{
  public static async Task Main(string[] args)
  {
      // Environment variables
      var endpoint = Environment.GetEnvironmentVariable("AZURE_COSMOS_RESOURCEENDPOINT");
      var listConnectionStringUrl = Environment.GetEnvironmentVariable("AZURE_COSMOS_LISTCONNECTIONSTRINGURL");
      var scope = Environment.GetEnvironmentVariable("AZURE_COSMOS_SCOPE");

      // Uncomment the corresponding lines for the authentication type you want to use.
      // For system-assigned identity.
      // var tokenProvider = new DefaultAzureCredential();

      // For user-assigned identity.
      // var tokenProvider = new DefaultAzureCredential(
      //     new DefaultAzureCredentialOptions
      //     {
      //         ManagedIdentityClientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID")
      //     });

      // For service principal.
      // var tenantId = Environment.GetEnvironmentVariable("AZURE_COSMOS_TENANTID");
      // var clientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID");
      // var clientSecret = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTSECRET");
      // var tokenProvider = new ClientSecretCredential(tenantId, clientId, clientSecret);

      // Acquire the access token.
      AccessToken accessToken = await tokenProvider.GetTokenAsync(
          new TokenRequestContext(scopes: new[] { scope }));

      // Get the connection string.
      using var httpClient = new HttpClient();
      httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken.Token}");
      var response = await httpClient.PostAsync(listConnectionStringUrl, null);
      response.EnsureSuccessStatusCode();
      var responseBody = await response.Content.ReadAsStringAsync();

      // Parse the connection string.
      var connectionStrings = JsonSerializer.Deserialize<Dictionary<string, List<Dictionary<string, string>>>>(responseBody);
      string connectionString = connectionStrings["connectionStrings"][0]["connectionString"];

      // Initialize the MongoClient with the connection string.
      var mongoClient = new MongoClient(connectionString);

      // Connect to the "products" database.
      var ProductDatabase = mongoClient.GetDatabase("products");

      // Add code to connect to a collection and add an entry here.
  }
}

就是這麼簡單，使用驅動程式連線後，我們就會建立新的資料庫，或根據語言指向具 GetDatabase 或類似方法的現有資料庫。我們的應用程式現在可以使用 ProductDatabase 變數來參考所需的資料庫。建立或連線至集合，就和建立新的資料庫一樣簡單。

在 Azure Cosmos DB for MongoDB 中建立集合

為建立或存取現有的集合，我們會根據程式設計語言使用取得集合方法或參考。我們在先前的範例中新增一些程式碼，以建立/連線至集合，並在該集合上新增一個輸入值。

Node.js

          // Add code to connect to a collection and add and find an entry here 
          var collection = ProductDatabase.collection('documents');
          var insertResult = await collection.insertOne({ ProductId: 1, name: "bread" });

          // return data where ProductId = 1
          const findProduct = await collection.find({ProductId: 1});
          await findProduct.forEach(console.log);

Java

          // Add code to connect to a collection and add and find an entry here 
          MongoCollection collection = ProductDatabase.getCollection("products");

          collection.insertOne(new Document()
                      .append("ProductId", 1)
                      .append("name", "bread"));

          // return data where ProductId = 1
          Document findProduct = (Document) collection.find(eq("ProductId", 1)).first();
          System.out.println(findProduct.toJson());

Python

# Add code to connect to a collection and add an entry here 
collection = ProductDatabase["products"]
collection.insert_one({ "ProductId": 1, "name": "bread" })

    // Add code to connect to a collection and add an entry here 
    var ProductCollection = ProductDatabase.GetCollection<Products>("products");

    Products Product = new Products {ProductId=1,name="bread"};
    ProductCollection.InsertOne (Product);

在下個單元中，我們將深入了解如何建立連接字串。

使用 MongoDB 延伸模組命令，管理「Azure Cosmos DB for MongoDBI 的 API」中儲存的資料

如先前所討論，Azure Cosmos DB for MongoDB 可讓我們使用相同的驅動程式和程式碼，以在 Azure Cosmos DB 帳戶的 MongoDB 伺服器中存取和建立物件。不過，使用該程式碼來建立資料庫和集合時，會採用預設的 Azure Cosmos DB 建立參數。若要利用 Azure Cosmos DB 功能，我們必須控制資料庫和集合建立參數，例如輸送量、自動調整、指派分區索引鍵，以及定義索引。 Azure Cosmos DB for MongoDB 可讓我們使用擴充命令來定義這些參數，以達成上述目標。這些命令可讓我們撰寫更精確的指示，說明如何建立或修改 Azure Cosmos DB 專用的資料庫和集合。

針對下列要求類型，Azure Cosmos DB for MongoDB 提供了延伸模組命令：

建立資料庫
更新資料庫
取得資料庫
建立集合
更新集合
取得集合

MongoDB 驅動程式提供可針對資料庫執行命令的函式，我們會使用此函式將擴充命令傳送至 Azure Cosmos DB。我們來看看程式碼，以建立輸送量為 2000 RU (要求單位) 的 IoT 裝置集合，以及 DeviceId 的分區索引鍵。

Node.js

    // create the Devices collection with a throughput of 2000 RUs and with DeviceId as the sharding key
    var result = IOTDatabase.command({customAction: "CreateCollection", collection: "Devices", offerThroughput: 2000, shardKey: "DeviceId"});

Java

      // create the Devices collection with a throughput of 2000 RUs and with DeviceId as the sharding key
      Document DevCollectionDef = new Document();
      DevCollectionDef.append("customAction", "CreateCollection");
      DevCollectionDef.append("collection", "Devices");
      DevCollectionDef.append("offerThroughput", 2000);
      DevCollectionDef.append("shardKey", "DeviceId");

      Document result = IOTDatabase.runCommand(DevCollectionDef);

Python

      # create the Devices collection with a throughput of 2000 RUs and with DeviceId as the sharding key
      IOTDatabase.command({'customAction': "CreateCollection", 'collection': "Devices", 'offerThroughput': 2000, 'shardKey': "DeviceId"})

      // create the Devices collection with a throughput of 1000 RUs and with EmployeeId as the sharding key
      var result = IOTDatabase.RunCommand<BsonDocument>(@"{customAction: ""CreateCollection"", collection: ""Devices"", offerThroughput: 2000, shardKey: ""DeviceId""}");

我們可以透過類似方法來修改集合，以及建立或修改資料庫。請參考使用 MongoDB 延伸模組命令，來管理適用於 MongoDB 的 Azure Cosmos DB API 中儲存的資料一文以了解更多資訊。

使用 Azure Cosmos DB for MongoDB 建立帳戶、資料庫和集合

使用 Azure 入口網站，為 Azure Cosmos DB for MongoDB 建立帳戶、資料庫和容器

建立 Azure Cosmos DB for MongoDB 帳戶

為 Azure Cosmos DB for MongoDB 建立資料庫和容器

建立或連線至 Azure Cosmos DB for MongoDB 資料庫和集合

建立或連線至 Azure Cosmos DB for MongoDB 資料庫

在 Azure Cosmos DB for MongoDB 中建立集合

使用 MongoDB 延伸模組命令，管理「Azure Cosmos DB for MongoDBI 的 API」中儲存的資料

意見反應