Merge pull request #235137 from laujan/85965-update-firewall-settings-page

update firewall settings

Author: American-Dipper

articles/cognitive-services/Translator/firewalls.md

@@ -8,15 +8,33 @@ manager: nitinme
 ms.service: cognitive-services
 ms.subservice: translator-text
 ms.topic: conceptual
-ms.date: 12/06/2021
+ms.date: 04/19/2023
 ms.author: lajanuar
 ---
 
-# How to translate behind IP firewalls with Translator
+# Use Translator behind firewalls
 
-Translator can translate behind firewalls using either domain-name or IP filtering. Domain-name filtering is the preferred method. If you still require IP filtering, we suggest you to get the [IP addresses details using service tag](../../virtual-network/service-tags-overview.md#service-tags-on-premises). Translator is under the **CognitiveServicesManagement** service tag.
+Translator can translate behind firewalls using either [Domain-name](../../firewall/dns-settings.md#configure-dns-proxy---azure-portal) or [IP filtering](#configure-firewall). Domain-name filtering is the preferred method.
 
-We **do not recommend** running Microsoft Translator from behind a specific IP filtered firewall. The setup is likely to break in the future without notice.
+If you still require IP filtering, you can get the [IP addresses details using service tag](../../virtual-network/service-tags-overview.md#discover-service-tags-by-using-downloadable-json-files). Translator is under the **CognitiveServicesManagement** service tag.
+
+## Configure firewall
+
+ Navigate to your Translator resource in the Azure portal.
+
+1. Select **Networking** from the **Resource Management** section.
+1. Under the **Firewalls and virtual networks** tab, choose **Selected Networks and Private Endpoints**.
+
+   :::image type="content" source="media/firewall-setting-azure-portal.png" alt-text="Screenshot of the firewall setting in the Azure portal.":::
+
+   > [!NOTE]
+   >
+   > * Once you enable **Selected Networks and Private Endpoints**, you must use the **Virtual Network** endpoint to call the Translator. You can't use the standard translator endpoint (`api.cognitive.microsofttranslator.com`) and you can't authenticate with an access token.
+   > * For more information, *see* [**Virtual Network Support**](reference/v3-0-reference.md#virtual-network-support).
+
+1. To grant access to an internet IP range, enter the IP address or address range (in [CIDR format](https://tools.ietf.org/html/rfc4632)) under **Firewall** > **Address Range**. Only valid public IP (`non-reserved`) addresses are accepted.
+
+Running Microsoft Translator from behind a specific IP filtered firewall is **not recommended**. The setup is likely to break in the future without notice.
 
 The IP addresses for Translator geographical endpoints as of September 21, 2021 are:
 
@@ -25,3 +43,9 @@ The IP addresses for Translator geographical endpoints as of September 21, 2021
 |United States|api-nam.cognitive.microsofttranslator.com|20.42.6.144, 20.49.96.128, 40.80.190.224, 40.64.128.192|
 |Europe|api-eur.cognitive.microsofttranslator.com|20.50.1.16, 20.38.87.129|
 |Asia Pacific|api-apc.cognitive.microsofttranslator.com|40.80.170.160, 20.43.132.96, 20.37.196.160, 20.43.66.16|
+
+## Next steps
+
+[**Translator virtual network support**](reference/v3-0-reference.md#virtual-network-support)
+
+[**Configure virtual networks**](../cognitive-services-virtual-networks.md#grant-access-from-an-internet-ip-range)

articles/cognitive-services/Translator/media/firewall-setting-azure-portal.png

@@ -8,7 +8,7 @@ manager: nitinme
 ms.service: cognitive-services
 ms.subservice: translator-text
 ms.topic: reference
-ms.date: 12/06/2021
+ms.date: 04/20/2023
 ms.author: lajanuar
 ---
 
@@ -28,16 +28,16 @@ Version 3 of the Translator provides a modern JSON-based Web API. It improves us
 
 Requests to Translator are, in most cases, handled by the datacenter that is closest to where the request originated. If there's a datacenter failure when using the global endpoint, the request may be routed outside of the geography.
 
-To force the request to be handled within a specific geography, use the desired geographical endpoint. All requests are processed among the datacenters within the geography. 
+To force the request to be handled within a specific geography, use the desired geographical endpoint. All requests are processed among the datacenters within the geography.
 
 |Geography|Base URL (geographical endpoint)|Datacenters|
 |:--|:--|:--|
-|Global (non-regional)|    api.cognitive.microsofttranslator.com|Closest available datacenter|
+|Global (`non-regional`)|    api.cognitive.microsofttranslator.com|Closest available datacenter|
 |Asia Pacific|    api-apc.cognitive.microsofttranslator.com|Korea South, Japan East, Southeast Asia, and Australia East|
 |Europe|    api-eur.cognitive.microsofttranslator.com|North Europe, West Europe|
 |United States|    api-nam.cognitive.microsofttranslator.com|East US, South Central US, West Central US, and West US 2|
 
-<sup>1</sup> Customers with a resource located in Switzerland North or Switzerland West can ensure that their Text API requests are served within Switzerland. To ensure that requests are handled in Switzerland, create the Translator resource in the 'Resource region' 'Switzerland North' or 'Switzerland West', then use the resource's custom endpoint in your API requests. For example: If you create a Translator resource in Azure portal with 'Resource region' as 'Switzerland North' and your resource name is 'my-swiss-n', then your custom endpoint is "https://my-swiss-n.cognitiveservices.azure.com". And a sample request to translate is:
+<sup>`1`</sup> Customers with a resource located in Switzerland North or Switzerland West can ensure that their Text API requests are served within Switzerland. To ensure that requests are handled in Switzerland, create the Translator resource in the 'Resource region' 'Switzerland North' or 'Switzerland West', then use the resource's custom endpoint in your API requests. For example: If you create a Translator resource in Azure portal with 'Resource region' as 'Switzerland North' and your resource name is 'my-swiss-n', then your custom endpoint is "https://my-swiss-n.cognitiveservices.azure.com". And a sample request to translate is:
 ```curl
 // Pass secret key and region using headers to a custom endpoint
 curl -X POST "https://my-swiss-n.cognitiveservices.azure.com/translator/text/v3.0/translate?to=fr" \
@@ -46,7 +46,7 @@ curl -X POST "https://my-swiss-n.cognitiveservices.azure.com/translator/text/v3.
 -H "Content-Type: application/json" \
 -d "[{'Text':'Hello'}]" -v
 ```
-<sup>2</sup> Custom Translator isn't currently available in Switzerland.
+<sup>`2`</sup> Custom Translator isn't currently available in Switzerland.
 
 ## Authentication
 
@@ -60,7 +60,8 @@ There are three headers that you can use to authenticate your subscription. This
 |Authorization|*Use with Cognitive Services subscription if you're passing an authentication token.*<br/>The value is the Bearer token: `Bearer <token>`.|
 |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
+### 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.
 
 #### Authenticating with a global resource
@@ -170,7 +171,7 @@ An authentication token is valid for 10 minutes. The token should be reused when
 |:-----|:----|
 |Authorization| The value is an access **bearer token** generated by Azure AD.</br><ul><li> The bearer token provides proof of authentication and validates the client's authorization to use the resource.</li><li> An authentication token is valid for 10 minutes and should be reused when making multiple calls to Translator.</br></li>*See* [Sample request: 2. Get a token](../../authentication.md?tabs=powershell#sample-request)</ul>|
 |Ocp-Apim-Subscription-Region| The value is the region of the **translator resource**.</br><ul><li> This value is optional if the resource is global.</li></ul>|
-|Ocp-Apim-ResourceId| The value is the Resource ID for your Translator resource instance.</br><ul><li>You'll find the Resource ID in the Azure portal at **Translator Resource  → Properties**. </li><li>Resource ID format: </br>/subscriptions/<**subscriptionId**>/resourceGroups/<**resourceGroupName**>/providers/Microsoft.CognitiveServices/accounts/<**resourceName**>/</li></ul>|
+|Ocp-Apim-ResourceId| The value is the Resource ID for your Translator resource instance.</br><ul><li>You find the Resource ID in the Azure portal at **Translator Resource  → Properties**. </li><li>Resource ID format: </br>/subscriptions/<**subscriptionId**>/resourceGroups/<**resourceGroupName**>/providers/Microsoft.CognitiveServices/accounts/<**resourceName**>/</li></ul>|
 
 ##### **Translator property page—Azure portal**
 
@@ -238,6 +239,19 @@ Once you turn on this capability, you must use the custom endpoint to call the T
 
 You can find the custom endpoint after you create a [translator resource](https://portal.azure.com/#create/Microsoft.CognitiveServicesTextTranslation) and allow access from selected networks and private endpoints.
 
+1. Navigate to your Translator resource in the Azure portal.
+1. Select **Networking** from the **Resource Management** section.
+1. Under the **Firewalls and virtual networks** tab, choose **Selected Networks and Private Endpoints**.
+
+   :::image type="content" source="../media/virtual-network-setting-azure-portal.png" alt-text="Screenshot of the virtual network setting in the Azure portal.":::
+
+1. Select **Save** to apply your changes.
+1. Select **Keys and Endpoint** from the **Resource Management** section.
+1. Select the **Virtual Network** tab.
+1. Listed there are the endpoints for Text Translation and Document Translation.
+
+   :::image type="content" source="../media/virtual-network-endpoint.png" alt-text="Screenshot of the virtual network endpoint.":::
+
 |Headers|Description|
 |:-----|:----|
 |Ocp-Apim-Subscription-Key| The value is the Azure secret key for your subscription to Translator.|
@@ -258,8 +272,8 @@ curl -X POST "https://<your-custom-domain>.cognitiveservices.azure.com/translato
 
 A standard error response is a JSON object with name/value pair named `error`. The value is also a JSON object with properties:
 
-  * `code`: A server-defined error code.
-  * `message`: A string giving a human-readable representation of the error.
+* `code`: A server-defined error code.
+* `message`: A string giving a human-readable representation of the error.
 
 For example, a customer with a free trial subscription would receive the following error once the free quota is exhausted: