Rychlý start: Použití Azure DocumentDB s ovladačem MongoDB pro Rust

V tomto rychlém startu vytvoříte základní aplikaci Azure DocumentDB pomocí Rustu. Azure DocumentDB je úložiště dat NoSQL, které umožňuje aplikacím ukládat dokumenty v cloudu a přistupovat k nim pomocí oficiálních ovladačů MongoDB. Tato příručka ukazuje, jak vytvářet dokumenty a provádět základní úlohy v clusteru Azure DocumentDB pomocí Rustu.

Referenční informace k | rozhraní APIZdrojový kód | Balíček (crates.io)

Prerequisites

  • Předplatné Azure

  • Rust 1.70 nebo novější

Vytvoření clusteru Azure DocumentDB

Abyste mohli začít, musíte nejprve vytvořit cluster Azure DocumentDB, který slouží jako základ pro ukládání a správu dat NoSQL.

  1. Přihlaste se k portálu Azure (https://portal.azure.com).

  2. V nabídce portálu Azure nebo na stránce Home vyberte Vytvořit prostředek.

  3. Na stránce Nový vyhledejte a vyberte Azure DocumentDB.

    Snímek obrazovky znázorňující hledání Azure DocumentDB

  4. Na stránce Vytvoření clusteru Azure DocumentDB a v části Basics vyberte možnost Konfigurovat v části Úroveň clusteru.

    Snímek obrazovky znázorňující možnost Konfigurovat cluster

  5. Na stránce Škálování nakonfigurujte tyto možnosti a pak výběrem možnosti Uložit uložte změny na úrovni clusteru.

    Value
    Úroveň clusteru M30 tier, 2 vCore, 8-GiB RAM
    Úložiště pro shard 128 GiB

    Snímek obrazovky s možnostmi konfigurace pro výpočetní prostředky a úložiště pro nový cluster Azure DocumentDB

  6. Zpět v části Základy nakonfigurujte následující možnosti:

    Value
    Předplatné Vyberte své předplatné Azure.
    Skupina zdrojů Vytvoření nové skupiny prostředků nebo výběr existující skupiny prostředků
    Název clusteru Zadejte globálně jedinečný název.
    Umístění Vyberte podporovanou oblast Azure pro vaše předplatné.
    Verze MongoDB Vyberte 8.0
    Uživatelské jméno správce Vytvoření uživatelského jména pro přístup ke clusteru jako správce uživatele
    Heslo Použití jedinečného hesla přidruženého k uživatelskému jménu

    Snímek obrazovky zobrazující parametry clusteru

    Tip

    Poznamenejte si hodnoty, které používáte pro uživatelské jméno a heslo. Tyto hodnoty se používají dále v tomto průvodci. Další informace o platných hodnotách najdete v tématu Omezení clusteru.

  7. Vyberte Další: Sítě.

  8. V části Pravidla brány firewall na kartě Sítě nakonfigurujte tyto možnosti:

    Value
    Metoda připojení Public access
    Povolit veřejný přístup ze služeb a prostředků Azure v rámci Azure k tomuto clusteru Enabled

  9. Přidáním pravidla brány firewall pro aktuální klientské zařízení udělte přístup ke clusteru výběrem + Přidat aktuální IP adresu klienta.

    Snímek obrazovky znázorňující konfigurace sítě

    Tip

    V mnoha podnikových prostředích jsou IP adresy vývojářských počítačů skryté kvůli nastavení sítě VPN nebo jiné podnikové sítě. V těchto případech můžete dočasně povolit přístup ke všem IP adresám přidáním rozsahu 0.0.0.0 - 255.255.255.255 IP adres jako pravidla brány firewall. Toto pravidlo brány firewall používejte pouze dočasně jako součást testování a vývoje připojení.

  10. Vyberte možnost Zkontrolovat a vytvořit.

  11. Zkontrolujte nastavení, která zadáte, a pak vyberte Vytvořit. Vytvoření clusteru bude trvat několik minut. Počkejte na dokončení nasazení prostředků.

  12. Nakonec vyberte Go to resource, a přejděte na cluster Azure DocumentDB na portálu.

Snímek obrazovky znázorňující možnosti prostředku goto

Získání přihlašovacích údajů clusteru

Získejte přihlašovací údaje, které používáte pro připojení ke clusteru.

  1. Na stránce clusteru vyberte v nabídce prostředků možnost Připojovací řetězce .

  2. V části Připojovací řetězce zkopírujte nebo poznamenejte hodnotu z pole Připojovací řetězec .

Snímek obrazovky znázorňující možnost připojovacích řetězců

Important

Připojovací řetězec na portálu neobsahuje hodnotu hesla. Zástupný symbol musíte nahradit <password> přihlašovacími údaji, které jste zadali při vytváření clusteru, nebo interaktivně zadat heslo.

Inicializace projektu

Vytvořte nový projekt Rust v aktuálním adresáři.

  1. Začněte v prázdném adresáři.

  2. Otevřete terminál v aktuálním adresáři.

  3. Vytvořte nový projekt Rust pomocí Cargo.

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

Instalace klientské knihovny

Klientská knihovna je k dispozici na crates.io jako mongodb krabička.

  1. Přidejte ovladač MongoDB Rust pomocí cargo.

    cargo add mongodb

  2. tokio Přidejte modul runtime pro asynchronní operace.

    cargo add tokio --features full

  3. Přidejte serde krabici pro podporu serializace.

    cargo add serde --features derive

  4. Přidejte crate pro asynchronní operace streamu.

    cargo add futures

  5. Otevřete soubor src/main.rs pro kód aplikace.

  6. Naimportujte požadované moduly do kódu aplikace:

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

Objektový model

Name Description
Client Typ použitý pro připojení k MongoDB.
Database Představuje databázi v clusteru.
Collection<T> Představuje kolekci v rámci databáze v clusteru.

Příklady kódu

Kód v této aplikaci se připojí k databázi pojmenované adventureworks a kolekci s názvem products. Kolekce products obsahuje podrobnosti, jako je název, kategorie, množství, jedinečný identifikátor a příznak prodeje pro každý produkt. Zde uvedené ukázky kódu provádějí nejběžnější operace při práci s kolekcí.

Ověření klienta

Nejprve se připojte k klientovi pomocí základního připojovacího řetězce.

  1. Vytvořte hlavní asynchronní funkci a nastavte připojovací řetězec. Nahraďte <your-cluster-name>, <your-username> a <your-password> vašimi skutečnými informacemi o clusteru.

    #[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. Vytvořte klienta MongoDB a ověřte připojení.

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

Získání kolekce

Teď získejte databázi a kolekci. Pokud databáze a kolekce ještě neexistují, pomocí ovladače ji vytvořte automaticky.

  1. Získejte odkaz na databázi.

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

  2. Získejte odkaz na kolekci v databázi.

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

Vytvoření dokumentu

Pak v kolekci vytvořte několik nových dokumentů. Vložte dokumenty, aby se zajistilo, že nahradí všechny existující dokumenty, pokud již existují se stejným jedinečným identifikátorem.

  1. Definujte strukturu produktu a vytvořte ukázkové dokumenty produktu.

        // 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. Vložte dokumenty pomocí operací 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);
        }
    }

