Crie uma conta, banco de dados e 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 precisamos 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, usamos o portal do Azure para criar uma conta do Azure Cosmos DB usando o Azure Cosmos DB for MongoDB. Depois, adicionamos 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. Para este exemplo, vamos apenas examinar a guia Noções básicas. Vamos criar nossa conta e seus elementos.

Criar uma conta para o Azure Cosmos DB for MongoDB

No portal do Azure, selecione + Criar um Recurso, escolha Azure Cosmos DB e Criar.
Selecione a opção Azure Cosmos DB para MongoDB.
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 sua conta tem mongo.cosmos.azure.com anexado ao nome da conta.
- Localização – A localização geográfica que hospeda 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.
Selecione Examinar + Criar e, quando a validação for bem-sucedida, selecione Criar.

Observação

Poderão ser necessários alguns minutos para criar a conta do Azure Cosmos DB.

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.

No menu à esquerda da conta do Azure Cosmos DB for MongoDB, selecione Data Explorer.
Selecione o menu suspenso à direita do ícone Nova Coleção e selecione Novo Banco de Dados.
Dê um novo nome ao banco de dados na caixa de texto ID do banco de dados.
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. É hora de criar nossa nova coleção.
Selecione o ícone Nova Coleção.
Insira os parâmetros a seguir na caixa de diálogo Nova Coleção.
- Nome do banco de dados – Você vê 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 é o nome que você dá à coleção.
- Fragmentação – O ideal é selecionar Fragmentado. Essa opção permite que o Azure Cosmos DB crie contêineres divididos entre vários locatários com base na chave de partição. Com grandes contêineres, o Azure Cosmos DB distribui os locatários entre vários nós físicos para alcançar um alto nível de escalabilidade. Discutimos a fragmentação em mais detalhes no módulo Design. Selecione Sharded.
  - Chave de fragmento – A seleção de Fragmentado exige que você adicione uma Chave de fragmento. Essa chave é a chave de partição que define a sua estratégia de particionamento. Por exemplo, na coleção IoT (Internet das Coisas) pode ser /deviceid ou talvez /region, dependendo da estratégia de particionamento escolhida. Discutimos 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. Discutimos 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ê precisa 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ê cobra o valor escolhido pelas RU/s, independentemente de usá-las ou não. O dimensionamento automático cobra apenas o que você usa até as RU/s máximas selecionadas. Nos dois casos, a coleção começa a ser limitada quando a taxa de transferência atinge 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 – discutimos 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 sobre como se conectar a uma conta do Azure Cosmos DB para 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 com os quais estão familiarizados para se conectar ao Azure Cosmos DB e criar aplicativos. Usamos esses drivers e as respectivas propriedades e métodos para programar nosso acesso e operações em nossa conta do Azure Cosmos DB para 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. Usamos 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.

Node.js

import { DefaultAzureCredential, ClientSecretCredential } from "@azure/identity";
const { MongoClient, ObjectId } = require('mongodb');
import axios from "axios";

async function main() {
  // Environment variables
  const endpoint = process.env.AZURE_COSMOS_RESOURCEENDPOINT;
  const listConnectionStringUrl = process.env.AZURE_COSMOS_LISTCONNECTIONSTRINGURL;
  const scope = process.env.AZURE_COSMOS_SCOPE;

  // Uncomment the corresponding lines for the authentication type you want to use.
  // For system-assigned managed identity.
  // const credential = new DefaultAzureCredential();

  // For user-assigned managed identity.
  // const clientId = process.env.AZURE_COSMOS_CLIENTID;
  // const credential = new DefaultAzureCredential({
  //     managedIdentityClientId: clientId
  // });

  // For service principal.
  // const tenantId = process.env.AZURE_COSMOS_TENANTID;
  // const clientId = process.env.AZURE_COSMOS_CLIENTID;
  // const clientSecret = process.env.AZURE_COSMOS_CLIENTSECRET;
  // const credential = new ClientSecretCredential(tenantId, clientId, clientSecret);

  // Acquire the access token
  const accessToken = await credential.getToken(scope);

  // Get the connection string
  const config = {
    method: 'post',
    url: listConnectionStringUrl,
    headers: {
        'Authorization': 'Bearer ${accessToken.token}'
    }
  };
  const response = await axios(config);
  const keysDict = response.data;
  const connectionString = keysDict['connectionStrings'][0]['connectionString'];

  // Connect to Azure Cosmos DB for MongoDB
  const client = new MongoClient(connectionString);

  try {
    // Open the connection
    await client.connect();

    // Connect to the database "products"
    const ProductDatabase = client.db('products');

    // Add code to connect to a collection and add an entry here
  } catch (err) {
    console.error("An error occurred:", err);
  } finally {
    // Close the connection
    await client.close();
  }
}

