Skip to content

Commit 773113b

Browse files
analogrelayanalogrelay
authored
update the Cosmos crate README (#2039)
* update the Cosmos crate README * fix README syntax issues * PR feedback * remove key_auth from readme * remove bogus links * remove 'en-us' from urls * fix build issue with azure_core_test in --all-features
1 parent 08c7a6e commit 773113b

File tree

3 files changed

+152
-4
lines changed

3 files changed

+152
-4
lines changed

‎sdk/core/azure_core_test/src/recorded.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ pub async fn start(
4949
.init();
5050
}
5151

52-
crate::proxy::start(Some(test_mode), crate_dir, options)
52+
crate::proxy::start(Some(mode), crate_dir, options)
5353
.await
5454
.map(Arc::new)
5555
})

‎sdk/cosmos/azure_data_cosmos/README.md‎

Lines changed: 150 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,153 @@
11
# Azure Cosmos DB SDK for Rust.
22

3-
## Introduction
3+
This client library enables client applications to connect to Azure Cosmos DB via the NoSQL API. Azure Cosmos DB is a globally distributed, multi-model database service.
44

5-
This client library enables client applications to connect to [Azure Cosmos DB](https://azure.microsoft.com/en-us/products/cosmos-db) via the NoSQL API. Azure Cosmos DB is a globally distributed, multi-model database service.
5+
[Source code] | [Package (crates.io)] | [API reference documentation] | [Azure Cosmos DB for NoSQL documentation]
6+
7+
## Getting started
8+
9+
### Install the package
10+
11+
Install the Azure Cosmos DB SDK for Rust with cargo:
12+
13+
```sh
14+
cargo add azure_data_cosmos
15+
```
16+
17+
### Prerequisites
18+
19+
* An [Azure subscription] or free Azure Cosmos DB trial account.
20+
21+
Note: If you don't have an Azure subscription, create a free account before you begin.
22+
You can Try Azure Cosmos DB for free without an Azure subscription, free of charge and commitments, or create an Azure Cosmos DB free tier account, with the first 400 RU/s and 5 GB of storage for free. You can also use the Azure Cosmos DB Emulator with a URI of https://localhost:8081. For the key to use with the emulator, see [how to develop with the emulator](https://learn.microsoft.com/azure/cosmos-db/how-to-develop-emulator).
23+
24+
### Create an Azure Cosmos DB account
25+
26+
You can create an Azure Cosmos DB account using:
27+
28+
* [Azure Portal](https://portal.azure.com).
29+
* [Azure CLI](https://learn.microsoft.com/cli/azure).
30+
* [Azure ARM](https://learn.microsoft.com/azure/cosmos-db/quick-create-template).
31+
32+
#### Authenticate the client
33+
34+
In order to interact with the Azure Cosmos DB service you'll need to create an instance of the `CosmosClient` struct. To make this possible you will need a URL and key of the Azure Cosmos DB service.
35+
36+
## Examples
37+
38+
The following section provides several code snippets covering some of the most common Azure Cosmos DB NoSQL API tasks, including:
39+
* [Create Client](#create-cosmos-db-client "Create Cosmos DB client")
40+
* [CRUD operation on Items](#crud-operation-on-items "CRUD operation on Items")
41+
42+
### Create Cosmos DB Client
43+
44+
In order to interact with the Azure Cosmos DB service, you'll need to create an instance of the `CosmosClient`. You need an endpoint URL and credentials to instantiate a client object.
45+
46+
**Using Microsoft Entra ID**
47+
48+
The example shown below use a `DefaultAzureCredential`, which is appropriate for most local development environments. Additionally, we recommend using a managed identity for authentication in production environments. You can find more information on different ways of authenticating and their corresponding credential types in the [Azure Identity] documentation.
49+
50+
The `DefaultAzureCredential` will automatically pick up on an Azure CLI authentication. Ensure you are logged in with the Azure CLI:
51+
52+
```sh
53+
az login
54+
```
55+
56+
Instantiate a `DefaultAzureCredential` to pass to the client. The same instance of a token credential can be used with multiple clients if they will be authenticating with the same identity.
57+
58+
```rust
59+
use azure_identity::DefaultAzureCredential;
60+
use azure_data_cosmos::CosmosClient;
61+
62+
async fn example() -> Result<(), Box<dyn std::error::Error>> {
63+
let credential = DefaultAzureCredential::new()?;
64+
let cosmos_client = CosmosClient::new("myAccountEndpointURL", credential.clone(), None)?;
65+
Ok(())
66+
}
67+
```
68+
69+
**Using account keys**
70+
71+
Cosmos DB also supports account keys, though we strongly recommend using Entra ID authentication. To use account keys, you will need to enable the `key_auth` feature:
72+
73+
```sh
74+
cargo add azure_data_cosmos --features key_auth
75+
```
76+
77+
For more information, see the [API reference documentation].
78+
79+
### CRUD operation on Items
80+
81+
```rust
82+
use serde::{Serialize, Deserialize};
83+
use azure_data_cosmos::{CosmosClient, models::PatchDocument};
84+
85+
#[derive(Serialize, Deserialize)]
86+
struct Item {
87+
pub id: String,
88+
pub partition_key: String,
89+
pub value: String,
90+
}
91+
92+
async fn example(cosmos_client: CosmosClient) -> Result<(), Box<dyn std::error::Error>> {
93+
let item = Item {
94+
id: "1".into(),
95+
partition_key: "partition1".into(),
96+
value: "2".into(),
97+
};
98+
99+
let container = cosmos_client.database_client("myDatabase").container_client("myContainer");
100+
101+
// Create an item
102+
container.create_item("partition1", item, None).await?;
103+
104+
// Read an item
105+
let item_response = container.read_item("partition1", "1", None).await?;
106+
let mut item: Item = item_response.into_json_body().await?;
107+
108+
item.value = "3".into();
109+
110+
// Replace an item
111+
container.replace_item("partition1", "1", item, None).await?;
112+
113+
// Patch an item
114+
let patch = PatchDocument::default()
115+
.with_add("/newField", "newValue")?
116+
.with_remove("/oldFieldToRemove")?;
117+
118+
container.patch_item("partition1", "1", patch, None).await?;
119+
120+
// Delete an item
121+
container.delete_item("partition1", "1", None).await?;
122+
Ok(())
123+
}
124+
```
125+
126+
## Next steps
127+
128+
- [Resource Model of Azure Cosmos DB Service](https://learn.microsoft.com/azure/cosmos-db/sql-api-resources)
129+
- [Azure Cosmos DB Resource URI](https://learn.microsoft.com/rest/api/documentdb/documentdb-resource-uri-syntax-for-rest)
130+
- [Partitioning](https://learn.microsoft.com/azure/cosmos-db/partition-data)
131+
- [Using emulator](https://github.com/Azure/azure-documentdb-dotnet/blob/master/docs/documentdb-nosql-local-emulator.md)
132+
133+
## Next steps
134+
135+
### Provide feedback
136+
137+
If you encounter bugs or have suggestions, [open an issue](https://github.com/Azure/azure-sdk-for-rust/issues).
138+
139+
## Contributing
140+
141+
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [https://cla.microsoft.com](https://cla.microsoft.com).
142+
143+
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You'll only need to do this once across all repos using our CLA.
144+
145+
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
146+
147+
<!-- LINKS -->
148+
[Azure subscription]: https://azure.microsoft.com/free/
149+
[Azure Identity]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/identity/azure_identity
150+
[API reference documentation]: https://docs.rs/azure_data_cosmos/latest/azure_data_cosmos/
151+
[Azure Cosmos DB for NoSQL documentation]: https://learn.microsoft.com/azure/cosmos-db/nosql/
152+
[Package (crates.io)]: https://crates.io/crates/azure_data_cosmos
153+
[Source code]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/cosmos/azure_data_cosmos

‎sdk/cosmos/azure_data_cosmos/docs/control-plane-warning.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<div class="warning">
22

3-
This is a control-plane API and requires that you authenticate using a key. To use Entra ID to perform this operation, you must use the [Azure Resource Manager APIs](https://learn.microsoft.com/en-us/azure/templates/microsoft.documentdb/databaseaccounts).
3+
This is a control-plane API and requires that you authenticate using a key. To use Entra ID to perform this operation, you must use the [Azure Resource Manager APIs](https://learn.microsoft.com/azure/templates/microsoft.documentdb/databaseaccounts).
44

55
</div>

0 commit comments

Comments
 (0)