[APIM] AOAI backends updates

Author: gitName

articles/api-management/api-management-authenticate-authorize-azure-openai.md

@@ -5,7 +5,7 @@ description: Options to authenticate and authorize to Azure OpenAI APIs using Az
 author: dlepow
 ms.service: azure-api-management
 ms.topic: article
-ms.date: 02/20/2024
+ms.date: 01/23/2025
 ms.author: danlep
 ms.collection: ce-skilling-ai-copilot
 ---
@@ -78,7 +78,7 @@ In this example, the named value in API Management is *openai-api-key*.
 
 ## Authenticate with managed identity
 
-An alternative way to authenticate to an Azure OpenAI API by using a managed identity in Microsoft Entra ID. For background, see
+An alternative and recommended way to authenticate to an Azure OpenAI API is by using a managed identity in Microsoft Entra ID. For background, see
 [How to configure Azure OpenAI Service with managed identity](/azure/ai-services/openai/how-to/managed-identity).
 
 Following are steps to configure your API Management instance to use a managed identity to authenticate requests to an Azure OpenAI API. 
@@ -101,6 +101,9 @@ Following are steps to configure your API Management instance to use a managed i
     </set-header> 
     ```
 
+> [!TIP]
+> An alternative to using the `authentication-managed-identity` and `set-header` policies shown in this example is to configure a [backend](backends.md) resource that directs API requests to the Azure OpenAI Service endpoint. In the backend configuration, enable managed identity authentication to the Azure OpenAI Service. Azure API Management automates these steps when importing an API directly from Azure OpenAI Service. For more information, see [Import API from Azure OpenAI Service](azure-openai-api-from-specification.md#option-1-import-api-from-azure-openai-service). 
+
 ## OAuth 2.0 authorization using identity provider
 
 To enable more fine-grained access to OpenAPI APIs by particular users or clients, you can preauthorize access to the Azure OpenAI API using OAuth 2.0 authorization with Microsoft Entra ID or another identity provider. For background, see [Protect an API in Azure API Management using OAuth 2.0 authorization with Microsoft Entra ID](api-management-howto-protect-backend-with-aad.md).

articles/api-management/azure-openai-api-from-specification.md

@@ -5,7 +5,7 @@ ms.service: azure-api-management
 author: dlepow
 ms.author: danlep
 ms.topic: how-to
-ms.date: 05/10/2024
+ms.date: 01/23/2025
 ms.collection: ce-skilling-ai-copilot
 ms.custom: template-how-to, build-2024
 ---
@@ -16,8 +16,8 @@ ms.custom: template-how-to, build-2024
 
 This article shows two options to import an [Azure OpenAI Service](/azure/ai-services/openai/overview) API into an Azure API Management instance as a REST API:
 
-- [Import an Azure OpenAI API directly from Azure OpenAI Service](#option-1-import-api-from-azure-openai-service)
-- [Download and add the OpenAPI specification](#option-2-add-an-openapi-specification-to-api-management) for Azure OpenAI and add it to API Management as an OpenAPI API.
+- [Import an Azure OpenAI API directly from Azure OpenAI Service](#option-1-import-api-from-azure-openai-service) (recommended)
+- [Download the OpenAPI specification](#option-2-add-an-openapi-specification-to-api-management) and add it to API Management as an OpenAPI API.
 
 ## Prerequisites
 
@@ -37,9 +37,9 @@ When you import the API, API Management automatically configures:
 
 * Operations for each of the Azure OpenAI [REST API endpoints](/azure/ai-services/openai/reference).
 * A system-assigned identity with the necessary permissions to access the Azure OpenAI resource.
-* A [backend](backends.md) resource and [set-backend-service](set-backend-service-policy.md) policy that direct API requests to the Azure OpenAI Service endpoint.
-* An [authentication-managed-identity](authentication-managed-identity-policy.md) policy that can authenticate to the Azure OpenAI resource using the instance's system-assigned identity.
-* (optionally) Policies to help you monitor and manage token consumption by the Azure OpenAI API.
+* A [backend](backends.md) resource and a [set-backend-service](set-backend-service-policy.md) policy that direct API requests to the Azure OpenAI Service endpoint.
+* Authentication to the Azure OpenAI backend using the instance's system-assigned managed identity.
+* (optionally) Policies to help you monitor and manage the Azure OpenAI API.
 
 To import an Azure OpenAI API to API Management:
 
@@ -57,8 +57,14 @@ To import an Azure OpenAI API to API Management:
 
         For example, if your API Management gateway endpoint is `https://contoso.azure-api.net`, set a **Base URL** similar to `https://contoso.azure-api.net/my-openai-api/openai`.
     1. Optionally select one or more products to associate with the API. Select **Next**.
