快速入门：将 Azure Cosmos DB for NoSQL 与 Azure SDK for Python 配合使用

在本快速入门中，你将使用用于 Python 的 Azure SDK 部署基本的 Azure Cosmos DB for NoSQL 应用程序。 Azure Cosmos DB for NoSQL 是一种无架构数据存储，允许应用程序在云中存储非结构化数据。 使用用于 Python 的 Azure SDK 查询容器中的数据并针对单个项执行常见作。

API 参考文档 | 库源代码 | 包 (PyPI) | Azure Developer CLI

• Azure 开发人员 CLI
• Docker Desktop
• Python 3.12

如果你没有 Azure 帐户，请在开始之前创建一个试用帐户。

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

1. 在空目录中打开终端。

2. 如果尚未经过身份验证，请使用 azd auth login 向 Azure Developer CLI 进行身份验证。 按照该工具指定的步骤，使用首选 Azure 凭据向 CLI 进行身份验证。

   azd auth login
   

3. 使用 azd init 来初始化项目。

   azd init --template cosmos-db-nosql-python-quickstart
   

4. 在初始化期间，配置唯一的环境名称。

5. 使用 azd up 部署 Azure Cosmos DB 帐户。 Bicep 模板还部署示例 Web 应用程序。

   azd up
   

6. 在预配过程中，选择订阅、所需位置和目标资源组。 等待预配过程完成。 此过程可能需要大约 5 分钟。

7. 预配 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.
   

8. 使用控制台中的 URL 在浏览器中导航到 Web 应用程序。 观察正在运行的应用的输出。

客户端库可通过 Python 包索引作为 azure-cosmos 库可用。

1. 打开终端并导航到 /src 文件夹。

   cd ./src
   

2. 使用 azure-cosmos 安装 pip install 包（如果尚未安装）。

   pip install azure-cosmos
   

3. 另请安装 azure-identity 包（如果尚未安装）。

   pip install azure-identity
   

4. 打开并查看 src/requirements.txt 文件以验证 和 azure-cosmos 条目是否同时存在azure-identity。

将 DefaultAzureCredential 和 CosmosClient 类型导入应用程序代码。

from azure.identity import DefaultAzureCredential
from azure.cosmos import CosmosClient

• 对客户端进行身份验证
• 获取数据库
• 获取容器
• 创建项
• 获取项
• 查询项

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

此示例创建一个 CosmosClient 类型的新实例并使用 DefaultAzureCredential 实例进行身份验证。

credential = DefaultAzureCredential()

client = CosmosClient(url="<azure-cosmos-db-nosql-account-endpoint>", credential=credential)

使用 client.get_database_client 检索名为 cosmicworks 的现有数据库。

database = client.get_database_client("cosmicworks")

使用 products 检索现有的 database.get_container_client 容器。

container = database.get_container_client("products")

使用要序列化为 JSON 的所有成员生成一个新对象。 在此示例中，该类型具有唯一标识符以及用于类别、名称、数量、价格和销售的字段。 使用 container.upsert_item 在容器中创建某个项。 此方法会“更新插入”该项，有效地替换该项（如果该项已存在）。

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

created_item = container.upsert_item(new_item)

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

existing_item = container.read_item(
    item="aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    partition_key="gear-surf-surfboards",
)

使用 container.GetItemQueryIterator 对容器中的多个项执行查询。 使用此参数化查询查找指定类别中的所有项：

SELECT * FROM products p WHERE p.category = @category

queryText = "SELECT * FROM products p WHERE p.category = @category"

results = container.query_items(
    query=queryText,
    parameters=[
        dict(
            name="@category",
            value="gear-surf-surfboards",
        )
    ],
    enable_cross_partition_query=False,
)

循环访问查询的结果。

items = [item for item in results]

output = json.dumps(items, indent=True)

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

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

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

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

azd down

• .NET 快速入门
• Node.js 快速入门
• Java 快速入门
• Go 快速入门