Merge pull request #215456 from aahill/resource-test

quickstart update - resource provisioning + environment variables

Author: 19BMG00

articles/cognitive-services/language-service/includes/clean-up-variables.md

@@ -0,0 +1,44 @@
+---
+services: cognitive-services
+author: aahill
+manager: nitinme
+ms.service: cognitive-services
+ms.subservice: language-service
+ms.topic: include
+ms.date: 10/21/2022
+ms.author: aahi
+---
+
+Use the following commands to delete the environment variables you created for this quickstart.
+
+#### [Windows](#tab/windows)
+
+```console
+reg delete "HKCU\Environment" /v LANGUAGE_KEY /f
+```
+
+```console
+reg delete "HKCU\Environment" /v LANGUAGE_ENDPOINT /f
+```
+
+#### [Linux](#tab/linux)
+
+```bash
+unset LANGUAGE_KEY
+```
+
+```bash
+unset LANGUAGE_ENDPOINT
+```
+
+#### [macOS](#tab/macos)
+
+```bash
+unset LANGUAGE_KEY
+```
+
+```bash
+unset LANGUAGE_ENDPOINT
+```
+
+---

articles/cognitive-services/language-service/includes/create-resource.md

@@ -0,0 +1,48 @@
+---
+services: cognitive-services
+author: aahill
+manager: nitinme
+ms.service: cognitive-services
+ms.subservice: language-service
+ms.topic: include
+ms.date: 10/21/2022
+ms.author: aahi
+---
+
+### Create an Azure resource
+
+To use the code sample below, you'll need to deploy an Azure resource. This resource will contain a key and endpoint you'll use to authenticate the API calls you send to the Language service.
+
+1. Use the following link to [create a language resource](https://portal.azure.com/#create/Microsoft.CognitiveServicesTextAnalytics) using the Azure portal. You will need to sign in using your Azure subscription.
+1. On the **Select additional features** screen that appears, select **Continue to create your resource**.
+
+    :::image type="content" source="../media/portal-resource-additional-features.png" alt-text="A screenshot showing additional feature options in the Azure portal." lightbox="../media/portal-resource-additional-features.png":::
+
+1. In the **Create language** screen, provide the following information:
+
+    |Detail  |Description  | 
+    |---------|---------|
+    |Subscription     | The subscription account that your resource will be associated with. Select your Azure subscription from the drop-down menu.         |
+    |Resource group   | A resource group is a container that stores the resources you create. Select **Create new** to create a new resource group.         |
+    |Region     | The location of your Language resource. Different regions may introduce latency depending on your physical location, but have no impact on the runtime availability of your resource. For this quickstart, either select an available region near you, or choose **East US**.        |
+    |Name     | The name for your Language resource. This name will also be used to create an endpoint URL that your applications will use to send API requests.         |
+    |Pricing tier     | The [pricing tier](https://azure.microsoft.com/pricing/details/cognitive-services/language-service/) for your Language resource. You can use the **Free F0** tier to try the service and upgrade later to a paid tier for production.       |
+     
+    :::image type="content" source="../media/portal-resource-creation-details.png" alt-text="A screenshot showing resource creation details in the Azure portal." lightbox="../media/portal-resource-creation-details.png":::
+
+1. Make sure the **Responsible AI Notice** checkbox is checked.
+1. Select **Review + Create** at the bottom of the page.
+
+1. In the screen that appears, make sure the validation has passed, and that you entered your information correctly. Then click **Create**. 
+
+### Get your key and endpoint
+
+Next you will need the key and endpoint from the resource to connect your application to the API. You'll paste your key and endpoint into the code later in the quickstart.
+
+1. After the Language resource deploys successfully, click the **Go to Resource** button under **Next Steps**.
+
+    :::image type="content" source="../media/portal-resource-next-steps.png" alt-text="A screenshot showing the next steps after a resource has deployed." lightbox="../media/portal-resource-next-steps.png":::
+
+1. On the screen for your resource, select **Keys and endpoint** on the left navigation menu. You will use one of your keys and your endpoint in the steps below. 
+
+    :::image type="content" source="../media/azure-portal-resource-credentials.png" alt-text="A screenshot showing the keys and endpoint section for a resource." lightbox="../media/azure-portal-resource-credentials.png":::

articles/cognitive-services/language-service/includes/environment-variables.md

@@ -0,0 +1,79 @@
+---
+services: cognitive-services
+author: aahill
+manager: nitinme
+ms.service: cognitive-services
+ms.subservice: language-service
+ms.topic: include
+ms.date: 10/21/2022
+ms.author: aahi
+---
+
+### Create environment variables 
+
+Your application must be authenticated to send API requests. For production, use a secure way of storing and accessing your credentials. In this example, you will write your credentials to environment variables on the local machine running the application.
+
+> [!TIP]
+> Don't include the key directly in your code, and never post it publicly. See the Cognitive Services [security](../../security-features.md) article for more authentication options like [Azure Key Vault](../../use-key-vault.md). 
+
+To set the environment variable for your Language resource key, open a console window, and follow the instructions for your operating system and development environment. 
+
+1. To set the `LANGUAGE_KEY` environment variable, replace `your-key` with one of the keys for your resource.
+2. To set the `LANGUAGE_ENDPOINT` environment variable, replace `your-endpoint` with the endpoint for your resource.
+
+#### [Windows](#tab/windows)
+
+```console
+setx LANGUAGE_KEY your-key
+```
+
+```console
+setx LANGUAGE_ENDPOINT your-endpoint
+```
+
+> [!NOTE]
+> If you only need to access the environment variables in the current running console, you can set the environment variable with `set` instead of `setx`.
+
+After you add the environment variables, you may need to restart any running programs that will need to read the environment variables, including the console window. For example, if you are using Visual Studio as your editor, restart Visual Studio before running the example.
+
+#### [Linux](#tab/linux)
+
+```bash
+export LANGUAGE_KEY=your-key
+```
+
+```bash
+export LANGUAGE_ENDPOINT=your-endpoint
+```
+
+After you add the environment variables, run `source ~/.bashrc` from your console window to make the changes effective.
+
+#### [macOS](#tab/macos)
+
+##### Bash
+
+Edit your `.bash_profile`, and add the environment variables:
+
+```bash
+export LANGUAGE_KEY=your-key
+```
+
+```bash
+export LANGUAGE_ENDPOINT=your-endpoint
+```
+
+After you add the environment variables, run `source ~/.bash_profile` from your console window to make the changes effective.
+
+##### Xcode
+
+For iOS and macOS development, you set the environment variables in Xcode. For example, follow these steps to set the environment variable in Xcode 13.4.1.
+
+1. Select **Product** > **Scheme** > **Edit scheme**
+1. Select **Arguments** on the **Run** (Debug Run) page
+1. Under **Environment Variables** select the plus (+) sign to add a new environment variable. 
+1. Enter `LANGUAGE_KEY` for the **Name** and enter your Language resource key for the **Value**.
+1. Perform these steps for your resource endpoint. Name the new environment variable `LANGUAGE_ENDPOINT`.
+
+For more configuration options, see the [Xcode documentation](https://help.apple.com/xcode/#/dev745c5c974).
+
+---

articles/cognitive-services/language-service/media/azure-portal-resource-credentials.png

@@ -4,7 +4,7 @@ manager: nitinme
 ms.service: cognitive-services
 ms.subservice: language-service
 ms.topic: include
-ms.date: 09/15/2022
+ms.date: 10/21/2022
 ms.author: aahi
 ms.custom: ignite-fall-2021
 ---
@@ -13,24 +13,20 @@ ms.custom: ignite-fall-2021
 
 Use this quickstart to create a sentiment analysis application with the client library for .NET. In the following example, you will create a C# application that can identify the sentiment(s) expressed in a text sample, and perform aspect-based sentiment analysis.
 
-
-[!INCLUDE [Use Language Studio](../../../includes/use-language-studio.md)]
-
-
 ## Prerequisites
 
 * Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-services)
 * The [Visual Studio IDE](https://visualstudio.microsoft.com/vs/)
-* Once you have your Azure subscription, <a href="https://portal.azure.com/#create/Microsoft.CognitiveServicesTextAnalytics"  title="Create a Language resource"  target="_blank">create a Language resource </a> in the Azure portal to get your key and endpoint.  After it deploys, click **Go to resource**.
-    * You will need the key and endpoint from the resource you create to connect your application to the API. You'll paste your key and endpoint into the code below later in the quickstart.
-    * You can use the free pricing tier (`Free F0`) to try the service, and upgrade later to a paid tier for production.
-* To use the Analyze feature, you will need a Language resource with the standard (S) pricing tier.
 
 > [!div class="nextstepaction"]
 > <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=CSHARP&Pillar=Language&Product=Sentiment-analysis&Page=quickstart&Section=Prerequisites" target="_target">I ran into an issue</a>
 
 ## Setting up
 
+[!INCLUDE [Create an Azure resource](../../../includes/create-resource.md)]
+
+[!INCLUDE [Create environment variables](../../../includes/environment-variables.md)]
+
 ### Create a new .NET Core application
 
 Using the Visual Studio IDE, create a new .NET Core console app. This will create a "Hello World" project with a single C# source file: *program.cs*.
@@ -42,9 +38,7 @@ Install the client library by right-clicking on the solution in the **Solution E
 
 ## Code example
 
-Copy the following code into your *program.cs* file. Remember to replace the `key` variable with the key for your resource, and replace the `endpoint` variable with the endpoint for your resource. 
-
-[!INCLUDE [find the key and endpoint for a resource](../../../includes/find-azure-resource-info.md)]
+Copy the following code into your *program.cs* file.
 
 ```csharp
 using Azure;
@@ -56,8 +50,12 @@ namespace Example
 {
     class Program
     {
-        private static readonly AzureKeyCredential credentials = new AzureKeyCredential("replace-with-your-key-here");
-        private static readonly Uri endpoint = new Uri("replace-with-your-endpoint-here");
+        // This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
+        static string languageKey = Environment.GetEnvironmentVariable("LANGUAGE_KEY");
+        static string languageEndpoint = Environment.GetEnvironmentVariable("LANGUAGE_ENDPOINT");
+
+        private static readonly AzureKeyCredential credentials = new AzureKeyCredential(languageKey);
+        private static readonly Uri endpoint = new Uri(languageEndpoint);
 
         // Example method for detecting opinions text. 
         static void SentimentAnalysisWithOpinionMiningExample(TextAnalyticsClient client)
@@ -163,6 +161,8 @@ Document sentiment: Mixed
 
 [!INCLUDE [clean up resources](../../../includes/clean-up-resources.md)]
 
+[!INCLUDE [clean up environment variables](../../../includes/clean-up-variables.md)]
+
 > [!div class="nextstepaction"]
 > <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=REST API&Pillar=Language&Product=Entity-linking&Page=quickstart&Section=Clean-up-resources" target="_target">I ran into an issue</a>
 

articles/cognitive-services/language-service/media/portal-resource-additional-features.png

@@ -4,7 +4,7 @@ manager: nitinme
 ms.service: cognitive-services
 ms.subservice: language-service
 ms.topic: include
-ms.date: 09/15/2022
+ms.date: 10/21/2022
 ms.custom: devx-track-java, ignite-fall-2021
 ms.author: aahi
 ---
@@ -13,23 +13,21 @@ ms.author: aahi
 
 Use this quickstart to create a sentiment analysis application with the client library for Java. In the following example, you will create a Java application that can identify the sentiment(s) expressed in a text sample, and perform aspect-based sentiment analysis.
 
-[!INCLUDE [Use Language Studio](../../../includes/use-language-studio.md)]
-
 ## Prerequisites
 
 * Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-services)
 * [Java Development Kit](https://www.oracle.com/technetwork/java/javase/downloads/index.html) (JDK) with version 8 or above
-* Once you have your Azure subscription, <a href="https://portal.azure.com/#create/Microsoft.CognitiveServicesTextAnalytics"  title="Create a Language resource"  target="_blank">create a Language resource </a> in the Azure portal to get your key and endpoint.  After it deploys, click **Go to resource**.
-    * You will need the key and endpoint from the resource you create to connect your application to the API. You'll paste your key and endpoint into the code below later in the quickstart.
-    * You can use the free pricing tier (`Free F0`) to try the service, and upgrade later to a paid tier for production.
-* To use the Analyze feature, you will need a Language resource with the standard (S) pricing tier.
 
 > [!div class="nextstepaction"]
 > <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=JAVA&Pillar=Language&Product=Sentiment-analysis&Page=quickstart&Section=Prerequisites" target="_target">I ran into an issue</a>
 
 
 ## Setting up
 
+[!INCLUDE [Create an Azure resource](../../../includes/create-resource.md)]
+
+[!INCLUDE [Create environment variables](../../../includes/environment-variables.md)]
+
 ### Add the client library
 
 Create a Maven project in your preferred IDE or development environment. Then add the following dependency to your project's *pom.xml* file. You can find the implementation syntax [for other build tools](https://mvnrepository.com/artifact/com.azure/azure-ai-textanalytics/5.2.0) online.
@@ -50,9 +48,7 @@ Create a Maven project in your preferred IDE or development environment. Then ad
 
 ## Code example
 
-Create a Java file named `Example.java`. Open the file and copy the below code. Remember to replace the `key` variable with the key for your resource, and replace the `endpoint` variable with the endpoint for your resource. 
-
-[!INCLUDE [find the key and endpoint for a resource](../../../includes/find-azure-resource-info.md)]
+Create a Java file named `Example.java`. Open the file and copy the below code.
 
 ```java
 import com.azure.core.credential.AzureKeyCredential;
@@ -61,12 +57,13 @@ import com.azure.ai.textanalytics.TextAnalyticsClientBuilder;
 import com.azure.ai.textanalytics.TextAnalyticsClient;
 
 public class Example {
-
-    private static String KEY = "replace-with-your-key-here";
-    private static String ENDPOINT = "replace-with-your-endpoint-here";
+    
+    // This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
+    private static String languageKey = System.getenv("LANGUAGE_KEY");
+    private static String languageEndpoint = System.getenv("LANGUAGE_ENDPOINT");
 
     public static void main(String[] args) {
-        TextAnalyticsClient client = authenticateClient(KEY, ENDPOINT);
+        TextAnalyticsClient client = authenticateClient(languageKey, languageEndpoint);
         sentimentAnalysisWithOpinionMiningExample(client);
     }
     // Method to authenticate the client object with your key and endpoint.
@@ -130,6 +127,8 @@ Recognized document sentiment: mixed, positive score: 0.470000, neutral score: 0
 
 [!INCLUDE [clean up resources](../../../includes/clean-up-resources.md)]
 
+[!INCLUDE [clean up environment variables](../../../includes/clean-up-variables.md)]
+
 > [!div class="nextstepaction"]
 > <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=REST API&Pillar=Language&Product=Entity-linking&Page=quickstart&Section=Clean-up-resources" target="_target">I ran into an issue</a>
 

articles/cognitive-services/language-service/media/portal-resource-creation-details.png

@@ -4,7 +4,7 @@ manager: nitinme
 ms.service: cognitive-services
 ms.subservice: language-service
 ms.topic: include
-ms.date: 08/15/2022
+ms.date: 10/21/2022
 ms.author: aahi
 ms.custom: devx-track-js, ignite-fall-2021
 ---
@@ -13,22 +13,20 @@ ms.custom: devx-track-js, ignite-fall-2021
 
 Use this quickstart to create a sentiment analysis application with the client library for Node.js. In the following example, you will create a JavaScript application that can identify the sentiment(s) expressed in a text sample, and perform aspect-based sentiment analysis.
 
-[!INCLUDE [Use Language Studio](../../../includes/use-language-studio.md)]
-
 ## Prerequisites
 
 * Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-services)
 * [Node.js](https://nodejs.org/) v14 LTS or later
-* Once you have your Azure subscription, <a href="https://portal.azure.com/#create/Microsoft.CognitiveServicesTextAnalytics"  title="Create a Language resource"  target="_blank">create a Language resource </a> in the Azure portal to get your key and endpoint. After it deploys, click **Go to resource**.
-    * You will need the key and endpoint from the resource you create to connect your application to the API. You'll paste your key and endpoint into the code below later in the quickstart.
-    * You can use the free pricing tier (`Free F0`) to try the service, and upgrade later to a paid tier for production.
-* To use the Analyze feature, you will need a Language resource with the standard (S) pricing tier.
 
 > [!div class="nextstepaction"]
 > <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=JAVASCRIPT&Pillar=Language&Product=Sentiment-analysis&Page=quickstart&Section=Prerequisites" target="_target">I ran into an issue</a>
 
 ## Setting up
 
+[!INCLUDE [Create an Azure resource](../../../includes/create-resource.md)]
+
+[!INCLUDE [Create environment variables](../../../includes/environment-variables.md)]
+
 ### Create a new Node.js application
 
 In a console window (such as cmd, PowerShell, or Bash), create a new directory for your app, and navigate to it. 
@@ -60,16 +58,17 @@ npm install @azure/[email protected]
 
 Open the file and copy the below code. Remember to replace the `key` variable with the key for your resource, and replace the `endpoint` variable with the endpoint for your resource. 
 
-[!INCLUDE [find the key and endpoint for a resource](../../../includes/find-azure-resource-info.md)]
-
 ```javascript
 "use strict";
 
 const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");
-const key = '<paste-your-key-here>';
-const endpoint = '<paste-your-endpoint-here>';
+
+// This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
+const languageKey = process.env.LANGUAGE_KEY;
+const languageEndpoint = process.env.LANGUAGE_ENDPOINT;
+
 // Authenticate the client with your key and endpoint.
-const textAnalyticsClient = new TextAnalyticsClient(endpoint,  new AzureKeyCredential(key));
+const textAnalyticsClient = new TextAnalyticsClient(LanguageEndpoint,  new AzureKeyCredential(languageKey));
 
 // Example method for detecting sentiment and opinions in text.
 async function sentimentAnalysisWithOpinionMining(client){
@@ -153,6 +152,8 @@ sentimentAnalysisWithOpinionMining(textAnalyticsClient);
 
 [!INCLUDE [clean up resources](../../../includes/clean-up-resources.md)]
 
+[!INCLUDE [clean up environment variables](../../../includes/clean-up-variables.md)]
+
 > [!div class="nextstepaction"]
 > <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=REST API&Pillar=Language&Product=Entity-linking&Page=quickstart&Section=Clean-up-resources" target="_target">I ran into an issue</a>