開始使用 Azure Cosmos DB for MongoDB 和 Python

適用於： MongoDB

本文說明如何使用 PyMongo 驅動程式套件連線至 Azure Cosmos DB for MongoDB。 連線之後，您即可在資料庫、集合和文件上執行作業。

注意

範例程式碼片段 可在 GitHub 上作為 Python 專案取得。

本文說明如何使用 Python PyMongo 的其中一個開放原始碼 MongoDB 用戶端驅動程式，與適用於 MongoDB 的 Azure Cosmos DB API 進行通訊。

必要條件

• 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
• Python 3.8+
• Azure 命令列介面 (CLI) 或 Azure PowerShell
• Azure Cosmos DB for MongoDB 資源

建立新的 Python 應用程式

1. 使用您慣用的終端機建立新的空白資料夾，並將目錄變更為資料夾。

   注意

   如果您只想要完成的程式碼，請下載或派生，並複製具有完整範例的範例程式碼片段存放庫。 您也可以在 Azure Cloud Shell 中 git clone 存放庫，以逐步解說本快速入門中所示的步驟。

2. 建立列出 PyMongo 和 python-dotenv 套件的 requirements.txt 檔案。 在本機部署期間，會使用 dotenv 套件來讀取 .env 檔案中的環境變數。

   # requirements.txt
   pymongo
   python-dotenv
   

3. 建立虛擬環境並安裝套件。

   Windows

   # py -3 uses the global python interpreter. You can also use python3 -m venv .venv.
   py -3 -m venv .venv
   source .venv/Scripts/activate   
   pip install -r requirements.txt
   

   Linux / macOS

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   

透過 PyMongo 驅動程式連線至 Azure Cosmos DB for MongoDB

若要透過 PyMongo 驅動程式連線至 Azure Cosmos DB，請建立 MongoClient 物件的執行個體。 此類別是針對資料庫執行所有作業的起點。

MongoClient 最常見的建構函式只需要 host 參數，在本文中，該參數會設為 COSMOS_CONNECTION_STRING 環境變數。 您可以在建構函式中使用其他選用的參數和關鍵字參數。 您也可以使用 host 參數來指定許多選用參數。 如果相同選項與 host 一起傳入並做為參數，該參數會優先使用。

請參閱連線問題的疑難排解指南。

取得資源名稱

在下列命令中，我們會將 msdocs-cosmos 顯示為資源群組名稱。 視情況適時變更名稱。

Azure CLI

1. 建立 resourceGroupName 的殼層變數。

   # Variable for resource group name
   resourceGroupName="msdocs-cosmos"
   

2. 使用 az cosmosdb list 命令來擷取資源群組中第一個 Azure Cosmos DB 帳戶的名稱，並將其儲存在 accountName 殼層變數中。

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

PowerShell

1. 建立 RESOURCE_GROUP_NAME 的殼層變數。

   # Variable for resource group name
   $RESOURCE_GROUP_NAME = "msdocs-cosmos"
   

2. 使用 Get-AzCosmosDBAccountKey Cmdlet 擷取資源群組中第一個 Azure Cosmos DB 帳戶的名稱，並將其儲存在 accountName 殼層變數中。

   # Get the name of the first Azure Cosmos DB account in your resource group
   $ACCOUNT_NAME = (Get-AzCosmosDBAccount -ResourceGroupName $RESOURCE_GROUP_NAME)[0].Name
   

入口網站

請略過此步驟，並在下一個步驟中使用入口網站的資訊。

擷取連接字串

Azure CLI

1. 使用 az cosmosdb keys list 命令，從帳戶的連接字串清單中尋找 API for MongoDB 連接字串。

   az cosmosdb keys list --type connection-strings \
       --resource-group $resourceGroupName \
       --name $accountName 
   

2. 記錄 PRIMARY KEY 值。 稍後您將使用這些認證。

PowerShell

