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

VAN TOEPASSING OP: Azure Cosmos DB-API voor MongoDB

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

Met behulp van de API van de Azure Cosmos DB voor MongoDB kunt u profiteren van de voordelen van Cosmos DB zoals wereldwijde distributie, automatische sharding, hoge beschikbaarheid, latentiegaranties, automatische versleuteling in rust, back-ups en nog veel meer, terwijl uw investeringen in uw MongoDB-app behouden blijven. U kunt communiceren met de API Azure Cosmos DB mongoDB van de klant met behulp van een van de open-source MongoDB-clientst stuurprogramma's. De AZURE COSMOS DB api voor MongoDB maakt het gebruik van bestaande clientst stuurprogramma's mogelijk door zich te houden aan het MongoDB-wireprotocol.

MongoDB-protocolondersteuning

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

De volgende extensieopdrachten bieden de mogelijkheid om specifieke Azure Cosmos DB te maken en te wijzigen via databaseaanvragen:

• Database maken
• Database bijwerken
• Database op halen
• Verzameling maken
• Verzameling bijwerken
• Verzameling ophalen

Database maken

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

Uitvoer

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

{ "ok" : 1 }

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

Voorbeelden

Een database maken

Gebruik de volgende opdracht om een database met de naam te maken die "test" gebruikmaakt van alle standaardwaarden:

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

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

Een database met doorvoer maken

Gebruik de volgende opdracht om een database met de naam te maken en een inrichtende doorvoer op "test" databaseniveau van 1000 RUs op te geven:

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

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

Een database maken met doorvoer voor automatisch schalen

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

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 inrichtende doorvoer in automatisch schalen en omgekeerd wordt alleen ondersteund in Azure Portal. In de volgende tabel worden de parameters in de opdracht beschreven:

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

Uitvoer

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

{ "ok" : 1 }

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

Voorbeelden

De inrichtende doorvoer bijwerken die is gekoppeld aan een database

Gebruik de volgende opdracht om de inrichtende doorvoer van een database met de naam bij te werken "test" naar 1200 RUs:

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

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

Als u de inrichtende doorvoer van een database met de naam wilt bijwerken naar "test" 20.000 RUs of wilt transformeren naar een doorvoerniveau voor automatisch schalen, gebruikt u de volgende opdracht:

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

Database op halen

De database-extensie op te halen opdracht 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:

Uitvoer

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

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

Voorbeelden

De database op te halen

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

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

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

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

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

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

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

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

Verzameling maken

Met de opdracht verzamelingsextensie maken maakt u een nieuwe MongoDB-verzameling. 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:

Uitvoer

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

Voorbeelden

Een verzameling maken met de minimale configuratie

Gebruik de volgende opdracht om een nieuwe verzameling te maken met de naam en "testCollection" de standaardwaarden:

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

Dit 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 . Bijvoorbeeld:

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

Een niet-geharde verzameling maken

Gebruik de volgende opdracht om een niet-geharde verzameling te maken met een naam en een inrichtende doorvoer van "testCollection" 1000 RUs:

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

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

Een shard-verzameling maken

Gebruik de volgende opdracht om een shard-verzameling te maken met een naam en een inrichtende doorvoer van "testCollection" 11.000 RUs en een eigenschap shardkey 'a.b':

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

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

Een niet-geharde verzameling voor automatisch schalen maken

Gebruik de volgende opdracht om een niet-geharde verzameling te maken met de naam die gebruikmaakt van de capaciteit voor automatische schaalsets van doorvoer op 'testCollection' 4000 RU/s:

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

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

Een verzameling voor automatisch schalen met sharding maken

Gebruik de volgende opdracht om een shard-verzameling met de naam te maken met een shardsleutel met de naam , en die gebruikmaakt van de capaciteit voor automatische schaalschalen die is ingesteld op 'testCollection' 'a.b' 20.000 RU/s:

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 inrichtende doorvoer in automatisch schalen en omgekeerd 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:

Uitvoer

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

Voorbeelden

De inrichtende doorvoer bijwerken die is gekoppeld aan een verzameling

Gebruik de volgende opdracht om de inrichtende doorvoer van een verzameling met de naam bij te werken "testCollection" naar 1200 RUs:

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

Verzameling ophalen

De aangepaste opdracht verzameling ophalen retourneert het verzamelingsobject.

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

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

Uitvoer

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

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

Voorbeelden

De verzameling ophalen

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

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

Als de verzameling een gekoppelde doorvoercapaciteit heeft, bevat deze de waarde provisionedThroughput 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 -object met de parameter , waarmee de maximale doorvoer wordt bepaald die de verzameling autoScaleSettings maxThroughput dynamisch zal verhogen. Daarnaast bevat deze ook de waarde , die de minimale doorvoer definieert waarmee deze verzameling wordt beperkt tot als er geen provisionedThroughput aanvragen in de verzameling zijn:

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

Als de verzameling doorvoer op databaseniveaudeelt, 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
}

Wijzigingsstromen parallelliseren

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

Door db.collection.watch() aan te roepen op elk hervatten-token (één thread per token), worden wijzigingsstromen efficiënt geschaald.

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

Voorbeeld

Voer de aangepaste opdracht uit om een hervatten-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 hervatten-token dat wordt geretourneerd door de aangepaste getChangeStreamTokens-opdracht. Hieronder vindt u 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 hervatten-token. watch() retourneert een kiezer voor alle documenten die zijn ingevoegd, bijgewerkt of vervangen door die fysieke partitie sinds de aangepaste getChangeStreamTokens-opdracht is uitgevoerd. Hieronder 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 hervatten-token (ze zijn allemaal hetzelfde voor elke pagina). Dit hervatten-token moet worden opgeslagen en opnieuw worden gebruikt als de thread/het proces is uitgevallen. Dit hervatten-token wordt opgehaald vanaf de locatie 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:

Bijvoorbeeld:

{ "ok" : 1 }

Volgende stappen

U kunt nu doorgaan met het leren van de volgende Azure Cosmos DB concepten:

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