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

快速入门：适用于 Python 的 Azure Cosmos DB for Apache Cassandra 客户端库

2025-07-24
适用于: ✅ Apache Cassanda

开始使用适用于 Python 的 Apache Cassandra 客户端库的 Azure Cosmos DB，以存储、管理和查询非结构化数据。按照本指南中的步骤创建新帐户、安装 Python 客户端库、连接到帐户、执行常见作以及查询最终示例数据。

API 参考文档 | 库源代码 | 包（PyPI）

先决条件

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

Azure Cloud Shell 中最新版本的 Azure CLI。
- 如果想要在本地运行 CLI 引用命令，请使用 az login 该命令登录到 Azure CLI。

Python 3.12 或更高版本

设置

首先，为本指南设置帐户和开发环境。本部分将指导你完成创建帐户、获取其凭据以及准备开发环境的过程。

创建帐户

首先，创建用于 Apache Cassandra 帐户的 API。创建帐户后，创建密钥空间和表资源。

Azure CLI
Azure 门户

如果还没有目标资源组，请使用 az group create 命令在订阅中创建新的资源组。
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

使用az cosmosdb create命令来创建一个具有默认设置的新的用于Apache Cassandra的Azure Cosmos DB账户。

az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --locations "regionName=<location>" \
    --capabilities "EnableCassandra"

使用 az cosmosdb cassandra keyspace create 命名的 cosmicworks 创建新的密钥空间。

az cosmosdb cassandra keyspace create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --name "cosmicworks"

使用多行 Bash 命令创建新的 JSON 对象来表示架构。然后，使用 az cosmosdb cassandra table create 命令创建一个名为 products 的新表。

schemaJson=$(cat <<EOF
{
  "columns": [
    {
      "name": "id",
      "type": "text"
    },
    {
      "name": "name",
      "type": "text"
    },
    {
      "name": "category",
      "type": "text"
    },
    {
      "name": "quantity",
      "type": "int"
    },
    {
      "name": "price",
      "type": "decimal"
    },
    {
      "name": "clearance",
      "type": "boolean"
    }
  ],
  "partitionKeys": [
    {
      "name": "id"
    }
  ]
}
EOF
)

az cosmosdb cassandra table create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --keyspace-name "cosmicworks" \
    --name "product" \
    --schema "$schemaJson"

登录到 Azure 门户 (https://portal.azure.com)。
在全局搜索栏中输入 Azure Cosmos DB。
在“服务”中，选择“Azure Cosmos DB”。
在 Azure Cosmos DB 窗格中，选择“创建”，然后在“其他”选项卡中选择“用于 Apache Cassandra 的 Azure Cosmos DB”。
选择帐户类型为请求单位（RU）数据库帐户。

在“基本信息”窗格中，配置以下选项，然后选择“查看 + 创建” ：

	价值
工作负载类型	学习
订阅	选择您的 Azure 订阅
资源组	创建新的资源组，或选择现有资源组
帐户名	提供一个全局唯一的名称
可用性区域	禁用
位置	为订阅选择支持的 Azure 区域

小窍门

可以将任何未指定的选项保留为其默认值。还可以将帐户配置为将帐户总吞吐量限制为每秒 1,000 个请求单位（RU/秒），或启用免费层以最大程度地降低成本。

在“查看 + 创建”窗格中，等待帐户验证成功完成，然后选择“创建”。
门户会自动导航到“部署”窗格。等待部署完成。
部署完成后，选择 转到资源，以导航至新建的 Apache Cassandra API 帐户。
在资源菜单中，选择 “数据资源管理器” 选项。
在数据资源管理器中，选择“ + 新建表”。
在 “添加表 ”对话框中，配置以下选项，然后选择“ 确定” ：

价值

Keyspace 新建

密钥空间名称 cosmicworks

表名称 product

表架构 (id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))

小窍门

可以将任何未指定的选项保留为其默认值。

	价值
Keyspace	新建
密钥空间名称	`cosmicworks`
表名称	`product`
表架构	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

获取凭据

现在，获取用于创建与最近创建的帐户的连接的客户端库的密码。

Azure CLI
Azure 门户

使用az cosmosdb show获取帐户的联系点和用户名。

az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{username:name,contactPoint:documentEndpoint}"

记录上述命令输出中的 contactPoint 值和 username 属性。这些属性的值分别是“联系点”和“用户名”，将在本指南的后续步骤中使用它们通过库连接到该帐户。

使用 az cosmosdb keys list 获取帐户的密钥。

az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

请记录先前命令输出中 primaryMasterKey 属性的值。此属性的值是稍后在本指南中使用的密码，用于使用库连接到帐户。

准备开发环境

