Merge pull request #2822 from MicrosoftDocs/main

2/7/2025 PM Publish

Author: Taojunshen

articles/ai-foundry/model-inference/how-to/quickstart-github-models.md

@@ -47,7 +47,7 @@ To obtain the key and endpoint:
 
 5. If your existing account is a free account, you first have to upgrade to a Pay as you go plan. Once you upgrade, go back to the playground and select **Get API key** again, then sign in with your upgraded account.
 
-6. Once you've signed in to your Azure account, you're taken to [Azure AI Studio > GitHub](https://ai-azure.com/GitHub). It might take one or two minutes to load your initial model details in AI Studio.
+6. Once you've signed in to your Azure account, you're taken to [Azure AI Studio > GitHub](https://ai.azure.com/GitHub). It might take one or two minutes to load your initial model details in AI Studio.
 
 7. The page is loaded with your model's details. Select the **Deploy** button to deploy the model to your account.
 

articles/ai-services/agents/how-to/tools/bing-grounding.md

@@ -44,6 +44,8 @@ Developers and end users don't have access to raw content returned from Groundin
 1. Create a Grounding with Bing Search resource. You need to have `owner` or `contributor` role in your subscription or resource group to create it.
 
    1. You can create one in the [Azure portal](https://portal.azure.com/#create/Microsoft.BingGroundingSearch), and select the different fields in the creation form. Make sure you create this Grounding with Bing Search resource in the same resource group as your Azure AI Agent, AI Project, and other resources.
+
+    :::image type="content" source="../../media/tools/bing/resource-selection.png" alt-text="A screenshot of the Bing resource selection in the Azure portal." lightbox="../../media/tools/bing/resource-selection.png":::
 
    1. You can also create one through code-first experience. If so, you need to manually [register](/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) Bing Search as an Azure resource provider. You must have permission to perform the `/register/action` operation for the resource provider. The permission is included in the **Contributor** and **Owner** roles.
 

articles/ai-services/agents/media/tools/bing/resource-selection.png

@@ -2,22 +2,22 @@
 title: Authentication in Azure AI services
 titleSuffix: Azure AI services
 description: "There are three ways to authenticate a request to an Azure AI services resource: a resource key, a bearer token, or a multi-service subscription. In this article, you'll learn about each method, and how to make a request."
-author: mgreenegit
+author: eric-urban
 manager: nitinme
 ms.service: azure-ai-services
 ms.custom: devx-track-azurepowershell
 ms.topic: how-to
-ms.date: 8/1/2024
-ms.author: migreene
+ms.date: 2/7/2025
+ms.author: eur
 ---
 
 # Authenticate requests to Azure AI services
 
 Each request to an Azure AI service must include an authentication header. This header passes along a resource key or authentication token, which is used to validate your subscription for a service or group of services. In this article, you'll learn about three ways to authenticate a request and the requirements for each.
 
-* Authenticate with a [single-service](#authenticate-with-a-single-service-resource-key) or [multi-service](#authenticate-with-a-multi-service-resource-key) resource key
-* Authenticate with a [token](#authenticate-with-an-access-token)
-* Authenticate with [Microsoft Entra ID](#authenticate-with-azure-active-directory)
+* Authenticate with a [single-service](#authenticate-with-a-single-service-resource-key) or [multi-service](#authenticate-with-a-multi-service-resource-key) resource key.
+* Authenticate with a [token](#authenticate-with-an-access-token).
+* Authenticate with [Microsoft Entra ID](#authenticate-with-azure-active-directory).
 
 ## Prerequisites
 
@@ -106,7 +106,7 @@ Some Azure AI services accept, and in some cases require, an access token. Curre
 * Speech Services: Speech to text API
 * Speech Services: Text to speech API
 
->[!WARNING]
+> [!WARNING]
 > The services that support access tokens may change over time, please check the API reference for a service before using this authentication method.
 
 Both single service and multi-service resource keys can be exchanged for authentication tokens. Authentication tokens are valid for 10 minutes. They're stored in JSON Web Token (JWT) format and can be queried programmatically using the [JWT libraries](https://jwt.io/libraries). 
@@ -176,13 +176,13 @@ The first step is to create a custom subdomain. If you want to use an existing A
    Set-AzContext -SubscriptionName <SubscriptionName>
    ```
 
-2. Next, [create an Azure AI services resource](/powershell/module/az.cognitiveservices/new-azcognitiveservicesaccount) with a custom subdomain. The subdomain name needs to be globally unique and cannot include special characters, such as: ".", "!", ",".
+1. Next, [create an Azure AI services resource](/powershell/module/az.cognitiveservices/new-azcognitiveservicesaccount) with a custom subdomain. The subdomain name needs to be globally unique and cannot include special characters, such as: ".", "!", ",".
 
    ```powershell-interactive
    $account = New-AzCognitiveServicesAccount -ResourceGroupName <RESOURCE_GROUP_NAME> -name <ACCOUNT_NAME> -Type <ACCOUNT_TYPE> -SkuName <SUBSCRIPTION_TYPE> -Location <REGION> -CustomSubdomainName <UNIQUE_SUBDOMAIN>
    ```
 
-3. If successful, the **Endpoint** should show the subdomain name unique to your resource.
+1. If successful, the **Endpoint** should show the subdomain name unique to your resource.
 
 
 ### Assign a role to a service principal
@@ -202,7 +202,7 @@ Now that you have a custom subdomain associated with your resource, you're going
 
    You're going to need the **ApplicationId** in the next step.
 
-2. Next, you need to [create a service principal](/powershell/module/az.resources/new-azadserviceprincipal) for the Microsoft Entra application.
+1. Next, you need to [create a service principal](/powershell/module/az.resources/new-azadserviceprincipal) for the Microsoft Entra application.
 
    ```powershell-interactive
    New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
@@ -211,7 +211,7 @@ Now that you have a custom subdomain associated with your resource, you're going
    > [!NOTE]
    > If you register an application in the Azure portal, this step is completed for you.
 
-3. The last step is to [assign the "Cognitive Services User" role](/powershell/module/az.Resources/New-azRoleAssignment) to the service principal (scoped to the resource). By assigning a role, you're granting service principal access to this resource. You can grant the same service principal access to multiple resources in your subscription.
+1. The last step is to [assign the "Cognitive Services User" role](/powershell/module/az.Resources/New-azRoleAssignment) to the service principal (scoped to the resource). By assigning a role, you're granting service principal access to this resource. You can grant the same service principal access to multiple resources in your subscription.
 
    > [!NOTE]
    > The ObjectId of the service principal is used, not the ObjectId for the application.
@@ -231,7 +231,7 @@ In this sample, a password is used to authenticate the service principal. The to
    $context.Tenant.Id
    ```
 
-2. Get a token:
+1. Get a token:
    ```powershell-interactive
    $tenantId = $context.Tenant.Id
    $clientId = $app.ApplicationId
@@ -253,7 +253,7 @@ In this sample, a password is used to authenticate the service principal. The to
    > [!NOTE]
    > Anytime you use passwords in a script, the most secure option is to use the PowerShell Secrets Management module and integrate with a solution such as Azure Key Vault.
   
-3. Call the Computer Vision API:
+1. Call the Computer Vision API:
    ```powershell-interactive
    $url = $account.Endpoint+"vision/v1.0/models"
    $result = Invoke-RestMethod -Uri $url  -Method Get -Headers @{"Authorization"="Bearer $accessToken"} -Verbose
@@ -284,7 +284,7 @@ You can [use Azure Key Vault](./use-key-vault.md) to securely develop Azure AI s
 
 Authentication is done via Microsoft Entra ID. Authorization may be done via Azure role-based access control (Azure RBAC) or Key Vault access policy. Azure RBAC can be used for both management of the vaults and access data stored in a vault, while key vault access policy can only be used when attempting to access data stored in a vault.
 
-## See also
+## Related content
 
 * [What are Azure AI services?](./what-are-ai-services.md)
 * [Azure AI services pricing](https://azure.microsoft.com/pricing/details/cognitive-services/)

articles/ai-services/authentication.md

@@ -6,15 +6,15 @@ author: eric-urban
 manager: nitinme
 ms.service: azure-ai-services
 ms.topic: how-to
-ms.date: 8/11/2024
+ms.date: 2/7/2025
 ms.author: eur
 ---
 
 # Use environment variables with Azure AI services
 
 This guide shows you how to set and retrieve environment variables for your Azure AI services credentials when you test applications.
 
-[!INCLUDE [Azure key vault](~/reusable-content/ce-skilling/azure/includes/ai-services/security/azure-key-vault.md)]
+[!INCLUDE [Azure key vault](~/reusable-content/ce-skilling/azure/includes/ai-services/security/microsoft-entra-id-akv.md)]
 
 ## Set an environment variable
 

articles/ai-services/cognitive-services-environment-variables.md

@@ -6,7 +6,7 @@ author: eric-urban
 manager: nitinme
 ms.service: azure-ai-services
 ms.topic: quickstart
-ms.date: 8/1/2024
+ms.date: 2/7/2025
 ms.author: eur
 ms.custom:
   - subject-armqs
@@ -35,7 +35,7 @@ The template that you use in this quickstart is from [Azure Quickstart Templates
 
 One Azure resource is defined in the Bicep file. The `kind` field in the Bicep file defines the type of resource.
 
-As needed, change the `sku` parameter value to the [pricing](https://azure.microsoft.com/pricing/details/cognitive-services/) instance you want. The `sku` depends on the resource `kind` that you use. For example, use `TextAnalytics` for the Azure AI Language service. The `TextAnalytics` kind uses `S` instead of `S0` for the `sku` value.
+As needed, change the `sku` parameter value to the [pricing](https://azure.microsoft.com/pricing/details/cognitive-services/) instance you want. The `sku` depends on the resource `kind` that you use. For example, use `AIServices` for the Azure AI Language service. 
 
 ## Deploy the template
 

articles/ai-services/create-account-resource-manager-template.md

@@ -6,7 +6,7 @@ author: laujan
 manager: nitinme
 ms.service: azure-ai-document-intelligence
 ms.topic: conceptual
-ms.date: 11/19/2024
+ms.date: 02/07/2025
 ms.author: lajanuar
 monikerRange: '>=doc-intel-3.1.0'
 ---

articles/ai-services/document-intelligence/concept/retrieval-augmented-generation.md

@@ -5,7 +5,7 @@ author: laujan
 manager: nitinme
 ms.service: azure-ai-document-intelligence
 ms.topic: include
-ms.date: 11/19/2024
+ms.date: 02/07/2025
 ms.author: lajanuar
 ms.custom: devx-track-csharp, linux-related-content
 monikerRange: 'doc-intel-4.0.0'
@@ -88,7 +88,7 @@ monikerRange: 'doc-intel-4.0.0'
 
 1. Open the *Program.cs* file.
 
-1. Delete the pre-existing code, including the line `Console.Writeline("Hello World!")`.
+1. Delete the existing code, including the line `Console.Writeline("Hello World!")`.
 
 1. Select one of the following code samples and copy/paste into your application's *Program.cs* file:
 

articles/ai-services/document-intelligence/how-to-guides/includes/v4-0/csharp-sdk.md

@@ -6,7 +6,7 @@ manager: nitinme
 ms.service: azure-ai-document-intelligence
 ms.custom: linux-related-content
 ms.topic: include
-ms.date: 11/19/2024
+ms.date: 02/07/2025
 ms.author: lajanuar
 ---
 <!-- markdownlint-disable MD033 -->
@@ -16,14 +16,14 @@ ms.author: lajanuar
 >
 > This project uses cURL command-line tool to execute REST API calls.
 
-| [Document Intelligence REST API](/rest/api/aiservices/operation-groups?view=rest-aiservices-v4.0%20(2024-11-30)&preserve-view=true) | [Supported Azure SDKS](../../../sdk-overview-v4-0.md)
+| [Document Intelligence REST API](/rest/api/aiservices/operation-groups?view=rest-aiservices-v4.0%20(2024-11-30)&preserve-view=true) | [Supported Azure `SDK`s](../../../sdk-overview-v4-0.md)
 
 ## Prerequisites
 
 - An Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-services/).
 - The cURL command line tool installed. Windows 10 and Windows 11 ship with a copy of cURL. At a command prompt, type the following cURL command. If the help options display, cURL is installed in your Windows environment.
 
-  ```console
+  ```bash
   curl -help
   ```
 
@@ -60,18 +60,18 @@ Use the following table as a reference. Replace *\<modelId>* and *\<document-url
 
 ## POST request
 
-Open a console window and run the following cURL command. The commands include the endpoint and key environment variables previously created in the set environment variables section. Replace those variables if your variable names differ. Remember to replace the *\<modelId>* and *\<document-url>* parameters.
+Open a bash window and run the following cURL command. The commands include the endpoint and key environment variables previously created in the set environment variables section. Replace those variables if your variable names differ. Remember to replace the *\<modelId>* and *\<document-url>* parameters.
 
-```console
-curl -i -X POST "%DI_ENDPOINT%/documentintelligence/documentModels/{modelId}:analyze?api-version=2024-02-29-preview" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: %DI_KEY%" --data-ascii "{'urlSource': '<document-url>'}"
+```bash
+curl -i -X POST "POST {endpoint}/documentintelligence/documentModels/{modelId}:analyze?_overload=analyzeDocument&api-version=2024-11-30" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {DI_KEY}" --data-ascii "{'urlSource': '<document-url>'}"
 ```
 
 To enable add-on capabilities, use the `features` query parameter in the POST request. There are four add-on capabilities available with the `2023-07-31` (GA) and later releases: *ocr.highResolution*, *ocr.formula*, *ocr.font*, and *queryFields.premium*. To learn more about each of the capabilities, see [Custom models](../../../concept/accuracy-confidence.md).
 
 You can only call the *highResolution*, *formula*, and *font* capabilities for the Read and Layout model, and the *queryFields* capability for the General Documents model. The following example shows how to call the *highResolution*, *formula*, and *font* capabilities for the Layout model.
 
 ```bash
-curl -i -X POST "%DI_ENDPOINT%documentintelligence/documentModels/prebuilt-layout:analyze?features=ocr.highResolution,ocr.formula,ocr.font?api-version=2024-02-29-preview" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: %DI_KEY%" --data-ascii "{'urlSource': '<document-url>'}"
+curl -i -X POST "{endpoint}/documentintelligence/documentModels/prebuilt-layout:analyze?features=ocr.highResolution,ocr.formula,ocr.font?api-version=2024-11-30" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {DI_KEY}" --data-ascii "{'urlSource': '<document-url>'}"
 ```
 
 ### POST response
@@ -82,7 +82,7 @@ You receive a `202 (Success)` response that includes an `Operation-location` hea
 
 ### Get analyze result (GET Request)
 
-After you call the [`Analyze document`](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2024-02-29-preview&preserve-view=true&tabs=HTTP) API, call the [`Get analyze` result}(/rest/api/aiservices/document-models/get-analyze-result?view=rest-aiservices-2024-02-29-preview&preserve-view=true&tabs=HTTP) API to get the status of the operation and the extracted data.
+After you call the [`Analyze document`](/rest/api/aiservices/document-models/analyze-batch-documents?view=rest-aiservices-v4.0%20(2024-11-30)&preserve-view=true&tabs=HTTP) API, call the [`Get analyze` result](/rest/api/aiservices/document-models/get-analyze-result?view=rest-aiservices-v4.0%20(2024-11-30)&preserve-view=true&tabs=HTTP) API to get the status of the operation and the extracted data.
 
 <!-- markdownlint-disable MD024 -->
 
@@ -92,16 +92,16 @@ The cURL command line tool doesn't format API responses that contain JSON conten
 
 Use the NodeJS *json tool* as a JSON formatter for cURL. If you don't have [Node.js](https://nodejs.org/) installed, download and install the latest version.
 
-1. Open a console window and install the json tool by using the following command:
+1. Open a bash window and install the json tool by using the following command:
 
-   ```console
+   ```bash
    npm install -g jsontool
    ```
 
 1. Pretty print the JSON output by including the pipe character `| json` with your GET requests.
 
-   ```console
-   curl -i -X GET "<endpoint>documentintelligence/documentModels/prebuilt-read/analyzeResults/0e49604a-2d8e-4b15-b6b8-bb456e5d3e0a?api-version=2024-02-29-preview"-H "Ocp-Apim-Subscription-Key: <subscription key>" | json
+   ```bash
+   curl -i -X GET "<endpoint>documentintelligence/documentModels/prebuilt-read/analyzeResults/0e49604a-2d8e-4b15-b6b8-bb456e5d3e0a?api-version=2024-11-30"-H "Ocp-Apim-Subscription-Key: <subscription key>" | json
    ```
 
 #### [macOS](#tab/macOS)
@@ -110,8 +110,8 @@ The *json_pp* command tool ships with macOS and can be used as a JSON formatter
 
 - Pretty print the JSON output by including `| json_pp` with your GET requests.
 
-  ```console
-  curl -i -X GET "{endpoint}documentintelligence/documentModels/prebuilt-read/analyzeResults/0e49604a-2d8e-4b15-b6b8-bb456e5d3e0a?api-version=2024-02-29-preview"-H "Ocp-Apim-Subscription-Key: <subscription key>" | json_pp
+  ```bash
+  curl -i -X GET "{endpoint}/documentintelligence/documentModels/{modelId}/analyzeResults/{resultId}?api-version=2024-11-30"-H "Ocp-Apim-Subscription-Key: <subscription key>" | json_pp
   ```
 
 #### [Linux](#tab/linux)
@@ -120,8 +120,8 @@ The *json_pp* command line tool is preinstalled in most Linux distributions. If
 
 - Pretty print the JSON output by including `| json_pp` with your `GET` requests.
 
-  ```console
-  curl -i -X GET "<endpoint>documentintelligence/documentModels/prebuilt-read/analyzeResults/0e49604a-2d8e-4b15-b6b8-bb456e5d3e0a?api-version=2024-02-29-preview"-H "Ocp-Apim-Subscription-Key: <subscription key>" | json_pp
+  ```bash
+  curl -i -X GET "{endpoint}/documentintelligence/documentModels/{modelId}/analyzeResults/{resultId}?api-version=2024-11-30"-H "Ocp-Apim-Subscription-Key: <subscription key>" | json_pp
   ```
 
 ---
@@ -134,8 +134,8 @@ Before you run the following command, make these changes:
 - Replace *\<DI_KEY* with the variable for your environment variable if it differs from the name in the code.
 - Replace *\<json-tool> with your JSON formatting tool.
 
-```console
-curl -i -X GET "<POST response>" -H "Ocp-Apim-Subscription-Key: %DI_KEY%" | `<json-tool>`
+```bash
+curl -i -X GET "<POST response>" -H "Ocp-Apim-Subscription-Key: {DI_KEY}" | `<json-tool>`
 ```
 
 ### Examine the response

articles/ai-services/document-intelligence/how-to-guides/includes/v4-0/rest-api.md

@@ -7,7 +7,7 @@ manager: nitinme
 ms.service: azure-ai-document-intelligence
 ms.custom: devx-track-dotnet, devx-track-extended-java, devx-track-js, devx-track-python, linux-related-content
 ms.topic: how-to
-ms.date: 11/19/2024
+ms.date: 02/07/2025
 ms.author: lajanuar
 zone_pivot_groups: programming-languages-set-formre
 ---