Použití příkazů rozšíření MongoDB ke správě dat uložených ve službě Azure Cosmos DB pro MongoDB
PLATÍ PRO: MongoDB
Následující dokument obsahuje vlastní příkazy akcí, které jsou specifické pro Službu Azure Cosmos DB pro MongoDB. Tyto příkazy je možné použít k vytvoření a získání databázových prostředků specifických pro model kapacity Azure Cosmos DB.
Pomocí služby Azure Cosmos DB pro MongoDB můžete využívat sdílené výhody služby Azure Cosmos DB. Mezi tyto výhody patří mimo jiné:
- Globální distribuce
- Automatické horizontální dělení
- Vysoká dostupnost
- Záruky latence
- Šifrování neaktivních uložených dat
- Zálohování
Tyto výhody můžete využívat při zachování svých investic do stávajících aplikací MongoDB. Se službou Azure Cosmos DB pro MongoDB můžete komunikovat pomocí libovolného opensourcového klientského ovladače MongoDB. Azure Cosmos DB pro MongoDB umožňuje použití existujících klientských ovladačů dodržováním přenosového protokolu MongoDB.
Podpora protokolu MongoDB
Azure Cosmos DB pro MongoDB je kompatibilní se serverem MongoDB verze 4.0, 3.6 a 3.2. Další informace najdete v tématu podporované funkce a syntaxe ve verzích 4.0, 3.6 a 3.2.
Následující příkazy rozšíření vytvářejí a upravují prostředky specifické pro Azure Cosmos DB prostřednictvím databázových požadavků:
- Vytvoření databáze
- Aktualizace databáze
- Získání databáze
- Vytvořit kolekci
- Aktualizovat kolekci
- Získání kolekce
Vytvoření databáze
Příkaz create database extension vytvoří novou databázi MongoDB. Název databáze lze použít z kontextu databáze nastaveného příkazem use database
. Následující tabulka popisuje parametry v rámci příkazu:
Pole | Typ | Description |
---|---|---|
customAction |
string |
Název vlastního příkazu Hodnota musí být CreateDatabase . |
offerThroughput |
int |
Zřízená propustnost, kterou jste nastavili pro databázi. Tento parametr je volitelný. |
autoScaleSettings |
Object |
Vyžaduje se pro režim automatického škálování. Tento objekt obsahuje nastavení přidružená k režimu kapacity automatického škálování. Můžete nastavit maxThroughput hodnotu, která popisuje nejvyšší počet jednotek žádostí, na který může kolekce dynamicky navýšit. |
Výstup
Pokud je příkaz úspěšný, vrátí následující odpověď:
{ "ok" : 1 }
Parametry ve výstupu najdete ve výchozím výstupu vlastního příkazu.
Příklad: Vytvoření databáze
K vytvoření databáze s názvem "test"
, která používá všechny výchozí hodnoty, použijte následující příkaz:
use test
db.runCommand({customAction: "CreateDatabase"});
Tento příkaz vytvoří databázi bez propustnosti na úrovni databáze. Tato operace znamená, že kolekce v rámci této databáze musí určit požadovanou propustnost.
Příklad: Vytvoření databáze s propustností
Pokud chcete vytvořit databázi s názvem "test"
a určit zřízenou propustnost 1 000 RU na úrovni databáze , použijte následující příkaz:
use test
db.runCommand({customAction: "CreateDatabase", offerThroughput: 1000 });
Tento příkaz vytvoří databázi a nastaví pro ni propustnost. Všechny kolekce v této databázi sdílejí nastavenou propustnost, pokud nejsou vytvořené s konkrétní úrovní propustnosti.
Příklad: Vytvoření databáze s propustností automatického škálování
Pokud chcete vytvořit databázi s názvem "test"
a zadat maximální propustnost automatického škálování 20 000 RU/s na úrovni databáze, použijte následující příkaz:
use test
db.runCommand({customAction: "CreateDatabase", autoScaleSettings: { maxThroughput: 20000 } });
Aktualizace databáze
Příkaz update database extension aktualizuje vlastnosti přidružené k zadané databázi. Změna zřízené propustnosti databáze na automatické škálování a naopak se podporuje jenom v Azure Portal. Následující tabulka popisuje parametry v rámci příkazu:
Pole | Typ | Description |
---|---|---|
customAction |
string |
Název vlastního příkazu Hodnota musí být UpdateDatabase . |
offerThroughput |
int |
Nová zřízená propustnost, kterou chcete nastavit pro databázi, pokud databáze používá propustnost na úrovni databáze |
autoScaleSettings |
Object |
Vyžaduje se pro režim automatického škálování. Tento objekt obsahuje nastavení přidružená k režimu kapacity automatického škálování. Můžete nastavit maxThroughput hodnotu, která popisuje nejvyšší počet jednotek žádostí, na který je možné databázi dynamicky zvýšit. |
Tento příkaz používá databázi určenou v kontextu relace. Tato databáze je stejná jako ta, kterou jste použili v use <database>
příkazu . V tuto chvíli není možné pomocí tohoto příkazu změnit název databáze.
Výstup
Pokud je příkaz úspěšný, vrátí následující odpověď:
{ "ok" : 1 }
Parametry ve výstupu najdete ve výchozím výstupu vlastního příkazu.
Příklad: Aktualizace zřízené propustnosti přidružené k databázi
Pokud chcete aktualizovat zřízenou propustnost databáze s názvem "test"
na 1200 RU, použijte následující příkaz:
use test
db.runCommand({customAction: "UpdateDatabase", offerThroughput: 1200 });
Příklad: Aktualizace propustnosti automatického škálování přidružené k databázi
Pokud chcete aktualizovat zřízenou propustnost databáze s názvem "test"
na 20 000 RU nebo ji transformovat na úroveň propustnosti automatického škálování, použijte následující příkaz:
use test
db.runCommand({customAction: "UpdateDatabase", autoScaleSettings: { maxThroughput: 20000 } });
Získání databáze
Příkaz get database extension vrátí databázový objekt . Název databáze se používá z kontextu databáze, ve kterém je příkaz proveden.
{
customAction: "GetDatabase"
}
Následující tabulka popisuje parametry v rámci příkazu:
Pole | Typ | Description |
---|---|---|
customAction |
string |
Název vlastního příkazu Hodnota musí být GetDatabase . |
Výstup
Pokud je příkaz úspěšný, odpověď obsahuje dokument s následujícími poli:
Pole | Typ | Description |
---|---|---|
ok |
int |
Stav odpovědi. 1 == úspěch. 0 == selhání. |
database |
string |
Název databáze. |
provisionedThroughput |
int |
Zřízená propustnost nastavená pro databázi, pokud databáze používá propustnost na úrovni databáze ručně |
autoScaleSettings |
Object |
Tento objekt obsahuje parametry kapacity přidružené k databázi, pokud používá režim automatického škálování. Hodnota maxThroughput popisuje nejvyšší počet jednotek žádostí, na který je možné databázi dynamicky zvýšit. |
Pokud příkaz selže, vrátí se výchozí odpověď na vlastní příkaz. Parametry ve výstupu najdete ve výchozím výstupu vlastního příkazu.
Příklad: Získání databáze
Pokud chcete získat databázový objekt pro databázi s názvem "test"
, použijte následující příkaz:
use test
db.runCommand({customAction: "GetDatabase"});
Pokud databáze nemá přidruženou propustnost, výstup bude následující:
{ "database" : "test", "ok" : 1 }
Pokud je k databázi přidružená ruční propustnost na úrovni databáze , ve výstupu provisionedThroughput
se zobrazí hodnoty:
{ "database" : "test", "provisionedThroughput" : 20000, "ok" : 1 }
Pokud je k databázi přidružená propustnost automatického škálování na úrovni databáze , zobrazí se provisionedThroughput
ve výstupu hodnota , která popisuje minimální POČET RU/s pro databázi, a autoScaleSettings
objekt včetně objektu maxThroughput
, který popisuje maximální počet RU/s pro databázi.
{
"database" : "test",
"provisionedThroughput" : 2000,
"autoScaleSettings" : {
"maxThroughput" : 20000
},
"ok" : 1
}
Vytvořit kolekci
Příkaz create collection extension vytvoří novou kolekci MongoDB. Název databáze se použije z kontextu databáze nastaveného příkazem use database
. Formát příkazu CreateCollection je následující:
{
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).
}
Následující tabulka popisuje parametry v rámci příkazu:
Pole | Typ | Vyžadováno | Popis |
---|---|---|---|
customAction |
string |
Povinné | Název vlastního příkazu Hodnota musí být CreateCollection . |
collection |
string |
Vyžadováno | Název kolekce. Nejsou povoleny žádné speciální znaky ani mezery. |
offerThroughput |
int |
Volitelné | Zřízená propustnost nastavená pro databázi. Pokud tento parametr není zadaný, nastaví se výchozí hodnota na minimální hodnotu 400 RU/s. * Pokud chcete zadat propustnost nad 10 000 RU/s, shardKey je parametr povinný. |
shardKey |
string |
Požadováno pro kolekce s velkou propustností | Cesta ke klíči horizontálního oddílu pro dělenou kolekci. Tento parametr je povinný, pokud v offerThroughput nástroji nastavíte více než 10 000 RU/s. Pokud je zadaný, všechny vložené dokumenty vyžadují tento klíč a hodnotu. |
autoScaleSettings |
Object |
Požadováno pro režim automatického škálování | Tento objekt obsahuje nastavení přidružená k režimu kapacity automatického škálování. Můžete nastavit maxThroughput hodnotu, která popisuje nejvyšší počet jednotek žádostí, které lze kolekci dynamicky zvýšit. |
indexes |
Array |
Volitelně můžete nakonfigurovat indexy. Tento parametr je podporován pouze pro účty verze 3.6 nebo novější. | Pokud je k dispozici, vyžaduje se index na _id. Každá položka v poli musí obsahovat klíč jednoho nebo více polí, název a může obsahovat možnosti indexu. Chcete-li například vytvořit složený jedinečný index polí a a b použít tuto položku: {key: {a: 1, b: 1}, name:"a_1_b_1", unique: true} . |
Výstup
Vrátí výchozí vlastní odpověď na příkaz. Parametry ve výstupu najdete ve výchozím výstupu vlastního příkazu.
Příklad: Vytvoření kolekce s minimální konfigurací
Pokud chcete vytvořit novou kolekci s názvem "testCollection"
a výchozími hodnotami, použijte následující příkaz:
use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection"});
Výsledkem této operace je nová pevná, nehardovaná kolekce s 400 RU/s a indexem v _id
poli automaticky. Tento typ konfigurace platí také při vytváření nových kolekcí prostřednictvím insert()
funkce. Příklad:
use test
db.newCollection.insert({});
Příklad: Vytvoření nehardované kolekce
Pokud chcete vytvořit nehardovanou kolekci s názvem "testCollection"
a zřízenou propustností 1 000 RU, použijte následující příkaz:
use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection", offerThroughput: 1000});
Můžete vytvořit kolekci s až 10 000 RU/s, offerThroughput
aniž byste museli zadávat klíč horizontálního oddílu. Informace o kolekcích s větší propustností najdete v další části.
Příklad: Vytvoření dělené kolekce
Pokud chcete vytvořit dělenou kolekci s názvem "testCollection"
a zřízenou propustností 11 000 RU a shardkey
vlastností a.b, použijte následující příkaz:
use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection", offerThroughput: 11000, shardKey: "a.b" });
Tento příkaz teď vyžaduje shardKey
parametr, protože více než 10 000 RU/s zadané v offerThroughput
.
Příklad: Vytvoření nehardované kolekce automatického škálování
Pokud chcete vytvořit nehardovanou kolekci s názvem 'testCollection'
, která používá kapacitu propustnosti automatického škálování nastavenou na 4 000 RU/s, použijte následující příkaz:
use test
db.runCommand({
customAction: "CreateCollection", collection: "testCollection",
autoScaleSettings:{
maxThroughput: 4000
}
});
autoScaleSettings.maxThroughput
Jako hodnotu můžete zadat rozsah od 4 000 RU/s do 10 000 RU/s bez klíče horizontálního oddílu. Pro vyšší propustnost automatického škálování musíte zadat shardKey
parametr .
Příklad: Vytvoření kolekce s horizontálním automatickým škálováním
Pokud chcete vytvořit dělenou kolekci s názvem 'testCollection'
s klíčem horizontálního oddílu s názvem 'a.b'
a která používá kapacitu propustnosti automatického škálování nastavenou na 20 000 RU/s, použijte následující příkaz:
use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection", shardKey: "a.b", autoScaleSettings: { maxThroughput: 20000 }});
Aktualizovat kolekci
Příkaz update collection extension aktualizuje vlastnosti přidružené k zadané kolekci. Změna zřízené propustnosti kolekce na automatické škálování a naopak se podporuje jenom v 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).
}
Následující tabulka popisuje parametry v rámci příkazu:
Pole | Typ | Description |
---|---|---|
customAction |
string |
Název vlastního příkazu Hodnota musí být UpdateCollection . |
collection |
string |
Název kolekce. |
offerThroughput |
int |
Zřízená propustnost nastavená pro kolekci. |
autoScaleSettings |
Object |
Vyžaduje se pro režim automatického škálování. Tento objekt obsahuje nastavení přidružená k režimu kapacity automatického škálování. Hodnota maxThroughput popisuje nejvyšší počet jednotek žádostí, které je možné dynamicky zvýšit. |
indexes |
Array |
Volitelně můžete nakonfigurovat indexy. Tento parametr je podporován pouze pro účty verze 3.6 nebo novější. Pokud je k dispozici, zadaná sada indexů (včetně indexů zahazování) nahradí existující indexy kolekce. Vyžaduje se index na _id. Každá položka v poli musí obsahovat klíč jednoho nebo více polí, název a může obsahovat možnosti indexu. Pokud například chcete vytvořit složený jedinečný index pro pole a a b, použijte tuto položku: {key: {a: 1, b: 1}, name: "a_1_b_1", unique: true} . |
Výstup
Vrátí výchozí vlastní odpověď na příkaz. Parametry ve výstupu najdete ve výchozím výstupu vlastního příkazu.
Příklad: Aktualizace zřízené propustnosti přidružené ke kolekci
Pokud chcete aktualizovat zřízenou propustnost kolekce s názvem "testCollection"
na 1200 RU, použijte následující příkaz:
use test
db.runCommand({customAction: "UpdateCollection", collection: "testCollection", offerThroughput: 1200 });
Získat kolekci
Příkaz získat vlastní kolekci vrátí objekt kolekce.
{
customAction: "GetCollection",
collection: "<Name of the collection>"
}
Následující tabulka popisuje parametry v rámci příkazu:
Pole | Typ | Description |
---|---|---|
customAction |
string |
Název vlastního příkazu Hodnota musí být GetCollection . |
collection |
string |
Název kolekce. |
Výstup
Pokud je příkaz úspěšný, odpověď obsahuje dokument s následujícími poli.
Pole | Typ | Description |
---|---|---|
ok |
int |
Stav odpovědi. 1 == úspěch. 0 == selhání. |
database |
string |
Název databáze. |
collection |
string |
Název kolekce. |
shardKeyDefinition |
document |
Dokument specifikace indexu použitý jako klíč horizontálního dělení. Toto pole je volitelný parametr odpovědi. |
provisionedThroughput |
int |
Zřízená propustnost nastavená pro kolekci. Toto pole je volitelný parametr odpovědi. |
autoScaleSettings |
Object |
Tento objekt obsahuje parametry kapacity přidružené k databázi, pokud používá režim automatického škálování. Hodnota maxThroughput popisuje nejvyšší počet jednotek žádostí, které je možné dynamicky zvýšit kolekci. |
Pokud příkaz selže, vrátí se výchozí odpověď na vlastní příkaz. Parametry ve výstupu najdete ve výchozím výstupu vlastního příkazu.
Příklad: Získání kolekce
K získání objektu kolekce pro kolekci s názvem "testCollection"
použijte následující příkaz:
use test
db.runCommand({customAction: "GetCollection", collection: "testCollection"});
Pokud má kolekce přidruženou kapacitu propustnosti, zahrnuje provisionedThroughput
hodnotu a výstup bude:
{
"database" : "test",
"collection" : "testCollection",
"provisionedThroughput" : 400,
"ok" : 1
}
Pokud má kolekce přidruženou propustnost automatického škálování, zahrnuje autoScaleSettings
objekt s parametrem maxThroughput
, který definuje maximální propustnost, kterou kolekce dynamicky zvyšuje. Kromě toho obsahuje provisionedThroughput
také hodnotu , která definuje minimální propustnost, na kterou tato kolekce sníží, pokud v kolekci nejsou žádné požadavky:
{
"database" : "test",
"collection" : "testCollection",
"provisionedThroughput" : 1000,
"autoScaleSettings" : {
"maxThroughput" : 10000
},
"ok" : 1
}
Pokud kolekce sdílí propustnost na úrovni databáze, a to buď v režimu automatického škálování, nebo ručně, výstup bude následující:
{ "database" : "test", "collection" : "testCollection", "ok" : 1 }
{
"database" : "test",
"provisionedThroughput" : 2000,
"autoScaleSettings" : {
"maxThroughput" : 20000
},
"ok" : 1
}
Paralelizace datových proudů změn
Při použití datových proudů změn ve velkém měřítku je nejlepší rovnoměrně rozložit zatížení. Následující příkaz vrátí jeden nebo více tokenů obnovení toku změn – každý z nich odpovídá datům z jednoho fyzického horizontálního oddílu nebo oddílu (v jednom fyzickém oddílu může existovat více logických horizontálních oddílů nebo oddílů). Každý token obnovení způsobí, že watch() vrátí pouze data z daného fyzického horizontálního oddílu nebo oddílu.
K efektivnímu škálování datových proudů změn použijte db.collection.watch()
v každém obnovovacím tokenu (jedno vlákno na token).
{
customAction: "GetChangeStreamTokens",
collection: "<Name of the collection>",
startAtOperationTime: "<BSON Timestamp>" // Optional. Defaults to the time the command is run.
}
Příklad: Získání tokenu streamu
Spuštěním vlastního příkazu získejte token obnovení pro každý fyzický horizontální oddíl nebo oddíl.
use test
db.runCommand({customAction: "GetChangeStreamTokens", collection: "<Name of the collection>"})
Spusťte vlákno nebo proces watch() pro každý token obnovení vrácený z vlastního příkazu GetChangeStreamTokens. Tady je příklad pro jedno vlákno.
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)}})
Dokument (hodnota) v poli resumeAfter představuje token obnovení. Příkaz watch()
vrátí pro všechny dokumenty, které byly vloženy, aktualizovány nebo nahrazeny z fyzického oddílu od spuštění vlastního příkazu GetChangeStreamTokens. Zde je uvedena ukázka vrácených dat.
{
"_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")
}
}
Každý vrácený dokument obsahuje token životopisu (pro každou stránku jsou všechny stejné). Tento obnovovací token by se měl uložit a znovu použít, pokud vlákno nebo proces zemře. Tento obnovovací token navazuje na místo, kde jste skončili, a přijímá data jenom z tohoto fyzického oddílu.
Výchozí výstup vlastního příkazu
Pokud není zadán, vlastní odpověď obsahuje dokument s následujícími poli:
Pole | Typ | Description |
---|---|---|
ok |
int |
Stav odpovědi. 1 == úspěch. 0 == selhání. |
code |
int |
Vráceno pouze v případě, že příkaz selhal (to znamená, že ok == 0). Obsahuje kód chyby MongoDB. Toto pole je volitelný parametr odpovědi. |
errMsg |
string |
Vráceno pouze v případě, že příkaz selhal (to znamená, že ok == 0). Obsahuje uživatelsky přívětivou chybovou zprávu. Toto pole je volitelný parametr odpovědi. |
Příklad:
{ "ok" : 1 }
Další kroky
Dále se můžete seznámit s následujícími koncepty služby Azure Cosmos DB: