Usare i comandi dell'estensione MongoDB per gestire i dati archiviati nell'API Azure Cosmos DB per MongoDB

Articolo
11/29/2022
14 minuti per la lettura

SI APPLICA A: Mongodb

Il documento seguente contiene i comandi di azione personalizzati specifici dell'API di Azure Cosmos DB per MongoDB. Questi comandi possono essere usati per creare e ottenere risorse di database specifiche per il modello di capacità di Azure Cosmos DB.

Usando l'API di Azure Cosmos DB per MongoDB, è possibile sfruttare i vantaggi offerti da Azure Cosmos DB, ad esempio la distribuzione globale, il partizionamento orizzontale automatico, la disponibilità elevata, le garanzie di latenza, la crittografia automatica dei dati inattivi, i backup e molti altri, mantenendo al tempo stesso gli investimenti nell'app MongoDB. È possibile comunicare con l'API di Azure Cosmos DB per MongoDB usando uno dei driver client MongoDB open source. L'API di Azure Cosmos DB per MongoDB consente l'uso dei driver client esistenti rispettando il protocollo di collegamento MongoDB.

Supporto del protocollo MongoDB

L'API di Azure Cosmos DB per MongoDB è compatibile con il server MongoDB versione 4.0, 3.6 e 3.2. Per altre informazioni, vedere le funzionalità e la sintassi supportate negli articoli 4.0, 3.6 e 3.2 .

I comandi di estensione seguenti consentono di creare e modificare risorse specifiche di Azure Cosmos DB tramite richieste di database:

Creare un database
Aggiornare il database
Recupera database
Crea raccolta
Aggiorna raccolta
Recupera una raccolta

Creazione del database

Il comando create database extension crea un nuovo database MongoDB. Il nome del database può essere usato dal contesto del database impostato dal use database comando . Nella tabella seguente vengono descritti i parametri all'interno del comando :

Campo	Tipo	Descrizione
`customAction`	`string`	Il nome del comando personalizzato deve essere "CreateDatabase".
`offerThroughput`	`int`	Velocità effettiva con provisioning impostata nel database. Questo parametro è facoltativo e,
`autoScaleSettings`	`Object`	Obbligatorio per la modalità di scalabilità automatica. Questo oggetto contiene le impostazioni associate alla modalità capacità di scalabilità automatica. È possibile impostare il `maxThroughput` valore , che descrive la quantità più elevata di unità richiesta che la raccolta verrà aumentata in modo dinamico.

Output

Se il comando ha esito positivo, restituirà la risposta seguente:

{ "ok" : 1 }

Vedere l'output predefinito del comando personalizzato per i parametri nell'output.

Esempi

Creazione di un database

Per creare un database denominato "test" che usa tutti i valori predefiniti, usare il comando seguente:

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

Questo comando creerà un database senza velocità effettiva a livello di database. Ciò significa che le raccolte all'interno di questo database dovranno specificare la quantità di velocità effettiva che è necessario usare.

Creare un database con velocità effettiva

Per creare un database denominato "test" e per specificare una velocità effettiva con provisioning a livello di database di 1000 UR, usare il comando seguente:

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

Verrà creato un database e verrà impostata una velocità effettiva. Tutte le raccolte all'interno di questo database condivideranno la velocità effettiva impostata, a meno che le raccolte non vengano create con un livello di velocità effettiva specifico.

Creare un database con velocità effettiva con scalabilità automatica

Per creare un database denominato "test" e per specificare una velocità effettiva massima di scalabilità automatica di 20.000 UR/sec a livello di database, usare il comando seguente:

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

Aggiornare il database

Il comando update database extension aggiorna le proprietà associate al database specificato. La modifica del database dalla velocità effettiva con provisioning alla scalabilità automatica e viceversa è supportata solo nel portale di Azure. Nella tabella seguente vengono descritti i parametri all'interno del comando :

Campo	Tipo	Descrizione
`customAction`	`string`	Nome del comando personalizzato. Deve essere "UpdateDatabase".
`offerThroughput`	`int`	Nuova velocità effettiva con provisioning che si vuole impostare nel database se il database usa la velocità effettiva a livello di database
`autoScaleSettings`	`Object`	Obbligatorio per la modalità di scalabilità automatica. Questo oggetto contiene le impostazioni associate alla modalità capacità di scalabilità automatica. È possibile impostare il `maxThroughput` valore , che descrive la quantità più elevata di unità richiesta che il database verrà aumentato in modo dinamico.

Questo comando usa il database specificato nel contesto della sessione. Si tratta del database usato nel use <database> comando . Al momento, il nome del database non può essere modificato usando questo comando.

Output

Se il comando ha esito positivo, restituirà la risposta seguente:

{ "ok" : 1 }

Vedere l'output predefinito del comando personalizzato per i parametri nell'output.

Esempi

Aggiornare la velocità effettiva con provisioning associata a un database

Per aggiornare la velocità effettiva con provisioning di un database con nome "test" a 1200 UR, usare il comando seguente:

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

Aggiornare la velocità effettiva di scalabilità automatica associata a un database

Per aggiornare la velocità effettiva con provisioning di un database con nome "test" a 20.000 UR o per trasformarla in un livello di velocità effettiva con scalabilità automatica, usare il comando seguente:

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

Recupera database

Il comando get database extension restituisce l'oggetto di database. Il nome del database viene usato dal contesto del database in base al quale viene eseguito il comando.

{
  customAction: "GetDatabase"
}

Nella tabella seguente vengono descritti i parametri all'interno del comando :

Campo	Tipo	Descrizione
`customAction`	`string`	Nome del comando personalizzato. Deve essere "GetDatabase"

Output

Se il comando ha esito positivo, la risposta contiene un documento con i campi seguenti:

Campo	Tipo	Descrizione
`ok`	`int`	Stato della risposta. 1 == esito positivo. 0 == errore.
`database`	`string`	Nome del database.
`provisionedThroughput`	`int`	Velocità effettiva con provisioning impostata nel database se il database usa una velocità effettiva manuale a livello di database
`autoScaleSettings`	`Object`	Questo oggetto contiene i parametri di capacità associati al database se usa la modalità di scalabilità automatica. Il `maxThroughput` valore descrive la quantità più elevata di unità richiesta che il database verrà aumentato in modo dinamico.

Se il comando ha esito negativo, viene restituita una risposta di comando personalizzata predefinita. Vedere l'output predefinito del comando personalizzato per i parametri nell'output.

Esempi

Ottenere il database

Per ottenere l'oggetto di database per un database denominato "test", usare il comando seguente:

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

Se il database non ha alcuna velocità effettiva associata, l'output sarà:

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

Se al database è associata una velocità effettiva manuale a livello di database , l'output mostrerà i provisionedThroughput valori:

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

Se al database è associata una velocità effettiva di scalabilità automatica a livello di database , l'output mostrerà provisionedThroughput, che descrive le UR/sec minime per il database e l'oggetto autoScaleSettings che include maxThroughput, che descrive il numero massimo di UR/sec per il database.

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

Crea raccolta

Il comando create collection extension crea una nuova raccolta MongoDB. Il nome del database viene usato dal contesto dei database impostato dal use database comando . Il formato del comando CreateCollection è il seguente:

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

Nella tabella seguente vengono descritti i parametri all'interno del comando :

Campo	Tipo	Obbligatorio	Descrizione
`customAction`	`string`	Necessario	Nome del comando personalizzato. Deve essere "CreateCollection".
`collection`	`string`	Necessario	Nome della raccolta. Non sono consentiti caratteri o spazi speciali.
`offerThroughput`	`int`	Facoltativo	Velocità effettiva con provisioning da impostare nel database. Se questo parametro non viene specificato, per impostazione predefinita verrà impostato il valore minimo, 400 UR/sec. * Per specificare la velocità effettiva superiore a 10.000 UR/sec, è necessario il `shardKey` parametro .
`shardKey`	`string`	Obbligatorio per le raccolte con velocità effettiva elevata	Percorso della chiave di partizione per la raccolta partizionata. Questo parametro è obbligatorio se si impostano più di 10.000 UR/sec in `offerThroughput`. Se viene specificato, tutti i documenti inseriti richiederanno questa chiave e il valore.
`autoScaleSettings`	`Object`	Obbligatorio per la modalità di scalabilità automatica	Questo oggetto contiene le impostazioni associate alla modalità capacità di scalabilità automatica. È possibile impostare il `maxThroughput` valore , che descrive la quantità più elevata di unità richiesta che la raccolta verrà aumentata in modo dinamico.
`indexes`	`Array`	Facoltativamente, configurare gli indici. Questo parametro è supportato solo per gli account 3.6+.	Se presente, è necessario un indice in _id. Ogni voce nella matrice deve includere una chiave di uno o più campi, un nome e può contenere opzioni di indice. Ad esempio, per creare un indice univoco composto nei campi `a` e `b` usare questa voce: `{key: {a: 1, b: 1}, name:"a_1_b_1", unique: true}`.

Output

Restituisce una risposta di comando personalizzata predefinita. Vedere l'output predefinito del comando personalizzato per i parametri nell'output.

Esempi

Creare una raccolta con la configurazione minima

Per creare una nuova raccolta con nome "testCollection" e i valori predefiniti, usare il comando seguente:

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

