快速入門：適用於 Python 的 Azure Cosmos DB for MongoDB 與 MongoDB 驅動程式

發行項
08/15/2024

適用於： MongoDB

開始使用 MongoDB，以在您的 Azure Cosmos DB 資源內建立資料庫、集合和文件。請依照以下步驟，使用 Azure Developer CLI 將基本解決方案部署到您的環境。

適用於 MongoDB 的 API 參考檔 | pymongo 套件 | Azure 開發人員 CLI

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
GitHub 帳戶

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
Azure Developer CLI
Docker Desktop

設定

將這個專案的開發容器部署到您的環境。然後使用 Azure Developer CLI (azd) 來建立 Azure Cosmos DB for MongoDB 帳戶，並部署容器化應用程式範例。應用程式範例使用用戶端程式庫管理、建立、讀取和查詢樣本資料。

重要

GitHub 帳戶的免費權利包括儲存體和核心時數。如需詳細資訊，請參閱 GitHub 帳戶包含的儲存體和核心時數。

在專案的根目錄中開啟終端。
使用 azd auth login 以向 Azure Developer CLI 進行驗證。依照工具指定的步驟，使用您慣用的 Azure 認證向 CLI 進行驗證。
```
azd auth login
```
使用 azd init 來初始化專案。
```
azd init --template cosmos-db-mongodb-python-quickstart
```
注意

本快速入門使用 azure-samples/cosmos-db-mongodb-python-quickstart 範本 GitHub 存放庫。如果此專案尚未存在，Azure 開發人員 CLI 會自動將此專案複製到您的電腦。
在初始化期間，請設定唯一的環境名稱。

提示

環境名稱也將是目標資源群組名稱。在這個快速入門中，請考慮使用 msdocs-cosmos-db。
使用 azd up 部署 Azure Cosmos DB 帳戶。 Bicep 範本也會部署範例 Web 應用程式。
```
azd up
```
在佈建流程期間，請選取您的訂用帳戶和所需位置。等候佈建程序完成。此流程「大約需要五分鐘」的時間。

Azure 資源佈建完成後，輸出將包含正在執行的 Web 應用程式的 URL。

Deploying services (azd deploy)

  (✓) Done: Deploying service web
- Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>

SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.

請使用主控台中的 URL，以在瀏覽器中導覽至您的 Web 應用程式。觀察執行中應用程式的輸出。

安裝用戶端程式庫

在應用程式目錄中建立檔案 requirements.txt ，其中列出 PyMongo 和 python-dotenv 套件。
```
# requirements.txt
pymongo
python-dotenv
```

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

Windows
Linux/macOS

# 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

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

物件模型

讓我們先看看 API for MongoDB 中的資源階層，以及用於建立及存取這些資源的物件模型。 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 資源模型一文。

本文所述的範例程式碼會建立名為 adventureworks 的資料庫，其中包含名為 products 的集合。 products 集合的設計目的是要包含產品詳細資料，例如名稱、類別、數量和銷售指標。每個產品也都包含唯一識別碼。完整的程式碼範例位於 https://github.com/Azure-Samples/azure-cosmos-db-mongodb-python-getting-started/tree/main/001-quickstart/。

針對以下步驟，資料庫不會使用分區化，並使用 PyMongo 驅動程式顯示同步應用程式。針對非同步應用程式，請使用 Motor 驅動程式。

驗證用戶端

在專案目錄中，建立 run.py 檔案。在您的編輯器中，新增 require 陳述式來參考您將使用的套件，包括 PyMongo 和 python-dotenv 套件。
```
import os
import sys
from random import randint

import pymongo
from dotenv import load_dotenv
```

從 .env 檔案中定義的環境變數取得連線資訊。

load_dotenv()
CONNECTION_STRING = os.environ.get("COSMOS_CONNECTION_STRING")

定義您將在程式碼中使用的常數。

DB_NAME = "adventureworks"
COLLECTION_NAME = "products"

連線至適用於 MongoDB 的 Azure Cosmos DB API

使用 MongoClient 物件，連線至適用於 MongoDB 的 Azure Cosmos DB 資源。此連接方法會傳回資料庫的參考。

client = pymongo.MongoClient(CONNECTION_STRING)

取得資料庫

使用 list_database_names 方法檢查資料庫是否存在。如果資料庫不存在，請使用 create database extension 命令，以指定的佈建輸送量加以建立。

# Create database if it doesn't exist
db = client[DB_NAME]
if DB_NAME not in client.list_database_names():
    # Create a database with 400 RU throughput that can be shared across
    # the DB's collections
    db.command({"customAction": "CreateDatabase", "offerThroughput": 400})
    print("Created db '{}' with shared throughput.\n".format(DB_NAME))
else:
    print("Using database: '{}'.\n".format(DB_NAME))

取得集合

使用 list_collection_names 方法檢查集合是否存在。如果集合不存在，請使用 create collection extension 命令來建立它。

# Create collection if it doesn't exist
collection = db[COLLECTION_NAME]
if COLLECTION_NAME not in db.list_collection_names():
    # Creates a unsharded collection that uses the DBs shared throughput
    db.command(
        {"customAction": "CreateCollection", "collection": COLLECTION_NAME}
    )
    print("Created collection '{}'.\n".format(COLLECTION_NAME))
else:
    print("Using collection: '{}'.\n".format(COLLECTION_NAME))

建立索引

使用更新集合延伸模組命令建立索引。您也可以在建立集合延伸模組命令中設定索引。將此範例中的索引設定為 name 屬性，以便您稍後可以使用產品名稱上的資料指標類別排序方法進行排序。

indexes = [
    {"key": {"_id": 1}, "name": "_id_1"},
    {"key": {"name": 2}, "name": "_id_2"},
]
db.command(
    {
        "customAction": "UpdateCollection",
        "collection": COLLECTION_NAME,
        "indexes": indexes,
    }
)
print("Indexes are: {}\n".format(sorted(collection.index_information())))

建立文件

使用 adventureworks 資料庫的 product 屬性來建立文件：

category 屬性。此屬性可作為邏輯分割區索引鍵。
name 屬性。
庫存 quantity 屬性。
sale 屬性，指出產品是否正在銷售。

"""Create new document and upsert (create or replace) to collection"""
product = {
    "category": "gear-surf-surfboards",
    "name": "Yamba Surfboard-{}".format(randint(50, 5000)),
    "quantity": 1,
    "sale": False,
}
result = collection.update_one(
    {"name": product["name"]}, {"$set": product}, upsert=True
)
print("Upserted document with _id {}\n".format(result.upserted_id))

藉由呼叫集合等級作業 update_one，在集合中建立文件。在此範例中，您將「更新插入」upsert，而不是「建立」新文件。此範例中不需要更新插入，因為產品「名稱」是隨機的。不過，在多次執行程式碼且產品名稱相同時，最好進行更新插入。

update_one 作業的結果包含您可以在後續作業中使用的 _id 欄位值。已自動建立 _id 屬性。

取得文件

使用 find_one 方法來取得文件。

doc = collection.find_one({"_id": result.upserted_id})
print("Found a document with _id {}: {}\n".format(result.upserted_id, doc))

在 Azure Cosmos DB 中，您可以使用唯一識別碼 (_id) 和分割區索引鍵來執行成本較低的點讀取作業。

查詢文件

插入文件之後，您可以執行查詢來取得符合特定篩選的所有文件。此範例會尋找符合特定類別的所有文件：gear-surf-surfboards。定義查詢之後，請呼叫 Collection.find 以取得 Cursor 結果，然後使用排序。

"""Query for documents in the collection"""
print("Products with category 'gear-surf-surfboards':\n")
allProductsQuery = {"category": "gear-surf-surfboards"}
for doc in collection.find(allProductsQuery).sort(
    "name", pymongo.ASCENDING
):
    print("Found a product with _id {}: {}\n".format(doc["_id"], doc))

疑難排解：

如果您收到 The index path corresponding to the specified order-by item is excluded. 這類錯誤，則請確定您已建立索引。

執行程式碼

此應用程式會建立 API for MongoDB 資料庫和集合，並建立文件，然後讀回完全相同的文件。最後，此範例會發出查詢，以傳回符合指定產品「類別」的文件。在每個步驟中，範例會將資訊輸出至主控台，包含其執行的步驟。

若要執行應用程式，請使用終端機瀏覽至應用程式目錄並執行應用程式。

python run.py

此命令的輸出應類似此範例：


Created db 'adventureworks' with shared throughput.

Created collection 'products'.

Indexes are: ['_id_', 'name_1']

Upserted document with _id <ID>

Found a document with _id <ID>:
{'_id': <ID>,
'category': 'gear-surf-surfboards',
'name': 'Yamba Surfboard-50',
'quantity': 1,
'sale': False}

Products with category 'gear-surf-surfboards':

Found a product with _id <ID>:
{'_id': ObjectId('<ID>'),
'name': 'Yamba Surfboard-386',
'category': 'gear-surf-surfboards',
'quantity': 1,
'sale': False}

清除資源

當您不再需要 Azure Cosmos DB for NoSQL 帳戶時，可以刪除對應的資源群組。

使用 az group delete 命令以刪除資源群組。

az group delete --name $resourceGroupName

使用 Remove-AzResourceGroup Cmdlet 以刪除資源群組。

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

共用方式為