main().catch((err) => console.error("Unhandled error:", err));

Java

package com.fabrikam;

import com.mongodb.MongoClient;
import com.mongodb.MongoClientURI;
import com.mongodb.client.MongoCollection;
import com.mongodb.client.MongoDatabase;
import com.mongodb.client.model.Filters;
import javax.net.ssl.*;
import java.net.InetSocketAddress;
import com.azure.identity.*;
import com.azure.core.credential.*;
import java.net.http.*;
import java.net.URI;

public class App {
  public static void main(String[] args) {
    // Environment variables
    String endpoint = System.getenv("AZURE_COSMOS_RESOURCEENDPOINT");
    String listConnectionStringUrl = System.getenv("AZURE_COSMOS_LISTCONNECTIONSTRINGURL");
    String scope = System.getenv("AZURE_COSMOS_SCOPE");

    // Uncomment the corresponding lines for the authentication type you want to use.
    // For system-assigned managed identity.
    // DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder().build();

    // For user-assigned managed identity.
    // DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder()
    //     .managedIdentityClientId(System.getenv("AZURE_COSMOS_CLIENTID"))
    //     .build();

    // For service principal.
    // ClientSecretCredential defaultCredential = new ClientSecretCredentialBuilder()
    //     .clientId(System.getenv("AZURE_COSMOS_CLIENTID"))
    //     .clientSecret(System.getenv("AZURE_COSMOS_CLIENTSECRET"))
    //     .tenantId(System.getenv("AZURE_COSMOS_TENANTID"))
    //     .build();

    MongoClient mongoClient = null;

    try {
      // Acquire the access token
      AccessToken accessToken = defaultCredential
          .getToken(new TokenRequestContext().addScopes(scope))
          .block();
      String token = accessToken.getToken();

      // Retrieve the connection string
      HttpClient client = HttpClient.newBuilder().build();
      HttpRequest request = HttpRequest.newBuilder()
          .uri(new URI(listConnectionStringUrl))
          .header("Authorization", "Bearer " + token)
          .POST(HttpRequest.BodyPublishers.noBody())
          .build();
      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

      JSONParser parser = new JSONParser();
      JSONObject responseBody = parser.parse(response.body());
      List<Map<String, String>> connectionStrings = responseBody.get("connectionStrings");
      String connectionString = connectionStrings.get(0).get("connectionString");

      // Connect to Azure Cosmos DB for MongoDB
      MongoClientURI uri = new MongoClientURI(connectionString);
      mongoClient = new MongoClient(uri);

      // Connect to the database
      MongoDatabase ProductDatabase = mongoClient.getDatabase("products");

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

    } catch (Exception e) {
      e.printStackTrace();
    } finally {
      if (mongoClient != null) {
        mongoClient.close();
      }
    }
  }
}

Python

import os
import pymongo
import requests
from azure.identity import ManagedIdentityCredential, ClientSecretCredential

# Environment variables
endpoint = os.getenv('AZURE_COSMOS_RESOURCEENDPOINT')
listConnectionStringUrl = os.getenv('AZURE_COSMOS_LISTCONNECTIONSTRINGURL')
scope = os.getenv('AZURE_COSMOS_SCOPE')

