MongoDB-extensieopdrachten gebruiken om gegevens te beheren die zijn opgeslagen in Azure Cosmos DB voor MongoDB

VAN TOEPASSING OP: MongoDB

Het volgende document bevat de aangepaste actieopdrachten die specifiek zijn voor Azure Cosmos DB voor MongoDB. Deze opdrachten kunnen worden gebruikt voor het maken en verkrijgen van databaseresources die specifiek zijn voor het Azure Cosmos DB-capaciteitsmodel.

Door Azure Cosmos DB voor MongoDB te gebruiken, kunt u profiteren van de gedeelde voordelen van Azure Cosmos DB. Deze voordelen omvatten, maar zijn niet beperkt tot:

• Wereldwijde distributie
• Automatische sharding
• Hoge beschikbaarheid
• Gegarandeerde latentie
• Versleuteling 'at rest'
• Back-ups

U kunt profiteren van deze voordelen terwijl u uw investeringen in uw bestaande MongoDB-toepassing[s] behoudt. U kunt communiceren met De Azure Cosmos DB voor MongoDB met behulp van een van de opensource-MongoDB-clientstuurprogramma's. Azure Cosmos DB voor MongoDB maakt het gebruik van bestaande clientstuurprogramma's mogelijk door het MongoDB-wireprotocol te volgen.

Ondersteuning voor MongoDB-protocol

Azure Cosmos DB voor MongoDB is compatibel met MongoDB-serverversie 4.0, 3.6 en 3.2. Zie ondersteunde functies en syntaxis in versies 4.0, 3.6 en 3.2 voor meer informatie.

Met de volgende extensieopdrachten kunt u Azure Cosmos DB-specifieke resources maken en wijzigen via databaseaanvragen:

• Database maken
• Database bijwerken
• Database ophalen
• Verzameling maken
• Verzameling bijwerken
• Verzameling ophalen

Database maken

Met de opdracht database-extensie maken wordt een nieuwe MongoDB-database gemaakt. De databasenaam kan worden gebruikt vanuit de databasecontext die is ingesteld met de use database opdracht . In de volgende tabel worden de parameters in de opdracht beschreven:

Veld	Type	Beschrijving
customAction	string	Naam van de aangepaste opdracht. De waarde moet zijn CreateDatabase.
offerThroughput	int	Ingerichte doorvoer die u instelt voor de database. Deze parameter is optioneel.
autoScaleSettings	Object	Vereist voor de modus Voor automatisch schalen. Dit object bevat de instellingen die zijn gekoppeld aan de capaciteitsmodus Automatisch schalen. U kunt de maxThroughput waarde instellen, waarmee het hoogste aantal aanvraageenheden wordt beschreven dat de verzameling dynamisch kan verhogen.

Uitvoer

Als de opdracht is geslaagd, wordt het volgende antwoord geretourneerd:

{ "ok" : 1 }

Zie de standaarduitvoer van de aangepaste opdracht voor de parameters in de uitvoer.

Voorbeeld: Een database maken

Als u een database met de naam "test" wilt maken die gebruikmaakt van alle standaardwaarden, gebruikt u de volgende opdracht:

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

Met deze opdracht maakt u een database zonder doorvoer op databaseniveau. Deze bewerking betekent dat de verzamelingen in deze database de hoeveelheid doorvoer moeten opgeven die u moet gebruiken.

Voorbeeld: Een database met doorvoer maken

Gebruik de volgende opdracht om een database met de naam "test" te maken en een ingerichte doorvoer op databaseniveau van 1000 RU's op te geven:

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

Met deze opdracht maakt u een database en stelt u een doorvoer in. Alle verzamelingen in deze database delen de ingestelde doorvoer, tenzij de verzamelingen zijn gemaakt met een specifiek doorvoerniveau.

Voorbeeld: Een database maken met doorvoer voor automatische schaalaanpassing

Gebruik de volgende opdracht om een database met de naam "test" te maken en een maximale doorvoer voor automatische schaalaanpassing van 20.000 RU/s op databaseniveau op te geven:

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

