Merge pull request #107388 from swmachan/master

Updates related to JEDI

Author: GitHubber17

articles/azure-government/documentation-government-cognitiveservices.md

@@ -623,9 +623,10 @@ For more information, please see [public documentation](../cognitive-services/Fa
     
 ### Variations
 * The URI for accessing the Text Translation API in Azure Government is: 
-  - `https://dev.microsofttranslator.us/translate?api-version=3.0`
-    ### Text Translation Method
-    This sample will use the [Text Translation - Translate method](../cognitive-services/translator/reference/v3-0-translate.md) to translate a string of text from a language into another specified language. There are multiple [language codes](https://api.cognitive.microsofttranslator.com/languages?api-version=3.0&scope=translation,dictionary,transliteration) that can be used with the Text Translation API. 
+  - `https://api.cognitive.microsofttranslator.us`
+* There are 2 regions `USGovVirginia` and `USGovArizona`
+### Text Translation Method
+The below example uses [Text Translation - Translate method](../cognitive-services/translator/reference/v3-0-translate.md) to translate a string of text from a language into another specified language. There are multiple [language codes](https://api.cognitive.microsofttranslator.com/languages?api-version=3.0&scope=translation) that can be used with the Text Translation API. 
 
 ### Text Translation C# example request
 
@@ -634,8 +635,9 @@ The sample is written in C#.
 1. Create a new Console solution in Visual Studio.
 2. Replace Program.cs with the corresponding code below.
 3. Replace the `subscriptionKey` value with the key value that you retrieved above.
-4. Replace the `text` value with text that you want to translate.
-5. Run the program.
+4. Replace the `region` value with the region value where you created your translator resource.
+5. Replace the `text` value with text that you want to translate.
+6. Run the program.
 
 You can also test out different languages and texts by replacing the "text", "from", and "to" variables in Program.cs. 
 
@@ -657,7 +659,7 @@ namespace TextTranslator
 {
     class Program
     {
-        static string host = "https://dev.microsofttranslator.us";
+        static string host = "https://api.cognitive.microsofttranslator.us";
         static string path = "/translate?api-version=3.0";
         // Translate to German.
         static string params_ = "&to=de";
@@ -666,7 +668,10 @@ namespace TextTranslator
 
         // NOTE: Replace this example key with a valid subscription key.
         static string key = "PASTE KEY HERE";
-
+        
+        // NOTE: Replace this example region with a valid region.
+        static string region = "PASTE REGION HERE";
+         
         static string text = "Hello world!";
 
         async static void Translate()
@@ -681,6 +686,7 @@ namespace TextTranslator
                 request.RequestUri = new Uri(uri);
                 request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
                 request.Headers.Add("Ocp-Apim-Subscription-Key", key);
+                request.Headers.Add("Ocp-Apim-Subscription-Region", region);
 
                 var response = await client.SendAsync(request);
                 var responseBody = await response.Content.ReadAsStringAsync();

articles/azure-government/documentation-government-services-aiandcognitiveservices.md

@@ -113,7 +113,9 @@ See details of supported locales by features in [Language and region support for
 Variations in Azure Government:
 
 - Endpoint:  https://api.cognitive.microsofttranslator.us
-- Auth Token Service: https://virginia.api.cognitive.microsoft.us/sts/v1.0/issueToken
+- Auth Token Service: 
+     - https://usgovvirginia.api.cognitive.microsoft.us/sts/v1.0/issueToken
+     - https://usgovarizona.api.cognitive.microsoft.us/sts/v1.0/issueToken
 - Available SKUs: S1
 - Custom Translator and Translator Hub are not supported.
 

articles/cognitive-services/Translator/reference/v3-0-reference.md

@@ -8,7 +8,7 @@ manager: nitinme
 ms.service: cognitive-services
 ms.subservice: translator-text
 ms.topic: reference
-ms.date: 11/14/2019
+ms.date: 3/13/2020
 ms.author: swmachan
 ---
 
@@ -53,17 +53,74 @@ There are three headers that you can use to authenticate your subscription. This
 |:----|:----|
 |Ocp-Apim-Subscription-Key|*Use with Cognitive Services subscription if you are passing your secret key*.<br/>The value is the Azure secret key for your subscription to Translator Text API.|
 |Authorization|*Use with Cognitive Services subscription if you are passing an authentication token.*<br/>The value is the Bearer token: `Bearer <token>`.|
-|Ocp-Apim-Subscription-Region|*Use with Cognitive Services multi-service subscription if you are passing a multi-service secret key.*<br/>The value is the region of the multi-service subscription. This value is optional when not using a multi-service subscription.|
+|Ocp-Apim-Subscription-Region|*Use with Cognitive Services multi-service and regional translator resource.*<br/>The value is the region of the multi-service or regional translator resource. This value is optional when using a global translator resource.|
 
 ###  Secret key
 The first option is to authenticate using the `Ocp-Apim-Subscription-Key` header. Add the `Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY>` header to your request.
 
-### Authorization token
+#### Authenticating with a global resource
+
+When you use a [global translator resource](https://ms.portal.azure.com/#create/Microsoft.CognitiveServicesTextTranslation), you need to include one header to call the translator API.
+
+|Headers|Description|
+|:-----|:----|
+|Ocp-Apim-Subscription-Key| The value is the Azure secret key for your subscription to Translator Text API.|
+
+Here's an example request to call the Translator API using the global translator resource
+
+```curl
+// Pass secret key using headers
+curl -X POST "https://api.cognitive.microsoft.com/translate?api-version=3.0&to=es" \
+     -H "Ocp-Apim-Subscription-Key:<your-key>" \
+     -H "Content-Type: application/json" \
+     -d "[{'Text':'Hello, what is your name?'}]"
+```
+
+#### Authenticating with a regional resource
+
+When you use a [regional translator resource](https://ms.portal.azure.com/#create/Microsoft.CognitiveServicesTextTranslation).
+There are 2 headers that you need to call the translator API.
+
+|Headers|Description|
+|:-----|:----|
+|Ocp-Apim-Subscription-Key| The value is the Azure secret key for your subscription to Translator Text API.|
+|Ocp-Apim-Subscription-Region| The value is the region of the translator resource. |
+
+Here's an example request to call the Translator API using the regional translator resource
+
+```curl
+// Pass secret key and region using headers
+curl -X POST "https://api.cognitive.microsoft.com/translate?api-version=3.0&to=es" \
+     -H "Ocp-Apim-Subscription-Key:<your-key>" \
+     -H "Ocp-Apim-Subscription-Region:<your-region>" \
+     -H "Content-Type: application/json" \
+     -d "[{'Text':'Hello, what is your name?'}]"
+```
+
+#### Authenticating with a Multi-service resource
+
+When you use a Cognitive Service’s multi-service resource. This allows you to use a single secret key to authenticate requests for multiple services. 
+
+When you use a multi-service secret key, you must include two authentication headers with your request. There are 2 headers that you need to call the translator API.
+
+|Headers|Description|
+|:-----|:----|
+|Ocp-Apim-Subscription-Key| The value is the Azure secret key for your multi-service resource.|
+|Ocp-Apim-Subscription-Region| The value is the region of the multi-service resource. |
+
+Region is required for the multi-service Text API subscription. The region you select is the only region that you can use for text translation when using the multi-service subscription key, and must be the same region you selected when you signed up for your multi-service subscription through the Azure portal.
+
+Available regions are `australiaeast`, `brazilsouth`, `canadacentral`, `centralindia`, `centralus`, `centraluseuap`, `eastasia`, `eastus`, `eastus2`, `francecentral`, `japaneast`, `japanwest`, `koreacentral`, `northcentralus`, `northeurope`, `southcentralus`, `southeastasia`, `uksouth`, `westcentralus`, `westeurope`, `westus`, `westus2`, and `southafricanorth`.
+
+If you pass the secret key in the query string with the parameter `Subscription-Key`, then you must specify the region with query parameter `Subscription-Region`.
+
+### Authenticating with an access token
 Alternatively, you can exchange your secret key for an access token. This token is included with each request as the `Authorization` header. To obtain an authorization token, make a `POST` request to the following URL:
 
-| Environment     | Authentication service URL                                |
+| Resource type     | Authentication service URL                                |
 |-----------------|-----------------------------------------------------------|
-| Azure           | `https://api.cognitive.microsoft.com/sts/v1.0/issueToken` |
+| Global          | `https://api.cognitive.microsoft.com/sts/v1.0/issueToken` |
+| Regional or Multi-Service | `https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken` |
 
 Here are example requests to obtain a token given a secret key:
 
@@ -83,22 +140,29 @@ Authorization: Bearer <Base64-access_token>
 
 An authentication token is valid for 10 minutes. The token should be reused when making multiple calls to the Translator APIs. However, if your program makes requests to the Translator API over an extended period of time, then your program must request a new access token at regular intervals (for example, every 8 minutes).
 
-### Multi-service subscription
-
-The last authentication option is to use a Cognitive Service’s multi-service subscription. This allows you to use a single secret key to authenticate requests for multiple services. 
+## Virtual Network support
 
-When you use a multi-service secret key, you must include two authentication headers with your request. The first passes the secret key, the second specifies the region associated with your subscription. 
-* `Ocp-Apim-Subscription-Key`
-* `Ocp-Apim-Subscription-Region`
+Translator service is now available with Virtual Network capabilities in limited regions (`WestUS2`, `EastUS`, `SouthCentralUS`, `WestUS`, `Central US EUAP`, `global`). To enable Virtual Network, please see [Configuring Azure Cognitive Services Virtual Networks](https://docs.microsoft.com/azure/cognitive-services/cognitive-services-virtual-networks?tabs=portal). 
 
-Region is required for the multi-service Text API subscription. The region you select is the only region that you can use for text translation when using the multi-service subscription key, and must be the same region you selected when you signed up for your multi-service subscription through the Azure portal.
+Once you turn on this capability, you must use the custom endpoint to call the Translator API. You cannot use the global translator endpoint ("api.cognitive.microsofttranslator.com") and you cannot authenticate with an access token.
 
-Available regions are `australiaeast`, `brazilsouth`, `canadacentral`, `centralindia`, `centralus`, `centraluseuap`, `eastasia`, `eastus`, `eastus2`, `francecentral`, `japaneast`, `japanwest`, `koreacentral`, `northcentralus`, `northeurope`, `southcentralus`, `southeastasia`, `uksouth`, `westcentralus`, `westeurope`, `westus`, `westus2`, and `southafricanorth`.
+You can find the custom endpoint once you create the [translator resource](https://ms.portal.azure.com/#create/Microsoft.CognitiveServicesTextTranslation).
 
-If you pass the secret key in the query string with the parameter `Subscription-Key`, then you must specify the region with query parameter `Subscription-Region`.
+|Headers|Description|
+|:-----|:----|
+|Ocp-Apim-Subscription-Key| The value is the Azure secret key for your subscription to Translator Text API.|
+|Ocp-Apim-Subscription-Region| The value is the region of the translator resource. This value is optional if the resource is `global`|
 
-If you use a bearer token, you must obtain the token from the region endpoint: `https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken`.
+Here's an example request to call the Translator API using the custom endpoint
 
+```curl
+// Pass secret key and region using headers
+curl -X POST "https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es" \
+     -H "Ocp-Apim-Subscription-Key:<your-key>" \
+     -H "Ocp-Apim-Subscription-Region:<your-region>" \
+     -H "Content-Type: application/json" \
+     -d "[{'Text':'Hello, what is your name?'}]"
+```
 
 ## Errors