azure-cosmos-db-py

azure-cosmos-db-py 技能概覽

這個技能的用途

azure-cosmos-db-py 技能可協助你在 Python 中實作 Azure Cosmos DB NoSQL 持久化，通常用在 FastAPI 或 service layer 後端。當你需要的是可直接落地的做法，例如 client 初始化、考量 partition 的 CRUD、參數化查詢，以及可測試的資料存取程式碼，而不是一次性提示答案時，這個技能最有價值。

最適合的使用者與工作內容

如果你正在建置需要從一開始就正確接上 Cosmos DB 的後端功能，建議使用 azure-cosmos-db-py skill：包含應用程式初始化、repository/service 類別、適合 emulator 的本機開發，以及乾淨的錯誤處理。當目標是在 azure-cosmos-db-py for Backend Development 中加入耐久型文件儲存，又不想自己重新發明連線與模型轉換模式時，它會是很合適的選擇。

它的差異化重點

它的核心價值在於實作層面的實用指引：雙重驗證路徑、單例式 client 重用、partition key 策略，以及以 TDD 為導向的 fixtures。它不只是一般性的 Cosmos DB 說明，而是明確朝向能在本機執行、部署到 Azure，並且能以較少猜測方式測試的程式碼。

如何使用 azure-cosmos-db-py 技能

安裝並先開啟正確的檔案

進行 azure-cosmos-db-py install 時，先用以下指令加入技能：

npx skills add microsoft/skills --skill azure-cosmos-db-py

接著先讀 SKILL.md，再依序閱讀 references/client-setup.md、references/partitioning.md、references/service-layer.md、references/error-handling.md 和 references/testing.md。實作時，可把 assets/cosmos_client_template.py、assets/service_template.py 與 assets/conftest_template.py 當作起始範本。

給技能一個具體的後端任務

azure-cosmos-db-py usage 最有效的情境，是你明確指定實體、partition key、驗證模式與預期操作。好的輸入例如：「為 FastAPI 建立一個 ProjectService，使用 Cosmos DB，以 workspace_id 分區，支援 create/get/update/delete，本機開發可用 emulator，並提供 pytest fixtures 供 service 測試使用。」這會給技能足夠的結構，去選對 document model 與 repository pattern。

提示中該包含哪些資訊

一個好的 azure-cosmos-db-py guide 提示，應該明確寫出：

• 實體名稱與欄位
• partition key 的選擇
• 你是否需要 Azure 驗證、emulator 驗證，或兩者都要
• 同步或非同步的應用程式情境
• 查詢模式，例如 id 查找、篩選清單，或跨 partition 搜尋
• 測試期待，特別是 pytest 與 mocking

如果你的應用程式已經有 models，也請提到你想保留的精確 Pydantic 類別或 JSON 結構。

實際工作流程

先從 Cosmos client 模組開始，再處理 service layer，最後寫測試。這個 repo 的結構本來就支持這樣的順序：先做 client setup，再處理 CRUD/service 模式，接著才是 fixtures 與錯誤處理。這樣的流程能減少返工，因為 partitioning 與驗證決策會影響後面的所有內容。

azure-cosmos-db-py 技能 FAQ

這個技能只適用於 Azure 主機化應用程式嗎？

不是。azure-cosmos-db-py 技能同時支援本機 emulator 開發與 Azure 部署。當你希望同一套程式碼能同時跑在開發與正式環境時，這種雙路徑設定是它最實用的特點之一。

如果我已經懂 Cosmos SDK，還需要這個技能嗎？

如果你想要的是可重複使用的後端模式，答案是需要。這個技能會針對連線重用、service 邊界、考量 partition 的存取方式，以及測試 fixtures 提供更有主張的結構。一般提示也許能給你 SDK 程式片段；但這個技能更適合用來塑造可維護的 service layer。

這個技能對初學者友善嗎？

如果你已經懂基本的 Python 應用程式結構，並且想要一條有引導的實作路徑，那它對初學者算友善。若你需要的是從零開始的 Cosmos DB 概念入門，它就比較不適合。azure-cosmos-db-py skill FAQ 的重點是：當你準備開始建置時再使用它，而不是還在猶豫要不要選這個資料庫時就用。

什麼情況下不該使用它？

不要把它用在非 Python 技術棧、原始資料搬移腳本，或 Cosmos DB 並不是合適儲存模型的情況。若你的應用程式沒有清楚的 partition 策略，也不適合用它；這個技能預設你已經能定義文件會如何被存取。

如何改進 azure-cosmos-db-py 技能

先把資料存取模式講清楚

要提升 azure-cosmos-db-py 的輸出品質，最關鍵的是先說明文件實際會怎麼被讀寫。請明講查詢是以主 ID、父層範圍 ID，還是篩選清單為主。如果你省略這些資訊，產生出來的設計也許技術上正確，卻可能對你的真實查詢模式效率不佳。

提供精確的限制條件與環境資訊

請包含你是否使用 DefaultAzureCredential、Cosmos emulator，或兩者都要；是否需要在非同步程式外再包一層同步 wrapper；以及目前已存在哪些環境變數。例如，說明「本機開發才使用 COSMOS_ENDPOINT、COSMOS_DATABASE_NAME、COSMOS_CONTAINER_ID 與 emulator key」會比只說「把 Cosmos 設定好」有用得多。

先要求第一個產出，不要一次要整個應用程式

最好的 azure-cosmos-db-py usage 通常是先從一個 service 和一個測試檔開始。你可以要求具體輸出，例如 client 模組、ProjectService，或 pytest fixtures。等你看到 document schema、錯誤對應與 partition key 選擇之後，再依情境迭代。

留意常見失敗模式

最常見的錯誤包括：partition key 選錯、把驗證假設寫死，以及忽略 not-found 和 conflict 情境的測試。如果第一版輸出太過泛用，就用更強的輸入來修正：範例文件欄位、預期查詢，以及你想要的 FastAPI route 行為。