Database bijwerken

De opdracht database-extensie bijwerken werkt de eigenschappen bij die zijn gekoppeld aan de opgegeven database. Het wijzigen van uw database van ingerichte doorvoer naar automatische schaalaanpassing en vice versa wordt alleen ondersteund in de Azure Portal. In de volgende tabel worden de parameters in de opdracht beschreven:

Veld	Type	Beschrijving
customAction	string	Naam van de aangepaste opdracht. De waarde moet zijn UpdateDatabase.
offerThroughput	int	Nieuwe ingerichte doorvoer die u wilt instellen voor de database als de database gebruikmaakt van doorvoer op databaseniveau
autoScaleSettings	Object	Vereist voor de modus Voor automatisch schalen. Dit object bevat de instellingen die zijn gekoppeld aan de capaciteitsmodus Automatisch schalen. U kunt de maxThroughput waarde instellen, waarmee het hoogste aantal aanvraageenheden wordt beschreven waarmee de database dynamisch kan worden verhoogd.

Met deze opdracht wordt de database gebruikt die is opgegeven in de context van de sessie. Deze database is dezelfde die u in de use <database> opdracht hebt gebruikt. Op dit moment kan de databasenaam niet worden gewijzigd met behulp van deze opdracht.

Uitvoer

Als de opdracht is geslaagd, wordt het volgende antwoord geretourneerd:

{ "ok" : 1 }

Zie de standaarduitvoer van de aangepaste opdracht voor de parameters in de uitvoer.

Voorbeeld: De ingerichte doorvoer bijwerken die is gekoppeld aan een database

Als u de ingerichte doorvoer van een database met een naam "test" wilt bijwerken naar 1200 RU's, gebruikt u de volgende opdracht:

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

Voorbeeld: De doorvoer voor automatisch schalen bijwerken die is gekoppeld aan een database

Gebruik de volgende opdracht om de ingerichte doorvoer van een database met de naam "test" bij te werken naar 20.000 RU's of om deze te transformeren naar een doorvoerniveau voor automatische schaalaanpassing:

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

Database ophalen

De opdracht database-extensie ophalen retourneert het databaseobject. De databasenaam wordt gebruikt vanuit de databasecontext waarop de opdracht wordt uitgevoerd.

{
  customAction: "GetDatabase"
}

In de volgende tabel worden de parameters in de opdracht beschreven:

Veld	Type	Beschrijving
customAction	string	Naam van de aangepaste opdracht. De waarde moet zijn GetDatabase.

Uitvoer

Als de opdracht slaagt, bevat het antwoord een document met de volgende velden:

Veld	Type	Beschrijving
ok	int	Status van antwoord. 1 == geslaagd. 0 == fout.
database	string	Naam van de database.
provisionedThroughput	int	Ingerichte doorvoer die is ingesteld voor de database als de database gebruikmaakt van handmatige doorvoer op databaseniveau
autoScaleSettings	Object	Dit object bevat de capaciteitsparameters die zijn gekoppeld aan de database als deze gebruikmaakt van de modus Automatisch schalen. De maxThroughput waarde beschrijft het hoogste aantal aanvraageenheden waarmee de database dynamisch kan worden verhoogd.

Als de opdracht mislukt, wordt een standaard aangepast opdrachtantwoord geretourneerd. Zie de standaarduitvoer van de aangepaste opdracht voor de parameters in de uitvoer.

Voorbeeld: De database ophalen

Gebruik de volgende opdracht om het databaseobject voor een database met de naam "test"op te halen:

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

Als de database geen gekoppelde doorvoer heeft, is de uitvoer:

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

Als aan de database handmatige doorvoer op databaseniveau is gekoppeld, worden in de uitvoer de provisionedThroughput waarden weergegeven:

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

