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 niestandardowe polecenia akcji 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 zalet usługi Azure Cosmos DB. Te korzyści obejmują, ale nie są ograniczone do:

  • Dystrybucja globalna
  • Automatyczne fragmentowanie
  • Wysoka dostępność
  • Gwarancje dot. opóźnienia
  • Szyfrowanie danych magazynowanych
  • Tworzenie kopii zapasowych

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 Autoskalowanie. Możesz skonfigurować maxThroughput wartość, która opisuje największą liczbę jednostek żądania, które kolekcja może zwiększyć dynamicznie.

Dane wyjściowe

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

{ "ok" : 1 }

Zobacz domyślne dane wyjściowe polecenia niestandardowego, aby uzyskać parametry 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 potrzebnej do użycia.

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 dla niej przepływność. Wszystkie kolekcje w tej bazie danych współdzielą przepływność zestawu, 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 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 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 Autoskalowanie. Możesz 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.

Dane wyjściowe

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

{ "ok" : 1 }

Zobacz domyślne dane wyjściowe polecenia niestandardowego, aby uzyskać parametry 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.

Dane wyjściowe

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

Pole Typ Opis
ok int Stan odpowiedzi. 1 == sukces. 0 == niepowodzenie.
database string Nazwa bazy danych.
provisionedThroughput int Aprowizowana przepływność ustawiona w bazie danych, jeśli baza danych korzysta z 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ć w celu dynamicznego zwiększenia bazy danych.

Jeśli polecenie zakończy się niepowodzeniem, zostanie zwrócona domyślna odpowiedź polecenia niestandardowego. 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ę RU/s dla bazy danych, oraz autoScaleSettings obiekt zawierający maxThroughputwartość , która opisuje maksymalną liczbę JEDNOSTEK RU/s dla bazy danych.

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

Tworzenie kolekcji

Polecenie create collection extension tworzy nową kolekcję bazy danych 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 Wymagane Opis
customAction string Wymagane Nazwa polecenia niestandardowego. Wartość musi mieć wartość CreateCollection.
collection string Wymagane Nazwa kolekcji. Znaki specjalne ani spacje nie są dozwolone.
offerThroughput int Opcjonalne Aprowizowana przepływność ustawiana w bazie danych. Jeśli ten parametr nie zostanie podany, wartość domyślna to minimalna, 400 RU/s. * Aby określić przepływność powyżej 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 dla trybu 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 zwiększyć w celu dynamicznego zwiększenia kolekcji.
indexes Array Opcjonalnie skonfiguruj indeksy. Ten parametr jest obsługiwany tylko w przypadku kont w wersji 3.6 lub nowszej. Gdy 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ć indeks unikatowy złożony w polach a i b użyć następującego wpisu: {key: {a: 1, b: 1}, name:"a_1_b_1", unique: true}.

Dane wyjściowe

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, nieshardowanej kolekcji z wartością 400RU/s i indeksem w polu automatycznie utworzonym _id . Ten typ konfiguracji ma zastosowanie również podczas tworzenia nowych kolekcji za pośrednictwem insert() funkcji . Przykład:

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

Przykład: tworzenie kolekcji bez fragmentowania

Aby utworzyć kolekcję bez fragmentowania 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ę podzielonej na fragmenty 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ć kolekcję bez fragmentowania 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. W przypadku wyższej przepływności autoskalowania należy określić shardKey parametr .

Przykład: tworzenie kolekcji autoskalowania podzielonego na fragmenty

Aby utworzyć kolekcję podzielonej na fragmenty 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 na odwrót jest obsługiwana tylko w 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ść ustawiana w kolekcji.
autoScaleSettings Object Wymagane dla trybu autoskalowania. Ten obiekt zawiera ustawienia skojarzone z trybem pojemności autoskalowania. Wartość maxThroughput opisuje największą liczbę jednostek żądania, które można zwiększyć w celu dynamicznego zwiększenia kolekcji.
indexes Array Opcjonalnie skonfiguruj indeksy. Ten parametr jest obsługiwany tylko w przypadku 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. Indeks _id jest wymagany. Każdy wpis w tablicy musi zawierać klucz co najmniej jednego pola, nazwę i może zawierać opcje indeksu. Aby na przykład utworzyć indeks unikatowy złożony w polach a i b, użyj następującego wpisu: {key: {a: 1, b: 1}, name: "a_1_b_1", unique: true}.

Dane wyjściowe

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.

Dane wyjściowe

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ść ustawiana 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 żądania, które można zwiększyć w celu dynamicznego zwiększania kolekcji.

Jeśli polecenie zakończy się niepowodzeniem, zostanie zwrócona domyślna odpowiedź polecenia niestandardowego. Zobacz domyślne dane wyjściowe polecenia niestandardowego, aby uzyskać parametry 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 będą następujące:

{
        "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 również wartość, która definiuje minimalną provisionedThroughput 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 korzystania ze 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 odpowiadający 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() w każdym tokenie wznawiania (jeden wątek na token), aby efektywnie skalować strumienie zmian.

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

Przykład: pobieranie 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 niestandardowego polecenia GetChangeStreamTokens. Oto przykład dla 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 wznawiania. Polecenie watch() zwraca przeklęcie 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 znajduje się przykład zwróconych 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 zostanie usunięty. Ten token wznawiania jest pobierany z miejsca, w którym zostało przerwane, 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 == niepowodzenie.
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.

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: