Använda MongoDB-tilläggskommandon för att hantera data som lagras Azure Cosmos DB i API:et för MongoDB

GÄLLER FÖR: Azure Cosmos DB API för MongoDB

Följande dokument innehåller de anpassade åtgärdskommandon som är specifika för Azure Cosmos DB API för MongoDB. Dessa kommandon kan användas för att skapa och hämta databasresurser som är specifika för Azure Cosmos DB kapacitetsmodellen.

Genom att använda API:et för Azure Cosmos DB för MongoDB kan du dra nytta av fördelarna med Cosmos DB som global distribution, automatisk horisontell partitionering, hög tillgänglighet, svarstidsgarantier, automatisk kryptering i vila, säkerhetskopieringar med mera, samtidigt som du behåller dina investeringar i MongoDB-appen. Du kan kommunicera med Azure Cosmos DB API för MongoDB med någon av MongoDB-klientdrivrutinerna med öppen källkod. Med Azure Cosmos DB-API:et för MongoDB kan du använda befintliga klientdrivrutiner genom att följa MongoDB-trådprotokollet.

Protokollstöd för MongoDB

Azure Cosmos DB API för MongoDB är kompatibelt med MongoDB-serverversion 4.0, 3.6 och 3.2. Mer information finns i funktioner och syntax som stöds i artiklarna 4.0, 3.6 och 3.2.

Följande tilläggskommandon ger möjlighet att skapa och ändra Azure Cosmos DB specifika resurser via databasbegäranden:

Skapa databas

Kommandot för att skapa databastillägg skapar en ny MongoDB-databas. Databasnamnet kan användas från databaskontexten som anges av use database kommandot . I följande tabell beskrivs parametrarna i kommandot :

Fält Typ Beskrivning
customAction string Namnet på det anpassade kommandot måste vara "CreateDatabase".
offerThroughput int Etablerat dataflöde som du anger i databasen. Den här parametern är valfri.
autoScaleSettings Object Krävs för autoskalningsläge. Det här objektet innehåller inställningarna som är associerade med kapacitetsläget för autoskalning. Du kan ställa in maxThroughput värdet, som beskriver den högsta mängden enheter för begäran som samlingen ökas till dynamiskt.

Utdata

Om kommandot lyckas returneras följande svar:

{ "ok" : 1 }

Se standardutdata för anpassat kommando för parametrarna i utdata.

Exempel

Skapa en databas

Om du vill skapa en databas "test" med namnet som använder alla standardvärden använder du följande kommando:

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

Det här kommandot skapar en databas utan dataflöde på databasnivå. Det innebär att samlingarna i den här databasen måste ange hur mycket dataflöde du behöver använda.

Skapa en databas med dataflöde

Om du vill skapa en databas "test" med namnet och "test" ange ett etablerat dataflöde på databasnivå på 1 000 RU:er använder du följande kommando:

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

Detta skapar en databas och anger ett dataflöde till den. Alla samlingar i den här databasen delar det inställda dataflödet, såvida inte samlingarna skapas med en specifik dataflödesnivå.

Skapa en databas med dataflöde för autoskalning

Om du vill skapa en "test" databas med namnet och ange ett maximalt dataflöde för autoskalning på 20 000 RU/s på "test" använder du följande kommando:

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

Uppdatera databas

Kommandot uppdatera databastillägg uppdaterar egenskaperna som är associerade med den angivna databasen. Att ändra databasen från etablerat dataflöde till autoskalning och vice versa stöds endast i Azure-portalen. I följande tabell beskrivs parametrarna i kommandot :

Fält Typ Beskrivning
customAction string Namnet på det anpassade kommandot. Måste vara "UpdateDatabase".
offerThroughput int Nytt etablerat dataflöde som du vill ange för databasen om databasen använder dataflöde på databasnivå
autoScaleSettings Object Krävs för autoskalningsläge. Det här objektet innehåller inställningarna som är associerade med kapacitetsläget för autoskalning. Du kan ställa in maxThroughput värdet, som beskriver den högsta mängden enheter för begäran som databasen ökas till dynamiskt.

Det här kommandot använder den databas som anges i kontexten för sessionen. Det här är den databas som du använde i use <database> kommandot . Databasnamnet kan för tillfället inte ändras med det här kommandot.

Utdata

Om kommandot lyckas returneras följande svar:

{ "ok" : 1 }

Se standardutdata för anpassat kommando för parametrarna i utdata.

Exempel

Uppdatera det etablerade dataflödet som är associerat med en databas

Om du vill uppdatera det etablerade dataflödet för en databas med namnet "test" till 1200 RU:er använder du följande kommando:

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

Uppdatera dataflödet för autoskalning som är associerat med en databas

Om du "test" vill uppdatera det etablerade dataflödet för en databas med namnet till 20 000 RU:er, eller omvandla det till en dataflödesnivå för automatisk skalning "test" du följande kommando:

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

Hämta databas

Kommandot get database extension returnerar databasobjektet. Databasnamnet används från databaskontexten som kommandot körs mot.

{
  customAction: "GetDatabase"
}

I följande tabell beskrivs parametrarna i kommandot :

Fält Typ Beskrivning
customAction string Namnet på det anpassade kommandot. Måste vara "GetDatabase"

Utdata

Om kommandot lyckas innehåller svaret ett dokument med följande fält:

Fält Typ Beskrivning
ok int Status för svar. 1 == lyckades. 0 == fel.
database string Namnet på databasen.
provisionedThroughput int Etablerat dataflöde som anges på databasen om databasen använder manuellt dataflöde på databasnivå
autoScaleSettings Object Det här objektet innehåller kapacitetsparametrarna som är associerade med databasen om den använder autoskalningsläget. Värdet maxThroughput beskriver den högsta mängden enheter för begäran som databasen ökas till dynamiskt.

Om kommandot misslyckas returneras ett anpassat standardkommandosvar. Se standardutdata för anpassat kommando för parametrarna i utdata.

Exempel

Hämta databasen

Om du vill hämta databasobjektet för en databas med "test"namnet använder du följande kommando:

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

Om databasen inte har något associerat dataflöde blir utdata:

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

Om databasen har ett manuellt dataflöde på databasnivå associerat visar utdata värdena :

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

Om databasen har ett kopplat dataflöde för automatisk skalning på databasnivå visar utdata , som beskriver minsta RU/s autoScaleSettingsmaxThroughputför databasen och objektet inklusive , som beskriver maximalt antal RU:er för databasen.

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

Skapa samling

Kommandot create collection extension skapar en ny MongoDB-samling. Databasnamnet används från databaskontexten som anges av use database kommandot . Formatet för kommandot CreateCollection är följande:

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

I följande tabell beskrivs parametrarna i kommandot:

Fält Typ Obligatoriskt Beskrivning
customAction string Obligatorisk Namnet på det anpassade kommandot. Måste vara "CreateCollection".
collection string Obligatorisk Namnet på samlingen. Inga specialtecken eller blanksteg tillåts.
offerThroughput int Valfritt Etablerat dataflöde som ska anges för databasen. Om den här parametern inte anges är standardvärdet 400 RU/s. * Parametern krävs för att ange ett dataflöde över 10 000 RU/s shardKey .
shardKey string Krävs för samlingar med stort dataflöde Sökvägen till Shard-nyckeln för den fragmenterade samlingen. Den här parametern krävs om du anger mer än 10 000 RU/s i offerThroughput. Om den anges kräver alla dokument som infogas den här nyckeln och värdet.
autoScaleSettings Object Krävs för autoskalningsläge Det här objektet innehåller inställningarna som är associerade med kapacitetsläget autoskalning. Du kan ställa in maxThroughput värdet, som beskriver den högsta mängden enheter för begäran som samlingen ska ökas till dynamiskt.
indexes Array Du kan också konfigurera index. Den här parametern stöds endast för 3.6+-konton. När det finns krävs ett _id index. Varje post i matrisen måste innehålla en nyckel med ett eller flera fält, ett namn och kan innehålla indexalternativ. Om du till exempel vill skapa ett sammansatt unikt index för fälten och använda ab den här posten: {key: {a: 1, b: 1}, name:"a_1_b_1", unique: true}.

