Cosmos Tweaks (#842)

* Add some docs to header constants

* Use COSMOS_PRIMARY_KEY instead of COSMOS_MASTER_KEY

* Clean up Cosmos crate docs

* Make operations private

* Add more docs to cosmos entity

* Rename add_as_partition_key_header_serialized{2,}

* Stop using headers_mut

* Also use primary_key instead of master_key

* More client docs

* Fix up order of client methods

Author: rylev

sdk/core/src/constants.rs

@@ -1,6 +1,5 @@
 /// Endpoints for Azure Resource Manager in different Azure clouds
 pub mod resource_manager_endpoint {
-
     /// Azure Resource Manager China cloud endpoint
     pub const AZURE_CHINA_CLOUD: &str = "https://management.chinacloudapi.cn";
 
@@ -14,9 +13,10 @@ pub mod resource_manager_endpoint {
     pub const AZURE_US_GOVERNMENT_CLOUD: &str = "https://management.usgovcloudapi.net";
 }
 
-/// https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Type
+/// Constants related to the Content-Type header
+///
+/// <https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Type>
 pub mod content_type {
-
     // Form content types
     // https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4
 
@@ -28,6 +28,9 @@ pub mod content_type {
     pub const APPLICATION_OCTET_STREAM: &str = "application/octet-stream";
 }
 
+/// Constants related to the Content-Type header
+///
+/// <https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Type>
 pub mod query_param {
     pub const API_VERSION: &str = "api-version";
 }

sdk/data_cosmos/README.md

@@ -38,8 +38,8 @@ impl<'a> azure_data_cosmos::CosmosEntity<'a> for MySampleStruct {
 #[tokio::main]
 async fn main() -> azure_core::Result<()> {
     // Let's get Cosmos account and master key from env variables.
-    let master_key =
-        std::env::var("COSMOS_MASTER_KEY").expect("Set env variable COSMOS_MASTER_KEY first!");
+    let primary_key =
+        std::env::var("COSMOS_PRIMARY_KEY").expect("Set env variable COSMOS_PRIMARY_KEY first!");
     let account = std::env::var("COSMOS_ACCOUNT").expect("Set env variable COSMOS_ACCOUNT first!");
 
     let database_name = std::env::args()
@@ -53,7 +53,7 @@ async fn main() -> azure_core::Result<()> {
     // constrained. This SDK supports both.
     // Please check the Azure documentation for details or the examples folder
     // on how to create and use token-based permissions.
-    let authorization_token = AuthorizationToken::primary_from_base64(&master_key)?;
+    let authorization_token = AuthorizationToken::primary_from_base64(&primary_key)?;
 
     // Next we will create a Cosmos client.
     let client = CosmosClient::new(account.clone(), authorization_token, CosmosOptions::default());

sdk/data_cosmos/examples/attachments_00.rs

@@ -30,11 +30,11 @@ async fn main() -> azure_core::Result<()> {
         .nth(2)
         .expect("please specify collection name as second command line parameter");
 
-    let master_key =
-        std::env::var("COSMOS_MASTER_KEY").expect("Set env variable COSMOS_MASTER_KEY first!");
+    let primary_key =
+        std::env::var("COSMOS_PRIMARY_KEY").expect("Set env variable COSMOS_PRIMARY_KEY first!");
     let account = std::env::var("COSMOS_ACCOUNT").expect("Set env variable COSMOS_ACCOUNT first!");
 
-    let authorization_token = AuthorizationToken::primary_from_base64(&master_key)?;
+    let authorization_token = AuthorizationToken::primary_from_base64(&primary_key)?;
 
     let client = CosmosClient::new(account, authorization_token, CosmosOptions::default());
     let client = client

sdk/data_cosmos/examples/cancellation.rs

@@ -9,9 +9,9 @@ async fn main() -> azure_core::Result<()> {
     // First we retrieve the account name and master key from environment variables, and
     // create an authorization token.
     let account = std::env::var("COSMOS_ACCOUNT").expect("Set env variable COSMOS_ACCOUNT first!");
-    let master_key =
-        std::env::var("COSMOS_MASTER_KEY").expect("Set env variable COSMOS_MASTER_KEY first!");
-    let authorization_token = AuthorizationToken::primary_from_base64(&master_key)?;
+    let primary_key =
+        std::env::var("COSMOS_PRIMARY_KEY").expect("Set env variable COSMOS_PRIMARY_KEY first!");
+    let authorization_token = AuthorizationToken::primary_from_base64(&primary_key)?;
 
     // Create a new Cosmos client.
     let options = CosmosOptions::default();

sdk/data_cosmos/examples/collection.rs

@@ -5,8 +5,8 @@ use futures::stream::StreamExt;
 async fn main() -> azure_core::Result<()> {
     // First we retrieve the account name and master key from environment variables.
     // We expect master keys (ie, not resource constrained)
-    let master_key =
-        std::env::var("COSMOS_MASTER_KEY").expect("Set env variable COSMOS_MASTER_KEY first!");
+    let primary_key =
+        std::env::var("COSMOS_PRIMARY_KEY").expect("Set env variable COSMOS_PRIMARY_KEY first!");
     let account = std::env::var("COSMOS_ACCOUNT").expect("Set env variable COSMOS_ACCOUNT first!");
 
     // This is how you construct an authorization token.
@@ -17,7 +17,7 @@ async fn main() -> azure_core::Result<()> {
     // errors, plus Azure specific ones. For example if a REST call returns the
     // unexpected result (ie NotFound instead of Ok) we return an Err telling
     // you that.
-    let authorization_token = AuthorizationToken::primary_from_base64(&master_key)?;
+    let authorization_token = AuthorizationToken::primary_from_base64(&primary_key)?;
 
     // Once we have an authorization token you can create a client instance. You can change the
     // authorization token at later time if you need, for example, to escalate the privileges for a

sdk/data_cosmos/examples/create_delete_database.rs

@@ -5,8 +5,8 @@ use futures::stream::StreamExt;
 async fn main() -> azure_core::Result<()> {
     // First we retrieve the account name and master key from environment variables.
     // We expect master keys (ie, not resource constrained)
-    let master_key =
-        std::env::var("COSMOS_MASTER_KEY").expect("Set env variable COSMOS_MASTER_KEY first!");
+    let primary_key =
+        std::env::var("COSMOS_PRIMARY_KEY").expect("Set env variable COSMOS_PRIMARY_KEY first!");
     let account = std::env::var("COSMOS_ACCOUNT").expect("Set env variable COSMOS_ACCOUNT first!");
 
     let database_name = std::env::args()
@@ -21,7 +21,7 @@ async fn main() -> azure_core::Result<()> {
     // errors, plus Azure specific ones. For example if a REST call returns the
     // unexpected result (ie NotFound instead of Ok) we return an Err telling
     // you that.
-    let authorization_token = permission::AuthorizationToken::primary_from_base64(&master_key)?;
+    let authorization_token = permission::AuthorizationToken::primary_from_base64(&primary_key)?;
 
     // Once we have an authorization token you can create a client instance. You can change the
     // authorization token at later time if you need, for example, to escalate the privileges for a

sdk/data_cosmos/examples/database_00.rs

@@ -6,11 +6,11 @@ use serde_json::Value;
 async fn main() -> azure_core::Result<()> {
     // First we retrieve the account name and master key from environment variables.
     // We expect master keys (ie, not resource constrained)
-    let master_key =
-        std::env::var("COSMOS_MASTER_KEY").expect("Set env variable COSMOS_MASTER_KEY first!");
+    let primary_key =
+        std::env::var("COSMOS_PRIMARY_KEY").expect("Set env variable COSMOS_PRIMARY_KEY first!");
     let account = std::env::var("COSMOS_ACCOUNT").expect("Set env variable COSMOS_ACCOUNT first!");
 
-    let authorization_token = permission::AuthorizationToken::primary_from_base64(&master_key)?;
+    let authorization_token = permission::AuthorizationToken::primary_from_base64(&primary_key)?;
 
     let client = CosmosClient::new(account, authorization_token, CosmosOptions::default());
 

sdk/data_cosmos/examples/database_01.rs

@@ -5,11 +5,11 @@ use futures::stream::StreamExt;
 async fn main() -> azure_core::Result<()> {
     // First we retrieve the account name and master key from environment variables.
     // We expect master keys (ie, not resource constrained)
-    let master_key =
-        std::env::var("COSMOS_MASTER_KEY").expect("Set env variable COSMOS_MASTER_KEY first!");
+    let primary_key =
+        std::env::var("COSMOS_PRIMARY_KEY").expect("Set env variable COSMOS_PRIMARY_KEY first!");
     let account = std::env::var("COSMOS_ACCOUNT").expect("Set env variable COSMOS_ACCOUNT first!");
 
-    let authorization_token = AuthorizationToken::primary_from_base64(&master_key)?;
+    let authorization_token = AuthorizationToken::primary_from_base64(&primary_key)?;
 
     let client = CosmosClient::new(account, authorization_token, CosmosOptions::default());
 

sdk/data_cosmos/examples/document_00.rs

@@ -35,14 +35,14 @@ const COLLECTION: &str = "azuresdktc";
 async fn main() -> azure_core::Result<()> {
     // Let's get Cosmos account and master key from env variables.
     // This helps automated testing.
-    let master_key =
-        std::env::var("COSMOS_MASTER_KEY").expect("Set env variable COSMOS_MASTER_KEY first!");
+    let primary_key =
+        std::env::var("COSMOS_PRIMARY_KEY").expect("Set env variable COSMOS_PRIMARY_KEY first!");
     let account = std::env::var("COSMOS_ACCOUNT").expect("Set env variable COSMOS_ACCOUNT first!");
 
     // First, we create an authorization token. There are two types of tokens, master and resource
     // constrained. Please check the Azure documentation for details. You can change tokens
     // at will and it's a good practice to raise your privileges only when needed.
-    let authorization_token = AuthorizationToken::primary_from_base64(&master_key)?;
+    let authorization_token = AuthorizationToken::primary_from_base64(&primary_key)?;
 
     // Next we will create a Cosmos client. You need an authorization_token but you can later
     // change it if needed.

sdk/data_cosmos/examples/document_entries_00.rs

@@ -32,11 +32,11 @@ async fn main() -> azure_core::Result<()> {
         .nth(2)
         .expect("please specify collection name as second command line parameter");
 
-    let master_key =
-        std::env::var("COSMOS_MASTER_KEY").expect("Set env variable COSMOS_MASTER_KEY first!");
+    let primary_key =
+        std::env::var("COSMOS_PRIMARY_KEY").expect("Set env variable COSMOS_PRIMARY_KEY first!");
     let account = std::env::var("COSMOS_ACCOUNT").expect("Set env variable COSMOS_ACCOUNT first!");
 
-    let authorization_token = permission::AuthorizationToken::primary_from_base64(&master_key)?;
+    let authorization_token = permission::AuthorizationToken::primary_from_base64(&primary_key)?;
 
     let client = CosmosClient::new(account, authorization_token, CosmosOptions::default());
     let client = client.database_client(database_name);