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

Concluído

O Azure Cosmos DB é uma plataforma como serviço (PaaS) totalmente gerenciada. Para usar esse serviço, precisamos primeiro criar uma conta do Azure Cosmos DB em nossa assinatura. Uma vez que nossa conta é criada, podemos adicionar banco de dados, coleções e documentos dentro dela.

Examinamos algumas maneiras de criar os diferentes elementos de modelo do Azure Cosmos DB para MongoDB.

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

Uma maneira de criar nossa conta do Azure Cosmos DB e seus elementos é usando o portal do Azure. Neste exemplo, usamos o portal do Azure para criar uma conta do Azure Cosmos DB usando o Azure Cosmos DB para MongoDB. Em seguida, adicionamos um banco de dados e uma coleção. Por enquanto, não se preocupe em preencher configurações mais avançadas que abordamos com mais detalhes em módulos posteriores. Para este exemplo, vamos apenas revisar a guia Noções básicas. Vamos criar a nossa conta e os seus elementos.

Criar uma conta para o Azure Cosmos DB para MongoDB

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

2. Selecione Azure Cosmos DB para MongoDB.

3. Insira os seguintes parâmetros.

   • Assinatura - Sua assinatura atual do Azure.
   • Grupo de Recursos - Um Grupo de Recursos do Azure novo ou existente no qual criar a conta do Azure Cosmos DB.
   • Nome da Conta - Um nome exclusivo para sua conta do Azure Cosmos DB. Esse nome deve ser exclusivo em todo o Azure. O URI da sua conta mongo.cosmos.azure.com anexado ao nome da sua conta.
   • Localização - A localização geográfica que hospeda sua conta do Azure Cosmos DB. Normalmente, você deve selecionar um local próximo aos seus usuários ou aplicativos.
   • Modo de capacidade - Como discutimos em uma unidade anterior, você pode selecionar para sua conta usar a taxa de transferência provisionada ou sem servidor. Selecione Taxa de transferência provisionada para este exemplo.
   • Aplicar desconto de nível gratuito - Selecione Não aplicar para este exemplo.
   • Limitar a taxa de transferência total da conta - Deixe desmarcado para este exemplo.
   • Versão - Selecione 4.0.

   Nota

   Para tirar melhor partido das funcionalidades suportadas, recomendamos que utilize as versões 3.6+ sempre que possível.

4. Selecione Rever + Criar e, numa validação bem-sucedida, selecione Criar.

Nota

Pode levar vários minutos para criar sua conta do Azure Cosmos DB.

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

Criar um banco de dados e um contêiner no portal do Azure é simples, vamos primeiro criar um banco de dados.

1. No menu esquerdo da conta do Azure Cosmos DB para MongoDB, selecione Data Explorer.

2. Selecione a lista suspensa à 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 pudéssemos definir a taxa de transferência de provisionamento na caixa de diálogo Novo banco de dados , na maioria dos casos, você selecionaria sua taxa de transferência provisionada no nível do contêiner. Vamos desmarcar a caixa de seleção Taxa de transferência de provisionamento e selecionar Ok para este exemplo.

   

   Devemos agora observar nosso novo banco de dados na seção API MONGO. Está na hora de criar a nossa nova coleção.

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