Als aan de database een doorvoer voor automatisch schalen op databaseniveau is gekoppeld, wordt in de uitvoer de provisionedThroughputweergegeven, waarin de minimale RU/s voor de database worden beschreven, en het autoScaleSettings object met inbegrip van de maxThroughput, waarmee het maximum aantal RU/s voor de database wordt beschreven.

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

Verzameling maken

Met de opdracht verzamelingsextensie maken wordt een nieuwe MongoDB-verzameling gemaakt. De databasenaam wordt gebruikt vanuit de databasecontext die is ingesteld door de use database opdracht . De indeling van de opdracht CreateCollection is als volgt:

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

In de volgende tabel worden de parameters in de opdracht beschreven:

Veld	Type	Vereist	Beschrijving
customAction	string	Vereist	Naam van de aangepaste opdracht. De waarde moet zijn CreateCollection.
collection	string	Vereist	Naam van de verzameling. Speciale tekens of spaties zijn niet toegestaan.
offerThroughput	int	Optioneel	Ingerichte doorvoer die moet worden ingesteld voor de database. Als deze parameter niet is opgegeven, wordt standaard ingesteld op het minimum, 400 RU/s. * Als u een doorvoer van meer dan 10.000 RU/s wilt opgeven, is de shardKey parameter vereist.
shardKey	string	Vereist voor verzamelingen met een grote doorvoer	Het pad naar de Shard-sleutel voor de shardverzameling. Deze parameter is vereist als u meer dan 10.000 RU/s instelt in offerThroughput. Als dit is opgegeven, vereisen alle ingevoegde documenten deze sleutel en waarde.
autoScaleSettings	Object	Vereist voor de modus Voor automatisch schalen	Dit object bevat de instellingen die zijn gekoppeld aan de capaciteitsmodus Automatisch schalen. U kunt de maxThroughput waarde instellen, waarmee het hoogste aantal aanvraageenheden wordt beschreven waarmee de verzameling dynamisch kan worden uitgebreid.
indexes	Array	Configureer desgewenst indexen. Deze parameter wordt alleen ondersteund voor 3.6+ accounts.	Indien aanwezig is een index op _id vereist. Elke vermelding in de matrix moet een sleutel van een of meer velden en een naam bevatten en kan indexopties bevatten. Als u bijvoorbeeld een samengestelde unieke index wilt maken voor de velden a en b deze vermelding wilt gebruiken: {key: {a: 1, b: 1}, name:"a_1_b_1", unique: true}.

Uitvoer

Retourneert een standaard aangepast opdrachtantwoord. Zie de standaarduitvoer van de aangepaste opdracht voor de parameters in de uitvoer.

Voorbeeld: Een verzameling maken met de minimale configuratie

Als u een nieuwe verzameling wilt maken met de naam "testCollection" en de standaardwaarden, gebruikt u de volgende opdracht:

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

Deze bewerking resulteert in een nieuwe vaste, niet-geharde verzameling met 400RU/s en een index in het _id veld die automatisch wordt gemaakt. Dit type configuratie is ook van toepassing bij het maken van nieuwe verzamelingen via de insert() functie. Bijvoorbeeld:

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

Voorbeeld: een niet-geharde verzameling maken

Als u een niet-geharde verzameling wilt maken met een naam "testCollection" en ingerichte doorvoer van 1000 RU's, gebruikt u de volgende opdracht:

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

U kunt een verzameling maken met maximaal 10.000 RU/s als de offerThroughput zonder dat u een shardsleutel hoeft op te geven. Bekijk de volgende sectie voor verzamelingen met een grotere doorvoer.

Voorbeeld: Een shard-verzameling maken

Als u een shard-verzameling wilt maken met een naam "testCollection" en ingerichte doorvoer van 11.000 RU's en een shardkey eigenschap 'a.b', gebruikt u de volgende opdracht:

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

Voor deze opdracht is nu de shardKey parameter vereist, omdat er meer dan 10.000 RU/s zijn opgegeven in de offerThroughput.

Voorbeeld: Een verzameling niet-geharde automatische schaalaanpassing maken

