Merge pull request #295249 from paulth1/comm-service-tutorials

[AQ] edit pass: Comm service tutorials

Author: ShawnJackson

articles/communication-services/tutorials/hmac-header-tutorial.md

@@ -1,7 +1,7 @@
 ---
-title: Learn how to sign an HTTP request with HMAC
+title: Tutorial - Learn How to Sign an HTTP Request with HMAC
 titleSuffix: An Azure Communication Services tutorial
-description: Learn how to sign an HTTP request for Azure Communication Services using HMAC.
+description: Learn how to sign an HTTP request for Azure Communication Services by using HMAC.
 author: alexandra142
 manager: soricos
 services: azure-communication-services
@@ -15,12 +15,20 @@ ms.custom: devx-track-python
 zone_pivot_groups: acs-programming-languages-csharp-python
 ---
 
-# Sign an HTTP request
+# Tutorial: Sign an HTTP request
 
-In this tutorial, you'll learn how to sign an HTTP request with an HMAC signature.
+In this tutorial, you learn how to sign an HTTP request with a hash-based message authentication code (HMAC) signature.
 
->[!NOTE]
->We strongly encourage to use [Azure SDKs](https://github.com/Azure/azure-sdk). Approach described here is a fallback option for cases when Azure SDKs can't be used for any reason.
+> [!NOTE]
+> We strongly encourage you to use [Azure SDKs](https://github.com/Azure/azure-sdk). The approach described here is a fallback option for cases when Azure SDKs can't be used for any reason.
+
+In this tutorial, you learn how to:
+> [!div class="checklist"]
+> * Create a request message.
+> * Create a content hash.
+> * Compute a signature.
+> * Create an authorization header string.
+> * Add headers.
 
 ::: zone pivot="programming-language-csharp"
 [!INCLUDE [Sign an HTTP request with C#](./includes/hmac-header-csharp.md)]
@@ -32,15 +40,11 @@ In this tutorial, you'll learn how to sign an HTTP request with an HMAC signatur
 
 ## Clean up resources
 
-To clean up and remove a Communication Services subscription, delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it. You can find out more about [cleaning up Azure Communication Services resources](../quickstarts/create-communication-resource.md#clean-up-resources) and [cleaning Azure Functions resources](../../azure-functions/create-first-function-vs-code-csharp.md#clean-up-resources).
-
-## Next steps
-
-> [!div class="nextstepaction"]
-> [Add voice calling to your app](../quickstarts/voice-video-calling/getting-started-with-calling.md)
+To clean up and remove a Communication Services subscription, delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it. You can find out more about how to [clean up Azure Communication Services resources](../quickstarts/create-communication-resource.md#clean-up-resources) and [clean up Azure Functions resources](../../azure-functions/create-first-function-vs-code-csharp.md#clean-up-resources).
 
-You might also want to:
+## Related content
 
+- [Add voice calling to your app](../quickstarts/voice-video-calling/getting-started-with-calling.md)
 - [Add chat to your app](../quickstarts/chat/get-started.md)
 - [Create user access tokens](../quickstarts/identity/access-tokens.md)
 - [Learn about client and server architecture](../concepts/identity-model.md#client-server-architecture)

articles/communication-services/tutorials/includes/hmac-header-csharp.md

@@ -1,5 +1,5 @@
 ---
-title: Sign an HTTP request with C#
+title: Sign an HTTP Request with C#
 description: This tutorial explains the C# version of signing an HTTP request with an HMAC signature for Azure Communication Services.
 author: alexandra142
 manager: soricos
@@ -14,9 +14,9 @@ ms.service: azure-communication-services
 
 Before you get started, make sure to:
 
-- Create an Azure account with an active subscription. For details, see [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
+- Create an Azure account with an active subscription. If you don't have an Azure subscription, see [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
 - Install [Visual Studio](https://visualstudio.microsoft.com/downloads/).
-- Create an Azure Communication Services resource. For details, see [Create an Azure Communication Services resource](../../quickstarts/create-communication-resource.md). You'll need to record your **resourceEndpoint** and **resourceAccessKey** for this tutorial.
+- Create an Azure Communication Services resource. If you don't have a resource, see [Create a Communication Services resource](../../quickstarts/create-communication-resource.md). You need to record your `resourceEndpoint` and `resourceAccessKey` parameters for this tutorial.
 
 ## Sign an HTTP request with C#
 
@@ -34,13 +34,13 @@ The `hmac-sha256-signature` consists of:
 - Host
 - x-ms-content-sha256
 
-## Setup
+## Set up the authorization header
 
 The following steps describe how to construct the authorization header.
 
 ### Create a new C# application
 
-In a console window, such as cmd, PowerShell, or Bash, use the `dotnet new` command to create a new console app with the name `SignHmacTutorial`. This command creates a simple "Hello World" C# project with a single source file: **Program.cs**.
+In a console window, such as cmd, PowerShell, or Bash, use the `dotnet new` command to create a new console app with the name `SignHmacTutorial`. This command creates a simple "Hello World" C# project with a single source file: `Program.cs`.
 
 ```console
 dotnet new console -o SignHmacTutorial
@@ -87,7 +87,7 @@ namespace SignHmacTutorial
 
 ## Create a request message
 
-For this example, we'll sign a request to create a new identity by using the Communication Services Authentication API (version `2021-03-07`).
+For this example, you sign a request to create a new identity by using the Communication Services Authentication API (version `2021-03-07`).
 
 Add the following code to the `Main` method.
 
@@ -143,20 +143,20 @@ Replace `resourceAccessKey` with an access key of your real Communication Servic
 
 ## Create an authorization header string
 
-We'll now construct the string that we'll add to our authorization header.
+Now you construct the string that you add to your authorization header.
 
 1. Prepare values for the headers to be signed.
-   1. Specify the current timestamp using the Coordinated Universal Time (UTC) timezone.
-   1. Get the request authority (DNS host name or IP address and the port number).
+   1. Specify the current timestamp by using the Coordinated Universal Time (UTC) timezone.
+   1. Get the request authority. Use the Domain Name System (DNS) host name or IP address and the port number.
    1. Compute a content hash.
 1. Prepare a string to sign.
 1. Compute the signature.
-1. Concatenate the string, which will be used in the authorization header.
- 
+1. Concatenate the string, which is used in the authorization header.
+
 Add the following code to the `Main` method.
 
 ```csharp
-// Specify the 'x-ms-date' header as the current UTC timestamp according to the RFC1123 standard
+// Specify the 'x-ms-date' header as the current UTC timestamp according to the RFC1123 standard.
 var date = DateTimeOffset.UtcNow.ToString("r", CultureInfo.InvariantCulture);
 // Get the host name corresponding with the 'host' header.
 var host = requestUri.Authority;
@@ -173,7 +173,7 @@ var authorizationHeader = $"HMAC-SHA256 SignedHeaders=x-ms-date;host;x-ms-conten
 
 ## Add headers to requestMessage
 
-Use the following code to add the required headers to your `requestMessage`.
+Use the following code to add the required headers to your `requestMessage` parameter.
 
 ```csharp
 // Add a date header.

articles/communication-services/tutorials/includes/hmac-header-python.md

@@ -1,5 +1,5 @@
 ---
-title: Sign an HTTP request with Python
+title: Sign an HTTP Request with Python
 description: This tutorial explains the Python version of signing an HTTP request with an HMAC signature for Azure Communication Services.
 author: maximrytych-ms
 manager: anitharaju
@@ -14,10 +14,10 @@ ms.service: azure-communication-services
 
 Before you get started, make sure to:
 
-- Create an Azure account with an active subscription. For details, see [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
+- Create an Azure account with an active subscription. If you don't have an Azure subscription, see [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
 - Download and install [Python](https://www.python.org/).
-- Download and install [Visual Studio Code](https://code.visualstudio.com/) or other IDE that supports Python.
-- Create an Azure Communication Services resource. For details, see [Create an Azure Communication Services resource](../../quickstarts/create-communication-resource.md). You'll need your **resource_endpoint_name** and **resource_endpoint_secret** for this tutorial.
+- Download and install [Visual Studio Code](https://code.visualstudio.com/) or another integrated development environment (IDE) that supports Python.
+- Create an Azure Communication Services resource. If you don't have a resource, see [Create a Communication Services resource](../../quickstarts/create-communication-resource.md). You need your `resource_endpoint_name` and `resource_endpoint_secret` parameters for this tutorial.
 
 ## Sign an HTTP request with Python
 
@@ -35,13 +35,13 @@ The `hmac-sha256-signature` consists of:
 - Host
 - x-ms-content-sha256
 
-## Setup
+## Set up the authorization header
 
 The following steps describe how to construct the authorization header.
 
 ### Create a new Python script
 
-Open Visual Studio Code or other IDE or editor of your choice and create a new file named `sign_hmac_tutorial.py`. Save this file to a known folder.
+Open Visual Studio Code or another IDE or editor of your choice. Create a new file named `sign_hmac_tutorial.py`. Save this file to a known folder.
 
 ## Add necessary imports
 
@@ -58,12 +58,12 @@ from urllib import request
 
 ## Prepare data for the request
 
-For this example, we'll sign a request to create a new identity by using the Communication Services Authentication API [(version `2021-03-07`)](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/communication/data-plane/Identity/stable/2021-03-07).
+For this example, you sign a request to create a new identity by using the Communication Services Authentication API [(version `2021-03-07`)](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/communication/data-plane/Identity/stable/2021-03-07).
 
 Add the following code to the `sign_hmac_tutorial.py` script.
 
-- Replace `resource_endpoint_name` with your real resource endpoint name value. This value can be found in Overview section of your Azure Communication Services resource. It's the value of "Endpoint" after "https://".
-- Replace `resource_endpoint_secret` with your real resource endpoint secret value. This value can be found in Keys section of your Azure Communication Services resource. It's the value of "Key" - either primary or secondary.
+- Replace `resource_endpoint_name` with your real resource endpoint name value. You can find this value in the **Overview** section of your Communication Services resource. It's the value of `Endpoint` after `https://`.
+- Replace `resource_endpoint_secret` with your real resource endpoint secret value. You can find this value in the **Keys** section of your Communication Services resource. It's the value of **Key**, which is either primary or secondary.
 
 ```python
 host = "resource_endpoint_name"
@@ -74,7 +74,7 @@ secret = "resource_endpoint_secret"
 # Create a uri you are going to call.
 request_uri = f"{resource_endpoint}{path_and_query}"
 
-# Endpoint identities?api-version=2021-03-07 accepts list of scopes as a body.
+# Endpoint identities?api-version=2021-03-07 accepts the list of scopes as a body.
 body = { "createTokenWithScopes": ["chat"] }
 
 serialized_body = json.dumps(body)
@@ -83,7 +83,7 @@ content = serialized_body.encode("utf-8")
 
 ## Create a content hash
 
-The content hash is a part of your HMAC signature. Use the following code to compute the content hash. You can add this method to `sign_hmac_tutorial.py` script.
+The content hash is a part of your HMAC signature. Use the following code to compute the content hash. You can add this method to the `sign_hmac_tutorial.py` script.
 
 ```python
 def compute_content_hash(content):
@@ -109,9 +109,9 @@ def compute_signature(string_to_sign, secret):
     return signature
 ```
 
-## Get current UTC timestamp according to the RFC1123 standard
+## Get a current UTC timestamp according to the RFC1123 standard
 
-Use the following code to get desired date format independent of locale settings.
+Use the following code to get the date format that you want that's independent of locale settings.
 
 ```python
 def format_date(dt):
@@ -131,20 +131,20 @@ def format_date(dt):
 
 ## Create an authorization header string
 
-We'll now construct the string that we'll add to our authorization header.
+Now you construct the string that you add to your authorization header.
 
 1. Prepare values for the headers to be signed.
-   1. Specify the current timestamp using the Coordinated Universal Time (UTC) timezone.
-   1. Get the request authority (DNS host name or IP address and the port number).
+   1. Specify the current timestamp by using the Coordinated Universal Time (UTC) timezone.
+   1. Get the request authority. Use the Domain Name System (DNS) host name or IP address and the port number.
    1. Compute a content hash.
 1. Prepare a string to sign.
 1. Compute the signature.
-1. Concatenate the string, which will be used in the authorization header.
- 
+1. Concatenate the string, which is used in the authorization header.
+
 Add the following code to the `sign_hmac_tutorial.py` script.
 
 ```python
-# Specify the 'x-ms-date' header as the current UTC timestamp according to the RFC1123 standard
+# Specify the 'x-ms-date' header as the current UTC timestamp according to the RFC1123 standard.
 utc_now = datetime.now(timezone.utc)
 date = format_date(utc_now)
 # Compute a content hash for the 'x-ms-content-sha256' header.
@@ -168,13 +168,13 @@ request_headers = {}
 # Add a date header.
 request_headers["x-ms-date"] = date
 
-# Add content hash header.
+# Add a content hash header.
 request_headers["x-ms-content-sha256"] = content_hash
 
-# Add authorization header.
+# Add an authorization header.
 request_headers["Authorization"] = authorization_header
 
-# Add content type header.
+# Add a content type header.
 request_headers["Content-Type"] = "application/json"
 ```