Azure Cosmos DB for MongoDB 和 Python 入门

项目
03/12/2024

适用对象： MongoDB

本文介绍如何使用 PyMongo 驱动程序包连接到 Azure Cosmos DB for MongoDB。连接后，可对数据库、集合和文档执行操作。

注意

示例代码片段在 GitHub 上作为 Python 项目提供。

本文介绍如何使用其中一个适用于 Python 的开源 MongoDB 客户端驱动程序 PyMongo 与 Azure Cosmos DB 的 API for MongoDB 通信。

先决条件

创建新的 Python 应用

使用首选的终端创建一个新空文件夹，并将目录切换到该文件夹。

注意

如果你只想查看已完成的代码，请下载或者分叉并克隆包含完整示例的示例代码片段存储库。
创建一个列出了 PyMongo 和 python-dotenv 包的 requirements.txt 文件。 dotenv 包用于在本地开发期间从 .env 文件中读取环境变量。
```
# requirements.txt
pymongo
python-dotenv
```

创建一个虚拟环境并安装这些包。

Windows
Linux/macOS

# py -3 uses the multiple-regional 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

使用 PyMongo 驱动程序连接到 Azure Cosmos DB for MongoDB

若要使用 PyMongo 驱动程序连接到 Azure Cosmos DB，请创建 MongoClient 对象的实例。此类是针对数据库执行所有操作的起点。

MongoClient 的最常见构造函数只需要 host 参数，本文中的该参数设置为 COSMOS_CONNECTION_STRING 环境变量。可以在构造函数中使用其他可选参数和关键字参数。还可以使用 host 参数来指定许多可选参数。如果同一选项是使用 host 传入的，同时也是作为参数传入的，则参数优先。

有关连接问题，请参阅故障排除指南。

获取资源名称

在以下命令中，我们将 msdocs-cosmos 显示为资源组名称。根据自己的情况更改名称。

为 resourceGroupName 创建 shell 变量。

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

使用 az cosmosdb list 命令检索资源组中第一个 Azure Cosmos DB 帐户的名称，并将其存储在 accountName shell 变量中。

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

为 RESOURCE_GROUP_NAME 创建 shell 变量。

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

使用 Get-AzCosmosDBAccountKey cmdlet 检索资源组中第一个 Azure Cosmos DB 帐户的名称，并将其存储在 accountName shell 变量中。

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

检索连接字符串

使用 az cosmosdb keys list 命令，从帐户的连接字符串列表中查找 API for MongoDB 连接字符串。

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

请记下“主密钥”值。稍后将使用这些凭据。

使用 Get-AzCosmosDBAccountKey cmdlet，从帐户的密钥和连接字符串列表中查找“连接字符串”。

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

请记下“连接字符串”值。稍后将使用这些凭据。

配置环境变量

若要在代码中使用“连接字符串”值，请在运行应用程序的本地环境中设置此值。若要设置环境变量，请使用首选终端运行以下命令：

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

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

.env 文件是将环境变量存储在项目中的标准方式。在项目的根目录中创建 .env 文件。将以下代码行添加到 .env 文件：

COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

使用连接字符串创建 MongoClient

添加依赖项以引用 PyMongo 和 python-dotenv 包。

import os

import pymongo
from dotenv import load_dotenv

使用构造函数和连接字符串（从环境变量中读取）定义 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 客户端类与 Azure Cosmos DB for API for MongoDB 配合使用

在开始构建应用程序之前，我们先来了解 Azure Cosmos DB 中的资源层次结构。 Azure Cosmos DB 具有用于创建和访问资源的特定对象模型。 Azure Cosmos DB 在由帐户、数据库、集合和文档组成的层次结构中创建资源。

Diagram of the Azure Cosmos DB DB hierarchy including accounts, databases, collections, and docs.

每种类型的资源由一个或多个关联的 Python 类表示。下面列出了最常见的类：

MongoClient - 使用 PyMongo 时的第一步是创建一个 MongoClient 以连接到 Azure Cosmos DB API for MongoDB。此客户端对象用于对服务进行配置和执行请求。
数据库 - Azure Cosmos DB API for MongoDB 支持一个或多个独立数据库。
集合 - 一个数据库可以包含一个或多个集合。集合是存储在 MongoDB 中的一组文档，大致相当于关系数据库中的表。
文档 - 文档是一组键值对。文档具有动态架构。动态架构是指同一集合中的文档不需要有相同的字段集或结构。集合文档中的常见字段可以包含不同类型的数据。

若要详细了解实体的层次结构，请参阅 Azure Cosmos DB 资源模型一文。

另请参阅

后续步骤

现在，你已连接到 API for MongoDB 帐户，请使用下一指南创建和管理数据库。

使用 Python 在 Azure Cosmos DB for MongoDB 中创建数据库