Als u een niet-geharde verzameling met de naam 'testCollection' wilt maken die gebruikmaakt van doorvoercapaciteit voor automatische schaalaanpassing die is ingesteld op 4000 RU/s, gebruikt u de volgende opdracht:

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

Voor de autoScaleSettings.maxThroughput waarde kunt u een bereik opgeven van 4000 RU/s tot 10.000 RU/s zonder een shardsleutel. Voor een hogere doorvoer voor automatische schaalaanpassing moet u de shardKey parameter opgeven.

Voorbeeld: Een verzameling shards voor automatisch schalen maken

Als u een shard-verzameling met de naam 'testCollection' wilt maken met een shardsleutel met de naam 'a.b', en die gebruikmaakt van doorvoercapaciteit voor automatische schaalaanpassing die is ingesteld op 20.000 RU/s, gebruikt u de volgende opdracht:

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

Verzameling bijwerken

Met de opdracht verzamelingsextensie bijwerken worden de eigenschappen bijgewerkt die zijn gekoppeld aan de opgegeven verzameling. Het wijzigen van uw verzameling van ingerichte doorvoer naar automatische schaalaanpassing en omgekeerd wordt alleen ondersteund in de 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).
}

In de volgende tabel worden de parameters in de opdracht beschreven:

Veld	Type	Beschrijving
customAction	string	Naam van de aangepaste opdracht. De waarde moet zijn UpdateCollection.
collection	string	Naam van de verzameling.
offerThroughput	int	Ingerichte doorvoer die moet worden ingesteld voor de verzameling.
autoScaleSettings	Object	Vereist voor de modus Voor automatisch schalen. Dit object bevat de instellingen die zijn gekoppeld aan de capaciteitsmodus Automatisch schalen. De maxThroughput waarde beschrijft het hoogste aantal aanvraageenheden waartoe de verzameling dynamisch kan worden uitgebreid.
indexes	Array	Configureer desgewenst indexen. Deze parameter wordt alleen ondersteund voor 3.6+ accounts. Indien aanwezig, vervangt de opgegeven set indexen (inclusief het verwijderen van indexen) de bestaande indexen van de verzameling. Er is een index op _id vereist. Elke vermelding in de matrix moet een sleutel van een of meer velden en een naam bevatten en kan indexopties bevatten. Als u bijvoorbeeld een samengestelde unieke index wilt maken voor de velden a en b, gebruikt u deze vermelding: {key: {a: 1, b: 1}, name: "a_1_b_1", unique: true}.

Uitvoer

Retourneert een standaard aangepast opdrachtantwoord. Zie de standaarduitvoer van de aangepaste opdracht voor de parameters in de uitvoer.

Voorbeeld: De ingerichte doorvoer bijwerken die is gekoppeld aan een verzameling

Gebruik de volgende opdracht om de ingerichte doorvoer van een verzameling met de naam "testCollection" bij te werken naar 1200 RU's:

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

Verzameling ophalen

De opdracht get collection custom retourneert het verzamelingsobject.

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

In de volgende tabel worden de parameters in de opdracht beschreven:

Veld	Type	Beschrijving
customAction	string	Naam van de aangepaste opdracht. De waarde moet zijn GetCollection.
collection	string	Naam van de verzameling.

Uitvoer

Als de opdracht slaagt, bevat het antwoord een document met de volgende velden

Veld	Type	Beschrijving
ok	int	Status van antwoord. 1 == geslaagd. 0 == fout.
database	string	Naam van de database.
collection	string	Naam van de verzameling.
shardKeyDefinition	document	Indexspecificatiedocument dat wordt gebruikt als een shardsleutel. Dit veld is een optionele antwoordparameter.
provisionedThroughput	int	Ingerichte doorvoer om in te stellen voor de verzameling. Dit veld is een optionele antwoordparameter.
autoScaleSettings	Object	Dit object bevat de capaciteitsparameters die zijn gekoppeld aan de database als deze gebruikmaakt van de modus Automatisch schalen. De maxThroughput waarde beschrijft het hoogste aantal aanvraageenheden waarmee de verzameling dynamisch kan worden uitgebreid.

