Udostępnij za pośrednictwem

Zarządzanie danymi przechowywanymi w usłudze Azure Cosmos DB dla bazy danych MongoDB za pomocą poleceń rozszerzenia MongoDB

  • Artykuł

DOTYCZY: MongoDB

Poniższy dokument zawiera polecenia akcji niestandardowej specyficzne dla usługi Azure Cosmos DB dla bazy danych MongoDB. Te polecenia mogą służyć do tworzenia i uzyskiwania zasobów bazy danych specyficznych dla modelu pojemności usługi Azure Cosmos DB.

Korzystając z usługi Azure Cosmos DB dla bazy danych MongoDB, możesz korzystać ze wspólnych korzyści z usługi Azure Cosmos DB. Obejmują one następujące korzyści, ale nie są ograniczone do następujących:

  • Globalne rozproszenie
  • Automatyczne fragmentowanie
  • Wysoka dostępność
  • Gwarancje dot. opóźnienia
  • Szyfrowanie w spoczynku
  • Kopie zapasowe

Możesz korzystać z tych korzyści, zachowując inwestycje w istniejącą aplikację MongoDB[s]. Możesz komunikować się z usługą Azure Cosmos DB dla bazy danych MongoDB przy użyciu dowolnego sterownika klienta bazy danych MongoDB typu open source. Usługa Azure Cosmos DB dla bazy danych MongoDB umożliwia korzystanie z istniejących sterowników klienta przez przestrzeganie protokołu przewodowego bazy danych MongoDB.

Obsługa protokołu MongoDB

Usługa Azure Cosmos DB dla bazy danych MongoDB jest zgodna z serwerem MongoDB w wersji 4.0, 3.6 i 3.2. Aby uzyskać więcej informacji, zobacz obsługiwane funkcje i składnia w wersjach 4.0, 3.6 i 3.2.

Następujące polecenia rozszerzenia tworzą i modyfikują zasoby specyficzne dla usługi Azure Cosmos DB za pośrednictwem żądań bazy danych:

Tworzenie bazy danych

Polecenie create database extension tworzy nową bazę danych MongoDB. Nazwa bazy danych może być używana z kontekstu bazy danych ustawionego use database przez polecenie . W poniższej tabeli opisano parametry w poleceniu :

Pole Typ Opis
customAction string Nazwa polecenia niestandardowego. Wartość musi mieć wartość CreateDatabase.
offerThroughput int Aprowizowana przepływność ustawiona w bazie danych. Ten parametr jest opcjonalny.
autoScaleSettings Object Wymagane w trybie autoskalowania. Ten obiekt zawiera ustawienia skojarzone z trybem pojemności autoskalowania. Możesz skonfigurować maxThroughput wartość, która opisuje największą liczbę jednostek żądań, które kolekcja może zwiększyć dynamicznie.

Wyjście

Jeśli polecenie zakończy się pomyślnie, zwraca następującą odpowiedź:

{ "ok" : 1 }

Zobacz domyślne dane wyjściowe polecenia niestandardowego dla parametrów w danych wyjściowych.

Przykład: tworzenie bazy danych

Aby utworzyć bazę danych o nazwie "test" , która używa wszystkich wartości domyślnych, użyj następującego polecenia:

use test
db.runCommand({customAction: "CreateDatabase"});

To polecenie tworzy bazę danych bez przepływności na poziomie bazy danych. Ta operacja oznacza, że kolekcje w tej bazie danych muszą określać ilość przepływności, której należy użyć.

Przykład: tworzenie bazy danych z przepływnością

Aby utworzyć bazę danych o nazwie "test" i określić aprowizowaną przepływność na poziomie bazy danych 1000 jednostek RU, użyj następującego polecenia:

use test
db.runCommand({customAction: "CreateDatabase", offerThroughput: 1000 });

To polecenie tworzy bazę danych i ustawia jej przepływność. Wszystkie kolekcje w tej bazie danych współużytkują ustawioną przepływność, chyba że kolekcje zostaną utworzone z określonym poziomem przepływności.

Przykład: tworzenie bazy danych z przepływnością autoskalowania

Aby utworzyć bazę danych o nazwie "test" i określić maksymalną przepływność autoskalowania równą 20 000 RU/s na poziomie bazy danych, użyj następującego polecenia:

