Update azure_core README (#2174)

* Init core README update * add no_run to code samples * Update README with new examples for SecretClient usage and response handling * fix sample explaining response type * Update sdk/core/azure_core/README.md Co-authored-by: Heath Stewart <[email protected]> * Update sdk/core/azure_core/README.md Co-authored-by: Heath Stewart <[email protected]> * Update sdk/core/azure_core/README.md Co-authored-by: Heath Stewart <[email protected]> * Update sdk/core/azure_core/README.md Co-authored-by: Heath Stewart <[email protected]> * Update sdk/core/azure_core/README.md Co-authored-by: Heath Stewart <[email protected]> * Fix formatting and improve error handling examples in README * Removing samples that are not implemented yet. --------- Co-authored-by: Heath Stewart <[email protected]>
Azure · Feb 14, 2025 · 96c6d4d · 96c6d4d
1 parent c6ceff1
commit 96c6d4d
Showing 1 changed file with 218 additions and 15 deletions.
diff --git a/sdk/core/azure_core/README.md b/sdk/core/azure_core/README.md
@@ -1,20 +1,223 @@
-# azure_core
+# Azure Core shared client library for Rust
 
-> Microsoft is developing the official Azure SDK for Rust crates and has no plans to update this unofficial crate.
-> In the future we may release an official version that may have a different package name.
-> If releasing an official version of this crate is important to you [let us know](https://github.com/Azure/azure-sdk-for-rust/issues/new/choose).
->
-> Source for this crate can now be found in <https://github.com/Azure/azure-sdk-for-rust/tree/legacy>.
-> To monitor for an official, supported version of this crate, see <https://aka.ms/azsdk/releases>.
+`azure_core` provides shared primitives, abstractions, and helpers for modern Rust Azure SDK client libraries.
+These libraries follow the [Azure SDK Design Guidelines for Rust](https://azure.github.io/azure-sdk/rust_introduction.html)
+and can be easily identified by package and namespaces names starting with `azure_`, e.g. `azure_identity`.
 
-Core types and traits for the Rust Azure SDK.
+`azure_core` allows client libraries to expose common functionality in a consistent fashion,
+so that once you learn how to use these APIs in one client library, you will know how to use them in other client libraries.
 
-This crate is part of the unofficial Azure SDK effort in Rust. For more
-information on the project and an overview of other crates, please refer to
-[our GitHub repository](https://github.com/azure/azure-sdk-for-rust).
+[Source code] | [Package (crates.io)] | [API Reference Documentation]
 
-It is a library that provides cross-cutting services to other client
-libraries.  Please see the [general
-guidelines](https://azure.github.io/azure-sdk/general_azurecore.html).
+## Getting started
 
-License: MIT
+Typically, you will not need to install `azure_core`;
+it will be installed for you when you install one of the client libraries using it.
+In case you want to install it explicitly (to implement your own client library, for example),
+you can find the crates.io package [here][Package (crates.io)].
+
+## Key concepts
+
+The main shared concepts of `azure_core` (and so Azure SDK libraries using `azure_core`) include:
+
+- Configuring service clients, e.g. configuring retries, logging (`ClientOptions`).
+- Accessing HTTP response details (`Response<T>`).
+- Paging and asynchronous streams (`Pager<T>`).
+- Errors from service requests in a consistent fashion. (`azure_core::Error`).
+- Customizing requests (`ClientOptions`).
+- Abstractions for representing Azure SDK credentials. (`TokenCredentials`).
+
+### Thread safety
+
+We guarantee that all client instance methods are thread-safe and independent of each other ([guideline](https://azure.github.io/azure-sdk/rust_introduction.html)). This ensures that the recommendation of reusing client instances is always safe, even across threads.
+
+### Additional concepts
+<!-- CLIENT COMMON BAR -->
+[Client options](#configuring-service-clients-using-clientoptions) |
+[Accessing the response](#accessing-http-response-details-using-responset) |
+[Handling Errors Results](#handling-errors-results) |
+[Consuming Service Methods Returning `Pager<T>`](#consuming-service-methods-returning-pagert)
+
+<!-- CLIENT COMMON BAR -->
+
+## Examples
+
+**NOTE:** Samples in this file apply only to packages that follow [Azure SDK Design Guidelines](https://azure.github.io/azure-sdk/rust_introduction.html). Names of such packages usually start with `azure_`.
+
+### Configuring Service Clients Using `ClientOptions`
+
+Azure SDK client libraries typically expose one or more _service client_ types that
+are the main starting points for calling corresponding Azure services.
+You can easily find these client types as their names end with the word _Client_.
+For example, `SecretClient` can be used to call the Key Vault service and interact with secrets,
+and `KeyClient` can be used to access Key Vault service cryptographic keys.
+
+These client types can be instantiated by calling a simple `new` function that takes various configuration options.These options are passed as a parameter that extends `ClientOptions` class exposed by `azure_core`.
+Various service specific options are usually added to its subclasses, but a set of SDK-wide options are
+available directly on `ClientOptions`.
+
+```rust no_run
+use azure_core::ClientOptions;
+use azure_identity::DefaultAzureCredential;
+use azure_security_keyvault_secrets::{SecretClient, SecretClientOptions};
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let options = SecretClientOptions {
+        api_version: "7.5".to_string(),
+        client_options: ClientOptions::default(),
+    };
+
+    let credential = DefaultAzureCredential::new()?;
+    let client = SecretClient::new(
+        "https://your-key-vault-name.vault.azure.net/",
+        credential.clone(),
+        Some(options),
+    )?;
+
+    Ok(())
+}
+```
+
+### Accessing HTTP Response Details Using `Response<T>`
+
+_Service clients_ have methods that can be used to call Azure services. We refer to these client methods as _service methods_.
+_Service methods_ return a shared `azure_core` type `Response<T>` (in rare cases its non-generic sibling, a raw `Response`).
+This type provides access to both the deserialized result of the service call, and to the details of the HTTP response returned from the server.
+
+```rust no_run
+use azure_core::Response;
+use azure_identity::DefaultAzureCredential;
+use azure_security_keyvault_secrets::{models::SecretBundle, SecretClient};
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // create a client
+    let credential = DefaultAzureCredential::new()?;
+    let client = SecretClient::new(
+        "https://your-key-vault-name.vault.azure.net/",
+        credential.clone(),
+        None,
+    )?;
+
+    // call a service method, which returns Response<T>
+    let response: Response<SecretBundle> = client.get_secret("SecretName", "", None).await?;
+
+    // Response<T> has two main accessors.
+    // The into_body() function for accessing the deserialized result of the call
+    let secret = response.into_body().await?;
+
+    // get response again because it was moved in above statement
+    let response: Response<SecretBundle> = client.get_secret("SecretName", "", None).await?;
+
+    // .. and the deconstruct() method for accessing all the details of the HTTP response
+    let (status, headers, body) = response.deconstruct();
+
+    // for example, you can access HTTP status
+    println!("Status: {}", status);
+
+    // or the headers
+    for (header_name, header_value) in headers.iter() {
+        println!("{}: {}", header_name.as_str(), header_value.as_str());
+    }
+
+    Ok(())
+}
+```
+
+### Handling Errors Results
+
+When a service call fails, the returned `Result` will contain an `Error`. The `Error` type provides a status property with an HTTP status code and an error_code property with a service-specific error code.
+
+```rust no_run
+use azure_core::{error::HttpError, Response, StatusCode};
+use azure_identity::DefaultAzureCredential;
+use azure_security_keyvault_secrets::SecretClient;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // create a client
+    let credential = DefaultAzureCredential::new()?;
+    let client = SecretClient::new(
+        "https://your-key-vault-name.vault.azure.net/",
+        credential.clone(),
+        None,
+    )?;
+
+    match client.get_secret("secret_name", "", None).await {
+        Ok(secret) => println!("Secret: {:?}", secret.into_body().await?.value),
+        Err(e) => match e {
+            azure_core::Error::HttpResponse { status, error_code, .. } if status == StatusCode::NotFound => {
+                // handle not found error
+                if let Some(code) = error_code {
+                    println!("ErrorCode: {}", code);
+                } else {
+                    println!("Secret not found, but no error code provided.");
+                }
+            },
+            _ => println!("An error occurred: {:?}", e),
+        },
+    }
+
+    Ok(())
+}
+```
+
+### Consuming Service Methods Returning `Pager<T>`
+
+If a service call returns multiple values in pages, it would return `Result<Pager<T>>` as a result. You can iterate over `AsyncPageable` directly or in pages.
+
+```rust no_run
+use azure_identity::DefaultAzureCredential;
+use azure_security_keyvault_secrets::{ResourceExt, SecretClient};
+use futures::TryStreamExt;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Create a new secret client
+    let credential = DefaultAzureCredential::new()?;
+    let client = SecretClient::new(
+        "https://your-key-vault-name.vault.azure.net/",
+        credential.clone(),
+        None,
+    )?;
+
+    // Get pager stream
+    let mut pager = client.get_secrets(None)?.into_stream();
+
+    // Poll pager until there are no more SecretListResults
+    while let Some(secrets) = pager.try_next().await? {
+        // If Secrets List is None try next page
+        let Some(secrets) = secrets.into_body().await?.value else {
+            continue;
+        };
+
+        // Loop through secrets in Secrets List
+        for secret in secrets {
+            // Get the secret name from the ID.
+            let name = secret.resource_id()?.name;
+            println!("Found Secret with Name: {}", name);
+        }
+    }
+
+    Ok(())
+}
+```
+
+<!-- ## Troubleshooting -->
+
+## Contributing
+
+See the [CONTRIBUTING.md] for details on building, testing, and contributing to these libraries.
+
+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://opensource.microsoft.com/cla/>.
+
+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 will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct]. For more information see the [Code of Conduct FAQ] or contact <[email protected]> with any additional questions or comments.
+
+[Source code]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/core/azure_core/src
+[Package (crates.io)]: https://crates.io/crates/azure_core
+[API Reference Documentation]: https://docs.rs/azure_core
+[CONTRIBUTING.md]: https://github.com/Azure/azure-sdk-for-rust/blob/main/CONTRIBUTING.md
+[Code of Conduct FAQ]: https://opensource.microsoft.com/codeofconduct/faq/