Utdata

Returnerar ett anpassat standardkommandosvar. Se standardutdata för anpassat kommando för parametrarna i utdata.

Exempel

Skapa en samling med minsta konfiguration

Om du vill skapa en ny samling med "testCollection" namn och standardvärden använder du följande kommando:

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

Detta resulterar i en ny fast, oskadd samling med 400RU/s och ett index på fältet _id som skapas automatiskt. Den här typen av konfiguration gäller även när du skapar nya samlingar via insert() funktionen . Till exempel:

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

Skapa en oskadd samling

Om du vill skapa en oskadd "testCollection" samling med namn och etablerat dataflöde på 1 000 RU:er använder du följande kommando:

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

Du kan skapa en samling med upp till 10 000 RU/s offerThroughput som utan att behöva ange en shardnyckel. För samlingar med större dataflöde kan du titta på nästa avsnitt.

Skapa en fragmenterad samling

Om du vill skapa en fragmenterad "testCollection" samling med namn och etablerat dataflöde på 11 000 shardkey RU:er och egenskapen "a.b" använder du följande kommando:

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

Det här kommandot kräver nu shardKey parametern eftersom mer än 10 000 RU/s anges i offerThroughput.

Skapa en unsharded Autoscale-samling

Om du vill skapa en oskadd 'testCollection' samling med 'testCollection' namnet som använder dataflödeskapacitet för autoskalning inställd på 4 000 RU/s använder du följande kommando:

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

För värdet autoScaleSettings.maxThroughput kan du ange ett intervall från 4 000 RU/s till 10 000 RU/s utan en shardnyckel. För högre dataflöde för autoskalning måste du ange shardKey parametern .

Skapa en fragmenterad autoskalningssamling

Om du vill skapa en fragmenterad 'testCollection' samling med namnet med en shardnyckel 'testCollection''a.b'med namnet och som använder dataflödeskapacitet för automatisk skalning inställd på 20 000 RU/s använder du följande kommando:

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

Uppdatera samling

Kommandot uppdatera samlingstillägg uppdaterar egenskaperna som är associerade med den angivna samlingen. Att ändra din samling från etablerat dataflöde till autoskalning och vice versa stöds endast i Azure-portalen.

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

I följande tabell beskrivs parametrarna i kommandot:

Fält Typ Beskrivning
customAction string Namnet på det anpassade kommandot. Måste vara "UpdateCollection".
collection string Namnet på samlingen.
offerThroughput int Etablerat dataflöde som ska anges för samlingen.
autoScaleSettings Object Krävs för autoskalningsläge. Det här objektet innehåller inställningarna som är associerade med kapacitetsläget autoskalning. Värdet maxThroughput beskriver den högsta mängden enheter för begäran som samlingen kommer att ökas till dynamiskt.
indexes Array Du kan också konfigurera index. Den här parametern stöds endast för 3.6+-konton. När det finns ersätts de befintliga indexen i samlingen med den angivna uppsättningen index (inklusive att släppa index). Ett index på _id krävs. Varje post i matrisen måste innehålla en nyckel med ett eller flera fält, ett namn och kan innehålla indexalternativ. Om du till exempel vill skapa ett sammansatt unikt index i fälten a och b använder du den här posten: {key: {a: 1, b: 1}, name: "a_1_b_1", unique: true}.

Utdata

Returnerar ett anpassat standardkommandosvar. Se standardutdata för anpassat kommando för parametrarna i utdata.

Exempel

Uppdatera det etablerade dataflödet som är associerat med en samling

Om du vill uppdatera det etablerade dataflödet för en samling med namnet "testCollection" till 1200 RU:er använder du följande kommando:

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

Hämta samling

