與 Azure Cosmos DB 的 RESTful 互動

發行項
08/05/2023

Azure Cosmos DB 是一個全域散發的多模型資料庫，可支援檔、圖形和索引鍵值資料模型。本節中的內容是透過 REST 建立、查詢及管理檔資源。

藉由閱讀本文，您可以回答下列問題：

標準 HTTP 方法如何搭配 Azure Cosmos DB 資源使用？
如何使用 POST 建立新的資源？
如何使用 POST 註冊預存程序？
Azure Cosmos DB 如何支援並行控制？
HTTPS 和 TCP 的連接選項有哪些？

如果您想要瞭解如何使用 REST 對特定資源執行 CRUD 作業的資訊，請參閱使用 Azure Cosmos DB REST API 的一般工作。如果您要尋找如何使用 C# 和 REST 執行 CRUD 作業的範例，請參閱 GitHub 上的 .NET 範例中的 REST 。

注意

您也可以使用 Cosmos DB SDK 在 Cosmos DB 資源上執行 CRUD 作業。如需範例，請參閱 Azure Cosmos DB 範例。如需 SDK 下載和檔的連結，請參閱 Cosmos DB SDK。

HTTP 動詞命令的概觀

Azure Cosmos DB 資源使用其標準解譯支援下列 HTTP 動詞：

POST 方法會建立新的項目資源
GET 方法會讀取現有項目或摘要資源
PUT 方法會取代現有項目資源
DELETE 方法會刪除現有項目資源
HEAD 表示 GET 會清理回應承載 (，也就是標頭)

如以下 HTTP 動詞命令圖所示，POST 只能對摘要資源發出；PUT、DELETE 只能對項目資源發出；GET 和 HEAD 能對摘要或項目資源發出。

使用標準 HTTP 方法

使用標準 HTTP 方法的互動模型

使用 POST HTTP 方法建立新的資源

為了更加了解互動模型，我們來看一下建立新資源 (也稱為 INSERT) 的情況。若要建立新的資源，您必須向要求本文發出 HTTP POST 要求，其中包含資源所屬容器摘要 URI 的資源標記法。要求的唯一必要屬性是資源的識別碼。

例如，若要建立新的資料庫，您可以藉由針對 /dbs 設定唯一名稱) 的 ID 屬性，將資料庫資源 (POST。同樣地，若要建立新的集合，您可以針對 /dbs/_rid/colls/ 張貼集合資源等等。回應包含系統產生的屬性的完整認可資源，包括資源 _self 連結，您可以使用該連結來巡覽至其他資源。作為簡單 HTTP 互動模型的範例，用戶端可以發出 HTTP 要求，在帳戶內建立新的資料庫。

POST https://fabrikam.documents.azure.com/dbs  
{  
    "id":"MyDb"
}

例如，若要建立新的資料庫，您可以 POST 藉由針對設定唯一名稱) 的 ID 屬性來 (/dbs 資料庫資源。同樣地，若要建立新的集合，您可以 POST 依 /dbs/_rid/colls/ 此類序建立集合資源。回應包含具有系統產生屬性的完整認可資源，包括 _self 您可以巡覽至其他資源的資源連結。作為簡單 HTTP 互動模型的範例，用戶端可以發出 HTTP 要求，在帳戶內建立新的資料庫。

Azure Cosmos DB 服務會以成功的回應和狀態碼回應，指出成功建立資料庫。

HTTP/1.1 201 Created  
Content-Type: application/json  
x-ms-request-charge: 4.95  
...  
  
{  
    "id": "MyDb",  
    "_rid": "UoEi5w==",  
    "_self": "dbs/UoEi5w==/",  
    "_ts": 1407370063,  
    "_etag": "00000100-0000-0000-0000-54b636600000",  
    "_colls": "colls/",  
    "_users": "users/"  
}

使用 POST HTTP 方法註冊預存程序

再來看另一個建立和執行資源的範例，考量 "HelloWorld" 預存程序完全是以 JavaScript 撰寫。

function HelloWorld() {  
    var context = getContext();  
    var response = context.getResponse();  

    response.setBody("Hello, World");  
}

預存程式可以向 MyDb 底下的集合註冊，方法是針對 /dbs/_rid-db/colls/_rid-coll/sprocs 發出 POST。

POST https://fabrikam.documents.azure.com/dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs HTTP/1.1  
  
{  
    "id": "HelloWorld",  
    "body": "function HelloWorld() {  
                var context = getContext();  
                var response = context.getResponse();  

                response.setBody("Hello, World");  
            }"  
}

Azure Cosmos DB 服務會以成功的回應和狀態碼回應，指出預存程式成功註冊。

HTTP/1.1 201 Created  
Content-Type: application/json  
x-ms-request-charge: 4.95  
...  
  
{  
    "body": "function HelloWorld() {  
        var context = getContext();  
        var response = context.getResponse();  

        response.setBody("Hello, World");  
        }",  
    "id": "HelloWorld"  
    "_rid": "UoEi5w+upwABAAAAAAAAgA==",  
    "_ts" :  1421227641  
    "_self": "dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs/UoEi5w+upwABAAAAAAAAgA==/",  
    "_etag": "00002100-0000-0000-0000-50f71fda0000"  
}

使用 POST HTTP 方法執行預存程序

最後，若要在上述範例中執行預存程式，必須針對預存程式資源的 /dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs/UoEi5w+upwABAAAAAAAAgA==/ URI 發出 POST ， () ，如下所示。

POST https://fabrikam.documents.azure.com/dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs/UoEi5w+upwABAAAAAAAAgA== HTTP/1.1

Azure Cosmos DB 服務會回應下列回應。

HTTP/1.1 200 OK  
  
"Hello World"

請注意，POST HTTP 動詞命令可用於建立新資源、執行預存程序和發出 SQL 查詢。為了說明 SQL 查詢如何執行，請看下列說明。

POST https://fabrikam.documents.azure.com/dbs/UoEi5w==/colls/UoEi5w+upwA=/docs HTTP/1.1  
...  
x-ms-documentdb-isquery: True  
x-ms-documentdb-query-enable-scan: True  
Content-Type: application/query+json  
...  

{"query":"SELECT f.LastName AS Name, f.Address.City AS City FROM Families f WHERE f.id='AndersenFamily' OR f.Address.City='NY'"}

服務會回應 SQL 查詢的結果。

HTTP/1.1 200 Ok  
...  
x-ms-activity-id: 83f9992c-abae-4eb1-b8f0-9f2420c520d2  
x-ms-item-count: 2  
x-ms-session-token: 4  
x-ms-request-charge: 3.1  
Content-Type: application/json1  

{"_rid":"UoEi5w+upwA=","Documents":[{"Name":"Andersen","City":"Seattle"},{"Name":"Wakefield","City":"NY"}],"_count":2}

使用 PUT、GET、和 DELETE HTTP 動詞命令

針對資源的_self連結，將資源數量取代或讀取為發出 PUT (的有效要求本文) 和 GET 動詞。同樣地，刪除資源會針對資源的_self連結發出 DELETE 動詞。值得一提的是，Azure Cosmos DB 資源模型中資源的階層式組織需要支援串聯刪除，其中刪除擁有者資源會導致刪除相依資源。相依資源可能會散佈在擁有者資源以外的其他節點，因此，刪除作業可能進展緩慢。不論記憶體回收的機制為何，資源一經刪除，就會立即釋出配額供您使用。請注意，系統會保留參考完整性。例如，您不可以將集合插入至已刪除的資料庫，或者取代或查詢不再存在之集合的文件。

GET針對資源摘要發出，或查詢集合可能會導致數百萬個專案，因此讓兩部伺服器都無法具體化它們和用戶端，以作為單一往返/要求和回應交換的一部分來取用它們。為了解決此問題，Azure Cosmos DB 可讓用戶端一次分頁到大型摘要頁面。用戶端可以使用 [x-ms-continuation] 回應標頭做為資料指標，以導覽到下一頁。

樂觀並行控制

大部分的 Web 應用程式都依賴以實體標記為基礎的開放式並行存取控制，以避免令人厭煩的「遺失更新」和「遺失刪除」問題。實體標記是支援 HTTP 且與資源相關聯的邏輯時間戳記。 Cosmos DB 原生支援開放式平行存取控制，方法是確保每個 HTTP 回應都包含與特定資源相關聯的版本 (永久) 。在下列情況時，可正確偵測到並行存取控制衝突：

如果兩個用戶端透過 PUT/ DELETE 動詞) 同時發出變動 (要求，且資源上具有透過 [if-match] 要求) 標頭所指定之最新版的資源 (，Cosmos DB 資料庫引擎會將要求主體設為交易式並行控制。
如果用戶端提出舊版資源 (透過 [if-match] 要求標頭來指定)，則會拒絕其要求。

連線選項

Cosmos DB 會公開邏輯定址模型，其中每個資源都有其 _self 連結所識別的邏輯和穩定 URI。當分散式儲存體系統分散到區域時，Cosmos DB 中各種資料庫帳戶下的資源會分割在多部機器上，而且每個分割區都會複寫以提供高可用性。管理給定資料分割資源的複本會註冊實體位址。雖然實體位址在一段時間後就會因為失敗而有所變更，但是其邏輯位址仍會維持不變。同時以資源形式在內部提供使用的路由表，會保存將邏輯位址轉譯為實體位址的方法。 Cosmos DB 會公開兩種連線模式：

閘道器模式 ：用戶端不會接觸到邏輯位址與實體位址的轉換過程或是路由細節；他們只會處理邏輯 URI，並以符合 REST 限制的方式導覽資源模型。用戶端使用邏輯 URI 發出要求，而 Edge 電腦會將邏輯 URI 轉譯為負責管理資源及轉送要求之複本的實體位址。由於有 Edge 電腦在快取 (並定期重新整理) 路由表，路由作業會十分有效率。
直接連線模式 ：用戶端直接在其程序空間中管理路由表，並定期進行重新整理。用戶端可以略過 Edge 電腦，直接與複本連線。

連線模式	通訊協定	詳細資料	Azure Cosmos DB SDK
閘道	HTTPS	應用程式使用邏輯 URI 直接與 Edge 節點連線。這會發生額外的網路躍點。	REST API、.NET、Node.js、Java、Python、JavaScript
直接連線	HTTPS 和 TCP	應用程式可以直接存取路由表，並執行用戶端路由直接與複本連線。	.NET、JAVA