-1. On the **Policies** tab, optionally enable policies to monitor and manage Azure OpenAI API token consumption. 
-    If selected, enter settings or accept defaults that define the `azure-openai-token-limit` and `azure-openai-emit-token-metric` policies for your API. You can also set or update the policy configuration later. Select **Review + Create**.
+1. On the **Policies** tab, optionally enable policies to monitor and manage Azure OpenAI API token consumption and response caching. You can also set or edit policies later.
+
+    If selected, enter settings or accept defaults that define the following policies (see linked articles for configuration details):
+    * [Manage token consumption](azure-openai-token-limit-policy.md)
+    * [Track token usage](azure-openai-emit-token-metric-policy.md)
+    * [Enable semantic caching](azure-openai-enable-semantic-caching.md)  
+    
+    Select **Review + Create**.
 1. After settings are validated, select **Create**. 
 
 ## Option 2. Add an OpenAPI specification to API Management
@@ -67,7 +73,7 @@ Alternatively, manually download the OpenAPI specification for the Azure OpenAI
 
 ### Download the OpenAPI specification
 
-Download the OpenAPI specification for the Azure OpenAI REST API, such as the [2024-02-01 GA version](https://github.com/Azure/azure-rest-api-specs/blob/main/specification/cognitiveservices/data-plane/AzureOpenAI/inference/stable/2024-02-01/inference.json).
+Download the OpenAPI specification for the Azure OpenAI REST API, such as the [2024-10-01 GA version](https://github.com/Azure/azure-rest-api-specs/blob/main/specification/cognitiveservices/data-plane/AzureOpenAI/inference/stable/2024-10-01/inference.json).
 
 1. In a text editor, open the specification file that you downloaded.
 1. In the `servers` element in the specification, substitute the name of your Azure OpenAI Service endpoint in the placeholder values of `url` and `default` endpoint in the specification. For example, if your Azure OpenAI Service endpoint is `contoso.openai.azure.com`, update the `servers` element with the following values:
@@ -89,7 +95,7 @@ Download the OpenAPI specification for the Azure OpenAI REST API, such as the [2
       ],
     [...]
     ```
-1. Make a note of the value of the API `version` in the specification. You'll need it to test the API. Example: `2024-02-01`.
+1. Make a note of the value of the API `version` in the specification. You'll need it to test the API. Example: `2024-10-01`.
 
 ### Add OpenAPI specification to API Management
 

articles/api-management/backends.md

@@ -5,7 +5,7 @@ services: api-management
 author: dlepow
 ms.service: azure-api-management
 ms.topic: concept-article
-ms.date: 05/13/2024
+ms.date: 01/24/2025
 ms.author: danlep
 ms.custom:
   - build-2024
@@ -20,7 +20,7 @@ A *backend* (or *API backend*) in API Management is an HTTP service that impleme
 When importing certain APIs, API Management configures the API backend automatically. For example, API Management configures the backend web service when importing:
 * An [OpenAPI specification](import-api-from-oas.md).
 * A [SOAP API](import-soap-api.md).
-* Azure resources, such as an HTTP-triggered [Azure Function App](import-function-app-as-api.md) or [Logic App](import-logic-app-as-api.md).
+* Azure resources, such as An [Azure OpenAI API](azure-openai-api-from-specification.md), an HTTP-triggered [Azure Function App](import-function-app-as-api.md),  or [Logic App](import-logic-app-as-api.md).
 
 API Management also supports using other Azure resources as an API backend, such as:
 * A [Service Fabric cluster](how-to-configure-service-fabric-backend.yml).
@@ -39,9 +39,29 @@ Use backends for one or more of the following:
 
 Configure and manage backend entities in the Azure portal, or using Azure APIs or tools.
 
+## Create a backend
+
+You can create a backend in the Azure portal, or using Azure APIs or tools.
+
+To create a backend in the portal:
+
+1. Sign into the [portal](https://portal.azure.com) and go to your API Management instance.
+1. In the left menu, select **APIs** > **Backends** > **+ Create new backend**.
+1. On the **Backend** page, do the following:
+    1. Enter a **Name** for the backend and optional **Description**.
+    1. Select a **Backend hosting type**, for example, **Azure resource** for an Azure resource such as a Function App or Logic App, **Custom URL** for a custom service, or a **Service Fabric** cluster. 
+    1. In **Runtime URL**, enter the URL of the backend service that API requests are forwarded to.
+    1. Under **Advanced**, optionally disable certificate chain or certificate name validation for the backend.
+    1. Under **Add this backend service to a backend pool**, optionally select or create a [load-balanced pool](#load-balanced-pool) for the backend.
+    1. Under **Circuit breaker rule**, optionally configure a [circuit breaker](#circuit-breaker) for the backend.
+    1. Under **Authorization credentials**, optionally configure credentials to authorize access to the backend. Options include a request header, query parameter, [client certificate](api-management-howto-mutual-certificates-for-clients.md), or system-assigned or user-assigned [managed identity](api-management-howto-use-managed-service-identity.md) configured in the API Management instance.
+    1. Select **Create**.
+    
+After creating a backend, you can update the backend settings at any time. For example, add a circuit breaker rule, change the runtime URL, or add authorization credentials.
+
 ## Reference backend using set-backend-service policy
 
-After creating a backend, you can reference the backend in your APIs. Use the [`set-backend-service`](set-backend-service-policy.md) policy to direct an incoming API request to the backend. If you already configured a backend web service for an API, you can use the `set-backend-service` policy to redirect the request to a backend entity instead. For example:
+After creating a backend, you can reference the backend identifier (name) in your APIs. Use the [`set-backend-service`](set-backend-service-policy.md) policy to direct an incoming API request to the backend. If you already configured a backend web service for an API, you can use the `set-backend-service` policy to redirect the request to a backend entity instead. For example:
 
 ```xml
 <policies>
@@ -93,9 +113,22 @@ The backend circuit breaker is an implementation of the [circuit breaker pattern
 
 ### Example
 
-Use the API Management [REST API](/rest/api/apimanagement/backend) or a Bicep or ARM template to configure a circuit breaker in a backend. In the following example, the circuit breaker in *myBackend* in the API Management instance *myAPIM* trips when there are three or more `5xx` status codes indicating server errors in 1 hour. 
+Use the Azure portal, API Management [REST API](/rest/api/apimanagement/backend), or a Bicep or ARM template to configure a circuit breaker in a backend. In the following example, the circuit breaker in *myBackend* in the API Management instance *myAPIM* trips when there are three or more `5xx` status codes indicating server errors in 1 hour. 
 
-The circuit breaker resets after 1 hour. If a `Retry-After` header is present in the response, the circuit breaker accepts the value and waits for the specified time before sending requests to the backend again.
+The circuit breaker in this example resets after 1 hour. If a `Retry-After` header is present in the response, the circuit breaker accepts the value and waits for the specified time before sending requests to the backend again.
+
+#### [Portal](#tab/portal)
+
+1. In the [Azure portal](https://portal.azure.com), go to your API Management instance.
+1. In the left menu, select **APIs** > **Backends** > your backend.
+1. In the backend page, select **Settings** > **Circuit breaker settings** > **Add new**.
+1. In the **Create new circuit breaker** page, configure the rule:
+    * **Rule name**: Enter a name for the rule, such as *myBackend*.
+    * **Failure count**: Enter *3*.
+    * **Failure interval**: Leave the default value of **1 hour**.
+    * **Failure status code range**: Select **500 - 599**.
+    * **Trip duration**: Leave the default value of **1 hour**.
+    * **Check 'Retry-After' header in HTTP response**: Select **True (Accept)**.
 
 #### [Bicep](#tab/bicep)
 
@@ -173,17 +206,16 @@ Include a JSON snippet similar to the following in your ARM template for a backe
 
 ## Load-balanced pool
 
-API Management supports backend *pools*, when you want to implement multiple backends for an API and load-balance requests across those backends. 
+API Management supports backend *pools*, when you want to implement multiple backends for an API and load-balance requests across those backends. A pool is a collection of backends that are treated as a single entity for load balancing.
 
 Use a backend pool for scenarios such as the following:
 
 * Spread the load to multiple backends, which may have individual backend circuit breakers.
 * Shift the load from one set of backends to another for upgrade (blue-green deployment).
 
-To create a backend pool, set the `type` property of the backend to `pool` and specify a list of backends that make up the pool.
 
 > [!NOTE]
-> * Currently, you can only include single backends in a backend pool. You can't add a backend of type `pool` to another backend pool. You can include up to 30 backends in a pool.
+> * You can include up to 30 backends in a pool. 
 > * Because of the distributed nature of the API Management architecture, backend load balancing is approximate. Different instances of the gateway do not synchronize and will load balance based on the information on the same instance.
 
 
@@ -200,11 +232,25 @@ API Management supports the following load balancing options for backend pools:
 
 ### Example
 
-Use the API Management [REST API](/rest/api/apimanagement/backend) or a Bicep or ARM template to configure a backend pool. In the following example, the backend *myBackendPool* in the API Management instance *myAPIM* is configured with a backend pool. Example backends in the pool are named *backend-1* and *backend-2*. Both backends are in the highest priority group; within the group, *backend-1* has a greater weight than *backend-2* .
+Use the portal, API Management [REST API](/rest/api/apimanagement/backend), or a Bicep or ARM template to configure a backend pool. In the following example, the backend *myBackendPool* in the API Management instance *myAPIM* is configured with a backend pool. Example backends in the pool are named *backend-1* and *backend-2*. Both backends are in the highest priority group; within the group, *backend-1* has a greater weight than *backend-2* .
+
+
+#### [Portal](#tab/portal)
+
+1. In the [Azure portal](https://portal.azure.com), go to your API Management instance.
+1. In the left menu, select **APIs** > **Backends** > your backend.
+1. In the **Backends** page, select the **Load balancer** tab.
+1. Select **+ Create new pool**.
+1. In the **Create new load-balanced pool** page, do the following:
+    * **Name**: Enter a name for the pool such as *myBackendPool*.
+    * **Description**: Optionally enter a description.
+    * **Add backends to pool**: Select one or more backends to add to the pool.
+    * **Backend weight and priority**: Select **Customize weight and priority** to configure the weight and priority of each backend in the pool. For example, if you added two backends named *backend-1* and *backend-2*, set the weight of *backend-1* to 3 and the weight of *backend-2* to 1, and set the priority of both backends to 1.
+    * Select **Create**.
 
 #### [Bicep](#tab/bicep)
 
-Include a snippet similar to the following in your Bicep template for a backend resource with a load-balanced pool:
+Include a snippet similar to the following in your Bicep template for a load-balanced pool. Set the `type` property of the backend entity to `Pool` and specify the backends in the pool:
 
 ```bicep
 resource symbolicname 'Microsoft.ApiManagement/service/backends@2023-09-01-preview' = {
@@ -231,7 +277,7 @@ resource symbolicname 'Microsoft.ApiManagement/service/backends@2023-09-01-previ
 ```
 #### [ARM](#tab/arm)
 
-Include a JSON snippet similar to the following in your ARM template for a backend resource with a load-balanced pool. 
+Include a JSON snippet similar to the following in your ARM template for a load-balanced pool. Set the `type` property of the backend resource to `Pool` and specify the backends in the pool: 
 
 ```json
 {