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 databasebronnen die specifiek zijn voor het Azure Cosmos DB-capaciteitsmodel.

Met behulp van Azure Cosmos DB voor MongoDB 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 van deze voordelen profiteren en uw investeringen in uw bestaande MongoDB-toepassing behouden[s]. U kunt communiceren met Azure Cosmos DB voor MongoDB met behulp van een van de opensource MongoDB-clientstuurprogramma's. De Azure Cosmos DB voor MongoDB maakt het gebruik van bestaande clientstuurprogramma's mogelijk door zich aan het MongoDB-wireprotocol te houden.

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 versie 4.0, 3.6 en 3.2 voor meer informatie.

Met de volgende extensieopdrachten maakt en wijzigt u azure Cosmos DB-specifieke resources 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 door de use database opdracht is ingesteld. In de volgende tabel worden de parameters in de opdracht beschreven:

Veld	Type	Description
customAction	string	Naam van de aangepaste opdracht. De waarde moet zijn CreateDatabase.
offerThroughput	int	Ingerichte doorvoer die u voor de database hebt ingesteld. Deze parameter is optioneel.
autoScaleSettings	Object	Vereist voor de modus Automatisch schalen. Dit object bevat de instellingen die zijn gekoppeld aan de capaciteitsmodus voor automatisch schalen. U kunt de maxThroughput waarde instellen, waarin 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 een aangepaste opdracht voor de parameters in de uitvoer.

Voorbeeld: Een database maken

Als u een database wilt maken met de naam "test" 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 maken met doorvoer

Als u een database met de naam "test" wilt maken en een ingerichte doorvoer op databaseniveau van 1000 RU's wilt opgeven, gebruikt u de volgende opdracht:

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

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

Voorbeeld: Een database maken met doorvoer automatisch schalen

Als u een database met de naam "test" wilt maken en een maximale doorvoer voor automatische schaalaanpassing van 20.000 RU/s op databaseniveau wilt opgeven, gebruikt u de volgende opdracht:

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

Database bijwerken

Met de opdracht database-extensie bijwerken worden de eigenschappen bijgewerkt die zijn gekoppeld aan de opgegeven database. Het wijzigen van uw database van ingerichte doorvoer in automatisch schalen en vice versa wordt alleen ondersteund in Azure Portal. In de volgende tabel worden de parameters in de opdracht beschreven:

Veld	Type	Description
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 Automatisch schalen. Dit object bevat de instellingen die zijn gekoppeld aan de capaciteitsmodus voor automatisch schalen. U kunt de maxThroughput waarde instellen, waarin het hoogste aantal aanvraageenheden wordt beschreven dat 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 hetzelfde dat 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 een aangepaste opdracht voor de parameters in de uitvoer.

Voorbeeld: De ingerichte doorvoer 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 1200 RU's:

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

Voorbeeld: De doorvoer voor automatische schaalaanpassing 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 waarmee de opdracht wordt uitgevoerd.

{
  customAction: "GetDatabase"
}

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

Veld	Type	Description
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	Description
ok	int	Status van antwoord. 1 == succes. 0 == fout.
database	string	Naam van de database.
provisionedThroughput	int	Ingerichte doorvoer die is ingesteld voor de database als de database handmatige doorvoer op databaseniveau gebruikt
autoScaleSettings	Object	Dit object bevat de capaciteitsparameters die aan de database zijn gekoppeld als het gebruikmaakt van de modus Automatisch schalen. De maxThroughput waarde beschrijft het hoogste aantal aanvraageenheden dat de database dynamisch kan worden verhoogd.

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

Voorbeeld: De database ophalen

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

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 op databaseniveau voor automatische schaalaanpassing is gekoppeld, wordt in de uitvoer de provisionedThroughputuitvoer weergegeven, waarin de minimale RU/s voor de database worden beschreven, en het autoScaleSettings object met inbegrip van het maxThroughputobject, waarin de maximale RU/s voor de database worden 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 context van de databases die door de use database opdracht is ingesteld. 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. Er zijn geen speciale tekens of spaties toegestaan.
offerThroughput	int	Optioneel	Ingerichte doorvoer die moet worden ingesteld voor de database. Als deze parameter niet is opgegeven, wordt deze standaard ingesteld op minimaal 400 RU/s. * Als u doorvoer wilt opgeven die hoger is dan 10.000 RU/s, is de shardKey parameter vereist.
shardKey	string	Vereist voor verzamelingen met grote doorvoer	Het pad naar de Shard-sleutel voor de shard-verzameling. Deze parameter is vereist als u meer dan 10.000 RU/s instelt in offerThroughput. Als deze is opgegeven, hebben alle ingevoegde documenten deze sleutel en waarde nodig.
autoScaleSettings	Object	Vereist voor de modus Automatisch schalen	Dit object bevat de instellingen die zijn gekoppeld aan de capaciteitsmodus voor automatisch schalen. U kunt de maxThroughput waarde instellen, waarin het hoogste aantal aanvraageenheden wordt beschreven dat de verzameling dynamisch kan worden verhoogd.
indexes	Array	Configureer eventueel indexen. Deze parameter wordt alleen ondersteund voor 3.6+ accounts.	Als deze aanwezig is, is een index op _id vereist. Elke vermelding in de matrix moet een sleutel bevatten van een of meer velden, een naam en kan indexopties bevatten. Als u bijvoorbeeld een samengestelde unieke index voor de velden a wilt maken 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 een aangepaste opdracht voor de parameters in de uitvoer.