1. 使用 Cmdlet，從帳戶的金鑰和連接字串清單中尋找 CONNECTION STRINGGet-AzCosmosDBAccountKey。

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "ConnectionStrings"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "Primary MongoDB Connection String"    
   

2. 記錄 CONNECTION STRING 值。 稍後您將使用這些認證。

入口網站

1. 登入 Azure 入口網站。

2. 瀏覽至現有的 Azure Cosmos DB for MongoDB 帳戶頁面。

3. 從 Azure Cosmos DB for MongoDB 帳戶頁面中，選取 [連接字串] 導覽功能表選項。

4. 記錄 [PRIMARY CONNECTION STRING] 欄位的值。 稍後的步驟中需要用到此值。

   

設定環境變數

若要在程式碼內使用 CONNECTION STRING 值，請在執行應用程式的本機環境中設定此值。 若要設定環境變數，請使用您慣用的終端機來執行下列命令：

Windows

$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"

Linux / macOS

export COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

.env

.env 檔案是將環境變數儲存在專案中的標準方式。 在專案的根目錄中建立 .env 檔案。 將下列幾行新增至 .env 檔案：

COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

使用連接字串建立 MongoClient

1. 新增相依性以參考 PyMongo 和 python-dotenv 套件。

   import os
   import sys
   
   import pymongo
   from dotenv import load_dotenv
   

2. 使用建構函式和從環境變數讀取的連接字串來定義 MongoClient 類別的新執行個體。

   load_dotenv()
   CONNECTION_STRING = os.environ.get("COSMOS_CONNECTION_STRING")
   client = pymongo.MongoClient(CONNECTION_STRING)
   
   for prop, value in vars(client.options).items():
       print("Property: {}: Value: {} ".format(prop, value))
   

如需使用不同方式建立 MongoClient 執行個體的詳細資訊，請參閱使用 MongoClient 建立連線。

關閉 MongoClient 連線

當應用程式完成連線時，請記得將其關閉。 該 .close() 呼叫應該在進行所有資料庫呼叫之後。

client.close()

將 MongoDB 用戶端類別與適用於 API for MongoDB 的 Azure Cosmos DB 搭配使用

在開始建置應用程式之前，讓我們看一下 Azure Cosmos DB 中的資源階層。 Azure Cosmos DB 具有用來建立和存取資源的特定物件模型。 Azure Cosmos DB 會在由帳戶、資料戶、集合和文件所組成的階層中建立資源。

階層式圖表：頂端顯示 Azure Cosmos DB 資料庫帳戶。 帳戶有兩個子資料庫節點。 其中一個資料庫節點包含兩個子集合節點。 另一個資料庫節點包含單一子集合節點。 該單一集合節點有三個子文件節點。

每種資源以一或多個相關聯的 Python 類別來表示。 以下是最常見類別的清單：

• MongoClient - 使用 PyMongo 時的第一個步驟是建立 MongoClient，以連線至 Azure Cosmos DB 的 API for MongoDB。 用戶端物件會用於設定及執行針對服務的要求。

• 資料庫 - 適用於 MongoDB 的 Azure Cosmos DB API 可以支援一或多個獨立資料庫。

• 集合 - 資料庫可以包含一或多個集合。 集合是儲存在 MongoDB 中的文件群組，可視為關係資料庫中資料表的大致對等項目。

• 文件 - 文件是一組機碼值組。 文件具有動態結構描述。 動態結構描述表示相同集合中的文件不需要有一組相同欄位或結構。 而且集合文件中的常見欄位可能會保存不同類型的資料。

若要深入了解實體階層，請參閱 Azure Cosmos DB 資源模型一文。

另請參閱

• PyPI 套件
• API 參考

下一步

既然您已連線到 API for MongoDB 帳戶，請使用下一個指南來建立和管理資料庫。

使用 Python 在 Azure Cosmos DB for MongoDB 中建立資料庫