Python 實作 Azure Cosmos DB (二) — CosmosClient

Where
5 min readOct 21, 2019

開始之前,還沒有看過(一)的,記得先看了解環境如何設置喔!

Python 實作 Azure Cosmos DB (一) — 環境建置

在 Azure 上建立好 Cosmos 資源後,接著就會需要新增 Database、Collection 及資料等,透過使用 CosmosClient 這個 class,你可以對 Cosmos 發送 request ,進行像是新增、刪除、更新、取代等的操作行為。查看文件是一個好習慣,這裡整理的 CosmosClient 可操作的動作。

初始化建立連線

首先,透過以下方法建立 CosmosClient,其中會需要使用到 Cosmos 的 endpoint 和 key。

CosmosClient(url_connection, auth, connection_policy=None, consistency_level='Session')

將 ENDPONIT 及 PRIMARYKEY 改成上一篇記錄下來的 URI 和 Primary key。

一般來說,會比較建議把這些連線字串寫在 config 檔裡面,而非寫死在程式碼當中。

建立 Database、Container 及資料

使用 CreateDatbase 的方法來建立一個資料庫。

CreateDatabase(database, options=None)

使用 CreateContainer 來建立 Container。

CreateContainer(database_link, collection, options=None)

最後,透過 CreateItem 來新增一筆資料。

CreateItem(database_or_Container_link, document, options=None)

你可以參考以下的程式碼來完成從建立 Database、Container 到添加資料一整個流程,而我這邊是設定以 region 為 partition key。

搜索資料

資料庫最重要的,就是如何去撈取資料。因為我們使用的是 Cosmos SQL API,因此可以使用 SQL 的語法去做資料庫資料的篩選動作。使用 QueryItems 的方法可以進行資料的搜索。

QueryItems(database_or_Container_link, query, options=None, partition_key=None)

項目更新 / 取代

在處理 Database 資料的同時,我們可能會遇到需要去更新資料的問題。

Upsert

根據官方的說明,UpsertItem 的方法解釋為 Upserts a document in a collection,很棒很棒,完全不懂!

UpsertItem(database_or_Container_link, document, options=None)

利用 Document ID 或 Database ID 來搜尋符合給定 Item ID 的項目,如有相同 ID 則取代;若沒有則新增一筆。若你不希望沒有找到 ID 時直接新增一筆,你可以將 option = true。

options['disableAutomaticIdGeneration'] boolDisables the automatic id generation. If id is missing in the body and this option is true, an error will be returned.

當你需要更新你 Document 裡的資料時,你比較適合使用 Upsert 這個方法。

Replace

利用 Item link 來搜尋並取代一整個項目。所以使用這個方法是直接去找你要取代的 document 項目,它不會去管你的 ID 是否相同,直接取代。

ReplaceItem(document_link, new_document, options=None)

關於 Item link 你可以在把一整筆資料撈出來的同時,發現除了當初建立資料的欄位,系統自動也幫你新增了其他欄位供 Cosmos DB 使用,你可以透過系統建立的 [_self] 欄位來撈取 Item link。

當你需要取代特定一筆資料時,建議使用 Replace 這個方法。

兩個的 link 連結可能會有點不同。如果是 Replace 的話,會先用 query 的方式把 item 撈出來,在用 _self 這個欄位取得連結。

client.ReplaceItem(item['_self'],newcontent)

而如果是使用 Upsert 的話,則可直接使用 Container 的 link。

client.UpsertItem(container_link,newcontent,True)

刪除資料

這邊很簡單的你可以選擇要刪除 Database、Container 或 Item。

DeleteDatabase(database_link, options=None)DeleteContainer(collection_link, options=None)DeleteItem(document_link, options=None)

後記

今天先簡單的教大家快速的上手 Azure Cosmos DB Pyhton SDK,如果還有機會的話,希望還可以更深入的寫教學。

只是,總感覺遙遙無期呢!⁄(⁄ ⁄•⁄ω⁄•⁄ ⁄)⁄

Reference

--

--