use test
db.runCommand({customAction: "CreateDatabase", autoScaleSettings: { maxThroughput: 20000 } });

Aktualizowanie bazy danych

Polecenie rozszerzenia bazy danych aktualizacji aktualizuje właściwości skojarzone z określoną bazą danych. Zmiana bazy danych z aprowizowanej przepływności na autoskalowanie i odwrotnie jest obsługiwana tylko w witrynie Azure Portal. W poniższej tabeli opisano parametry w poleceniu :

Pole Typ Opis
customAction string Nazwa polecenia niestandardowego. Wartość musi mieć wartość UpdateDatabase.
offerThroughput int Nowa aprowizowana przepływność, którą chcesz ustawić w bazie danych, jeśli baza danych używa przepływności na poziomie bazy danych
autoScaleSettings Object Wymagane w trybie autoskalowania. Ten obiekt zawiera ustawienia skojarzone z trybem pojemności autoskalowania. Można skonfigurować maxThroughput wartość, która opisuje największą liczbę jednostek żądań, które można zwiększyć w celu dynamicznego zwiększenia bazy danych.

To polecenie używa bazy danych określonej w kontekście sesji. Ta baza danych jest taka sama, która była używana w poleceniu use <database> . W tej chwili nie można zmienić nazwy bazy danych przy użyciu tego polecenia.

Wyjście

Jeśli polecenie zakończy się pomyślnie, zwraca następującą odpowiedź:

{ "ok" : 1 }

Zobacz domyślne dane wyjściowe polecenia niestandardowego dla parametrów w danych wyjściowych.

Przykład: aktualizowanie aprowizowanej przepływności skojarzonej z bazą danych

Aby zaktualizować aprowizowaną przepływność bazy danych o nazwie "test" do 1200 jednostek RU, użyj następującego polecenia:

use test
db.runCommand({customAction: "UpdateDatabase", offerThroughput: 1200 });

Przykład: aktualizowanie przepływności autoskalowania skojarzonej z bazą danych

Aby zaktualizować aprowizowaną przepływność bazy danych o nazwie "test" do 20 000 jednostek RU lub przekształcić ją w poziom przepływności autoskalowania, użyj następującego polecenia:

use test
db.runCommand({customAction: "UpdateDatabase", autoScaleSettings: { maxThroughput: 20000 } });

Pobieranie bazy danych

Polecenie get database extension zwraca obiekt bazy danych. Nazwa bazy danych jest używana z kontekstu bazy danych, względem którego jest wykonywane polecenie.

{
  customAction: "GetDatabase"
}

W poniższej tabeli opisano parametry w poleceniu :

Pole Typ Opis
customAction string Nazwa polecenia niestandardowego. Wartość musi mieć wartość GetDatabase.

Wyjście

Jeśli polecenie powiedzie się, odpowiedź zawiera dokument z następującymi polami:

Pole Typ Opis
ok int Stan odpowiedzi. 1 == sukces. 0 == awaria.
database string Nazwa bazy danych.
provisionedThroughput int Aprowizowana przepływność ustawiona w bazie danych, jeśli baza danych używa ręcznej przepływności na poziomie bazy danych
autoScaleSettings Object Ten obiekt zawiera parametry pojemności skojarzone z bazą danych, jeśli używa trybu autoskalowania. Wartość maxThroughput opisuje największą liczbę jednostek żądań, które można zwiększyć do dynamicznej bazy danych.

Jeśli polecenie zakończy się niepowodzeniem, zostanie zwrócona domyślna niestandardowa odpowiedź polecenia. Zobacz domyślne dane wyjściowe polecenia niestandardowego dla parametrów w danych wyjściowych.

Przykład: pobieranie bazy danych

Aby uzyskać obiekt bazy danych dla bazy danych o nazwie "test", użyj następującego polecenia:

use test
db.runCommand({customAction: "GetDatabase"});

Jeśli baza danych nie ma skojarzonej przepływności, dane wyjściowe będą następujące:

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

Jeśli baza danych ma skojarzona ręczną przepływność na poziomie bazy danych, dane wyjściowe będą pokazywać provisionedThroughput wartości:

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

Jeśli baza danych ma skojarzona przepływność autoskalowania na poziomie bazy danych, w danych wyjściowych zostanie wyświetlona provisionedThroughputwartość , która opisuje minimalną liczbę JEDNOSTEK RU/s dla bazy danych oraz autoScaleSettings obiekt maxThroughputzawierający wartość , która opisuje maksymalną wartość RU/s dla bazy danych.

