Schnellstart: Verwenden von Azure Cosmos DB mit Azure SDK für Rust

In dieser Schnellstartanleitung verbinden Sie eine Rust-Anwendung mit Azure Cosmos DB unter Verwendung des Azure SDK für Rust. Erstellen, lesen und fragen Sie Elemente in einem vorhandenen Container ab.

Diese Schnellstartanleitung verwendet Version 1.0.0 des allgemein verfügbaren Azure Cosmos DB SDK für Rust.

Important

OpenTelemetry-Unterstützung (unstable_opentelemetry) und Patchvorgänge (unstable_patch) im Azure Cosmos DB SDK für Rust verbleiben in der Vorschau und werden für Produktionsworkloads nicht empfohlen. Diese Vorschaufeatures sind vom allgemein verfügbaren SDK getrennt und werden in dieser Schnellstartanleitung nicht verwendet.

API-Referenzdokumentation | Quellcode der Bibliothek | Crate (Rust) | Azure Developer CLI

Prerequisites

Wenn Sie nicht über ein Azure-Konto verfügen, erstellen Sie ein kostenloses Konto , bevor Sie beginnen.

Tip

Agent Kit hilft Coding-Agenten, mithilfe empfohlener Best Practices schnell und effizient mit Azure Cosmos DB zu arbeiten. Führen Sie zunächst Folgendes aus:

npx skills add AzureCosmosDB/cosmosdb-agent-kit

Weitere Informationen finden Sie unter Azure Cosmos DB Agent Kit.

Installieren der Clientbibliothek

Sie können die Clientbibliothek als azure_data_cosmos crate abrufen. Die folgenden Befehle verwenden die neuesten stabilen Releaseversionen von Azure Cosmos DB und Azure Identity, Version 1.0.0.

  1. Erstellen Sie eine Rust-Anwendung, und öffnen Sie das Verzeichnis.

    cargo new cosmos-quickstart
    cd cosmos-quickstart
    
  2. Fügen Sie Version 1.0.0 der azure_data_cosmos Crate mithilfe von cargo add hinzu.

    cargo add azure_data_cosmos@1.0.0
    
  3. Fügen Sie Version 1.0.0 der azure_identity crate hinzu.

    cargo add azure_identity@1.0.0
    
  4. Fügen Sie die Abhängigkeiten für JSON-Serialisierung, asynchrone Ausführung und Abfrageiteration hinzu.

    cargo add serde --features derive
    cargo add tokio --features macros,rt-multi-thread
    cargo add futures
    

Importieren von Bibliotheken

Fügen Sie diese Importe zu den Importen in src/main.rs hinzu.

use azure_data_cosmos::{AccountReference, CosmosClient, FeedScope, PartitionKey, Query, RoutingStrategy};
use azure_identity::DeveloperToolsCredential;
use futures::TryStreamExt;

Objektmodell

Name Description
CosmosClient Der primäre Client zum Herstellen einer Verbindung mit einem Konto und zum Abrufen von Datenbankclients.
DatabaseClient Ein Client für eine Datenbank innerhalb des Kontos.
ContainerClient Ein Client für einen Container und seine Elemente.

Code-Beispiele

In den Beispielen wird die vorhandene products Datenbank und der vorhandene cosmicworks Container verwendet. Der Container verwendet /category als Partitionsschlüssel. Platzieren Sie den Item Typ aus dem Erstellungsbeispiel nach den Importen. Ersetzen Sie die generierte main Funktion durch den folgenden asynchronen Einstiegspunkt, und fügen Sie dann die Authentifizierung, Datenbank, Container, Upsert, Lese- und Abfrageausschnitte in der Reihenfolge vor Ok(()).

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    Ok(())
}

Authentifizieren des Clients

Verwenden Sie DeveloperToolsCredential, um sich über Ihre angemeldeten Entwicklertools zu authentifizieren. Legen Sie die Umgebungsvariable AZURE_COSMOS_ENDPOINT auf die Endpunkt-URL Ihres Kontos fest, die auf der Azure-Portalseite Übersicht verfügbar ist. Legen Sie AZURE_COSMOS_REGION auf die Azure-Region fest, die Ihrer Anwendung am nächsten ist, z. B. East US.

