Utilizar comandos de extensão do MongoDB para gerir dados armazenados no Azure Cosmos DB para MongoDB

Artigo
05/23/2023

APLICA-SE A: MongoDB

O documento seguinte contém os comandos de ação personalizados específicos do Azure Cosmos DB para MongoDB. Estes comandos podem ser utilizados para criar e obter recursos de base de dados específicos do modelo de capacidade do Azure Cosmos DB.

Ao utilizar o Azure Cosmos DB para MongoDB, pode desfrutar das vantagens partilhadas do Azure Cosmos DB. Estes benefícios incluem, mas não se limitam a:

Distribuição global
Fragmentação automática
Elevada disponibilidade
Garantias de latência
Encriptação de dados inativos
Cópias de segurança

Pode usufruir destes benefícios ao mesmo tempo que preserva os seus investimentos na sua aplicação mongoDB existente[s]. Pode comunicar com o Azure Cosmos DB para MongoDB com qualquer um dos controladores de cliente do MongoDB open source. O Azure Cosmos DB para MongoDB permite a utilização de controladores de cliente existentes ao aderir ao protocolo de transmissão do MongoDB.

Suporte de protocolo do MongoDB

O Azure Cosmos DB para MongoDB é compatível com a versão 4.0, 3.6 e 3.2 do servidor MongoDB. Para obter mais informações, consulte funcionalidades e sintaxe suportadas nas versões 4.0, 3.6 e 3.2.

Os seguintes comandos de extensão criam e modificam recursos específicos do Azure Cosmos DB através de pedidos de base de dados:

Criar base de dados
Atualizar base de dados
Obter base de dados
Criar coleção
Atualizar coleção
Obter coleção

Criar base de dados

O comando criar extensão de base de dados cria uma nova base de dados do MongoDB. O nome da base de dados pode ser utilizado a partir do contexto da base de dados definido pelo use database comando . A tabela seguinte descreve os parâmetros no comando :

Campo	Tipo	Description
`customAction`	`string`	Nome do comando personalizado. O valor tem de ser `CreateDatabase`.
`offerThroughput`	`int`	Débito aprovisionado definido na base de dados. Este parâmetro é opcional.
`autoScaleSettings`	`Object`	Necessário para o modo de Dimensionamento Automático. Este objeto contém as definições associadas ao modo de capacidade de Dimensionamento Automático. Pode configurar o `maxThroughput` valor, que descreve o maior número de Unidades de Pedido para o qual a coleção pode aumentar dinamicamente.

Saída

Se o comando for bem-sucedido, devolve a seguinte resposta:

{ "ok" : 1 }

Veja a saída predefinida do comando personalizado para os parâmetros na saída.

Exemplo: Criar uma base de dados

Para criar uma base de dados com o nome "test" que utiliza todos os valores predefinidos, utilize o seguinte comando:

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

Este comando cria uma base de dados sem débito ao nível da base de dados. Esta operação significa que as coleções nesta base de dados têm de especificar a quantidade de débito que precisa de utilizar.

Exemplo: Criar uma base de dados com débito

Para criar uma base de dados com o nome "test" e especificar um débito aprovisionado ao nível da base de dados de 1000 RUs, utilize o seguinte comando:

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

Este comando cria uma base de dados e define um débito para a mesma. Todas as coleções nesta base de dados partilham o débito definido, a menos que as coleções sejam criadas com um nível de débito específico.

Exemplo: Criar uma base de dados com débito de Dimensionamento Automático

Para criar uma base de dados com o nome "test" e especificar um débito máximo de Dimensionamento Automático de 20 000 RU/s ao nível da base de dados, utilize o seguinte comando:

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

Atualizar base de dados

O comando atualizar extensão da base de dados atualiza as propriedades associadas à base de dados especificada. A alteração do débito aprovisionado da base de dados para o dimensionamento automático e vice-versa só é suportada no portal do Azure. A tabela seguinte descreve os parâmetros no comando :

Campo	Tipo	Description
`customAction`	`string`	Nome do comando personalizado. O valor tem de ser `UpdateDatabase`.
`offerThroughput`	`int`	Novo débito aprovisionado que pretende definir na base de dados se a base de dados utilizar débito ao nível da base de dados
`autoScaleSettings`	`Object`	Necessário para o modo de Dimensionamento Automático. Este objeto contém as definições associadas ao modo de capacidade de Dimensionamento Automático. Pode configurar o `maxThroughput` valor, que descreve o maior número de Unidades de Pedido para o qual a base de dados pode ser aumentada dinamicamente.

Este comando utiliza a base de dados especificada no contexto da sessão. Esta base de dados é a mesma que utilizou no use <database> comando . De momento, o nome da base de dados não pode ser alterado com este comando.

