Azure Cosmos DB との RESTful 相互作用

2023-07-19

Azure Cosmos DB は、ドキュメント、グラフ、キー値のデータモデルをサポートするグローバルに分散されたマルチモデルデータベースです。このセクションの内容は、REST を介して SQL API を使用してドキュメントリソースを作成、クエリ、および管理するための内容です。

この記事を読むと、次の質問に回答できます。

標準の 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 が応答ペイロード (つまりヘッダーのみ) を sans することを意味します

次の HTTP 動詞図に示すように、POST はフィードリソースに対してのみ発行できます。PUT と DELETE は、アイテムリソースに対してのみ発行できます。GET とHEADは、フィードリソースまたはアイテムリソースに対して発行できます。

標準 HTTP メソッドを使用した相互作用モデル標準 HTTP メソッド

標準の HTTP メソッドを使用した対話モデル

POST HTTP メソッドを使用した新しいリソースの作成

相互作用モデルの操作性を向上させるために、新しいリソース (INSERT) を作成する場合を考えてみましょう。新しいリソースを作成するには、リソースが属しているコンテナーフィードの URI に対するリソースの表現を含む要求本文で HTTP POST 要求を発行する必要があります。要求に必要なプロパティは、リソースの ID のみです。

たとえば、新しいデータベースを作成するには、データベースリソースを /dbs に対して (一意の名前で ID プロパティを設定して) POST します。同様に、新しいコレクションを作成するには、 /dbs/_rid/colls/ などに対してコレクションリソースを POST します。応答には、他のリソースに移動できるリソースの _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 メソッドを使用したストアドプロシージャの登録

リソースを作成して実行するもう 1 つの例として、JavaScript で完全に記述された単純な "HelloWorld" ストアドプロシージャを考えてみましょう。

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

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

ストアドプロシージャを MyDb の下のコレクションに登録するには、に対して POST を発行します /dbs/_rid-db/colls/_rid-coll/sprocs。

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"

新しいリソースの作成とストアドプロシージャの実行だけでなく、SQL クエリの発行にも、POST HTTP 動詞が使用されます。 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 のリソースモデル内のリソースの階層organizationでは、連鎖削除のサポートが必要であり、所有者リソースを削除すると依存リソースが削除されることを指摘する価値があります。依存リソースは所有者リソース以外のノードに分散される可能性があるため、削除が遅延して発生する可能性があります。ガベージコレクションの仕組みに関係なく、リソースを削除すると、クォータはすぐに解放され、使用できるようになります。参照整合性はシステムによって保持されることに注意してください。たとえば、削除されたデータベースにコレクションを挿入したり、存在しなくなったコレクションのドキュメントに対してクエリを実行したりすることはできません。

リソースのフィードに対してを GET 発行したり、コレクションに対してクエリを実行したりすると、何百万もの項目が発生する可能性があるため、サーバーとクライアントの両方がそれらを 1 回のラウンドトリップ/要求と応答の交換の一部として使用することは現実的ではありません。これに対処するために、Azure Cosmos DB を使用すると、クライアントは一度に大きなフィードページをページングできます。クライアントは、[x-ms-continuation] 応答ヘッダーをカーソルとして使用して、次のページに移動できます。

オプティミスティックコンカレンシー

ほとんどの Web アプリケーションは、エンティティタグベースのオプティミスティックコンカレンシーによって、"Lost Update (失われた更新)" や "Lost Delete (失われた削除)" と呼ばれる悩ましい問題に対処しています。エンティティタグは、リソースに関連付けられる論理上のタイムスタンプで、HTTP で手軽に使うことができます。 Cosmos DB では、すべての HTTP 応答に特定のリソースに関連付けられているバージョン (永続的) が含まれていることを確認することで、オプティミスティックコンカレンシー制御がネイティブにサポートされます。次のケースでは、コンカレンシー制御の競合が正しく検出されます。

リソースの最新バージョン ([if-match] 要求ヘッダーを使用して指定) を持つリソースに対して、2 つのクライアントが同時に (PUT/DELETE 動詞を使用して) 変更要求を発行する場合、Cosmos DB データベースエンジンはそれらをトランザクションコンカレンシー制御に適用します。
クライアントから提示されたリソースのバージョンが、[if-match] 要求ヘッダーに指定されたバージョンよりも古い場合、その要求は拒否されます。

接続オプション

Cosmos DB は、論理アドレス指定モデルを公開します。各リソースには、 その_self リンクによって識別される論理的で安定した URI があります。分散ストレージシステムはリージョン間に分散されるため、Cosmos DB のさまざまなデータベースアカウントの下のリソースは多数のマシンにパーティション分割され、各パーティションは高可用性のためにレプリケートされます。特定のパーティションのリソースを管理するレプリカは、物理アドレスを登録します。障害が原因で物理アドレスは時間の経過とともに変化しますが、論理アドレスは安定して一定のままです。論理アドレスから物理アドレスへの変換は、リソースとして内部的に使用できるルーティングテーブルに保持されます。 Cosmos DB では、次の 2 つの接続モードが公開されています。

ゲートウェイモード: クライアントは、論理アドレスから物理アドレスへの変換、またはルーティングの詳細から保護されます。論理 URI を扱い、リソースモデルを完全にナビゲートするだけです。クライアントは論理 URI を使用して要求を発行し、エッジマシンは論理 URI をリソースを管理して要求を転送するレプリカの物理アドレスに変換します。エッジマシンがルーティングテーブルをキャッシュ (および定期的に更新) すると、ルーティングは非常に効率的です。
直接接続モード: クライアントが直接そのプロセス空間でルーティングテーブルを管理し、定期的に更新します。クライアントは直接レプリカに接続し、エッジコンピューターをバイパスできます。

接続モード	Protocol	詳細	Azure Cosmos DB SDK
Gateway	HTTPS	アプリケーションは、論理 URI を使用してエッジノードに直接接続します。そのためネットワークホップが余分に発生します。	REST API、.NET、Node.js、Java、Python、JavaScript
直接接続	HTTPS および TCP	アプリケーションは、ルーティングテーブルに直接アクセスし、クライアント側でルーティングを実行してレプリカに直接接続することができます。	.NET、Java

次の方法で共有

Azure Cosmos DB との RESTful 相互作用

HTTP 動詞の概要

POST HTTP メソッドを使用した新しいリソースの作成

POST HTTP メソッドを使用したストアド プロシージャの登録

POST HTTP メソッドを使用したストアド プロシージャの実行

PUT、GET、および DELETE HTTP 動詞の使用

オプティミスティック コンカレンシー

接続オプション

参照

その他のリソース

POST HTTP メソッドを使用したストアドプロシージャの登録

POST HTTP メソッドを使用したストアドプロシージャの実行

オプティミスティックコンカレンシー