Ciò comporterà una nuova raccolta fissa, non partizionata, con 400RU/s e un indice sul _id campo creato automaticamente. Questo tipo di configurazione verrà applicato anche quando si creano nuove raccolte tramite la insert() funzione . Ad esempio:

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

Creare una raccolta non partizionata

Per creare una raccolta non partizionata con nome "testCollection" e velocità effettiva con provisioning di 1000 UR, usare il comando seguente:

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

È possibile creare una raccolta con un massimo di 10.000 UR/sec come offerThroughput senza dover specificare una chiave di partizione. Per le raccolte con una velocità effettiva maggiore, vedere la sezione successiva.

Creare una raccolta partizionata

Per creare una raccolta partizionata con nome "testCollection" e velocità effettiva con provisioning di 11.000 UR e una shardkey proprietà "a.b", usare il comando seguente:

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

Questo comando richiede ora il shardKey parametro , poiché più di 10.000 UR/s specificate in offerThroughput.

Creare una raccolta di scalabilità automatica non partizionata

Per creare una raccolta non partizionata denominata 'testCollection' che usa la capacità di velocità effettiva con scalabilità automatica impostata su 4.000 UR/sec, usare il comando seguente:

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

Per il autoScaleSettings.maxThroughput valore è possibile specificare un intervallo compreso tra 4.000 UR/sec e 10.000 UR/sec senza una chiave di partizione. Per una velocità effettiva con scalabilità automatica più elevata, è necessario specificare il shardKey parametro .

Creare una raccolta di scalabilità automatica partizionata

Per creare una raccolta partizionata denominata 'testCollection' con una chiave di partizione denominata 'a.b'e che usa la capacità di velocità effettiva con scalabilità automatica impostata su 20.000 UR/sec, usare il comando seguente:

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

Aggiorna raccolta

Il comando update collection extension aggiorna le proprietà associate alla raccolta specificata. La modifica della raccolta dalla velocità effettiva con provisioning alla scalabilità automatica e viceversa è supportata solo nel portale di Azure.

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

Nella tabella seguente vengono descritti i parametri all'interno del comando :

Campo	Tipo	Descrizione
`customAction`	`string`	Nome del comando personalizzato. Deve essere "UpdateCollection".
`collection`	`string`	Nome della raccolta.
`offerThroughput`	`int`	Velocità effettiva con provisioning da impostare nella raccolta.
`autoScaleSettings`	`Object`	Obbligatorio per la modalità di scalabilità automatica. Questo oggetto contiene le impostazioni associate alla modalità capacità di scalabilità automatica. Il `maxThroughput` valore descrive la quantità più elevata di unità richiesta che l'insieme verrà aumentato in modo dinamico.
`indexes`	`Array`	Facoltativamente, configurare gli indici. Questo parametro è supportato solo per gli account 3.6+. Se presente, gli indici esistenti dell'insieme vengono sostituiti dal set di indici specificato (inclusa l'eliminazione degli indici). È necessario un indice in _id. Ogni voce nella matrice deve includere una chiave di uno o più campi, un nome e può contenere opzioni di indice. Ad esempio, per creare un indice univoco composto nei campi a e b usare questa voce: `{key: {a: 1, b: 1}, name: "a_1_b_1", unique: true}`.

Output

Restituisce una risposta di comando personalizzata predefinita. Vedere l'output predefinito del comando personalizzato per i parametri nell'output.

Esempi

Aggiornare la velocità effettiva con provisioning associata a una raccolta

Per aggiornare la velocità effettiva con provisioning di una raccolta con nome "testCollection" a 1200 UR, usare il comando seguente:

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

Recupera una raccolta

Il comando personalizzato get collection restituisce l'oggetto raccolta.

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

Nella tabella seguente vengono descritti i parametri all'interno del comando :

Campo	Tipo	Descrizione
`customAction`	`string`	Nome del comando personalizzato. Deve essere "GetCollection".
`collection`	`string`	Nome della raccolta.

Output

Se il comando ha esito positivo, la risposta contiene un documento con i campi seguenti

Campo	Tipo	Descrizione
`ok`	`int`	Stato della risposta. 1 == esito positivo. 0 == errore.
`database`	`string`	Nome del database.
`collection`	`string`	Nome della raccolta.
`shardKeyDefinition`	`document`	Documento di specifica dell'indice usato come chiave di partizione. Si tratta di un parametro di risposta facoltativo.
`provisionedThroughput`	`int`	Velocità effettiva di cui è stato effettuato il provisioning per impostare la raccolta. Si tratta di un parametro di risposta facoltativo.
`autoScaleSettings`	`Object`	Questo oggetto contiene i parametri di capacità associati al database se usa la modalità di scalabilità automatica. Il `maxThroughput` valore descrive la quantità più elevata di Unità richiesta che la raccolta verrà aumentata in modo dinamico.