Voorbeeld: Een verzameling maken met de minimale configuratie

Als u een nieuwe verzameling met een naam "testCollection" en de standaardwaarden wilt maken, 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 dat automatisch wordt gemaakt. Dit type configuratie is ook van toepassing bij het maken van nieuwe verzamelingen via de insert() functie. Voorbeeld:

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

Voorbeeld: Een niet-geharde verzameling maken

Gebruik de volgende opdracht om een niet-geharde verzameling te maken met de naam "testCollection" en ingerichte doorvoer van 1000 RU's:

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

U kunt een verzameling met maximaal 10.000 RU/s maken als de offerThroughput verzameling 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 de 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 meer dan 10.000 RU/s zijn opgegeven in de offerThroughput.

Voorbeeld: Een verzameling voor niet-geharde automatische schaalaanpassing maken

Gebruik de volgende opdracht om een niet-geharde verzameling te maken met de naam 'testCollection' die gebruikmaakt van doorvoercapaciteit voor automatische schaalaanpassing die is ingesteld op 4000 RU/s:

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

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

Voorbeeld: Een verzameling met sharding voor automatische schaalaanpassing maken

Gebruik de volgende opdracht om een shardverzameling met de naam 'testCollection' shardsleutel 'a.b'te maken en die gebruikmaakt van doorvoercapaciteit voor automatisch schalen ingesteld op 20.000 RU/s:

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

Verzameling bijwerken

Met de opdracht updateverzamelingsextensie worden de eigenschappen bijgewerkt die zijn gekoppeld aan de opgegeven verzameling. Het wijzigen van uw verzameling van ingerichte doorvoer in automatisch schalen en vice versa wordt alleen ondersteund in 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	Description
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 Automatisch schalen. Dit object bevat de instellingen die zijn gekoppeld aan de capaciteitsmodus voor automatisch schalen. De maxThroughput waarde beschrijft het hoogste aantal aanvraageenheden dat de verzameling dynamisch kan worden verhoogd.
indexes	Array	Configureer eventueel indexen. Deze parameter wordt alleen ondersteund voor 3.6+ accounts. Indien aanwezig, vervangt de set opgegeven 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 bevatten van een of meer velden, een naam 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 een 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

Met de aangepaste opdracht ophalen wordt het verzamelingsobject geretourneerd.

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

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

Veld	Type	Description
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	Description
ok	int	Status van antwoord. 1 == succes. 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 die moet worden ingesteld voor de verzameling. Dit veld is een optionele antwoordparameter.
autoScaleSettings	Object	Dit object bevat de capaciteitsparameters die aan de database zijn gekoppeld als het gebruikmaakt van de modus Automatisch schalen. De maxThroughput waarde beschrijft het hoogste aantal aanvraageenheden dat de verzameling dynamisch kan worden verhoogd.

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

Voorbeeld: De verzameling ophalen

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

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

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

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

Als de verzameling een gekoppelde doorvoer voor automatische schaalaanpassing heeft, bevat deze het autoScaleSettings object met de maxThroughput parameter, waarmee de maximale doorvoer wordt gedefinieerd die de verzameling dynamisch verhoogt. 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, hetzij 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
}

Wijzigingenstromen parallelliseren

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

Gebruik db.collection.watch() voor elk cv-token (één thread per token) om wijzigingenstromen 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/proces uit voor elk cv-token dat wordt geretourneerd met 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 curser voor alle documenten die zijn ingevoegd, bijgewerkt of vervangen door die fysieke partitie, omdat 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 wordt opgehaald van 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	Description
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.

Voorbeeld:

{ "ok" : 1 }

Volgende stappen

Hierna kunt u doorgaan met het leren van de volgende Concepten van Azure Cosmos DB:

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