快速入門：適用於 Python 的 Azure Cosmos DB for Apache Cassandra 用戶端程式庫

適用於: ✅ Apache Cassanda

開始使用適用於 Python 的 Azure Cosmos DB for Apache Cassandra 用戶端程式庫，以儲存、管理和查詢非結構化資料。請依照本指南中的步驟建立新帳戶、安裝 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 命令，新建具有預設設定的 Azure Cosmos DB Apache Cassandra 帳戶。

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

使用 az cosmosdb cassandra keyspace create 名為 cosmicworks建立新的keyspace。

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

建立新的 JSON 物件，以使用多行 Bash 命令來代表您的結構描述。然後，使用 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	新建
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 檔案。

物件模型

	說明
`Cluster`	表示叢集的特定連線

驗證用戶端

首先，使用本指南稍早收集的認證來驗證用戶端。

在整合開發環境（IDE）中開啟 app.py 檔案。
從模組匯入 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）驗證，以簡化驗證。針對生產環境部署，請完全啟用驗證。

更新插入資料

接下來，將新資料「更新或插入」到資料表中。更新插入可確保根據資料表中是否已存在相同的資料，適當地建立或取代資料。

建立以 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)
"""

建立具有新產品各種屬性的新物件，並將其儲存在名為 params的變數中。

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 概觀

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-07-27