Creación de una cuenta, una base de datos y una colección mediante Azure Cosmos DB for MongoDB

Completado

Azure Cosmos DB es una plataforma como servicio (PaaS) totalmente administrada. Para usar este servicio, primero es necesario crear una cuenta de Azure Cosmos DB en nuestra suscripción. Una vez creada la cuenta, podemos agregar una base de datos, colecciones y documentos dentro de ella.

Se examinarán un par de formas de crear los distintos elementos del modelo de Azure Cosmos DB for MongoDB.

Creación de una cuenta, una base de datos y un contenedor para Azure Cosmos DB for MongoDB mediante Azure Portal

Una manera de crear nuestra cuenta de Azure Cosmos DB y sus elementos es usar Azure Portal. En este ejemplo, se usa Azure Portal para crear una cuenta de Azure Cosmos DB mediante Azure Cosmos DB for MongoDB. A continuación, agregamos una base de datos y una colección. Por el momento, no se preocupe por rellenar configuraciones más avanzadas que tratamos con más detalle en módulos posteriores. En este ejemplo, simplemente revise la pestaña Aspectos básicos. Vamos a crear nuestra cuenta y sus elementos.

Creación de una cuenta para Azure Cosmos DB for MongoDB

1. En Azure Portal, seleccione + Crear un recurso, seleccione Azure Cosmos DB, y Crear.

2. Seleccione Azure Cosmos DB for MongoDB.

3. Introduzca los siguientes parámetros.

   • Suscripción: su suscripción actual a Azure.
   • Grupo de recursos: un grupo de recursos de Azure nuevo o existente en el que crear la cuenta de Azure Cosmos DB.
   • Nombre de cuenta: un nombre único para su cuenta de Azure Cosmos DB. Este nombre debe ser único en Azure. El URI de la cuenta tiene mongo.cosmos.azure.com anexado al nombre de la cuenta.
   • Ubicación: La ubicación geográfica que hospeda la cuenta de Azure Cosmos DB. Normalmente, debe seleccionar una ubicación cercana a los usuarios o aplicaciones.
   • Modo de capacidad: como se ha explicado en una unidad anterior, puede seleccionar que la cuenta use Rendimiento aprovisionado o Sin servidor. Seleccione Rendimiento aprovisionado para este ejemplo.
   • Aplicar descuento por nivel Gratis: seleccione No aplicar para este ejemplo.
   • Limitar el rendimiento total de la cuenta: se debe dejar desactivado para este ejemplo.
   • Versión: seleccione 4.0.

   Nota

   Para aprovechar mejor las características admitidas, se recomienda usar las versiones 3.6 y posteriores siempre que sea posible.

4. Seleccione Revisar y crear y, tras una validación correcta, seleccione Crear.

Nota

La cuenta de Azure Cosmos DB puede tardar varios minutos en crearse.

Creación de una base de datos y un contenedor para Azure Cosmos DB for MongoDB

La creación de una base de datos y un contenedor en Azure Portal es directa. Primero, vamos a crear una base de datos.

1. En el menú de la izquierda Azure Cosmos DB for MongoDB, seleccione Data Explorer.

2. Seleccione la lista desplegable situada a la derecha del icono Nueva colección y seleccione Nueva base de datos.

   

3. Asigne un nombre nuevo a la base de datos en el cuadro de texto Id. de base de datos.

4. Aunque podríamos definir el Rendimiento de aprovisionamiento en el cuadro de diálogo Nueva base de datos, en la mayoría de los casos seleccionará el rendimiento aprovisionado en el nivel de contenedor. Desactive la casilla Aprovisionar rendimiento y seleccione Aceptar para este ejemplo.

   

   Ahora deberíamos ver nuestra nueva base de datos en la sección API de MONGO. Es el momento de crear una nueva colección.

5. Seleccione el icono Nueva colección.

6. Escriba los parámetros siguientes en el cuadro de diálogo Nueva colección.

   • Nombre de base de datos: Observe que tiene dos opciones aquí, Crear nuevo, o Usar existente. Esta opción permite crear una nueva base de datos en el momento en que se crea la nueva colección. Puesto que ya hemos creado una nueva base de datos en nuestros pasos anteriores, seleccione Usar existente y elija el nombre de la base de datos en las opciones del menú desplegable.
   • Identificador de colección: Este parámetro es el nombre que asigna a la colección.
   • Particionamiento: normalmente seleccionará Particionado. Esta opción permite a Azure Cosmos DB crear contenedores particionados en varios inquilinos en función de la clave de partición. Con los contenedores grandes, Azure Cosmos DB distribuye los inquilinos entre varios nodos físicos para lograr un alto grado de escala. Se describe el particionamiento con más detalle en el módulo Diseño. Seleccione Particionado.
     • Clave de partición: Al seleccionar Particionado, será necesario agregar una Clave de partición. Esta clave es la clave de partición que define la estrategia de creación de particiones. Por ejemplo, en la colección IoT (Internet de las cosas) podría ser /deviceid o quizás /region en función de la estrategia de creación de particiones que elija. Se describe la estrategia de creación de particiones con más detalle en el módulo Diseño.
     • Casilla Aprovisionar rendimiento dedicado para esta recopilación: Normalmente quiere aprovisionar el rendimiento de la colección como Escalado automático o Manual. Esta configuración le permite tener un mejor control del costo de la colección individual. Se describe el rendimiento con más detalle en el módulo Diseño. Por ahora, active la casilla y seleccione Escalabilidad automática.
     • Rendimiento de recopilación o Recopilación máxima RU/s: Dependiendo de si seleccionó Manual o Escalado automático debe especificar el Rendimiento de la colección o Recopilación máxima RU/s, respectivamente, o en otras palabras, el modo de rendimiento. La principal diferencia es que en modo Manual cobra la cantidad elegida por las RU/s elegidas independientemente de si las usa o no. Escalabilidad automática solo cobra lo que usa hasta el máximo de RU/s que seleccionó. En cualquier caso, la colección inicia la limitación una vez que su rendimiento alcanza el valor seleccionado. Deje el valor predefinido para este ejemplo.
     • Almacén analítico: el almacén analítico de Azure Cosmos DB está fuera del ámbito de estas lecciones. Consulte el artículo ¿Qué es el almacén analítico de Azure Cosmos DB? para obtener más información sobre el tema.
     • Avanzado/Indexación: Hablaremos de los índices en más detalle en el módulo Diseño. Deje desactivada la casilla.