Als de opdracht mislukt, wordt een standaard aangepast opdrachtantwoord geretourneerd. Zie de standaarduitvoer van de aangepaste opdracht voor de parameters in de uitvoer.

Voorbeeld: De verzameling ophalen

Gebruik de volgende opdracht om het verzamelingsobject voor een verzameling met de naam "testCollection"op te halen:

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

Als de verzameling een bijbehorende doorvoercapaciteit heeft, bevat deze de provisionedThroughput waarde en is de uitvoer:

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

Als de verzameling een gekoppelde doorvoer voor automatisch schalen heeft, bevat deze het autoScaleSettings -object met de maxThroughput parameter , waarmee de maximale doorvoer wordt gedefinieerd waarmee de verzameling dynamisch wordt verhoogd. Daarnaast bevat het ook de provisionedThroughput waarde, die de minimale doorvoer definieert die deze verzameling vermindert als er geen aanvragen in de verzameling zijn:

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

Als de verzameling doorvoer op databaseniveau deelt, in de modus Automatisch schalen of handmatig, is de uitvoer:

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

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

Parallelle wijzigingsstromen

Wanneer u wijzigingsstromen op schaal gebruikt, kunt u de belasting het beste gelijkmatig verdelen. De volgende opdracht retourneert een of meer cv-tokens voor de wijzigingsstroom, die allemaal overeenkomen met gegevens uit één fysieke shard/partitie (er kunnen meerdere logische shards/partities op één fysieke partitie bestaan). Elk resume-token zorgt ervoor dat watch() alleen gegevens retourneert van die fysieke shard/partitie.

Gebruik db.collection.watch() op elk cv-token (één thread per token) om wijzigingsstromen efficiënt te schalen.

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

Voorbeeld: Het streamtoken ophalen

Voer de aangepaste opdracht uit om een cv-token op te halen voor elke fysieke shard/partitie.

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

Voer een watch() thread/process uit voor elk cv-token dat wordt geretourneerd door de aangepaste opdracht GetChangeStreamTokens. Hier volgt een voorbeeld voor één thread.

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

Het document (waarde) in het veld resumeAfter vertegenwoordigt het cv-token. De opdracht watch() retourneert een vloek voor alle documenten die zijn ingevoegd, bijgewerkt of vervangen vanaf die fysieke partitie sinds de aangepaste opdracht GetChangeStreamTokens is uitgevoerd. Hier vindt u een voorbeeld van de geretourneerde gegevens.

{
  "_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")
  }
}

Elk geretourneerd document bevat een cv-token (ze zijn allemaal hetzelfde voor elke pagina). Dit cv-token moet worden opgeslagen en opnieuw worden gebruikt als de thread/het proces sterft. Dit cv-token gaat verder waar u was gebleven en ontvangt alleen gegevens van die fysieke partitie.

Standaarduitvoer van een aangepaste opdracht

Als dit niet is opgegeven, bevat een aangepast antwoord een document met de volgende velden:

Veld	Type	Beschrijving
ok	int	Status van antwoord. 1 == succes. 0 == fout.
code	int	Alleen geretourneerd wanneer de opdracht is mislukt (dat wil gezegd, ok == 0). Bevat de MongoDB-foutcode. Dit veld is een optionele antwoordparameter.
errMsg	string	Alleen geretourneerd wanneer de opdracht is mislukt (dat wil gezegd, ok == 0). Bevat een gebruiksvriendelijk foutbericht. Dit veld is een optionele antwoordparameter.

Bijvoorbeeld:

{ "ok" : 1 }

Volgende stappen

Vervolgens kunt u meer te weten komen over de volgende Azure Cosmos DB-concepten:

• Indexering in Azure Cosmos DB
• Gegevens in Azure Cosmos DB automatisch laten verlopen met TTL