Compartir a través de

Inicio rápido: Uso de Azure DocumentDB con el controlador mongoDB para Rust

En este inicio rápido, creará una aplicación básica de Azure DocumentDB mediante Rust. Azure DocumentDB es un almacén de datos NoSQL que permite a las aplicaciones almacenar documentos en la nube y acceder a ellos mediante controladores oficiales de MongoDB. En esta guía se muestra cómo crear documentos y realizar tareas básicas en el clúster de Azure DocumentDB mediante Rust.

Referencia de la API | Código fuente | Paquete (crates.io)

Prerrequisitos

  • Una suscripción de Azure

  • Rust 1.70 o posterior

Creación de un clúster de Azure DocumentDB

Para empezar, primero debe crear un clúster de Azure DocumentDB, que sirve como base para almacenar y administrar los datos NoSQL.

  1. Inicie sesión en Azure Portal (https://portal.azure.com).

  2. En el menú de Azure Portal o en la página principal, seleccione Crear un recurso.

  3. En la página Nuevo , busque y seleccione Azure DocumentDB.

    Captura de pantalla que muestra la búsqueda de Azure DocumentDB.

  4. En la página Crear clúster de Azure DocumentDB y, en la sección Aspectos básicos , seleccione la opción Configurar en la sección Nivel de clúster.

    Captura de pantalla que muestra la opción Configurar clúster.

  5. En la página Escala , configure estas opciones y seleccione Guardar para conservar los cambios en el nivel de clúster.

    Importancia
    Nivel de clúster M30 tier, 2 vCore, 8-GiB RAM
    Almacenamiento por partición 128 GiB

    Captura de pantalla de las opciones de configuración para el proceso y el almacenamiento de un nuevo clúster de Azure DocumentDB.

  6. De nuevo en la sección Aspectos básicos , configure las siguientes opciones:

    Importancia
    Subscription Seleccione su suscripción a Azure.
    Grupo de recursos Cree un grupo de recursos nuevo o seleccione uno existente
    Nombre del clúster Proporcione un nombre único global.
    Ubicación Seleccione una región de Azure compatible para su suscripción
    Versión de MongoDB Seleccione 8.0.
    Nombre de usuario administrador Creación de un nombre de usuario para acceder al clúster como administrador de usuarios
    Contraseña Uso de una contraseña única asociada al nombre de usuario

    Captura de pantalla que muestra los parámetros del clúster.

    Sugerencia

    Registre los valores que usa para el nombre de usuario y la contraseña. Estos valores se usan más adelante en esta guía. Para más información sobre los valores válidos, consulte Limitaciones del clúster.

  7. Seleccione Siguiente: Redes.

  8. En la sección Reglas de firewall de la pestaña Redes , configure estas opciones:

    Importancia
    Método de conectividad Public access
    Permitir el acceso público desde servicios y recursos de Azure a este clúster Habilitado

  9. Agregue una regla de firewall para el dispositivo cliente actual para conceder acceso al clúster seleccionando + Agregar dirección IP del cliente actual.

    Captura de pantalla que muestra las configuraciones de red.

    Sugerencia

    En muchos entornos corporativos, las direcciones IP de la máquina del desarrollador se ocultan debido a una VPN u otra configuración de red corporativa. En estos casos, puede permitir temporalmente el acceso a todas las direcciones IP agregando el 0.0.0.0 - 255.255.255.255 intervalo de direcciones IP como regla de firewall. Use esta regla de firewall solo temporalmente como parte de las pruebas de conexión y el desarrollo.

  10. Selecciona Revisar + crear.

  11. Revise la configuración que proporcione y, a continuación, seleccione Crear. La operación de creación del clúster tarda unos minutos. Espere a que se complete la implementación de recursos.

  12. Por último, seleccione Ir al recurso para ir al clúster de Azure DocumentDB en el portal.

Captura de pantalla que muestra las opciones de recursos goto.

Obtener credenciales del clúster

Obtenga las credenciales que usa para conectarse al clúster.

  1. En la página del clúster, seleccione la opción Cadenas de conexión en el menú de recursos.

  2. En la sección Cadenas de conexión , copie o registre el valor del campo Cadena de conexión .

Captura de pantalla que muestra la opción cadenas de conexión.

Importante

La cadena de conexión del portal no incluye el valor de contraseña. Debe reemplazar el marcador de posición <password> por los datos de acceso que introdujo al crear el clúster o ingresar la contraseña de manera interactiva.

Inicialización del proyecto

Cree un nuevo proyecto de Rust en el directorio actual.

  1. Inicie en un directorio vacío.

  2. Abra un terminal en el directorio actual.

  3. Cree un nuevo proyecto de Rust mediante Cargo.

    cargo new azure-documentdb-rust-quickstart
cd azure-documentdb-rust-quickstart

Instalación de la biblioteca cliente

La biblioteca cliente está disponible en crates.io, como el contendor mongodb.

  1. Agregue el controlador de Rust de MongoDB mediante Cargo.

    cargo add mongodb

  2. Agregue el tokio tiempo de ejecución para las operaciones asincrónicas.

    cargo add tokio --features full

  3. Agregue el contenedor serde para el soporte de serialización.

    cargo add serde --features derive

  4. Agregue el futures crate para las operaciones de flujo asincrónicas.

    cargo add futures

  5. Abra el archivo src/main.rs para el código de la aplicación.

  6. Importe los módulos necesarios en el código de la aplicación:

    use futures::TryStreamExt;
use mongodb::{
    bson::doc,
    options::ClientOptions,
    Client, Collection,
};
use serde::{Deserialize, Serialize};

Modelo de objetos

Nombre Descripción
Client Tipo que se usa para conectarse a MongoDB.
Database Representa una base de datos en el clúster.
Collection<T> Representa una colección dentro de una base de datos del clúster.

Ejemplos de código

El código de esta aplicación se conecta a una base de datos denominada adventureworks y a una colección denominada products. La products colección contiene detalles como el nombre, la categoría, la cantidad, un identificador único y una marca de venta para cada producto. Los ejemplos de código aquí realizan las operaciones más comunes al trabajar con una colección.

Autenticar el cliente

En primer lugar, conéctese al cliente mediante una cadena de conexión básica.

  1. Cree la función asincrónica principal y configure la cadena de conexión. Reemplace <your-cluster-name>, <your-username>, y <your-password> con su información real del clúster.

    #[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connection string for Azure DocumentDB cluster
    let connection_string = "mongodb+srv://<your-username>:<your-password>@<your-cluster-name>.global.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000";

    // Parse connection string into client options
    let client_options = ClientOptions::parse(connection_string).await?;

  2. Cree el cliente de MongoDB y compruebe la conexión.

        // Create a new client and connect to the server
    let client = Client::with_options(client_options)?;

    // Ping the server to verify connection
    client
        .database("admin")
        .run_command(doc! { "ping": 1 })
        .await?;

    println!("Successfully connected and pinged Azure DocumentDB");

Consigue una colección

Ahora, consigue base de datos y colección. Si la base de datos y la colección aún no existen, use el controlador para crearla automáticamente.

  1. Obtenga una referencia a la base de datos.

        // Get database reference
    let database = client.database("adventureworks");
    println!("Connected to database: {}", database.name());

  2. Obtenga una referencia a la colección dentro de la base de datos.

        // Get collection reference
    let collection: Collection<Product> = database.collection("products");
    println!("Connected to collection: products");

Creación de un documento

A continuación, cree un par de documentos nuevos dentro de la colección. Inserte o actualice los documentos para asegurarse de que reemplacen cualquier documento existente si ya existen con el mismo identificador único.

  1. Defina una estructura de producto y cree documentos de producto de ejemplo.

        // Define Product struct for type-safe operations
    #[derive(Debug, Serialize, Deserialize)]
    struct Product {
        #[serde(rename = "_id")]
        id: String,
        name: String,
        category: String,
        quantity: i32,
        price: f64,
        sale: bool,
    }

    // Create sample products
    let products = vec![
        Product {
            id: "00000000-0000-0000-0000-000000004018".to_string(),
            name: "Windry Mittens".to_string(),
            category: "apparel-accessories-gloves-and-mittens".to_string(),
            quantity: 121,
            price: 35.00,
            sale: false,
        },
        Product {
            id: "00000000-0000-0000-0000-000000004318".to_string(),
            name: "Niborio Tent".to_string(),
            category: "gear-camp-tents".to_string(),
            quantity: 140,
            price: 420.00,
            sale: true,
        },
    ];

  2. Inserte los documentos mediante operaciones upsert.

        // Insert documents with upsert
    for product in &products {
        let filter = doc! { "_id": &product.id };
        let update = doc! { "$set": mongodb::bson::to_document(product)? };

        let result = collection
            .update_one(filter, update)
            .upsert(true)
            .await?;

        if result.upserted_id.is_some() {
            println!("Inserted document with ID: {}", product.id);
        } else {
            println!("Updated document with ID: {}", product.id);
        }
    }

Recuperar un documento

A continuación, realice una operación de lectura puntual para recuperar un documento específico de la colección.

  1. Defina el filtro para buscar un documento específico por identificador.

        // Retrieve a specific document by ID
    let filter = doc! { "_id": "00000000-0000-0000-0000-000000004018" };

  2. Ejecute la consulta y recupere el resultado.

        let retrieved_product = collection.find_one(filter).await?;

    match retrieved_product {
        Some(product) => println!("Retrieved product: {} - ${:.2}", product.name, product.price),
        None => println!("Product not found"),
    }

Consultar documentos

Por último, consulte varios documentos mediante el lenguaje de consulta mongoDB (MQL).

  1. Defina una consulta para buscar documentos que coincidan con criterios específicos.

        // Query for products on sale
    let query_filter = doc! { "sale": true };
    let mut cursor = collection.find(query_filter).await?;

  2. Recorrer en iteración el cursor para recuperar todos los documentos coincidentes.

        println!("Products on sale:");
    while let Some(product) = cursor.try_next().await? {
        println!(
            "- {}: ${:.2} (Category: {})",
            product.name, product.price, product.category
        );
    }

    Ok(())
}