# Uncomment the following lines corresponding to the authentication type you want to use.
# For system-assigned managed identity
# cred = ManagedIdentityCredential()

# For user-assigned managed identity
# managed_identity_client_id = os.getenv('AZURE_COSMOS_CLIENTID')
# cred = ManagedIdentityCredential(client_id=managed_identity_client_id)

# For service principal
# tenant_id = os.getenv('AZURE_COSMOS_TENANTID')
# client_id = os.getenv('AZURE_COSMOS_CLIENTID')
# client_secret = os.getenv('AZURE_COSMOS_CLIENTSECRET')
# cred = ClientSecretCredential(tenant_id=tenant_id, client_id=client_id, client_secret=client_secret)

# Get the connection string
session = requests.Session()
token = cred.get_token(scope)
response = session.post(listConnectionStringUrl, headers={"Authorization": "Bearer {}".format(token.token)})
keys_dict = response.json()
conn_str = keys_dict["connectionStrings"][0]["connectionString"]

# Connect to Azure Cosmos DB for MongoDB
client = pymongo.MongoClient(conn_str)

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

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

using MongoDB.Driver;
using Azure.Identity;
using Azure.Core;
using System;
using System.Net.Http;
using System.Text.Json;
using System.Collections.Generic;
using System.Threading.Tasks;

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

class test
{
  public static async Task Main(string[] args)
  {
      // Environment variables
      var endpoint = Environment.GetEnvironmentVariable("AZURE_COSMOS_RESOURCEENDPOINT");
      var listConnectionStringUrl = Environment.GetEnvironmentVariable("AZURE_COSMOS_LISTCONNECTIONSTRINGURL");
      var scope = Environment.GetEnvironmentVariable("AZURE_COSMOS_SCOPE");

      // Uncomment the corresponding lines for the authentication type you want to use.
      // For system-assigned identity.
      // var tokenProvider = new DefaultAzureCredential();

      // For user-assigned identity.
      // var tokenProvider = new DefaultAzureCredential(
      //     new DefaultAzureCredentialOptions
      //     {
      //         ManagedIdentityClientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID")
      //     });

      // For service principal.
      // var tenantId = Environment.GetEnvironmentVariable("AZURE_COSMOS_TENANTID");
      // var clientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID");
      // var clientSecret = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTSECRET");
      // var tokenProvider = new ClientSecretCredential(tenantId, clientId, clientSecret);

      // Acquire the access token.
      AccessToken accessToken = await tokenProvider.GetTokenAsync(
          new TokenRequestContext(scopes: new[] { scope }));

      // Get the connection string.
      using var httpClient = new HttpClient();
      httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken.Token}");
      var response = await httpClient.PostAsync(listConnectionStringUrl, null);
      response.EnsureSuccessStatusCode();
      var responseBody = await response.Content.ReadAsStringAsync();

      // Parse the connection string.
      var connectionStrings = JsonSerializer.Deserialize<Dictionary<string, List<Dictionary<string, string>>>>(responseBody);
      string connectionString = connectionStrings["connectionStrings"][0]["connectionString"];

      // Initialize the MongoClient with the connection string.
      var mongoClient = new MongoClient(connectionString);

      // Connect to the "products" database.
      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 é tão simples quanto foi a criação de um banco de dados.

Criar uma coleção no Azure Cosmos DB para MongoDB

Para criar ou acessar uma coleção existente, usamos 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.

Node.js

          // 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);

Java

          // 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());

Python

# 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 usa os parâmetros de criação padrão do Azure Cosmos DB. Para aproveitar os recursos do Azure Cosmos DB, precisamos 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. Usamos 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 (unidades de solicitação) e a chave de fragmento DeviceId.

Node.js

    // 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"});

Java

      // 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);

Python

      # 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.

Comentários

Esta página foi útil?