Načtení dokumentu

Dále proveďte operaci čtení bodu, která načte konkrétní dokument z kolekce.

  1. Definujte filtr pro vyhledání konkrétního dokumentu podle ID.

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

  2. Spusťte dotaz a načtěte výsledek.

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

Dotazování na dokumenty

Nakonec dotazujte více dokumentů pomocí dotazovacího jazyka MongoDB (MQL).

  1. Definujte dotaz pro vyhledání dokumentů odpovídajících konkrétním kritériím.

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

  2. Iterujte kurzorem a získejte všechny odpovídající dokumenty.

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

    Ok(())
}

Prozkoumání dat pomocí editoru Visual Studio Code

Pomocí rozšíření DocumentDB v editoru Visual Studio Code můžete provádět základní databázové operace, včetně dotazování, vkládání, aktualizace a odstraňování dat.

  1. Otevřete Visual Studio Code.

  2. Přejděte do zobrazení Rozšíření a vyhledejte termín DocumentDB. Vyhledejte rozšíření DocumentDB pro VS Code.

  3. Vyberte tlačítko Instalovat pro rozšíření. Počkejte na dokončení instalace. Znovu načtěte Visual Studio Code, pokud se zobrazí výzva.

  4. Výběrem odpovídající ikony na panelu aktivit přejděte na rozšíření DocumentDB .

  5. V podokně Připojení DocumentDB vyberte + Nové připojení....

  6. V dialogovém okně vyberte Zjišťování služeb a pak Azure DocumentDB – Azure Service Discovery.

  7. Vyberte své předplatné Azure a nově vytvořený cluster Azure DocumentDB.

    Tip

    V mnoha podnikových prostředích jsou IP adresy vývojářských počítačů skryté kvůli nastavení sítě VPN nebo jiné podnikové sítě. V těchto případech můžete dočasně povolit přístup ke všem IP adresám přidáním rozsahu 0.0.0.0 - 255.255.255.255 IP adres jako pravidla brány firewall. Toto pravidlo brány firewall používejte pouze dočasně jako součást testování a vývoje připojení. Další informace najdete v tématu konfigurace brány firewall.

  8. V podokně Připojení DocumentDB najděte uzel vašeho clusteru a rozbalte jej, poté přejděte k vašim existujícím uzlům dokumentů a kolekcí.

  9. Otevřete místní nabídku kolekce a pak vyberte DocumentDB Scrapbook<0/> Nový DocumentDB Scrapbook.

  10. Zadejte následující příkazy jazyka MongoDB Query Language (MQL) a pak vyberte Spustit vše. Sledujte výstup z příkazů.

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

Vyčistěte zdroje

Až budete hotovi s clusterem Azure DocumentDB, můžete odstranit prostředky Azure, které jste vytvořili, takže vám nebudou účtovány další poplatky.

  1. Na panelu hledání na webu Azure Portal vyhledejte a vyberte skupiny prostředků.

    Snímek obrazovky znázorňující možnost vyhledávání skupin prostředků

  2. V seznamu vyberte skupinu prostředků, kterou jste použili pro účely tohoto rychlého startu.

    Snímek obrazovky znázorňující skupinu prostředků

  3. Na stránce skupiny prostředků vyberte Odstranit skupinu prostředků.

  4. V potvrzovací dialogovém okně odstranění zadejte název skupiny prostředků, abyste potvrdili, že ji chcete odstranit. Nakonec vyberte Odstranit a trvale odstraňte skupinu prostředků.

    Snímek obrazovky s tlačítkem pro potvrzení odstranění skupiny prostředků.

Související obsah

  • Last updated on