Saída

Se o comando for bem-sucedido, devolve a seguinte resposta:

{ "ok" : 1 }

Veja a saída predefinida do comando personalizado para os parâmetros na saída.

Exemplo: Atualizar o débito aprovisionado associado a uma base de dados

Para atualizar o débito aprovisionado de uma base de dados com o nome "test" para 1200 RUs, utilize o seguinte comando:

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

Exemplo: Atualizar o débito de Dimensionamento Automático associado a uma base de dados

Para atualizar o débito aprovisionado de uma base de dados com o nome "test" para 20 000 RUs ou para transformá-lo num nível de débito de Dimensionamento Automático, utilize o seguinte comando:

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

Obter base de dados

O comando obter extensão de base de dados devolve o objeto de base de dados. O nome da base de dados é utilizado a partir do contexto da base de dados no qual o comando é executado.

{
  customAction: "GetDatabase"
}

A tabela seguinte descreve os parâmetros no comando :

Campo	Tipo	Description
`customAction`	`string`	Nome do comando personalizado. O valor tem de ser `GetDatabase`.

Saída

Se o comando for bem-sucedido, a resposta contém um documento com os seguintes campos:

Campo	Tipo	Description
`ok`	`int`	Estado da resposta. 1 == êxito. 0 == falha.
`database`	`string`	Nome da base de dados.
`provisionedThroughput`	`int`	Débito aprovisionado definido na base de dados se a base de dados estiver a utilizar o débito manual ao nível da base de dados
`autoScaleSettings`	`Object`	Este objeto contém os parâmetros de capacidade associados à base de dados se estiver a utilizar o modo de Dimensionamento Automático. O `maxThroughput` valor descreve o número mais elevado de Unidades de Pedido para as quais a base de dados pode ser aumentada dinamicamente.

Se o comando falhar, é devolvida uma resposta de comando personalizada predefinida. Veja a saída predefinida do comando personalizado para os parâmetros na saída.

Exemplo: Obter a base de dados

Para obter o objeto de base de dados de uma base de dados com o nome "test", utilize o seguinte comando:

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

Se a base de dados não tiver débito associado, o resultado será:

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

Se a base de dados tiver um débito manual ao nível da base de dados associado, a saída mostrará os provisionedThroughput valores:

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

Se a base de dados tiver um débito de Dimensionamento Automático ao nível da base de dados associado, a saída mostrará o provisionedThroughput, que descreve as RU/s mínimas para a base de dados e o autoScaleSettings objeto, incluindo o maxThroughput, que descreve as RU/s máximas para a base de dados.

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

Criar coleção

O comando criar extensão de coleção cria uma nova coleção do MongoDB. O nome da base de dados é utilizado a partir do contexto de bases de dados definido pelo use database comando . O formato do comando CreateCollection é o seguinte:

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

A tabela seguinte descreve os parâmetros no comando :

Campo	Tipo	Necessário	Descrição
`customAction`	`string`	Obrigatório	Nome do comando personalizado. O valor tem de ser `CreateCollection`.
`collection`	`string`	Necessário	Nome da coleção. Não são permitidos carateres ou espaços especiais.
`offerThroughput`	`int`	Opcional	Débito aprovisionado a definir na base de dados. Se este parâmetro não for fornecido, a predefinição é 400 RU/s mínima. * Para especificar débito para além de 10 000 RU/s, o `shardKey` parâmetro é necessário.
`shardKey`	`string`	Necessário para coleções com débito grande	O caminho para a Chave de Partição Horizontal para a coleção fragmentada. Este parâmetro é necessário se definir mais de 10 000 RU/s em `offerThroughput`. Se for especificado, todos os documentos inseridos requerem esta chave e valor.
`autoScaleSettings`	`Object`	Necessário para o modo de Dimensionamento Automático	Este objeto contém as definições associadas ao modo de capacidade de Dimensionamento Automático. Pode configurar o `maxThroughput` valor, que descreve o maior número de Unidades de Pedido para o qual a coleção pode ser aumentada dinamicamente.
`indexes`	`Array`	Opcionalmente, configure índices. Este parâmetro é suportado apenas para contas com mais de 3,6.	Quando estiver presente, é necessário um índice no _id. Cada entrada na matriz tem de incluir uma chave de um ou mais campos, um nome e pode conter opções de índice. Por exemplo, para criar um índice exclusivo composto nos campos `a` e `b` utilizar esta entrada: `{key: {a: 1, b: 1}, name:"a_1_b_1", unique: true}`.

Saída

Devolve uma resposta de comando personalizada predefinida. Veja a saída predefinida do comando personalizado para os parâmetros na saída.

