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

DOTYCZY: Mongodb

Poniższy dokument zawiera niestandardowe polecenia akcji specyficzne dla interfejsu API 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 interfejsu API usługi Azure Cosmos DB dla bazy danych MongoDB, możesz korzystać z zalet usługi Azure Cosmos DB, takich jak dystrybucja globalna, automatyczne fragmentowanie, wysoka dostępność, gwarancje opóźnienia, automatyczne, szyfrowanie magazynowane, kopie zapasowe i wiele innych, zachowując inwestycje w aplikację MongoDB. Możesz komunikować się z interfejsem API usługi Azure Cosmos DB dla bazy danych MongoDB przy użyciu dowolnego sterownika klienta bazy danych MongoDB typu open source. Interfejs API usługi 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

Interfejs API usługi Azure Cosmos DB dla bazy danych MongoDB jest zgodny 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 4.0, 3.6 i 3.2 .

Następujące polecenia rozszerzenia umożliwiają tworzenie i modyfikowanie zasobów specyficznych 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 musi być "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ą ilość jednostek żądania, które kolekcja zostanie zwiększona dynamicznie.

Dane wyjściowe

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

{ "ok" : 1 }

Zobacz domyślne dane wyjściowe polecenia niestandardowego, aby uzyskać parametry w danych wyjściowych.

Przykłady

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 spowoduje utworzenie bazy danych bez przepływności na poziomie bazy danych. Oznacza to, że kolekcje w tej bazie danych będą musiały określić ilość przepływności, której należy użyć.

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 });

Spowoduje to utworzenie bazy danych i ustawienie jej przepływności. Wszystkie kolekcje w tej bazie danych będą współdzielić ustawioną przepływność, chyba że kolekcje zostaną utworzone z określonym poziomem przepływności.

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 witrynie Azure Portal. W poniższej tabeli opisano parametry w poleceniu :

Pole Typ Opis
customAction string Nazwa polecenia niestandardowego. 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 baza danych będzie zwiększana dynamicznie.

To polecenie używa bazy danych określonej w kontekście sesji. Jest to baza danych użyta 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, zwróci następującą odpowiedź:

{ "ok" : 1 }

Zobacz domyślne dane wyjściowe polecenia niestandardowego, aby uzyskać parametry w danych wyjściowych.

Przykłady

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 });

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. Musi być "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 baza danych zostanie zwiększona dynamicznie.

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łady

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, a autoScaleSettings także obiekt maxThroughputzawierający opis maksymalnej liczby 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. 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 minimum 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 będą wymagały tego klucza i wartości.
autoScaleSettings Object Wymagane dla trybu 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 będą dynamicznie zwiększane do 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łady

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"});

Spowoduje to utworzenie nowej stałej, nieshardowanej kolekcji z wartością 400RU/s i indeksem w polu automatycznie utworzonym _id . Ten typ konfiguracji będzie również stosowany podczas tworzenia nowych kolekcji za pośrednictwem insert() funkcji . Przykład:

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

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ą.

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

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 .

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 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. 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órą kolekcja zostanie zwiększona dynamicznie.
indexes Array Opcjonalnie skonfiguruj indeksy. Ten parametr jest obsługiwany tylko w przypadku kont w wersji 3.6 lub nowszej. W chwili obecnej istniejące indeksy kolekcji są zastępowane przez określony zestaw indeksów (w tym porzucanie indeksów). 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łady

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. 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. Jest to opcjonalny parametr odpowiedzi.
provisionedThroughput int Aprowizowana przepływność ustawiana w kolekcji. Jest to opcjonalny parametr odpowiedzi.
autoScaleSettings Object Ten obiekt zawiera parametry pojemności skojarzone z bazą danych, jeśli używa trybu autoskalowania. Wartość maxThroughput opisuje największą ilość jednostek żądań, którą kolekcja zostanie zwiększona dynamicznie.

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łady

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, będzie 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, będzie zawierać autoScaleSettings obiekt z parametrem maxThroughput , który definiuje maksymalną przepływność, którą kolekcja będzie zwiększać dynamicznie. Ponadto będzie ona również zawierać provisionedThroughput wartość, która definiuje minimalną przepływność, do której ta kolekcja zmniejszy się, 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 zwróci co najmniej jeden token wznowienia strumienia zmian — każdy odpowiadający danym z jednego fizycznego fragmentu/partycji (wiele logicznych fragmentów/partycji może istnieć na jednej partycji fizycznej). Każdy token wznawiania spowoduje, że funkcja watch() zwróci tylko dane z tego fizycznego fragmentu/partycji.

Wywoływanie elementu db.collection.watch() w każdym tokenie wznawiania (jeden wątek na token) umożliwia wydajne skalowanie strumieni zmian.

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

Przykład

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. Poniżej znajduje się 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. watch() zwróci przeklętę dla wszystkich dokumentów, które zostały wstawione, zaktualizowane lub zastąpione z tej partycji fizycznej od czasu uruchomienia polecenia niestandardowego GetChangeStreamTokens. Poniżej znajduje się 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") }}

Należy pamiętać, że 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 zostanie odebrany z miejsca, z którego zostało przerwane, i otrzyma 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ę (tj. ok == 0). Zawiera kod błędu bazy danych MongoDB. Jest to opcjonalny parametr odpowiedzi.
errMsg string Zwracane tylko wtedy, gdy polecenie nie powiodło się (tj. ok == 0). Zawiera przyjazny dla użytkownika komunikat o błędzie. Jest to opcjonalny parametr 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: