Azure Cosmos DB for MongoDB に格納されているデータを管理するために MongoDB 拡張コマンドを使用する
適用対象: 
MongoDB
次のドキュメントには、Azure Cosmos DB for MongoDB に固有のカスタム アクション コマンドが含まれています。 これらのコマンドを使用して、Azure Cosmos DB 容量モデルに固有のデータベース リソースを作成および取得できます。
Azure Cosmos DB for MongoDB を使用すると、Azure Cosmos DB の共有の利点を享受できます。 このような利点には以下のものが含まれますが、これらだけではありません。
- グローバル配信
- 自動シャーディング
- 高可用性
- 待ち時間の保証
- 保存時の暗号化
- バックアップ
既存の MongoDB アプリケーションへの投資を維持しながら、これらの利点を享受できます。 Azure Cosmos DB for MongoDB との通信は、オープン ソースで公開されている任意の MongoDB クライアント ドライバーを使用して行うことができます。 Azure Cosmos DB for MongoDB では、MongoDB ワイヤー プロトコルに従うことにより、既存のクライアント ドライバーを利用できます。
MongoDB のプロトコル サポート
Azure Cosmos DB for MongoDB は、MongoDB サーバー バージョン 4.0、3.6、3.2 と互換性があります。 詳細については、バージョン 4.0、3.6、3.2 でサポートされている機能と構文に関するページを参照してください。
次の拡張コマンドでは、データベース要求を使用して Azure Cosmos DB 固有のリソースを作成および変更します。
データベースの作成
データベースの作成拡張コマンドは、新しい MongoDB データベースを作成します。 データベース名は、use database コマンドによって設定されたデータベース コンテキストから使用できます。 次の表では、コマンド内のパラメーターについて説明します。
| フィールド | タイプ | 説明 |
|---|---|---|
customAction |
string |
カスタム コマンドの名前。 値は CreateDatabase である必要があります。 |
offerThroughput |
int |
データベースに設定したプロビジョニング済みスループット。 このパラメーターは省略可能です。 |
autoScaleSettings |
Object |
自動スケーリング モードの場合は必須です。 このオブジェクトには、自動スケーリング容量モードに関連付けられている設定が含まれています。 maxThroughput の値を設定できます。これは、コレクションがその数まで動的に増加できる、要求ユニットの最大数を示します。 |
出力
コマンドが成功した場合は、次の応答が返されます。
{ "ok" : 1 }
出力内のパラメーターについては、「既定の出力」を参照してください。
例: データベースを作成する
すべての既定値を使用する "test" という名前のデータベースを作成するには、次のコマンドを使用します。
use test
db.runCommand({customAction: "CreateDatabase"});
このコマンドでは、データベースレベルのスループットを指定せずにデータベースを作成します。 この操作は、このデータベース内のコレクションで、使用する必要があるスループットの量を指定する必要があることを意味します。
例: スループットを指定してデータベースを作成する
"test" という名前でデータベースを作成し、データベースレベルのプロビジョニング済みスループットを 1000 RU に指定するには、次のコマンドを使用します。
use test
db.runCommand({customAction: "CreateDatabase", offerThroughput: 1000 });
このコマンドでは、データベースを作成し、それにスループットを設定します。 コレクションが特定のスループット レベルで作成される場合を除き、このデータベース内のすべてのコレクションは、設定されたスループットを共有します。
例: 自動スケーリング スループットのデータベースを作成する
"test" という名前のデータベースを作成し、データベースレベルで自動スケーリング最大スループットを 20,000 RU/秒に指定するには、次のコマンドを使用します。
use test
db.runCommand({customAction: "CreateDatabase", autoScaleSettings: { maxThroughput: 20000 } });
データベースを更新する
データベースの更新拡張コマンドは、指定したデータベースに関連付けられているプロパティを更新します。 プロビジョニングされたスループットから自動スケーリングへのデータベースの変更やその逆の変更は、Azure portal でのみサポートされています。 次の表では、コマンド内のパラメーターについて説明します。
| フィールド | タイプ | 説明 |
|---|---|---|
customAction |
string |
カスタム コマンドの名前。 値は UpdateDatabase である必要があります。 |
offerThroughput |
int |
データベースでデータベースレベルのスループットが使用されている場合に、データベースに対して設定する新しいプロビジョニング済みスループット |
autoScaleSettings |
Object |
自動スケーリング モードの場合は必須です。 このオブジェクトには、自動スケーリング容量モードに関連付けられている設定が含まれています。 maxThroughput の値を設定できます。これは、データベースがその数まで動的に増加できる、要求ユニットの最大数を示します。 |
このコマンドは、セッションのコンテキストで指定されたデータベースを使用します。 これは、use <database> コマンドで使用したのと同じデータベースです。 現時点では、このコマンドを使用してデータベース名を変更することはできません。
出力
コマンドが成功した場合は、次の応答が返されます。
{ "ok" : 1 }
出力内のパラメーターについては、「既定の出力」を参照してください。
例: データベースに関連付けられているプロビジョニング済みスループットを更新する
"test" という名前のデータべースのプロビジョニング済みスループットを 1200 RU に更新するには、次のコマンドを使用します。
use test
db.runCommand({customAction: "UpdateDatabase", offerThroughput: 1200 });
例: データベースに関連付けられている自動スケーリング スループットを更新する
"test" という名前のデータベースのプロビジョニング済みスループットを 20,000 RU に更新したり、これを自動スケーリング スループット レベルに変換したりするには、次のコマンドを使用します。
use test
db.runCommand({customAction: "UpdateDatabase", autoScaleSettings: { maxThroughput: 20000 } });
データベースの取得
データベースの取得拡張コマンドは、データベース オブジェクトを返します。 データベース名は、コマンドの実行対象のデータベース コンテキストから使用されます。
{
customAction: "GetDatabase"
}
次の表では、コマンド内のパラメーターについて説明します。
| フィールド | タイプ | 説明 |
|---|---|---|
customAction |
string |
カスタム コマンドの名前。 値は GetDatabase である必要があります。 |
出力
コマンドが成功すると、応答には次のフィールドを持つドキュメントが含まれます。
| フィールド | タイプ | 説明 |
|---|---|---|
ok |
int |
応答の状態。 1 == 成功。 0 == 失敗。 |
database |
string |
データベースの名前です。 |
provisionedThroughput |
int |
データベースで手動のデータベースレベルのスループットが使用されている場合に、データベースに対して設定するプロビジョニング済みスループット |
autoScaleSettings |
Object |
このオブジェクトには、自動スケーリング モードを使用している場合に、データベースに関連付けられている容量パラメーターが格納されます。 maxThroughput の値は、データベースがその数まで動的に増加できる、要求ユニットの最大数を示します。 |
コマンドが失敗すると、既定のカスタム コマンド応答が返されます。 出力内のパラメーターについては、「既定の出力」を参照してください。
例: データベースを取得する
"test" という名前のデータベースのデータベース オブジェクトを取得するには、次のコマンドを使用します。
use test
db.runCommand({customAction: "GetDatabase"});
データベースにスループットが関連付けられていない場合、出力は次のようになります。
{ "database" : "test", "ok" : 1 }
データベースに データベースレベルの手動スループットが関連付けられている場合、出力には provisionedThroughput 値が表示されます。
{ "database" : "test", "provisionedThroughput" : 20000, "ok" : 1 }
データベースにデータベースレベルの自動スケーリングのスループットが関連付けられている場合、出力には、データベースの最小 RU/秒を説明する provisionedThroughput と、データベースの最大 RU/秒を示す maxThroughput を含む autoScaleSettings オブジェクトが表示されます。
{
"database" : "test",
"provisionedThroughput" : 2000,
"autoScaleSettings" : {
"maxThroughput" : 20000
},
"ok" : 1
}
コレクションの作成
コレクションの作成拡張コマンドは、新しい MongoDB コレクションを作成します。 データベース名は、use database コマンドによって設定されたデータベース コンテキストから使用されます。 CreateCollection コマンドの形式は次のとおりです。
{
customAction: "CreateCollection",
collection: "<Collection Name>",
shardKey: "<Shard key path>",
// Replace the line below with "autoScaleSettings: { maxThroughput: (int) }" to use Autoscale instead of Provisioned Throughput. Fill the required Autoscale max throughput setting.
offerThroughput: (int) // Provisioned Throughput enabled with required throughput amount set.
indexes: [{key: {_id: 1}, name: "_id_1"}, ... ] // Optional indexes (3.6+ accounts only).
}
次の表では、コマンド内のパラメーターについて説明します。
| フィールド | Type | Required | 説明 |
|---|---|---|---|
customAction |
string |
必須 | カスタム コマンドの名前。 値は CreateCollection である必要があります。 |
collection |
string |
必須 | コレクションの名前。 特殊文字およびスペースは使用できません。 |
offerThroughput |
int |
省略可能 | データベースに設定するプロビジョニング済みスループット。 このパラメーターが指定されていない場合、既定で最小の 400 RU/秒に設定されます。 * 10,000 RU/秒を超えるスループットを指定するには、shardKey パラメーターが必要です。 |
shardKey |
string |
スループットの高いコレクションの場合は必須です | シャード コレクション用シャード キーへのパス。 offerThroughput で 10,000 RU/秒を超える値を設定する場合、このパラメーターは必須です。 この値が指定されている場合は、挿入されたすべてのドキュメントでこのキーと値が必要になります。 |
autoScaleSettings |
Object |
自動スケーリング モードの場合は必須です | このオブジェクトには、自動スケーリング容量モードに関連付けられている設定が含まれています。 maxThroughput の値を設定できます。これは、コレクションがその数まで動的に増加できる、要求ユニットの最大数を示します。 |
indexes |
Array |
必要に応じてインデックスを構成します。 このパラメーターは、3.6 以降のアカウントでのみサポートされています。 | 存在する場合は、_id にインデックスが必要です。 配列内の各エントリには、1 つ以上のフィールドのキーと名前を含める必要があります。また、インデックス オプションを含めることもできます。 たとえば、フィールドに複合一意インデックスを作成し、aとb というエントリを使用します {key: {a: 1, b: 1}, name:"a_1_b_1", unique: true}。 |
出力
既定のカスタム コマンド応答を返します。 出力内のパラメーターについては、「既定の出力」を参照してください。
例: 最小構成でコレクションを作成する
名前 "testCollection" と既定値を持つ新しいコレクションを作成するには、次のコマンドを使用します。
use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection"});
この操作により、400RU/秒のシャード化されていない新しい固定のコレクションが作成され、_id フィールドにインデックスが自動的に作成されます。 この種類の構成は、insert() 関数を使用して新しいコレクションを作成するときにも適用されます。 次に例を示します。
use test
db.newCollection.insert({});
例: シャード化されていないコレクションを作成する
"testCollection" という名前で、プロビジョニング済みスループットが 1000 RU のシャード化されていないコレクションを作成するには、次のコマンドを使用します。
use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection", offerThroughput: 1000});
シャード キーを指定しなくても、最大で 10,000 RU/秒のコレクションを offerThroughput として作成できます。 スループットの高いコレクションについては、次のセクションをご覧ください。
例: シャード化されたコレクションを作成する
"testCollection" という名前で、プロビジョニング済みスループットが 11,000 RU で、shardkey プロパティ "a.b" を持つシャード コレクションを作成するには、次のコマンドを使用します。
use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection", offerThroughput: 11000, shardKey: "a.b" });
このコマンドでは、offerThroughput に 10,000 RU/秒以上が指定されたため、shardKey パラメーターが必要になります。
例: シャード化されていない自動スケーリング コレクションを作成する
'testCollection' という名前で、4,000 RU/秒に設定された自動スケーリング スループット容量を使用する のシャード化されていないコレクションを作成するには、次のコマンドを使用します。
use test
db.runCommand({
customAction: "CreateCollection", collection: "testCollection",
autoScaleSettings:{
maxThroughput: 4000
}
});
autoScaleSettings.maxThroughput 値には、シャード キーを使用せずに 4,000 RU/秒から 10,000 RU/秒の範囲を指定できます。 自動スケーリング スループットがさらに高い場合、shardKey パラメーターを指定する必要があります。
例: シャード化された自動スケーリング コレクションを作成する
'testCollection' という名前で、'a.b' と呼ばれるシャード キーを持ち、20,000 RU/秒に設定された自動スケーリング スループット容量を使用するシャード コレクションを作成するには、次のコマンドを使用します。
use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection", shardKey: "a.b", autoScaleSettings: { maxThroughput: 20000 }});
コレクションの更新
コレクションの更新拡張コマンドは、指定したコレクションに関連付けられているプロパティを更新します。 プロビジョニングされたスループットから自動スケーリングへのコレクションの変更やその逆の変更は、Azure portal でのみサポートされています。
{
customAction: "UpdateCollection",
collection: "<Name of the collection that you want to update>",
// Replace the line below with "autoScaleSettings: { maxThroughput: (int) }" if using Autoscale instead of Provisioned Throughput. Fill the required Autoscale max throughput setting. Changing between Autoscale and Provisioned throughput is only supported in the Azure Portal.
offerThroughput: (int) // Provisioned Throughput enabled with required throughput amount set.
indexes: [{key: {_id: 1}, name: "_id_1"}, ... ] // Optional indexes (3.6+ accounts only).
}
次の表では、コマンド内のパラメーターについて説明します。
| フィールド | タイプ | 説明 |
|---|---|---|
customAction |
string |
カスタム コマンドの名前。 値は UpdateCollection である必要があります。 |
collection |
string |
コレクションの名前。 |
offerThroughput |
int |
コレクションに設定するプロビジョニング済みスループット。 |
autoScaleSettings |
Object |
自動スケーリング モードの場合は必須です。 このオブジェクトには、自動スケーリング容量モードに関連付けられている設定が含まれています。 maxThroughput の値は、コレクションがその数まで動的に増加できる、要求ユニットの最大数を示します。 |
indexes |
Array |
必要に応じてインデックスを構成します。 このパラメーターは、3.6 以降のアカウントでのみサポートされています。 存在する場合、指定されたインデックスのセット (インデックスの削除を含む) によってコレクションの既存のインデックスが置き換えられます。 _id にインデックスが必要です。 配列内の各エントリには、1 つ以上のフィールドのキーと名前を含める必要があります。また、インデックス オプションを含めることもできます。 たとえば、フィールド a と b に複合一意インデックスを作成するには、{key: {a: 1, b: 1}, name: "a_1_b_1", unique: true} というエントリを使用します。 |
出力
既定のカスタム コマンド応答を返します。 出力内のパラメーターについては、「既定の出力」を参照してください。
例: コレクションに関連付けられているプロビジョニング済みスループットを更新する
"testCollection" という名前のコレクションのプロビジョニング済みスループットを 1200 RU に更新するには、次のコマンドを使用します。
use test
db.runCommand({customAction: "UpdateCollection", collection: "testCollection", offerThroughput: 1200 });
コレクションの取得
コレクションの取得カスタム コマンドは、コレクション オブジェクトを返します。
{
customAction: "GetCollection",
collection: "<Name of the collection>"
}
次の表では、コマンド内のパラメーターについて説明します。
| フィールド | タイプ | 説明 |
|---|---|---|
customAction |
string |
カスタム コマンドの名前。 値は GetCollection である必要があります。 |
collection |
string |
コレクションの名前。 |
出力
コマンドが成功すると、応答には次のフィールドを持つドキュメントが含まれます
| フィールド | タイプ | 説明 |
|---|---|---|
ok |
int |
応答の状態。 1 == 成功。 0 == 失敗。 |
database |
string |
データベースの名前です。 |
collection |
string |
コレクションの名前。 |
shardKeyDefinition |
document |
シャード キーとして使用されるインデックス仕様ドキュメント。 このフィールドは省略可能な応答パラメーターです。 |
provisionedThroughput |
int |
コレクションに設定するプロビジョニング済みスループット。 このフィールドは省略可能な応答パラメーターです。 |
autoScaleSettings |
Object |
このオブジェクトには、自動スケーリング モードを使用している場合に、データベースに関連付けられている容量パラメーターが格納されます。 maxThroughput の値は、コレクションがその数まで動的に増加できる、要求ユニットの最大数を示します。 |
コマンドが失敗すると、既定のカスタム コマンド応答が返されます。 出力内のパラメーターについては、「既定の出力」を参照してください。
例: コレクションを取得する
"testCollection" という名前のコレクションのコレクション オブジェクトを取得するには、次のコマンドを使用します。
use test
db.runCommand({customAction: "GetCollection", collection: "testCollection"});
コレクションにスループット容量が関連付けられている場合、これに provisionedThroughput 値が含まれ、出力は次のようになります。
{
"database" : "test",
"collection" : "testCollection",
"provisionedThroughput" : 400,
"ok" : 1
}
コレクションに自動スケーリング スループットが関連付けられている場合、これには maxThroughput パラメーターを持つ autoScaleSettings オブジェクトが含まれます。このパラメーターにより、コレクションがその量まで動的に増加する最大スループットが定義されます。 また、これには provisionedThroughput 値も含まれます。この値により、コレクションに要求がない場合に、このコレクションがその量まで減少する最小スループットが定義されます。
{
"database" : "test",
"collection" : "testCollection",
"provisionedThroughput" : 1000,
"autoScaleSettings" : {
"maxThroughput" : 10000
},
"ok" : 1
}
コレクションが自動スケーリング モードまたは手動のいずれかで、データベースレベルのスループットを共有している場合、出力は次のようになります。
{ "database" : "test", "collection" : "testCollection", "ok" : 1 }
{
"database" : "test",
"provisionedThroughput" : 2000,
"autoScaleSettings" : {
"maxThroughput" : 20000
},
"ok" : 1
}
変更ストリームの並列化
変更ストリームを大規模に使用する場合は、負荷を均一に分散させることが推奨されます。 次のコマンドは、1 つまたは複数の変更ストリーム再開トークンを返します。それぞれ 1 つの物理シャードまたはパーティションのデータに対応します (複数の論理シャードまたはパーティションが 1 つの物理パーティションに存在できます)。 各再開トークンにより、watch() は、その物理シャードまたはパーティションからのデータのみを返します。
変更ストリームを効率的にスケーリングするには、各再開トークンで db.collection.watch() (トークンごとに 1 つのスレッド) を使用します。
{
customAction: "GetChangeStreamTokens",
collection: "<Name of the collection>",
startAtOperationTime: "<BSON Timestamp>" // Optional. Defaults to the time the command is run.
}
例: ストリーム トークンを取得する
カスタム コマンドを実行して、各物理シャードまたはパーティションの再開トークンを取得します。
use test
db.runCommand({customAction: "GetChangeStreamTokens", collection: "<Name of the collection>"})
GetChangeStreamTokens カスタム コマンドから返された再開トークンごとに watch () スレッドまたはプロセスを実行します。 次に、1 つのスレッドの例を示します。
db.test_coll.watch([{ $match: { "operationType": { $in: ["insert", "update", "replace"] } } }, { $project: { "_id": 1, "fullDocument": 1, "ns": 1, "documentKey": 1 } }],
{fullDocument: "updateLookup",
resumeAfter: { "_data" : BinData(0,"eyJWIjoyLCJSaWQiOiJQeFVhQUxuMFNLRT0iLCJDb250aW51YXRpb24iOlt7IkZlZWRSYW5nZSI6eyJ0eXBlIjoiRWZmZWN0aXZlIFBhcnRpdGlvbiBLZXkgUmFuZ2UiLCJ2YWx1ZSI6eyJtaW4iOiIiLCJtYXgiOiJGRiJ9fSwiU3RhdGUiOnsidHlwZSI6ImNvbnRpbndkFLbiIsInZhbHVlIjoiXCIxODQ0XCIifX1dfQ=="), "_kind" : NumberInt(1)}})
resumeAfter フィールドのドキュメント (値) は、再開トークンを表します。 コマンド watch() は、GetChangeStreamTokens カスタム コマンドが実行された後にその物理パーティションから挿入、更新、または置換されたすべてのドキュメントに対して、カーソルを返します。 返されるデータのサンプルは次のとおりです。
{
"_id": {
"_data": BinData(0,
"eyJWIjoyLCJSaWQiOiJQeFVhQUxuMFNLRT0iLCJDfdsfdsfdsft7IkZlZWRSYW5nZSI6eyJ0eXBlIjoiRWZmZWN0aXZlIFBhcnRpdGlvbiBLZXkgUmFuZ2UiLCJ2YWx1ZSI6eyJtaW4iOiIiLCJtYXgiOiJGRiJ9fSwiU3RhdGUiOnsidHlwZSI6ImNvbnRpbnVhdGlvbiIsInZhbHVlIjoiXCIxOTgwXCIifX1dfQ=="),
"_kind": 1
},
"fullDocument": {
"_id": ObjectId("60da41ec9d1065b9f3b238fc"),
"name": John,
"age": 6
},
"ns": {
"db": "test-db",
"coll": "test_coll"
},
"documentKey": {
"_id": ObjectId("60da41ec9d1065b9f3b238fc")
}
}
返される各ドキュメントには再開トークンが含まれます (すべてのページで同じです)。 この再開トークンは、スレッドまたはプロセスが停止した場合に保存して再利用する必要があります。 この再開トークンは、中断した場所からデータを取得し、その物理パーティションからのみデータを受信します。
カスタム コマンドの既定の出力
指定しない場合、カスタムの応答には次のフィールドを持つドキュメントが含まれます。
| フィールド | タイプ | 説明 |
|---|---|---|
ok |
int |
応答の状態。 1 == 成功。 0 == 失敗。 |
code |
int |
コマンドが失敗した場合 (ok == 0) のみ返されます。 MongoDB のエラー コードが含まれます。 このフィールドは省略可能な応答パラメーターです。 |
errMsg |
string |
コマンドが失敗した場合 (ok == 0) のみ返されます。 わかりやすいエラー メッセージが含まれます。 このフィールドは省略可能な応答パラメーターです。 |
次に例を示します。
{ "ok" : 1 }
次のステップ
次は、以下の Azure Cosmos DB の概念について学習することができます。