你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
通过 Python 开始使用适用于 NoSQL 的 Azure Cosmos DB
适用范围：
NoSQL
本文介绍如何使用 Python SDK 连接到 Azure Cosmos DB for NoSQL。 连接后，可对数据库、容器和项执行操作。
包 (PyPi) | 示例 | API 参考 | 库源代码 | 反馈
先决条件
- 具有活动订阅的 Azure 帐户。 免费创建帐户。
- Azure Cosmos DB for NoSQL 帐户。 创建 API for NoSQL 帐户。
- Python 3.7 或更高版本
- Azure 命令行接口 (CLI) 或 Azure PowerShell
设置项目
创建可运行 Python 代码的环境。
通过虚拟环境可以在隔离的环境中安装 Python 包，而不会影响系统的其余部分。
在虚拟环境中安装 Azure Cosmos DB for NoSQL Python SDK。
pip install azure-cosmos
创建 Python 应用程序
在你的环境中，创建新的 app.py 文件并在其中添加以下代码：
import json
import os
import sys
import uuid
from azure.core.exceptions import AzureError
from azure.cosmos import CosmosClient, PartitionKey
以上代码将导入你要在本文余下内容中使用的模块。
连接到 Azure Cosmos DB for NoSQL
若要连接到 Azure Cosmos DB 的 API for NoSQL，请创建 CosmosClient 类的实例。 此类是针对数据库执行所有操作的起点。
若要使用 Microsoft Entra 连接到 NoSQL 帐户 的 API，请使用安全主体。 主体的确切类型将取决于应用程序代码的托管位置。 下表可用作快速参考指南。
| 应用程序的运行位置 | 安全主体 |
|---|---|
| 本地计算机（开发和测试） | 用户标识或服务主体 |
| Azure | 托管标识 |
| Azure 外部的服务器或客户端 | 服务主体 |
导入 Azure.Identity
azure-identity 包包含所有 Azure SDK 库之间共享的核心身份验证功能。
将 azure-identity 包导入你的环境。
pip install azure-identity
使用默认凭据实现创建 CosmosClient
如果在本地计算机上进行测试，或者应用程序将在 Azure 服务上运行，并直接支持托管标识，则通过创建 DefaultAzureCredential 实例来获取 OAuth 令牌。
在 app.py 中：
获取终结点以连接到帐户，并将其设置为环境变量
COSMOS_ENDPOINT。导入 DefaultAzureCredential 并创建它的实例。
使用终结点和凭据作为参数创建 CosmosClient 类的新实例。
from azure.identity import DefaultAzureCredential
ENDPOINT = os.environ["COSMOS_ENDPOINT"]
credential = DefaultAzureCredential()
client = CosmosClient(ENDPOINT, credential)
重要
有关如何添加正确的角色以使 DefaultAzureCredential 正常运行的详细信息，请参阅使用 Microsoft Entra ID 为 Azure Cosmos DB 帐户配置基于角色的访问控制。 具体而言，请参阅有关创建角色并将其分配到主体 ID 的部分。
生成应用程序
在生成应用程序时，代码主要与四种类型的资源交互：
API for NoSQL 帐户，它是 Azure Cosmos DB 数据的唯一顶级命名空间。
数据库，它用于组织帐户中的容器。
容器，它包含数据库中的一组单个项。
项，它表示容器中的 JSON 文档。
以下图示显示了这些资源之间的关系。
顶部是显示 Azure Cosmos DB 帐户的层次结构示意图。 该帐户包含两个子数据库节点。 其中一个数据库节点包含两个子容器节点。 另一个数据库节点包含单个子容器节点。 该容器节点包含三个子项节点。
每种类型的资源由一个或多个关联的 Python 类表示。 下面是最常用的同步编程类的列表。 （azure.cosmos.aio 命名空间中有类似的异步编程类。）
| 类 | 说明 |
|---|---|
CosmosClient |
此类为 Azure Cosmos DB 服务提供客户端逻辑表示。 此客户端对象用于对服务进行配置和执行请求。 |
DatabaseProxy |
不一定在服务中存在的数据库接口。 不应直接实例化此类。 应改用 CosmosClient get_database_client 方法。 |
ContainerProxy |
与特定 Cosmos DB 容器交互的接口。 不应直接实例化此类。 请改用 DatabaseProxy get_container_client 方法获取现有容器，或改用 create_container 方法创建新容器。 |
以下指南介绍了如何使用上述每个类来生成应用程序。
| 指南 | 说明 |
|---|---|
| 创建数据库 | 创建数据库 |
| 创建容器 | 创建容器 |
| 项示例 | 点读特定项 |