Sdílet prostřednictvím

Použití příkazů rozšíření MongoDB ke správě dat uložených ve službě Azure Cosmos DB pro MongoDB

  • Článek

PLATÍ PRO: MongoDB

Následující dokument obsahuje vlastní příkazy akcí specifické pro Azure Cosmos DB pro MongoDB. Tyto příkazy lze použít k vytvoření a získání databázových prostředků, které jsou specifické pro model kapacity služby 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ří:

  • 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 si můžete vychutnat při zachování investic do stávající aplikace MongoDB. Ke komunikaci se službou Azure Cosmos DB for MongoDB můžete použít kterýkoli z opensourcových klientských ovladačů MongoDB. Azure Cosmos DB for MongoDB umožňuje používat existující klientské ovladače tím, že dodržuje protokol přenosu 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 podporovaných funkcích a syntaxi 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 službu Azure Cosmos DB prostřednictvím databázových požadavků:

Vytvoření databáze

Příkaz pro vytvoření rozšíření databáze 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 Popis
customAction string Název vlastního příkazu Hodnota musí být CreateDatabase.
offerThroughput int Zřízená propustnost, kterou jste nastavili v 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í, které může kolekce dynamicky navýšit.

Výstup

Pokud je příkaz úspěšný, vrátí následující odpověď:

{ "ok" : 1 }

Prohlédněte si výchozí výstup vlastního příkazu pro parametry ve výstupu.

Příklad: Vytvoření databáze

Pokud chcete vytvořit databázi 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 této databázi musí určovat propustnost, kterou potřebujete použít.

Příklad: Vytvoření databáze s propustností

Pokud chcete vytvořit databázi s názvem "test" a zadat zřízenou propustnost na úrovni databáze 1 000 RU, 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 kolekce vytvořeny 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 aktualizace rozšíření databáze aktualizuje vlastnosti přidružené k zadané databázi. Změna databáze ze zřízené propustnosti na automatické škálování a naopak se podporuje jenom na webu Azure Portal. Následující tabulka popisuje parametry v rámci příkazu:

Pole Typ Popis
customAction string Název vlastního příkazu Hodnota musí být UpdateDatabase.
offerThroughput int Nová zřízená propustnost, kterou chcete nastavit v 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í, které je možné v databázi dynamicky navýšit.

Tento příkaz používá databázi zadanou v kontextu relace. Tato databáze je stejná jako v use <database> příkazu. V tuto chvíli se název databáze nedá změnit pomocí tohoto příkazu.

Výstup

Pokud je příkaz úspěšný, vrátí následující odpověď:

{ "ok" : 1 }

Prohlédněte si výchozí výstup vlastního příkazu pro parametry ve výstupu.

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 se příkaz spustí.

{
  customAction: "GetDatabase"
}

Následující tabulka popisuje parametry v rámci příkazu:

Pole Typ Popis
customAction string Název vlastního příkazu Hodnota musí být GetDatabase.

Výstup

Pokud příkaz proběhne úspěšně, odpověď obsahuje dokument s následujícími poli:

Pole Typ Popis
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á ruční propustnost na úrovni databáze
autoScaleSettings Object Tento objekt obsahuje parametry kapacity přidružené k databázi, pokud používá režim automatického škálování. Tato maxThroughput hodnota popisuje nejvyšší počet jednotek žádostí, na které je možné databázi dynamicky navýšit.

Pokud příkaz selže, vrátí se výchozí odpověď vlastního příkazu. Prohlédněte si výchozí výstup vlastního příkazu pro parametry ve výstupu.

Příklad: Získání databáze

K získání databázového objektu 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, bude výstup vypadat takto:

{ "database" : "test", "ok" : 1 }

Pokud má databáze přidruženou ruční propustnost na úrovni databáze, výstup zobrazí provisionedThroughput hodnoty:

{ "database" : "test", "provisionedThroughput" : 20000, "ok" : 1 }

Pokud má databáze přidruženou propustnost automatického škálování na úrovni databáze, výstup by zobrazil provisionedThroughputminimální počet RU/s databáze 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ření kolekce

Příkaz create collection extension vytvoří novou kolekci MongoDB. Název databáze se používá 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 Požadováno Popis
customAction string Povinní účastníci Název vlastního příkazu Hodnota musí být CreateCollection.
collection string Požaduje se Název kolekce. Nejsou povoleny žádné speciální znaky ani mezery.
offerThroughput int Volitelné Zřízená propustnost, která se nastaví v databázi. Pokud tento parametr není zadaný, výchozí hodnota je 400 RU/s. * Pokud chcete zadat propustnost nad 10 000 RU/s, shardKey je parametr povinný.
shardKey string Vyžadováno pro kolekce s velkou propustností Cesta k klíči horizontálního oddílu pro horizontálně dělenou kolekci. Tento parametr je povinný, pokud nastavíte více než 10 000 RU/s v offerThroughput. 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é je možné v 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 _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ěď příkazu. Prohlédněte si výchozí výstup vlastního příkazu pro parametry ve výstupu.

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á, neshardovaná kolekce se 400 RU/s a indexem v poli, které se _id automaticky vytvoří. 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 nesehardovanou 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});