{
        "database" : "test",
        "provisionedThroughput" : 2000,
        "autoScaleSettings" : {
                "maxThroughput" : 20000
        },
        "ok" : 1
}

Tworzenie kolekcji

Polecenie create collection extension tworzy nową kolekcję MongoDB. Nazwa bazy danych jest używana z kontekstu baz danych ustawionego use database przez polecenie . Format polecenia CreateCollection jest następujący:

{
  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).
}

W poniższej tabeli opisano parametry w poleceniu :

Pole Typ Wymagania opis
customAction string Wymagania Nazwa polecenia niestandardowego. Wartość musi mieć wartość CreateCollection.
collection string Wymagania Nazwa kolekcji. Znaki specjalne ani spacje nie są dozwolone.
offerThroughput int Opcjonalnie Aprowizowana przepływność ustawiona w bazie danych. Jeśli ten parametr nie zostanie podany, wartość domyślna to minimum 400 RU/s. * Aby określić przepływność przekraczającą 10 000 RU/s, shardKey parametr jest wymagany.
shardKey string Wymagane w przypadku kolekcji z dużą przepływnością Ścieżka do klucza fragmentu dla kolekcji podzielonej na fragmenty. Ten parametr jest wymagany w przypadku ustawienia więcej niż 10 000 RU/s w elemecie offerThroughput. Jeśli zostanie określony, wszystkie wstawione dokumenty wymagają tego klucza i wartości.
autoScaleSettings Object Wymagane w trybie autoskalowania Ten obiekt zawiera ustawienia skojarzone z trybem pojemności autoskalowania. Można skonfigurować maxThroughput wartość, która opisuje największą liczbę jednostek żądania, które można dynamicznie zwiększyć do kolekcji.
indexes Array Opcjonalnie skonfiguruj indeksy. Ten parametr jest obsługiwany tylko dla kont w wersji 3.6 lub nowszej. Jeśli jest obecny, wymagany jest indeks _id. Każdy wpis w tablicy musi zawierać klucz co najmniej jednego pola, nazwę i może zawierać opcje indeksu. Aby na przykład utworzyć złożony unikatowy indeks w polach a i b użyć tego wpisu: {key: {a: 1, b: 1}, name:"a_1_b_1", unique: true}.

Wyjście

Zwraca domyślną niestandardową odpowiedź polecenia. Zobacz domyślne dane wyjściowe polecenia niestandardowego dla parametrów w danych wyjściowych.

Przykład: tworzenie kolekcji z minimalną konfiguracją

Aby utworzyć nową kolekcję o nazwie "testCollection" i wartościach domyślnych, użyj następującego polecenia:

use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection"});

Ta operacja powoduje utworzenie nowej stałej, nieuhardowanej kolekcji z wartością 400RU/s i indeksem w _id polu utworzonym automatycznie. Ten typ konfiguracji ma zastosowanie również podczas tworzenia nowych kolekcji za pośrednictwem insert() funkcji. Na przykład:

use test
db.newCollection.insert({});

Przykład: tworzenie kolekcji bez fragmentowania

Aby utworzyć nieuhardowaną kolekcję o nazwie "testCollection" i aprowizowanej przepływności 1000 jednostek RU, użyj następującego polecenia:

use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection", offerThroughput: 1000});

Możesz utworzyć kolekcję z maksymalnie 10 000 RU/s jako offerThroughput bez konieczności określania klucza fragmentu. W przypadku kolekcji o większej przepływności zapoznaj się z następną sekcją.

Przykład: tworzenie kolekcji podzielonej na fragmenty

Aby utworzyć kolekcję fragmentowaną o nazwie "testCollection" i aprowizowanej przepływności 11 000 jednostek RU i shardkey właściwości "a.b", użyj następującego polecenia:

use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection", offerThroughput: 11000, shardKey: "a.b" });

To polecenie wymaga teraz parametrushardKey, ponieważ więcej niż 10 000 RU/s określonych w .offerThroughput

Przykład: tworzenie kolekcji autoskalowania bez fragmentowania

Aby utworzyć nieuhardowaną kolekcję o nazwie 'testCollection' , która używa pojemności przepływności autoskalowania ustawionej na 4000 RU/s, użyj następującego polecenia:

