azure-cosmos-rust

Azure Cosmos DB SDK for Rust

Azure Cosmos DB NoSQL API 用のクライアントライブラリです。グローバルに分散されたマルチモデルデータベースです。

以下の例を使用するには、互換性が確認されたクレートのセットを用意し、すべてのリソースプレースホルダーを置き換える必要があります。デモ用の書き込みに本番データを使用しないでください。

インストール

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

環境変数

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

認証

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

クライアント階層

クライアント	用途	取得元
CosmosClient	アカウントレベルの操作	直接インスタンス化
DatabaseClient	データベース操作	client.database_client()
ContainerClient	コンテナー／アイテム操作	database.container_client()

基本的なワークフロー

データベースとコンテナーのクライアントを取得する

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

アイテムを作成する

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

アイテムを読み取る

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

アイテムを置き換える

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

アイテムにパッチを適用する

// 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()?;

アイテムを削除する

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

現在の API として確認済みのものでは、非同期ビルダー／コンテナーの初期化と、個別に指定するアイテム ID が使用されます。プレビュー版の PATCH は、本番環境での使用を保証するものではありません。選択した戦略、競合／再試行の動作、およびリクエストユニットのコストを確認してください。公式クレートリファレンス。

キー認証（任意）

機能フラグを使ってキー認証を有効にします。

cargo add azure_data_cosmos@=0.37.1 --features key_auth

ベストプラクティス

1. パーティションキーを必ず指定する — ポイント読み取りと書き込みに必要です
2. into_model()? を使用する — レスポンスを型にデシリアライズします
3. すべてのドキュメント型に Serialize と Deserialize を導出する
4. Entra ID 認証を使用する — キー認証よりも DeveloperToolsCredential を優先します
5. クライアントインスタンスを再利用する — クライアントはスレッドセーフで、再利用できます

確認済みの例のセットでは、azure_data_cosmos 0.37.1 と互換性のある Azure のコア／認証情報クレートを使用します。Cargo.lock を記録してコミットしてください。ソース／API の確認は、コンパイルや実サービスでのテストを意味するものではありません。

参考リンク

リソース	リンク
API リファレンス	https://docs.rs/azure_data_cosmos
ソースコード	https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/cosmos/azure_data_cosmos
crates.io	https://crates.io/crates/azure_data_cosmos

使用する場面

Rust アプリケーションで Cosmos DB NoSQL のアイテムに対する CRUD、パーティションキーを使ったポイント読み取り、コンテナーへのアクセス、または明示的にオプトインしたプレビュー版パッチ適用が必要な場合に使用します。

制限事項

• 例は非同期アプリケーションコード内の断片であり、互換性のある Azure クレートの固定バージョンと、必要な Tokio／Serde／Futures の依存関係を前提とします。使用前に、選択したバージョンの API を確認してください。ここでは、公式ソース／リファレンスと照合して確認していますが、コンパイルやクラウドアカウントに対する実行は行っていません。
• 最小権限の原則に従い、認可されたテナント、リソース、ID を使用してください。書き込み、上書き、削除、バックアップの取得、アカウントの変更には、それぞれに対応するスコープが必要です。クリーンアップでは、明示的に特定された破棄可能なリソースのみを削除してください。リクエスト、再試行、ダウンロードするバイト数に上限を設け、ペイロード、認証情報、シークレット値をログに記録しないでください。
• この出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功条件が不足している場合は、停止して確認を求めてください。