Use comandos de extensão do MongoDB para gerenciar dados armazenados no Azure Cosmos DB para MongoDB

APLICA-SE A: MongoDB

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

Usando o Azure Cosmos DB para MongoDB, você pode aproveitar os benefícios compartilhados do Azure Cosmos DB. Esses benefícios incluem, mas não estão limitados a:

• Distribuição global
• Fragmentação automática
• Elevada disponibilidade
• Garantias de latência
• Encriptação inativa
• Cópias de Segurança

Você pode aproveitar esses benefícios enquanto preserva seus investimentos em seus aplicativos MongoDB existentes. Você pode se comunicar com o Azure Cosmos DB para MongoDB usando qualquer um dos drivers de cliente MongoDB de código aberto. O Azure Cosmos DB para MongoDB permite o uso de drivers de cliente existentes aderindo ao protocolo de fio MongoDB.

Suporte ao protocolo MongoDB

O Azure Cosmos DB para MongoDB é compatível com o servidor MongoDB versão 4.0, 3.6 e 3.2. Para obter mais informações, consulte Recursos e sintaxe suportados 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 por meio de solicitações de banco 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 create database extension cria um novo banco de dados MongoDB. O nome do banco de dados pode ser usado a partir do contexto do banco de dados definido pelo use database comando. A tabela a seguir descreve os parâmetros dentro do comando:

Campo	Tipo	Description
customAction	string	Nome do comando personalizado. O valor deve ser CreateDatabase.
offerThroughput	int	Taxa de transferência provisionada definida no banco de dados. Este parâmetro é opcional.
autoScaleSettings	Object	Necessário para o modo de dimensionamento automático. Este objeto contém as configurações associadas ao modo de capacidade Autoscale. Você pode configurar o maxThroughput valor, que descreve o maior número de Unidades de Solicitação para as quais a coleção pode aumentar dinamicamente.

Saída

Se o comando for bem-sucedido, ele retornará a seguinte resposta:

{ "ok" : 1 }

Consulte a saída padrão do comando personalizado para os parâmetros na saída.

Exemplo: Criar um banco de dados

Para criar um banco de dados nomeado "test" que usa todos os valores padrão, use o seguinte comando:

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

Este comando cria um banco de dados sem taxa de transferência no nível de banco de dados. Essa operação significa que as coleções dentro desse banco de dados precisam especificar a quantidade de taxa de transferência que você precisa usar.

Exemplo: Criar um banco de dados com taxa de transferência

Para criar um banco de dados nomeado "test" e especificar uma taxa de transferência provisionada no nível de banco de dados de 1000 RUs, use o seguinte comando:

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

Este comando cria um banco de dados e define uma taxa de transferência para ele. Todas as coleções dentro desse banco de dados compartilham a taxa de transferência definida, a menos que as coleções sejam criadas com um nível de taxa de transferência específico.

Exemplo: Criar um banco de dados com taxa de transferência de dimensionamento automático

Para criar um banco de dados chamado "test" e especificar uma taxa de transferência máxima de Autoscale de 20.000 RU/s no nível do banco de dados, use o seguinte comando:

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

Atualizar base de dados

O comando update database extension atualiza as propriedades associadas ao banco de dados especificado. A alteração do banco de dados de taxa de transferência provisionada para dimensionamento automático e vice-versa só é suportada no portal do Azure. A tabela a seguir descreve os parâmetros dentro do comando:

Campo	Tipo	Description
customAction	string	Nome do comando personalizado. O valor deve ser UpdateDatabase.
offerThroughput	int	Nova taxa de transferência provisionada que você deseja definir no banco de dados se o banco de dados usar taxa de transferência no nível de banco de dados
autoScaleSettings	Object	Necessário para o modo de dimensionamento automático. Este objeto contém as configurações associadas ao modo de capacidade Autoscale. Você pode configurar o maxThroughput valor, que descreve o maior número de Unidades de Solicitação para as quais o banco de dados pode ser aumentado dinamicamente.

Este comando usa o banco de dados especificado no contexto da sessão. Esse banco de dados é o mesmo que você usou no use <database> comando. No momento, o nome do banco de dados não pode ser alterado usando este comando.

Saída

Se o comando for bem-sucedido, ele retornará a seguinte resposta:

{ "ok" : 1 }

Consulte a saída padrão do comando personalizado para os parâmetros na saída.

Exemplo: atualizar a taxa de transferência provisionada associada a um banco de dados

Para atualizar a taxa de transferência provisionada de um banco de dados com nome "test" para 1200 RUs, use o seguinte comando:

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

Exemplo: Atualizar a taxa de transferência de dimensionamento automático associada a um banco de dados

Para atualizar a taxa de transferência provisionada de um banco de dados com nome "test" para 20.000 RUs ou transformá-la em um nível de taxa de transferência de Autoscale, use o seguinte comando:

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

Obter base de dados

O comando get database extension retorna o objeto de banco de dados. O nome do banco de dados é usado a partir do contexto do banco de dados no qual o comando é executado.

{
  customAction: "GetDatabase"
}

