Criar uma conta, um banco de dados e uma coleção usando o Azure Cosmos DB for MongoDB

• 8 minutos

O Azure Cosmos DB é uma plataforma como serviço (PaaS) totalmente gerenciada. Para usar esse serviço, primeiro precisaremos criar uma conta do Azure Cosmos DB na assinatura. Depois que a conta for criada, poderemos adicionar o banco de dados, as coleções e os documentos a ela.

Vamos dar uma olhada em algumas maneiras de criar os diferentes elementos de modelo do Azure Cosmos DB for MongoDB.

Criar uma conta, um banco de dados e um contêiner para o Azure Cosmos DB for MongoDB usando o portal do Azure

Uma forma de criar a conta do Azure Cosmos DB e seus elementos é usar o portal do Azure. Neste exemplo, usaremos o portal do Azure para criar uma conta simples do Azure Cosmos DB usando o Azure Cosmos DB for MongoDB. Depois, vamos adicionar um banco de dados e uma coleção. Por enquanto, não precisamos preencher as configurações mais avançadas, que serão abordadas com mais detalhes em módulos posteriores. Neste exemplo, vamos apenas conhecer a guia Informações básicas. Vamos criar a conta e seus elementos.

Criar uma conta para o Azure Cosmos DB for MongoDB

1. No portal do Azure, selecione + Criar um Recurso, escolha Azure Cosmos DB e Criar.

2. Selecione o Azure Cosmos DB for MongoDB.

3. Insira os parâmetros a seguir.

   • Assinatura – Sua assinatura do Azure atual.
   • Grupo de Recursos – Um grupo de recursos do Azure novo ou existente no qual a conta do Azure Cosmos DB será criada.
   • Nome da conta – Um nome exclusivo para a conta do Azure Cosmos DB. Esse nome precisa ser exclusivo no Azure. O URI da conta será mongo.cosmos.azure.com acrescentado ao nome da conta.
   • Localização – A localização geográfica que hospedará a conta do Azure Cosmos DB. Selecione uma localização próxima aos seus usuários ou aplicativos.
   • Modo de capacidade – Como discutimos em uma unidade anterior, você pode selecionar que sua conta use a opção Taxa de transferência provisionada ou Sem servidor. Selecione Taxa de transferência provisionada neste exemplo.
   • Aplicar Desconto de Camada Gratuita – Selecione Não Aplicar neste exemplo.
   • Limitar a taxa de transferência total da conta – Deixe essa opção desmarcada neste exemplo.
   • Versão – Selecione 4.0.

   Observação

   Para aproveitar melhor os recursos com suporte, recomendamos que você use as versões 3.6 ou superiores sempre que possível.

4. Selecione Examinar + Criar e, quando a validação for bem-sucedida, selecione Criar.

Criar um banco de dados e um contêiner para o Azure Cosmos DB for MongoDB

A criação de um banco de dados e um contêiner no portal do Azure é fácil. Vamos primeiro criar um banco de dados.

1. No menu à esquerda da conta do Azure Cosmos DB for MongoDB, selecione Data Explorer.

2. Selecione o menu suspenso à direita do ícone Nova Coleção e selecione Novo Banco de Dados.

   

3. Dê um novo nome ao banco de dados na caixa de texto ID do banco de dados.

4. Embora seja possível definir a opção Provisionar taxa de transferência na caixa de diálogo Novo Banco de Dados, na maioria dos casos, você seleciona a taxa de transferência provisionada no nível do contêiner. Vamos desmarcar a caixa de seleção Provisionar taxa de transferência e selecionar Ok neste exemplo.

   

   Agora, vamos observar o novo banco de dados na seção API do MONGO. Chegou a hora de criar a coleção.

5. Selecione o ícone Nova Coleção.

6. Insira os parâmetros a seguir na caixa de diálogo Nova Coleção.

   • Nome do banco de dados – Você verá que há duas opções aqui, Criar ou Usar existente. Essa opção permite que você crie um banco de dados no momento em que está criando a coleção. Como já criamos um banco de dados nas etapas anteriores, selecione Usar existente e escolha o nome do banco de dados nas opções suspensas.
   • ID da coleção – Esse parâmetro será o nome que você dará à coleção.
   • Fragmentação – O ideal é selecionar Fragmentado. Essa opção permite que o Azure Cosmos DB crie contêineres fragmentados em vários locatários com base na Chave de fragmento. Em contêineres grandes, o Azure Cosmos DB espalha os locatários entre vários nós físicos para atingir um alto grau de escala. Discutiremos a fragmentação em mais detalhes no módulo Design. Selecione Fragmentado.
     • Chave de fragmento – A seleção de Fragmentado exigirá que você adicione uma chave de fragmento. Essa é a chave de partição que define a estratégia de particionamento. Por exemplo, em uma coleção de IoT poderia ser /deviceid ou /region, dependendo da estratégia de particionamento escolhida. Discutiremos a estratégia de particionamento com mais detalhes no módulo Design.
     • Caixa de seleção Provisionar uma taxa de transferência dedicada para esta coleção – O ideal é provisionar a taxa de transferência da coleção como Dimensionamento automático ou Manual. Essa configuração permite que você tenha um controle melhor do custo da coleção individual. Discutiremos a taxa de transferência com mais detalhes no módulo Design. Por enquanto, marque a caixa de seleção e selecione Dimensionamento automático.
     • Taxa de transferência da coleção ou Máximo de RU/s da coleção – Dependendo da seleção de Manual ou Dimensionamento automático, você precisará inserir a Taxa de transferência da coleção ou o Máximo de RU/s da coleção, respectivamente ou, em outras palavras, o modo de taxa de transferência. A principal diferença é que no modo Manual você será cobrado de acordo com o valor de RU/s escolhido, independentemente do uso, e no Dimensionamento automático você será cobrado apenas pelo que usar até o Máximo de RU/s selecionado. Nos dois casos, a coleção começará a ser limitada quando a taxa de transferência atingir o valor selecionado. Deixe o valor predefinido neste exemplo.
     • Repositório Analítico – O repositório analítico do Azure Cosmos DB não faz parte do escopo dessas lições. Examine o artigo Repositório analítico do Azure Cosmos DB para obter mais informações sobre esse tópico.
     • Avançado/Indexação – Discutiremos os índices com mais detalhes no módulo Design. Deixe a caixa de seleção desmarcada.

Agora temos um banco de dados e uma coleção com os quais podemos nos conectar. Na próxima unidade, entraremos em mais detalhes de como se conectar a uma contado Azure Cosmos DB for MongoDB. Antes disso, vamos examinar outra maneira de criar bancos de dados e coleções do Azure Cosmos DB for MongoDB.

Criar um banco de dados e uma coleção do Azure Cosmos DB for MongoDB e se conectar a eles

Você pode criar a conta do Azure Cosmos DB for MongoDB ou se conectar a ela usando Java, Python, Node.js, .NET ou outra linguagem de programação com um driver do MongoDB. Vamos introduzir algumas funções que você usaria para criar esses elementos com algumas das diferentes linguagens. No início deste módulo, afirmamos que os desenvolvedores podem continuar usando drivers, SDKs e ferramentas do MongoDB que já conhecem para criar aplicativos e se conectar ao Azure Cosmos DB. Vamos aproveitar esses drivers e suas propriedades e métodos para programar o acesso e as operações na conta do Azure Cosmos DB for MongoDB.

Criar um banco de dados do Azure Cosmos DB for MongoDB ou se conectar a ele

Você pode usar sua ferramenta de desenvolvimento favorita para criar o aplicativo do Azure Cosmos DB for MongoDB. Vamos aproveitar o driver do MongoDB de cada linguagem de programação respectiva para criar os bancos de dados e as coleções. Vamos examinar o código de conexão com as contas do Azure Cosmos DB for MongoDB e de conexão com o banco de dados products.

const {MongoClient} = require("mongodb");

async function main() {

  // We will discuss connection string in more detail in the next unit of this module.
  // Remember to replace below "YourAzureCosmosDBAccount" with the name of your Azure Cosmos DB 
  // account name and "YourAzureCosmosDBAccountKEY" with the Azure Cosmos DB account key.
  var url = "mongodb://YourAzureCosmosDBAccount:YourAzureCosmosDBAccountKEY@YourAzureCosmosDBAccount.mongo.cosmos.azure.com:10255/?ssl=true&retrywrites=false&replicaSet=globaldb&maxIdleTimeMS=120000&appName=@YourAzureCosmosDBAccount@";

  // define the connection using the MongoClient method ane the url above
  var mongoClient = new MongoClient(url, function(err,client)
      {
          if (err)
          {
              console.log("error connecting")
          }
      }
  );

  // open the connection
  await mongoClient.connect();

  // connect to the database "products"
  var ProductDatabase = mongoClient.db("products");

  // Add code to connect to a collection and add an entry here 

  // close the connection
  mongoClient.close();
}

main();

package com.fabrikam;

import org.bson.Document;
import com.mongodb.MongoClient;
import com.mongodb.MongoClientURI;
import com.mongodb.client.MongoDatabase;
import com.mongodb.client.MongoCollection;
import static com.mongodb.client.model.Filters.eq;

public class App {
  public static void main(String[] args) {

    // We will discuss connection string in more detail in the next unit of this module
    // Remember to replace below "YourAzureCosmosDBAccount" with the name of your Azure Cosmos DB 
    // account name and "YourAzureCosmosDBAccountKEY" with the Azure Cosmos DB account key.
    MongoClientURI uri = new MongoClientURI("mongodb://YourAzureCosmosDBAccount:YourAzureCosmosDBAccountKEY@YourAzureCosmosDBAccount.mongo.cosmos.azure.com:10255/?ssl=true&retrywrites=false&replicaSet=globaldb&maxIdleTimeMS=120000&appName=@YourAzureCosmosDBAccount@");

    MongoClient mongoClient = null;
    try {
          // We use the "MongoClient" method and the "uri" value to connect to the account 
          mongoClient = new MongoClient(uri);

          // Connecting to your database is as simple as calling the GetDatabase method
          MongoDatabase ProductDatabase = mongoClient.getDatabase("products");

          // Add code to connect to a collection and add an entry here 
    }
    finally {
      if (mongoClient != null) {
        mongoClient.close();
      }
    }
  }
}

import pymongo

# We will discuss connection string in more detail in the next unit of this module
#  Remember to replace below "YourAzureCosmosDBAccount" with the name of your Azure Cosmos DB 
#  account name and "YourAzureCosmosDBAccountKEY" with the Azure Cosmos DB account key.
uri = "mongodb://YourAzureCosmosDBAccount:YourAzureCosmosDBAccountKEY@YourAzureCosmosDBAccount.mongo.cosmos.azure.com:10255/?ssl=true&retrywrites=false&replicaSet=globaldb&maxIdleTimeMS=120000&appName=@YourAzureCosmosDBAccount@"

# We use the "MongoClient" method and the "uri" value to connect to the account 
client = pymongo.MongoClient(uri)

# To connect to the database, use the connection variable ("client" in this case), and the database name
# inside brackets
ProductDatabase = client["products"]

# Add code to connect to a collection and add an entry here 

using MongoDB.Driver;

  public class Products {
    public int ProductId { get; set; }
    public string name { get; set; }
  }

class test {
  public static void Main (string[] args) {

    // We will discuss connection string in more detail in the next section of this module
    // Remember to replace below "YourAzureCosmosDBAccount" with the name of your Azure Cosmos DB 
    // account name and "YourAzureCosmosDBAccountKEY" with the Azure Cosmos DB account key.
    string connectionString = 
      @"mongodb://calopezdp420mongodb01:6CKYlfyagNSQ2ZmP8XEmc2Z6gozF6NkIJ6w1WoYFehZ8Z3842jEhz7xRBl7KeGX2QajQt54Y2g9bJ9MZXU8Z9Q==@calopezdp420mongodb01.mongo.cosmos.azure.com:10255/?ssl=true&retrywrites=false&replicaSet=globaldb&maxIdleTimeMS=120000&appName=@calopezdp420mongodb01@";

    MongoClientSettings settings = MongoClientSettings.FromUrl(new MongoUrl(connectionString));

    // We use the "MongoClient" method and the "settings" value to connect to the account 
    var mongoClient = new MongoClient(settings);

    // Connecting to your database is as simple as calling the GetDatabase method
    var ProductDatabase = mongoClient.GetDatabase("products");

    // Add code to connect to a collection and add an entry here 
  }
}

É muito simples. Depois de fazer a conexão usando o driver, criamos um banco de dados ou apontamos a um existente com o GetDatabase ou métodos semelhantes, dependendo da linguagem. Agora, o aplicativo pode usar a variável ProductDatabase para fazer referência ao banco de dados desejado. A criação de uma coleção ou a conexão a ela será tão simples quanto foi a criação de um banco de dados.

Criar uma coleção do Azure Cosmos DB for MongoDB

Para criar ou acessar uma coleção existente, usaremos um método de obtenção de coleção ou de referência, dependendo da linguagem de programação. Vamos adicionar um código ao exemplo anterior para criar uma coleção ou se conectar a ela e adicionar uma entrada.

          // Add code to connect to a collection and add and find an entry here 
          var collection = ProductDatabase.collection('documents');
          var insertResult = await collection.insertOne({ ProductId: 1, name: "bread" });

          // return data where ProductId = 1
          const findProduct = await collection.find({ProductId: 1});
          await findProduct.forEach(console.log);

          // Add code to connect to a collection and add and find an entry here 
          MongoCollection collection = ProductDatabase.getCollection("products");

          collection.insertOne(new Document()
                      .append("ProductId", 1)
                      .append("name", "bread"));

          // return data where ProductId = 1
          Document findProduct = (Document) collection.find(eq("ProductId", 1)).first();
          System.out.println(findProduct.toJson());

# Add code to connect to a collection and add an entry here 
collection = ProductDatabase["products"]
collection.insert_one({ "ProductId": 1, "name": "bread" })

    // Add code to connect to a collection and add an entry here 
    var ProductCollection = ProductDatabase.GetCollection<Products>("products");

    Products Product = new Products {ProductId=1,name="bread"};
    ProductCollection.InsertOne (Product);

Na próxima unidade, veremos exatamente como criamos a cadeia de conexão.

Usar comandos de extensão do MongoDB para gerenciar dados armazenados na API do Azure Cosmos DB para MongoDB

Como já abordamos, o Azure Cosmos DB for MongoDB oferece a capacidade de usar os mesmos drivers e o mesmo código que usamos para acessar e criar objetos em um servidor do MongoDB na conta do Azure Cosmos DB. No entanto, o uso desse código para criar bancos de dados e coleções usará os parâmetros de criação padrão do Azure Cosmos DB. Para aproveitar os recursos do Azure Cosmos DB, precisaremos controlar os parâmetros de criação de banco de dados e de coleção, como taxa de transferência, dimensionamento automático, atribuição de chaves de fragmento e definição de índices. O Azure Cosmos DB for MongoDB oferece essa capacidade usando comandos estendidos para definir esses parâmetros. Esses comandos permitem codificar instruções mais precisas de como criar ou modificar os bancos de dados e as coleções especificamente para o Azure Cosmos DB.

O Azure Cosmos DB for MongoDB oferece comandos de extensão para os seguintes tipos de solicitação:

• Criar banco de dados
• Atualizar banco de dados
• Obter banco de dados
• Criar coleção
• Atualizar coleção
• Obter coleção

Os drivers do MongoDB oferecem uma função para executar um comando em um banco de dados. Usaremos essa função para enviar comandos estendidos ao Azure Cosmos DB. Vamos dar uma olhada no código para criar uma coleção de dispositivos IoT com uma taxa de transferência de 2000 RUs e a chave de fragmento DeviceId.

    // create the Devices collection with a throughput of 2000 RUs and with DeviceId as the sharding key
    var result = IOTDatabase.command({customAction: "CreateCollection", collection: "Devices", offerThroughput: 2000, shardKey: "DeviceId"});

      // create the Devices collection with a throughput of 2000 RUs and with DeviceId as the sharding key
      Document DevCollectionDef = new Document();
      DevCollectionDef.append("customAction", "CreateCollection");
      DevCollectionDef.append("collection", "Devices");
      DevCollectionDef.append("offerThroughput", 2000);
      DevCollectionDef.append("shardKey", "DeviceId");

      Document result = IOTDatabase.runCommand(DevCollectionDef);

      # create the Devices collection with a throughput of 2000 RUs and with DeviceId as the sharding key
      IOTDatabase.command({'customAction': "CreateCollection", 'collection': "Devices", 'offerThroughput': 2000, 'shardKey': "DeviceId"})

      // create the Devices collection with a throughput of 1000 RUs and with EmployeeId as the sharding key
      var result = IOTDatabase.RunCommand<BsonDocument>(@"{customAction: ""CreateCollection"", collection: ""Devices"", offerThroughput: 2000, shardKey: ""DeviceId""}");

De maneira semelhante, podemos modificar uma coleção ou criar ou modificar um banco de dados. Para saber mais, examine o artigo Usar comandos de extensão do MongoDB para gerenciar dados armazenados na API do Azure Cosmos DB para MongoDB.