Kommandot get collection custom returnerar samlingsobjektet.

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

I följande tabell beskrivs parametrarna i kommandot:

Fält Typ Beskrivning
customAction string Namnet på det anpassade kommandot. Måste vara "GetCollection".
collection string Namnet på samlingen.

Utdata

Om kommandot lyckas innehåller svaret ett dokument med följande fält

Fält Typ Beskrivning
ok int Status för svar. 1 == lyckades. 0 == fel.
database string Namnet på databasen.
collection string Namnet på samlingen.
shardKeyDefinition document Dokument om indexspecifikation som används som en shardnyckel. Det här är en valfri svarsparameter.
provisionedThroughput int Etablerat dataflöde som ska anges för samlingen. Det här är en valfri svarsparameter.
autoScaleSettings Object Det här objektet innehåller kapacitetsparametrarna som är associerade med databasen om det använder autoskalningsläget. Värdet maxThroughput beskriver den högsta mängden enheter för begäran som samlingen kommer att ökas till dynamiskt.

Om kommandot misslyckas returneras ett anpassat standardkommandosvar. Se standardutdata för anpassat kommando för parametrarna i utdata.

Exempel

Hämta samlingen

Om du vill hämta samlingsobjektet för en samling med "testCollection"namnet använder du följande kommando:

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

Om samlingen har en associerad dataflödeskapacitet inkluderar den värdet provisionedThroughput och utdata blir:

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

Om samlingen har ett associerat dataflöde autoScaleSettingsmaxThroughput för autoskalning inkluderar den objektet med parametern , som definierar det maximala dataflödet som samlingen ökar till dynamiskt. Dessutom innehåller den även värdet , som provisionedThroughput definierar det minsta dataflöde som samlingen minskar till om det inte finns några begäranden i samlingen:

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

Om samlingen delar dataflödet på databasnivå, antingen i autoskalningsläge eller manuellt, blir utdata:

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

Parallellisera ändringsströmmar

När du använder ändringsströmmar i stor skala är det bäst att sprida belastningen jämnt. Följande kommando returnerar en eller flera återställningstoken för ändringsströmmen – var och en motsvarar data från en enda fysisk shard/partition (flera logiska shards/partitioner kan finnas på en fysisk partition). Varje återuppta token gör att watch() endast returnerar data från den fysiska sharden/partitionen.

Om du anropar db.collection.watch() på varje återuppta-token (en tråd per token) skalas ändringsströmmarna effektivt.

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

Exempel

Kör det anpassade kommandot för att hämta en återuppta-token för varje fysisk shard/partition.

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

Kör en watch()-tråd/process för varje återuppta token som returneras från det anpassade kommandot GetChangeStreamTokens. Nedan visas ett exempel på en tråd.

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

Dokumentet (värdet) i fältet resumeAfter representerar token för återuppta. watch() returnerar en -växlare för alla dokument som har infogats, uppdaterats eller ersatts från den fysiska partitionen sedan det anpassade kommandot GetChangeStreamTokens har körts. Ett exempel på de data som returneras visas nedan.

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

Observera att varje dokument som returneras innehåller en återuppta-token (de är likadana för varje sida). Denna återuppta-token ska lagras och återanvändas om tråden/processen slider. Denna återuppta-token hämtas där du slutade och tar bara emot data från den fysiska partitionen.

Standardutdata för ett anpassat kommando

Om inget anges innehåller ett anpassat svar ett dokument med följande fält:

Fält Typ Beskrivning
ok int Status för svar. 1 == lyckades. 0 == fel.
code int Returneras endast när kommandot misslyckades (dvs. ok == 0). Innehåller MongoDB-felkoden. Det här är en valfri svarsparameter.
errMsg string Returneras endast när kommandot misslyckades (dvs. ok == 0). Innehåller ett användarvänligt felmeddelande. Det här är en valfri svarsparameter.

Till exempel:

{ "ok" : 1 }

Nästa steg

Härnäst kan du gå vidare och lära dig följande Azure Cosmos DB begrepp: