Usare i comandi di estensione MongoDB per gestire i dati archiviati in Azure Cosmos DB for MongoDB

SI APPLICA A: MongoDB

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

Usando Azure Cosmos DB for MongoDB, è possibile sfruttare i vantaggi condivisi di Azure Cosmos DB, che includono, ad esempio:

• Distribuzione globale
• Partizionamento orizzontale automatico
• Disponibilità elevata
• Garanzie di latenza
• Crittografia dei dati inattivi
• Backup

È possibile usufruire di questi vantaggi mantenendo al tempo stesso gli investimenti nelle applicazioni MongoDB esistenti. È possibile comunicare con Azure Cosmos DB for MongoDB usando uno dei driver client MongoDB open source. L'API Azure Cosmos DB for MongoDB consente di usare driver client esistenti aderendo al protocollo di collegamento MongoDB.

Supporto del protocollo MongoDB

Azure Cosmos DB for MongoDB è compatibile con le versioni 4.0, 3.6 e 3.2 del server MongoDB. Per altre informazioni, vedere Funzionalità supportate e sintassi per le versioni 4.0, 3.6 e 3.2.

I comandi di estensione seguenti creano e modificano le risorse specifiche di Azure Cosmos DB tramite richieste di database:

• CreateDatabase
• UpdateDatabase
• GetDatabase
• CreateCollection
• UpdateCollection
• GetCollection

Creazione del database

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

Campo	Tipo	Descrizione
customAction	string	Nome del comando personalizzato. Il valore deve essere CreateDatabase.
offerThroughput	int	Velocità effettiva con provisioning impostata nel database. Il parametro è facoltativo.
autoScaleSettings	Object	Obbligatorio per la modalità di scalabilità automatica. Questo oggetto contiene le impostazioni associate alla modalità della capacità di scalabilità automatica. È possibile impostare il valore di maxThroughput, che descrive il numero più elevato di unità richiesta che può raggiungere dinamicamente la raccolta.

Output

Se il comando ha esito positivo, restituisce la risposta seguente:

{ "ok" : 1 }

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

Esempio: creare 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 crea un database senza velocità effettiva a livello di database. Ciò significa che le raccolte all'interno di questo database devono specificare la quantità di velocità effettiva che è necessario usare.

Esempio: creare un database con velocità effettiva

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

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

Questo comando crea un database e imposta una velocità effettiva per tale database. Tutte le raccolte all'interno del database condividono la velocità effettiva impostata, a meno che non vengano create con un livello di velocità effettiva specifico.

Esempio: creare un database con velocità effettiva a scalabilità automatica

Per creare un database denominato "test" e per specificare una velocità effettiva massima a 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 di estensione UpdateDatabase aggiorna le proprietà associate al database specificato. La modifica del database per passare dalla velocità effettiva con provisioning a quella con scalabilità automatica e viceversa è supportata solo nel portale di Azure. Nella tabella seguente sono descritti i parametri all'interno del comando:

Campo	Tipo	Descrizione
customAction	string	Nome del comando personalizzato. Il valore deve essere UpdateDatabase.
offerThroughput	int	Nuova velocità effettiva con provisioning da impostare nel database se quest'ultimo 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à della capacità di scalabilità automatica. È possibile impostare il valore di maxThroughput, che descrive il numero più elevato di unità richiesta che può raggiungere dinamicamente il database.

Questo comando usa il database specificato nel contesto della sessione, che corrisponde a quello usato nel comando use <database>. Al momento, il nome del database non può essere modificato tramite questo comando.

Output

Se il comando ha esito positivo, restituisce la risposta seguente:

{ "ok" : 1 }

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

Esempio: aggiornare la velocità effettiva con provisioning associata a un database

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

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

Esempio: aggiornare la velocità effettiva a scalabilità automatica associata a un database

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

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

Recupera database

Il comando di estensione GetDatabase restituisce l'oggetto di database. Il nome del database viene usato dal contesto del database in cui viene eseguito il comando.

{
  customAction: "GetDatabase"
}

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

Campo	Tipo	Descrizione
customAction	string	Nome del comando personalizzato. Il valore 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 di .
provisionedThroughput	int	Velocità effettiva con provisioning impostata nel database se il database usa 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 valore di maxThroughput descrive il numero più elevato di unità richiesta che può raggiungere dinamicamente il database.

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

Esempio: 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 al database non è associata alcuna velocità effettiva, l'output sarà:

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

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

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

Se al database è associata una velocità effettiva a scalabilità automatica a livello di database, l'output mostrerà il valore di provisionedThroughput, che descrive il numero minimo di UR/sec 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 di estensione CreateCollection crea una nuova raccolta MongoDB. Il nome del database viene usato dal contesto dei database impostato dal comando use database. 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 sono descritti i parametri all'interno del comando:

Campo	Type	Obbligatorio	Descrizione
customAction	string	Richiesto	Nome del comando personalizzato. Il valore deve essere CreateCollection.
collection	string	Richiesto	Nome della raccolta. Non sono consentiti caratteri speciali o spazi.
offerThroughput	int	Facoltativo	Velocità effettiva con provisioning da impostare nel database. Se questo parametro non è specificato, viene impostato il valore minimo predefinito, ovvero 400 UR/sec. * Per specificare la velocità effettiva superiore a 10.000 UR/sec, è necessario il parametro shardKey.
shardKey	string	Obbligatorio per le raccolte con velocità effettiva elevata	Percorso della chiave di partizione per la raccolta partizionata. Questo parametro è obbligatorio se si imposta un valore superiore a 10.000 UR/sec in offerThroughput. Se è specificato, tutti i documenti inseriti richiedono la chiave e il valore specificati.
autoScaleSettings	Object	Obbligatorio per la modalità di scalabilità automatica	Questo oggetto contiene le impostazioni associate alla modalità della capacità di scalabilità automatica. È possibile impostare il valore di maxThroughput, che descrive il numero più elevato di unità richiesta che può raggiungere dinamicamente la raccolta.
indexes	Array	La configurazione degli indici è facoltativa. Questo parametro è supportato solo per gli account della versione 3.6 e successive.	Quando questo campo è presente, è necessario un indice basato su _id. Ogni voce della 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 predefinita del comando personalizzato. Vedere l'output predefinito del comando personalizzato per i parametri nell'output.

Esempio: creare una raccolta con la configurazione minima

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

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

Questa operazione ha come risultato una nuova raccolta fissa, non partizionata, con 400 UR/sec e un indice nel campo _id creato automaticamente. Questo tipo di configurazione si applica anche quando vengono create nuove raccolte tramite la funzione insert(). Ad esempio:

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

Esempio: creare una raccolta non partizionata

Per creare una raccolta non partizionata denominata "testCollection" e con 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.

Esempio: creare una raccolta partizionata

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

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

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

Esempio: creare una raccolta a scalabilità automatica non partizionata

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

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

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

Esempio: creare una raccolta a scalabilità automatica partizionata

Per creare una raccolta partizionata denominata 'testCollection', con una chiave di partizione chiamata 'a.b' e che usa una capacità di velocità effettiva a 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 di estensione UpdateCollection 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 sono descritti i parametri all'interno del comando:

Campo	Tipo	Descrizione
customAction	string	Nome del comando personalizzato. Il valore 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à della capacità di scalabilità automatica. Il valore di maxThroughput descrive il numero più elevato di unità richiesta che può raggiungere dinamicamente la raccolta.
indexes	Array	La configurazione degli indici è facoltativa. Questo parametro è supportato solo per gli account della versione 3.6 e successive. Quando presente, il set di indici specificati (inclusa l'eliminazione degli indici) sostituisce gli indici esistenti della raccolta. È necessario un indice basato su _id. Ogni voce della 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 predefinita del comando personalizzato. Vedere l'output predefinito del comando personalizzato per i parametri nell'output.

Esempio: aggiornare la velocità effettiva con provisioning associata a una raccolta

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

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

Recupera una raccolta

Il comando personalizzato GetCollection restituisce l'oggetto raccolta.

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

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

Campo	Tipo	Descrizione
customAction	string	Nome del comando personalizzato. Il valore 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 di .
collection	string	Nome della raccolta.
shardKeyDefinition	document	Documento di specifica dell'indice usato come chiave di partizione. Questo campo è un parametro di risposta facoltativo.
provisionedThroughput	int	Velocità effettiva con provisioning da impostare nella raccolta. Questo campo è 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 valore di maxThroughput descrive il numero più elevato di unità richiesta che può raggiungere dinamicamente la raccolta.

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

Esempio: 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, include il valore di provisionedThroughput e l'output sarà:

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

Se la raccolta ha una velocità effettiva a scalabilità automatica associata, include l'oggetto autoScaleSettings con il parametro maxThroughput, che definisce la velocità effettiva massima raggiungibile dalla raccolta. Include inoltre il valore provisionedThroughput, che definisce la velocità effettiva minima per questa raccolta se non sono presenti richieste:

{
        "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 modifiche

Quando si usano flussi di modifiche su larga scala, è consigliabile distribuire il carico in maniera uniforme. Il comando seguente restituisce uno o più token di ripresa del flusso di modifiche, ognuno corrispondente ai dati di una singola partizione/partizione fisica (più partizioni/partizioni logiche possono esistere in una sola partizione fisica). Ogni token di ripresa fa sì che watch() restituisca solo dati da tale partizione/partizione fisica.

Usare db.collection.watch() su ogni token di ripresa (un thread per token) per ridimensionare i flussi di modifiche in modo efficiente.

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

Esempio: ottenere il token di flusso

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. Ecco 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. Il comando watch() restituisce un cursore 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")
  }
}

Ogni documento restituito include un token di ripresa (sono tutti uguali per ogni pagina). Questo token deve essere archiviato e riutilizzato se il thread/processo muore. Il token riprende dal punto in cui è avvenuta l'interruzione e riceve 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 = esito positivo. 0 = errore.
code	int	Restituito solo quando il comando ha avuto esito negativo, ovvero ok == 0. Contiene il codice di errore MongoDB. Questo campo è un parametro di risposta facoltativo.
errMsg	string	Restituito solo quando il comando ha avuto esito negativo, ovvero ok == 0. Contiene una messaggio di errore descrittivo. Questo campo è un parametro di risposta facoltativo.

Ad esempio:

{ "ok" : 1 }

Passaggi successivi

È quindi possibile proseguire per apprendere i concetti di Azure Cosmos DB seguenti:

• Indicizzazione in Azure Cosmos DB
• Impostare la scadenza automatica dei dati in Azure Cosmos DB con la durata (TTL)