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

Článek
05/23/2023

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 provisionedThroughputve 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:

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

Podpora protokolu MongoDB

Vytvoření databáze

Výstup

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

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

Příklad: Vytvoření databáze s propustností automatického škálování

Aktualizace databáze

Výstup

Příklad: Aktualizace zřízené propustnosti přidružené k databázi

Příklad: Aktualizace propustnosti automatického škálování přidružené k databázi

Získání databáze

Výstup

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

Vytvořit kolekci

Výstup

Příklad: Vytvoření kolekce s minimální konfigurací

Příklad: Vytvoření nehardované kolekce

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

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

Příklad: Vytvoření kolekce s horizontálním automatickým škálováním

Aktualizovat kolekci

Výstup

Příklad: Aktualizace zřízené propustnosti přidružené ke kolekci

Získat kolekci

Výstup

Příklad: Získání kolekce

Paralelizace datových proudů změn

Příklad: Získání tokenu streamu

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

Další kroky

Další materiály