然后，使用新项目和客户端库配置开发环境。在转到本指南的其余部分之前，此步骤是最后一个必需的先决条件。

从空目录中开始。
从 Python 包索引（PyPI）导入cassandra-driver包。
```
pip install cassandra-driver
```
创建 app.py 文件。

对象模型

	DESCRIPTION
`Cluster`	表示与群集的特定连接

对客户端进行身份验证

首先，使用本指南前面收集的凭据对客户端进行身份验证。

在集成开发环境中打开 app.py 文件（IDE）。
从 cassandra-driver 模块导入以下类型：
- cassandra.cluster.Cluster
- cassandra.auth.PlainTextAuthProvider
```
from cassandra.cluster import Cluster
from cassandra.auth import PlainTextAuthProvider
```
从 ssl 模块导入以下类型：
- ssl.PROTOCOL_TLS_CLIENT
- ssl.SSLContext
- ssl.CERT_NONE
```
from ssl import PROTOCOL_TLS_CLIENT, SSLContext, CERT_NONE
```
为本指南前面收集的凭据创建字符串变量。为变量 username命名， password以及 contactPoint。
```
username = "<username>"
password = "<password>"
contactPoint = "<contact-point>"
```
SSLContext通过创建名为ssl_context的新变量，设置协议为PROTOCOL_TLS_CLIENT，禁用主机名检查，并将验证模式设置为CERT_NONE来配置其。
```
ssl_context = SSLContext(PROTOCOL_TLS_CLIENT)
ssl_context.check_hostname = False
ssl_context.verify_mode = CERT_NONE
```
使用前面步骤中指定的凭据创建新 PlainTextAuthProvider 对象。将结果存储在名为 auth_provider 的变量中。
```
auth_provider = PlainTextAuthProvider(username=username, password=password)
```
Cluster使用在前面的步骤中创建的凭据和配置变量创建对象。将结果存储在名为 cluster 的变量中。
```
cluster = Cluster([contactPoint], port=10350, auth_provider=auth_provider, ssl_context=ssl_context)
```

连接到群集。

session = cluster.connect("cosmicworks")

警告

本指南中禁用了完整的传输层安全性（TLS）验证，以简化身份验证。对于生产部署，请完全启用验证。

更新插入数据

接下来，将新数据向上插入表中。 Upserting 可确保根据表中是否已存在相同的数据，适当地创建或替换数据。

创建一个名为 Cassandra 查询语言（CQL）查询的新字符串变量 insertQuery ，用于插入新行。

insertQuery = """
INSERT INTO
    product (id, name, category, quantity, price, clearance)
VALUES
    (%(id)s, %(name)s, %(category)s, %(quantity)s, %(price)s, %(clearance)s)
"""

使用新产品的各种属性创建新对象，并将其存储在名为 <a0/> 的变量中。

params = {
    "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "name": "Yamba Surfboard",
    "category": "gear-surf-surfboards",
    "quantity": 12,
    "price": 850.00,
    "clearance": False
}

使用 execute 函数运行具有指定参数的查询。
```
session.execute(insertQuery, params)
```

读取数据

然后，读取以前插入到表中的数据。

创建一个名为 CQL 查询的新字符串变量 readQuery ，该查询与具有相同 id 字段的项匹配。
```
readQuery = "SELECT * FROM product WHERE id = %s LIMIT 1"
```
创建与本指南前面创建的产品相同的值的字符串变量 id 。
```
id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
```
使用 execute 函数运行存储在 readQuery 中的查询，并传入 id 变量作为参数。将结果存储在名为 readResults 的变量中。
```
readResults = session.execute(readQuery, (id,))
```
使用函数 one 获取预期的单个结果。将此单个结果存储在名为matchedProduct的变量中。
```
matchedProduct = readResults.one()
```

查询数据

最后，使用查询查找与表中特定筛选器匹配的所有数据。

创建名为 findQuery 和 category 的字符串变量，使用 CQL 查询和必需参数。

findQuery = "SELECT * FROM product WHERE category = %s ALLOW FILTERING"
category = "gear-surf-surfboards"

使用两个字符串变量和 execute 函数查询多个结果。将此查询的结果存储在名为 findResults 的变量中。
```
findResults = session.execute(findQuery, (category,))
```

使用for循环遍历查询结果。

for row in findResults:
    # Do something here with each result

运行代码

使用应用程序目录中的终端运行新创建的应用程序。

python app.py

清理资源

如果不再需要此帐户，请通过删除资源来从 Azure 订阅中删除该帐户。

Azure CLI
Azure 门户

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"

后续步骤

适用于 Apache Cassandra 的 Azure Cosmos DB 概述