use test
db.runCommand({ 
    customAction: "CreateCollection", collection: "testCollection", 
    autoScaleSettings:{
      maxThroughput: 4000
    } 
});

autoScaleSettings.maxThroughput Dla wartości można określić zakres od 4000 RU/s do 10 000 RU/s bez klucza fragmentu. Aby uzyskać wyższą przepływność autoskalowania, należy określić shardKey parametr .

Przykład: tworzenie kolekcji autoskalowania podzielonego na fragmenty

Aby utworzyć kolekcję fragmentowaną o nazwie z kluczem fragmentu o 'testCollection' nazwie 'a.b', i która używa pojemności przepływności autoskalowania ustawionej na 20 000 RU/s, użyj następującego polecenia:

use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection", shardKey: "a.b", autoScaleSettings: { maxThroughput: 20000 }});

Aktualizowanie kolekcji

Polecenie rozszerzenia kolekcji aktualizacji aktualizuje właściwości skojarzone z określoną kolekcją. Zmiana kolekcji z aprowizowanej przepływności na autoskalowanie i odwrotnie jest obsługiwana tylko w witrynie 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).
}

W poniższej tabeli opisano parametry w poleceniu :

Pole Typ Opis
customAction string Nazwa polecenia niestandardowego. Wartość musi mieć wartość UpdateCollection.
collection string Nazwa kolekcji.
offerThroughput int Aprowizowana przepływność ustawiona w kolekcji.
autoScaleSettings Object Wymagane w trybie autoskalowania. Ten obiekt zawiera ustawienia skojarzone z trybem pojemności autoskalowania. Wartość maxThroughput opisuje największą liczbę jednostek żądań, które można zwiększyć w celu dynamicznego zwiększania kolekcji.
indexes Array Opcjonalnie skonfiguruj indeksy. Ten parametr jest obsługiwany tylko dla kont w wersji 3.6 lub nowszej. Gdy jest obecny, określony zestaw indeksów (w tym upuszczanie indeksów) zastępuje istniejące indeksy kolekcji. Wymagany jest indeks _id. Każdy wpis w tablicy musi zawierać klucz co najmniej jednego pola, nazwę i może zawierać opcje indeksu. Aby na przykład utworzyć złożony unikatowy indeks w polach a i b, użyj następującego wpisu: {key: {a: 1, b: 1}, name: "a_1_b_1", unique: true}.

Wyjście

Zwraca domyślną niestandardową odpowiedź polecenia. Zobacz domyślne dane wyjściowe polecenia niestandardowego dla parametrów w danych wyjściowych.

Przykład: aktualizowanie aprowizowanej przepływności skojarzonej z kolekcją

Aby zaktualizować aprowizowaną przepływność kolekcji o nazwie "testCollection" do 1200 jednostek RU, użyj następującego polecenia:

use test
db.runCommand({customAction: "UpdateCollection", collection: "testCollection", offerThroughput: 1200 });

Pobieranie kolekcji

Polecenie niestandardowe get collection zwraca obiekt kolekcji.

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

W poniższej tabeli opisano parametry w poleceniu :

Pole Typ Opis
customAction string Nazwa polecenia niestandardowego. Wartość musi mieć wartość GetCollection.
collection string Nazwa kolekcji.

Wyjście

Jeśli polecenie powiedzie się, odpowiedź zawiera dokument z następującymi polami

Pole Typ Opis
ok int Stan odpowiedzi. 1 == sukces. 0 == awaria.
database string Nazwa bazy danych.
collection string Nazwa kolekcji.
shardKeyDefinition document Dokument specyfikacji indeksu używany jako klucz fragmentu. To pole jest opcjonalnym parametrem odpowiedzi.
provisionedThroughput int Aprowizowana przepływność ustawiona w kolekcji. To pole jest opcjonalnym parametrem odpowiedzi.
autoScaleSettings Object Ten obiekt zawiera parametry pojemności skojarzone z bazą danych, jeśli używa trybu autoskalowania. Wartość maxThroughput opisuje największą liczbę jednostek żądań, które można zwiększyć w celu dynamicznego zwiększania kolekcji.

Jeśli polecenie zakończy się niepowodzeniem, zostanie zwrócona domyślna niestandardowa odpowiedź polecenia. Zobacz domyślne dane wyjściowe polecenia niestandardowego dla parametrów w danych wyjściowych.

