Utiliser les commandes d’extension MongoDB pour gérer des données stockées dans Azure Cosmos DB for MongoDB

  • Article

S’APPLIQUE À : MongoDB

Le document suivant contient les commandes d’action personnalisées spécifiques à Azure Cosmos DB for MongoDB. Ces commandes peuvent être utilisées pour créer et obtenir des ressources de base de données spécifiques au modèle de capacité Azure Cosmos DB.

Lorsque vous utilisez Azure Cosmos DB for MongoDB, vous pouvez profiter des avantages partagés d’Azure Cosmos DB. Ces avantages incluent les éléments suivants, sans toutefois s’y limiter :

  • Diffusion mondiale
  • Partitionnement automatique
  • Haute disponibilité
  • Garanties de latence
  • Chiffrement au repos
  • Sauvegardes

Vous pouvez tirer parti de ces avantages tout en préservant vos investissements dans votre ou vos applications MongoDB existantes. Vous pouvez communiquer avec Azure Cosmos DB for MongoDB en utilisant n’importe quel pilote client open source MongoDB. Azure Cosmos DB for MongoDB permet d’utiliser les pilotes clients existants en adhérant au protocole Wire MongoDB.

Prise en charge des protocoles MongoDB

Azure Cosmos DB for MongoDB est compatible avec les versions serveur 4.0, 3.6 et 3.2 de MongoDB. Pour plus d’informations, consultez les fonctionnalités et syntaxe prises en charge dans les versions 4.0, 3.6 et 3.2.

Les commandes d’extension suivantes permettent de créer et de modifier des ressources spécifiques à Azure Cosmos DB via des requêtes de base de données :

Créer une base de données

La commande d’extension de création de base de données crée une base de données MongoDB. Le nom de la base de données peut être utilisé à partir du contexte de base de données défini par la commande use database. Le tableau suivant décrit les paramètres inclus dans la commande :

Champ Type Description
customAction string Nom de la commande personnalisée. La valeur doit être CreateDatabase.
offerThroughput int Débit approvisionné que vous définissez sur la base de données. Ce paramètre est facultatif.
autoScaleSettings Object Requis pour le mode de mise à l’échelle automatique. Cet objet contient les paramètres associés au mode de capacité de mise à l’échelle automatique. Vous pouvez configurer la valeur maxThroughput, qui décrit le nombre le plus élevé d’unités de requête vers lequel la collection peut être augmentée de manière dynamique.

Sortie

En cas de réussite de la commande, la réponse suivante est retournée :

{ "ok" : 1 }

Consultez la sortie par défaut de la commande personnalisée pour connaître les paramètres de la sortie.

Exemple : créer une base de données

Pour créer une base de données nommée "test" qui utilise toutes les valeurs par défaut, utilisez la commande suivante :

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

Cette commande crée une base de données sans débit au niveau de la base de données. Cette opération signifie que les collections de cette base de données devront spécifier la quantité de débit que vous devez utiliser.

Exemple : créer une base de données avec débit

Pour créer une base de données nommée "test" et spécifier un débit approvisionné au niveau de la base de données de 1 000 unités de requête, utilisez la commande suivante :

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

Cette commande crée une base de données et lui définit un débit. Toutes les collections de cette base de données partagent le débit défini, à moins que les collections ne soient créées avec un niveau de débit spécifique.

Exemple : créer une base de données avec un débit de mise à l’échelle automatique

Pour créer une base de données nommée "test" et spécifier un débit maximal avec mise à l’échelle automatique de 20 000 RU/s au niveau de la base de données, utilisez la commande suivante :

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

Mettre à jour la base de données

La commande d’extension de mise à jour de base de données met à jour les propriétés associées à la base de données spécifiée. Passer votre base de données d’un débit approvisionné avec mise à l’échelle automatique, ou vice versa, est uniquement possible dans le Portail Azure. Le tableau suivant décrit les paramètres inclus dans la commande :

Champ Type Description
customAction string Nom de la commande personnalisée. La valeur doit être UpdateDatabase.
offerThroughput int Nouveau débit approvisionné que vous souhaitez définir sur la base de données si la base de données utilise un débit au niveau de la base de données.
autoScaleSettings Object Requis pour le mode de mise à l’échelle automatique. Cet objet contient les paramètres associés au mode de capacité de mise à l’échelle automatique. Vous pouvez définir la valeur maxThroughput, qui décrit le nombre le plus élevé d’unités de requête vers lequel la base de données peut être augmentée de manière dynamique.

