|
1 | 1 | # Microsoft Azure SDK for Rust |
2 | 2 |
|
3 | | -> :construction: :construction: |
4 | | -> |
5 | | -> **Warning**: This repo is in *maintenance mode* only. |
6 | | -> It's being migrated to the [Microsoft Open Source](https://github.com/Azure) org :two_hearts:. The new repo is here [https://github.com/Azure/azure-sdk-for-rust](https://github.com/Azure/azure-sdk-for-rust). |
7 | | -> |
8 | | -> In maintenance mode only essential PRs will be accepted; non bug-related issues will be closed. |
9 | | -> As soon as the migration is completed this repo will become read-only. |
10 | | -> |
11 | | -> :construction: :construction: |
| 3 | +Given the success of Rust in general and this repository in particular, we at Microsoft decided it was due time to migrate it in the [Microsoft Azure |
| 4 | +](https://github.com/Azure) organization. The new repo - still unofficial and unsupported - is here [https://github.com/Azure/azure-sdk-for-rust](https://github.com/Azure/azure-sdk-for-rust). While unoffical and unsupported this step marks the "adulthood" of this repository and it will hopefully attract more talent from the community. |
12 | 5 |
|
| 6 | +I took care to migrate all the commits so you will find all the code history there, **along with your contributions** of course! |
13 | 7 |
|
14 | | -[](LICENSE) |
| 8 | +> :construction: :construction: Please refer to the [new repository](https://github.com/Azure/azure-sdk-for-rust) from now on. |
15 | 9 |
|
16 | | -[](https://travis-ci.org/MindFlavor/AzureSDKForRust) [](https://coveralls.io/github/MindFlavor/AzureSDKForRust?branch=master)  |
| 10 | +This repository have been made read-only for your convenience. |
17 | 11 |
|
18 | | -[](https://github.com/MindFlavor/AzureSDKForRust/tree/queue_0.1.0) [](https://github.com/MindFlavor/AzureSDKForRust/releases/tag/queue_0.1.0) [](https://github.com/MindFlavor/AzureSDKForRust/commits/master) |
19 | | - |
20 | | -[](https://github.com/MindFlavor/AzureSDKForRust/graphs/contributors) |
21 | | - |
22 | | -Crate repo | Docs | Crates.io | Downloads | Downloads@Latest | |
23 | | --- | -- | -- | -- | -- | |
24 | | -[azure_sdk_auth_aad](https://github.com/MindFlavor/AzureSDKForRust/tree/master/azure_sdk_auth_aad) | [](https://docs.rs/azure_sdk_auth_aad) | [](https://crates.io/crates/azure_sdk_auth_aad) | [](https://crates.io/crates/azure_sdk_auth_aad) | [](https://crates.io/crates/azure_sdk_auth_aad) |
25 | | -[azure_sdk_core](https://github.com/MindFlavor/AzureSDKForRust/tree/master/azure_sdk_core) | [](https://docs.rs/azure_sdk_core) | [](https://crates.io/crates/azure_sdk_core) | [](https://crates.io/crates/azure_sdk_core) | [](https://crates.io/crates/azure_sdk_core) |
26 | | -[azure_sdk_cosmos](https://github.com/MindFlavor/AzureSDKForRust/tree/master/azure_sdk_cosmos) | [](https://docs.rs/azure_sdk_cosmos) | [](https://crates.io/crates/azure_sdk_cosmos) | [](https://crates.io/crates/azure_sdk_cosmos) | [](https://crates.io/crates/azure_sdk_cosmos) |
27 | | -[azure_sdk_service_bus](https://github.com/MindFlavor/AzureSDKForRust/tree/master/azure_sdk_service_bus) | [](https://docs.rs/azure_sdk_service_bus) | [](https://crates.io/crates/azure_sdk_service_bus) | [](https://crates.io/crates/azure_sdk_service_bus) | [](https://crates.io/crates/azure_sdk_service_bus) |
28 | | -[azure_sdk_storage_account](https://github.com/MindFlavor/AzureSDKForRust/tree/master/azure_sdk_storage_account) | [](https://docs.rs/azure_sdk_storage_account) | [](https://crates.io/crates/azure_sdk_storage_account) | [](https://crates.io/crates/azure_sdk_storage_account) | [](https://crates.io/crates/azure_sdk_storage_account) |
29 | | -[azure_sdk_storage_blob](https://github.com/MindFlavor/AzureSDKForRust/tree/master/azure_sdk_storage_blob) | [](https://docs.rs/azure_sdk_storage_blob) | [](https://crates.io/crates/azure_sdk_storage_blob) | [](https://crates.io/crates/azure_sdk_storage_blob) | [](https://crates.io/crates/azure_sdk_storage_blob) |
30 | | -[azure_sdk_storage_queue](https://github.com/MindFlavor/AzureSDKForRust/tree/master/azure_sdk_storage_queue) | [](https://docs.rs/azure_sdk_storage_queue) | [](https://crates.io/crates/azure_sdk_storage_queue) | [](https://crates.io/crates/azure_sdk_storage_queue) | [](https://crates.io/crates/azure_sdk_storage_queue) |
31 | | -[azure_sdk_storage_core](https://github.com/MindFlavor/AzureSDKForRust/tree/master/azure_sdk_storage_core) | [](https://docs.rs/azure_sdk_storage_core) | [](https://crates.io/crates/azure_sdk_storage_core) | [](https://crates.io/crates/azure_sdk_storage_core) | [](https://crates.io/crates/azure_sdk_storage_core) |
32 | | -[azure_sdk_storage_table](https://github.com/MindFlavor/AzureSDKForRust/tree/master/azure_sdk_storage_table) | [](https://docs.rs/azure_sdk_storage_table) | [](https://crates.io/crates/azure_sdk_storage_table) | [](https://crates.io/crates/azure_sdk_storage_table) | [](https://crates.io/crates/azure_sdk_storage_table) |
33 | | - |
34 | | -#### Ancillary crates |
35 | | - |
36 | | -Ancillary crates are maintained in a separated GitHub repo by other members of the community. If you have a crate that you want to list here do not hesitate to drop a line/PR. |
37 | | - |
38 | | -Crate repo | Maintainer | Docs | Crates.io | Downloads | Downloads@Latest | Contributors |
39 | | --- | -- | -- | -- | -- | -- | -- | |
40 | | -[azure-sdk-keyvault](https://github.com/guywaldman/azure-sdk-keyvault) | [Guy Waldman](https://github.com/guywaldman) | [](https://docs.rs/azure-sdk-keyvault) | [](https://crates.io/crates/azure_sdk_keyvault) | [](https://crates.io/crates/azure_sdk_keyvault) | [](https://crates.io/crates/azure_sdk_keyvault) | [](https://github.com/guywaldman/azure-sdk-keyvault/graphs/contributors) |
41 | | - |
42 | | -## Introduction |
43 | | -Microsoft Azure exposes its technologies via REST API. These APIs are easily consumable from any language (good) but are weakly typed. With this library and its related [crate](https://crates.io/crates/azure_sdk_for_rust/) you can exploit the power of Microsoft Azure from Rust in a idiomatic way. |
44 | | - |
45 | | -This crate relies heavily on the excellent crate called [Hyper](https://github.com/hyperium/hyper). As of this library version [0.30.0](https://github.com/MindFlavor/AzureSDKForRust/releases/tag/0.30.0) all the methods are async/await compliant (`futures 0.3`). |
46 | | - |
47 | | -From version 0.8.0 for Cosmos and 0.9.0 for Storage the repo is embracing the builder pattern. As of 0.10.0, most of storage APIs have been migrated to the builder pattern but there are methods still missing. Please chech the relevant issues to follow the update process. This is still an in-progress transition but the resulting API is much more easy to use. Also most checks have been moved to compile-time. Unfortunately the changes are not backward-compatibile. I have blogged about my appoach here: [https://dev.to/mindflavor/rust-builder-pattern-with-types-3chf](https://dev.to/mindflavor/rust-builder-pattern-with-types-3chf). |
48 | | - |
49 | | -From version 0.12.0 the library switched from [hyper-tls](https://github.com/hyperium/hyper-tls) to [hyper-rustls](https://github.com/ctz/hyper-rustls) as suggested by [bmc-msft](https://github.com/bmc-msft) in the issue [#120](https://github.com/MindFlavor/AzureSDKForRust/issues/120). This should allow the library to be 100% rust. |
50 | | - |
51 | | -> **NOTE:** This repository is under heavy development and is likely to break over time. The current releases will probabily contain bugs. As usual open issues if you find any. |
52 | | -
|
53 | | -## Disclaimer |
54 | | -Although I am a Microsoft employee, this is not a Microsoft endorsed project. It's simply a pet project of mine: I love Rust (who doesn't? :smirk:) and Microsoft Azure technologies so I thought to close the gap between them. It's also a good project for learning Rust. This library relies heavily on [Hyper](https://github.com/hyperium/hyper). We use the latest Hyper code so this library is fully async with Futures and Tokio. |
55 | | - |
56 | | -## Example |
57 | | -You can find examples in the [```examples```](https://github.com/MindFlavor/AzureSDKForRust/tree/master/azure_sdk_cosmos/examples) folder of each sub-crate. Here is a glimpse: |
58 | | - |
59 | | -### main.rs |
60 | | - |
61 | | -```rust |
62 | | -#[macro_use] |
63 | | -extern crate serde_derive; |
64 | | -// Using the prelude module of the Cosmos crate makes easier to use the Rust Azure SDK for Cosmos |
65 | | -// DB. |
66 | | -use azure_sdk_core::prelude::*; |
67 | | -use azure_sdk_cosmos::prelude::*; |
68 | | -use futures::stream::StreamExt; |
69 | | -use std::borrow::Cow; |
70 | | -use std::error::Error; |
71 | | - |
72 | | -// This is the stuct we want to use in our sample. |
73 | | -// Make sure to have a collection with partition key "a_number" for this example to |
74 | | -// work (you can create with this SDK too, check the examples folder for that task). |
75 | | -#[derive(Serialize, Deserialize, Debug)] |
76 | | -struct MySampleStruct<'a> { |
77 | | - id: Cow<'a, str>, |
78 | | - a_string: Cow<'a, str>, |
79 | | - a_number: u64, |
80 | | - a_timestamp: i64, |
81 | | -} |
82 | | - |
83 | | -// This code will perform these tasks: |
84 | | -// 1. Create 10 documents in the collection. |
85 | | -// 2. Stream all the documents. |
86 | | -// 3. Query the documents. |
87 | | -// 4. Delete the documents returned by task 4. |
88 | | -// 5. Check the remaining documents. |
89 | | -#[tokio::main] |
90 | | -async fn main() -> Result<(), Box<dyn Error>> { |
91 | | - // Let's get Cosmos account and master key from env variables. |
92 | | - // This helps automated testing. |
93 | | - let master_key = |
94 | | - std::env::var("COSMOS_MASTER_KEY").expect("Set env variable COSMOS_MASTER_KEY first!"); |
95 | | - let account = std::env::var("COSMOS_ACCOUNT").expect("Set env variable COSMOS_ACCOUNT first!"); |
96 | | - |
97 | | - let database_name = std::env::args() |
98 | | - .nth(1) |
99 | | - .expect("please specify the database name as first command line parameter"); |
100 | | - let collection_name = std::env::args() |
101 | | - .nth(2) |
102 | | - .expect("please specify the collection name as first command line parameter"); |
103 | | - |
104 | | - // First, we create an authorization token. There are two types of tokens, master and resource |
105 | | - // constrained. This SDK supports both. |
106 | | - // Please check the Azure documentation for details or the examples folder |
107 | | - // on how to create and use token-based permissions. |
108 | | - let authorization_token = AuthorizationToken::new_master(&master_key)?; |
109 | | - |
110 | | - // Next we will create a Cosmos client. |
111 | | - let client = ClientBuilder::new(account, authorization_token)?; |
112 | | - // We know the database so we can obtain a database client. |
113 | | - let database_client = client.with_database_client(database_name); |
114 | | - // We know the collection so we can obtain a collection client. |
115 | | - let collection_client = database_client.with_collection_client(collection_name); |
116 | | - |
117 | | - // TASK 1 - Insert 10 documents |
118 | | - println!("Inserting 10 documents..."); |
119 | | - let mut session_token = None; |
120 | | - for i in 0..10 { |
121 | | - // define the document. |
122 | | - let document_to_insert = Document::new(MySampleStruct { |
123 | | - id: Cow::Owned(format!("unique_id{}", i)), |
124 | | - a_string: Cow::Borrowed("Something here"), |
125 | | - a_number: i * 100, // this is the partition key |
126 | | - a_timestamp: chrono::Utc::now().timestamp(), |
127 | | - }); |
128 | | - |
129 | | - // insert it and store the returned session token for later use! |
130 | | - session_token = Some( |
131 | | - collection_client |
132 | | - .create_document() |
133 | | - .with_partition_keys( |
134 | | - PartitionKeys::new().push(&document_to_insert.document.a_number)?, |
135 | | - ) |
136 | | - .with_is_upsert(true) // this option will overwrite a preexisting document (if any) |
137 | | - .execute_with_document(&document_to_insert) |
138 | | - .await? |
139 | | - .session_token, // get only the session token, if everything else was ok! |
140 | | - ); |
141 | | - } |
142 | | - // wow that was easy and fast, wasnt'it? :) |
143 | | - println!("Done!"); |
144 | | - |
145 | | - let session_token = ConsistencyLevel::from(session_token.unwrap()); |
146 | | - |
147 | | - // TASK 2 |
148 | | - { |
149 | | - println!("\nStreaming documents"); |
150 | | - // we limit the number of documents to 3 for each batch as a demonstration. In practice |
151 | | - // you will use a more sensible number (or accept the Azure default). |
152 | | - let stream = collection_client |
153 | | - .list_documents() |
154 | | - .with_consistency_level(session_token.clone()) |
155 | | - .with_max_item_count(3); |
156 | | - let mut stream = Box::pin(stream.stream::<MySampleStruct>()); |
157 | | - // TODO: As soon as the streaming functionality is stabilized |
158 | | - // in Rust we can substitute this while let Some... into |
159 | | - // for each (or whatever the Rust team picks). |
160 | | - while let Some(res) = stream.next().await { |
161 | | - let res = res?; |
162 | | - println!("Received {} documents in one batch!", res.documents.len()); |
163 | | - res.documents.iter().for_each(|doc| println!("{:#?}", doc)); |
164 | | - } |
165 | | - } |
166 | | - |
167 | | - // TASK 3 |
168 | | - println!("\nQuerying documents"); |
169 | | - let query_documents_response = collection_client |
170 | | - .query_documents() |
171 | | - .with_query(&("SELECT * FROM A WHERE A.a_number < 600".into())) // there are other ways to construct a query, this is the simplest. |
172 | | - .with_query_cross_partition(true) // this will perform a cross partition query! notice how simple it is! |
173 | | - .with_consistency_level(session_token) |
174 | | - .execute::<MySampleStruct>() // This will make sure the result is our custom struct! |
175 | | - .await? |
176 | | - .into_documents() // queries can return Documents or Raw json (ie without etag, _rid, etc...). Since our query return docs we convert with this function. |
177 | | - .unwrap(); // we know in advance that the conversion to Document will not fail since we SELECT'ed * FROM table |
178 | | - |
179 | | - println!( |
180 | | - "Received {} documents!", |
181 | | - query_documents_response.results.len() |
182 | | - ); |
183 | | - |
184 | | - query_documents_response |
185 | | - .results |
186 | | - .iter() |
187 | | - .for_each(|document| { |
188 | | - println!("number ==> {}", document.result.a_number); |
189 | | - }); |
190 | | - |
191 | | - // TASK 4 |
192 | | - let session_token = ConsistencyLevel::from(query_documents_response.session_token.clone()); |
193 | | - for ref document in query_documents_response.results { |
194 | | - // From our query above we are sure to receive a Document. |
195 | | - println!( |
196 | | - "deleting id == {}, a_number == {}.", |
197 | | - document.result.id, document.result.a_number |
198 | | - ); |
199 | | - |
200 | | - // to spice the delete a little we use optimistic concurreny |
201 | | - collection_client |
202 | | - .with_document_client(&document.result.id as &str, document.result.a_number.into()) |
203 | | - .delete_document() |
204 | | - .with_consistency_level(session_token.clone()) |
205 | | - .with_if_match_condition((&document.document_attributes).into()) |
206 | | - .execute() |
207 | | - .await?; |
208 | | - } |
209 | | - |
210 | | - // TASK 5 |
211 | | - // Now the list documents should return 4 documents! |
212 | | - let list_documents_response = collection_client |
213 | | - .list_documents() |
214 | | - .with_consistency_level(session_token) |
215 | | - .execute::<serde_json::Value>() // you can use this if you don't know/care about the return type! |
216 | | - .await?; |
217 | | - assert_eq!(list_documents_response.documents.len(), 4); |
218 | | - |
219 | | - Ok(()) |
220 | | -} |
221 | | -``` |
222 | | - |
223 | | -## State of the art |
224 | | -Right now the key framework is in place (authentication, enumerations, parsing and so on). If you want to contribute please do! |
225 | | -Methods are added daily so please check the [release page](https://github.com/MindFlavor/AzureSDKForRust/releases) for updates on the progress. |
226 | | -Also note that the project is in early stages so the APIs are bound to change at any moment. I will strive to keep things steady but since I'm new to Rust I'm sure I'll have to correct some serious mistake before too long :smile:. |
227 | | -I generally build for the latest nightly and leave to Travis to check the retrocompatibility. |
228 | | - |
229 | | -## Contributing |
230 | | -If you want to contribute please do! No formality required! :wink:. Please note that asking for a pull request you accept to yield your code as per [Apache license, version 2.0](LICENSE). |
231 | | - |
232 | | -## Run E2E test |
233 | | - |
234 | | -### Linux |
235 | | - |
236 | | -```bash |
237 | | -export STORAGE_ACCOUNT=<account> |
238 | | -export STORAGE_MASTER_KEY=<key> |
239 | | - |
240 | | -export AZURE_SERVICE_BUS_NAMESPACE=<azure_service_bus_namespace> |
241 | | -export AZURE_EVENT_HUB_NAME=<azure_event_hub_name> |
242 | | -export AZURE_POLICY_NAME=<azure_policy_name> |
243 | | -export AZURE_POLICY_KEY=<azure policy key> |
244 | | - |
245 | | -export COSMOS_ACCOUNT=<cosmos_account> |
246 | | -export COSMOS_KEY=<cosmos_master_key> |
247 | | - |
248 | | -cd azure_sdk_service_bus |
249 | | -cargo test --features=test_e2e |
250 | | - |
251 | | -cd ../azure_sdk_storage_blob |
252 | | -cargo test --features=test_e2e |
253 | | - |
254 | | -cd ../azure_sdk_storage_account |
255 | | -cargo test --features=test_e2e |
256 | | - |
257 | | -cd ../azure_sdk_cosmos |
258 | | -cargo test --features=test_e2e |
259 | | -``` |
260 | | - |
261 | | -### Windows |
262 | | - |
263 | | -```bat |
264 | | -set STORAGE_ACCOUNT=<account> |
265 | | -set STORAGE_MASTER_KEY=<key> |
266 | | -
|
267 | | -set AZURE_SERVICE_BUS_NAMESPACE=<azure_service_bus_namespace> |
268 | | -set AZURE_EVENT_HUB_NAME=<azure_event_hub_name> |
269 | | -set AZURE_POLICY_NAME=<azure_policy_name> |
270 | | -set AZURE_POLICY_KEY=<azure policy key> |
271 | | -
|
272 | | -set COSMOS_ACCOUNT=<cosmos_account> |
273 | | -set COSMOS_MASTER_KEY=<cosmos_master_key> |
274 | | -
|
275 | | -cd azure_sdk_service_bus |
276 | | -cargo test --features=test_e2e |
277 | | -
|
278 | | -cd ../azure_sdk_storage_blob |
279 | | -cargo test --features=test_e2e |
280 | | -
|
281 | | -cd ../azure_sdk_storage_account |
282 | | -cargo test --features=test_e2e |
283 | | -
|
284 | | -cd ../azure_sdk_cosmos |
285 | | -cargo test --features=test_e2e |
286 | | -``` |
287 | | - |
288 | | -## License |
289 | | -This project is published under [Apache license, version 2.0](LICENSE). |
| 12 | +## :two_hearts: Thank you for your involvement and effort, this important step would not have been possible without **you**! :two_hearts: |
0 commit comments