Przykład: pobieranie kolekcji

Aby uzyskać obiekt kolekcji dla kolekcji o nazwie "testCollection", użyj następującego polecenia:

use test
db.runCommand({customAction: "GetCollection", collection: "testCollection"});

Jeśli kolekcja ma skojarzona pojemność przepływności, zawiera provisionedThroughput wartość, a dane wyjściowe to:

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

Jeśli kolekcja ma skojarzona przepływność autoskalowania, zawiera autoScaleSettings obiekt z parametrem maxThroughput , który definiuje maksymalną przepływność, którą kolekcja zwiększa się dynamicznie. Ponadto zawiera provisionedThroughput również wartość, która definiuje minimalną przepływność, którą ta kolekcja zmniejsza, jeśli w kolekcji nie ma żadnych żądań:

{
        "database" : "test",
        "collection" : "testCollection",
        "provisionedThroughput" : 1000,
        "autoScaleSettings" : {
            "maxThroughput" : 10000
        },
        "ok" : 1
}

Jeśli kolekcja udostępnia przepływność na poziomie bazy danych, w trybie autoskalowania lub ręcznym, dane wyjściowe będą następujące:

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

{
        "database" : "test",
        "provisionedThroughput" : 2000,
        "autoScaleSettings" : {
            "maxThroughput" : 20000
        },
        "ok" : 1
}

Równoległe strumienie zmian

W przypadku używania strumieni zmian na dużą skalę najlepiej równomiernie rozłożyć obciążenie. Następujące polecenie zwraca co najmniej jeden token wznawiania zmian strumienia — każdy z nich odpowiada danym z jednego fizycznego fragmentu/partycji (wiele fragmentów logicznych/partycji może istnieć na jednej partycji fizycznej). Każdy token wznawiania powoduje, że funkcja watch() zwraca tylko dane z tego fizycznego fragmentu/partycji.

Użyj db.collection.watch() na każdym tokenie wznawiania (jeden wątek na token), aby wydajnie skalować strumienie zmian.

{
        customAction: "GetChangeStreamTokens", 
        collection: "<Name of the collection>", 
        startAtOperationTime: "<BSON Timestamp>" // Optional. Defaults to the time the command is run.
}

Przykład: uzyskiwanie tokenu strumienia

Uruchom polecenie niestandardowe, aby uzyskać token wznawiania dla każdego fizycznego fragmentu/partycji.

use test
db.runCommand({customAction: "GetChangeStreamTokens", collection: "<Name of the collection>"})

Uruchom wątek/proces watch() dla każdego tokenu wznawiania zwróconego z polecenia niestandardowego GetChangeStreamTokens. Oto przykład jednego wątku.

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 (wartość) w polu resumeAfter reprezentuje token wznowienia. Polecenie watch() zwraca przekleństwo dla wszystkich dokumentów, które zostały wstawione, zaktualizowane lub zastąpione z tej partycji fizycznej od czasu uruchomienia polecenia niestandardowego GetChangeStreamTokens. W tym miejscu dołączono przykład zwracanych danych.

{
  "_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żdy zwrócony dokument zawiera token wznawiania (wszystkie są takie same dla każdej strony). Ten token wznawiania powinien być przechowywany i ponownie używany, jeśli wątek/proces umrze. Ten token wznawiania jest pobierany z miejsca, w którym został przerwany, i odbiera dane tylko z tej partycji fizycznej.

Domyślne dane wyjściowe polecenia niestandardowego

Jeśli nie zostanie określona, odpowiedź niestandardowa zawiera dokument z następującymi polami:

Pole Typ Opis
ok int Stan odpowiedzi. 1 == sukces. 0 == awaria.
code int Zwracane tylko wtedy, gdy polecenie nie powiodło się (czyli ok == 0). Zawiera kod błędu bazy danych MongoDB. To pole jest opcjonalnym parametrem odpowiedzi.
errMsg string Zwracane tylko wtedy, gdy polecenie nie powiodło się (czyli ok == 0). Zawiera przyjazny dla użytkownika komunikat o błędzie. To pole jest opcjonalnym parametrem odpowiedzi.

Na przykład:

{ "ok" : 1 }

Następne kroki

Następnie możesz zapoznać się z następującymi pojęciami dotyczącymi usługi Azure Cosmos DB: