Azure Cosmos DB との RESTful 相互作用

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 動詞がサポートされています。

1. POST: 新しいアイテム リソースを作成します。
2. GET: 既存のアイテム リソースまたはフィード リソースを読み取ります。
3. PUT: 既存のアイテム リソースを置き換えます。
4. DELETE: 既存のアイテム リソースを削除します。
5. HEAD は、GET が応答ペイロード (つまりヘッダーのみ) をサンスすることを意味します

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

標準の 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");  
}  

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

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 メソッドを使用したストアド プロシージャの実行

最後に、前の例のストアド プロシージャを実行するには、次に POST 示すように、ストアド プロシージャ リソース (/dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs/UoEi5w+upwABAAAAAAAAgA==/) の URI に対して発行する必要があります。

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 のリソース モデル内のリソースの階層的な編成では、連鎖削除のサポートが必要であり、所有者リソースを削除すると依存リソースが削除される点に注目してください。 依存リソースは所有者リソース以外のノードに分散される可能性があるため、削除が遅れる可能性があります。 ガベージ コレクションのメカニズムに関係なく、リソースを削除すると、クォータはすぐに解放され、使用できるようになります。 参照整合性はシステムによって保持されることに注意してください。 たとえば、削除されたデータベースにコレクションを挿入したり、存在しなくなったコレクションのドキュメントに対してクエリを実行したりすることはできません。

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

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

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

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

2. クライアントから提示されたリソースのバージョンが、[if-match] 要求ヘッダーに指定されたバージョンよりも古い場合、その要求は拒否されます。

接続オプション

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

• ゲートウェイ モード: クライアントは、論理アドレスから物理アドレスへの変換またはルーティングの詳細からシールドされます。論理 URI を扱い、リソース モデルを RESTful にナビゲートするだけです。 クライアントは論理 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
• Azure Cosmos DB SQL API
• Azure Cosmos DB SQL API SDK
• .NET サンプルからの REST