Cette commande utilise la base de données spécifiée dans le contexte de la session. Il s’agit de la même base de données que celle utilisée dans la commande use <database>. Le nom de la base de données ne peut pas être modifié à l’aide de cette commande pour le moment.

Sortie

En cas de réussite de la commande, la réponse suivante est retournée :

{ "ok" : 1 }

Consultez la sortie par défaut de la commande personnalisée pour connaître les paramètres de la sortie.

Exemple : mettre à jour le débit approvisionné associé à une base de données

Pour mettre à jour le débit approvisionné d’une base de données nommée "test" à 1 200 unités de requête, utilisez la commande suivante :

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

Exemple : mettre à jour le débit avec mise à l’échelle automatique associé à une base de données

Pour mettre à jour le débit approvisionné d’une base de données nommée "test" à 20 000 unités de requête ou pour le transformer en un niveau de débit avec mise à l’échelle automatique, utilisez la commande suivante :

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

Obtenir une base de données

La commande d’extension d’obtention de base de données retourne l’objet de base de données. Le nom de la base de données est tiré du contexte de base de données par rapport auquel la commande est exécutée.

{
  customAction: "GetDatabase"
}

Le tableau suivant décrit les paramètres inclus dans la commande :

Champ Type Description
customAction string Nom de la commande personnalisée. La valeur doit être GetDatabase.

Output

Si la commande réussit, la réponse contient un document avec les champs suivants :

Champ Type Description
ok int État de la réponse. 1 == réussite. 0 == échec.
database string Nom de la base de données.
provisionedThroughput int Débit approvisionné qui est défini sur la base de données si la base de données utilise un débit manuel au niveau de la base de données.
autoScaleSettings Object Cet objet contient les paramètres de capacité associés à la base de données si elle utilise le Mode de mise à l’échelle automatique. La valeur maxThroughput décrit le nombre le plus élevé d’unités de requête vers lequel la base de données peut être augmentée de manière dynamique.

Si la commande échoue, une réponse de commande personnalisée par défaut est retournée. Consultez la sortie par défaut de la commande personnalisée pour connaître les paramètres de la sortie.

Exemple : obtenir la base de données

Pour obtenir l’objet de base de données pour une base de données nommée "test", utilisez la commande suivante :

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

Si la base de données n’a pas de débit associé, la sortie est la suivante :

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

Si la base de données a un débit manuel au niveau de la base de données qui lui est associé, la sortie affiche les valeurs provisionedThroughput suivantes :

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

Si la base de données a un débit avec mise à l’échelle automatique au niveau de la base de données qui lui est associé, la sortie indique le provisionedThroughput, qui décrit le nombre minimal de RU/s pour la base de données, et l’objet autoScaleSettings, y compris le maxThroughput, qui décrit le nombre maximal de RU/s pour la base de données.

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

Créer une collection

La commande d’extension de création de collection crée une collection MongoDB. Le nom de la base de données est utilisé à partir du contexte de base de données défini par la commande use database. Le format de la commande CreateCollection est le suivant :

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

Le tableau suivant décrit les paramètres inclus dans la commande :

Champ Type Obligatoire Description
customAction string Obligatoire Nom de la commande personnalisée. La valeur doit être CreateCollection.
collection string Obligatoire Nom de la collection. Aucun caractère spécial ni aucune espace ne sont autorisés.
offerThroughput int Facultatif Débit approvisionné à définir sur la base de données. Si ce paramètre n’est pas fourni, la valeur par défaut est la valeur minimum, soit 400 RU/s. * Pour spécifier un débit supérieur à 10 000 RU/s, le paramètre shardKey est obligatoire.
shardKey string Obligatoire pour les collections avec un débit élevé Chemin d'accès à la clé de partition pour la collection partitionnée. Ce paramètre est obligatoire si vous définissez plus de 10 000 RU/s dans offerThroughput. S’il est spécifié, tous les documents insérés ont besoin de cette clé et de cette valeur.
autoScaleSettings Object Obligatoire pour le mode de mise à l’échelle automatique Cet objet contient les paramètres associés au mode de capacité de mise à l’échelle automatique. Vous pouvez configurer la valeur maxThroughput, qui décrit le nombre le plus élevé d’unités de requête vers lequel la collection peut être augmentée de manière dynamique.
indexes Array Si vous le souhaitez, vous pouvez également configurer les index. Ce paramètre est pris en charge uniquement pour les comptes 3.6 et versions ultérieures. Quand il est présent, un index sur _id est requis. Chaque entrée du tableau doit inclure une clé d’un ou plusieurs champs ainsi qu’un nom et peut contenir des options d’index. Par exemple, pour créer un index unique composé sur les champs aet b, utilisez l’entrée suivante : {key: {a: 1, b: 1}, name:"a_1_b_1", unique: true}.