Exemplo: Criar uma coleção com a configuração mínima

Para criar uma nova coleção com o nome "testCollection" e os valores predefinidos, utilize o seguinte comando:

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

Esta operação resulta numa nova coleção fixa, sem alterações, com 400RU/s e um índice no _id campo criado automaticamente. Este tipo de configuração também se aplica ao criar novas coleções através da insert() função . Por exemplo:

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

Exemplo: Criar uma coleção não alterada

Para criar uma coleção não integrada com o nome "testCollection" e o débito aprovisionado de 1000 RUs, utilize o seguinte comando:

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

Pode criar uma coleção com até 10 000 RU/s como sem offerThroughput ter de especificar uma chave de partição horizontal. Para coleções com débito maior, consulte a secção seguinte.

Exemplo: Criar uma coleção fragmentada

Para criar uma coleção fragmentada com o nome "testCollection" e débito aprovisionado de 11 000 RUs e uma shardkey propriedade "a.b", utilize o seguinte comando:

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

Este comando requer agora o shardKey parâmetro , uma vez que mais de 10 000 RU/s especificados no offerThroughput.

Exemplo: Criar uma coleção de Dimensionamento Automático não harded

Para criar uma coleção não definida com o nome 'testCollection' que utiliza a capacidade de débito de Dimensionamento Automático definida como 4000 RU/s, utilize o seguinte comando:

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

Para o autoScaleSettings.maxThroughput valor, pode especificar um intervalo de 4000 RU/s a 10 000 RU/s sem uma chave de partição horizontal. Para um débito de dimensionamento automático mais elevado, tem de especificar o shardKey parâmetro .

Exemplo: Criar uma coleção de Dimensionamento Automático fragmentado

Para criar uma coleção fragmentada denominada 'testCollection' com uma chave de partição horizontal denominada 'a.b'e que utiliza a capacidade de débito de Dimensionamento Automático definida como 20 000 RU/s, utilize o seguinte comando:

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

Atualizar coleção

O comando update collection extension atualiza as propriedades associadas à coleção especificada. A alteração da coleção do débito aprovisionado para o dimensionamento automático e vice-versa só é suportada no portal do 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).
}

A tabela seguinte descreve os parâmetros no comando :

Campo	Tipo	Description
`customAction`	`string`	Nome do comando personalizado. O valor tem de ser `UpdateCollection`.
`collection`	`string`	Nome da coleção.
`offerThroughput`	`int`	Débito aprovisionado a definir na coleção.
`autoScaleSettings`	`Object`	Necessário para o modo de Dimensionamento Automático. Este objeto contém as definições associadas ao modo de capacidade de Dimensionamento Automático. O `maxThroughput` valor descreve o número mais elevado de Unidades de Pedido para as quais a coleção pode ser aumentada dinamicamente.
`indexes`	`Array`	Opcionalmente, configure índices. Este parâmetro é suportado apenas para contas com mais de 3,6. Quando estiver presente, o conjunto de índices especificados (incluindo a remoção de índices) substitui os índices existentes da coleção. É necessário um índice no _id. Cada entrada na matriz tem de incluir uma chave de um ou mais campos, um nome e pode conter opções de índice. Por exemplo, para criar um índice exclusivo composto nos campos a e b, utilize esta entrada: `{key: {a: 1, b: 1}, name: "a_1_b_1", unique: true}`.

Saída

Devolve uma resposta de comando personalizada predefinida. Veja a saída predefinida do comando personalizado para os parâmetros na saída.

Exemplo: Atualizar o débito aprovisionado associado a uma coleção

Para atualizar o débito aprovisionado de uma coleção com o nome "testCollection" para 1200 RUs, utilize o seguinte comando:

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

Obter coleção

O comando get collection custom devolve o objeto de coleção.

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

A tabela seguinte descreve os parâmetros no comando :

Campo	Tipo	Description
`customAction`	`string`	Nome do comando personalizado. O valor tem de ser `GetCollection`.
`collection`	`string`	Nome da coleção.

Saída

Se o comando for bem-sucedido, a resposta contém um documento com os seguintes campos

Campo	Tipo	Description
`ok`	`int`	Estado da resposta. 1 == êxito. 0 == falha.
`database`	`string`	Nome da base de dados.
`collection`	`string`	Nome da coleção.
`shardKeyDefinition`	`document`	Documento de especificação de índice utilizado como uma chave de partição horizontal. Este campo é um parâmetro de resposta opcional.
`provisionedThroughput`	`int`	Débito Aprovisionado a definir na coleção. Este campo é um parâmetro de resposta opcional.
`autoScaleSettings`	`Object`	Este objeto contém os parâmetros de capacidade associados à base de dados se estiver a utilizar o modo de Dimensionamento Automático. O `maxThroughput` valor descreve o número mais elevado de Unidades de Pedido para as quais a coleção pode ser aumentada dinamicamente.

Se o comando falhar, é devolvida uma resposta de comando personalizada predefinida. Veja a saída predefinida do comando personalizado para os parâmetros na saída.

Exemplo: Obter a coleção

Para obter o objeto de coleção de uma coleção com o nome "testCollection", utilize o seguinte comando:

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

Se a coleção tiver uma capacidade de débito associada à mesma, inclui o provisionedThroughput valor e a saída será:

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

Se a coleção tiver um débito de Dimensionamento Automático associado, inclui o autoScaleSettings objeto com o maxThroughput parâmetro , que define o débito máximo para o qual a coleção aumenta dinamicamente. Além disso, também inclui o provisionedThroughput valor, que define o débito mínimo para o qual esta coleção reduz se não existirem pedidos na coleção:

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

Se a coleção estiver a partilhar débito ao nível da base de dados, no modo de Dimensionamento Automático ou manual, a saída será:

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

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

Paralelizar fluxos de alteração

Ao utilizar fluxos de alteração em escala, é melhor distribuir uniformemente a carga. O comando seguinte devolve um ou mais tokens de currículo de fluxo de alterações – cada um correspondente aos dados de uma única partição/partição de partições/partições físicas físicas (podem existir várias partições/partições lógicas numa partição física). Cada token de currículo faz com que watch() devolva apenas dados dessa partição/partição de partição/partição física.

Utilize db.collection.watch() em cada token de currículo (um thread por token), para dimensionar os fluxos de alteração de forma eficiente.

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

Exemplo: Obter o token de fluxo

Execute o comando personalizado para obter um token de currículo para cada partição/partição horizontal física.

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

Execute um thread/processo watch() para cada token de currículo devolvido a partir do comando personalizado GetChangeStreamTokens. Eis um exemplo para um tópico.

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

O documento (valor) no campo resumeAfter representa o token de currículo. O comando watch() devolve um cursor para todos os documentos que foram inseridos, atualizados ou substituídos dessa partição física, uma vez que o comando personalizado GetChangeStreamTokens foi executado. Uma amostra dos dados devolvidos está incluída aqui.

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

Cada documento devolvido inclui um token de currículo (são todos iguais para cada página). Este token de currículo deve ser armazenado e reutilizado se o thread/processo morrer. Este token de currículo é retomado a partir de onde ficou e recebe apenas dados dessa partição física.

Saída predefinida de um comando personalizado

Se não for especificado, uma resposta personalizada contém um documento com os seguintes campos:

Campo	Tipo	Description
`ok`	`int`	Estado da resposta. 1 == êxito. 0 == falha.
`code`	`int`	Só foi devolvido quando o comando falhou (ou seja, ok == 0). Contém o código de erro do MongoDB. Este campo é um parâmetro de resposta opcional.
`errMsg`	`string`	Só foi devolvido quando o comando falhou (ou seja, ok == 0). Contém uma mensagem de erro amigável para o utilizador. Este campo é um parâmetro de resposta opcional.

Por exemplo:

{ "ok" : 1 }

Passos seguintes

Em seguida, pode aprender os seguintes conceitos do Azure Cosmos DB:

Utilizar comandos de extensão do MongoDB para gerir dados armazenados no Azure Cosmos DB para MongoDB

Suporte de protocolo do MongoDB

Criar base de dados

Saída

Exemplo: Criar uma base de dados

Exemplo: Criar uma base de dados com débito

Exemplo: Criar uma base de dados com débito de Dimensionamento Automático

Atualizar base de dados

Saída

Exemplo: Atualizar o débito aprovisionado associado a uma base de dados

Exemplo: Atualizar o débito de Dimensionamento Automático associado a uma base de dados

Obter base de dados

Saída

Exemplo: Obter a base de dados

Criar coleção

Saída

Exemplo: Criar uma coleção com a configuração mínima

Exemplo: Criar uma coleção não alterada

Exemplo: Criar uma coleção fragmentada

Exemplo: Criar uma coleção de Dimensionamento Automático não harded

Exemplo: Criar uma coleção de Dimensionamento Automático fragmentado

Atualizar coleção

Saída

Exemplo: Atualizar o débito aprovisionado associado a uma coleção

Obter coleção

Saída

Exemplo: Obter a coleção

Paralelizar fluxos de alteração

Exemplo: Obter o token de fluxo

Saída predefinida de um comando personalizado

Passos seguintes

Recursos adicionais