let credential = DeveloperToolsCredential::new(None)?;
let endpoint = std::env::var("AZURE_COSMOS_ENDPOINT")?.parse()?;
let region = std::env::var("AZURE_COSMOS_REGION")?;
let account = AccountReference::with_credential(endpoint, credential);

let client = CosmosClient::builder()
    .build(account, RoutingStrategy::ProximityTo(region.into()))
    .await?;

Verwenden Sie den Client für nachfolgende Vorgänge wieder. Verwenden Sie für Azure gehostete Produktionsanwendungen eine verwaltete Identität anstelle von Entwickleranmeldeinformationen.

Datenbank abrufen

Verwenden Sie client.database_client, um einen Client für die vorhandene Datenbank mit dem Namen cosmicworks abzurufen.

let database = client.database_client("cosmicworks");

Container abrufen

Rufen Sie einen Client für den vorhandenen products Container mithilfe von database.container_client.

let container = database.container_client("products", None).await?;

Erstellen eines Elements

Erstellen Sie einen neuen Typ mit allen Membern, die Sie in JSON serialisieren möchten. In diesem Beispiel weist der Typ einen eindeutigen Bezeichner und Felder für Kategorie, Name, Menge, Preis und Verkauf auf. Leiten Sie die serde::Serialize-Eigenschaft für diesen Typ ab, damit sie in JSON serialisiert werden kann.

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
pub struct Item {
    pub id: String,
    pub category: String,
    pub name: String,
    pub quantity: i32,
    pub price: f64,
    pub clearance: bool,
}

Erstellen Sie mithilfe von container.upsert_item ein Element im Container. Mit dieser Methode wird das Element „upsertiert“, wodurch es effektiv ersetzt wird, falls es bereits existiert.

let item = Item {
    id: "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb".to_string(),
    category: "gear-surf-surfboards".to_string(),
    name: "Yamba Surfboard".to_string(),
    quantity: 12,
    price: 850.00,
    clearance: false,
};

let partition_key = PartitionKey::from(item.category.clone());

container.upsert_item(partition_key, &item.id, &item, None).await?;

Lesen eines Elements

Führen Sie einen Punktlesevorgang aus, indem Sie sowohl die eindeutigen Bezeichner (id) als auch die Partitionsschlüsselfelder verwenden. Verwenden Sie container.read_item, um das jeweilige Element effizient abzurufen.

let item_id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb";
let item_partition_key = "gear-surf-surfboards";

let response = container.read_item(item_partition_key, item_id, None).await?;

let item: Item = response.into_model()?;
println!("Read item: {} ({})", item.name, item.id);

Abfrageelemente

Führen Sie mithilfe von container.query_items eine Abfrage für mehrere Elemente in einem Container durch. Suchen Sie alle Elemente in einer angegebenen Kategorie mithilfe dieser parametrisierten Abfrage:

SELECT * FROM c WHERE c.category = @category
let item_partition_key = "gear-surf-surfboards";

let query = Query::from("SELECT * FROM c WHERE c.category = @category")
    .with_parameter("@category", item_partition_key)?;

let mut items = container
    .query_items::<Item>(query, FeedScope::partition(item_partition_key), None)
    .await?;

while let Some(item) = items.try_next().await? {
    println!("Query result: {} ({})", item.name, item.id);
}

Führen Sie die Anwendung nach dem Hinzufügen der Codeausschnitte aus, und legen Sie die Umgebungsvariablen fest.

cargo run

Erkunden Sie Ihre Daten

Verwenden Sie die Visual Studio Code-Erweiterung für Azure Cosmos DB, um Ihre NoSQL-Daten zu untersuchen. Sie können Kerndatenbankvorgänge ausführen, einschließlich, aber nicht beschränkt auf:

  • Abfragen mit einem Notizbuch oder dem Abfrage-Editor ausführen
  • Ändern, Aktualisieren, Erstellen und Löschen von Elementen
  • Importieren von Massendaten aus anderen Quellen
  • Verwalten von Datenbanken und Containern

Weitere Informationen finden Sie unter So verwenden Sie die Visual Studio Code-Erweiterung, um Azure Cosmos DB für NoSQL-Daten zu untersuchen.

Nächster Schritt