你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：将 Azure Cosmos DB for MongoDB vCore 与用于 Python 的 MongoDB 驱动程序配合使用

2025-06-11
适用于: ✅ MongoDB (vCore)

在本快速入门中，你将使用 Python 部署基本的 Azure Cosmos DB for MongoDB 应用程序。 Azure Cosmos DB for MongoDB vCore 是一种无架构数据存储，允许应用程序使用 MongoDB 库将非结构化文档存储在云中。你将了解如何使用 Python 在 Azure Cosmos DB 资源中创建文档并执行基本任务。

“库源代码”“包 (PyPI)” | “Azure Developer CLI” |

先决条件

Azure Developer CLI
Docker Desktop

Azure 订阅服务
- 如果没有 Azure 订阅，请在开始之前创建一个免费帐户。

Python 3.12

初始化项目

使用 Azure 开发人员 CLI （azd）创建 Azure Cosmos DB for MongoDB vCore 群集并部署容器化示例应用程序。示例应用程序使用客户端库来管理、创建、读取和查询示例数据。

在空目录中打开终端。
如果尚未经过身份验证，请使用 azd auth login 向 Azure Developer CLI 进行身份验证。按照工具指定的步骤，使用首选的 Azure 凭据向 CLI 进行身份验证。
```
azd auth login
```

使用 azd init 来初始化项目。

azd init --template cosmos-db-mongodb-vcore-python-quickstart

在初始化期间，配置唯一的环境名称。
使用 azd up. 部署群集。 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 应用程序。观察正在运行的应用的输出。

正在运行的 Web 应用程序的屏幕截图。

安装客户端库

客户端库可通过 PyPi 作为 pymongo 包使用。

打开终端并导航到 /src 文件夹。
```
cd ./src
```
使用 pymongo 安装 pip install 包（如果尚未安装）。
```
pip install pymongo
```
使用 azure.identity 安装 pip install 包（如果尚未安装）。
```
pip install azure.identity
```
打开并查看 src/requirements.txt 文件，以验证这两个包条目是否存在。

导入库文件

将以下命名空间导入应用程序代码：

	包装	来源
`DefaultAzureCredential`	`azure.identity`	用于 Python 的 Azure SDK
`MongoClient`	`pymongo`	适用于 Python 的官方 MongoDB 驱动程序
`OIDCCallback`	`pymongo`	适用于 Python 的官方 MongoDB 驱动程序
`OIDCCallbackContext`	`pymongo`	适用于 Python 的官方 MongoDB 驱动程序
`OIDCCallbackResult`	`pymongo`	适用于 Python 的官方 MongoDB 驱动程序

from azure.identity import DefaultAzureCredential

from pymongo import MongoClient
from pymongo.auth_oidc import OIDCCallback, OIDCCallbackContext, OIDCCallbackResult

对象模型

名称	DESCRIPTION
MongoClient	用于连接到 MongoDB 的类型。
`Database`	表示群集中的数据库。
`Collection`	表示群集中数据库内的集合。

模板中的示例代码使用名为 cosmicworks 的数据库和名为 products 的集合。 products 集合包含每个产品的名称、类别、数量和唯一标识符等详细信息。该集合使用 /category 属性作为分片键。

对客户端进行身份验证

虽然 Azure Cosmos DB for MongoDB vCore 的 Microsoft Entra 身份验证可以使用众所周知的 TokenCredential 类型，但你必须实现自定义令牌处理程序。此示例实现可用于创建支持MongoClient的 Microsoft Entra 标准身份验证，以支持多种身份类型。

首先，定义一个类，该 AzureIdentityTokenCallback 类定义一个 fetch 函数，该类采用 OIDCCallbackContext 参数并返回一个 OIDCCallbackResult。

class AzureIdentityTokenCallback(OIDCCallback):
    def __init__(self, credential):
        self.credential = credential

    def fetch(self, context: OIDCCallbackContext) -> OIDCCallbackResult:
        token = self.credential.get_token(
            "https://ossrdbms-aad.database.windows.net/.default").token
        return OIDCCallbackResult(access_token=token)

使用自定义处理程序类并传入 DefaultAzureCredential 类型的新实例

credential = DefaultAzureCredential()

authProperties = {"OIDC_CALLBACK": AzureIdentityTokenCallback(credential)}

使用您的群集名称和适用于 MongoDB vCore 的 Azure Cosmos DB 已知最佳实践配置选项来构建 MongoClient 实例。此外，请配置自定义身份验证机制。

clusterName = "<azure-cosmos-db-mongodb-vcore-cluster-name>"

client = MongoClient(
    f"mongodb+srv://{clusterName}.global.mongocluster.cosmos.azure.com/",
    connectTimeoutMS=120000,
    tls=True,
    retryWrites=True,
    authMechanism="MONGODB-OIDC",
    authMechanismProperties=authProperties
)

获取数据库

此示例使用 Database 类型的 get_database 函数创建 MongoClient 类型的实例。

database = client.get_database("<database-name>")

获取集合

此示例使用 Collection 类型的 get_collection 函数创建 Database 类型的实例。

collection = database.get_collection("<collection-name>")

创建文档

使用 collection.update_one 在集合中创建文档。如果该项已经存在，此方法会“更新插入”该项，从而有效地替换该项。

new_document = {
    "_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "category": "gear-surf-surfboards",
    "name": "Yamba Surfboard",
    "quantity": 12,
    "sale": False,
}

filter = {
    "_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "category": "gear-surf-surfboards"
}

payload = {
    "$set": new_document
}

result = collection.update_one(filter, payload, upsert=True);

阅读文档

同时使用唯一标识符 (id) 和分片键字段来执行点读取操作。使用 collection.find_one 以有效检索特定项。

filter = {
    "_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
    "category": "gear-surf-surfboards"
}

existing_document = collection.find_one(filter)

查询文档

使用 collection.find 对容器中的多个项执行查询。此查询查找指定类别（分片键）中的所有项。

filter = {
    "category": "gear-surf-surfboards"
}

matched_documents = collection.find(filter)

for document in matched_documents:
    # Do something with each item

删除文档

通过发送文档的唯一标识符的筛选器来删除文档。使用delete_one从集合中删除文档。

filter = {
    '_id': id
}

result = collection.delete_one(filter)

探索您的数据

使用适用于 Azure Cosmos DB 的 Visual Studio Code 扩展浏览 MongoDB vCore 数据。可以执行核心数据库操作，这些操作包括但不限于：

使用剪贴簿或查询编辑器执行查询
修改、更新、创建和删除文档
从其他源导入批量数据
管理数据库和集合

有关详细信息，请参阅如何使用 Visual Studio Code 扩展浏览 Azure Cosmos DB for MongoDB vCore 数据。

清理资源

不再需要示例应用程序或资源时，请删除相应的部署和所有资源。

azd down --force

反馈

此页面是否有帮助？