Output

Retourne une réponse de commande personnalisée par défaut. Consultez la sortie par défaut de la commande personnalisée pour connaître les paramètres de la sortie.

Exemple : créer une collection avec la configuration minimale

Pour créer une collection avec le nom "testCollection" et les valeurs par défaut, utilisez la commande suivante :

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

Cette opération se traduit par une nouvelle collection fixe et non partitionnée, avec 400 RU/s et un index sur le champ _id créé automatiquement. Ce type de configuration s’applique également lors de la création de collections via la fonction insert(). Par exemple :

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

Exemple : créer une collection non partitionnée

Pour créer une collection non partitionnée nommée "testCollection" avec un débit approvisionné de 1 000 unités de requête, utilisez la commande suivante :

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

Vous pouvez créer une collection avec un maximum de 10 000 RU/s en tant que offerThroughput sans avoir besoin de spécifier une clé de partition. Pour les collections avec un débit plus élevé, consultez la section suivante.

Exemple : créer une collection partitionnée

Pour créer une collection partitionnée nommée "testCollection" avec un débit approvisionné de 11 000 unités de requête et une propriété shardkey « a.b », utilisez la commande suivante :

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

Cette commande requiert désormais le paramètre shardKey, car plus de 10 000 RU/s sont spécifiées dans le offerThroughput.

Exemple : créer une collection avec mise à l’échelle automatique non partitionnée

Pour créer une collection non partitionnée nommée 'testCollection' qui utilise la capacité de débit avec mise à l’échelle automatique définie sur 4 000 RU/s, utilisez la commande suivante :

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

Pour la valeur autoScaleSettings.maxThroughput, vous pouvez spécifier une plage comprise entre 4 000 RU/s et 10 000 RU/s sans clé de partition. Pour un débit avec mise à l’échelle automatique plus élevé, vous devez spécifier le paramètre shardKey.

Exemple : créer une collection avec mise à l’échelle automatique partitionnée

Pour créer une collection partitionnée nommée 'testCollection' avec une clé de partition appelée 'a.b' et qui utilise la capacité de débit avec mise à l’échelle automatique définie sur 20 000 RU/s, utilisez la commande suivante :

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

Mettre à jour la collection

La commande d’extension de mise à jour de collection met à jour les propriétés associées à la collection spécifiée. Passer votre collection d’un débit approvisionné à une mise à l’échelle automatique, ou vice versa, est possible uniquement dans le Portail 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).
}

Le tableau suivant décrit les paramètres inclus dans la commande :

Champ Type Description
customAction string Nom de la commande personnalisée. La valeur doit être UpdateCollection.
collection string Nom de la collection.
offerThroughput int Débit approvisionné à définir sur la collection.
autoScaleSettings Object Requis pour le mode de mise à l’échelle automatique. Cet objet contient les paramètres associés au mode de capacité de mise à l’échelle automatique. La valeur maxThroughput décrit le nombre le plus élevé d’unités de requête vers lequel la collection peut être augmentée de manière dynamique.
indexes Array Si vous le souhaitez, vous pouvez également configurer les index. Ce paramètre est pris en charge uniquement pour les comptes 3.6 et versions ultérieures. Quand ils sont présents, les ensembles d’index spécifié (y compris les index de suppression) remplacent les index de collection existants. Un index sur _id est requis. Chaque entrée du tableau doit inclure une clé d’un ou plusieurs champs ainsi qu’un nom et peut contenir des options d’index. Par exemple, pour créer un index unique composé sur les champs a et b, utilisez l’entrée suivante : {key: {a: 1, b: 1}, name: "a_1_b_1", unique: true}.

Output

Retourne une réponse de commande personnalisée par défaut. Consultez la sortie par défaut de la commande personnalisée pour connaître les paramètres de la sortie.

Exemple : mettre à jour le débit approvisionné associé à une collection

Pour mettre à jour le débit approvisionné d’une collection nommée "testCollection" à 1 200 unités de requête, utilisez la commande suivante :

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

Obtenir une collection

La commande personnalisée d’obtention de collection retourne l’objet de collection.

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

Le tableau suivant décrit les paramètres inclus dans la commande :

Champ Type Description
customAction string Nom de la commande personnalisée. La valeur doit être GetCollection.
collection string Nom de la collection.

Output

Si la commande réussit, la réponse contient un document avec les champs suivants.

Champ Type Description
ok int État de la réponse. 1 == réussite. 0 == échec.
database string Nom de la base de données.
collection string Nom de la collection.
shardKeyDefinition document Document de spécification d’index utilisé comme clé de partition. Ce champ est un paramètre de réponse facultatif.
provisionedThroughput int Débit approvisionné à définir sur la collection. Ce champ est un paramètre de réponse facultatif.
autoScaleSettings Object Cet objet contient les paramètres de capacité associés à la base de données si elle utilise le Mode de mise à l’échelle automatique. La valeur maxThroughput décrit le nombre le plus élevé d’unités de requête vers lequel la collection peut être augmentée de manière dynamique.

Si la commande échoue, une réponse de commande personnalisée par défaut est retournée. Consultez la sortie par défaut de la commande personnalisée pour connaître les paramètres de la sortie.

Exemple : obtenir la collection

Pour obtenir l’objet de collection pour une collection nommée "testCollection", utilisez la commande suivante :

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

Si la collection a une capacité de débit associée, elle inclut la valeur provisionedThroughput et la sortie est la suivante :

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

Si la collection est associée à un débit avec mise à l’échelle automatique, elle inclut l’objet autoScaleSettings avec le paramètre maxThroughput, qui définit le débit maximal vers lequel la collection augmente de façon dynamique. En outre, elle inclut également la valeur provisionedThroughput, qui définit le débit minimal vers lequel cette collection est réduite en l’absence de requête dans la collection :

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

Si la collection partage un débit au niveau de la base de données, soit en mode de mise à l’échelle automatique, soit en manuel, la sortie est la suivante :

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

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

Parallélisation de flux de modification

Lorsque vous utilisez des flux de modification à grande échelle, il est préférable de répartir uniformément la charge. La commande suivante retourne un ou plusieurs jetons de reprise de flux de modification, chacun correspondant aux données d’une étendue/partition physique unique (plusieurs étendues/partitions logiques peuvent exister sur une même partition physique). Pour chaque jeton de reprise, watch() retourne uniquement des données de l’étendue/la partition physique correspondante.

Utilisez db.collection.watch() sur chaque jeton de reprise (un thread par jeton) pour effectuer une mise à l’échelle efficace des flux de modification.

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

Exemple : obtenir le jeton de flux

Exécutez la commande personnalisée pour obtenir un jeton de reprise pour chaque étendue/partition physique.

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

Exécutez un thread/processus watch() pour chaque jeton de reprise retourné par la commande personnalisée GetChangeStreamTokens. Voici l’exemple d’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)}})

Le document (valeur) dans le champ resumeAfter représente le jeton de reprise. La commande watch() retourne un curseur pour tous les documents qui ont été insérés, mis à jour ou remplacés depuis l’exécution de la commande personnalisée GetChangeStreamTokens à partir de cette partition physique. Vous trouverez ici un exemple des données retournées.

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

Chaque document retourné comprend un jeton de reprise (ils sont tous identiques pour chaque page). Ce jeton de reprise doit être stocké et réutilisé si le thread/processus s’achève. Ce jeton de reprise reprend là où vous vous êtes arrêté et reçoit uniquement les données de cette partition physique.

Sortie par défaut d’une commande personnalisée

Si elle n’est pas spécifiée, la réponse personnalisée contient un document avec les champs suivants :

Champ Type Description
ok int État de la réponse. 1 == réussite. 0 == échec.
code int Retourné uniquement lorsque la commande a échoué (c’est-à-dire ok == 0). Contient le code d’erreur MongoDB. Ce champ est un paramètre de réponse facultatif.
errMsg string Retourné uniquement lorsque la commande a échoué (c’est-à-dire ok == 0). Contient un message d’erreur convivial. Ce champ est un paramètre de réponse facultatif.

Par exemple :

{ "ok" : 1 }

Étapes suivantes

Vous pouvez ensuite commencer à apprendre les concepts relatifs à Azure Cosmos DB suivants :