Ahora debería tener una base de datos y una colección a la que conectarse. En la unidad siguiente, se verá con más detalle cómo conectarse a una cuenta de Azure Cosmos DB for MongoDB. Antes de eso, se revisará otra manera de crear las colecciones y bases de datos de Azure Cosmos DB for MongoDB.

Creación o conexión a una base de datos y colección para Azure Cosmos DB for MongoDB

Debe poder crear o conectarse a su cuenta de Azure Cosmos DB for MongoDB mediante Java, Python, Node.js, .NET u otro lenguaje de programación con un controlador de MongoDB. Vamos a introducir algunas funciones que usaría para crear estos elementos mediante algunos de los distintos lenguajes. Al principio de este módulo, hemos indicado que los desarrolladores pueden seguir usando controladores, SDK y herramientas de MongoDB con las que están familiarizados para conectarse a Azure Cosmos DB y crear aplicaciones. Usamos esos controladores y sus propiedades y métodos para programar el acceso y las operaciones en nuestra cuenta de Azure Cosmos DB for MongoDB.

Creación o conexión a una base de datos para Azure Cosmos DB for MongoDB

Puede usar la herramienta de desarrollo que prefiera para crear la aplicación de Azure Cosmos DB for MongoDB. Usamos el controlador MongoDB para cada lenguaje de programación respectivo para crear nuestras bases de datos y colecciones. Ahora se revisará el código para conectarse a las cuentas de Azure Cosmos DB for MongoDB y a la base de datos 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

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

Es tan sencillo, una vez que nos conectamos mediante el controlador, creamos una nueva base de datos o apuntamos a una existente con la GetDatabase o métodos similares en función del idioma. Nuestra aplicación ahora puede usar la variable ProductDatabase para hacer referencia a la base de datos deseada. Crear o conectarse a una colección es tan sencillo como era crear una nueva base de datos.

Creación de una colección para Azure Cosmos DB for MongoDB

Para crear o acceder a una colección existente, usamos un método get collection o una referencia en función del lenguaje de programación. Vamos a agregar código al ejemplo anterior para crear o conectarse a una colección y agregar una entrada en esa colección.

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

En la siguiente unidad, veremos cómo crear exactamente nuestra cadena de conexión.

Usa comandos de la extensión de MongoDB para administrar los datos almacenados en la API de Azure Cosmos DB para MongoDB

Como se ha explicado antes, Azure Cosmos DB for MongoDB ofrece la capacidad de usar los mismos controladores y código que se utilizan a fin de acceder a los objetos y crearlos en un servidor de MongoDB para la cuenta de Azure Cosmos DB. Sin embargo, el uso de ese código para crear nuestras bases de datos y colecciones usa los parámetros de creación predeterminados de Azure Cosmos DB. Para aprovechar las características de Azure Cosmos DB, es necesario poder controlar nuestros parámetros de creación de bases de datos y recopilación, como el rendimiento, el escalado automático, la asignación de claves de partición y la definición de índices. Azure Cosmos DB for MongoDB ofrece esta capacidad mediante el uso de comandos extendidos para definir esos parámetros. Estos comandos nos permiten codificar instrucciones más precisas sobre cómo crear o modificar nuestras bases de datos y colecciones específicamente para Azure Cosmos DB.

Azure Cosmos DB for MongoDB proporciona comandos de extensión para los siguientes tipos de solicitud:

• Creación de una base de datos
• Actualizar la base de datos
• Obtener una base de datos
• Crear colección
• Actualizar una colección
• Obtener una colección

Los controladores de MongoDB proporcionan una función para ejecutar un comando en una base de datos que usamos esta función para enviar nuestros comandos extendidos a Azure Cosmos DB. Echemos un vistazo al código para crear una colección de dispositivos IoT con un rendimiento de 2000 RUs (Unidades de solicitud) y una clave de partición 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""}");

De forma similar, podemos modificar una colección o crear o modificar una base de datos. Consulte el artículo Uso de comandos de la extensión de MongoDB para administrar los datos almacenados en la API de Azure Cosmos DB para MongoDB para obtener más información.