6. Insira os seguintes parâmetros na caixa de diálogo Nova coleção .

   • Nome do banco de dados - Você percebe que tem duas opções aqui, Criar novo ou Usar existente. Essa opção permite que você crie um novo banco de dados no momento em que estiver criando a nova coleção. Como já criamos um novo banco de dados em nossas etapas anteriores, selecione Usar existente e escolha o nome do banco de dados nas opções suspensas.
   • ID da coleção - Este parâmetro é o nome que você dá à sua coleção.
   • Compartilhamento - Normalmente, gostaríamos de selecionar Fragmentado. Essa opção permite que o Azure Cosmos DB crie contêineres que são fragmentados em vários locatários com base na chave Shard. Com contêineres grandes, o Azure Cosmos DB distribui seus locatários por vários nós físicos para alcançar um alto grau de escala. Discutimos a fragmentação em mais detalhes no módulo Design . Selecione Fragmentado.
     • Tecla Shard - Selecionar Sharded requer que você adicione uma tecla Shard. Esta chave é a chave de partição que define a sua estratégia de particionamento. Por exemplo, na coleção e IoT (Internet of Things) pode ser /deviceid ou talvez /region , dependendo da estratégia de particionamento escolhida. Discutimos a estratégia de particionamento em mais detalhes no módulo Design .
     • Caixa de seleção Provisionar taxa de transferência dedicada para esta coleção - Normalmente, você deseja provisionar a taxa de transferência de sua coleção como Autoscale ou Manual. Esta definição permite-lhe ter um melhor controlo do custo da sua 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 de coleta ou Coleção Max RU/s - Dependendo se você selecionou Manual ou Autoscale, você precisa inserir a taxa de transferência de coleta ou Collection Max RU/s, respectivamente, ou, em outras palavras, o modo de taxa de transferência. A principal diferença é que no modo Manual cobra o valor do RU/s escolhido, independentemente de você usá-los ou não. O dimensionamento automático cobra apenas o que você usa até o máximo de RU/s selecionado. Em ambos os casos, sua coleção começa a ser limitada assim que sua taxa de transferência atinge o valor selecionado. Deixe o valor predefinido para este exemplo.
     • Repositório analítico - O repositório analítico do Azure Cosmos DB está além do escopo dessas lições. Consulte o artigo O que é o 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 marcada.

Agora devemos ter um banco de dados e uma coleção para nos conectarmos. Na próxima unidade, entraremos em mais detalhes sobre como se conectar a uma conta do Azure Cosmos DB para MongoDB. Antes disso, vamos analisar outra maneira de criar nossos bancos de dados e coleções do Azure Cosmos DB para MongoDB.

Criar ou conectar-se a um banco de dados e coleção para o Azure Cosmos DB para MongoDB

Você deve ser capaz de criar ou se conectar à sua conta do Azure Cosmos DB para MongoDB usando Java, Python, Node.js, .NET ou outra linguagem de programação com um driver MongoDB. Vamos apresentar algumas funções que você usaria para criar esses elementos usando 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 suas propriedades e métodos para programar nosso acesso e operações em nossa conta do Azure Cosmos DB para MongoDB.

Criar ou conectar-se a um banco de dados para o Azure Cosmos DB para MongoDB

Você pode usar sua ferramenta de desenvolvimento favorita para criar seu aplicativo Azure Cosmos DB para MongoDB. Usamos o driver MongoDB para cada linguagem de programação respetiva para criar nossos bancos de dados e coleções. Vamos revisar o código para se conectar às contas do Azure Cosmos DB para MongoDB e para se conectar ao banco de dados de produtos .

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

C#

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

É tão simples, uma vez que nos conectamos usando o driver, criamos um novo banco de dados ou apontamos para um existente com o GetDatabase ou métodos semelhantes, dependendo do idioma. Nosso aplicativo agora pode usar a variável ProductDatabase para fazer referência ao banco de dados desejado. Criar ou conectar-se a uma coleção é tão simples quanto criar um novo banco de dados.

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

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

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

C#

    // 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 como exatamente criamos nossa cadeia de conexão.

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

Como discutimos anteriormente, o Azure Cosmos DB para MongoDB nos dá a capacidade de usar os mesmos drivers e código que usamos para acessar e criar nossos objetos em um servidor MongoDB para nossa conta do Azure Cosmos DB. No entanto, usar esse código para criar nossos 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 ser capazes de controlar nossos parâmetros de criação de banco de dados e coleção, como taxa de transferência, dimensionamento automático, atribuição de chaves de estilhaço e definição de índices. O Azure Cosmos DB para MongoDB nos dá essa capacidade usando comandos estendidos para definir esses parâmetros. Esses comandos nos permitem codificar instruções mais precisas sobre como criar ou modificar nossos bancos de dados e coleções especificamente para o Azure Cosmos DB.

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

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

Os drivers MongoDB fornecem uma função para executar um comando em um banco de dados, usamos essa função para enviar nossos comandos estendidos para o 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 uma chave de fragmento de 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"})

C#

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

Da mesma forma, podemos modificar uma coleção ou criar ou modificar um banco de dados. Consulte o artigo Usar comandos de extensão do MongoDB para gerenciar dados armazenados na API do Azure Cosmos DB para MongoDB para obter mais informações.