Merge branch 'main' into release-rsa-sentinel-platform-2

Author: v-alje

articles/api-management/azure-ai-foundry-api.md

@@ -5,7 +5,7 @@ ms.service: azure-api-management
 author: dlepow
 ms.author: danlep
 ms.topic: how-to
-ms.date: 03/24/2026
+ms.date: 03/30/2026
 ms.update-cycle: 180-days
 ms.collection: ce-skilling-ai-copilot
 ms.custom: template-how-to, build-2024
@@ -17,29 +17,37 @@ ms.custom: template-how-to, build-2024
 
 You can import AI model endpoints deployed in Microsoft Foundry to your API Management instance as APIs. Use AI gateway policies and other capabilities in API Management to simplify integration, improve observability, and enhance control over the model endpoints.
 
-Learn more about managing AI APIs in API Management:
+To learn more about managing AI APIs in API Management, see:
 
 * [AI gateway capabilities in Azure API Management](genai-gateway-capabilities.md)
 
 ## Client compatibility options
 
-API Management supports two client compatibility options for AI APIs from Microsoft Foundry. When you import the API using the wizard, choose the option suitable for your model deployment. The option determines how clients call the API and how the API Management instance routes requests to the Foundry tool.
+API Management supports the following client compatibility options for AI APIs from Microsoft Foundry. When you import the API by using the wizard, choose the option suitable for your model deployment. The option determines how clients call the API and how the API Management instance routes requests to the Foundry tool.
 
 * **Azure OpenAI**: Manage Azure OpenAI in Microsoft Foundry model deployments.
 
-    Clients call the deployment at an `/openai` endpoint such as `/openai/deployments/my-deployment/chat/completions`. Deployment name is passed in the request path. Use this option if your Foundry tool only includes Azure OpenAI model deployments.
+    Clients call the deployment at an `/openai` endpoint such as `/openai/deployments/my-deployment/chat/completions`. The request path includes the deployment name. Use this option if your Foundry tool only includes Azure OpenAI model deployments. 
 
 * **Azure AI**: Manage model endpoints in Microsoft Foundry that are exposed through the [Azure AI Model Inference API](/rest/api/aifoundry/modelinference/).
 
-    Clients call the deployment at a `/models` endpoint such as `/my-model/models/chat/completions`. Deployment name is passed in the request body. Use this option if you want flexibility to switch between models exposed through the Azure AI Model Inference API and those deployed in Azure OpenAI in Foundry Models.
+    Clients call the deployment at a `/models` endpoint such as `/my-model/models/chat/completions`. The request body includes the deployment name. Use this option if you want flexibility to switch between models exposed through the Azure AI Model Inference API and those deployed in Azure OpenAI in Foundry Models.
+
+* **Azure OpenAI v1** - Manage Azure OpenAI in Microsoft Foundry model deployments, using the [Azure OpenAI API version 1 API](/azure/foundry/openai/api-version-lifecycle). 
+
+    Clients call the deployment at an Azure OpenAI v1 model endpoint such as `openai/v1/my-model/chat/completions`. The request body includes the deployment name. 
 
 ## Prerequisites
 
 * An existing API Management instance. [Create one if you haven't already](get-started-create-service-instance.md).
 
 * A Foundry tool in your subscription with one or more models deployed. Examples include models deployed in Microsoft Foundry or Azure OpenAI.
 
-## Import Microsoft Foundry API using the portal
+- If you want to enable semantic caching for the API, see [Enable semantic caching of responses](azure-openai-enable-semantic-caching.md) for prerequisites.
+
+- If you want to enforce content safety checks on the API, see [Enforce content safety checks on LLM requests](llm-content-safety-policy.md) for prerequisites.
+
+## Import Microsoft Foundry API by using the portal
 
 Use the following steps to import an AI API to API Management.
 
@@ -48,28 +56,29 @@ When you import the API, API Management automatically configures:
 * Operations for each of the API's REST API endpoints.
 * A system-assigned identity with the necessary permissions to access the Foundry tool deployment.
 * A [backend](backends.md) resource and a [set-backend-service](set-backend-service-policy.md) policy that direct API requests to the Azure AI Services endpoint.
-* Authentication to the backend using the instance's system-assigned managed identity.
+* Authentication to the backend by using the instance's system-assigned managed identity.
 * (optionally) Policies to help you monitor and manage the API.
 
 To import a Microsoft Foundry API to API Management:
 
-1. In the [Azure portal](https://portal.azure.com), navigate to your API Management instance.
+1. In the [Azure portal](https://portal.azure.com), go to your API Management instance.
 1. In the left menu, under **APIs**, select **APIs** > **+ Add API**.
 1. Under **Create from Azure resource**, select **Microsoft Foundry**.
 
     :::image type="content" source="media/azure-ai-foundry-api/ai-foundry-api.png" alt-text="Screenshot of creating an OpenAI-compatible API in the portal." :::
 1. On the **Select AI Service** tab:
     1. Select the **Subscription** in which to search for Foundry Tools. To get information about the model deployments in a service, select the **deployments** link next to the service name.
-       :::image type="content" source="media/azure-ai-foundry-api/deployments.png" alt-text="Screenshot of deployments for an AI service in the portal.":::
-    1. Select a Foundry tool.
+       :::image type="content" source="media/azure-ai-foundry-api/deployments.png" alt-text="Screenshot of deployments for an AI service in the portal." lightbox="media/azure-ai-foundry-api/deployments.png":::
+    1. Select a Foundry tool. 
     1. Select **Next**.
 1. On the **Configure API** tab:
     1. Enter a **Display name** and optional **Description** for the API.
     1. In **Base path**, enter a path that your API Management instance uses to access the deployment endpoint.
-    1. Optionally, select one or more **Products** to associate with the API.  
-    1. In **Client compatibility**, select either of the following based on the types of client you intend to support. See [Client compatibility options](#client-compatibility-options) for more information.
-        * **Azure OpenAI**: Select this option if your clients only need to access Azure OpenAI in Microsoft Foundry model deployments.
-        * **Azure AI**: Select this option if your clients need to access other models in Microsoft Foundry.
+    1. Optionally select one or more **Products** to associate with the API.  
+    1. In **Client compatibility**, select one of the following options based on the types of client you intend to support. See [Client compatibility options](#client-compatibility-options) for more information.
+        * **Azure OpenAI** - Select this option if your clients only need to access Azure OpenAI in Microsoft Foundry model deployments.
+        * **Azure AI** - Select this option if your clients need to access other models in Microsoft Foundry.
+        * **Azure OpenAI v1** - Select this option if you want to use the Azure OpenAI API version 1 with your Foundry model deployments. 
     1. Select **Next**.
 
         :::image type="content" source="media/azure-ai-foundry-api/client-compatibility.png" alt-text="Screenshot of Microsoft Foundry API configuration in the portal.":::
@@ -79,15 +88,14 @@ To import a Microsoft Foundry API to API Management:
     * [Track token usage](llm-emit-token-metric-policy.md)
 1. On the **Apply semantic caching** tab, optionally enter settings, or accept defaults that define the policies to help optimize performance and reduce latency for the API:
     * [Enable semantic caching of responses](azure-openai-enable-semantic-caching.md)
-1. On the **AI content safety**, optionally enter settings, or accept defaults to configure the Azure AI Content Safety service to block prompts with unsafe content:
+1. On the **AI content safety** tab, optionally enter settings or accept defaults to configure the Azure AI Content Safety service to block prompts with unsafe content:
     * [Enforce content safety checks on LLM requests](llm-content-safety-policy.md)
 1. Select **Review**.
-1. After settings are validated, select **Create**.
+1. After the portal validates the settings, select **Create**. 
 
 ## Test the AI API
 
-To ensure that your AI API is working as expected, test it in the API Management test console.
-
+To make sure your AI API works as expected, test it in the API Management test console. 
 1. Select the API you created in the previous step.
 1. Select the **Test** tab.
 1. Select an operation that's compatible with the model deployment.
@@ -108,9 +116,9 @@ To ensure that your AI API is working as expected, test it in the API Management
     ```
 
     > [!NOTE]
-    > 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**.
+    > In the test console, API Management automatically adds an **Ocp-Apim-Subscription-Key** header and sets the subscription key for the built-in [all-access subscription](api-management-subscriptions.md#all-access-subscription). This key provides access to every API in the API Management instance. To optionally display the **Ocp-Apim-Subscription-Key** header, select 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 language model token consumption.
+    When the test is successful, the backend responds with a successful HTTP response code and some data. The response includes token usage data to help you monitor and manage your language model token consumption.
 
 [!INCLUDE [api-management-define-api-topics.md](../../includes/api-management-define-api-topics.md)]

articles/api-management/media/azure-ai-foundry-api/ai-foundry-api.png

@@ -4,7 +4,7 @@ description: Set up Azure App Service and Azure Functions to use App Configurati
 author: muksvso
 
 ms.topic: how-to
-ms.date: 05/08/2025
+ms.date: 03/30/2026
 ms.author: mubatra
 
 #customer intent: As a developer, I want to use Azure App Configuration references so that I can make configuration key/value pairs available to code.  
@@ -17,6 +17,20 @@ ms.custom: sfi-ropc-nochange
 
 This article shows how to work with configuration data in Azure App Service or Azure Functions applications without making any code changes. [Azure App Configuration](../azure-app-configuration/overview.md) is an Azure service that you can use to centrally manage application configuration. It's also an effective tool for auditing your configuration values over time or across releases.
 
+## Important notes for Azure Functions local development
+
+App Configuration references (`@Microsoft.AppConfiguration(...)`) are resolved by the Azure App Service/Functions platform when your app runs in Azure.
+
+- **Azure (supported):** Put the reference in your function app's **Application settings** (for example, in the Azure portal, ARM/Bicep, or other deployment tooling).
+- **Local (not supported):** The Functions host running on your development machine doesn't resolve `@Microsoft.AppConfiguration(...)` values from *local.settings.json*.
+- **User secrets (not supported):** The Functions user secrets store (*secrets.json*) is also not processed for `@Microsoft.AppConfiguration(...)` references.
+- **SDK code (not required for this feature):** Calling `AddAzureAppConfiguration()` configures the App Configuration SDK for in-process resolution, but it doesn't make the platform resolve `@Microsoft.AppConfiguration(...)` references locally.
+
+If you want the same configuration values locally, use one of the following approaches:
+
+- Add the values directly to *local.settings.json* (for example, set `MySetting` to the literal value you want locally).
+- Use the App Configuration SDK in your app code (for example, by configuring `AddAzureAppConfiguration()` and connecting to your store with a connection string or credentials appropriate for local dev). This approach is separate from platform references.
+
 ## Grant app access to App Configuration
 
 To get started with using App Configuration references in App Service, first you create an App Configuration store. You then grant permissions to your app to access the configuration key/value pairs that are in the store.
@@ -78,20 +92,58 @@ An App Configuration reference has the form `@Microsoft.AppConfiguration({refere
 Here's an example of a complete reference that includes `Label`:
 
 ```json
-@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey; Label=myKeyLabel)​
+@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey; Label=myKeyLabel)
 ```
 
 Here's an example that doesn't include `Label`:
 
 ```json
-@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey)​
+@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey)
 ```
 
 Any configuration change to the app that results in a site restart causes an immediate refetch of all referenced key/value pairs from the App Configuration store.
 
 > [!NOTE]
 > Automatic refresh and refetch of these values when the key/value pairs are updated in App Configuration isn't currently supported.
 
+## Working example (Azure Functions)
+
+The following example shows where the `@Microsoft.AppConfiguration(...)` syntax goes for an Azure Functions app.
+
+### 1) Create a key/value in App Configuration
+
+In your App Configuration store, create a key/value pair:
+
+- **Key:** `Demo:Color`
+- **Label:** (optional) `dev`
+- **Value:** `Blue`
+
+### 2) Add an application setting to your function app in Azure
+
+In your Function App (in Azure), add an application setting named `Demo__Color` and set its value to an App Configuration reference.
+
+> [!NOTE]
+> Use double underscores (`__`) if you want .NET configuration binding to map to `Demo:Color`.
+
+**Application setting name**
+
+```text
+Demo__Color
+```
+
+**Application setting value**
+
+```text
+@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=Demo:Color; Label=dev)
+```
+
+### 3) Read the setting in your function code
+
+At runtime, your code reads `Demo:Color` like any other app setting.
+
+> [!TIP]
+> You don't need to call `AddAzureAppConfiguration()` for platform references. Use `AddAzureAppConfiguration()` only when you want to load configuration directly via the SDK.
+
 ## Source application settings from App Configuration
 
 You can use App Configuration references as values for [application settings](configure-common.md#configure-app-settings) so you can keep configuration data in App Configuration instead of in the site configuration settings. Application settings and App Configuration key/value pairs are both securely encrypted at rest. If you need centralized configuration management capabilities, add configuration data to App Configuration.
@@ -162,8 +214,8 @@ Here's a sample template for a function app that has App Configuration reference
                         "[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]"
                     ],
                     "properties": {
-                        "WEBSITE_FONTNAME": "[concat('@Microsoft.AppConfiguration(Endpoint=', reference(resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))).endpoint,'; Key=',variables('FontNameKey'),'; Label=',variables('myLabel'), ')')]",
-                        "WEBSITE_FONTCOLOR": "[concat('@Microsoft.AppConfiguration(Endpoint=', reference(resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))).endpoint,'; Key=',variables('FontColorKey'),'; Label=',variables('myLabel'), ')')]",
+                        "WEBSITE_FONTNAME": "[concat('@Microsoft.AppConfiguration(Endpoint=', reference(resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))).endpoint,'; Key=',variables('FontNameKey'),'; Label=',variables('myLabel'), ')]",
+                        "WEBSITE_FONTCOLOR": "[concat('@Microsoft.AppConfiguration(Endpoint=', reference(resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))).endpoint,'; Key=',variables('FontColorKey'),'; Label=',variables('myLabel'), ')]",
                         "WEBSITE_ENABLE_SYNC_UPDATE_SITE": "true"
                         //...
                     }
@@ -202,7 +254,6 @@ Here's a sample template for a function app that has App Configuration reference
                     //...
                     "dependsOn": [
                         "[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]"
-
                     ],
                     "properties": {
                         "value": "Calibri",
@@ -216,7 +267,6 @@ Here's a sample template for a function app that has App Configuration reference
                     //...
                     "dependsOn": [
                         "[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]"
-
                     ],
                     "properties": {
                         "value": "Blue",
@@ -226,8 +276,8 @@ Here's a sample template for a function app that has App Configuration reference
             ]
         },
         {
-            "scope": "[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]",
-            "type": "Microsoft.Authorization/roleAssignments",
+            "scope": "[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName')]
+            ,"type": "Microsoft.Authorization/roleAssignments",
             "apiVersion": "2020-04-01-preview",
             "name": "[parameters('roleNameGuid')]",
             "properties": {