SDK do Azure Cosmos DB para Rust

Biblioteca cliente para a API NoSQL do Azure Cosmos DB — banco de dados distribuído globalmente e multimodelo.

Os exemplos abaixo exigem um conjunto de crates compatíveis revisados e a substituição de cada espaço reservado de recurso. Não use dados de produção para gravações de demonstração.

Instalação

cargo add azure_data_cosmos@=0.37.1 azure_identity@=1.0.0 azure_core@=1.1.0

Variáveis de Ambiente

export COSMOS_ENDPOINT="https://<account>.documents.azure.com:443/"
export COSMOS_DATABASE="mydb"
export COSMOS_CONTAINER="mycontainer"

Autenticação

use azure_identity::DeveloperToolsCredential;
use azure_data_cosmos::{AccountEndpoint, AccountReference, CosmosClient, RoutingStrategy};

let credential = DeveloperToolsCredential::new(None)?;
let endpoint: AccountEndpoint = "https://<account>.documents.azure.com/".parse()?;
let account = AccountReference::with_credential(endpoint, credential.clone());
let client = CosmosClient::builder()
    .build(account, RoutingStrategy::ProximityTo("East US".into()))
    .await?;

Hierarquia de Clientes

Fluxo de Trabalho Principal

Obter Clientes de Banco de Dados e Contêiner

let database = client.database_client("myDatabase");
let container = database.container_client("myContainer", None).await?;

Criar Item

use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize)]
struct Item {
    pub id: String,
    pub partition_key: String,
    pub value: String,
}

let item = Item {
    id: "1".into(),
    partition_key: "partition1".into(),
    value: "hello".into(),
};

container.create_item("partition1", "1", item, None).await?;

Ler Item

let response = container.read_item("partition1", "1", None).await?;
let item: Item = response.into_model()?;

Substituir Item

let mut item: Item = container.read_item("partition1", "1", None).await?.into_model()?;
item.value = "updated".into();

container.replace_item("partition1", "1", item, None).await?;

Patch de Item

// Explicit preview opt-in: cargo add azure_data_cosmos@=0.37.1 --features preview_patch
use azure_data_cosmos::models::{PatchInstructions, PatchOperation};

let patch = PatchInstructions::from(vec![
    PatchOperation::set("/value", serde_json::json!("newValue")),
]);
let patched: Item = container.patch_item("partition1", "1", patch, None)
    .await?.into_model()?;

Excluir Item

container.delete_item("partition1", "1", None).await?;

A API atual revisada usa um inicializador/inicialização de contêiner assíncrono e um ID de item explícito separado. O PATCH de pré-visualização não é uma garantia pronta para produção; revise sua estratégia selecionada, comportamento de conflito/tentativa e custo de unidade de solicitação. Referência oficial da crate.

Autenticação por Chave (Opcional)

Habilite a autenticação baseada em chave com o sinalizador de recurso:

cargo add azure_data_cosmos@=0.37.1 --features key_auth

Melhores Práticas

1. Sempre especifique a chave de partição — necessária para leituras e gravações pontuais
2. Use into_model()? — para desserializar respostas em seus tipos
3. Derive Serialize e Deserialize — para todos os tipos de documento
4. Use autenticação do Entra ID — prefira DeveloperToolsCredential em vez de autenticação por chave
5. Reutilize instâncias de cliente — clientes são thread-safe e reutilizáveis

O conjunto de exemplos revisados usa azure_data_cosmos 0.37.1 e crates de credenciais/core do Azure compatíveis. Grave e confirme o Cargo.lock; a revisão de código-fonte/API não é um teste de compilador ou de serviço ativo.

Links de Referência

Quando Usar

Use quando um aplicativo Rust precisar de CRUD de itens NoSQL do Cosmos DB, leituras pontuais por chave de partição, acesso a contêiner ou patching de pré-visualização explicitamente optado.

Limitações

…