Merge pull request #297478 from MicrosoftDocs/main

4/1/2025 PM Publish

Author: Taojunshen

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: concept-article
-ms.date: 01/23/2025
+ms.date: 04/01/2025
 ms.author: danlep
 ms.collection: ce-skilling-ai-copilot
 ---
@@ -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: 01/23/2025
+ms.date: 04/01/2025
 ms.collection: ce-skilling-ai-copilot
 ms.custom: template-how-to, build-2024
 ---
@@ -29,6 +29,10 @@ Learn more about managing AI APIs in API Management:
 - An Azure OpenAI resource with a model deployed. For more information about model deployment, see the [resource deployment guide](/azure/ai-services/openai/how-to/create-resource).
 
     Make a note of the ID (name) of the deployment. You'll need it when you test the imported API in API Management.
+
+    > [!NOTE]
+    > API Management policies such as [azure-openai-token-limit](azure-openai-token-limit-policy.md) and [azure-openai-emit-token-metric](azure-openai-emit-token-metric-policy.md) are supported for certain API endpoints exposed through specific Azure OpenAI Service models. For more information, see [Supported Azure OpenAI Service models](azure-openai-token-limit-policy.md#supported-azure-openai-service-models).
+
 - Permissions to grant access to the Azure OpenAI resource from the API Management instance.
 
 ## Option 1. Import API from Azure OpenAI Service
@@ -39,11 +43,11 @@ You can import an Azure OpenAI API directly from Azure OpenAI Service to API Man
 
 When you import the API, API Management automatically configures:
 
-* Operations for each of the Azure OpenAI [REST API endpoints](/azure/ai-services/openai/reference).
+* 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:
 
@@ -55,14 +59,19 @@ To import an Azure OpenAI API to API Management:
 
 1. On the **Basics** tab:
     1. Select the Azure OpenAI resource that you want to import.
-    1. Optionally select an **Azure OpenAI API version**. If you don't select one, the latest production-ready REST API version is used by default.
+    1. Optionally select an **Azure OpenAI API version**. If you don't select one, the latest production-ready REST API version is used by default. Make a note of the version you selected. You'll need it to test the API.
     1. Enter a **Display name** and optional **Description** for the API.
     1. In **Base URL**, append a path that your API Management instance uses to access the Azure OpenAI API endpoints. If you enable **Ensure OpenAI SDK compatibility** (recommended), `/openai` is automatically appended to the base URL.
 
         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. You can also set or edit policies later.
+
+    If selected, enter settings or accept defaults that define the following policies (see linked articles for prerequisites and configuration details):
+    * [Manage token consumption](azure-openai-token-limit-policy.md)
+    * [Track token usage](azure-openai-emit-token-metric-policy.md) 
+    
+    Select **Review + Create**.
 1. After settings are validated, select **Create**. 
 
 ## Option 2. Add an OpenAPI specification to API Management
@@ -71,13 +80,13 @@ 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-21 GA version](https://github.com/Azure/azure-rest-api-specs/blob/main/specification/cognitiveservices/data-plane/AzureOpenAI/inference/stable/2024-10-21/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:
 
-    * url: `https://contoso.openai.azure.com/openai`
-    * default endpoint: `contoso.openai.azure.com`
+    * **url**: `https://contoso.openai.azure.com/openai`
+    * **default** endpoint: `contoso.openai.azure.com`
 
     ```json
     [...]
@@ -93,7 +102,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-21`.
 
 ### Add OpenAPI specification to API Management
 
@@ -113,7 +122,7 @@ If you added the Azure OpenAI API from its OpenAPI specification, you need to co
 
 ## Test the Azure OpenAI API
 
-To ensure that your Azure OpenAI API is working as expected, test it in the API Management test console. You need to supply a model deployment ID (name) configured in the Azure OpenAI resource to test the API.
+To ensure that your Azure OpenAI API is working as expected, test it in the API Management test console. You need to supply a model deployment ID (name) configured in the Azure OpenAI resource and the API version to test the API.
 
 1. Select the API you created in the previous step.
 1. Select the **Test** tab.
@@ -128,7 +137,8 @@ To ensure that your Azure OpenAI API is working as expected, test it in the API
     > In the test console, API Management automatically populates an **Ocp-Apim-Subscription-Key** header, and configures the subscription key of the built-in [all-access subscription](api-management-subscriptions.md#all-access-subscription). This key enables access to every API in the API Management instance. Optionally display the **Ocp-Apim-Subscription-Key** header by selecting the "eye" icon next to the **HTTP Request**.
 1. Select **Send**.
 
-    When the test is successful, the backend responds with a successful HTTP response code and some data. Appended to the response is token usage data to help you monitor and manage your Azure OpenAI API consumption.
+    When the test is successful, the backend responds with a successful HTTP response code and some data. Appended to the response is token usage data to help you monitor and manage your Azure OpenAI API token consumption.
+
     :::image type="content" source="media/azure-openai-api-from-specification/api-response-usage.png" alt-text="Screenshot of token usage data in API response in the portal." :::
 
 ## Caching policies for Azure OpenAI APIs
@@ -138,5 +148,4 @@ In addition to the `azure-openai-token-limit` and `azure-openai-emit-token-metri
 * `azure-openai-semantic-cache-store`
 * `azure-openai-semantic-cache-lookup` 
 
-
 [!INCLUDE [api-management-define-api-topics.md](../../includes/api-management-define-api-topics.md)]

articles/api-management/azure-openai-emit-token-metric-policy.md

@@ -6,7 +6,7 @@ author: dlepow
 
 ms.service: azure-api-management
 ms.topic: reference
-ms.date: 09/26/2024
+ms.date: 04/01/2025
 ms.author: danlep
 ms.collection: ce-skilling-ai-copilot
 ms.custom:
@@ -65,19 +65,11 @@ The `azure-openai-emit-token-metric` policy sends custom metrics to Application
 | name      | A string or policy expression. Name of dimension.      | Yes      |  N/A            |
 | value     | A string or policy expression. Value of dimension. Can only be omitted if `name` matches one of the default dimensions. If so, value is provided as per dimension name. | No        | N/A |
 
- ### Default dimension names that may be used without value
-
-* API ID
-* Operation ID
-* Product ID
-* User ID
-* Subscription ID
-* Location
-* Gateway ID
+[!INCLUDE [api-management-emit-metric-dimensions](../../includes/api-management-emit-metric-dimensions.md)]
 
 ## Usage
 
-- [**Policy sections:**](./api-management-howto-policies.md#sections) inbound
+- [**Policy sections:**](./api-management-howto-policies.md#sections) inbound, outbound
 - [**Policy scopes:**](./api-management-howto-policies.md#scopes) global, workspace, product, API, operation
 -  [**Gateways:**](api-management-gateways-overview.md) classic, v2, consumption, self-hosted, workspace
 
@@ -91,7 +83,7 @@ The `azure-openai-emit-token-metric` policy sends custom metrics to Application
 
 ## Example
 
-The following example sends Azure OpenAI token count metrics to Application Insights along with API ID as a custom dimension.
+The following example sends Azure OpenAI token count metrics to Application Insights along with API ID as a default dimension.
 
 ```xml
 <policies>