Se il comando ha esito negativo, viene restituita una risposta di comando personalizzata predefinita. Vedere l'output predefinito del comando personalizzato per i parametri nell'output.

Esempi

Ottenere la raccolta

Per ottenere l'oggetto raccolta per una raccolta denominata "testCollection", usare il comando seguente:

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

Se la raccolta ha una capacità di velocità effettiva associata, includerà il provisionedThroughput valore e l'output sarà:

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

Se la raccolta ha una velocità effettiva di scalabilità automatica associata, includerà l'oggetto con il autoScaleSettingsmaxThroughput parametro, che definisce la velocità effettiva massima che la raccolta aumenterà in modo dinamico. Inoltre, includerà anche il provisionedThroughput valore, che definisce la velocità effettiva minima che questa raccolta ridurrà a se non sono presenti richieste nella raccolta:

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

Se la raccolta condivide la velocità effettiva a livello di database, in modalità di scalabilità automatica o manuale, l'output sarà:

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

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

Parallelizzazione dei flussi di modifica

Quando si usano flussi di modifica su larga scala, è preferibile distribuire in modo uniforme il carico. Il comando seguente restituirà uno o più token di ripresa del flusso di modifica, ognuno corrispondente ai dati da una singola partizione/partizione fisica (più partizioni/partizioni logiche possono esistere in una partizione fisica). Ogni token di ripresa causerà la restituzione dei dati solo da tale partizione/partizione fisica.

La chiamata di db.collection.watch() a ogni token di ripresa (un thread per token), ridimensiona i flussi di modifica in modo efficiente.

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

Esempio

Eseguire il comando personalizzato per ottenere un token di ripresa per ogni partizione/partizione fisica.

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

Eseguire un thread/processo watch() per ogni token di ripresa restituito dal comando personalizzato GetChangeStreamTokens. Di seguito è riportato un esempio per un 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)}})

Il documento (valore) nel campo resumeAfter rappresenta il token di ripresa. watch() restituirà un maledetto per tutti i documenti inseriti, aggiornati o sostituiti da tale partizione fisica dopo l'esecuzione del comando personalizzato GetChangeStreamTokens. Di seguito è riportato un esempio dei dati restituiti.

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

Si noti che ogni documento restituito include un token di ripresa (sono tutti uguali per ogni pagina). Questo token di ripresa deve essere archiviato e riutilizzato se il thread/processo muore. Questo token di ripresa riceverà da dove è stato lasciato e riceverà i dati solo da tale partizione fisica.

Output predefinito di un comando personalizzato

Se non specificato, una risposta personalizzata contiene un documento con i campi seguenti:

Campo	Tipo	Descrizione
`ok`	`int`	Stato della risposta. 1 == successo. 0 == errore.
`code`	`int`	Restituito solo quando il comando non è riuscito (ad esempio ok == 0). Contiene il codice di errore MongoDB. Si tratta di un parametro di risposta facoltativo.
`errMsg`	`string`	Restituito solo quando il comando non è riuscito (ad esempio ok == 0). Contiene un messaggio di errore descrittivo. Si tratta di un parametro di risposta facoltativo.

Ad esempio:

{ "ok" : 1 }

Passaggi successivi

È quindi possibile procedere per informazioni sui concetti seguenti di Azure Cosmos DB:

Usare i comandi dell'estensione MongoDB per gestire i dati archiviati nell'API Azure Cosmos DB per MongoDB

Supporto del protocollo MongoDB

Creazione del database

Output

Esempi

Creazione di un database

Creare un database con velocità effettiva

Creare un database con velocità effettiva con scalabilità automatica

Aggiornare il database

Output

Esempi

Aggiornare la velocità effettiva con provisioning associata a un database

Aggiornare la velocità effettiva di scalabilità automatica associata a un database

Recupera database

Output

Esempi

Ottenere il database

Crea raccolta

Output

Esempi

Creare una raccolta con la configurazione minima

Creare una raccolta non partizionata

Creare una raccolta partizionata

Creare una raccolta di scalabilità automatica non partizionata

Creare una raccolta di scalabilità automatica partizionata

Aggiorna raccolta

Output

Esempi

Aggiornare la velocità effettiva con provisioning associata a una raccolta

Recupera una raccolta

Output

Esempi

Ottenere la raccolta

Parallelizzazione dei flussi di modifica

Esempio

Output predefinito di un comando personalizzato

Passaggi successivi

Risorse aggiuntive

Risorse aggiuntive