A tabela a seguir descreve os parâmetros dentro do comando:

Campo	Tipo	Description
customAction	string	Nome do comando personalizado. O valor deve ser GetDatabase.

Saída

Se o comando for bem-sucedido, a resposta conterá um documento com os seguintes campos:

Campo	Tipo	Description
ok	int	Estado da resposta. 1 == sucesso. 0 == fracasso.
database	string	Nome do banco de dados.
provisionedThroughput	int	Taxa de transferência provisionada definida no banco de dados se o banco de dados estiver usando a taxa de transferência manual no nível do banco de dados
autoScaleSettings	Object	Este objeto contém os parâmetros de capacidade associados ao banco de dados se estiver usando o modo Autoscale. O maxThroughput valor descreve o maior número de Unidades de Solicitação para as quais o banco de dados pode ser aumentado dinamicamente.

Se o comando falhar, uma resposta de comando personalizado padrão será retornada. Consulte a saída padrão do comando personalizado para os parâmetros na saída.

Exemplo: Obter o banco de dados

Para obter o objeto de banco de dados para um banco de dados chamado "test", use o seguinte comando:

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

Se o banco de dados não tiver taxa de transferência associada, a saída será:

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

Se o banco de dados tiver uma taxa de transferência manual no nível de banco de dados associada a ele, a saída mostrará os provisionedThroughput valores:

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

Se o banco de dados tiver uma taxa de transferência de Autoscale no nível de banco de dados associada a ele, a saída mostrará o provisionedThroughput, que descreve o RU/s mínimo para o banco de dados e o autoScaleSettings objeto, incluindo o maxThroughput, que descreve o RU/s máximo para o banco de dados.

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

Criar coleção

O comando create collection extension cria uma nova coleção MongoDB. O nome do banco de dados é usado a partir do contexto de bancos 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 a seguir descreve os parâmetros dentro do comando:

Campo	Type	Obrigatório	Description
customAction	string	Obrigatório	Nome do comando personalizado. O valor deve ser CreateCollection.
collection	string	Necessário	Nome da coleção. Não são permitidos caracteres especiais ou espaços.
offerThroughput	int	Opcional	Taxa de transferência provisionada a ser definida no banco de dados. Se esse parâmetro não for fornecido, o padrão será de no mínimo, 400 RU/s. * Para especificar a taxa de transferência além de 10.000 RU/s, o shardKey parâmetro é necessário.
shardKey	string	Necessário para coleções com grande taxa de transferência	O caminho para a Chave de Fragmento para a coleção fragmentada. Este parâmetro é necessário se você definir mais de 10.000 RU/s no offerThroughput. Se for especificado, todos os documentos inseridos requerem essa chave e valor.
autoScaleSettings	Object	Necessário para o modo de dimensionamento automático	Este objeto contém as configurações associadas ao modo de capacidade Autoscale. Você pode configurar o maxThroughput valor, que descreve o maior número de Unidades de Solicitação para as quais a coleção pode ser aumentada dinamicamente.
indexes	Array	Opcionalmente, configure índices. Este parâmetro é suportado apenas para contas 3.6+.	Quando presente, é necessário um índice sobre _id. Cada entrada na matriz deve incluir uma chave de um ou mais campos, um nome e pode conter opções de índice. Por exemplo, para criar um índice composto exclusivo nos campos a e b usar esta entrada: {key: {a: 1, b: 1}, name:"a_1_b_1", unique: true}.

Saída

Retorna uma resposta de comando personalizado padrão. Consulte a saída padrão 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 nome "testCollection" e os valores padrão, use o seguinte comando:

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

Esta operação resulta em uma nova coleção fixa, sem fragmentos, 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 sem fragmentos

Para criar uma coleção não fragmentada com nome "testCollection" e taxa de transferência provisionada de 1000 RUs, use o seguinte comando:

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

Você pode criar uma coleção com até 10.000 RU/s sem offerThroughput precisar especificar uma chave de estilhaço. Para coleções com maior taxa de transferência, confira a próxima seção.

Exemplo: Criar uma coleção fragmentada

Para criar uma coleção fragmentada com nome "testCollection" e taxa de transferência provisionada de 11.000 RUs e uma shardkey propriedade "a.b", use o seguinte comando:

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

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

Exemplo: Criar uma coleção de Autoscale não fragmentada

Para criar uma coleção não fragmentada nomeada 'testCollection' que usa a capacidade de taxa de transferência Autoscale definida como 4.000 RU/s, use o seguinte comando:

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

Para o autoScaleSettings.maxThroughput valor, você pode especificar um intervalo de 4.000 RU/s a 10.000 RU/s sem uma chave de estilhaço. Para uma taxa de transferência de escala automática mais alta, você precisa especificar o shardKey parâmetro.

Exemplo: Criar uma coleção de Autoscale fragmentada

Para criar uma coleção fragmentada nomeada 'testCollection' com uma chave de estilhaço chamada 'a.b', e que usa a capacidade de taxa de transferência Autoscale definida como 20.000 RU/s, use 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 sua coleção de taxa de transferência provisionada para 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 a seguir descreve os parâmetros dentro do comando:

Campo	Tipo	Description
customAction	string	Nome do comando personalizado. O valor deve ser UpdateCollection.
collection	string	Nome da coleção.
offerThroughput	int	Taxa de transferência provisionada a ser definida na coleção.
autoScaleSettings	Object	Necessário para o modo de dimensionamento automático. Este objeto contém as configurações associadas ao modo de capacidade Autoscale. O maxThroughput valor descreve o maior número de Unidades de Solicitação para as quais a coleção pode ser aumentada dinamicamente.
indexes	Array	Opcionalmente, configure índices. Este parâmetro é suportado apenas para contas 3.6+. Quando presente, o conjunto de índices especificados (incluindo índices em queda) substitui os índices existentes da coleção. É necessário um índice sobre _id. Cada entrada na matriz deve incluir uma chave de um ou mais campos, um nome e pode conter opções de índice. Por exemplo, para criar um índice composto exclusivo nos campos a e b, use esta entrada: {key: {a: 1, b: 1}, name: "a_1_b_1", unique: true}.

Saída

Retorna uma resposta de comando personalizado padrão. Consulte a saída padrão do comando personalizado para os parâmetros na saída.

Exemplo: atualizar a taxa de transferência provisionada associada a uma coleção

Para atualizar a taxa de transferência provisionada de uma coleção com nome "testCollection" para 1200 RUs, use o seguinte comando:

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

Obter coleção

O comando get collection custom retorna o objeto collection.

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

A tabela a seguir descreve os parâmetros dentro do comando:

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

Saída

Se o comando for bem-sucedido, a resposta conterá um documento com os seguintes campos

Campo	Tipo	Description
ok	int	Estado da resposta. 1 == sucesso. 0 == fracasso.
database	string	Nome do banco de dados.
collection	string	Nome da coleção.
shardKeyDefinition	document	Documento de especificação de índice usado como uma chave de estilhaço. Este campo é um parâmetro de resposta opcional.
provisionedThroughput	int	Taxa de transferência provisionada a ser definida na coleção. Este campo é um parâmetro de resposta opcional.
autoScaleSettings	Object	Este objeto contém os parâmetros de capacidade associados ao banco de dados se estiver usando o modo Autoscale. O maxThroughput valor descreve o maior número de Unidades de Solicitação para as quais a coleção pode ser aumentada dinamicamente.

Se o comando falhar, uma resposta de comando personalizado padrão será retornada. Consulte a saída padrão do comando personalizado para os parâmetros na saída.

Exemplo: Obter a coleção

Para obter o objeto de coleção para uma coleção chamada "testCollection", use o seguinte comando:

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

Se a coleção tiver uma capacidade de taxa de transferência associada, ela incluirá o provisionedThroughput valor e a saída será:

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

Se a coleção tiver uma taxa de transferência Autoscale associada, ela incluirá o autoScaleSettings objeto com o maxThroughput parâmetro, que define a taxa de transferência máxima para a qual a coleção aumenta dinamicamente. Além disso, ele também inclui o provisionedThroughput valor, que define a taxa de transferência mínima que essa coleção reduz para se não houver solicitações na coleção:

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

Se a coleção estiver compartilhando a taxa de transferência no nível do banco de dados, no modo Autoscale ou manual, a saída será:

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

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

Paralelização de fluxos de alteração

Ao usar fluxos de alteração em escala, é melhor distribuir uniformemente a carga. O comando a seguir retorna um ou mais tokens de retomada de fluxo de alteração - cada um correspondendo a dados de um único fragmento/partição física (vários fragmentos/partições lógicas podem existir em uma partição física). Cada token de retomada faz com que watch() retorne apenas dados desse fragmento/partição física.

Use db.collection.watch() em cada token de currículo (um thread por token) para dimensionar 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 fragmento/partição física.

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

Execute um thread/processo watch() para cada token de currículo retornado do comando personalizado GetChangeStreamTokens. Aqui está 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() retorna um curser para todos os documentos que foram inseridos, atualizados ou substituídos a partir dessa partição física desde que o comando personalizado GetChangeStreamTokens foi executado. Uma amostra dos dados retornados 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). Esse token de retomada deve ser armazenado e reutilizado se o thread/processo morrer. Esse token de currículo pega de onde você parou e recebe dados somente dessa partição física.

Saída padrão 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 == sucesso. 0 == fracasso.
code	int	Só retornou quando o comando falhou (ou seja, ok == 0). Contém o código de erro MongoDB. Este campo é um parâmetro de resposta opcional.
errMsg	string	Só retornou quando o comando falhou (ou seja, ok == 0). Contém uma mensagem de erro amigável. Este campo é um parâmetro de resposta opcional.

Por exemplo:

{ "ok" : 1 }

Próximos passos

Em seguida, você pode continuar para aprender os seguintes conceitos do Azure Cosmos DB:

• Indexação no Azure Cosmos DB
• Expirar dados no Azure Cosmos DB automaticamente com tempo de vida