Exploración de los datos mediante Visual Studio Code

Use la extensión DocumentDB en Visual Studio Code para realizar operaciones básicas de base de datos, como consultar, insertar, actualizar y eliminar datos.

  1. Abra Visual Studio Code.

  2. Vaya a la vista Extensiones y busque el término DocumentDB. Busque la extensión DocumentDB para VS Code .

  3. Seleccione el botón Instalar de la extensión. Espere a que termine la instalación. Vuelva a cargar Visual Studio Code si se le solicita.

  4. Vaya a la extensión DocumentDB seleccionando el icono correspondiente en la barra de actividad.

  5. En el panel Conexiones de DocumentDB , seleccione + Nueva conexión....

  6. En el cuadro de diálogo, seleccione Detección de servicios y, a continuación, Azure DocumentDB - Azure Service Discovery.

  7. Seleccione la suscripción de Azure y el clúster de Azure DocumentDB recién creado.

    Sugerencia

    En muchos entornos corporativos, las direcciones IP de la máquina del desarrollador se ocultan debido a una VPN u otra configuración de red corporativa. En estos casos, puede permitir temporalmente el acceso a todas las direcciones IP agregando el 0.0.0.0 - 255.255.255.255 intervalo de direcciones IP como regla de firewall. Use esta regla de firewall solo temporalmente como parte de las pruebas de conexión y el desarrollo. Para más información, consulte Configuración del firewall.

  8. De nuevo en el panel Conexiones de DocumentDB , expanda el nodo del clúster y vaya a los nodos de documento y colección existentes.

  9. Abra el menú contextual de la colección y luego seleccione >.

  10. Escriba los siguientes comandos del lenguaje de consulta de MongoDB (MQL) y, a continuación, seleccione Ejecutar todo. Observa la salida de los comandos.

    db.products.find({
  price: { $gt: 200 },
  sale: true
})
.sort({ price: -1 })
.limit(3)

Limpieza de recursos

Cuando haya terminado con el clúster de Azure DocumentDB, puede eliminar los recursos de Azure que creó para que no incurra en más cargos.

  1. En la barra de búsqueda de Azure Portal, busque y seleccione Grupos de recursos.

    Captura de pantalla que muestra la opción para buscar grupos de recursos.

  2. En la lista, seleccione el grupo de recursos que usó para este inicio rápido.

    Captura de pantalla que muestra el grupo de recursos.

  3. En la página del grupo de recursos, seleccione Eliminar grupo de recursos.

  4. En el cuadro de diálogo de confirmación de eliminación, escriba el nombre del grupo de recursos para confirmar que desea eliminarlo. Por último, seleccione Eliminar para eliminar de forma permanente el grupo de recursos.

    Captura de pantalla que muestra el botón de confirmación para eliminar el grupo de recursos.

Contenido relacionado

  • Last updated on