Kolekci můžete vytvořit až s 10 000 RU/s, offerThroughput aniž byste museli zadat klíč horizontálního dělení. V případě kolekcí s větší propustností si projděte další část.

Příklad: Vytvoření horizontálně dělené kolekce

Pokud chcete vytvořit horizontálně 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ých v sadě offerThroughput.

Příklad: Vytvoření neshardované kolekce automatického škálování

Pokud chcete vytvořit neshardovanou 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 Pro hodnotu můžete zadat rozsah od 4 000 RU/s do 10 000 RU/s bez klíče horizontálního dělení. Pro vyšší propustnost automatického škálování je potřeba zadat shardKey parametr.

Příklad: Vytvoření horizontálně dělené kolekce automatického škálování

Pokud chcete vytvořit horizontálně dělenou kolekci s názvem 'testCollection' 'a.b'klíče horizontálního dělení 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 }});

Aktualizace kolekce

Příkaz rozšíření aktualizace kolekce aktualizuje vlastnosti přidružené k zadané kolekci. Změna kolekce ze zřízené propustnosti na automatické škálování a naopak se podporuje jenom na webu 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 Popis
customAction string Název vlastního příkazu Hodnota musí být UpdateCollection.
collection string Název kolekce.
offerThroughput int Zřízená propustnost pro nastavení v 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í. Tato maxThroughput hodnota popisuje nejvyšší počet jednotek žádostí, které je možné dynamicky zvýšit na kolekci.
indexes Array Volitelně můžete nakonfigurovat indexy. Tento parametr je podporován pouze pro účty verze 3.6 nebo novější. V případě přítomnosti nahradí zadaná sada indexů (včetně vyřazení indexů) existující indexy kolekce. Je vyžadován index _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ěď příkazu. Prohlédněte si výchozí výstup vlastního příkazu pro parametry ve výstupu.

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ískání kolekce

Vlastní příkaz get collection vrátí objekt kolekce.

{
  customAction: "GetCollection",
  collection: "<Name of the collection>"
}

Následující tabulka popisuje parametry v rámci příkazu:

Pole Typ Popis
customAction string Název vlastního příkazu Hodnota musí být GetCollection.
collection string Název kolekce.

Výstup

Pokud příkaz proběhne úspěšně, odpověď obsahuje dokument s následujícími poli.

Pole Typ Popis
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žívaný jako klíč horizontálního dělení Toto pole je volitelný parametr odpovědi.
provisionedThroughput int Zřízená propustnost pro nastavení v 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í. Tato maxThroughput hodnota popisuje nejvyšší počet jednotek žádostí, které je možné dynamicky zvýšit na kolekci.

Pokud příkaz selže, vrátí se výchozí odpověď vlastního příkazu. Prohlédněte si výchozí výstup vlastního příkazu pro parametry ve výstupu.

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 by byl:

{
        "database" : "test",
        "collection" : "testCollection",
        "provisionedThroughput" : 400,
        "ok" : 1
}

Pokud má kolekce přidruženou propustnost automatického škálování, zahrnuje autoScaleSettings objekt s maxThroughput parametrem, který definuje maximální propustnost, kterou kolekce dynamicky zvyšuje. Kromě toho obsahuje provisionedThroughput také hodnotu, která definuje minimální propustnost, na kterou se 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, buď v režimu automatického škálování, nebo ručně, bude výstup vypadat takto:

{ "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í streamů 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í streamu změn – každý z nich odpovídá datům z jednoho fyzického horizontálního oddílu nebo oddílu (na 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.

Pomocí db.collection.watch() každého obnovovacího tokenu (jedno vlákno na token) můžete efektivně škálovat datové proudy změn.

{
        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 životopisu 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 životopisu 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í prokletí pro všechny dokumenty, které byly vloženy, aktualizovány nebo nahrazeny z daného fyzického oddílu od spuštění vlastního příkazu GetChangeStreamTokens. Tady 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 (všechny jsou pro každou stránku stejné). Pokud vlákno nebo proces zemře, měl by se tento token obnovení uložit a znovu použít. Tento token životopisu převezme místo, kde jste skončili, a přijímá data pouze z tohoto fyzického oddílu.

Výchozí výstup vlastního příkazu

Pokud není zadáno, vlastní odpověď obsahuje dokument s následujícími poli:

Pole Typ Popis
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á 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á 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: