+The **Paragraph** user input type is used to provide a field that shows text only in a paragraph tag. For example, <p>text</p>. A **Paragraph** user input type `OutputClaim` of self-asserted technical profile, must set the `Required` attribute `false` (default). This user input type is only supported in self-asserted page layouts. Unified sign-in and sign-up pages (unifiedssp) might not display this properly.

+ Title: "Custom categories in Azure AI Content Safety"

+description: Learn about custom content categories and the different ways you can use Azure AI Content Safety to handle them on your platform.

+#

+# Custom categories

+Azure AI Content Safety lets you create and manage your own content moderation categories for enhanced moderation and filtering that matches your specific policies or use cases.

+## Types of customization

+There are multiple ways to define and use custom categories, which are detailed and compared in this section.

+| API | Functionality |

+| : | : |

+| [Custom categories (standard) API](#custom-categories-standard-api) | Use a customizable machine learning model to create, get, query, and delete a customized category. Or, list all your customized categories for further annotation tasks. |

+| [Custom categories (rapid) API](#custom-categories-rapid-api) | Use a large language model (LLM) to quickly learn specific content patterns in emerging content incidents. |

+### Custom categories (standard) API

+The Custom categories (standard) API enables customers to define categories specific to their needs, provide sample data, train a custom machine learning model, and use it to classify new content according to the learned categories.

+This is the standard workflow for customization with machine learning models. Depending on the training data quality, it can reach very good performance levels, but it can take up to several hours to train the model.

+This implementation works on text content, not image content.

+### Custom categories (rapid) API

+The Custom categories (rapid) API is designed to be quicker and more flexible than the standard method. It's meant to be used for identifying, analyzing, containing, eradicating, and recovering from cyber incidents that involve inappropriate or harmful content on online platforms.

+An incident may involve a set of emerging content patterns (text, image, or other modalities) that violate Microsoft community guidelines or the customers' own policies and expectations. These incidents need to be mitigated quickly and accurately to avoid potential live site issues or harm to users and communities.

+This implementation works on text content and image content.

+> [!TIP]

+> One way to deal with emerging content incidents is to use [Blocklists](/azure/ai-services/content-safety/how-to/use-blocklist), but that only allows exact text matching and no image matching. The Custom categories (rapid) API offers the following advanced capabilities:

+- semantic text matching using embedding search with a lightweight classifier

+- image matching with a lightweight object-tracking model and embedding search.

+## How it works

+#### [Custom categories (standard) API](#tab/standard)

+The Azure AI Content Safety custom category feature uses a multi-step process for creating, training, and using custom content classification models. Here's a look at the workflow:

+### Step 1: Definition and setup

+

+When you define a custom category, you need to teach the AI what type of content you want to identify. This involves providing a clear **category name** and a detailed **definition** that encapsulates the content's characteristics.

+Then, you collect a balanced dataset with **positive** and (optionally) **negative** examples to help the AI to learn the nuances of your category. This data should be representative of the variety of content that the model will encounter in a real-world scenario.

+### Step 2: Model training

+

+After you prepare your dataset and define categories, the Azure AI Content Safety service trains a new machine learning model. This model uses your definitions and uploaded dataset to perform data augmentation using a large language model. As a result, the training dataset is made larger and of higher quality. During training, the AI model analyzes the data and learns to differentiate between content that aligns with the specified category and content that does not.

+### Step 3: Model inferencing

+

+After training, you need to evaluate the model to ensure it meets your accuracy requirements. Test the model with new content that it hasn't received before. The evaluation phase helps you identify any potential adjustments you need to make deploying the model into a production environment.

+### Step 4: Model usage

+You use the **analyzeCustomCategory** API to analyze text content and determine whether it matches the custom category you've defined. The service will return a Boolean indicating whether the content aligns with the specified category

+#### [Custom categories (rapid) API](#tab/rapid)

+To use the custom category (rapid) API, you first create an **incident** object with a text description. Then, you upload any number of image or text samples to the incident. The LLM on the backend will then use these to evaluate future input content. No training step is needed.

+You can include your defined incident in a regular text analysis or image analysis request. The service will indicate whether the submitted content is an instance of your incident. The service can still do other content moderation tasks in the same API call.

+## Limitations

+### Language availability

+The Custom categories APIs support all languages that are supported by Content Safety text moderation. See [Language support](/azure/ai-services/content-safety/language-support).

+### Input limitations

+#### [Custom categories (standard) API](#tab/standard)

+See the following table for the input limitations of the custom categories (standard) API:

+| Object | Limitation |

+| - | |

+| Supported languages | English only |

+| Number of categories per user | 3 |

+| Number of versions per category | 3 |

+| Number of concurrent builds (processes) per category | 1 |

+| Inference operations per second | 5 |

+| Number of samples in a category version | Positive samples(required): minimum 50, maximum 5K<br>In total (both negative and positive samples): 10K<br>No duplicate samples allowed. |

+| Sample file size | maximum 128000 bytes |

+| Length of a text sample | maximum 125K characters |

+| Length of a category definition | maximum 1000 chars |

+|Length of a category name | maximum 128 characters |

+|Length of a blob url | maximum 500 characters |

+#### [Custom categories (rapid) API](#tab/rapid)

+See the following table for the input limitations of the custom categories (rapid) API:

+| Object | Limitation |

+| : | :-- |

+| Maximum length of an incident name | 100 characters |

+| Maximum number of text/image samples per incident | 1000 |

+| Maximum size of each sample | Text: 500 characters<br>Image: 4 MBΓÇ» |

+| Maximum number of text or image incidents per resource| 100 |

+| Supported Image formats | BMP, GIF, JPEG, PNG, TIF, WEBP |

+### Region availability

+To use these APIs, you must create your Azure AI Content Safety resource in one of the supported regions. See [Region availability](../overview.md#region-availability).

+## Next steps

+Follow a how-to guide to use the Azure AI Content Safety APIs to create custom categories.

+* [Use custom category (standard) API](../how-to/custom-categories.md)

+* [Use the custom categories (rapid) API](../how-to/custom-categories-rapid.md)

+## Azure AI Studio error messages

+If you encounter the error **Your account does not have access to this resource, please contact your resource owner to get access**, please ensure your account is assigned the role of `Cognitive Services User` for the Content Safety resource or Azure AI Services resource you are using.

+- [Custom categories concepts](../concepts/custom-categories.md)

+ Title: "Use the custom category API"

+description: Learn how to use the custom category API to create your own harmful content categories and train the Content Safety model for your use case.

+#

+# Use the custom categories (standard) API

+The custom categories (standard) API lets you create your own content categories for your use case and train Azure AI Content Safety to detect them in new content.

+> [!IMPORTANT]

+> This feature is only available in certain Azure regions. See [Region availability](../overview.md#region-availability).

+> [!CAUTION]

+> The sample data in this guide might contain offensive content. User discretion is advised.

+## Prerequisites

+* An Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-services/)

+* Once you have your Azure subscription, <a href="https://aka.ms/acs-create" title="Create a Content Safety resource" target="_blank">create a Content Safety resource</a> in the Azure portal to get your key and endpoint. Enter a unique name for your resource, select your subscription, and select a resource group, [supported region](../overview.md#region-availability), and supported pricing tier. Then select **Create**.

+ * The resource takes a few minutes to deploy. After it finishes, Select **go to resource**. In the left pane, under **Resource Management**, select **Subscription Key and Endpoint**. Copy the endpoint and either of the key values to a temporary location for later use.

+* Also [create an Azure blob storage container](https://ms.portal.azure.com/#create/Microsoft.StorageAccount-ARM) where you'll keep your training annotation file.

+* One of the following installed:

+ * [cURL](https://curl.haxx.se/) for REST API calls.

+ * [Python 3.x](https://www.python.org/) installed

+## Prepare your training data

+To train a custom category, you need example text data that represents the category you want to detect. Follow these steps to prepare your sample data:

+1. Collect or write your sample data:

+ - The quality of your sample data is important for training an effective model. Aim to collect at least 50 positive samples that accurately represent the content you want to identify. These samples should be clear, varied, and directly related to the category definition.

+ - Negative samples aren't required, but they can improve the model's ability to distinguish relevant content from irrelevant content.

+ To improve performance, aim for 50 samples that aren't related to the positive case definition. These should be varied but still within the context of the content your model will encounter. Choose negative samples carefully to ensure they don't inadvertently overlap with the positive category.

+ - Strive for a balance between the number of positive and negative samples. An uneven dataset can bias the model, causing it to favor one type of classification over another, which may lead to a higher rate of false positives or negatives.

+1. Use a text editor to format your data in a *.jsonl* file. Below is an example of the appropriate format. Category examples should set `isPositive` to `true`. Negative examples are optional but can improve performance:

+ ```json

+ {"text": "This is the 1st sample.", "isPositive": true}

+ {"text": "This is the 2nd sample.", "isPositive": true}

+ {"text": "This is the 3rd sample (negative).", "isPositive": false}

+ ```

+1. Upload the _.jsonl_ file to an Azure Storage account blob container. Copy the blob URL to a temporary location for later use.

+### Grant storage access

+## Create and train a custom category

+> [!IMPORTANT]

+> **Allow enough time for model training**

+>

+> The end-to-end execution of custom category training can take from around five hours to ten hours. Plan your moderation pipeline accordingly and allocate time for:

+> * Collecting and preparing your sample data

+> * The training process

+> * Model evaluation and adjustments

+#### [cURL](#tab/curl)

+In the commands below, replace `<your_api_key>`, `<your_endpoint>`, and other necessary parameters with your own values. Then enter each command in a terminal window and run it.

+### Create new category version

+```bash

+curl -X PUT "<your_endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-02-15-preview" \

+ -H "Ocp-Apim-Subscription-Key: <your_api_key>" \

+ -H "Content-Type: application/json" \

+ -d "{

+ \"categoryName\": \"<your_category_name>\",

+ \"definition\": \"<your_category_definition>\",

+ \"sampleBlobUrl\": \"https://example.blob.core.windows.net/example-container/sample.jsonl\"

+ }"

+```

+### Start the category build process:

+After you receive the response, store the operation ID (referred to as `id`) in a temporary. You need this ID to retrieve the build status using the **Get status** API.

+```bash

+curl -X POST "<your_endpoint>/contentsafety/text/categories/<your_category_name>:build?api-version=2024-02-15-preview&version={version}" \

+ -H "Ocp-Apim-Subscription-Key: <your_api_key>" \

+ -H "Content-Type: application/json"

+```

+### Get the category build status:

+To retrieve the status, utilize the `id` obtained from the previous API response and place it in the path of the API below.

+```bash

+curl -X GET "<your_endpoint>/contentsafety/text/categories/operations/<id>?api-version=2024-02-15-preview" \

+ -H "Ocp-Apim-Subscription-Key: <your_api_key>" \

+ -H "Content-Type: application/json"

+```

+## Analyze text with a customized category

+Run the following command to analyze text with your customized category. Replace `<your_category_name>` with your own value:

+```bash

+curl -X POST "<your_endpoint>/contentsafety/text:analyzeCustomCategory?api-version=2024-02-15-preview" \

+ -H "Ocp-Apim-Subscription-Key: <your_api_key>" \

+ -H "Content-Type: application/json" \

+ -d "{

+ \"text\": \"Example text to analyze\",

+ \"categoryName\": \"<your_category_name>\",

+ \"version\": 1

+ }"

+```

+#### [Python](#tab/python)

+First, you need to install the required Python library:

+```bash

+pip install requests

+```

+Then, open a new Python script and define the necessary variables with your own Azure resource details:

+```python

+import requests

+API_KEY = '<your_api_key>'

+ENDPOINT = '<your_endpoint>'

+headers = {

+ 'Ocp-Apim-Subscription-Key': API_KEY,

+ 'Content-Type': 'application/json'

+}

+```

+### Create a new category version

+You can create a new category with *category name*, *definition* and *sample_blob_url*, and you'll get the autogenerated version number of this category.

+```python

+def create_new_category_version(category_name, definition, sample_blob_url):

+ url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}?api-version=2024-02-15-preview"

+ data = {

+ "categoryName": category_name,

+ "definition": definition,

+ "sampleBlobUrl": sample_blob_url

+ }

+ response = requests.put(url, headers=headers, json=data)

+ return response.json()

+# Replace the parameters with your own values

+category_name = "DrugAbuse"

+definition = "This category is related to Drug Abuse."

+sample_blob_url = "https://<your-azure-storage-url>/example-container/drugsample.jsonl"

+result = create_new_category_version(category_name, definition, sample_blob_url)

+print(result)

+```

+### Start the category build process

+You can start the category build process with the *category name* and *version number*.

+```python

+def trigger_category_build_process(category_name, version):

+ url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}:build?api-version=2024-02-15-preview&version={version}"

+ response = requests.post(url, headers=headers)

+ return response.status_code

+# Replace the parameters with your own values

+category_name = "<your_category_name>"

+version = 1

+result = trigger_category_build_process(category_name, version)

+print(result)

+```

+### Get the category build status:

+To retrieve the status, utilize the `id` obtained from the previous response.

+```python

+def get_build_status(id):

+ url = f"{ENDPOINT}/contentsafety/text/categories/operations/{id}?api-version=2024-02-15-preview"

+ response = requests.get(url, headers=headers)

+ return response.status_code

+# Replace the parameter with your own value

+id = "your-operation-id"

+result = get_build_status(id)

+print(result)

+```

+## Analyze text with a customized category

+You need to specify the *category name* and the *version number* (optional; the service uses the latest one by default) during inference. You can specify multiple categories if they're already defined.

+```python

+def analyze_text_with_customized_category(text, category_name, version):

+ url = f"{ENDPOINT}/contentsafety/text:analyzeCustomCategory?api-version=2024-02-15-preview"

+ data = {

+ "text": text,

+ "categoryName": category_name,

+ "version": version

+ }

+ response = requests.post(url, headers=headers, json=data)

+ return response.json()

+# Replace the parameters with your own values

+text = "Example text to analyze"

+category_name = "<your_category_name>"

+version = 1

+result = analyze_text_with_customized_category(text, category_name, version)

+print(result)

+```

+## Other custom category operations

+Remember to replace the placeholders below with your actual values for the API key, endpoint, and specific content (category name, definition, and so on). These examples help you to manage the customized categories in your account.

+#### [cURL](#tab/curl)

+### Get a customized category or a specific version of it

+Replace the placeholders with your own values and run the following command in a terminal window:

+```bash

+curl -X GET "<endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-02-15-preview&version=1" \

+ -H "Ocp-Apim-Subscription-Key: <your_api_key>" \

+ -H "Content-Type: application/json"

+```

+### List categories of their latest versions

+Replace the placeholders with your own values and run the following command in a terminal window:

+```bash

+curl -X GET "<endpoint>/contentsafety/text/categories?api-version=2024-02-15-preview" \

+ -H "Ocp-Apim-Subscription-Key: <your_api_key>" \

+ -H "Content-Type: application/json"

+```

+### Delete a customized category or a specific version of it

+Replace the placeholders with your own values and run the following command in a terminal window:

+```bash

+curl -X DELETE "<endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-02-15-preview&version=1" \

+ -H "Ocp-Apim-Subscription-Key: <your_api_key>" \

+ -H "Content-Type: application/json"

+```

+#### [Python](#tab/python)

+First, make sure you've installed the required Python library:

+```bash

+pip install requests

+```

+Then, set up the necessary configurations with your own AI resource details:

+```python

+import requests

+API_KEY = '<your_api_key>'

+ENDPOINT = '<your_endpoint>'

+headers = {

+ 'Ocp-Apim-Subscription-Key': API_KEY,

+ 'Content-Type': 'application/json'

+}

+```

+### Get a customized category or a specific version of it

+Replace the placeholders with your own values and run the following code in your Python script:

+```python

+def get_customized_category(category_name, version=None):

+ url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}?api-version=2024-02-15-preview"

+ if version:

+ url += f"&version={version}"

+

+ response = requests.get(url, headers=headers)

+ return response.json()

+# Replace the parameters with your own values

+category_name = "DrugAbuse"

+version = 1

+result = get_customized_category(category_name, version)

+print(result)

+```

+### List categories of their latest versions

+```python

+def list_categories_latest_versions():

+ url = f"{ENDPOINT}/contentsafety/text/categories?api-version=2024-02-15-preview"

+ response = requests.get(url, headers=headers)

+ return response.json()

+result = list_categories_latest_versions()

+print(result)

+```

+### Delete a customized category or a specific version of it

+Replace the placeholders with your own values and run the following code in your Python script:

+```python

+def delete_customized_category(category_name, version=None):

+ url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}?api-version=2024-02-15-preview"

+ if version:

+ url += f"&version={version}"

+

+ response = requests.delete(url, headers=headers)

+ return response.status_code

+# Replace the parameters with your own values

+category_name = "<your_category_name>"

+version = 1

+result = delete_customized_category(category_name, version)

+print(result)

+```

+## Related content

+* [Custom categories concepts](../concepts/custom-categories.md)

+* [Moderate content with Content Safety](../quickstart-text.md)

+| [Prompt Shields](/rest/api/contentsafety/text-operations/detect-text-jailbreak) (preview) | Scans text for the risk of a [User input attack](./concepts/jailbreak-detection.md) on a Large Language Model. [Quickstart](./quickstart-jailbreak.md) |

+| [Groundedness detection](/rest/api/contentsafety/text-groundedness-detection-operations/detect-groundedness-options) (preview) | Detects whether the text responses of large language models (LLMs) are grounded in the source materials provided by the users. [Quickstart](./quickstart-groundedness.md) |

+| [Protected material text detection](/rest/api/contentsafety/text-operations/detect-text-protected-material) (preview) | Scans AI-generated text for [known text content](./concepts/protected-material.md) (for example, song lyrics, articles, recipes, selected web content). [Quickstart](./quickstart-protected-material.md)|

+| Custom categories API (preview) | Lets you create and train your own [custom content categories](./concepts/custom-categories.md) and scan text for matches. [Quickstart](./quickstart-custom-categories.md) |

+| Custom categories (rapid) API (preview) | Lets you define [emerging harmful content patterns](./concepts/custom-categories.md) and scan text and images for matches. [How-to guide](./how-to/custom-categories-rapid.md) |

+| [Analyze text](/rest/api/contentsafety/text-operations/analyze-text) API | Scans text for sexual content, violence, hate, and self harm with multi-severity levels. |

+| [Analyze image](/rest/api/contentsafety/image-operations/analyze-image) API | Scans images for sexual content, violence, hate, and self harm with multi-severity levels. |

+- **Custom categories (standard)**:

+ - Maximum inference input length: 1K characters.

+Custom Categories currently only works well in English. You can try to use other languages with your own dataset, but the quality might vary across languages.

+|Region | Moderation APIs | Prompt Shields<br>(preview) | Protected material<br>detection (preview) | Groundedness<br>detection (preview) | Custom categories<br>(rapid) (preview) | Custom categories<br>(standard) | Blocklists |

+||||||||--|

+| East US | ✅ | ✅| ✅ |✅ |✅ |✅|✅ |

+| East US 2 | ✅ | | | ✅ |✅ | |✅|

+| West US | | | | | ✅ | | |

+| West US 2 | ✅ | | | |✅ | |✅ |

+| Central US | ✅ | | | | | |✅ |

+| North Central US | ✅ | | | |✅ | | ✅|

+| South Central US | ✅ | | | | ✅| |✅ |

+| Canada East | ✅ | | | | ✅| | ✅|

+| Switzerland North | ✅ | | | |✅ | ✅ | ✅|

+| Sweden Central | ✅ | | |✅ |✅ | | ✅|

+| UK South | ✅ | | | | ✅| |✅ |

+| France Central | ✅ | | | |✅ | | ✅|

+| West Europe | ✅ | ✅ |✅ | |✅ | |✅ |

+| Japan East | ✅ | | | |✅ | |✅ |

+| Australia East| ✅ | ✅ | | |✅ | ✅| ✅|

+Content Safety features have query rate limits in requests-per-second (RPS) or requests-per-10-seconds (RP10S) . See the following table for the rate limits for each feature.

+|Pricing tier | Moderation APIs | Prompt Shields<br>(preview) | Protected material<br>detection (preview) | Groundedness<br>detection (preview) | Custom categories<br>(rapid) (preview) | Custom categories<br>(standard) (preview)|

+|--||-||||--|

+| F0 | 1000 RP10S | 1000 RP10S | 1000 RP10S | 50 RP10S | 1000 RP10S | 5 RPS|

+| S0 | 1000 RP10S | 1000 RP10S | 1000 RP10S | 50 RP10S | 1000 RP10S | 5 RPS|

+ Title: "Quickstart: Custom categories"

+description: Use the custom category API to create your own harmful content categories and train the Content Safety model for your use case.

+#

+# Quickstart: Custom categories (standard mode)

+Follow this guide to use Azure AI Content Safety Custom category REST API to create your own content categories for your use case and train Azure AI Content Safety to detect them in new text content.

+> [!IMPORTANT]

+> This feature is only available in certain Azure regions. See [Region availability](./overview.md#region-availability).

+> [!IMPORTANT]

+> **Allow enough time for model training**

+>

+> The end-to-end execution of custom category training can take from around five hours to ten hours. Plan your moderation pipeline accordingly.

+## Prerequisites

+* An Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-services/)

+* Once you have your Azure subscription, <a href="https://aka.ms/acs-create" title="Create a Content Safety resource" target="_blank">create a Content Safety resource</a> in the Azure portal to get your key and endpoint. Enter a unique name for your resource, select your subscription, and select a resource group, [supported region](./overview.md#region-availability), and supported pricing tier. Then select **Create**.

+ * The resource takes a few minutes to deploy. After it finishes, Select **go to resource**. In the left pane, under **Resource Management**, select **Subscription Key and Endpoint**. Copy the endpoint and either of the key values to a temporary location for later use.

+* Also [create an Azure blob storage container](https://ms.portal.azure.com/#create/Microsoft.StorageAccount-ARM) where you'll keep your training annotation file.

+* One of the following installed:

+ * [cURL](https://curl.haxx.se/) for REST API calls.

+ * [Python 3.x](https://www.python.org/) installed

+## Prepare your training data

+To train a custom category, you need example text data that represents the category you want to detect. In this guide, you can use sample data. The provided annotation file contains text prompts about survival advice in camping/wilderness situations. The trained model will learn to detect this type of content in new text data.

+> [!TIP]

+> For tips on creating your own data set, see the [How-to guide](./how-to/custom-categories.md#prepare-your-training-data).

+1. Download the [sample text data file](https://github.com/Azure-Samples/cognitive-services-sample-data-files/blob/master/ContentSafety/survival-advice.jsonl) from the GitHub repository.

+1. Upload the _.jsonl_ file to your Azure Storage account blob container. Then copy the blob URL to a temporary location for later use.

+### Grant storage access

+## Create and train a custom category

+#### [cURL](#tab/curl)

+In the command below, replace `<your_api_key>`, `<your_endpoint>`, and other necessary parameters with your own values. Then enter each command in a terminal window and run it.

+### Create new category version

+```bash

+curl -X PUT "<your_endpoint>/contentsafety/text/categories/survival-advice?api-version=2024-02-15-preview" \

+ -H "Ocp-Apim-Subscription-Key: <your_api_key>" \

+ -H "Content-Type: application/json" \

+ -d "{

+ \"categoryName\": \"survival-advice\",

+ \"definition\": \"text prompts about survival advice in camping/wilderness situations\",

+ \"sampleBlobUrl\": \"https://<your-azure-storage-url>/example-container/survival-advice.jsonl\"

+ }"

+```

+### Start the category build process:

+Replace `<your_api_key>` and `<your_endpoint>` with your own values. Allow enough time for model training: the end-to-end execution of custom category training can take from around five hours to ten hours. Plan your moderation pipeline accordingly. After you receive the response, store the operation ID (referred to as `id`) in a temporary location. This ID will be necessary for retrieving the build status using the **Get status** API in the next section.

+```bash

+curl -X POST "<your_endpoint>/contentsafety/text/categories/survival-advice:build?api-version=2024-02-15-preview" \

+ -H "Ocp-Apim-Subscription-Key: <your_api_key>" \

+ -H "Content-Type: application/json"

+```

+### Get the category build status:

+To retrieve the status, utilize the `id` obtained from the previous API response and place it in the path of the API below.

+```bash

+curl -X GET "<your_endpoint>/contentsafety/text/categories/operations/<id>?api-version=2024-02-15-preview" \

+ -H "Ocp-Apim-Subscription-Key: <your_api_key>" \

+ -H "Content-Type: application/json"

+```

+## Analyze text with a customized category

+Run the following command to analyze text with your customized category. Replace `<your_api_key>` and `<your_endpoint>` with your own values.

+```bash

+curl -X POST "<your_endpoint>/contentsafety/text:analyzeCustomCategory?api-version=2024-02-15-preview" \

+ -H "Ocp-Apim-Subscription-Key: <your_api_key>" \

+ -H "Content-Type: application/json" \

+ -d "{

+ \"text\": \"<Example text to analyze>\",

+ \"categoryName\": \"survival-advice\",

+ \"version\": 1

+ }"

+```

+#### [Python](#tab/python)

+First, you need to install the required Python library:

+```bash

+pip install requests

+```

+Then, open a new Python script and define the necessary variables with your own Azure resource details:

+```python

+import requests

+API_KEY = '<your_api_key>'

+ENDPOINT = '<your_endpoint>'

+headers = {

+ 'Ocp-Apim-Subscription-Key': API_KEY,

+ 'Content-Type': 'application/json'

+}

+```

+### Create a new category

+You can create a new category with *category name*, *definition* and *sample_blob_url*, and you'll get the autogenerated version number of this category.

+```python

+def create_new_category_version(category_name, definition, sample_blob_url):

+ url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}?api-version=2024-02-15-preview"

+ data = {

+ "categoryName": category_name,

+ "definition": definition,

+ "sampleBlobUrl": sample_blob_url

+ }

+ response = requests.put(url, headers=headers, json=data)

+ return response.json()

+# Replace the parameters with your own values

+category_name = "survival-advice"

+definition = "text prompts about survival advice in camping/wilderness situations"

+sample_blob_url = "https://<your-azure-storage-url>/example-container/survival-advice.jsonl"

+result = create_new_category_version(category_name, definition, sample_blob_url)

+print(result)

+```

+### Start the category build process

+You can start the category build process with the *category name* and *version number*. Allow enough time for model training: the end-to-end execution of custom category training can take from around five hours to ten hours. Plan your moderation pipeline accordingly. After receiving the response, ensure that you store the operation ID (referred to as `id`) somewhere like your notebook. This ID will be necessary for retrieving the build status using the ΓÇÿget_build_statusΓÇÖ function in the next section.

+```python

+def trigger_category_build_process(category_name, version):

+ url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}:build?api-version=2024-02-15-preview&version={version}"

+ response = requests.post(url, headers=headers)

+ return response.status_code

+# Replace the parameters with your own values

+category_name = "survival-advice"

+version = 1

+result = trigger_category_build_process(category_name, version)

+print(result)

+```

+### Get the category build status:

+To retrieve the status, utilize the `id` obtained from the previous response.

+```python

+def get_build_status(id):

+ url = f"{ENDPOINT}/contentsafety/text/categories/operations/{id}?api-version=2024-02-15-preview"

+ response = requests.get(url, headers=headers)

+ return response.status_code

+# Replace the parameter with your own value

+id = "your-operation-id"

+result = get_build_status(id)

+print(result)

+```

+## Analyze text with a customized category

+You need to specify the *category name* and the *version number* (optional; the service uses the latest one by default) during inference. You can specify multiple categories if they're already defined.

+```python

+def analyze_text_with_customized_category(text, category_name, version):

+ url = f"{ENDPOINT}/contentsafety/text:analyzeCustomCategory?api-version=2024-02-15-preview"

+ data = {

+ "text": text,

+ "categoryName": category_name,

+ "version": version

+ }

+ response = requests.post(url, headers=headers, json=data)

+ return response.json()

+# Replace the parameters with your own values

+text = "<Example text to analyze>"

+category_name = "survival-advice"

+version = 1

+result = analyze_text_with_customized_category(text, category_name, version)

+print(result)

+```

+## Related content

+* For information on other Custom category operations, see the [How-to guide](./how-to/custom-categories.md).

+* [Custom categories concepts](./concepts/custom-categories.md)

+* [Moderate content with Content Safety](./quickstart-text.md)

+* Once you have your Azure subscription, <a href="https://aka.ms/acs-create" title="Create a Content Safety resource" target="_blank">create a Content Safety resource </a> in the Azure portal to get your key and endpoint. Enter a unique name for your resource, select your subscription, and select a resource group, [supported region](./overview.md#region-availability), and supported pricing tier. Then select **Create**.

+Protected material text describes language that matches known text content (for example, song lyrics, articles, recipes, selected web content). This feature can be used to identify and block known text content from being displayed in language model output (English content only). For more information, see [Protected material concepts](./concepts/protected-material.md).

+## July 2024

+### Custom categories (standard) API

+The custom categories API lets you create and train your own custom content categories and scan text for matches. See [Custom categories](./concepts/custom-categories.md) to learn more.

+The custom categories (rapid) API lets you quickly define emerging harmful content patterns and scan text and images for matches. See [Custom categories](./concepts/custom-categories.md) to learn more.

+ Title: Azure OpenAI default content safety policies

+description: Learn about the default content safety policies that Azure OpenAI uses to flag content.

+# Default content safety policies

+Azure OpenAI Service includes default safety applied to all models, excluding Azure OpenAI Whisper. These configurations provide you with a responsible experience by default, including [content filtering models](/azure/ai-services/openai/concepts/content-filter?tabs=warning%2Cpython-new), blocklists, prompt transformation, [content credentials](/azure/ai-services/openai/concepts/content-credentials), and others.

+Default safety aims to mitigate risks such as hate and fairness, sexual, violence, self-harm, protected material content and user prompt injection attacks. To learn more about content filtering, visit our documentation describing categories and severity levels [here](/azure/ai-services/openai/concepts/content-filter?tabs=warning%2Cpython-new).

+All safety is configurable. To learn more about configurability, visit our documentation on [configuring content filtering](/azure/ai-services/openai/how-to/content-filters).

+## Text models: GPT-4, GPT-3.5

+Text models in the Azure OpenAI Service can take in and generate both text and code. These models leverage AzureΓÇÖs text content filtering models to detect and prevent harmful content. This system works on both prompt and completion.

+| Risk Category | Prompt/Completion | Severity Threshold |

+|-|||

+| Hate and Fairness | Prompts and Completions| Medium |

+| Violence | Prompts and Completions| Medium |

+| Sexual | Prompts and Completions| Medium |

+| Self-Harm | Prompts and Completions| Medium |

+| User prompt injection attack (Jailbreak) | Prompts | N/A |

+| Protected Material ΓÇô Text | Completions | N/A |

+| Protected Material ΓÇô Code | Completions | N/A |

+## Vision models: GPT-4o, GPT-4 Turbo, DALL-E 3, DALL-E 2

+### GPT-4o and GPT-4 Turbo

+| Risk Category | Prompt/Completion | Severity Threshold |

+||||

+| Hate and Fairness | Prompts and Completions| Medium |

+| Violence | Prompts and Completions| Medium |

+| Sexual | Prompts and Completions| Medium |

+| Self-Harm | Prompts and Completions| Medium |

+| Identification of Individuals and Inference of Sensitive Attributes | Prompts | N/A |

+| User prompt injection attack (Jailbreak) | Prompts | N/A |

+### DALL-E 3 and DALL-E 2

+| Risk Category | Prompt/Completion | Severity Threshold |

+||||

+| Hate and Fairness | Prompts and Completions| Low |

+| Violence | Prompts and Completions| Low |

+| Sexual | Prompts and Completions| Low |

+| Self-Harm | Prompts and Completions| Low |

+| Content Credentials | Completions | N/A |

+| Deceptive Generation of Political Candidates | Prompts | N/A |

+| Depictions of Public Figures | Prompts | N/A |

+| User prompt injection attack (Jailbreak) | Prompts | N/A |

+| Protected Material ΓÇô Art and Studio Characters | Prompts | N/A |

+| Profanity | Prompts | N/A |

+In addition to the above safety configurations, Azure OpenAI DALL-E also comes with [prompt transformation](./prompt-transformation.md) by default. This transformation occurs on all prompts to enhance the safety of your original prompt, specifically in the risk categories of diversity, deceptive generation of political candidates, depictions of public figures, protected material, and others.

+ Title: Azure OpenAI prompt transformation concepts

+description: Learn about the prompt transformation feature in Azure OpenAI DALL-E 3, how it works, and why it's necessary.

+# What is prompt transformation?

+Prompt transformation is a process in DALL-E 3 image generation that applies a safety and quality system message to your original prompt using a large language model (LLM) call before being sent to the model for image generation. This system message enriches your original prompt with the goal of generating more diverse and higher-quality images, while maintaining intent.

+Prompt transformation is applied to all Azure OpenAI DALL-E 3 requests by default. There may be scenarios in which your use case requires a lower level of enrichment. To generate images that use prompts that more closely resemble your original prompt, append this text to your prompt: `I NEED to test how the tool works with extremely simple prompts. DO NOT add any detail, just use it AS-IS:`. This ensures there is minimal prompt transformation. Evaluating your system behavior with and without this prompt helps you better understand the impact and value of prompt transformation.

+After prompt transformation is applied to the original prompt, content filtering is applied as a secondary step before image generation; for more information, see [Content filtering](./content-filter.md).

+> [!TIP]

+> Learn more about image generation prompting in OpenAI's [DALL┬╖E documentation](https://platform.openai.com/docs/guides/images/language-specific-tips).

+## Prompt transformation example

+| **Example text prompt** | **Example generated image without prompt transformation** | **Example generated image with prompt transformation** |

+||||

+|"Watercolor painting of the Seattle skyline" |  |  |

+## Why is prompt transformation needed?

+Prompt transformation is essential for responsible and high-quality generations. Not only does prompt transformation improve the safety of your generated image, but it also enriches your prompt in a more descriptive manner, leading to higher quality and descriptive imagery.

+Default prompt transformation in Azure OpenAI DALL-E 3 contains safety enhancements that steer the model away from generating images of Copyright Studio characters and artwork, public figures, and other harmful content such as sexual, hate and unfairness, violence, and self-harm content.

+## How do I use prompt transformation?

+Prompt transformation is applied by default to all Azure OpenAI DALL-E 3 requests. No extra setup is required to benefit from prompt transformation enhancements.

+Like image generation, prompt transformation is non-deterministic due to the nature of large language models. A single original prompt may lead to many image variants.

+## View prompt transformations

+Your revised or transformed prompt is visible in the API response object as shown here, in the `revised_prompt` field.

+```json

+Input Content:

+{

+ "prompt": "Watercolor painting of the Seattle skyline",

+ "n": 1,

+ "size": "1024x1024"

+}

+

+Output Content:

+{

+ "created": 1720557218,

+ "data": [

+ {

+ "content_filter_results": {

+ ...

+ },

+ "prompt_filter_results": {

+ ...

+ },

+ "revised_prompt": "A soft and vivid watercolor painting capturing the scenic beauty of the Seattle skyline. The painting illustrates a setting sun casting warm hues over the sprawling cityscape, with the Space Needle prominently standing tall against the sky. Imagine the scattered high-rise buildings, a soothing blend of the lush green of the parks with the winding blue water of the Puget Sound, and the snow-covered peak of Mount Rainier in the distance. A play of light and shadow adds depth and dynamism to this multihued urban panorama."

+ }

+}

+```

+> [!NOTE]

+> Azure OpenAI Service does not offer configurability for prompt transformation at this time. To bypass prompt transformation, prepend the following to any request: `I NEED to test how the tool works with extremely simple prompts. DO NOT add any detail, just use it AS-IS:`.

+>

+> While this addition will encourage the revised prompt to be more representative of your original prompt, the system may alter specific details.

+## Next steps

+* [DALL-E quickstart](/azure/ai-services/openai/dall-e-quickstart)

+> [!TIP]

+> For a thorough look at how you can tweak your text prompts to generate different kinds of images, see the [Image prompt engineering guide](/azure/ai-services/openai/concepts/gpt-4-v-prompt-engineering).

+### New Responsible AI default content filtering policy

+The new default content filtering policy `DefaultV2` delivers the latest safety and security mitigations for the GPT model series (text), including:

+- Prompt Shields for jailbreak attacks on user prompts (filter),

+- Protected material detection for text (filter) on model completions

+- Protected material detection for code (annotate) on model completions

+While there are no changes to content filters for existing resources and deployments (default or custom content filtering configurations remain unchanged), new resources and GPT deployments will automatically inherit the new content filtering policy `DefaultV2`. Customers have the option to switch between safety defaults and create custom content filtering configurations.

+Refer to our [Default safety policy documentation](./concepts/default-safety-policies.md) for more information.

+The batch transcription API (and [fast transcription API](./fast-transcription-create.md)) supports multiple formats and codecs, such as:

+> Batch transcription service integrates GStreamer and might accept more formats and codecs without returning errors. We suggest to use lossless formats such as WAV (PCM encoding) and FLAC to ensure best transcription quality.

+ > It might take up to 5 min for the network changes to propagate.

+You need a standard (S0) Speech resource. Free resources (F0) aren't supported.

+}' "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/db474955-ab85-4c6c-ba6e-3bfe63d041ba",

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/5988d691-0893-472c-851e-8e36a0fe7aaf"

+ "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/db474955-ab85-4c6c-ba6e-3bfe63d041ba/files"

+ "lastActionDateTime": "2024-05-21T14:18:06Z",

+ "createdDateTime": "2024-05-21T14:18:06Z",

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/7f4232d5-9873-47a7-a6f7-4a3f00d00dc0",

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/5988d691-0893-472c-851e-8e36a0fe7aaf"

+ "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/7f4232d5-9873-47a7-a6f7-4a3f00d00dc0/files"

+ "lastActionDateTime": "2024-05-21T14:21:59Z",

+ "createdDateTime": "2024-05-21T14:21:59Z",

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/5988d691-0893-472c-851e-8e36a0fe7aaf"

+}' "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions"

+spx batch transcription create --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav;https://crbn.us/whatstheweatherlike.wav --model "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/5988d691-0893-472c-851e-8e36a0fe7aaf"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/e418c4a9-9937-4db7-b2c9-8afbff72d950"

+spx batch transcription create --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav;https://crbn.us/whatstheweatherlike.wav --model "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/e418c4a9-9937-4db7-b2c9-8afbff72d950" --api-version v3.2

+curl -v -X GET "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/YourTranscriptionId" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/637d9333-6559-47a6-b8de-c7d732c1ddf3",

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/aaa321e9-5a4e-4db1-88a2-f251bbe7b555"

+ "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/637d9333-6559-47a6-b8de-c7d732c1ddf3/files"

+ "lastActionDateTime": "2024-05-10T18:39:09Z",

+ "createdDateTime": "2024-05-10T18:39:07Z",

+spx batch transcription status --api-version v3.2 --transcription YourTranscriptionId

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/637d9333-6559-47a6-b8de-c7d732c1ddf3",

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/aaa321e9-5a4e-4db1-88a2-f251bbe7b555"

+ "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/637d9333-6559-47a6-b8de-c7d732c1ddf3/files"

+ "lastActionDateTime": "2024-05-10T18:39:09Z",

+ "createdDateTime": "2024-05-10T18:39:07Z",

+curl -v -X GET "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/YourTranscriptionId/files" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/637d9333-6559-47a6-b8de-c7d732c1ddf3/files/2dd180a1-434e-4368-a1ac-37350700284f",

+ "createdDateTime": "2024-05-10T18:39:09Z",

+ "contentUrl": "YourTranscriptionUrl"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/637d9333-6559-47a6-b8de-c7d732c1ddf3/files/c027c6a9-2436-4303-b64b-e98e3c9fc2e3",

+ "createdDateTime": "2024-05-10T18:39:09Z",

+ "contentUrl": "YourTranscriptionUrl"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/637d9333-6559-47a6-b8de-c7d732c1ddf3/files/faea9a41-c95c-4d91-96ff-e39225def642",

+ "createdDateTime": "2024-05-10T18:39:09Z",

+ "contentUrl": "YourTranscriptionReportUrl"

+spx batch transcription list --api-version v3.2 --files --transcription YourTranscriptionId

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/637d9333-6559-47a6-b8de-c7d732c1ddf3/files/2dd180a1-434e-4368-a1ac-37350700284f",

+ "createdDateTime": "2024-05-10T18:39:09Z",

+ "contentUrl": "YourTranscriptionUrl"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/637d9333-6559-47a6-b8de-c7d732c1ddf3/files/c027c6a9-2436-4303-b64b-e98e3c9fc2e3",

+ "createdDateTime": "2024-05-10T18:39:09Z",

+ "contentUrl": "YourTranscriptionUrl"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/637d9333-6559-47a6-b8de-c7d732c1ddf3/files/faea9a41-c95c-4d91-96ff-e39225def642",

+ "createdDateTime": "2024-05-10T18:39:09Z",

+ "contentUrl": "YourTranscriptionReportUrl"

+|`displayWords`|The timestamps for each word of the transcription. The `displayFormWordLevelTimestampsEnabled` request property must be set to `true`, otherwise this property isn't present.<br/><br/>**Note**: This property is only available with Speech to text REST API version 3.1 and later.|

+|`locale`|The locale identified from the input the audio. The `languageIdentification` request property must be set, otherwise this property isn't present.<br/><br/>**Note**: This property is only available with Speech to text REST API version 3.1 and later.|

+spx csr project create --api-version v3.2 --name "My Project" --description "My Project Description" --language "en-US"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52",

+ "evaluations": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52/evaluations",

+ "datasets": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52/datasets",

+ "models": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52/models",

+ "endpoints": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52/endpoints",

+ "transcriptions": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52/transcriptions"

+ "createdDateTime": "2024-07-14T17:15:55Z",

+} ' "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.2/projects"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52",

+ "evaluations": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52/evaluations",

+ "datasets": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52/datasets",

+ "models": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52/models",

+ "endpoints": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52/endpoints",

+ "transcriptions": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52/transcriptions"

+ "createdDateTime": "2024-07-14T17:15:55Z",

+spx csr endpoint create --api-version v3.2 --project YourProjectId --model YourModelId --name "My Endpoint" --description "My Endpoint Description" --language "en-US"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/endpoints/a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/9e240dc1-3d2d-4ac9-98ec-1be05ba0e9dd"

+ "logs": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/endpoints/a07164e8-22d1-4eb7-aa31-bf6bb1097f37/files/logs",

+ "restInteractive": "https://eastus.stt.speech.microsoft.com/speech/recognition/interactive/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "restConversation": "https://eastus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "restDictation": "https://eastus.stt.speech.microsoft.com/speech/recognition/dictation/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "webSocketInteractive": "wss://eastus.stt.speech.microsoft.com/speech/recognition/interactive/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "webSocketConversation": "wss://eastus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "webSocketDictation": "wss://eastus.stt.speech.microsoft.com/speech/recognition/dictation/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+ "lastActionDateTime": "2024-07-15T16:29:36Z",

+ "createdDateTime": "2024-07-15T16:29:36Z",

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/ae8d1643-53e4-4554-be4c-221dcfb471c5"

+}' "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.2/endpoints"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/endpoints/a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/9e240dc1-3d2d-4ac9-98ec-1be05ba0e9dd"

+ "logs": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/endpoints/a07164e8-22d1-4eb7-aa31-bf6bb1097f37/files/logs",

+ "restInteractive": "https://eastus.stt.speech.microsoft.com/speech/recognition/interactive/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "restConversation": "https://eastus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "restDictation": "https://eastus.stt.speech.microsoft.com/speech/recognition/dictation/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "webSocketInteractive": "wss://eastus.stt.speech.microsoft.com/speech/recognition/interactive/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "webSocketConversation": "wss://eastus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "webSocketDictation": "wss://eastus.stt.speech.microsoft.com/speech/recognition/dictation/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+ "lastActionDateTime": "2024-07-15T16:29:36Z",

+ "createdDateTime": "2024-07-15T16:29:36Z",

+spx csr endpoint update --api-version v3.2 --endpoint YourEndpointId --model YourModelId

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/endpoints/a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/9e240dc1-3d2d-4ac9-98ec-1be05ba0e9dd"

+ "logs": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/endpoints/a07164e8-22d1-4eb7-aa31-bf6bb1097f37/files/logs",

+ "restInteractive": "https://eastus.stt.speech.microsoft.com/speech/recognition/interactive/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "restConversation": "https://eastus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "restDictation": "https://eastus.stt.speech.microsoft.com/speech/recognition/dictation/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "webSocketInteractive": "wss://eastus.stt.speech.microsoft.com/speech/recognition/interactive/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "webSocketConversation": "wss://eastus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "webSocketDictation": "wss://eastus.stt.speech.microsoft.com/speech/recognition/dictation/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+ "lastActionDateTime": "2024-07-15T16:30:12Z",

+ "status": "Succeeded",

+ "createdDateTime": "2024-07-15T16:29:36Z",

+ "description": "My Endpoint Description"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/9e240dc1-3d2d-4ac9-98ec-1be05ba0e9dd"

+ },

+}' "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.2/endpoints/YourEndpointId"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/endpoints/a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/9e240dc1-3d2d-4ac9-98ec-1be05ba0e9dd"

+ "logs": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/endpoints/a07164e8-22d1-4eb7-aa31-bf6bb1097f37/files/logs",

+ "restInteractive": "https://eastus.stt.speech.microsoft.com/speech/recognition/interactive/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "restConversation": "https://eastus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "restDictation": "https://eastus.stt.speech.microsoft.com/speech/recognition/dictation/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "webSocketInteractive": "wss://eastus.stt.speech.microsoft.com/speech/recognition/interactive/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "webSocketConversation": "wss://eastus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "webSocketDictation": "wss://eastus.stt.speech.microsoft.com/speech/recognition/dictation/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+ "lastActionDateTime": "2024-07-15T16:30:12Z",

+ "status": "Succeeded",

+ "createdDateTime": "2024-07-15T16:29:36Z",

+ "description": "My Endpoint Description"

+spx csr endpoint list --api-version v3.2 --endpoint YourEndpointId

+curl -v -X GET "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.2/endpoints/YourEndpointId" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/endpoints/a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/9e240dc1-3d2d-4ac9-98ec-1be05ba0e9dd"

+ "logs": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/endpoints/a07164e8-22d1-4eb7-aa31-bf6bb1097f37/files/logs",

+ "restInteractive": "https://eastus.stt.speech.microsoft.com/speech/recognition/interactive/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "restConversation": "https://eastus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "restDictation": "https://eastus.stt.speech.microsoft.com/speech/recognition/dictation/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "webSocketInteractive": "wss://eastus.stt.speech.microsoft.com/speech/recognition/interactive/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "webSocketConversation": "wss://eastus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37",

+ "webSocketDictation": "wss://eastus.stt.speech.microsoft.com/speech/recognition/dictation/cognitiveservices/v1?cid=a07164e8-22d1-4eb7-aa31-bf6bb1097f37"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+ "lastActionDateTime": "2024-07-15T16:30:12Z",

+ "createdDateTime": "2024-07-15T16:29:36Z",

+ "description": "My Endpoint Description"

+curl -v -X GET "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.2/endpoints/YourEndpointId/files/logs" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"

+spx csr evaluation create --api-version v3.2 --project 0198f569-cc11-4099-a0e8-9d55bc3d0c52 --dataset 23b6554d-21f9-4df1-89cb-f84510ac8d23 --model1 ff43e922-e3e6-4bf0-8473-55c08fd68048 --model2 13fb305e-09ad-4bce-b3a1-938c9124dda3 --name "My Evaluation" --description "My Evaluation Description"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/evaluations/dda6e880-6ccd-49dc-b277-137565cbaa38",

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/datasets/23b6554d-21f9-4df1-89cb-f84510ac8d23"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/b50642a8-febf-43e1-b9d3-e0c90b82a62a"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/b50642a8-febf-43e1-b9d3-e0c90b82a62a"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+ "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/evaluations/dda6e880-6ccd-49dc-b277-137565cbaa38/files"

+ "wordInsertionCount1": -1,

+ "wordErrorRate2": -1.0,

+ "sentenceErrorRate2": -1.0,

+ "sentenceCount2": -1,

+ "wordCount2": -1,

+ "correctWordCount2": -1,

+ "wordSubstitutionCount2": -1,

+ "wordDeletionCount2": -1,

+ "wordInsertionCount2": -1

+ "lastActionDateTime": "2024-07-14T21:31:14Z",

+ "createdDateTime": "2024-07-14T21:31:14Z",

+ "description": "My Evaluation Description",

+ "customProperties": {

+ "testingKind": "Evaluation"

+ }

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/13fb305e-09ad-4bce-b3a1-938c9124dda3"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/datasets/23b6554d-21f9-4df1-89cb-f84510ac8d23"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+}' "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.2/evaluations"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/evaluations/dda6e880-6ccd-49dc-b277-137565cbaa38",

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/datasets/23b6554d-21f9-4df1-89cb-f84510ac8d23"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/b50642a8-febf-43e1-b9d3-e0c90b82a62a"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/b50642a8-febf-43e1-b9d3-e0c90b82a62a"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+ "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/evaluations/dda6e880-6ccd-49dc-b277-137565cbaa38/files"

+ "wordInsertionCount1": -1,

+ "wordErrorRate2": -1.0,

+ "sentenceErrorRate2": -1.0,

+ "sentenceCount2": -1,

+ "wordCount2": -1,

+ "correctWordCount2": -1,

+ "wordSubstitutionCount2": -1,

+ "wordDeletionCount2": -1,

+ "wordInsertionCount2": -1

+ "lastActionDateTime": "2024-07-14T21:31:14Z",

+ "createdDateTime": "2024-07-14T21:31:14Z",

+spx csr evaluation status --api-version v3.2 --evaluation 8bfe6b05-f093-4ab4-be7d-180374b751ca

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/evaluations/dda6e880-6ccd-49dc-b277-137565cbaa38",

+ "model1": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"

+ },

+ "model2": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"

+ },

+ "dataset": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/datasets/23b6554d-21f9-4df1-89cb-f84510ac8d23"

+ },

+ "transcription2": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/b50642a8-febf-43e1-b9d3-e0c90b82a62a"

+ },

+ "transcription1": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/b50642a8-febf-43e1-b9d3-e0c90b82a62a"

+ },

+ "project": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+ },

+ "links": {

+ "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/evaluations/dda6e880-6ccd-49dc-b277-137565cbaa38/files"

+ },

+ "properties": {

+ "wordErrorRate1": 0.028900000000000002,

+ "sentenceErrorRate1": 0.667,

+ "tokenErrorRate1": 0.12119999999999999,

+ "sentenceCount1": 3,

+ "wordCount1": 173,

+ "correctWordCount1": 170,

+ "wordSubstitutionCount1": 2,

+ "wordDeletionCount1": 1,

+ "wordInsertionCount1": 2,

+ "tokenCount1": 165,

+ "correctTokenCount1": 145,

+ "tokenSubstitutionCount1": 10,

+ "tokenDeletionCount1": 1,

+ "tokenInsertionCount1": 9,

+ "tokenErrors1": {

+ "punctuation": {

+ "numberOfEdits": 4,

+ "percentageOfAllEdits": 20.0

+ },

+ "capitalization": {

+ "numberOfEdits": 2,

+ "percentageOfAllEdits": 10.0

+ },

+ "inverseTextNormalization": {

+ "numberOfEdits": 1,

+ "percentageOfAllEdits": 5.0

+ },

+ "lexical": {

+ "numberOfEdits": 12,

+ "percentageOfAllEdits": 12.0

+ },

+ "others": {

+ "numberOfEdits": 1,

+ "percentageOfAllEdits": 5.0

+ }

+ },

+ "wordErrorRate2": 0.028900000000000002,

+ "sentenceErrorRate2": 0.667,

+ "tokenErrorRate2": 0.12119999999999999,

+ "sentenceCount2": 3,

+ "wordCount2": 173,

+ "correctWordCount2": 170,

+ "wordSubstitutionCount2": 2,

+ "wordDeletionCount2": 1,

+ "wordInsertionCount2": 2,

+ "tokenCount2": 165,

+ "correctTokenCount2": 145,

+ "tokenSubstitutionCount2": 10,

+ "tokenDeletionCount2": 1,

+ "tokenInsertionCount2": 9,

+ "tokenErrors2": {

+ "punctuation": {

+ "numberOfEdits": 4,

+ "percentageOfAllEdits": 20.0

+ },

+ "capitalization": {

+ "numberOfEdits": 2,

+ "percentageOfAllEdits": 10.0

+ },

+ "inverseTextNormalization": {

+ "numberOfEdits": 1,

+ "percentageOfAllEdits": 5.0

+ },

+ "lexical": {

+ "numberOfEdits": 12,

+ "percentageOfAllEdits": 12.0

+ },

+ "others": {

+ "numberOfEdits": 1,

+ "percentageOfAllEdits": 5.0

+ }

+ }

+ },

+ "lastActionDateTime": "2024-07-14T21:31:22Z",

+ "status": "Succeeded",

+ "createdDateTime": "2024-07-14T21:31:14Z",

+ "locale": "en-US",

+ "displayName": "My Evaluation",

+ "description": "My Evaluation Description",

+ "customProperties": {

+ "testingKind": "Evaluation"

+ }

+curl -v -X GET "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.2/evaluations/YourEvaluationId" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/evaluations/dda6e880-6ccd-49dc-b277-137565cbaa38",

+ "model1": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"

+ },

+ "model2": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"

+ },

+ "dataset": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/datasets/23b6554d-21f9-4df1-89cb-f84510ac8d23"

+ },

+ "transcription2": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/b50642a8-febf-43e1-b9d3-e0c90b82a62a"

+ },

+ "transcription1": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/b50642a8-febf-43e1-b9d3-e0c90b82a62a"

+ },

+ "project": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+ },

+ "links": {

+ "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/evaluations/dda6e880-6ccd-49dc-b277-137565cbaa38/files"

+ },

+ "properties": {

+ "wordErrorRate1": 0.028900000000000002,

+ "sentenceErrorRate1": 0.667,

+ "tokenErrorRate1": 0.12119999999999999,

+ "sentenceCount1": 3,

+ "wordCount1": 173,

+ "correctWordCount1": 170,

+ "wordSubstitutionCount1": 2,

+ "wordDeletionCount1": 1,

+ "wordInsertionCount1": 2,

+ "tokenCount1": 165,

+ "correctTokenCount1": 145,

+ "tokenSubstitutionCount1": 10,

+ "tokenDeletionCount1": 1,

+ "tokenInsertionCount1": 9,

+ "tokenErrors1": {

+ "punctuation": {

+ "numberOfEdits": 4,

+ "percentageOfAllEdits": 20.0

+ },

+ "capitalization": {

+ "numberOfEdits": 2,

+ "percentageOfAllEdits": 10.0

+ },

+ "inverseTextNormalization": {

+ "numberOfEdits": 1,

+ "percentageOfAllEdits": 5.0

+ },

+ "lexical": {

+ "numberOfEdits": 12,

+ "percentageOfAllEdits": 12.0

+ },

+ "others": {

+ "numberOfEdits": 1,

+ "percentageOfAllEdits": 5.0

+ }

+ },

+ "wordErrorRate2": 0.028900000000000002,

+ "sentenceErrorRate2": 0.667,

+ "tokenErrorRate2": 0.12119999999999999,

+ "sentenceCount2": 3,

+ "wordCount2": 173,

+ "correctWordCount2": 170,

+ "wordSubstitutionCount2": 2,

+ "wordDeletionCount2": 1,

+ "wordInsertionCount2": 2,

+ "tokenCount2": 165,

+ "correctTokenCount2": 145,

+ "tokenSubstitutionCount2": 10,

+ "tokenDeletionCount2": 1,

+ "tokenInsertionCount2": 9,

+ "tokenErrors2": {

+ "punctuation": {

+ "numberOfEdits": 4,

+ "percentageOfAllEdits": 20.0

+ },

+ "capitalization": {

+ "numberOfEdits": 2,

+ "percentageOfAllEdits": 10.0

+ },

+ "inverseTextNormalization": {

+ "numberOfEdits": 1,

+ "percentageOfAllEdits": 5.0

+ },

+ "lexical": {

+ "numberOfEdits": 12,

+ "percentageOfAllEdits": 12.0

+ },

+ "others": {

+ "numberOfEdits": 1,

+ "percentageOfAllEdits": 5.0

+ }

+ }

+ },

+ "lastActionDateTime": "2024-07-14T21:31:22Z",

+ "status": "Succeeded",

+ "createdDateTime": "2024-07-14T21:31:14Z",

+ "locale": "en-US",

+ "displayName": "My Evaluation",

+ "description": "My Evaluation Description",

+ "customProperties": {

+ "testingKind": "Evaluation"

+ }

+Human-labeled transcriptions are word-by-word transcriptions of an audio file. You use human-labeled transcriptions to evaluate model accuracy and to improve recognition accuracy, especially when words are deleted or incorrectly replaced. This guide can help you create high-quality transcriptions.

+A representative sample of transcription data is recommended to evaluate model accuracy. The data should cover various speakers and utterances that are representative of what users say to the application. For test data, the maximum duration of each individual audio file is 2 hours.

+A large sample of transcription data is required to improve recognition. We suggest providing between 1 and 100 hours of audio data. The Speech service uses up to 100 hours of audio for training (up to 20 hours for older models that don't charge for training). Each individual audio file shouldn't be longer than 40 seconds (up to 30 seconds for Whisper customization).

+This guide has sections for US English, Mandarin Chinese, and German locales.

+| "Hello world" | "Hello world" | The opening and closing quotations marks are substituted with appropriate ASCII characters. |

+- Nonalphabetic characters or mixed alphanumeric characters should be transcribed as pronounced.

+spx csr evaluation create --api-version v3.2 --project 0198f569-cc11-4099-a0e8-9d55bc3d0c52 --dataset 23b6554d-21f9-4df1-89cb-f84510ac8d23 --model1 13fb305e-09ad-4bce-b3a1-938c9124dda3 --model2 13fb305e-09ad-4bce-b3a1-938c9124dda3 --name "My Inspection" --description "My Inspection Description"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/evaluations/9c06d5b1-213f-4a16-9069-bc86efacdaac",

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/datasets/23b6554d-21f9-4df1-89cb-f84510ac8d23"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/b50642a8-febf-43e1-b9d3-e0c90b82a62a"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/b50642a8-febf-43e1-b9d3-e0c90b82a62a"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+ "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/evaluations/9c06d5b1-213f-4a16-9069-bc86efacdaac/files"

+ "wordInsertionCount1": -1,

+ "wordErrorRate2": -1.0,

+ "sentenceErrorRate2": -1.0,

+ "sentenceCount2": -1,

+ "wordCount2": -1,

+ "correctWordCount2": -1,

+ "wordSubstitutionCount2": -1,

+ "wordDeletionCount2": -1,

+ "wordInsertionCount2": -1

+ "lastActionDateTime": "2024-07-14T21:21:39Z",

+ "createdDateTime": "2024-07-14T21:21:39Z",

+- Set the required `model1` property to the URI of a model that you want to test.

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/13fb305e-09ad-4bce-b3a1-938c9124dda3"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/datasets/23b6554d-21f9-4df1-89cb-f84510ac8d23"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+}' "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.2/evaluations"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/evaluations/9c06d5b1-213f-4a16-9069-bc86efacdaac",

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/datasets/23b6554d-21f9-4df1-89cb-f84510ac8d23"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/b50642a8-febf-43e1-b9d3-e0c90b82a62a"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/b50642a8-febf-43e1-b9d3-e0c90b82a62a"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+ "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/evaluations/9c06d5b1-213f-4a16-9069-bc86efacdaac/files"

+ "wordInsertionCount1": -1,

+ "wordErrorRate2": -1.0,

+ "sentenceErrorRate2": -1.0,

+ "sentenceCount2": -1,

+ "wordCount2": -1,

+ "correctWordCount2": -1,

+ "wordSubstitutionCount2": -1,

+ "wordDeletionCount2": -1,

+ "wordInsertionCount2": -1

+ "lastActionDateTime": "2024-07-14T21:21:39Z",

+ "createdDateTime": "2024-07-14T21:21:39Z",

+spx csr evaluation status --api-version v3.2 --evaluation 9c06d5b1-213f-4a16-9069-bc86efacdaac

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/evaluations/9c06d5b1-213f-4a16-9069-bc86efacdaac",

+ "model1": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"

+ },

+ "model2": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"

+ },

+ "dataset": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/datasets/23b6554d-21f9-4df1-89cb-f84510ac8d23"

+ },

+ "transcription2": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/b50642a8-febf-43e1-b9d3-e0c90b82a62a"

+ },

+ "transcription1": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/b50642a8-febf-43e1-b9d3-e0c90b82a62a"

+ },

+ "project": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+ },

+ "links": {

+ "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/evaluations/9c06d5b1-213f-4a16-9069-bc86efacdaac/files"

+ },

+ "properties": {

+ "wordErrorRate1": 0.028900000000000002,

+ "sentenceErrorRate1": 0.667,

+ "tokenErrorRate1": 0.12119999999999999,

+ "sentenceCount1": 3,

+ "wordCount1": 173,

+ "correctWordCount1": 170,

+ "wordSubstitutionCount1": 2,

+ "wordDeletionCount1": 1,

+ "wordInsertionCount1": 2,

+ "tokenCount1": 165,

+ "correctTokenCount1": 145,

+ "tokenSubstitutionCount1": 10,

+ "tokenDeletionCount1": 1,

+ "tokenInsertionCount1": 9,

+ "tokenErrors1": {

+ "punctuation": {

+ "numberOfEdits": 4,

+ "percentageOfAllEdits": 20.0

+ },

+ "capitalization": {

+ "numberOfEdits": 2,

+ "percentageOfAllEdits": 10.0

+ },

+ "inverseTextNormalization": {

+ "numberOfEdits": 1,

+ "percentageOfAllEdits": 5.0

+ },

+ "lexical": {

+ "numberOfEdits": 12,

+ "percentageOfAllEdits": 12.0

+ },

+ "others": {

+ "numberOfEdits": 1,

+ "percentageOfAllEdits": 5.0

+ }

+ },

+ "wordErrorRate2": 0.028900000000000002,

+ "sentenceErrorRate2": 0.667,

+ "tokenErrorRate2": 0.12119999999999999,

+ "sentenceCount2": 3,

+ "wordCount2": 173,

+ "correctWordCount2": 170,

+ "wordSubstitutionCount2": 2,

+ "wordDeletionCount2": 1,

+ "wordInsertionCount2": 2,

+ "tokenCount2": 165,

+ "correctTokenCount2": 145,

+ "tokenSubstitutionCount2": 10,

+ "tokenDeletionCount2": 1,

+ "tokenInsertionCount2": 9,

+ "tokenErrors2": {

+ "punctuation": {

+ "numberOfEdits": 4,

+ "percentageOfAllEdits": 20.0

+ },

+ "capitalization": {

+ "numberOfEdits": 2,

+ "percentageOfAllEdits": 10.0

+ },

+ "inverseTextNormalization": {

+ "numberOfEdits": 1,

+ "percentageOfAllEdits": 5.0

+ },

+ "lexical": {

+ "numberOfEdits": 12,

+ "percentageOfAllEdits": 12.0

+ },

+ "others": {

+ "numberOfEdits": 1,

+ "percentageOfAllEdits": 5.0

+ }

+ }

+ },

+ "lastActionDateTime": "2024-07-14T21:22:45Z",

+ "status": "Succeeded",

+ "createdDateTime": "2024-07-14T21:21:39Z",

+ "locale": "en-US",

+ "displayName": "My Inspection",

+ "description": "My Inspection Description"

+curl -v -X GET "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.2/evaluations/YourEvaluationId" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/evaluations/9c06d5b1-213f-4a16-9069-bc86efacdaac",

+ "model1": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"

+ },

+ "model2": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"

+ },

+ "dataset": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/datasets/23b6554d-21f9-4df1-89cb-f84510ac8d23"

+ },

+ "transcription2": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/b50642a8-febf-43e1-b9d3-e0c90b82a62a"

+ },

+ "transcription1": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/b50642a8-febf-43e1-b9d3-e0c90b82a62a"

+ },

+ "project": {

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+ },

+ "links": {

+ "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/evaluations/9c06d5b1-213f-4a16-9069-bc86efacdaac/files"

+ },

+ "properties": {

+ "wordErrorRate1": 0.028900000000000002,

+ "sentenceErrorRate1": 0.667,

+ "tokenErrorRate1": 0.12119999999999999,

+ "sentenceCount1": 3,

+ "wordCount1": 173,

+ "correctWordCount1": 170,

+ "wordSubstitutionCount1": 2,

+ "wordDeletionCount1": 1,

+ "wordInsertionCount1": 2,

+ "tokenCount1": 165,

+ "correctTokenCount1": 145,

+ "tokenSubstitutionCount1": 10,

+ "tokenDeletionCount1": 1,

+ "tokenInsertionCount1": 9,

+ "tokenErrors1": {

+ "punctuation": {

+ "numberOfEdits": 4,

+ "percentageOfAllEdits": 20.0

+ },

+ "capitalization": {

+ "numberOfEdits": 2,

+ "percentageOfAllEdits": 10.0

+ },

+ "inverseTextNormalization": {

+ "numberOfEdits": 1,

+ "percentageOfAllEdits": 5.0

+ },

+ "lexical": {

+ "numberOfEdits": 12,

+ "percentageOfAllEdits": 12.0

+ },

+ "others": {

+ "numberOfEdits": 1,

+ "percentageOfAllEdits": 5.0

+ }

+ },

+ "wordErrorRate2": 0.028900000000000002,

+ "sentenceErrorRate2": 0.667,

+ "tokenErrorRate2": 0.12119999999999999,

+ "sentenceCount2": 3,

+ "wordCount2": 173,

+ "correctWordCount2": 170,

+ "wordSubstitutionCount2": 2,

+ "wordDeletionCount2": 1,

+ "wordInsertionCount2": 2,

+ "tokenCount2": 165,

+ "correctTokenCount2": 145,

+ "tokenSubstitutionCount2": 10,

+ "tokenDeletionCount2": 1,

+ "tokenInsertionCount2": 9,

+ "tokenErrors2": {

+ "punctuation": {

+ "numberOfEdits": 4,

+ "percentageOfAllEdits": 20.0

+ },

+ "capitalization": {

+ "numberOfEdits": 2,

+ "percentageOfAllEdits": 10.0

+ },

+ "inverseTextNormalization": {

+ "numberOfEdits": 1,

+ "percentageOfAllEdits": 5.0

+ },

+ "lexical": {

+ "numberOfEdits": 12,

+ "percentageOfAllEdits": 12.0

+ },

+ "others": {

+ "numberOfEdits": 1,

+ "percentageOfAllEdits": 5.0

+ }

+ }

+ },

+ "lastActionDateTime": "2024-07-14T21:22:45Z",

+ "status": "Succeeded",

+ "createdDateTime": "2024-07-14T21:21:39Z",

+ "locale": "en-US",

+ "displayName": "My Inspection",

+ "description": "My Inspection Description"

+| [Audio only](#audio-data-for-training-or-testing) | Yes (visual inspection) | 5+ audio files | Yes (Preview for `en-US`) | 1-100 hours of audio |

+| [Audio + human-labeled transcripts](#audio--human-labeled-transcript-data-for-training-or-testing) | Yes (evaluation of accuracy) | 0.5-5 hours of audio | Yes | 1-100 hours of audio |

+If you train a custom model with audio data, choose a Speech resource region with dedicated hardware for training audio data. For more information, see footnotes in the [regions](regions.md#speech-service) table. In regions with dedicated hardware for custom speech training, the Speech service uses up to 100 hours of your audio training data, and can process about 10 hours of data per day. After the model is trained, you can copy the model to another region as needed with the [Models_CopyTo](/rest/api/speechtotext/models/copy-to) REST API.

+A large training dataset is required to improve recognition. Generally, we recommend that you provide word-by-word transcriptions for 1 to 100 hours of audio (up to 20 hours for older models that do not charge for training). However, even as little as 30 minutes can help improve recognition results. Although creating human-labeled transcription can take time, improvements in recognition are only as good as the data that you provide. You should upload only high-quality transcripts.

+| Maximum length per audio | Two hours (testing) / 40 s (training)<br/><br/>Training with audio has a maximum audio length of 40 seconds per file (up to 30 seconds for Whisper customization). For audio files longer than 40 seconds, only the corresponding text from the transcription files is used for training. If all audio files are longer than 40 seconds, the training fails.|

+> In regions with dedicated hardware for custom speech training, the Speech service will use up to 100 hours of your audio training data, and can process about 10 hours of data per day. See footnotes in the [regions](regions.md#speech-service) table for more information.

+- Optionally, you can set the `base` property. For example: `--base 5988d691-0893-472c-851e-8e36a0fe7aaf`. If you don't specify the `base`, the default base model for the locale is used. The Speech CLI `base` parameter corresponds to the `baseModel` property in the JSON request and response.

+spx csr model create --api-version v3.2 --project YourProjectId --name "My Model" --description "My Model Description" --dataset YourDatasetId --language "en-US"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/9e240dc1-3d2d-4ac9-98ec-1be05ba0e9dd",

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/5988d691-0893-472c-851e-8e36a0fe7aaf"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/datasets/23b6554d-21f9-4df1-89cb-f84510ac8d23"

+ "manifest": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/9e240dc1-3d2d-4ac9-98ec-1be05ba0e9dd/manifest",

+ "copy": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/9e240dc1-3d2d-4ac9-98ec-1be05ba0e9dd:copy",

+ "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/9e240dc1-3d2d-4ac9-98ec-1be05ba0e9dd/files"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+ "transcriptionDateTime": "2026-07-15T00:00:00Z"

+ },

+ "customModelWeightPercent": 30,

+ "features": {

+ "supportsTranscriptions": true,

+ "supportsEndpoints": true,

+ "supportsTranscriptionsOnSpeechContainers": false,

+ "supportedOutputFormats": [

+ "Display",

+ "Lexical"

+ ]

+ "lastActionDateTime": "2024-07-14T21:38:40Z",

+ "status": "Running",

+ "createdDateTime": "2024-07-14T21:38:40Z",

+- Optionally, you can set the `baseModel` property. For example: `"baseModel": {"self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/5988d691-0893-472c-851e-8e36a0fe7aaf"}`. If you don't specify the `baseModel`, the default base model for the locale is used.

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/datasets/23b6554d-21f9-4df1-89cb-f84510ac8d23"

+}' "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.2/models"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/9e240dc1-3d2d-4ac9-98ec-1be05ba0e9dd",

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/5988d691-0893-472c-851e-8e36a0fe7aaf"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/datasets/23b6554d-21f9-4df1-89cb-f84510ac8d23"

+ "manifest": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/9e240dc1-3d2d-4ac9-98ec-1be05ba0e9dd/manifest",

+ "copy": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/9e240dc1-3d2d-4ac9-98ec-1be05ba0e9dd:copy",

+ "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/9e240dc1-3d2d-4ac9-98ec-1be05ba0e9dd/files"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+ "transcriptionDateTime": "2026-07-15T00:00:00Z"

+ },

+ "customModelWeightPercent": 30,

+ "features": {

+ "supportsTranscriptions": true,

+ "supportsEndpoints": true,

+ "supportsTranscriptionsOnSpeechContainers": false,

+ "supportedOutputFormats": [

+ "Display",

+ "Lexical"

+ ]

+ "lastActionDateTime": "2024-07-14T21:38:40Z",

+ "status": "Running",

+ "createdDateTime": "2024-07-14T21:38:40Z",

+To copy a model to another Speech resource, use the [Models_Copy](/rest/api/speechtotext/models/copy) operation of the [Speech to text REST API](rest-speech-to-text.md). Construct the request body according to the following instructions:

+} ' "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.2/models/YourModelId:copy"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/9df35ddb-edf9-4e91-8d1a-576d09aabdae",

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/eb5450a7-3ca2-461a-b2d7-ddbb3ad96540"

+ "manifest": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/9df35ddb-edf9-4e91-8d1a-576d09aabdae/manifest",

+ "copy": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/9df35ddb-edf9-4e91-8d1a-576d09aabdae:copy"

+spx csr model update --api-version v3.2 --model YourModelId --project YourProjectId

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+Make an HTTP PATCH request using the URI as shown in the following example. Use the URI of the new model. You can get the new model ID from the `self` property of the [Models_Copy](/rest/api/speechtotext/models/copy) response body. Replace `YourSubscriptionKey` with your Speech resource key, replace `YourServiceRegion` with your Speech resource region, and set the request body properties as previously described.

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+}' "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.2/models"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+- Set the required `kind` parameter. The possible set of values for a training dataset kind are: Acoustic, AudioFiles, Language, LanguageMarkdown, and Pronunciation.

+spx csr dataset create --api-version v3.2 --kind "Acoustic" --name "My Acoustic Dataset" --description "My Acoustic Dataset Description" --project YourProjectId --content YourContentUrl --language "en-US"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/datasets/23b6554d-21f9-4df1-89cb-f84510ac8d23",

+ "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/datasets/23b6554d-21f9-4df1-89cb-f84510ac8d23/files"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+ "textNormalizationKind": "Default",

+ "acceptedLineCount": 2,

+ "rejectedLineCount": 0,

+ "duration": "PT59S"

+ "lastActionDateTime": "2024-07-14T17:36:30Z",

+ "status": "Succeeded",

+ "createdDateTime": "2024-07-14T17:36:14Z",

+ "description": "My Acoustic Dataset Description",

+ "customProperties": {

+ "PortalAPIVersion": "3"

+ }

+- Set the required `kind` property. The possible set of values for a training dataset kind are: Acoustic, AudioFiles, Language, LanguageMarkdown, and Pronunciation.

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+}' "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.2/datasets"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/datasets/23b6554d-21f9-4df1-89cb-f84510ac8d23",

+ "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/datasets/23b6554d-21f9-4df1-89cb-f84510ac8d23/files"

+ "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/projects/0198f569-cc11-4099-a0e8-9d55bc3d0c52"

+ "textNormalizationKind": "Default",

+ "acceptedLineCount": 2,

+ "rejectedLineCount": 0,

+ "duration": "PT59S"

+ "lastActionDateTime": "2024-07-14T17:36:30Z",

+ "status": "Succeeded",

+ "createdDateTime": "2024-07-14T17:36:14Z",

+ "description": "My Acoustic Dataset Description",

+ "customProperties": {

+ "PortalAPIVersion": "3"

+ }

+¹ The region has dedicated hardware for custom speech training. If you plan to train a custom model with audio data, you must use one of the regions with dedicated hardware. Then you can [copy the trained model](how-to-custom-speech-train-model.md#copy-a-model) to another region.

+* Ensure that the proxy allows connections to AML APIs, such as "*.\<region\>.api.azureml.ms" and "*.instances.azureml.ms"

+Explore our [samples](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/ai/azure-ai-inference/samples) and read the [API reference documentation](https://aka.ms/azsdk/azure-ai-inference/python/reference) to get yourself started.

+Explore our [samples](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/ai/ai-inference-rest/samples) and read the [API reference documentation](https://aka.ms/AAp1kxa) to get yourself started.

+> When using Azure AI Inference SDK, using `model_extras` configures the request with `extra-parameters: pass-through` automatically for you.

+import json

+from azure.core.exceptions import HttpResponseError

+ az identity create --resource-group <resource-group> --name <identity-name>

+## Create an Azure Service Bus

+## Consume messages from Azure Service Bus

+Now that we have published messages to the Azure Service Bus queue, we will deploy a ScaledJob to consume the messages. This ScaledJob will use the KEDA TriggerAuthentication resource to authenticate against the Azure Service Bus queue using the workload identity and scale out every 10 messages.

+## Clean up resources

+After you verify that the deployment is successful, you can clean up the resources to avoid incurring Azure costs.

+1. Delete the Azure resource group and all resources in it using the [`az group delete`][az-group-delete] command.

+ ```azurecli-interactive

+ az group delete --name $RG_NAME --yes --no-wait

+ ```

+For information on KEDA troubleshooting, see [Troubleshoot the Kubernetes Event-driven Autoscaling (KEDA) add-on][keda-troubleshoot].

+ ```bash

+1. With the pod deployed, run the following command and verify the *hello-apparmor* pod shows a *Running* status:

+ ```bash

+

+* [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) - to generate OpenAPI specification files from API code

+## Generate OpenAPI specification file from API code

+

+Use the power of GitHub Copilot with the Azure API Center extension for Visual Studio Code to create an OpenAPI specification file from your API code. Right click on the API code, select **Copilot** from the options, and select **Generate API documentation**. This will create an OpenAPI specification file.

+After generating the OpenAPI specification file and checking for accuracy, you can register the API with your API center using the **Azure API Center: Register API** command.

+ > [!TIP]

+ > You can also use the extension to generate API documentation in Markdown, a format that's easy to maintain and share with end users. Right-click on the definition, and select **Generate Markdown**.

+### Why do some customers see performance differences after migrating?

+App Service Environment v3 uses newer virtual machines that are based on virtual CPUs (vCPU), not physical cores. One vCPU typically doesn't equate to one physical core in terms of raw CPU performance. As a result, CPU-bound workloads might see a performance difference if attempting to match old-school physical core counts to current vCPU counts.

+When migrating to App Service Environment v3, we map App Service plan tiers as follows:

+|App Service Environment v2 SKU|App Service Environment v3 SKU|

+|||

+|I1 |I1v2 |

+|I2 |I2v2 |

+|I3 |I3v2 |

+|CPU|Physical cores|Physical cores|Virtual CPu (vCPU)|

+> [!NOTE]

+> This article is for Visual Studio 2019. For troubleshooting in Visual Studio 2022, see [Remote Debug ASP.NET Core on Azure App Service.](/visualstudio/debugger/remote-debugging-azure-app-service)

+>

+- Use the video guide for [Migrate Application Gateway from v1 to v2](https://learn.microsoft.com/_themes/docs.theme/master/en-us/_themes/global/video-embed.html?id=7ed01e33-80a9-4daa-9322-e771f963a2fe) to understand the migration steps.

+## Version 1.44 - July 2024

+- Fixed a bug where the service would sometimes reject reports from an upgraded extension if the previous extension was in a failed state.

+- Setting OPENSSL_CNF environment at process level to override build openssl.cnf path on Windows.

+- Fixed access denied errors in writing configuration files.

+- Fixed SYMBIOS GUID related bug with Windows Server 2012 and Windows Server 2012 R2 [Extended Security Updates](/windows-server/get-started/extended-security-updates-overview) enabled by Azure Arc.

+### New features

+- Extension service enhancements: Added download/validation error details to extension report. Increased unzipped extension package size limit to 1 GB.

+- Update of hardwareprofile information to support upcoming Windows Server licensing capabilities.

+- Update of the error json output to include more detailed recommended actions for troubleshooting scenarios.

+- Block on installation of unsupported operating systems and distribution versions. See [Supported operating systems](prerequisites.md#supported-operating-systems) for details.

+> [!NOTE]

+> Azure Connected Machine agent version 1.44 is the last version to officially support Debian 10, Ubuntu 16.04, and Azure Linux (CBL-Mariner) 1.0.

+>

+## Version 1.43 - June 2024

+Download for [Windows](https://download.microsoft.com/download/0/7/8/078f3bb7-6a42-41f7-b9d3-9a0eb4c94df8/AzureConnectedMachineAgent.msi) or [Linux](manage-agent.md#installing-a-specific-version-of-the-agent)

+### Fixed

+> [!NOTE]

+> [Azure Connected Machine agent version 1.44](agent-release-notes.md#version-144july-2024) is the last version to officially support Debian 10, Ubuntu 16.04, and Azure Linux (CBL-Mariner) 1.0.

+>

+- Stateful alerts fire when the rule conditions are met, and will not fire again or trigger any more actions until the conditions are resolved.

+Each alert rule is evaluated individually. There is no validation to check if there is another alert configured for the same conditions. If there is more than one alert rule configured for the same conditions, each of those alerts will fire when the conditions are met.

+See [service limits](/azure/azure-monitor/service-limits#alerts) for alerts limitations, including limitations for stateful log alerts.

+We recommend configuring remote-write directly in your self-managed Prometheus config running in your environment. The Azure Monitor side car container can be used in case your preferred authentication is not supported through directly configuration.

+| Cluster Managers (Operator Nexus)| [NCMClusterOperationsLogs](/azure/azure-monitor/reference/tables/NCMClusterOperationsLogs) |

+| Nexus Storage Appliances | [NCSStorageLogs](/azure/azure-monitor/reference/tables/NCSStorageLogs)<br>[NCSStorageAlerts](/azure/azure-monitor/reference/tables/NCSStorageAlerts)<br>[NCSStorageAudits](/azure/azure-monitor/reference/tables/NCSStorageAudits) |

+| Run a search job | `Microsoft.OperationalInsights/workspaces/tables/write` and `Microsoft.OperationalInsights/workspaces/searchJobs/write` permissions to the Log Analytics workspace, for example, as provided by the [Log Analytics Contributor built-in role](../logs/manage-access.md#built-in-roles). |

+* [Restoring data from Archived Logs](restore.md) for a specific time range.<br/>

+* Querying Basic Logs directly and paying for each query.<br/>

+| Column | Value |

+|:--|:--|

+| _OriginalType | *Type* value from source table. |

+| _OriginalItemId | *_ItemID* value from source table. |

+| TimeGenerated | Time at which the search job ran. |

+| Name | Type | Description |

+| - | - | - |

+| properties.searchResults.query | string | Log query written in KQL to retrieve data. |

+| properties.searchResults.limit | integer | Maximum number of records in the result set, up to one million records. (Optional) |

+| properties.searchResults.startSearchTime | string | Start of the time range to search. |

+| properties.searchResults.endSearchTime | string | End of the time range to search. |

+**Example**

+### [PowerShell](#tab/powershell-1)

+To run a search job, run the [New-AzOperationalInsightsSearchTable](/powershell/module/az.operationalinsights/new-azoperationalinsightssearchtable) command. The name of the results table, which you set using the `TableName` parameter, must end with *_SRCH*.

+**Example**

+```powershell

+New-AzOperationalInsightsSearchTable -ResourceGroupName ContosoRG -WorkspaceName ContosoWorkspace -TableName HeartbeatByIp_SRCH -SearchQuery "Heartbeat" -StartSearchTime "01-01-2022 00:00:00" -EndSearchTime "01-01-2022 00:00:00"

+```

+1. From the **Log Analytics workspace** menu, select **Logs**.

+**Table status**

+| Status | Description |

+|:--|:--|

+| Updating | Populating the table and its schema. |

+| Succeeded | Search job completed. |

+| Deleting | Deleting the search job table. |

+**Example**

+### [PowerShell](#tab/powershell-2)

+To check the status and details of a search job table, run the [Get-AzOperationalInsightsTable](/powershell/module/az.operationalinsights/get-azoperationalinsightstable) command.

+**Example**

+```powershell

+Get-AzOperationalInsightsTable -ResourceGroupName "ContosoRG" -WorkspaceName "ContosoWorkspace" -tableName "HeartbeatByIp_SRCH"

+```

+> [!NOTE]

+> When "-TableName" is not provided, the command will instead list all tables associated with a workspace.

+* Optimized to query one table at a time.

+* Search date range is up to one year.

+* Supports long running searches up to a 24-hour time-out.

+* Results are limited to one million records in the record set.

+* Concurrent execution is limited to five search jobs per workspace.

+* Limited to 100 search results tables per workspace.

+* Limited to 100 search job executions per day per workspace.

+* [where](/azure/data-explorer/kusto/query/whereoperator)

+* [extend](/azure/data-explorer/kusto/query/extendoperator)

+* [project](/azure/data-explorer/kusto/query/projectoperator)

+* [project-away](/azure/data-explorer/kusto/query/projectawayoperator)

+* [project-keep](/azure/data-explorer/kusto/query/project-keep-operator)

+* [project-rename](/azure/data-explorer/kusto/query/projectrenameoperator)

+* [project-reorder](/azure/data-explorer/kusto/query/projectreorderoperator)

+* [parse](/azure/data-explorer/kusto/query/parse-operator)

+* [parse-where](/azure/data-explorer/kusto/query/parse-where-operator)

+* Search job execution - the amount of data the search job scans.

+* Search job results - the amount of data the search job finds and is ingested into the results table, based on the regular log data ingestion prices.

+- Each inode uses roughly 288 bytes of capacity in the volume. Having many inodes in a volume can consume a non-trivial amount of physical space overhead on top of the capacity of the actual data.

+ - If a file is less than 64 bytes in size, it's stored in the inode itself and doesn't use additional capacity. This capacity is only used when files are actually allocated to the volume.

+ - Files larger than 64 bytes do consume additional capacity on the volume. For instance, if there are one million files greater than 64 bytes in an Azure NetApp Files volume, then approximately 274 MiB of capacity would belong to the inodes.

+* US Gov Arizona

+* US Gov Texas

+* US Gov Virginia

+## About 64-bit file IDs

+Whereas regular volume use 32-bit file IDs, large volumes employ 64-bit file IDs. File IDs are unique identifiers that allow Azure NetApp Files to keep track of files in the file system. 64-bit IDs are utilized to increase the number of files allowed in a single volume, enabling a large volume able to hold more files than a regular volume.

+* Ensure that the network latency is less than 10 ms RTT between Azure NetApp Files and AD DS domain controllers.

+For more information on Microsoft Active Directory requirements for network latency over a WAN, see

+[Creating a Site Design](/windows-server/identity/ad-ds/plan/creating-a-site-design).

+| Service | Ports | Protocols |

+| ICMPv4 (ping) | N/A | Echo Reply |

+| DNS* | 53 | TCP, UDP |

+| Kerberos | 88 | TCP, UDP |

+| NetBIOS Datagram Service | 138 | UDP |

+| NetBIOS | 139 | UDP |

+| LDAP** | 389 | TCP, UDP |

+| SAM/LSA/SMB | 445 | TCP, UDP |

+| Kerberos (kpasswd) | 464 | TCP, UDP |

+| Active Directory Global Catalog | 3268 | TCP |

+| Active Directory Secure Global Catalog | 3269 | TCP |

+| Active Directory Web Service | 9389 | TCP |

+\* Active Directory DNS only

+\*\* LDAP over SSL (port 636) isn't currently supported. Instead, use [LDAP over StartTLS](configure-ldap-over-tls.md) (port 389) to encrypt LDAP traffic.

+## July 2024

+* [Azure NetApp Files backup](backup-introduction.md) is now available in Azure [US Gov regions](backup-introduction.md#supported-regions).

+description: Error/warning - Expected a value of type <data-type> but the provided value is of type <data-type>.

+# Bicep error/warning code - BCP033

+This error/warning occurs when you assign a value of a mismatched data type.

+## Error/warning description

+`Expected a value of type <data-type> but the provided value is of type <data-type>.`

+For more information about Bicep error and warning codes, see [Bicep warnings and errors](./bicep-error-codes.md).

+description: Error/warning - The specified <data-type> declaration is missing the following required properties <property-name>.

+# Bicep error/warning code - BCP035

+This error/warning occurs when your resource definition is missing a required property.

+## Error/warning description

+`The specified <date-type> declaration is missing the following required properties: <property-name>.`

+You can fix the issue by adding the missing properties:

+For more information about Bicep error and warning codes, see [Bicep warnings and errors](./bicep-error-codes.md).

+ Title: BCP036

+description: Error/warning - The property <property-name> expected a value of type <data-type> but the provided value is of type <data-type>.

+# Bicep error/warning code - BCP036

+This error/warning occurs when you assign a value to a property whose expected data type is not compatible with that of the assigned value.

+## Error/warning description

+`The property <property-name> expected a value of type <data-type> but the provided value is of type <data-type>.`

+## Solution

+Assign a value with the correct data type.

+## Examples

+The following example raises the error because `sku` is defined as a string, not an integer:

+```bicep

+type storageAccountConfigType = {

+ name: string

+ sku: string

+}

+param foo storageAccountConfigType = {

+ name: 'myStorage'

+ sku: 2

+}

+```

+You can fix the issue by assigning a string value to `sku`:

+```bicep

+type storageAccountConfigType = {

+ name: string

+ sku: string

+}

+param foo storageAccountConfigType = {

+ name: 'myStorage'

+ sku: 'Standard_LRS'

+}

+```

+## Next steps

+For more information about Bicep error and warning codes, see [Bicep warnings and errors](./bicep-error-codes.md).

+ Title: BCP037

+description: Warning - The property <property-name> is not allowed on objects of type <type-definition>.

+# Bicep warning code - BCP037

+This warning occurs when you specify a property that isn't defined in a resource type.

+## Warning description

+`The property <property-name> is not allowed on objects of type <type-defintion>.`

+## Solution

+Remove the undefined property.

+## Examples

+The following example raises the warning because `bar` isn't defined in `storageAccountType`:

+```bicep

+type storageAccountConfigType = {

+ name: string

+ sku: string

+}

+param foo storageAccountConfigType = {

+ name: 'myStorage'

+ sku: 'Standard_LRS'

+ bar: 'myBar'

+}

+```

+You can fix the issue by removing the property:

+```bicep

+type storageAccountConfigType = {

+ name: string

+ sku: string

+}

+param foo storageAccountConfigType = {

+ name: 'myStorage'

+ sku: 'Standard_LRS'

+}

+```

+The following example raises the error because `obj` is a sealed type and doesn't define a `baz` property.

+```bicep

+@sealed()

+type obj = {

+ foo: string

+ bar: string

+}

+param p obj = {

+ foo: 'foo'

+ bar: 'bar'

+ baz: 'baz'

+}

+```

+You can fix the issue by removing the property:

+```bicep

+@sealed()

+type obj = {

+ foo: string

+ bar: string

+}

+param p obj = {

+ foo: 'foo'

+ bar: 'bar'

+}

+```

+## Next steps

+For more information about Bicep error and warning codes, see [Bicep warnings and errors](./bicep-error-codes.md).

+ Title: BCP040

+description: Error/warning - String interpolation is not supported for keys on objects of type <type-definition>.

+# Bicep error/warning code - BCP040

+This error/warning occurs when the Bicep compiler cannot determine the exact value of an interpolated string key.

+## Error/warning description

+`String interpolation is not supported for keys on objects of type <type-definition>.`

+## Solution

+Remove string interpolation.

+## Examples

+The following example raises the warning because string interpolation is used for specifying the key `sku1`:

+```bicep

+var name = 'sku'

+type storageAccountConfigType = {

+ name: string

+ sku1: string

+}

+param foo storageAccountConfigType = {

+ name: 'myStorage'

+ '${name}1': 'Standard_LRS'

+}

+```

+You can fix the issue by adding the missing properties:

+```bicep

+var name = 'sku'

+type storageAccountConfigType = {

+ name: string

+ sku1: string

+}

+param foo storageAccountConfigType = {

+ name: 'myStorage'

+ sku1: 'Standard_LRS'

+}

+```

+## Next steps

+For more information about Bicep error and warning codes, see [Bicep warnings and errors](./bicep-error-codes.md).

+ Title: BCP053

+description: Error/warning - The type <resource-type> does not contain property <property-name>. Available properties include <property-names>.

+# Bicep error/warning code - BCP053

+This error/warning occurs when you reference a property that is not defined in the resource type or [user-defined data type](./user-defined-data-types.md).

+## Error/warning description

+`The type <resource-type> does not contain property <property-name>. Available properties include <property-names>.`

+## Solution

+Reference the correct property name

+## Examples

+The following example raises the error because `Microsoft.Storage/storageAccounts` doesn't contain a property called `bar`.

+```bicep

+param location string

+resource storage 'Microsoft.Storage/storageAccounts@2023-04-01' = {

+ name: 'myStorage'

+ location: location

+ sku: {

+ name: 'Standard_LRS'

+ }

+ kind: 'StorageV2'

+}

+output foo string = storage.bar

+```

+You can fix the error by referencing a valid property, such as `name`:

+```bicep

+param location string

+resource storage 'Microsoft.Storage/storageAccounts@2023-04-01' = {

+ name: 'myStorage'

+ location: location

+ sku: {

+ name: 'Standard_LRS'

+ }

+ kind: 'StorageV2'

+}

+output foo string = storage.name

+```

+## Next steps

+For more information about Bicep error and warning codes, see [Bicep warnings and errors](./bicep-error-codes.md).

+# Bicep error code - BCP072

+For more information about Bicep error and warning codes, see [Bicep warnings and errors](./bicep-error-codes.md).

+ Title: BCP073

+description: Warning - The property <property-name> is read-only. Expressions cannot be assigned to read-only properties.

+# Bicep warning code - BCP073

+This warning occurs when you assign a value to a read-only property.

+## Warning description

+`The property <property-name> is read-only. Expressions cannot be assigned to read-only properties.`

+## Solution

+Remove the property assignment from the file.

+## Examples

+The following example raises the warning because `sku` can only be set on the `storageAccounts` level. It is read-only for services that are under a storage account like `blobServices` and `fileServices`.

+```bicep

+param location string

+resource storage 'Microsoft.Storage/storageAccounts@2023-04-01' = {

+ name: 'mystore'

+ location: location

+ sku: {

+ name: 'Standard_LRS'

+ }

+ kind: 'StorageV2'

+}

+resource blobService 'Microsoft.Storage/storageAccounts/blobServices@2023-04-01' = {

+ parent: storage

+ name: 'default'

+ sku: {}

+}

+```

+You can fix the issue by removing the `sku` property assignment:

+```bicep

+param location string

+resource storage 'Microsoft.Storage/storageAccounts@2023-04-01' = {

+ name: 'mystore'

+ location: location

+ sku: {

+ name: 'Standard_LRS'

+ }

+ kind: 'StorageV2'

+}

+resource blobService 'Microsoft.Storage/storageAccounts/blobServices@2023-04-01' = {

+ parent: storage

+ name: 'default'

+}

+```

+## Next steps

+For more information about Bicep error and warning codes, see [Bicep warnings and errors](./bicep-error-codes.md).

+ Title: BCP327

+description: Error/warning - The provided value (which will always be greater than or equal to <value>) is too large to assign to a target for which the maximum allowable value is <max-value>.

+# Bicep error/warning code - BCP327

+This error/warning occurs when you assign a value that is greater than the allowable value.

+## Error/warning description

+`The provided value (which will always be greater than or equal to <value>) is too large to assign to a target for which the maximum allowable value is <max-value>.`

+## Solution

+Assign a value that falls within the permitted range.

+## Examples

+The following example raises the error because `13` is greater than maximum allowable value:

+```bicep

+@minValue(1)

+@maxValue(12)

+param month int = 13

+```

+You can fix the error by assigning a value within the permitted range:

+```bicep

+@minValue(1)

+@maxValue(12)

+param month int = 12

+```

+## Next steps

+For more information about Bicep error and warning codes, see [Bicep warnings and errors](./bicep-error-codes.md).

+ Title: BCP328

+description: Error/warning - The provided value (which will always be less than or equal to <value>) is too small to assign to a target for which the minimum allowable value is <min-value>.

+# Bicep error/warning code - BCP328

+This error/warning occurs when you assign a value that is less than the allowable value.

+## Error/warning description

+`The provided value (which will always be less than or equal to <value>) is too small to assign to a target for which the minimum allowable value is <min-value>.`

+## Solution

+Assign a value that falls within the permitted range.

+## Examples

+The following example raises the error because `0` is less than minimum allowable value:

+```bicep

+@minValue(1)

+@maxValue(12)

+param month int = 0

+```

+You can fix the error by assigning a value within the permitted range:

+```bicep

+@minValue(1)

+@maxValue(12)

+param month int = 1

+```

+## Next steps

+For more information about Bicep error and warning codes, see [Bicep warnings and errors](./bicep-error-codes.md).

+ Title: BCP332

+description: Error/warning - The provided value (whose length will always be greater than or equal to <length>) is too long to assign to a target for which the maximum allowable length is <max-length>.

+# Bicep error/warning code - BCP332

+This error/warning occurs when a string or array exceeding the allowable length is assigned.

+## Error/warning description

+`The provided value (whose length will always be greater than or equal to <length>) is too long to assign to a target for which the maximum allowable length is <max-length>.`

+## Solution

+Assign a string whose length is within the allowable range.

+## Examples

+The following example raises the error because the value `longerThan10` exceeds the allowable length:

+```bicep

+@minLength(3)

+@maxLength(10)

+param storageAccountName string = 'longerThan10'

+```

+You can fix the error by assigning a string whose length is within the allowable range.

+```bicep

+@minLength(3)

+@maxLength(10)

+param storageAccountName string = 'myStorage'

+```

+## Next steps

+For more information about Bicep error and warning codes, see [Bicep warnings and errors](./bicep-error-codes.md).

+ Title: BCP333

+description: Error/warning - The provided value (whose length will always be less than or equal to <length>) is too short to assign to a target for which the minimum allowable length is <min-length>.

+# Bicep error/warning code - BCP333

+This error/warning occurs when an assigned string or array is shorter than the allowable length.

+## Error/warning description

+`The provided value (whose length will always be less than or equal to <length>) is too short to assign to a target for which the minimum allowable length is <min-length>.`

+## Solution

+Assign a string whose length is within the allowable range.

+## Examples

+The following example raises the error because the value `st` is shorter than the allowable length:

+```bicep

+@minLength(3)

+@maxLength(10)

+param storageAccountName string = 'st'

+```

+You can fix the error by assigning a string whose length is within the allowable range.

+```bicep

+@minLength(3)

+@maxLength(10)

+param storageAccountName string = 'myStorage'

+```

+## Next steps

+For more information about Bicep error and warning codes, see [Bicep warnings and errors](./bicep-error-codes.md).

+| [BCP033](./bicep-error-bcp033.md) | Expected a value of type &lt;data-type> but the provided value is of type &lt;data-type>. |

+| [BCP035](./bicep-error-bcp035.md) | The specified &lt;data-type> declaration is missing the following required properties: &lt;property-name>. |

+| [BCP036](./bicep-error-bcp036.md) | The property &lt;property-name> expected a value of type &lt;data-type> but the provided value is of type &lt;data-type>. |

+| [BCP037](./bicep-error-bcp037.md) | The property &lt;property-name> is not allowed on objects of type &lt;type-definition>. |

+| [BCP040](./bicep-error-bcp040.md) | String interpolation is not supported for keys on objects of type &lt;type-definition>. |

+| [BCP073](./bicep-error-bcp073.md) | The property &lt;property-name> is read-only. Expressions cannot be assigned to read-only properties. |

+| [BCP327](./bicep-error-bcp327.md) | The provided value (which will always be greater than or equal to &lt;value>) is too large to assign to a target for which the maximum allowable value is &lt;max-value>. |

+| [BCP328](./bicep-error-bcp328.md) | The provided value (which will always be less than or equal to &lt;value>) is too small to assign to a target for which the minimum allowable value is &lt;max-value>. |

+| [BCP332](./bicep-error-bcp332.md) | The provided value (whose length will always be greater than or equal to &lt;string-length>) is too long to assign to a target for which the maximum allowable length is &lt;max-length>. |

+| [BCP333](./bicep-error-bcp333.md) | The provided value (whose length will always be less than or equal to &lt;string-length>) is too short to assign to a target for which the minimum allowable length is &lt;min-length>. |

+> | actionGroups | resource group | 1-260 | Can't use:<br>`:<>+/&%\?|` or control characters <br><br>Can't end with space or period. |

+> | autoScaleSettings | resource group | 1-260 | Can't use:<br>`:<>+/&%\?|` or control characters <br><br>Can't end with space or period. |

+> | scheduledQueryRules | resource group | 1-260 | Can't use:<br>`*<>%{}&:\\?/#|` or control characters <br><br>Can't end with space or period. |

+> | metricAlerts | resource group | 1-260 | Can't use:<br>`*#&+:<>?@%{}\/|` or control characters <br><br>Can't end with space or period. |

+> | activityLogAlerts | resource group | 1-260 | Can't use:<br>`<>*%{}&:\\?+/#|` or control characters <br><br>Can't end with space or period. |

+1. Find the resource provider you want to register.

+ :::image type="content" source="./media/resource-providers-and-types/find-resource-providers.png" alt-text="Screenshot of finding resource providers in the Azure portal.":::

+1. Select the resource provider to see the details of the resource provider.

+ :::image type="content" source="./media/resource-providers-and-types/show-resource-provider-details.png" alt-text="Screenshot of Resource provider details in the Azure portal.":::

+1. Select the resource provider, and select **Register**. To maintain least privileges in your subscription, only register those resource providers that you're ready to use.

+The command returns a message that registration is ongoing.

+az rest --verbose --skip-authorization-header --header "Authorization=Bearer $accessToken" --method PUT --uri "https://centraluseuap.management.azure.com/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.Chaos/privateAccesses/<CSPAResourceName>?api-version=2023-10-27-preview" --body '

+az rest --verbose --skip-authorization-header --header "Authorization=Bearer $accessToken" --method PUT --uri "https://management.azure.com/subscriptions/<subscriptionID>/resourceGroups/<resourceGroup>/providers/Microsoft.Compute/virtualMachines/<VMSSname>/providers/Microsoft.Chaos/targets/Microsoft-Agent?api-version=2023-10-27-preview " --body ' {

+Opaque is the confidential AI platform unlocking sensitive data to securely accelerate AI into production. Created by world-renowned researchers at the Berkeley RISELab, OpaqueΓÇÖs user-friendly platform empowers organizations to run cloud-scale, general purpose AI workloads on encrypted data. Opaque supports popular languages and frameworks for AI, including Python and Spark, and enables governed data sharing with cryptographic verification of privacy and sovereignty. Opaque customers deploy high-performance AI faster and eliminate the tradeoff between innovation and security.

+Opaque provides a suite of business applications in Opaque Workspaces and Opaque Gateway that plug into your existing data stack and extends existing infrastructure, enabling you to build a confidential data pipeline with a hardware root of trust.

+## Opaque Workspaces

+The solution provides a centralized data platform that eliminates the need for compliance-driven, time-consuming tasks like anonymization and manual access approvals so that teams can operationalize their data for AI and analytics in days, not weeks, or months. Leverage confidential computing to protect data while sharing across teams and harnessed for AI, to ensure only expected participants can view the original data and results of the computation. The top 3 business outcomes that enterprises experience from deploying Opaque Workspaces are:

+ - Faster time to insights into confidential data

+ - Risk mitigation by secure data processing in use

+ - Reduced costs by optimizing data security/compliance

+## Opaque Gateway

+Organizations need a privacy-preserving AI solution that bridges the gap between protecting privacy and realizing the full potential of LLMs (Large Language Models). To protect privacy throughout the stages of a generative AI lifecycle, strict techniques must be implemented to securely and efficiently perform all security-critical operations that directly touch a model and all confidential data that is used for training and inferencing.

+Opaque Gateway serves as a privacy layer around your LLM of choice. With Opaque Gateway, you can securely and provably sanitize LLM prompts seamlessly to hide sensitive data from external parties and LLM providers. OpaqueΓÇÖs Confidential Computing technology ensures that no third party, not even Opaque Gateway, gets any visibility into the underlying prompt or data being sanitized.

+Get started today with the Azure Marketplace solution, [you can check it out here](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/opaquesystemsinc1638314744398.opaque_analytics_001?tab=Overview).

+ Title: "Tutorial: Integrate Admin for Spring with Eureka Server for Spring in Azure Container Apps"

+description: Learn to integrate Admin for Spring with Eureka Server for Spring in Azure Container Apps.

+# Tutorial: Integrate Admin for Spring with Eureka Server for Spring in Azure Container Apps

+This tutorial will guide you through the process of integrating a managed Admin for Spring with a Eureka Server for Spring within Azure Container Apps.

+This article contains some content similar to the "Connect to a managed Admin for Spring in Azure Container Apps" tutorial, but with Eureka Server for Spring, you can bind Admin for Spring to Eureka Server for Spring, so that it can get application information through Eureka, instead of having to bind individual applications to Admin for Spring.

+By following this guide, you'll set up a Eureka Server for service discovery and then create an Admin for Spring to manage and monitor your Spring applications registered with the Eureka Server. This setup ensures that other applications only need to bind to the Eureka Server, simplifying the management of your microservices.

+In this tutorial, you will learn to:

+1. Create a Eureka Server for Spring.

+2. Create an Admin for Spring and link it to the Eureka Server.

+3. Bind other applications to the Eureka Server for streamlined service discovery and management.

+## Prerequisites

+To complete this tutorial, you need the following items:

+| Requirement | Instructions |

+|--|--|

+| Azure account | An active subscription is required. If you don't have one, you [can create one for free](https://azure.microsoft.com/free/). |

+| Azure CLI | Install the [Azure CLI](/cli/azure/install-azure-cli).|

+| An existing Eureka Server for Spring Java component | If you don't have one, follow the [Create the Eureka Server for Spring](java-eureka-server.md#create-the-eureka-server-for-spring-java-component) section to create one. |

+## Considerations

+When running managed Java components in Azure Container Apps, be aware of the following details:

+## Setup

+Before you begin, create the necessary resources by executing the following commands.

+1. Create variables to support your application configuration. These values are provided for you for the purposes of this lesson.

+ ```bash

+ export LOCATION=eastus

+ export RESOURCE_GROUP=my-services-resource-group

+ export ENVIRONMENT=my-environment

+ export EUREKA_COMPONENT_NAME=eureka

+ export ADMIN_COMPONENT_NAME=admin

+ export CLIENT_APP_NAME=sample-service-eureka-client

+ export CLIENT_IMAGE="mcr.microsoft.com/javacomponents/samples/sample-admin-for-spring-client:latest"

+ ```

+ | Variable | Description |

+ |||

+ | `LOCATION` | The Azure region location where you create your container app and Java components. |

+ | `RESOURCE_GROUP` | The Azure resource group name for your demo application. |

+ | `ENVIRONMENT` | The Azure Container Apps environment name for your demo application. |

+ | `EUREKA_COMPONENT_NAME` | The name of the Eureka Server Java component. |

+ | `ADMIN_COMPONENT_NAME` | The name of the Admin for Spring Java component. |

+ | `CLIENT_APP_NAME` | The name of the container app that will bind to the Eureka Server. |

+ | `CLIENT_IMAGE` | The container image used in your Eureka Server container app. |

+1. Log in to Azure with the Azure CLI.

+ ```azurecli

+ az login

+ ```

+1. Create a resource group.

+ ```azurecli

+ az group create --name $RESOURCE_GROUP --location $LOCATION

+ ```

+1. Create your container apps environment.

+ ```azurecli

+ az containerapp env create \

+ --name $ENVIRONMENT \

+ --resource-group $RESOURCE_GROUP \

+ --location $LOCATION \

+ --query "properties.provisioningState"

+ ```

+ Using the `--query` parameter filters the response down to a simple success or failure message.

+## Optional: Create the Eureka Server for Spring

+If you don't have an existing Eureka Server for Spring, follow the command below to create the Eureka Server Java component. For more information, see [Create the Eureka Server for Spring](java-eureka-server.md#create-the-eureka server-for-spring-java-component).

+```azurecli

+az containerapp env java-component eureka-server-for-spring create \

+ --environment $ENVIRONMENT \

+ --resource-group $RESOURCE_GROUP \

+ --name $EUREKA_COMPONENT_NAME

+```

+## Bind the components together

+Create the Admin for Spring Java component.

+```azurecli

+az containerapp env java-component admin-for-spring create \

+ --environment $ENVIRONMENT \

+ --resource-group $RESOURCE_GROUP \

+ --name $ADMIN_COMPONENT_NAME \

+ --bind $EUREKA_COMPONENT_NAME

+```

+## Bind other apps to the Eureka Server

+With the Eureka Server set up, you can now bind other applications to it for service discovery. And you can also monitor and manage these applications in the dashboard of Admin for Spring. Follow the steps below to create and bind a container app to the Eureka Server:

+Create the container app and bind it to the Eureka Server.

+```azurecli

+az containerapp create \

+ --name $CLIENT_APP_NAME \

+ --resource-group $RESOURCE_GROUP \

+ --environment $ENVIRONMENT \

+ --image $CLIENT_IMAGE \

+ --min-replicas 1 \

+ --max-replicas 1 \

+ --ingress external \

+ --target-port 8080 \

+ --bind $EUREKA_COMPONENT_NAME

+```

+> [!TIP]

+> Since the previous steps bound the Admin for Spring component to the Eureka Server for Spring component, the Admin component enables service discovery and allows you to manage it through the Admin for Spring dashboard at the same time.

+## View the dashboards

+> [!IMPORTANT]

+> To view the dashboard, you need to have at least the `Microsoft.App/managedEnvironments/write` role assigned to your account on the managed environment resource. You can either explicitly assign `Owner` or `Contributor` role on the resource or follow the steps to create a custom role definition and assign it to your account.

+1. Create the custom role definition.

+ ```azurecli

+ az role definition create --role-definition '{

+ "Name": "Java Component Dashboard Access",

+ "IsCustom": true,

+ "Description": "Can access managed Java Component dashboards in managed environments",

+ "Actions": [

+ "Microsoft.App/managedEnvironments/write"

+ ],

+ "AssignableScopes": ["/subscriptions/<SUBSCRIPTION_ID>"]

+ }'

+ ```

+ Make sure to replace placeholder in between the `<>` brackets in the `AssignableScopes` value with your subscription ID.

+1. Assign the custom role to your account on managed environment resource.

+ Get the resource id of the managed environment.

+ ```azurecli

+ export ENVIRONMENT_ID=$(az containerapp env show \

+ --name $ENVIRONMENT --resource-group $RESOURCE_GROUP \

+ --query id -o tsv)

+ ```

+1. Assign the role to your account.

+ Before running this command, replace the placeholder in between the `<>` brackets with your user or service principal ID.

+ ```azurecli

+ az role assignment create \

+ --assignee <USER_OR_SERVICE_PRINCIPAL_ID> \

+ --role "Java Component Dashboard Access" \

+ --scope $ENVIRONMENT_ID

+ ```

+1. Get the URL of the Admin for Spring dashboard.

+ ```azurecli

+ az containerapp env java-component admin-for-spring show \

+ --environment $ENVIRONMENT \

+ --resource-group $RESOURCE_GROUP \

+ --name $ADMIN_COMPONENT_NAME \

+ --query properties.ingress.fqdn -o tsv

+ ```

+1. Get the URL of the Eureka Server for Spring dashboard.

+ ```azurecli

+ az containerapp env java-component eureka-server-for-spring show \

+ --environment $ENVIRONMENT \

+ --resource-group $RESOURCE_GROUP \

+ --name $EUREKA_COMPONENT_NAME \

+ --query properties.ingress.fqdn -o tsv

+ ```

+ This command returns the URL you can use to access the Eureka Server for Spring dashboard. Through the dashboard, your container app is also to you as shown in the following screenshot.

+ :::image type="content" source="media/java-components/spring-boot-admin.png" alt-text="Screenshot of the Admin for Spring dashboard." lightbox="media/java-components/spring-boot-admin.png":::

+ :::image type="content" source="media/java-components/eureka.png" alt-text="Screenshot of the Eureka Server for Spring dashboard." lightbox="media/java-components/eureka.png":::

+## Clean up resources

+The resources created in this tutorial have an effect on your Azure bill. If you aren't going to use these services long-term, run the following command to remove everything created in this tutorial.

+```azurecli

+az group delete \

+ --resource-group $RESOURCE_GROUP

+```

+## Next steps

+> [!div class="nextstepaction"]

+> [Configure Eureka Server for Spring settings](java-eureka-server-usage.md)

+> [Configure Admin for Spring settings](java-admin-for-spring-usage.md)

+ Title: Configure settings for the Admin for Spring component in Azure Container Apps (preview)

+description: Learn to configure the Admin for Spring component in Azure Container Apps.

+# Configure the Spring Boot Admin component in Azure Container Apps

+The Admin for Spring managed component offers an administrative interface for Spring Boot web applications that expose actuator endpoints. This article shows you how to configure and manage your Spring component.

+## Show

+You can view the details of an individual component by name using the `show` command.

+Before you run the following command, replace placeholders surrounded by `<>` with your values.

+```azurecli

+az containerapp env java-component admin-for-spring show \

+ --environment <ENVIRONMENT_NAME> \

+ --resource-group <RESOURCE_GROUP> \

+ --name <JAVA_COMPONENT_NAME>

+```

+## Update

+You can update the configuration of an Admin for Spring component using the `update` command.

+Before you run the following command, replace placeholders surrounded by `<>` with your values. Supported configurations are listed in the [properties list table](#configurable-properties).

+```azurecli

+az containerapp env java-component admin-for-spring update \

+ --environment <ENVIRONMENT_NAME> \

+ --resource-group <RESOURCE_GROUP> \

+ --name <JAVA_COMPONENT_NAME> \

+ --configuration <CONFIGURATION_KEY>="<CONFIGURATION_VALUE>"

+```

+## List

+You can list all registered Java components using the `list` command.

+Before you run the following command, replace placeholders surrounded by `<>` with your values.

+```azurecli

+az containerapp env java-component list \

+ --environment <ENVIRONMENT_NAME> \

+ --resource-group <RESOURCE_GROUP>

+```

+## Unbind

+To remove a binding from a container app, use the `--unbind` option.

+Before you run the following command, replace placeholders surrounded by `<>` with your values.

+``` azurecli

+az containerapp update \

+ --name <APP_NAME> \

+ --unbind <JAVA_COMPONENT_NAME> \

+ --resource-group <RESOURCE_GROUP>

+```

+## Dependency

+When you use the admin component in your container app, you need to add the following dependency in your `pom.xml` file. Replace the version number with the latest version available on the [Maven Repository](https://search.maven.org/artifact/de.codecentric/spring-boot-admin-starter-client).

+```xml

+<dependency>

+ <groupId>de.codecentric</groupId>

+ <version>3.3.2</version>

+ <artifactId>spring-boot-admin-starter-client</artifactId>

+</dependency>

+```

+## Configurable properties

+Starting with Spring Boot 2, endpoints other than health and info are not exposed by default. You can expose them by adding the following configuration in your `application.properties` file.

+```properties

+management.endpoints.web.exposure.include=*

+management.endpoint.health.show-details=always

+```

+## Allowed configuration list for your Admin for Spring

+The following list details the admin component properties you can configure for your app. You can find more details in [Spring Boot Admin](https://docs.spring-boot-admin.com/current/server.html) docs.

+| Property name | Description | Default value |

+|--|--|--|

+| `spring.boot.admin.server.enabled` | Enables the Spring Boot Admin Server. | `true` |

+| `spring.boot.admin.context-path` | The path prefix where the Admin ServerΓÇÖs statics assets and API are served. Relative to the Dispatcher-Servlet. | |

+| `spring.boot.admin.monitor.status-interval` | Time interval in milliseconds to check the status of instances. | `10,000ms` |

+| `spring.boot.admin.monitor.status-lifetime` | Lifetime of status in milliseconds. The status isn't updated as long the last status isnΓÇÖt expired. | 10,000 ms |

+| `spring.boot.admin.monitor.info-interval` | Time interval in milliseconds to check the info of instances. | `1m` |

+| `spring.boot.admin.monitor.info-lifetime` | Lifetime of info in minutes. The info isn't as long the last info isnΓÇÖt expired. | `1m` |

+| `spring.boot.admin.monitor.default-timeout` | Default timeout when making requests. Individual values for specific endpoints can be overridden using `spring.boot.admin.monitor.timeout.*`. | `10,000` |

+| `spring.boot.admin.monitor.timeout.*` | Key-value pairs with the timeout per `endpointId`. | Defaults to `default-timeout` value. |

+| `spring.boot.admin.monitor.default-retries` | Default number of retries for failed requests. Requests that modify data (`PUT`, `POST`, `PATCH`, `DELETE`) are never retried. Individual values for specific endpoints can be overridden using `spring.boot.admin.monitor.retries.*`. | `0` |

+| `spring.boot.admin.monitor.retries.*` | Key-value pairs with the number of retries per `endpointId`. Requests that modify data (`PUT`, `POST`, `PATCH`, `DELETE`) are never retried. | Defaults to `default-retries` value. |

+| `spring.boot.admin.metadata-keys-to-sanitize` | Metadata values for the keys matching these regex patterns used to sanitize in all JSON output. Starting from Spring Boot 3, all actuator values are masked by default. For more information about how to configure the unsanitization process, see ([Sanitize Sensitive Values](https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#howto.actuator.sanitize-sensitive-values)). | `".**password$", ".\*secret$", ".\*key$", ".\*token$", ".\*credentials.**", ".*vcap_services$"` |

+| `spring.boot.admin.probed-endpoints` | For Spring Boot 1.x client applications Spring Boot Admin probes for the specified endpoints using an `OPTIONS` request. If the path differs from the ID, you can specify this value as `id:path` (for example: `health:ping`) | `"health", "env", "metrics", "httptrace:trace", "threaddump:dump", "jolokia", "info", "logfile", "refresh", "flyway", "liquibase", "heapdump", "loggers", "auditevents"` |

+| `spring.boot.admin.instance-proxy.ignored-headers` | Headers not to forwarded when making requests to clients. | `"Cookie", "Set-Cookie", "Authorization"` |

+| `spring.boot.admin.ui.title` | The displayed page title. | `"Spring Boot Admin"` |

+| `spring.boot.admin.ui.poll-timer.cache` | Polling duration in milliseconds to fetch new cache data. | `2500` |

+| `spring.boot.admin.ui.poll-timer.datasource` | Polling duration in milliseconds to fetch new data source data. | `2500` |

+| `spring.boot.admin.ui.poll-timer.gc` | Polling duration in milliseconds to fetch new gc data. | `2500` |

+| `spring.boot.admin.ui.poll-timer.process` | Polling duration in milliseconds to fetch new process data. | `2500` |

+| `spring.boot.admin.ui.poll-timer.memory` | Polling duration in milliseconds to fetch new memory data. | `2500` |

+| `spring.boot.admin.ui.poll-timer.threads` | Polling duration in milliseconds to fetch new threads data. | `2500` |

+| `spring.boot.admin.ui.poll-timer.logfile` | Polling duration in milliseconds to fetch new logfile data. | `1000` |

+| `spring.boot.admin.ui.enable-toasts` | Enables or disables toast notifications. | `false` |

+| `spring.boot.admin.ui.title` | Browser's window title value. | "" |

+| `spring.boot.admin.ui.brand` | HTML code rendered in the navigation header and defaults to the Spring Boot Admin label. By default the Spring Boot Admin logo is followed by its name. | "" |

+| `management.scheme` | Value that is substituted in the service URL used for accessing the actuator endpoints. | |

+| `management.address` | Value that is substituted in the service URL used for accessing the actuator endpoints. | |

+| `management.port` | Value that is substituted in the service URL used for accessing the actuator endpoints. | |

+| `management.context-path` | Value that is appended to the service URL used for accessing the actuator endpoints. | `${spring.boot.admin.discovery.converter.management-context-path}` |

+| `health.path` | Value that is appended to the service URL used for health checking. Ignored by the `EurekaServiceInstanceConverter`. | `${spring.boot.admin.discovery.converter.health-endpoint}` |

+| `spring.boot.admin.discovery.enabled` | Enables the `DiscoveryClient` support for the admin server. | `true` |

+| `spring.boot.admin.discovery.converter.management-context-path` | Value that is appended to the `service-url` of the discovered service when the `management-url` value is converted by the `DefaultServiceInstanceConverter`. | `/actuator` |

+| `spring.boot.admin.discovery.converter.health-endpoint-path` | Value that is appended to the `management-url` of the discovered service when the `health-url` value is converted by the `DefaultServiceInstanceConverter`. | `"health"` |

+| `spring.boot.admin.discovery.ignored-services` | Services that are ignored when using discovery and not registered as application. Supports simple patterns such as `"foo*"`, `"*bar"`, `"foo*bar*"`. | |

+| `spring.boot.admin.discovery.services` | Services included when using discovery and registered as application. Supports simple patterns such as `"foo*"`, `"*bar"`, `"foo*bar*"`. | `"*"` |

+| `spring.boot.admin.discovery.ignored-instances-metadata` | Services ignored if they contain at least one metadata item that matches patterns in this list. Supports patterns such as `"discoverable=false"`. | |

+| `spring.boot.admin.discovery.instances-metadata` | Services included if they contain at least one metadata item that matches patterns in list. Supports patterns such as `"discoverable=true"`. | |

+### Common configurations

+- Logging related configurations:

+ - [**logging.level.***](https://docs.spring.io/spring-boot/docs/2.1.13.RELEASE/reference/html/boot-features-logging.html#boot-features-custom-log-levels)

+ - [**logging.group.***](https://docs.spring.io/spring-boot/docs/2.1.13.RELEASE/reference/html/boot-features-logging.html#boot-features-custom-log-groups)

+ - Any other configurations under `logging.*` namespace should be forbidden. For example, writing log files by using `logging.file` should be forbidden.

+## Next steps

+> [!div class="nextstepaction"]

+> [Tutorial: Connect to a managed Admin for Spring](java-admin.md)

+## Related content

+- [Tutorial: Integrate the managed Admin for Spring with Eureka Server for Spring](java-admin-eureka-integration.md)

+ Title: "Tutorial: Connect to a managed Admin for Spring in Azure Container Apps"

+description: Learn to use a managed Admin for Spring in Azure Container Apps.

+# Tutorial: Connect to a managed Admin for Spring in Azure Container Apps

+The Admin for Spring managed component offers an administrative interface for Spring Boot web applications that expose actuator endpoints. As a managed component in Azure Container Apps, you can easily bind your container app to Admin for Spring for seamless integration and management.

+This tutorial shows you how to create an Admin for Spring Java component and bind it to your container app so you can monitor and manage your Spring applications with ease.

+In this tutorial, you learn to:

+> [!div class="checklist"]

+> * Create an Admin for Spring Java component

+> * Bind your container app to Admin for Spring Java component

+> [!NOTE]

+> If you want to integrate Admin for Spring with Eureka Server for Spring, see [Integrate Admin for Spring with Eureka Server for Spring in Azure Container Apps](java-admin-eureka-integration.md) instead.

+> [!IMPORTANT]

+> This tutorial uses services that can affect your Azure bill. If you decide to follow along step-by-step, make sure you delete the resources featured in this article to avoid unexpected billing.

+## Prerequisites

+To complete this project, you need the following items:

+| Requirement | Instructions |

+|--|--|

+| [Azure account](https://azure.microsoft.com/free/) | An active subscription is required. If you don't have one, you [can create one for free](https://azure.microsoft.com/free/). |

+| [Azure CLI](/cli/azure/install-azure-cli) | Install the [Azure CLI](/cli/azure/install-azure-cli).|

+## Considerations

+When running Admin for Spring in Azure Container Apps, be aware of the following details:

+## Setup

+Before you begin to work with the Admin for Spring, you first need to create the required resources.

+The following commands help you create your resource group and Container Apps environment.

+1. Create variables to support your application configuration. These values are provided for you for the purposes of this lesson.

+ ```bash

+ export LOCATION=eastus

+ export RESOURCE_GROUP=my-demo-resource-group

+ export ENVIRONMENT=my-environment

+ export JAVA_COMPONENT_NAME=admin

+ export APP_NAME=sample-admin-client

+ export IMAGE="mcr.microsoft.com/javacomponents/samples/sample-admin-for-spring-client:latest"

+ ```

+ | Variable | Description |

+ |||

+ | `LOCATION` | The Azure region location where you create your container app and Java component. |

+ | `ENVIRONMENT` | The Azure Container Apps environment name for your demo application. |

+ | `RESOURCE_GROUP` | The Azure resource group name for your demo application. |

+ | `JAVA_COMPONENT_NAME` | The name of the Java component created for your container app. In this case, you create an Admin for Spring Java component. |

+ | `IMAGE` | The container image used in your container app. |

+1. Log in to Azure with the Azure CLI.

+ ```azurecli

+ az login

+ ```

+1. Create a resource group.

+ ```azurecli

+ az group create \

+ --name $RESOURCE_GROUP \

+ --location $LOCATION \

+ --query "properties.provisioningState"

+ ```

+ Using the `--query` parameter filters the response down to a simple success or failure message.

+1. Create your container apps environment.

+ ```azurecli

+ az containerapp env create \

+ --name $ENVIRONMENT \

+ --resource-group $RESOURCE_GROUP \

+ --location $LOCATION

+ ```

+## Use the component

+Now that you have an existing environment, you can create your container app and bind it to a Java component instance of Admin for Spring component.

+1. Create the Admin for Spring Java component.

+ ```azurecli

+ az containerapp env java-component admin-for-spring create \

+ --environment $ENVIRONMENT \

+ --resource-group $RESOURCE_GROUP \

+ --name $JAVA_COMPONENT_NAME

+ ```

+1. Create the container app and bind to the Admin for Spring.

+ ```azurecli

+ az containerapp create \

+ --name $APP_NAME \

+ --resource-group $RESOURCE_GROUP \

+ --environment $ENVIRONMENT \

+ --image $IMAGE \

+ --min-replicas 1 \

+ --max-replicas 1 \

+ --ingress external \

+ --target-port 8080 \

+ --bind $JAVA_COMPONENT_NAME

+ ```

+ The `--bind` parameter binds the container app to the Admin for Spring Java component. The container app can now read the configuration values from environment variables, primarily the `SPRING_BOOT_ADMIN_CLIENT_URL` property and connect to the Admin for Spring.

+ The binding also injects the following property:

+ ```bash

+ "SPRING_BOOT_ADMIN_CLIENT_INSTANCE_PREFER-IP": "true",

+ ```

+ This property indicates that the Admin for Spring component client should prefer the IP address of the container app instance when connecting to the Admin for Spring server.

+ You can also [remove a binding](java-admin-for-spring-usage.md#unbind) from your application.

+## View the dashboard

+> [!IMPORTANT]

+> To view the dashboard, you need to have at least the `Microsoft.App/managedEnvironments/write` role assigned to your account on the managed environment resource. You can either explicitly assign `Owner` or `Contributor` role on the resource or follow the steps to create a custom role definition and assign it to your account.

+1. Create the custom role definition.

+ ```azurecli

+ az role definition create --role-definition '{

+ "Name": "<ROLE_NAME>",

+ "IsCustom": true,

+ "Description": "Can access managed Java Component dashboards in managed environments",

+ "Actions": [

+ "Microsoft.App/managedEnvironments/write"

+ ],

+ "AssignableScopes": ["/subscriptions/<SUBSCRIPTION_ID>"]

+ }'

+ ```

+ Make sure to replace the placeholders in between the `<>` brackets with your values.

+1. Assign the custom role to your account on managed environment resource.

+ Get the resource id of the managed environment:

+ ```azurecli

+ export ENVIRONMENT_ID=$(az containerapp env show \

+ --name $ENVIRONMENT --resource-group $RESOURCE_GROUP \

+ --query id -o tsv)

+ ```

+1. Assign the role to your account.

+ Before running this command, replace the placeholder in between the `<>` brackets with your user or service principal ID.

+ ```azurecli

+ az role assignment create \

+ --assignee <USER_OR_SERVICE_PRINCIPAL_ID> \

+ --role "<ROLE_NAME>" \

+ --scope $ENVIRONMENT_ID

+ ```

+ > [!NOTE]

+ > <USER_OR_SERVICE_PRINCIPAL_ID> usually should be the identity that you use to access Azure Portal. <ROLE_NAME> is the name you assigned in step 1.

+1. Get the URL of the Admin for Spring dashboard.

+ ```azurecli

+ az containerapp env java-component admin-for-spring show \

+ --environment $ENVIRONMENT \

+ --resource-group $RESOURCE_GROUP \

+ --name $JAVA_COMPONENT_NAME \

+ --query properties.ingress.fqdn -o tsv

+ ```

+ This command returns the URL you can use to access the Admin for Spring dashboard. Through the dashboard, your container app is also to you as shown in the following screenshot.

+ :::image type="content" source="media/java-components/spring-boot-admin-alone.png" alt-text="Screenshot of the overview the Admin for Spring dashboard." lightbox="media/java-components/spring-boot-admin-alone.png":::

+## Clean up resources

+The resources created in this tutorial have an effect on your Azure bill. If you aren't going to use these services long-term, run the following command to remove everything created in this tutorial.

+```azurecli

+az group delete \

+ --resource-group $RESOURCE_GROUP

+```

+## Next steps

+> [!div class="nextstepaction"]

+> [Configure Admin for Spring settings](java-admin-for-spring-usage.md)

+## Related content

+- [Integrate the managed Admin for Spring with Eureka Server for Spring](java-admin-eureka-integration.md)

+ export EUREKA_COMPONENT_NAME=eureka

+ | `EUREKA_COMPONENT_NAME` | The name of the Java component created for your container app. In this case, you create a Eureka Server for Spring Java component. |

+## Create the Eureka Server for Spring Java component

+ --name $EUREKA_COMPONENT_NAME

+1. Optional: Update the Eureka Server for Spring Java component configuration.

+ --name $EUREKA_COMPONENT_NAME

+## Bind your container app to the Eureka Server for Spring Java component

+ --bind $EUREKA_COMPONENT_NAME \

+## View the application through a dashboard

+> [!IMPORTANT]

+> To view the dashboard, you need to have at least the `Microsoft.App/managedEnvironments/write` role assigned to your account on the managed environment resource. You can either explicitly assign `Owner` or `Contributor` role on the resource or follow the steps to create a custom role definition and assign it to your account.

+1. Create the custom role definition.

+ ```azurecli

+ az role definition create --role-definition '{

+ "Name": "<YOUR_ROLE_NAME>",

+ "IsCustom": true,

+ "Description": "Can access managed Java Component dashboards in managed environments",

+ "Actions": [

+ "Microsoft.App/managedEnvironments/write"

+ ],

+ "AssignableScopes": ["/subscriptions/<SUBSCRIPTION_ID>"]

+ }'

+ ```

+ Make sure to replace placeholder in between the `<>` brackets in the `AssignableScopes` value with your subscription ID.

+1. Assign the custom role to your account on managed environment resource.

+ Get the resource id of the managed environment:

+ ```azurecli

+ export ENVIRONMENT_ID=$(az containerapp env show \

+ --name $ENVIRONMENT --resource-group $RESOURCE_GROUP \

+ --query id -o tsv)

+ ```

+1. Assign the role to your account.

+ Before running this command, replace the placeholder in between the `<>` brackets with your user or service principal ID.

+ ```azurecli

+ az role assignment create \

+ --assignee <USER_OR_SERVICE_PRINCIPAL_ID> \

+ --role "<ROLE_NAME>" \

+ --scope $ENVIRONMENT_ID

+ ```

+ > [!NOTE]

+ > <USER_OR_SERVICE_PRINCIPAL_ID> usually should be the identity that you use to access Azure Portal. <ROLE_NAME> is the name you assigned in step 1.

+1. Get the URL of the Eureka Server for Spring dashboard.

+ ```azurecli

+ az containerapp env java-component eureka-server-for-spring show \

+ --environment $ENVIRONMENT \

+ --resource-group $RESOURCE_GROUP \

+ --name $EUREKA_COMPONENT_NAME \

+ --query properties.ingress.fqdn -o tsv

+ ```

+ This command returns the URL you can use to access the Eureka Server for Spring dashboard. Through the dashboard, your container app is also to you as shown in the following screenshot.

+ :::image type="content" source="media/java-components/eureka-alone.png" alt-text="Screenshot of the Eureka Server for Spring dashboard." lightbox="media/java-components/eureka-alone.png":::

+## Optional: Integrate the Eureka Server for Spring and Admin for Spring Java components

+If you want to integrate the Eureka Server for Spring and the Admin for Spring Java components, see [Integrate the managed Admin for Spring with Eureka Server for Spring](java-admin-eureka-integration.md).

+## Related content

+- [Integrate the managed Admin for Spring with Eureka Server for Spring](java-admin-eureka-integration.md)

+Azure Container Apps can run any containerized Java application in the cloud while giving flexible options for how you deploy your applications.

+ - **JAR deployment**: You can deploy your container app directly from a [JAR file](java-get-started.md?tabs=jar).

+ - **WAR deployment**: You can deploy your container app directly from a [WAR file](java-get-started.md?tabs=war).

+ - **IDE support**: You can deploy your container app directly from [IntelliJ](/azure/developer/java/toolkit-for-intellij/create-container-apps-intellij#deploy-the-container-app).

+- **Automatic memory fitting**: Container Apps optimizes how the Java Virtual Machine (JVM) [manages memory](java-memory-fit.md), making the most possible memory available to your Java applications.

+- **Build environment variables**: You can configure [custom key-value pairs](java-build-environment-variables.md) to control the Java image build from source code.

+Examples listed in this table aren't meant to be exhaustive, but to help your best understand the intent of different application types.

+- **Metrics**: Java Virtual Machine (JVM) metrics are critical for monitoring the health and performance of your Java applications. The data collected includes insights into memory usage, garbage collection, thread count of your JVM. You can check [metrics](java-metrics.md) to help ensure the health and stability of your applications.

+## Diagnostics

+Azure Container Apps offers built-in diagnostics tools exclusively for Java developers. This support streamlines the debugging and troubleshooting of Java applications running on Azure Container Apps for enhanced efficiency and eases.

+- **Dynamic logger level**: Allows you to access and check different level of log details without code modifications or forcing you to restart your app. You can view [Set dynamic logger level](java-dynamic-log-level.md) for reference.

+- **Admin for Spring**： The Admin for Spring managed component provides an administrative interface is designed for Spring Boot web applications that have actuator endpoints. A managed component provides integration and management to your container app by allowing you to bind your container app to the [Admin for Spring component](java-admin.md).

+ --cpu 0.25 --memory 0.5Gi \

+| `--cpu` | `0.25` | The required CPU in cores. |

+| `--memory` | `0.5Gi` | The required memory. |

+ "type": "Microsoft.App/sessionPools",

+ "poolManagementType": "Dynamic",

+ "cooldownPeriodInSeconds": 600

+ "name": "mycontainer",

+ "cpu": 0.25,

+ "memory": "0.5Gi"

+ "command": [

+ "/bin/sh"

+ ],

+ "args": [

+ "-c",

+ "while true; do echo hello; sleep 10;done"

+ ],

+ ]

+ "status": "EgressEnabled"

+| `poolManagementType` | `Dynamic` | Must be `Dynamic` for custom container sessions. |

+| `dynamicPoolConfiguration.cooldownPeriodInSeconds` | `600` | The number of seconds that a session can be idle before the session is terminated. The idle period is reset each time the session's API is called. Value must be between `300` and `3600`. |

+| `customContainerTemplate.containers[0].image` | `myregistry.azurecr.io/my-container-image:1.0` | The container image to use for the session pool. |

+| `customContainerTemplate.containers[0].name` | `mycontainer` | The name of the container. |

+| `customContainerTemplate.containers[0].resources.cpu` | `0.25` | The required CPU in cores. |

+| `customContainerTemplate.containers[0].resources.memory` | `0.5Gi` | The required memory. |

+| `customContainerTemplate.containers[0].env` | Array of name-value pairs | The environment variables to set in the container. |

+| `customContainerTemplate.containers[0].args` | `["-c", "while true; do echo hello; sleep 10;done"]` | The arguments to pass to the command. |

+- [Retrieval Augmented Generation (RAG)](rag.md)

+- [Retrieval Augmented Generation (RAG)](rag.md)

+ Title: Quickstart - Build a RAG Chatbot

+description: Learn how to build a RAG chatbot in Python

+# Quickstart - Build a RAG chatbot with Azure Cosmos DB NoSQL API

+In this quickstart, we'll demonstrate how to build a [RAG Pattern](../gen-ai/rag.md) application using a subset of the Movie Lens dataset. This sample leverages the Python SDK for Azure Cosmos DB for NoSQL to perform vector search for RAG, store and retrieve chat history, and store vectors of the chat history to use as a semantic cache. Azure OpenAI is used to generate embeddings and Large Language Model (LLM) completions.

+At the end, we'll create a simple UX using Gradio to allow users to type in questions and display responses generated by Azure OpenAI or served from the cache. The responses will also display an elapsed time to show the impact caching has on performance versus generating a response.

+> [!TIP]

+> You can find the full Python notebook sample [here](https://aka.ms/CosmosPythonRAGQuickstart).

+> For more RAG samples, visit: [AzureDataRetrievalAugmentedGenerationSamples](https://github.com/microsoft/AzureDataRetrievalAugmentedGenerationSamples)

+**Important Note**: This sample requires you to set up accounts for Azure Cosmos DB for NoSQL and Azure OpenAI. To get started, visit:

+- [Azure Cosmos DB for NoSQL Python Quickstart](../nosql/quickstart-python.md)

+- [Azure Cosmos DB for NoSQL Vector Search](../nosql/vector-search.md)

+- [Azure OpenAI](../../ai-services/openai/toc.yml)

+### 1. Install Required Packages

+Install the necessary Python packages to interact with Azure Cosmos DB and other services.

+```bash

+! pip install --user python-dotenv

+! pip install --user aiohttp

+! pip install --user openai

+! pip install --user gradio

+! pip install --user ijson

+! pip install --user nest_asyncio

+! pip install --user tenacity

+# Note: ensure you have azure-cosmos version 4.7 or higher installed

+! pip install --user azure-cosmos

+```

+### 2. Initialize Your Client Connection

+Populate `sample_env_file.env` with the appropriate credentials for Azure Cosmos DB and Azure OpenAI.

+```env

+cosmos_uri = "https://<replace with cosmos db account name>.documents.azure.com:443/"

+cosmos_key = "<replace with cosmos db account key>"

+cosmos_database_name = "database"

+cosmos_collection_name = "vectorstore"

+cosmos_vector_property_name = "vector"

+cosmos_cache_database_name = "database"

+cosmos_cache_collection_name = "vectorcache"

+openai_endpoint = "<replace with azure openai endpoint>"

+openai_key = "<replace with azure openai key>"

+openai_type = "azure"

+openai_api_version = "2023-05-15"

+openai_embeddings_deployment = "<replace with azure openai embeddings deployment name>"

+openai_embeddings_model = "<replace with azure openai embeddings model - e.g. text-embedding-3-large"

+openai_embeddings_dimensions = "1536"

+openai_completions_deployment = "<replace with azure openai completions deployment name>"

+openai_completions_model = "<replace with azure openai completions model - e.g. gpt-35-turbo>"

+storage_file_url = "https://cosmosdbcosmicworks.blob.core.windows.net/fabcondata/movielens_dataset.json"

+```

+```python

+# Import the required libraries

+import time

+import json

+import uuid

+import urllib

+import ijson

+import zipfile

+from dotenv import dotenv_values

+from openai import AzureOpenAI

+from azure.core.exceptions import AzureError

+from azure.cosmos import PartitionKey, exceptions

+from time import sleep

+import gradio as gr

+# Cosmos DB imports

+from azure.cosmos import CosmosClient

+# Load configuration

+env_name = "sample_env_file.env"

+config = dotenv_values(env_name)

+cosmos_conn = config['cosmos_uri']

+cosmos_key = config['cosmos_key']

+cosmos_database = config['cosmos_database_name']

+cosmos_collection = config['cosmos_collection_name']

+cosmos_vector_property = config['cosmos_vector_property_name']

+comsos_cache_db = config['cosmos_cache_database_name']

+cosmos_cache = config['cosmos_cache_collection_name']

+# Create the Azure Cosmos DB for NoSQL async client for faster data loading

+cosmos_client = CosmosClient(url=cosmos_conn, credential=cosmos_key)

+openai_endpoint = config['openai_endpoint']

+openai_key = config['openai_key']

+openai_api_version = config['openai_api_version']

+openai_embeddings_deployment = config['openai_embeddings_deployment']

+openai_embeddings_dimensions = int(config['openai_embeddings_dimensions'])

+openai_completions_deployment = config['openai_completions_deployment']

+# Movies file url

+storage_file_url = config['storage_file_url']

+# Create the OpenAI client

+openai_client = AzureOpenAI(azure_endpoint=openai_endpoint, api_key=openai_key, api_version=openai_api_version)

+```

+### 3. Create a Database and Containers with Vector Policies

+This function takes a database object, a collection name, the name of the document property that stores vectors, and the number of vector dimensions used for the embeddings.

+```python

+db = cosmos_client.create_database_if_not_exists(cosmos_database)

+# Create the vector embedding policy to specify vector details

+vector_embedding_policy = {

+ "vectorEmbeddings": [

+ {

+ "path":"/" + cosmos_vector_property,

+ "dataType":"float32",

+ "distanceFunction":"dotproduct",

+ "dimensions":openai_embeddings_dimensions

+ },

+ ]

+}

+# Create the vector index policy to specify vector details

+indexing_policy = {

+ "vectorIndexes": [

+ {

+ "path": "/"+cosmos_vector_property,

+ "type": "quantizedFlat"

+ }

+ ]

+}

+# Create the data collection with vector index (note: this creates a container with 10000 RUs to allow fast data load)

+try:

+ movies_container = db.create_container_if_not_exists(id=cosmos_collection,

+ partition_key=PartitionKey(path='/id'),

+ indexing_policy=indexing_policy,

+ vector_embedding_policy=vector_embedding_policy,

+ offer_throughput=10000)

+ print('Container with id \'{0}\' created'.format(movies_container.id))

+except exceptions.CosmosHttpResponseError:

+ raise

+# Create the cache collection with vector index

+try:

+ cache_container = db.create_container_if_not_exists(id=cosmos_cache,

+ partition_key=PartitionKey(path='/id'),

+ indexing_policy=indexing_policy,

+ vector_embedding_policy=vector_embedding_policy,

+ offer_throughput=1000)

+ print('Container with id \'{0}\' created'.format(cache_container.id))

+except exceptions.CosmosHttpResponseError:

+ raise

+```

+### 4. Generate Embeddings from Azure OpenAI

+This function vectorizes the user input for vector search. Ensure the dimensionality and model used match the sample data provided, or else regenerate vectors with your desired model.

+```python

+from tenacity import retry, stop_after_attempt, wait_random_exponential

+@retry(wait=wait_random_exponential(min=2, max=300), stop=stop_after_attempt(20))

+def generate_embeddings(text):

+ response = openai_client.embeddings.create(

+ input=text,

+ model=openai_embeddings_deployment,

+ dimensions=openai_embeddings_dimensions

+ )

+ embeddings = response.model_dump()

+ return embeddings['data'][0]['embedding']

+```

+### 5. Load Data from the JSON File

+Extract the MovieLens dataset from the zip file.

+```python

+# Unzip the data file

+with zipfile.ZipFile("../../DataSet/Movies/MovieLens-4489-256D.zip", 'r') as zip_ref:

+ zip_ref.extractall("/Data")

+zip_ref.close()

+# Load the data file

+data = []

+with open('/Data/MovieLens-4489-256D.json', 'r') as d:

+ data = json.load(d)

+# View the number of documents in the data (4489)

+len(data)

+```

+### 6. Store Data in Azure Cosmos DB

+Upsert data into Azure Cosmos DB for NoSQL. Records are written asynchronously.

+```python

+import asyncio

+import time

+from concurrent.futures import ThreadPoolExecutor

+async def generate_vectors(items, vector_property):

+ for item in items:

+ vectorArray = await generate_embeddings(item['overview'])

+ item[vector_property] = vectorArray

+ return items

+async def insert_data():

+ start_time = time.time() # Record the start time

+

+ counter = 0

+ tasks = []

+ max_concurrency = 20 # Adjust this value to control the level of concurrency

+ semaphore = asyncio.Semaphore(max_concurrency)

+ print("Starting doc load, please wait...")

+

+ def upsert_item_sync(obj):

+ movies_container.upsert_item(body=obj)

+

+ async def upsert_object(obj):

+ nonlocal counter

+ async with semaphore:

+ await asyncio.get_event_loop().run_in_executor(None, upsert_item_sync, obj)

+ # Progress reporting

+ counter += 1

+ if counter % 100 == 0:

+ print(f"Sent {counter} documents for insertion into collection.")

+

+ for obj in data:

+ tasks.append(asyncio.create_task(upsert_object(obj)))

+

+ # Run all upsert tasks concurrently within the limits set by the semaphore

+ await asyncio.gather(*tasks)

+

+ end_time = time.time() # Record the end time

+ duration = end_time - start_time # Calculate the duration

+ print(f"All {counter} documents inserted!")

+ print(f"Time taken: {duration:.2f} seconds ({duration:.3f} milliseconds)")

+# Run the async function

+await insert_data()

+```

+### 7. Perform Vector Search

+This function defines a vector search over the movies data and chat cache collections.

+```python

+def vector_search(container, vectors, similarity_score=0.02, num_results=5):

+ results = container.query_items(

+ query='''

+ SELECT TOP @num_results c.overview, VectorDistance(c.vector, @embedding) as SimilarityScore

+ FROM c

+ WHERE VectorDistance(c.vector,@embedding) > @similarity_score

+ ORDER BY VectorDistance(c.vector,@embedding)

+ ''',

+ parameters=[

+ {"name": "@embedding", "value": vectors},

+ {"name": "@num_results", "value": num_results},

+ {"name": "@similarity_score", "value": similarity_score}

+ ],

+ enable_cross_partition_query=True,

+ populate_query_metrics=True

+ )

+ results = list(results)

+ formatted_results = [{'SimilarityScore': result.pop('SimilarityScore'), 'document': result} for result in results]

+ return formatted_results

+```

+### 8. Get Recent Chat History

+This function provides conversational context to the LLM, allowing it to better have a conversation with the user.

+```python

+def get_chat_history(container, completions=3):

+ results = container.query_items(

+ query='''

+ SELECT TOP @completions *

+ FROM c

+ ORDER BY c._ts DESC

+ ''',

+ parameters=[

+ {"name": "@completions", "value": completions},

+ ],

+ enable_cross_partition_query=True

+ )

+ results = list(results)

+ return results

+```

+### 9. Chat Completion Functions

+Define the functions to handle the chat completion process, including caching responses.

+```python

+def generate_completion(user_prompt, vector_search_results, chat_history):

+ system_prompt = '''

+ You are an intelligent assistant for movies. You are designed to provide helpful answers to user questions about movies in your database.

+ You are friendly, helpful, and informative and can be lighthearted. Be concise in your responses, but still friendly.

+ - Only answer questions related to the information provided below. Provide at least 3 candidate movie answers in a list.

+ - Write two lines of whitespace between each answer in the list.

+ '''

+ messages = [{'role': 'system', 'content': system_prompt}]

+ for chat in chat_history:

+ messages.append({'role': 'user', 'content': chat['prompt'] + " " + chat['completion']})

+ messages.append({'role': 'user', 'content': user_prompt})

+ for result in vector_search_results:

+ messages.append({'role': 'system', 'content': json.dumps(result['document'])})

+ response = openai_client.chat.completions.create(

+ model=openai_completions_deployment,

+ messages=messages,

+ temperature=0.1

+ )

+ return response.model_dump()

+def chat_completion(cache_container, movies_container, user_input):

+ print("starting completion")

+ # Generate embeddings from the user input

+ user_embeddings = generate_embeddings(user_input)

+ # Query the chat history cache first to see if this question has been asked before

+ cache_results = get_cache(container=cache_container, vectors=user_embeddings, similarity_score=0.99, num_results=1)

+ if len(cache_results) > 0:

+ print("Cached Result\n")

+ return cache_results[0]['completion'], True

+

+ else:

+ # Perform vector search on the movie collection

+ print("New result\n")

+ search_results = vector_search(movies_container, user_embeddings)

+ print("Getting Chat History\n")

+ # Chat history

+ chat_history = get_chat_history(cache_container, 3)

+ # Generate the completion

+ print("Generating completions \n")

+ completions_results = generate_completion(user_input, search_results, chat_history)

+ print("Caching response \n")

+ # Cache the response

+ cache_response(cache_container, user_input, user_embeddings, completions_results)

+ print("\n")

+ # Return the generated LLM completion

+ return completions_results['choices'][0]['message']['content'], False

+```

+### 10. Cache Generated Responses

+Save the user prompts and generated completions to the cache for faster future responses.

+```python

+def cache_response(container, user_prompt, prompt_vectors, response):

+ chat_document = {

+ 'id': str(uuid.uuid4()),

+ 'prompt': user_prompt,

+ 'completion': response['choices'][0]['message']['content'],

+ 'completionTokens': str(response['usage']['completion_tokens']),

+ 'promptTokens': str(response['usage']['prompt_tokens']),

+ 'totalTokens': str(response['usage']['total_tokens']),

+ 'model': response['model'],

+ 'vector': prompt_vectors

+ }

+ container.create_item(body=chat_document)

+```

+### 11. Create a Simple UX in Gradio

+Build a user interface using Gradio for interacting with the AI application.

+```python

+chat_history = []

+with gr.Blocks() as demo:

+ chatbot = gr.Chatbot(label="Cosmic Movie Assistant")

+ msg = gr.Textbox(label="Ask me about movies in the Cosmic Movie Database!")

+ clear = gr.Button("Clear")

+ def user(user_message, chat_history):

+ start_time = time.time()

+ response_payload, cached = chat_completion(cache_container, movies_container, user_message)

+ end_time = time.time()

+ elapsed_time = round((end

+ time - start_time) * 1000, 2)

+ details = f"\n (Time: {elapsed_time}ms)"

+ if cached:

+ details += " (Cached)"

+ chat_history.append([user_message, response_payload + details])

+

+ return gr.update(value=""), chat_history

+

+ msg.submit(user, [msg, chatbot], [msg, chatbot], queue=False)

+ clear.click(lambda: None, None, chatbot, queue=False)

+# Launch the Gradio interface

+demo.launch(debug=True)

+# Be sure to run this cell to close or restart the Gradio demo

+demo.close()

+```

+### Next Steps

+This quickstart guide is designed to help you set up and get running with Azure Cosmos DB NoSQL API for vector search applications in a few simple steps. If you have any further questions or need assistance, check out these resources:

+- [30-day Free Trial without Azure subscription](https://azure.microsoft.com/try/cosmosdb/)

+- [90-day Free Trial and up to $6,000 in throughput credits with Azure AI Advantage](../ai-advantage.md)

+> [!div class="nextstepaction"]

+> [Use the Azure Cosmos DB lifetime free tier](../free-tier.md)

+### More Vector Database Solutions

+- [Azure PostgreSQL Server pgvector Extension](../../postgresql/flexible-server/how-to-use-pgvector.md)

+ Title: Retrieval Augmented Generation (RAG) in Azure Cosmos DB

+description: Learn about Retrieval Augmented Generation (RAG) in Azure Cosmos DB

+# Retrieval Augmented Generation (RAG) in Azure Cosmos DB

+Retrieval Augmented Generation (RAG) combines the power of large language models (LLMs) with robust information retrieval systems to create more accurate and contextually relevant responses. Unlike traditional generative models that rely solely on pre-trained data, RAG architectures enhance an LLM's capabilities by integrating real-time information retrieval. This augmentation ensures responses are not only generative but also grounded in the most relevant, up-to-date data available.

+Azure Cosmos DB, an operational database that supports vector search, stands out as an excellent platform for implementing RAG. Its ability to handle both operational and analytical workloads in a single database, along with advanced features such as multitenancy and hierarchical partition keys, provides a solid foundation for building sophisticated generative AI applications.

+## Key Advantages of Using Azure Cosmos DB

+### Unified data storage and retrieval

+Azure Cosmos DB enables seamless integration of [vector search](../nosql/vector-search.md) capabilities within a unified database system. This means that your operational data and vectorized data coexist, eliminating the need for separate indexing systems.

+### Real-Time data ingestion and querying

+Azure Cosmos DB supports real-time ingestion and querying, making it ideal for AI applications. This is crucial for RAG architectures, where the freshness of data can significantly impact the relevance of generated responses.

+### Scalability and global distribution

+Designed for large-scale applications, Azure Cosmos DB offers global distribution and [instant autoscale](../../cosmos-db/provision-throughput-autoscale.md). This ensures that your RAG-enabled application can handle high query volumes and deliver consistent performance irrespective of user location.

+### High availability and reliability

+Azure Cosmos DB offers comprehensive SLAs for throughput, latency, and [availability](../../reliability/reliability-cosmos-db-nosql.md). This reliability ensures that your RAG system is always available to generate responses with minimal downtime.

+### Multitenancy with hierarchical partition keys

+Azure Cosmos DB supports [multitenancy](../nosql/multi-tenancy-vector-search.md) through various performance and security isolation models, making it easier to manage data for different clients or user groups within the same database. This feature is particularly useful for SaaS applications where separation of tenant data is crucial for security and compliance.

+### Comprehensive security features

+With built-in features such as end-to-end encryption, role-based access control (RBAC), and virtual network (VNet) integration, Azure Cosmos DB ensures that your data remains secure. These security measures are essential for enterprise-grade RAG applications that handle sensitive information.

+## Implementing RAG with Azure Cosmos DB

+> [!TIP]

+> For RAG samples, visit: [AzureDataRetrievalAugmentedGenerationSamples](https://github.com/microsoft/AzureDataRetrievalAugmentedGenerationSamples)

+Here's a streamlined process for building a RAG application with Azure Cosmos DB:

+1. **Data Ingestion**: Store your documents, images, and other content types in Azure Cosmos DB. Utilize the database's support for vector search to index and retrieve vectorized content.

+2. **Query Execution**: When a user submits a query, Azure Cosmos DB can quickly retrieve the most relevant data using its vector search capabilities.

+3. **LLM Integration**: Pass the retrieved data to an LLM (e.g., Azure OpenAI) to generate a response. The well-structured data provided by Cosmos DB enhances the quality of the model's output.

+4. **Response Generation**: The LLM processes the data and generates a comprehensive response, which is then delivered to the user.

+## Related content

+- [What is a vector database?](../vector-database.md)

+- [Vector database in Azure Cosmos DB NoSQL](../nosql/vector-search.md)

+- [Vector database in Azure Cosmos DB for MongoDB](../mongodb/vcore/vector-search.md)

+- LLM [tokens](tokens.md)

+- Vector [embeddings](vector-embeddings.md)

+- [Distance functions](distance-functions.md)

+- [kNN vs ANN vector search algorithms](knn-vs-ann.md)

+- [Multitenancy for Vector Search](../nosql/multi-tenancy-vector-search.md)

+- [Retrieval Augmented Generation (RAG)](rag.md)

+- [Retrieval Augmented Generation (RAG)](rag.md)

+- [Retrieval Augmented Generation (RAG)](rag.md)

+- [Multi-tenancy for Vector Search](../nosql/multi-tenancy-vector-search.md)

+> Previously, role-based access was only supported in Cosmos Explorer using `https://cosmos.azure.com/?feature.enableAadDataPlane=true`. This is still supported and will override the value of the **Enable Entra ID RBAC** setting. Using this query parameter is equivalent to using the 'True' mode mentioned above.

+ Title: Multitenancy in Azure Cosmos DB

+description: Learn concepts for building multitenant gen-ai apps in Azure Cosmos DB

+# Multitenancy for vector search in Azure Cosmos DB

+> "OpenAI relies on Cosmos DB to dynamically scale their ChatGPT service ΓÇô one of the fastest-growing consumer apps ever ΓÇô enabling high reliability and low maintenance."

+> ΓÇö Satya Nadella

+Azure Cosmos DB stands out as the world's first full-featured serverless operational database with vector search, offering unparalleled scalability and performance. By using Azure Cosmos DB, users can enhance their vector search capabilities, ensuring high reliability and low maintenance for multitenant applications.

+Multitenancy enables a single instance of a database to serve multiple customers, or tenants, simultaneously. This approach efficiently shares infrastructure and operational overhead, resulting in cost savings and simplified management. It's a crucial design consideration for SaaS applications and some internal enterprise solutions.

+Multitenancy introduces complexity. Your system must scale efficiently to maintain high performance across all tenants, who may have unique workloads, requirements, and service-level agreements (SLAs).

+Imagine a fictional AI-assisted research platform called ResearchHub. Serving thousands of companies and individual researchers, ResearchHub manages varying user bases, data scales, and SLAs. Ensuring low query latency and high performance is vital for sustaining an excellent user experience.

+Azure Cosmos DB, with its [DiskANN vector index](../index-policy.md#vector-indexes) capability, simplifies multitenant design, providing efficient data storage and access mechanisms for high-performance applications.

+## Multi-tenancy models in Azure Cosmos DB

+In Azure Cosmos DB, we recommend two primary approaches to managing multi-tenancy: partition key-per-tenant or account-per-tenant, each with its own set of benefits and trade-offs.

+### 1. Partition key-per-tenant

+For a higher density of tenants and lower isolation, the partition key-per-tenant model is effective. Each tenant is assigned a unique partition key within a given container, allowing logical separation of data. This strategy works best when each tenant has roughly the same workload volume. If there is significant skew, customers should consider isolating those tenants in their own account. Additionally, if a single tenant has more than 20GB of data, [hierarchical partition keys (HPK)](#hierarchical-partitioning-enhanced-data-organization) should be used. For vector search in particular, quantizedFlat index may perform very well if vector search queries can be focused to a particular partition or sets of partitions.

+**Benefits:**

+- **Cost Efficiency:** Sharing a single Cosmos DB account across multiple tenants reduces overhead.

+- **Scalability:** Can manage a large number of tenants, each isolated within their partition key.

+- **Simplified Management:** Fewer Cosmos DB accounts to manage.

+- **Hierarchical Partition Keys (HPK):** Optimizes data organization and query performance in multi-tenant apps with a high number of tenants.

+**Drawbacks:**

+- **Resource Contention:** Shared resources can lead to contention during peak usage.

+- **Limited Isolation:** Logical but not physical isolation, which may not meet strict isolation requirements.

+- **Less Flexibility:** Reduced flexibility per tenant for enabling account-level features like geo-replication, point-in-time restore (PITR), and customer-managed keys (CMK).

+### Hierarchical partitioning: enhanced data organization

+[Hierarchical partitioning](../hierarchical-partition-keys.md) builds on the partition key-per-tenant model, adding deeper levels of data organization. This method involves creating multiple levels of partition keys for more granular data management. The lowest level of hierarchical partitioning should have high cardinality. Typically, it is recommended to use an ID/guid for this level to ensure continuous scalability beyond 20GB per tenant.

+**Advantages:**

+- **Optimized Queries:** More precise targeting of subpartitions at the parent partition level reduces query latency.

+- **Improved Scalability:** Facilitates deeper data segmentation for easier scaling.

+- **Better Resource Allocation:** Evenly distributes workloads, minimizing bottlenecks for high tenant counts.

+**Considerations:**

+- If applications have very few tenants and use hierarchical partitioning, this can lead to bottlenecks since all documents with the same first-level key will write to the same physical partition(s).

+**Example:**

+ResearchHub can stratify data within each tenantΓÇÖs partition by organizing it at various levels such as "DepartmentId" and "ResearcherId," facilitating efficient management and queries.

+

+### 2. Account-per-tenant

+For maximum isolation, the account-per-tenant model is preferable. Each tenant gets a dedicated Cosmos DB account, ensuring complete separation of resources.

+**Benefits:**

+- **High Isolation:** No contention or interference due to dedicated resources.

+- **Custom SLAs:** Resources and SLAs can be tailored to individual tenant needs.

+- **Enhanced Security:** Physical data isolation ensures robust security.

+- **Flexibility:** Tenants can enable account-level features like geo-replication, point-in-time restore (PITR), and customer-managed keys (CMK) as needed.

+**Drawbacks:**

+- **Increased Management:** Higher complexity in managing multiple Cosmos DB accounts.

+- **Higher Costs:** More accounts mean higher infrastructure costs.

+## Security isolation with customer-managed keys

+Azure Cosmos DB enables [customer-managed keys](../how-to-setup-customer-managed-keys.md) for data encryption, adding an extra layer of security for multitenant environments.

+**Steps to Implement:**

+- **Set Up Azure Key Vault:** Securely store your encryption keys.

+- **Link to Cosmos DB:** Associate your Key Vault with your Cosmos DB account.

+- **Rotate Keys Regularly:** Enhance security by routinely updating your keys.

+Using customer-managed keys ensures each tenant's data is encrypted uniquely, providing robust security and compliance.

+

+## Other isolation models

+### Container and database isolation

+In addition to the partition key-per-tenant and account-per-tenant models, Azure Cosmos DB provides other isolation methods such as container isolation and database isolation. These approaches offer varying degrees of performance isolation, though they don't provide the same level of security isolation as the account-per-tenant model.

+#### Container isolation

+In the container isolation model, each tenant is assigned a separate container within a shared Cosmos DB account. This model allows for some level of isolation in terms of performance and resource allocation.

+**Benefits:**

+- **Better Performance Isolation:** Containers can be allocated specific performance resources, minimizing the impact of one tenantΓÇÖs workload on another.

+- **Easier Management:** Managing multiple containers within a single account is generally easier than managing multiple accounts.

+- **Cost Efficiency:** Similar to the partition key-per-tenant model, this method reduces the overhead of multiple accounts.

+**Drawbacks:**

+- **Limited Security Isolation:** Unlike separate accounts, containers within the same account don't provide physical data isolation. So, this model may not meet stringent security requirements.

+- **Resource Contention:** Heavy workloads in one container can still affect others if resource limits are breached.

+#### Database isolation

+The database isolation model assigns each tenant a separate database within a shared Cosmos DB account. This provides enhanced isolation in terms of resource allocation and management.

+**Benefits:**

+- **Enhanced Performance:** Separate databases reduce the risk of resource contention, offering better performance isolation.

+- **Flexible Resource Allocation:** Resources can be allocated and managed at the database level, providing tailored performance capabilities.

+- **Centralized Management:** Easier to manage compared to multiple accounts, yet offering more isolation than container-level separation.

+**Drawbacks:**

+- **Limited Security Isolation:** Similar to container isolation, having separate databases within a single account does not provide physical data isolation.

+- **Complexity:** Managing multiple databases can be more complex than managing containers, especially as the number of tenants grows.

+While container and database isolation models don't offer the same level of security isolation as the account-per-tenant model, they can still be useful for achieving performance isolation and flexible resource management. These methods are beneficial for scenarios where cost efficiency and simplified management are priorities, and stringent security isolation is not a critical requirement.

+By carefully evaluating the specific needs and constraints of your multitenant application, you can choose the most suitable isolation model in Azure Cosmos DB, balancing performance, security, and cost considerations to achieve the best results for your tenants.

+## Real-world implementation considerations

+When designing a multitenant system with Cosmos DB, consider these factors:

+- **Tenant Workload:** Evaluate data size and activity to select the appropriate isolation model.

+- **Performance Requirements:** Align your architecture with defined SLAs and performance metrics.

+- **Cost Management:** Balance infrastructure costs against the need for isolation and performance.

+- **Scalability:** Plan for growth by choosing scalable models.

+### Practical implementation in Azure Cosmos DB

+**Partition Key-Per-Tenant:**

+- **Assign Partition Keys:** Unique keys for each tenant ensure logical separation.

+- **Store Data:** Tenant data is confined to respective partition keys.

+- **Optimize Queries:** Use partition keys for efficient, targeted queries.

+**Hierarchical Partitioning:**

+- **Create Multi-Level Keys:** Further organize data within tenant partitions.

+- **Targeted Queries:** Enhance performance with precise sub-partition targeting.

+- **Manage Resources:** Distribute workloads evenly to prevent bottlenecks.

+**Account-Per-Tenant:**

+- **Provide Separate Accounts:** Each tenant gets a dedicated Cosmos DB account.

+- **Customize Resources:** Tailor performance and SLAs to tenant requirements.

+- **Ensure Security:** Physical data isolation offers robust security and compliance.

+## Best practices for using Azure Cosmos DB with vector search

+Azure Cosmos DB's support for DiskANN vector index capability makes it an excellent choice for applications that require fast, high-dimensional searches, such as AI-assisted research platforms like ResearchHub. HereΓÇÖs how you can leverage these capabilities:

+**Efficient Storage and Retrieval:**

+ - **Vector Indexing:** Use the DiskANN vector index to efficiently store and retrieve high-dimensional vectors. This is useful for applications that involve similarity searches in large datasets, such as image recognition or document similarity.

+ - **Performance Optimization:** DiskANNΓÇÖs vector search capabilities enable quick, accurate searches, ensuring low latency and high performance, which is critical for maintaining a good user experience.

+**Scaling Across Tenants:**

+ - **Partition Key-Per-Tenant:** Utilize partition keys to logically isolate tenant data while benefiting from Cosmos DBΓÇÖs scalable infrastructure.

+ - **Hierarchical Partitioning:** Implement hierarchical partitioning to further segment data within each tenantΓÇÖs partition, improving query performance and resource distribution.

+**Security and Compliance:**

+ - **Customer-Managed Keys:** Implement customer-managed keys for data encryption at rest, ensuring each tenantΓÇÖs data is securely isolated.

+ - **Regular Key Rotation:** Enhance security by regularly rotating encryption keys stored in Azure Key Vault.

+### Real-world example: implementing ResearchHub

+**Partition Key-Per-Tenant:**

+- **Assign Partition Keys:** Each organization (tenant) is assigned a unique partition key.

+- **Data Storage:** All researchersΓÇÖ data for a tenant is stored within its partition, ensuring logical separation.

+- **Query Optimization:** Queries are executed using the tenant's partition key, enhancing performance by isolating data access.

+**Hierarchical Partitioning:**

+- **Multi-Level Partition Keys:** Data within a tenantΓÇÖs partition is further segmented by "DepartmentId" and "ResearcherId" or other relevant attributes.

+- **Granular Data Management:** This hierarchical approach allows ResearchHub to manage and query data more efficiently, reducing latency, and improving response times.

+**Account-Per-Tenant:**

+- **Separate Cosmos DB Accounts:** High-profile clients or those with sensitive data are provided individual Cosmos DB accounts.

+- **Custom Configurations:** Resources and SLAs are tailored to meet the specific needs of each tenant, ensuring optimal performance and security.

+- **Enhanced Data Security:** Physical separation of data with customer-managed encryption keys ensures robust security compliance.

+## Conclusion

+Multi-tenancy in Azure Cosmos DB, especially with its DiskANN vector index capability, offers a powerful solution for building scalable, high-performance AI applications. Whether you choose partition key-per-tenant, hierarchical partitioning, or account-per-tenant models, you can effectively balance cost, security, and performance. By using these models and best practices, you can ensure that your multitenant application meets the diverse needs of your customers, delivering an exceptional user experience.

+Azure Cosmos DB provides the tools necessary to build a robust, secure, and scalable multitenant environment. With the power of DiskANN vector indexing, you can deliver fast, high-dimensional searches that drive your AI applications.

+### Next steps

+[30-day Free Trial without Azure subscription](https://azure.microsoft.com/try/cosmosdb/)

+[Multitenancy and Azure Cosmos DB](https://aka.ms/CosmosMultitenancy)

+> [!div class="nextstepaction"]

+> [Use the Azure Cosmos DB lifetime free tier](../free-tier.md)

+## More vector database solutions

+- [Azure PostgreSQL Server pgvector Extension](../../postgresql/flexible-server/how-to-use-pgvector.md)

+Access to view the management group scope requires at least the Cost Management Reader (or Contributor) permission. You can configure permissions for a management group in the Azure portal. You must have at least the User Access Administrator (or Owner) permission for the management group to enable access for others. And for Azure EA accounts, you must also enable the **AO view charges** setting.

+You can assign the Cost Management Reader (or Contributor) role to a user at the management group scope. For more information, see [Assign Azure roles using the Azure portal](../../role-based-access-control/role-assignments-portal.yml).

+Access to a subscription requires at least the Cost Management Reader (or Contributor) permission. You can configure permissions to a subscription in the Azure portal. You must have at least the User Access Administrator (or Owner) permission for the subscription to enable access for others. And for Azure EA accounts, you must also enable the **AO view charges** setting.

+You can assign the Cost Management Reader (or Contributor) role to a user at the subscription scope. For more information, see [Assign Azure roles using the Azure portal](../../role-based-access-control/role-assignments-portal.yml).

+Access to a resource group requires at least the Cost Management Reader (or Contributor) permission. You can configure permissions to a resource group in the Azure portal. You must have at least the User Access Administrator (or Owner) permission for the resource group to enable access for others. And for Azure EA accounts, you must also enable the **AO view charges** setting.

+You can assign the Cost Management Reader (or Contributor) role to a user at the resource group scope. For more information, see [Assign Azure roles using the Azure portal](../../role-based-access-control/role-assignments-portal.yml).

+Subscriptions are shown for the directory that you're signed in to. If you have access to multiple directories, you can switch directories to view subscriptions for each directory.

+| type | The type property must be set to "Dynamics", "DynamicsCrm", or "CommonDataServiceForApps". | Yes |

+| deploymentType | The deployment type of the Dynamics instance. The value must be "OnPremisesWithIfd" for Dynamics on-premises with IFD.| Yes |

+| hostName | The host name of the on-premises Dynamics server. | Yes |

+| organizationName | The organization name of the Dynamics instance. | Yes |

+| authenticationType | The authentication type to connect to the Dynamics server. Specify "ActiveDirectoryAuthentication" for Dynamics on-premises with IFD. | Yes |

+| domain | The Active Directory domain that will verify user credentials. | Yes |

+| username | The username to connect to Dynamics. | Yes |

+| password | The password for the user account you specified for the username. You can mark this field with "SecureString" to store it securely. Or you can store a password in Key Vault and let the copy activity pull from there when it does data copy. Learn more from [Store credentials in Key Vault](store-credentials-in-key-vault.md). | Yes |

+>[!Note]

+>Due to the sunset of Idf authentication type by **August 31, 2024**, please upgrade to Active Directory Authentication type before the date if you are currently using it.

+

+#### Example: Dynamics on-premises with IFD using Active Directory authentication

+ "authenticationType": "ActiveDirectoryAuthentication",

+ "domain": "< Active Directory domain >",

+ - [Modify a rule](#modify-a-rule)

+ - [Delete a rule](#delete-a-rule)

+ - [Add a rule](#add-a-new-rule)

+## Modify a rule

+- A **Deny all traffic** rule is the only type of "deny" rule that would be listed here, and it cannot be modified. You can, however, delete it (see [Delete a rule](#delete-a-rule)). To learn about this type of rule, see the common questions entry [When should I use a "Deny all traffic" rule?](faq-defender-for-servers.yml).

+## Add a new rule

+## Delete a rule

+>

+> - Has Defender CSPM enabled.

+>

+Defenders for Cloud automatically and continuously discover deployed AI workloads across the following

+Defender for Cloud assesses your generative AI apps configuration and provides security recommendations to improve AI security posture.

+Detected misconfigurations should be remediated early in the development cycle to prevent more complex problems later on.

+Attack paths analysis detects and mitigates risks to AI workloads, particularly during grounding (linking AI models to specific data) and fine-tuning (adjusting a pretrained model on a specific dataset to improve its performance on a related task) stages, where data might be exposed.

+Permissions for security connectors are managed through Azure role-based access control (RBAC). You can assign roles to users, groups, and applications at a subscription, resource group, or resource level.

+ 1. Select the relevant resource connector.

+ - Recommendation severity.

+ - Security findings.

+ - Controls.

+| [External attack surface management](concept-easm.md) | - | :::image type="icon" source="./media/icons/yes-icon.png"::: | Azure, AWS, GCP |

+description: Learn about Defender for Cloud integration with Defender External attack surface management to enhance security and reduce the risk of attacks.

+#customer intent: As a reader, I want to learn about the integration between Defender for Cloud and Defender External attack surface management so that I can enhance my organization's security.

+Microsoft Defender for Cloud has the capability to perform external attack surface management, (outside-in) scans on multicloud environments. Defender for Cloud accomplishes this through its integration with [Microsoft Defender External Attack Surface Management](../external-attack-surface-management/overview.md). The integration allows organizations to improve their security posture while reducing the potential risk of being attacked by exploring their external attack surface. The integration is included with the Defender Cloud Security Posture Management (CSPM) plan by default and doesn't require a license from Defender External Attack Surface Management or any special configurations.

+Defender External Attack Surface Management applies MicrosoftΓÇÖs crawling technology to discover assets that are related to your known online infrastructure, and actively scans these assets to discover new connections over time. Attack Surface Insights are generated by applying vulnerability and infrastructure data to showcase the key areas of concern for your organization, such as:

+External Attack Surface Management collects data on publicly exposed assets (ΓÇ£outside-inΓÇ¥) which Defender for Cloud's Cloud Security Posture Management (CSPM) (ΓÇ£inside-outΓÇ¥) plan uses to assist with internet-exposure validation and discovery capabilities.

+Learn more about [Defender External Attack Surface Management](../external-attack-surface-management/overview.md).

+## External Attack Surface Management capabilities in Defender CSPM

+The [Defender CSPM](concept-cloud-security-posture-management.md) plan utilizes the data collected through the Defender External Attack Surface Management integration to provide the following capabilities within the Defender for Cloud portal:

+- [Deploy Defender External Attack Surface Management](../external-attack-surface-management/deploying-the-defender-easm-azure-resource.md).

+Onboarding permissions | To enable and onboard Defender for APIs, you will need [API Management Service Contributor](../api-management/api-management-role-based-access-control.md#built-in-service-roles) role access, along with the permissions outlined in the [User roles and permissions](permissions.md#roles-and-allowed-actions) for enabling Microsoft Defender plans.

+Microsoft Defender for Cloud's provides organizations the capability to perform external attack surface management (outside-in) scans to improve their security posture through its integration with Defender External Attack Surface Management. Defender for Cloud's external attack surface management scans uses the information provided by the Defender External Attack Surface Management integration to provide actionable recommendations and visualizations of attack paths to reduce the risk of bad actors exploiting internet exposed IP addresses.

+1. Map the API attack surface. Bright can parse and learn the exact valid structure of REST and GraphQL APIs, from an OAS file (swagger) or an Introspection (GraphQL schema description). In addition, Bright can learn API content from HAR files. These methods provide a comprehensive way to visualize the attack surface.

+1. On your OT sensor console, select **System settings** > **Network monitoring** and under **Active Discovery**, select **Reverse DNS Lookup**.

+## Define DNS servers

+Enhance device data enrichment by configuring multiple DNS servers to carryout reverse lookups and resolve host names or FQDNs associated with the IP addresses detected in network subnets. For example, if a sensor discovers an IP address, it might query multiple DNS servers to resolve the host name. You need the DNS server address, server port and the subnet addresses.

+**To define the DNS server lookup**:

+1. On your OT sensor console, select **System settings** > **Network monitoring** and under **Active Discovery**, select **Reverse DNS Lookup**.

+1. Use the **Schedule Reverse Lookup** options to define your scan as in fixed intervals, per hour, or at a specific time.

+ If you select **By specific times**, use a 24-hour clock, such as **14:30** for **2:30 PM**. Select the **+** button on the side to add additional, specific times that you want the lookup to run.

+1. Select **Add DNS Server**, and then populate your fields as needed to define the following fields:

+ - **DNS server address**, which is the DNS server IP address

+ - **DNS server port**

+ - **Number of labels**, which is the number of domain labels you want to display. To get this value, resolve the network IP address to device FQDNs. You can enter up to 30 characters in this field.

+ - **Subnets**, which is the subnets that you want the DNS server to query

+1. Toggle on the **Enabled** option at the top to start the reverse lookup query as scheduled, and then select **Save** to finish the configuration.

+For more information, see [Configure reverse DNS lookup](configure-reverse-dns-lookup.md).

+### Test the DNS configuration

+Use a test device to verify that the reverse DNS lookup settings you'd defined work as expected.

+1. On your sensor console, select **System settings** > **Network monitoring** and under **Active Discovery**, select **Reverse DNS Lookup**.

+1. Make sure that the **Enabled** toggle is selected.

+1. Select **Test**.

+1. In the **DNS reverse lookup test for server** dialog, enter an address in the **Lookup Address** and then select **Test**.

+ - These options prevent a lengthy search for and installation of drivers during the first boot. For more information, see [Sysprep Command-Line Options](/windows-hardware/manufacture/desktop/sysprep-command-line-options?view=windows-11#modevm&preserve-view=true).

+

+1. Enable the Read/Write cache on the OS disk.

+The Geo-disaster recovery feature of Azure Event Hubs is a disaster recovery solution. The concepts and workflow described in this article apply to disaster scenarios, and not to temporary outages. For a detailed discussion of disaster recovery in Microsoft Azure, see [this article](/azure/architecture/resiliency/disaster-recovery-azure-applications).

+The Geo-disaster recovery feature is available for the [standard, premium, and dedicated tiers](https://azure.microsoft.com/pricing/details/event-hubs/) only. You don't need to make any connection string changes, as the connection is made via an alias.

+- *Failover*: The process of activating the secondary namespace.

+> [!NOTE]

+> The Geo-disaster recovery feature doesn't support an automatic failover.

+Use the [`az eventhubs georecovery-alias fail-over`](/cli/azure/eventhubs/georecovery-alias#az-eventhubs-georecovery-alias-fail-over) command.

+Use the [`Set-AzEventHubGeoDRConfigurationFailOver`](/powershell/module/az.eventhub/set-azeventhubgeodrconfigurationfailover) cmdlet.

+Use the [`DisasterRecoveryConfigsOperationsExtensions.FailOverAsync`](/dotnet/api/microsoft.azure.management.eventhub.disasterrecoveryconfigsoperationsextensions.failoverasync#Microsoft_Azure_Management_EventHub_DisasterRecoveryConfigsOperationsExtensions_FailOverAsync_Microsoft_Azure_Management_EventHub_IDisasterRecoveryConfigsOperations_System_String_System_String_System_String_System_Threading_CancellationToken_) method.

+For the sample code that uses this method, see the [`GeoDRClient`](https://github.com/Azure/azure-event-hubs/blob/3cb13d5d87385b97121144b0615bec5109415c5a/samples/Management/DotNet/GeoDRClient/GeoDRClient/GeoDisasterRecoveryClient.cs#L137) sample in GitHub.

+1. By design, Event Hubs geo-disaster recovery doesn't replicate data, and therefore you can't reuse the old offset value of your primary event hub on your secondary event hub. We recommend restarting your event receiver with one of the following methods:

+3. The fact that no data is replicated means that current active sessions aren't replicated. Additionally, duplicate detection and scheduled messages might not work. New sessions, scheduled messages, and new duplicates will work.

+Let's say you have two virtual networks: `VNET-1`, `VNET-2` and these primary and secondary namespaces: `EventHubs-Namespace1-Primary`, `EventHubs-Namespace2-Secondary`. You need to do the following steps:

+- On `EventHubs-Namespace1-Primary`, create two private endpoints that use subnets from `VNET-1` and `VNET-2`

+- On `EventHubs-Namespace2-Secondary`, create two private endpoints that use the same subnets from `VNET-1` and `VNET-2`

+**Application-only failover:** Here, the application won't exist in `VNET-1` but will move to `VNET-2`. As both private endpoints are configured on both `VNET-1` and `VNET-2` for both primary and secondary namespaces, the application will just work.

+Azure ExpressRoute is an essential hybrid connectivity service widely used for its low latency, resilience, high throughput private connectivity between your on-premises network and Azure workloads. It offers the ability to achieve reliability, resiliency, and disaster recovery in network connections between on-premises and Azure to ensure availability of business and mission-critical workloads. This capability also extends access to Azure resources in a scalable, and cost-effective way.

+* [High resiliency](#high-resiliencyin-preview)

+The Maximum resiliency architecture in ExpressRoute is structured to eliminate any single point of failure within the Microsoft network path. This set up is achieved by configuring a pair of circuits across two distinct locations for site diversity with ExpressRoute. The objective of Maximum resiliency is to enhance reliability, resiliency, and availability, as a result ensuring the highest level of resilience for business and/or mission-critical workloads. For such operations, we recommend that you configure maximum resiliency. This architectural design is recommended as part of the [Well Architected Framework](/azure/well-architected/service-guides/azure-expressroute#reliability) under the reliability pillar. The ExpressRoute engineering team developed a [guided portal experience](expressroute-howto-circuit-portal-resource-manager.md?pivots=expressroute-preview) to assist you in configuring maximum resiliency.

+### High resiliency - In Preview

+High resiliency, also referred to as ExpressRoute Metro, enables the use of multiple sites within the same metropolitan (Metro) area to connect your on-premises network through ExpressRoute to Azure. High resiliency offers site diversity by splitting a single circuit across two sites. The first connection is established at one site and the second connection at a different site. The objective of ExpressRoute Metro is to mitigate the effect of edge-sites isolation and failures by introducing capabilities to enable site diversity. Site diversity is achieved by using a single circuit across paired sites within a metropolitan city, which offers resiliency to failures between edge and region. ExpressRoute Metro provides a higher level of site resiliency than Standard resiliency, but not as much as Maximum resiliency. ExpressRoute Metro architecture can be used for business and mission-critical workloads within a region. For more information, see [ExpressRoute Metro](metro.md)

+Microsoft offers multiple ExpressRoute peering locations in many geopolitical regions. For maximum resiliency, Microsoft recommends that you establish connection to two ExpressRoute circuits in two peering locations. For non-production and non-critical workloads, you can achieve standard resiliency by connecting to a single ExpressRoute circuit that offers redundant connections within a single peering location. The Azure portal provides a guided experience to help you create a resilient ExpressRoute configuration. For Azure PowerShell, CLI, ARM template, Terraform, and Bicep, maximum resiliency can be achieved by creating a second ExpressRoute circuit in a different ExpressRoute location and establishing a connection to it. For more information, see [Create maximum resiliency with ExpressRoute](expressroute-howto-circuit-portal-resource-manager.md?pivots=expressroute-preview).

+ > * During configuration, the Azure portal doesn't validate if the origin is accessible from Azure Front Door environments. You need to verify that Azure Front Door can reach your origin.

+ > * When an origin is **disabled**, both routing and health probes to the origin are also disabled.

+> [!IMPORTANT]

+> When an origin is **disabled**, both routing and health probes to the origin are also disabled.

+It's possible to port the open-source DU agent code to run on other OS versions but these agent builds aren't tested and maintained by Microsoft.

+| Debian 11 (Bullseye) |  |  |  |

+| Ubuntu Server 22.04 |  | |  |

+Device Update for IoT Hub release assets and release notes are available on the [Device Update Release](https://github.com/Azure/iot-hub-device-update/releases) page. Support for the APIs, PnP Models, and device update reference agents is covered in the table.

+Newer REST Service API versions support older agents unless specified. Device Update for IoT Hub portal experience uses the latest APIs and have the same support as the API version.

+The latest API version, 2022-10-01 will be supported until the next stable release and the latest agent version, 1.0.x, will receive bug fixes and security fixes until the next stable release.

+Device Update agents are built and provided for [various Linux OSs](support.md). Device Update for IoT Hub also provides open-source code if you aren't

+[Tutorial: Device Update using the simulator agent](device-update-simulator.md)

+| opType | deviceConnected or deviceDisconnected |

+> Full restore is a very destructive and disruptive operation. Therefore it is mandatory to have completed a full backup of the HSM you are restoring to at least 30 minutes prior to a `restore` operation can be performed.

+Selective key restore allows you to restore one individual key with all its key versions from a previous backup to an HSM. The key must be purged in order for selective key restore to work. If you are attempting to recover a soft-deleted key, use key recover. Learn more about [key recover](key-management.md).

+- An exclusive cryptographic boundary for each customer composed of three [Intel Secure Guard Extensions (Intel SGX)](https://www.intel.com/content/www/us/en/architecture-and-technology/software-guard-extensions.html) confidential enclaves connected to three FIPS 140-2 Level 3 compliant HSM instances. The root keys for this boundary are generated and stored in the three HSMs. As we describe later in this article, no person associated with Microsoft has access to the data that's within this boundary. Only service code that's running in the Intel SGX enclave (including the Node Service agent), acting on behalf of the customer, has access.

+description: To deploy policies that use a remediation task via Azure Lighthouse, you need to create a managed identity in the customer tenant.

+[Azure Lighthouse](../overview.md) allows service providers to create and edit policy definitions within a delegated subscription. To deploy policies that use a [remediation task](../../governance/policy/how-to/remediate-resources.md) (that is, policies with the [deployIfNotExists](../../governance/policy/concepts/effect-deploy-if-not-exists.md) or [modify](../../governance/policy/concepts/effect-modify.md) effect), you must create a [managed identity](../../active-directory/managed-identities-azure-resources/overview.md) in the customer tenant. This managed identity can be used by Azure Policy to deploy the template within the policy. This article describes the steps that are required to enable this scenario, both when you onboard the customer for Azure Lighthouse, and when you deploy the policy itself.

+To allow a **principalId** to assign roles to a managed identity in the customer tenant, you must set its **roleDefinitionId** to **User Access Administrator**. While this role isn't generally supported for Azure Lighthouse, it can be used in this specific scenario. Granting this role to this **principalId** allows it to assign specific built-in roles to managed identities. These roles are defined in the **delegatedRoleDefinitionIds** property, and can include any [supported Azure built-in role](../concepts/tenants-users-roles.md#role-support-for-azure-lighthouse) except for User Access Administrator or Owner.

+After the customer is onboarded, the **principalId** created in this authorization will be able to assign these built-in roles to managed identities in the customer tenant. It won't any other permissions normally associated with the User Access Administrator role.

+This example shows a **principalId** with the User Access Administrator role. This user will be able to assign two built-in roles to managed identities in the customer tenant: Contributor and Log Analytics Contributor.

+After you create the user with the necessary permissions, that user can deploy policies that use remediation tasks within delegated customer subscriptions.

+> You can manage delegated resources that are located in different [regions](../../availability-zones/az-overview.md#regions). However, you can't delegate resources across a national cloud and the Azure public cloud, or across two separate [national clouds](../../active-directory/develop/authentication-national-cloud.md).

+- Data from all data sources and data connectors that are integrated with Microsoft Sentinel (such as Microsoft Entra Activity Logs, Office 365 logs, or Microsoft Threat Protection alerts) remains within each customer tenant.

+> If workspaces are only created in customer tenants, the **Microsoft.SecurityInsights** and **Microsoft.OperationalInsights** resource providers must also be [registered](../../azure-resource-manager/management/resource-providers-and-types.md#register-resource-provider) on a subscription in the managing tenant.

+When creating your authorizations, you can assign Microsoft Sentinel built-in roles to users, groups, or service principals in your managing tenant. Common roles include:

+You may also want to assign other built-in roles to perform additional functions. For information about specific roles that can be used with Microsoft Sentinel, see [Roles and permissions in Microsoft Sentinel](../../sentinel/roles.md).

+After you onboard your customers, designated users can log into your managing tenant and [directly access the customer's Microsoft Sentinel workspace](../../sentinel/multiple-tenants-service-providers.md#how-to-access-microsoft-sentinel-in-managed-tenants) with the roles that were assigned.

+> Be sure that the users in your managing tenant have been assigned both read and write permissions on all of the managed workspaces. If a user only has read permissions on some workspaces, warning messages may appear when selecting incidents in those workspaces, and the user won't be able to modify those incidents or any others selected along with them (even if the user has write permissions for the others).

+For more information, see [Query multiple workspace](../../sentinel/extend-sentinel-across-workspaces-tenants.md#query-multiple-workspaces).

+You can use automation to manage multiple Microsoft Sentinel workspaces and configure [hunting queries](../../sentinel/hunting.md), playbooks, and workbooks. For more information, see [Manage multiple workspaces using automation](../../sentinel/extend-sentinel-across-workspaces-tenants.md#manage-multiple-workspaces-using-automation).

+Use Azure Lighthouse with Microsoft Sentinel to monitor the security of Office 365 environments across tenants. First, enable out-of-the-box [Office 365 data connectors](../../sentinel/data-connectors/office-365.md) in the managed tenant. Information about user and admin activities in Exchange and SharePoint (including OneDrive) can then be ingested to a Microsoft Sentinel workspace within the managed tenant. This information includes details about actions such as file downloads, access requests sent, changes to group events, and mailbox operations, along with details about the users who performed those actions. [Office 365 DLP alerts](https://techcommunity.microsoft.com/t5/azure-sentinel/ingest-office-365-dlp-events-into-azure-sentinel/ba-p/1031820) are also supported as part of the built-in Office 365 connector.

+The [Microsoft Defender for Cloud Apps connector](../../sentinel/data-connectors/microsoft-defender-for-cloud-apps.md) lets you stream alerts and Cloud Discovery logs into Microsoft Sentinel. This connector offers visibility into cloud apps, provides sophisticated analytics to identify and combat cyberthreats, and helps you control how data travels. Activity logs for Defender for Cloud Apps can be [consumed using the Common Event Format (CEF)](https://techcommunity.microsoft.com/t5/azure-sentinel/ingest-box-com-activity-events-via-microsoft-cloud-app-security/ba-p/1072849).

+When working with customers, you might want to protect intellectual property developed in Microsoft Sentinel, such as Microsoft Sentinel analytics rules, hunting queries, playbooks, and workbooks. There are different methods you can use to ensure that customers don't have complete access to the code used in these resources.

+Depending on your scenario, you can create the Azure Migrate project in the customer tenant or in your managing tenant. This article describes each model so you can determine which one best fits your customers' migration needs.

+One option when using Azure Lighthouse is to create the Azure Migrate project in the customer tenant. Users in the managing tenant can then select the customer subscription when creating a migration project. From the managing tenant, the service provider can perform the necessary migration operations. Examples of these operations are deploying the Azure Migrate appliance to discover the workloads, assessing workloads by grouping VMs and calculating cloud-related costs, reviewing VM readiness, and performing the actual migration.

+In this scenario, no resources are created or stored in the managing tenant, even though the discovery and assessment steps are initiated and executed from that tenant. All of the resources, such as migration projects, assessment reports for on-premises workloads, and migrated resources at the target destination, are deployed in the delegated customer subscription. The service provider can access all customer projects from their own tenant and portal experience.

+A high-level workflow for this model is:

+1. The customer is [onboarded to Azure Lighthouse](onboard-customer.md). The Contributor built-in role is required for the identity that will be used with Azure Migrate. See the [delegated-resource-management-azmigrate](https://github.com/Azure/Azure-Lighthouse-samples/tree/master/templates/delegated-resource-management-azmigrate) sample template for an example using this role. Before deploying the template, be sure to modify the parameter file to reflect your environment.

+ > For migration of VMware virtual machines, only the agent-based method is currently supported when working in a delegated customer subscription.

+1. When the target customer subscription is ready, proceed with the migration through the access granted by Azure Lighthouse. The migration project containing assessment results and migrated resources are created in the customer tenant under the target subscription.

+In this scenario, the migration project and all of the relevant resources reside in the managing tenant. Customers don't have direct access to the migration project, although assessments can be shared with customers if desired. As with the previous scenario, migration-related operations such as discovery and assessment are performed by users in the managing tenant, and the migration destination for each customer is the target subscription in their tenant.

+A high-level workflow for this model is:

+1. The customer is [onboarded to Azure Lighthouse](onboard-customer.md). The Contributor built-in role is required for the identity that will be used with Azure Migrate. See the [delegated-resource-management-azmigrate](https://github.com/Azure/Azure-Lighthouse-samples/tree/master/templates/delegated-resource-management-azmigrate) sample template for an example using this role. Before deploying the template, be sure to modify the parameter file to reflect your environment.

+1. The user then [performs steps for discovery and assessment](../../migrate/tutorial-discover-vmware.md). The on-premises VMs are discovered and assessed within the migration project created in the managing tenant, then migrated from there.

+ If you manage multiple customers in the same Hyper-V host, you can discover all workloads at once. You can select customer-specific VMs in the same group, and then create an assessment. Migration is performed by selecting the appropriate customer's subscription as the target destination. There's no need to limit the discovery scope, and you can maintain a full overview of all customer workloads in one migration project.

+1. When ready, proceed with the migration by selecting the delegated customer subscription as the target destination for replicating and migrating the workloads. The new resources are created in the customer subscription, while assessment data and resources pertaining to the migration project remain in the managing tenant.

+As a member of the [Microsoft Cloud Partner Program](https://partner.microsoft.com), you can link your partner ID with the credentials used to manage delegated customer resources. This link allows Microsoft to attribute influence and Azure consumed revenue to your organization based on the tasks you perform for customers, including migration projects.

+This topic explains how to use [Azure Policy](../../governance/policy/index.yml) to deploy a policy definition and policy assignment across multiple tenants using PowerShell commands. In this example, the policy definition ensures that storage accounts are secured by allowing only HTTPS traffic. You can use the same general process for any policy that you want to deploy.

+You can use [Azure Resource Graph](../../governance/resource-graph/overview.md) to query across all subscriptions in customer tenants that you manage. In this example, we'll identify any storage accounts in these subscriptions that don't currently require HTTPS traffic.

+The following example shows how to use an [Azure Resource Manager template](https://github.com/Azure/Azure-Lighthouse-samples/blob/master/templates/policy-enforce-https-storage/enforceHttpsStorage.json) to deploy a policy definition and policy assignment across delegated subscriptions in multiple customer tenants. This policy definition requires all storage accounts to use HTTPS traffic. It prevents the creation of any new storage accounts that don't comply. Any existing storage accounts without the setting are marked as noncompliant.

+When you're finished, you can remove the policy definition and assignment created by the deployment.

+If youΓÇÖre using a public standard load balancer and experience SNAT exhaustion or connection failures, ensure youΓÇÖre using outbound rules with manual port allocation. Otherwise, youΓÇÖre likely relying on load balancerΓÇÖs default port allocation. Default port allocation automatically assigns a conservative number of ports, which is based on the number of instances in your backend pool. Default port allocation isn't a recommended method for enabling outbound connections. When your backend pool scales, your connections may be impacted if ports need to be reallocated.

+To learn more about default port allocation, see [Source Network Address Translation for outbound connections](load-balancer-outbound-connections.md).

+> [!IMPORTANT]

+> Retrieving customer-managed keys from a private Azure key vault that has access restrictions is currently not supported in **US Gov Virginia** region.

+ |Azure Key Vault (when using [access policies permission model](../../key-vault/general/assign-access-policy.md))|Contributor + any access policy permissions besides **purge** operations, this is `default mode` for linked Azure Key Vault.|

+To use credential-less storage in Azure AI studio. You need basically do following things:

+- Change the data store auth type to None.

+- Grant project MSI and user blob/file data contributor permission on storage.

+- If you still can't view the flow detail page and the first time you using prompt flow is earlier than 2024-01-01, you need to grant workspace MSI as `Storage Table Data Contributor` to storage account linked with workspace.

+> * [Jais](deploy-jais-models.md) family of models

+> * [Jamba](how-to-deploy-models-jamba.md) family of models

+> [!NOTE]

+> The Azure AI model inference API is available in managed inference (Managed Online Endpoints) for __models deployed after June 24th, 2024__. To take advance of the API, redeploy your endpoint if the model has been deployed before such date.

+If you are using an endpoint with support for Entra ID, you can create your client as follows:

+```python

+import os

+from azure.ai.inference import ChatCompletionsClient

+from azure.identity import AzureDefaultCredential

+model = ChatCompletionsClient(

+ endpoint=os.environ["AZUREAI_ENDPOINT_URL"],

+ credential=AzureDefaultCredential(),

+)

+```

+For endpoint with support for Microsoft Entra ID, you can create your client as follows:

+```javascript

+import ModelClient from "@azure-rest/ai-inference";

+import { isUnexpected } from "@azure-rest/ai-inference";

+import { AzureDefaultCredential } from "@azure/identity";

+const client = new ModelClient(

+ process.env.AZUREAI_ENDPOINT_URL,

+ new AzureDefaultCredential()

+);

+```

+print(response.choices[0].message.content)

+> [!TIP]

+> When using Azure AI Inference SDK, using `model_extras` configures the request with `extra-parameters: pass-through` automatically for you.

+console.log(response.choices[0].message.content)

+> [!NOTE]

+> The default value for `extra-parameters` is `error` which returns an error if an extra parameter is indicated in the payload. Alternatively, you can set `extra-parameters: drop` to drop any unknown parameter in the request. Use this capability in case you happen to be sending requests with extra parameters that you know the model won't support but you want the request to completes anyway. A typical example of this is indicating `seed` parameter.

+from azure.ai.inference.models import SystemMessage, UserMessage, ChatCompletionsResponseFormat

+from azure.core.exceptions import HttpResponseError

+from azure.core.exceptions import HttpResponseError

+> [!NOTE]

+> Azure Machine Learning model monitoring (v2) provides improved capabilities for data drift along with additional functionalities for monitoring signals and metrics. To learn more about the capabilities of model monitoring in Azure Machine Learning (v2), see [Model monitoring with Azure Machine Learning](../concept-model-monitoring.md).

+1. Download and open the following Power BI template in the Power BI Desktop application [Network Watcher Power BI flow logs template](https://github.com/Azure/NWPublicScripts/raw/main/nw-public-docs-artifacts/nsg-flow-logs/PowerBI_FlowLogs_Storage_Template.pbit)

+We're pleased to announce the launch of OpenShift 4.14 for Azure Red Hat OpenShift. This release enables [OpenShift Container Platform 4.14](https://docs.openshift.com/container-platform/4.14/welcome/https://docsupdatetracker.net/index.html). Version 4.12 will be outside of support after July 17, 2024. Existing clusters on version 4.12 and below should be upgraded before then.

+ - This enables customers to select specific Y and Z version of the release. For more information about versions, see [Red Hat OpenShift versions](support-lifecycle.md#red-hat-openshift-versions).

+ - Customers can still deploy 4.10 clusters if that version is specified. For more information, see [Selecting a different ARO version](create-cluster.md#selecting-a-different-aro-version).

+|`location`|The Operator Nexus' Azure Region used during NFC Creation|eastus| True

+|`location`|The Operator Nexus' Azure Region used during NFC Creation|eastus|True|

+|`location`|The Operator Nexus' Azure Region used during NFC Creation|eastus | True

+|East US |&check; | &check;|

+|Germany West Central | &check;|&check; |

+|France Central |&check; | |

+|UK South |&check; |&check; |

+|Canada Central |&check; |&check; |

+## Monitor multiple subscriptions

+You can now monitor all your subscriptions through a single New Relic resource using **Monitored Subscriptions**. Your experience is simplified because you don't have to set up a New Relic resource in every subscription that you intend to monitor. You can monitor multiple subscriptions by linking them to a single New Relic resource that is tied to a New Relic organization. This provides a single pane view for all resources across multiple subscriptions.

+To manage multiple subscriptions that you want to monitor, select **Monitored Subscriptions** in the **New Relic New Relic organization configurations** section of the Resource menu.

+From **Monitored Subscriptions** in the Resource menu, select the **Add Subscriptions**. The **Add Subscriptions** experience that opens and shows the subscriptions you have _Owner_ role assigned to and any New Relic resource created in those subscriptions that is already linked to the same New Relic organization as the current resource.

+If the subscription you want to monitor has a resource already linked to the same New Relic org, we recommended that you delete the New Relic resources to avoid shipping duplicate data, and incurring double the charges.

+Select the subscriptions you want to monitor through the New Relic resource and select **Add**.

+If the list doesnΓÇÖt get updated automatically, select **Refresh** to view the subscriptions and their monitoring status. You might see an intermediate status of _In Progress_ while a subscription gets added. When the subscription is successfully added, you see the status is updated to **Active**. If a subscription fails to get added, **Monitoring Status** shows as **Failed**.

+The set of tag rules for metrics and logs defined for the New Relic resource apply to all subscriptions that are added for monitoring. Setting separate tag rules for different subscriptions isn't supported. Diagnostics settings are automatically added to resources in the added subscriptions that match the tag rules defined for the New Relic resource.

+If you have existing New Relic resources that are linked to the account for monitoring, you can end up with duplication of logs that can result in added charges. Ensure you delete redundant New Relic resources that are already linked to the account. You can view the list of connected resources and delete the redundant ones. We recommended to consolidate subscriptions into the same New Relic resource where possible.

+The tag rules and logs that you defined for the New Relic resource are applied to all the subscriptions that you select to be monitored. If you would like to reconfigure the tag rules, you can follow the steps described here.

+For more information about the following capabilities, see [Monitor Virtual Machines using the New Relic agent](#monitor-virtual-machines-by-using-the-new-relic-agent) and [Monitor App Services using the New Relic agent](#monitor-app-services-by-using-the-new-relic-agent).

+## Connected New Relic resources

+To access all New Relic resources and deployments you created using the Azure or New Relic portal experience, go to the **Connected New Relic resources** tab in any of your Azure New Relic resources.

+You can easily manage the corresponding New Relic deployments or Azure resources using the links, provided you have owner or contributor rights to those deployments and resources.

+### Limitations

+- Custom domains do not work with preview environments.

+- Pre-production environments aren't geo-distributed.

+Microsoft recommends that you configure immutability policies mainly for block blobs and append blobs. Configuring an immutability policy for a page blob that stores a VHD disk for an active virtual machine is discouraged as writes to the disk will be blocked, or if versioning is enabled, each write is stored as a new version. Microsoft recommends that you thoroughly review the documentation and test your scenarios before locking any time-based policies.

+This feature is incompatible with point in time restore and last access tracking. This feature is compatible with customer-managed unplanned failover, however, any changes that are made to the immutable policy after the last sync time (such as locking a time based retention policy, extending it, etc.) will not be synced to the secondary region. Once failover is completed, you can redo the changes to the secondary region to ensure it is up-to-date with your immutability requirements.

+> The NFS 3.0 protocol uses ports 111 and 2049. If you're connecting from an on-premises network, make sure that your client allows outgoing communication through those ports. If you have granted access to specific VNets, make sure that any network security groups associated with those VNets don't contain security rules that block incoming communication through those ports.

+1. Under **Data management**, choose **Data Protection**.

+- Australia Central

+- Brazil Southeast

+- Canada East

+- France South

+- East Asia

+- Southeast Asia

+- Japan East

+- Japan West

+- North Europe

+- West Europe

+- UK South

+| | **CloudCasa**<br>CloudCasa by Catalogic is an award-winning backup, recovery, migration, and replication service, built specifically for Kubernetes, and cloud native applications. It supports AKS, and all other major Kubernetes distributions, and managed services. <br><br>From a single dashboard, CloudCasa makes managing cross-cluster, cross-tenant, cross-region, and cross-cloud backup and recovery easy. With CloudCasa's Azure integration, cluster recoveries, and migrations include the ability to automatically re-create entire AKS clusters along with their vNETs, add-ons, and load balancers.|[Partner page](https://cloudcasa.io/partners/microsoft-azure/)<br>[Azure Marketplace](https://azuremarketplace.microsoft.com/marketplace/apps/catalogicsoftware1625626770507.cloudcasa-aks-app)|

+ The following table lists the metrics that you can use to define autoscale rules:

+ [!INCLUDE [microsoft-streamanalytics-streamingjobs-metrics-include](~/reusable-content/ce-skilling/azure/includes/azure-monitor/reference/metrics/microsoft-streamanalytics-streamingjobs-metrics-include.md)]

+See [Troubleshoot Azure Stream Analytics by using diagnostics logs](monitor-azure-stream-analytics-reference.md#resource-logs-schema) to see the schema for resource logs. The following JSON is an example value for the **Properties** field of a resource log for a data error.

+3. Select the name of the input data source from the dropdown to see input metrics. The input source in the screenshot below is called *quotes*. For more information about input metrics, see [Azure Stream Analytics job metrics](monitor-azure-stream-analytics-reference.md#metrics).

+5. Select an output in the diagram or from the dropdown to see output-related metrics. For more information about output metrics, see [Azure Stream Analytics job metrics](monitor-azure-stream-analytics-reference.md#metrics). Live output sinks aren't supported.

+* [Azure Stream Analytics job metrics](monitor-azure-stream-analytics-reference.md#metrics)

+* [Azure Stream Analytics metrics dimensions](monitor-azure-stream-analytics-reference.md#metric-dimensions)

+* **Physical diagram**: it visualizes the key metrics of Stream Analytics job with the physical computation concept: streaming node dimension. A streaming node represents a set of compute resources that's used to process job's input data. To learn more details about the streaming node dimension, see [Azure Stream Analytics node name dimension](monitor-azure-stream-analytics-reference.md#node-name-dimension).

+ For more information about the metrics definition, see [Azure Stream Analytics node name dimension](monitor-azure-stream-analytics-reference.md#node-name-dimension).

+2. **Diagram section**: the node box in this selection represents the job's input, output, and query steps. You can view the metrics in the node directly or in the chart section interactively by clicking certain node in this section. For more information about the metrics definition, see [Azure Stream Analytics node name dimension](monitor-azure-stream-analytics-reference.md#node-name-dimension).

+* [Azure Stream Analytics job metrics](monitor-azure-stream-analytics-reference.md#metrics)

+| **Running** | Your job is running on Azure reading events coming from the defined input sources, processing them and writing the results to the configured output sinks. | It's a best practice to track your jobΓÇÖs performance by monitoring [key metrics](monitor-azure-stream-analytics.md#azure-stream-analytics-metrics). |

+| **Degraded** | There might be intermittent issues with your input and output connections. These errors are called transient errors that might make your job enter a Degraded state. Stream Analytics will immediately try to recover from such errors and return to a Running state (within few minutes). These errors could happen due to network issues, availability of other Azure resources, deserialization errors etc. Your jobΓÇÖs performance may be impacted when job is in degraded state.| You can look at the [diagnostic or activity logs](./stream-analytics-job-diagnostic-logs.md#debugging-using-activity-logs) to learn more about the cause of these transient errors. In cases such as deserialization errors, it's recommended to take corrective action to ensure events aren't malformed. If the job keeps reaching the resource utilization limit, try to increase the SU number or [parallelize your job](./stream-analytics-parallelization.md). In other cases where you can't take any action, Stream Analytics will try to recover to a *Running* state. <br> You can use [watermark delay](monitor-azure-stream-analytics.md#azure-stream-analytics-metrics) metric to understand if these transient errors are impacting your job's performance.|

+* [Azure Stream Analytics job metrics](monitor-azure-stream-analytics-reference.md#metrics)

+* [Azure Stream Analytics metrics dimensions](monitor-azure-stream-analytics-reference.md#metric-dimensions)

+Azure Stream Analytics provides plenty of metrics that you can use to monitor and troubleshoot your query and job performance. You can view data from these metrics on the **Overview** page of the Azure portal, in the **Monitoring** section.

+If you want to check a specific metric, select **Metrics** in the **Monitoring** section. On the page that appears, select the metric.

+### Logical Name dimension

+### Node Name dimension

+### Partition ID dimension

+### Resource logs schema

+- [Dimensions for Azure Stream Analytics metrics](monitor-azure-stream-analytics-reference.md#metric-dimensions)

+After you create and run your Stream Analytics jobs, you can easily operationalize production workloads. Use the right set of [built-in metrics](monitor-azure-stream-analytics-reference.md#metrics) for monitoring and troubleshooting purposes. Stream Analytics jobs are billed according to the [pricing model](https://azure.microsoft.com/pricing/details/stream-analytics/) when they're running.

+You can select more metrics from the list. To understand all the metrics in detail, see [Azure Stream Analytics job metrics](monitor-azure-stream-analytics-reference.md#metrics).

+- **Job monitoring**: Select **Open metrics** to see the metrics related to this Stream Analytics job. For more information about the metrics that you can use to monitor your Stream Analytics job, see [Azure Stream Analytics job metrics](monitor-azure-stream-analytics-reference.md#metrics).

+* [Azure Stream Analytics job metrics](monitor-azure-stream-analytics-reference.md#metrics)

+* [Dimensions for Azure Stream Analytics metrics](monitor-azure-stream-analytics-reference.md#metric-dimensions)

+All logs are stored in JSON format. To learn about the schema for resource logs, see [Resource logs schema](monitor-azure-stream-analytics-reference.md#resource-logs-schema).

+A job's metrics provides lots of insights to your job's health. You can view these metrics through the job diagram in its chart section in job level or in the step level. To learn about Stream Analytics job metrics definition, see [Azure Stream Analytics job metrics](./monitor-azure-stream-analytics-reference.md#metrics). Job diagram integrates these metrics into the query steps (diagram). You can use these metrics within steps to monitor and analyze your job.

+* [Azure Stream Analytics job metrics](./monitor-azure-stream-analytics-reference.md#metrics)

+For more information about the metrics definition, see [Azure Stream Analytics node name dimension](monitor-azure-stream-analytics-reference.md#metric-dimensions).

+* [Azure Stream Analytics job metrics](./monitor-azure-stream-analytics-reference.md#metrics)

+It is recommended to deploy identical jobs to both paired regions. You should then [monitor these jobs](monitor-azure-stream-analytics.md) to get notified when something unexpected happens. If one of these jobs ends up in a [Failed state](./job-states.md) after a Stream Analytics service update, you can contact customer support to help identify the root cause. You should also fail over any downstream consumers to the healthy job output.

+There are 17 types of metrics provided by Azure Stream Analytics service. To learn about the details of them, see [Azure Stream Analytics job metrics](monitor-azure-stream-analytics-reference.md#metrics-descriptions).

+You can also use these metrics to [monitor the performance of your Stream Analytics job](monitor-azure-stream-analytics.md#azure-stream-analytics-metrics).

+To check the metrics data for a specific dimension, you can use **Add filter**. There are three important metrics dimensions available. To learn more about the metric dimensions, see [Azure Stream Analytics metrics dimensions](monitor-azure-stream-analytics-reference.md#metric-dimensions).

+Using the Azure portal, you can track the performance related metrics of a job. To learn about the metrics definition, see [Azure Stream Analytics job metrics](./monitor-azure-stream-analytics-reference.md#metrics). To learn more about the metrics monitoring in portal, see [Monitor Stream Analytics job with Azure portal](./stream-analytics-monitoring.md).

+While comparing utilization over a period of time, use [event rate metrics](monitor-azure-stream-analytics-reference.md#metrics). InputEvents and OutputEvents metrics show how many events were read and processed. There are metrics that indicate number of error events as well, such as deserialization errors. When the number of events per time unit increases, SU% increases in most cases.

+* [Azure Stream Analytics job metrics](monitor-azure-stream-analytics-reference.md#metrics)

+* [Azure Stream Analytics job metrics dimensions](monitor-azure-stream-analytics-reference.md#metric-dimensions)

+Stream Analytics derives the start time from the query specification. However, because the input event broker is only indexed by arrival time, the system has to translate the starting event time to arrival time. The system can start processing events from that point in the input event broker. With the early arriving window limit, the translation is straightforward: starting event time minus the 5-minute early arriving window. This calculation also means that the system drops all events that are seen as having an event time 5 minutes earlier than the arrival time. The [early input events metric](monitor-azure-stream-analytics-reference.md#metrics) is incremented when the events are dropped.

+You can observe a number of the Event ordering time tolerance effects through [Azure Stream Analytics job metrics](monitor-azure-stream-analytics-reference.md#metrics). The following metrics are relevant:

+* [Azure Stream Analytics job metrics](./monitor-azure-stream-analytics-reference.md#metrics)

+ Title: 'Deep learning (deprecated)'

+# Deep learning (deprecated)

+> [!NOTE]

+> The Preview for Azure Synapse GPU-enabled pools has now been deprecated.

+> [!CAUTION]

+> Deprecation and disablement notification for GPUs on the Azure Synapse Runtime for Apache Spark 3.1 and 3.2

+> - The GPU accelerated preview is now deprecated on the [Apache Spark 3.2 (deprecated) runtime](../spark/apache-spark-32-runtime.md). Deprecated runtimes will not have bug and feature fixes. This runtime and the corresponding GPU accelerated preview on Spark 3.2 has been retired and disabled as of July 8, 2024.

+> - The GPU accelerated preview is now deprecated on the [Azure Synapse 3.1 (deprecated) runtime](../spark/apache-spark-3-runtime.md). Azure Synapse Runtime for Apache Spark 3.1 has reached its end of support as of January 26, 2023, with official support discontinued effective January 26, 2024, and no further addressing of support tickets, bug fixes, or security updates beyond this date.

+> - GPU-accelerated pools are only available with the Apache Spark 3.1 (deprecated) and 3.2 runtime (deprecated).

+- Accelerate ETL workloads with RAPIDS: [Apache Spark Rapids](../spark/apache-spark-rapids-gpu.md)

+ Title: 'Tutorial: Distributed training with Horovod and PyTorch (deprecated)'

+# Tutorial: Distributed Training with Horovod Estimator and PyTorch (deprecated)

+> [!NOTE]

+> The Preview for Azure Synapse GPU-enabled pools has now been deprecated.

+> [!CAUTION]

+> Deprecation and disablement notification for GPUs on the Azure Synapse Runtime for Apache Spark 3.1 and 3.2

+> - The GPU accelerated preview is now deprecated on the [Apache Spark 3.2 (deprecated) runtime](../spark/apache-spark-32-runtime.md). Deprecated runtimes will not have bug and feature fixes. This runtime and the corresponding GPU accelerated preview on Spark 3.2 has been retired and disabled as of July 8, 2024.

+> - The GPU accelerated preview is now deprecated on the [Azure Synapse 3.1 (deprecated) runtime](../spark/apache-spark-3-runtime.md). Azure Synapse Runtime for Apache Spark 3.1 has reached its end of support as of January 26, 2023, with official support discontinued effective January 26, 2024, and no further addressing of support tickets, bug fixes, or security updates beyond this date.

+ Title: 'Tutorial: Distributed training with Horovod and TensorFlow (deprecated)'

+# Tutorial: Distributed Training with Horovod Runner and TensorFlow (deprecated)

+> [!NOTE]

+> The Preview for Azure Synapse GPU-enabled pools has now been deprecated.

+> [!CAUTION]

+> Deprecation and disablement notification for GPUs on the Azure Synapse Runtime for Apache Spark 3.1 and 3.2

+> - The GPU accelerated preview is now deprecated on the [Apache Spark 3.2 (deprecated) runtime](../spark/apache-spark-32-runtime.md). Deprecated runtimes will not have bug and feature fixes. This runtime and the corresponding GPU accelerated preview on Spark 3.2 has been retired and disabled as of July 8, 2024.

+> - The GPU accelerated preview is now deprecated on the [Azure Synapse 3.1 (deprecated) runtime](../spark/apache-spark-3-runtime.md). Azure Synapse Runtime for Apache Spark 3.1 has reached its end of support as of January 26, 2023, with official support discontinued effective January 26, 2024, and no further addressing of support tickets, bug fixes, or security updates beyond this date.

+ Title: 'Load data with Petastorm (deprecated)'

+# Load data with Petastorm (deprecated)

+> [!NOTE]

+> The Preview for Azure Synapse GPU-enabled pools has now been deprecated.

+> [!CAUTION]

+> Deprecation and disablement notification for GPUs on the Azure Synapse Runtime for Apache Spark 3.1 and 3.2

+> - The GPU accelerated preview is now deprecated on the [Apache Spark 3.2 (deprecated) runtime](../spark/apache-spark-32-runtime.md). Deprecated runtimes will not have bug and feature fixes. This runtime and the corresponding GPU accelerated preview on Spark 3.2 has been retired and disabled as of July 8, 2024.

+> - The GPU accelerated preview is now deprecated on the [Azure Synapse 3.1 (deprecated) runtime](../spark/apache-spark-3-runtime.md). Azure Synapse Runtime for Apache Spark 3.1 has reached its end of support as of January 26, 2023, with official support discontinued effective January 26, 2024, and no further addressing of support tickets, bug fixes, or security updates beyond this date.

+* [Learn more about GPU-enabled Apache Spark pools](../spark/apache-spark-gpu-concept.md)

+> [!CAUTION]

+* End of Support announced for Azure Synapse Runtime for Apache Spark 3.2 July 8, 2023.

+* Effective July 8, 2024, Azure Synapse will discontinue official support for Spark 3.2 Runtimes.

+* In accordance with the Synapse runtime for Apache Spark lifecycle policy, Azure Synapse runtime for Apache Spark 3.2 will be retired as of July 8, 2024. Existing workflows will continue to run but security updates and bug fixes will no longer be available. Metadata will temporarily remain in the Synapse workspace.

+* **We strongly recommend that you upgrade your Apache Spark 3.2 workloads to [Azure Synapse Runtime for Apache Spark 3.4 (GA)](./apache-spark-34-runtime.md) before July 8, 2024.**

+ Title: GPU-accelerated pools (deprecated)

+# GPU-accelerated Apache Spark pools in Azure Synapse Analytics (deprecated)

+> [!CAUTION]

+> Deprecation and disablement notification for GPUs on the Azure Synapse Runtime for Apache Spark 3.1 and 3.2

+> - The GPU accelerated preview is now deprecated on the [Apache Spark 3.2 (deprecated) runtime](../spark/apache-spark-32-runtime.md). Deprecated runtimes will not have bug and feature fixes. This runtime and the corresponding GPU accelerated preview on Spark 3.2 has been retired and disabled as of July 8, 2024.

+> - The GPU accelerated preview is now deprecated on the [Azure Synapse 3.1 (deprecated) runtime](../spark/apache-spark-3-runtime.md). Azure Synapse Runtime for Apache Spark 3.1 has reached its end of support as of January 26, 2023, with official support discontinued effective January 26, 2024, and no further addressing of support tickets, bug fixes, or security updates beyond this date.

+> Azure Synapse GPU-enabled preview has now been deprecated.

+ Title: Apache Spark on GPU (deprecated)

+# Apache Spark GPU-accelerated pools in Azure Synapse Analytics (deprecated)

+> The Preview for Azure Synapse GPU-enabled pools has now been deprecated.

+> [!CAUTION]

+> Deprecation and disablement notification for GPUs on the Azure Synapse Runtime for Apache Spark 3.1 and 3.2

+> - The GPU accelerated preview is now deprecated on the [Apache Spark 3.2 (deprecated) runtime](../spark/apache-spark-32-runtime.md). Deprecated runtimes will not have bug and feature fixes. This runtime and the corresponding GPU accelerated preview on Spark 3.2 has been retired and disabled as of July 8, 2024.

+> - The GPU accelerated preview is now deprecated on the [Azure Synapse 3.1 (deprecated) runtime](../spark/apache-spark-3-runtime.md). Azure Synapse Runtime for Apache Spark 3.1 has reached its end of support as of January 26, 2023, with official support discontinued effective January 26, 2024, and no further addressing of support tickets, bug fixes, or security updates beyond this date.

+Azure Virtual Desktop supports [hybrid identities](/entra/identity/hybrid/whatis-hybrid-identity) through Microsoft Entra ID, including those federated using AD FS. You can manage these user identities in AD DS and sync them to Microsoft Entra ID using [Microsoft Entra Connect](/entra/identity/hybrid/connect/whatis-azure-ad-connect). You can also use Microsoft Entra ID to manage these identities and sync them to [Microsoft Entra Domain Services](/entra/identity/domain-services/overview).

+### Federated identity

+If you're using a third-party Identity Provider (IdP), other than Microsoft Entra ID or Active Directory Domain Services, to manage your user accounts, you must ensure that:

+- Your IdP is [federated with Microsoft Entra ID](/entra/identity/devices/device-join-plan#federated-environment).

+- Your session hosts are Microsoft Entra joined or [Microsoft Entra hybrid joined](/entra/identity/devices/hybrid-join-plan).

+Azure Virtual Desktop currently doesn't support [external identities](/entra/external-id/external-identities-overview).

+When accessing Azure Virtual Desktop resources, there are three separate authentication phases:

+- **Cloud service authentication**: Authenticating to the Azure Virtual Desktop service, which includes subscribing to resources and authenticating to the Gateway, is with Microsoft Entra ID.

+- **Remote session authentication**: Authenticating to the remote VM. There are multiple ways to authenticate to the remote session, including the recommended single sign-on (SSO).

+- **In-session authentication**: Authenticating to applications and web sites within the remote session.

+For the list of credential available on the different clients for each of the authentication phase, [compare the clients across platforms](compare-remote-desktop-clients.md?pivots=azure-virtual-desktop#authentication).

+>[!IMPORTANT]

+>In order for authentication to work properly, your local machine must also be able to access the [required URLs for Remote Desktop clients](safe-url-list.md#remote-desktop-clients).

+The following sections provide more information on these authentication phases.

+### Cloud service authentication

+To access Azure Virtual Desktop resources, you must first authenticate to the service by signing in with a Microsoft Entra ID account. Authentication happens whenever you subscribe to retrieve your resources, connect to the gateway when launching a connection or when sending diagnostic information to the service. The Microsoft Entra ID resource used for this authentication is Azure Virtual Desktop (app ID 9cdead84-a844-4324-93f2-b2e6bb768d07).

+You can use any authentication type supported by Microsoft Entra ID, such as [Windows Hello for Business](/windows/security/identity-protection/hello-for-business/hello-overview) and other [passwordless authentication options](/entra/identity/authentication/concept-authentication-passwordless) (for example, FIDO keys), to authenticate to the service.

+To use a smart card to authenticate to Microsoft Entra ID, you must first [configure Microsoft Entra certificate-based authentication](/entra/identity/authentication/concept-certificate-based-authentication) or [configure AD FS for user certificate authentication](/windows-server/identity/ad-fs/operations/configure-user-certificate-authentication).

+#### Third-party identity providers

+You can use third-party identity providers as long as they [federate with Microsoft Entra ID](/entra/identity/devices/device-join-plan#federated-environment).

+### Remote session authentication

+If you haven't already enabled [single sign-on](#single-sign-on-sso) or saved your credentials locally, you'll also need to authenticate to the session host when launching a connection.

+SSO allows the connection to skip the session host credential prompt and automatically sign the user in to Windows through Microsoft Entra authentication. For session hosts that are Microsoft Entra joined or Microsoft Entra hybrid joined, it's recommended to enable [SSO using Microsoft Entra authentication](configure-single-sign-on.md). Microsoft Entra authentication provides other benefits including passwordless authentication and support for third-party identity providers.

+Without SSO, the client prompts users for their session host credentials for every connection. The only way to avoid being prompted is to save the credentials in the client. We recommend you only save credentials on secure devices to prevent other users from accessing your resources.

+To access Microsoft Entra resources with Windows Hello for Business or security devices, you must enable the FIDO2 Security Key as an authentication method for your users. To enable this method, follow the steps in [Enable FIDO2 security key method](/entra/identity/authentication/how-to-enable-passkey-fido2#enable-fido2-security-key-method).

+To use a smart card in your session, make sure you've installed the smart card drivers on the session host and enabled [smart card redirection](configure-device-redirections.md#smart-card-redirection). Review the [client comparison chart](compare-remote-desktop-clients.md?pivots=azure-virtual-desktop#in-session-authentication) to make sure your client supports smart card redirection.

+| [Passkeys (FIDO2)](/entra/identity/authentication/concept-authentication-passwordless#passkeys-fido2) | Passkeys provide a standards-based passwordless authentication method that comes in many form factors, including FIDO2 security keys. Passkeys incorporate the web authentication (WebAuthn) standard. |

+| Passkeys (FIDO2) | _{:::image type="icon" source="media/yes.svg" border="false":::} | _{:::image type="icon" source="media/yes.svg" border="false":::} | _{:::image type="icon" source="media/yes.svg" border="false":::} | ^{&#160;&#160;&#8201;}_{:::image type="icon" source="media/yes.svg" border="false":::}&sup1; | ^{&#160;&#160;&#8201;}_{:::image type="icon" source="media/yes.svg" border="false":::}&sup1; | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/yes.svg" border="false":::} |

+| Windows Hello for Business certificate trust | _{:::image type="icon" source="media/yes.svg" border="false":::} | _{:::image type="icon" source="media/yes.svg" border="false":::} | _{:::image type="icon" source="media/yes.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | ^{&#160;&#160;&#8201;}_{:::image type="icon" source="media/yes.svg" border="false":::}&sup2; |

+| Windows Hello for Business cloud trust | _{:::image type="icon" source="media/yes.svg" border="false":::} | _{:::image type="icon" source="media/yes.svg" border="false":::} | _{:::image type="icon" source="media/yes.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | ^{&#160;&#160;&#8201;}_{:::image type="icon" source="media/yes.svg" border="false":::}&sup2; |

+| Windows Hello for Business key trust | _{:::image type="icon" source="media/yes.svg" border="false":::} | _{:::image type="icon" source="media/yes.svg" border="false":::} | _{:::image type="icon" source="media/yes.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | ^{&#160;&#160;&#8201;}_{:::image type="icon" source="media/yes.svg" border="false":::}&sup2; |

+| Passkeys (FIDO2) | _{:::image type="icon" source="media/yes.svg" border="false":::} | ^{&#160;&#160;&#8201;}_{:::image type="icon" source="media/yes.svg" border="false":::}&sup1; | ^{&#160;&#160;&#8201;}_{:::image type="icon" source="media/yes.svg" border="false":::}&sup1; | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/yes.svg" border="false":::} |

+| Windows Hello for Business certificate trust | _{:::image type="icon" source="media/yes.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | ^{&#160;&#160;&#8201;}_{:::image type="icon" source="media/yes.svg" border="false":::}&sup2; |

+| Windows Hello for Business cloud trust | _{:::image type="icon" source="media/yes.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | ^{&#160;&#160;&#8201;}_{:::image type="icon" source="media/yes.svg" border="false":::}&sup2; |

+| Windows Hello for Business key trust | _{:::image type="icon" source="media/yes.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | ^{&#160;&#160;&#8201;}_{:::image type="icon" source="media/yes.svg" border="false":::}&sup2; |

+1. Available in preview. Requires macOS client version 10.9.8 or later. Requires iOS client version 10.5.9 or later. For more information, see [Support for FIDO2 authentication with Microsoft Entra ID](/entra/identity/authentication/concept-fido2-compatibility#native-application-support-with-authentication-broker-preview).

+| Passkeys (FIDO2) | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} |

+| Passkeys (FIDO2) | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} |

+| Passkeys (FIDO2) | ^{&#160;&#160;&#8201;}_{:::image type="icon" source="media/yes.svg" border="false":::}&sup2; | ^{&#160;&#160;&#8201;}_{:::image type="icon" source="media/yes.svg" border="false":::}&sup2; | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} |

+| Passkeys (FIDO2) | ^{&#160;&#160;&#8201;}_{:::image type="icon" source="media/yes.svg" border="false":::}&sup2; | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} | _{:::image type="icon" source="media/no.svg" border="false":::} |

+| Validation | 1.0.9103.5000 |

+## Version 1.0.9103.5000 (validation)

+*Published: July 2024*

+In this update, we've made the following changes:

+- General improvements and bug fixes.

+## Version 1.0.9103.3800

+| CentOS ¹ | 6.10 and 7 |

+| Oracle Linux | 6.10 ², 7 and 8+ |

+| Red Hat Enterprise Linux (RHEL) | 6.10 ³, 7, 8 and 9.2 |

+¹ CentOS Linux reached its end-of-life (EOL) on June 30, 2024. For more information, see the [CentOS End Of Life guidance](../workloads/centos/centos-end-of-life.md).

+² [Extended life cycle (ELS) support](https://www.oracle.com/a/ocom/docs/linux/oracle-linux-extended-support-ds.pdf) for Oracle Linux version 6.X ended on [July 1, 2024](https://www.oracle.com/a/ocom/docs/elsp-lifetime-069338.pdf).

+³ [Extended life cycle (ELS) support](https://www.redhat.com/en/resources/els-datasheet) for Red Hat Enterprise Linux 6.X ended on [June 30, 2024]( https://access.redhat.com/product-life-cycles/?product=Red%20Hat%20Enterprise%20Linux,OpenShift%20Container%20Platform%204).

+### What are the differences between Secure Boot and measured boot?

+In a Secure Boot chain, each step in the boot process checks a cryptographic signature of the subsequent steps. For example, the BIOS checks a signature on the loader, and the loader checks signatures on all the kernel objects that it loads, and so on. If any of the objects are compromised, the signature doesn't match and the VM doesn't boot. For more information, see [Secure Boot](/windows-hardware/design/device-experiences/oem-secure-boot).

+### What is VM Guest State (VMGS)?

+VM Guest State (VMGS) is specific to Trusted Launch VMs. It's a blob managed by Azure and contains the unified extensible firmware interface (UEFI) Secure Boot signature databases and other security information. The lifecycle of the VMGS blob is tied to that of the OS disk.

+## Troubleshooting issues

+### What should I do when my Trusted Launch VM has deployment failures ?

+This section provides additional details on Trusted Launch deployment failures for you to take proper action to prevent them.

+```

+Virtual machine <vm name> failed to create from the selected snapshot because the virtual Trusted Platform Module (vTPM) state is locked.

+To proceed with the VM creation, please select a different snapshot without a locked vTPM state.

+For more assistance, please refer to “Troubleshooting locked vTPM state” in FAQ page at https://aka.ms/TrustedLaunch-FAQ.

+```

+This deployment error happens when the snapshot or restore point provided is inaccessible or unusable for the following reasons:

+1. Corrupt virtual machine guest state (VMGS)

+2. vTPM in a locked state

+3. One or more critical vTPM indices are in an invalid state.

+The above can happen if a user or workload running on the virtual machine sets the lock on vTPM or modifies critical vTPM indices that leaves the vTPM in an invalid state.

+Retrying with the same snapshot/restore point will result in the same failure.

+To resolve this:

+1. On the source Trusted Launch VM where the snapshot or restore point was generated, the vTPM errors must be rectified.

+ 1. If the vTPM state was modified by a workload on the virtual machine, you need to use the same to check the error states and bring the vTPM to a non-error state.

+ 1. If TPM tools were used to modify the vTPM state, then you should use the same tools to check the error states and bring the vTPM to a non-error state.

+Once the snapshot or restore point is free from these errors, you can use this to create a new Trusted Launch VM.

+The following section describes how to configure Windows Server Network Policy Server (NPS) to authenticate users to respond to Access-Request messages with the Vendor Specific Attribute (VSA) used for user group support in Virtual WAN point-to-site-VPN. The following steps assume that your Network Policy Server is already registered to Active Directory. The steps might vary depending on the vendor/version of your NPS server.

+The following steps describe setting up single Network Policy on the NPS server. The NPS server replies with the specified VSA for all users who match this policy, and the value of this VSA can be used on your point-to-site VPN gateway in Virtual WAN.

+1. In the wizard, select **Access granted** to ensure your RADIUS server can send Access-Accept messages after authenticating users. Then, click **Next**.

+1. On the **Specify Conditions** page, click **Add** to select a condition. Then, select **User Groups** as the condition and click **Add**. You can also use other Network Policy conditions that are supported by your RADIUS server vendor.

+ Title: 'Report an Azure VPN Client problem via Feedback Hub'

+description: Learn how to report problems for the Azure VPN Client using the Microsoft Feedback Hub app.

+# Use Feedback Hub to report an Azure VPN Client problem

+This article helps you report an Azure VPN Client problem or improve the Azure VPN Client experience using the **FeedBack Hub** app. Use the steps in this article to help collect logs, send files and screenshots, and review diagnostics. The steps in this article apply to the Windows 10 and Windows 11 operating systems and the Azure VPN Client.

+The Feedback Hub app is automatically a part of Windows 10 and Windows 11. You don't need to download it separately. The screenshots shown in this article might be slightly different, depending on the version of Feedback Hub. For more information about FeedBack Hub, see [Send feedback to Microsoft with the Feedback Hub app](https://support.microsoft.com/en-us/windows/send-feedback-to-microsoft-with-the-feedback-hub-app-f59187f8-8739-22d6-ba93-f66612949332).

+## Open Feedback Hub

+1. To open the Feedback Hub app, on your Windows computer, press the **Windows logo key** + **F**, or select **Start** on your Windows 10 or Windows 11 computer and type **Feedback Hub**.

+1. **Sign in**. Signing in is the only way to track your feedback and get the full experience of the Feedback Hub.

+1. On the left side of the page, make sure you are on **Feedback**.

+## Enter your feedback

+1. Summarize your feedback. The **Summarize your feedback** box is used as a title for your feedback. Make your title concise and descriptive. This helps the search function locate similar problems and also helps others find and upvote your feedback.

+ :::image type="content" source="./media/feedback-hub-azure-vpn-client/summary.png" alt-text="Screenshot showing the Enter your feedback fields." lightbox="./media/feedback-hub-azure-vpn-client/summary.png":::

+1. In the **Explain in more detail** box you can give us more specific information, like how you encountered the problem. This field is public, so be sure not to include personal information.

+1. Select **Next** to advance to **Choose a category**.

+## Choose a category

+1. Under **Choose a category**, select whether this is a **Problem** or a **Suggestion**.

+1. Choose the following category settings. There are multiple options available in the dropdown. Make sure to select **Azure VPN Client**. This ensures that log files are sent to the correct destination.

+ **Problem** -> **Network and Internet** -> **Azure VPN Client**.

+ :::image type="content" source="./media/feedback-hub-azure-vpn-client/category.png" alt-text="Screenshot showing the Choose a category page." lightbox="./media/feedback-hub-azure-vpn-client/category.png":::

+1. Select **Next** to advance to **Find similar feedback**.

+## Find similar feedback

+1. In the **Find similar feedback** section, look for bugs with similar feedback to see if anything matches the issue you're having.

+

+ * If you see feedback that's **similar or the same** as the issue you're experiencing, select this option.

+ * If you don't see anything or are unsure of what to select, select **New feedback** and **Make a new bug**.

+1. Select **Next** to advance to the **Add more details** section.

+## Add more details

+In this section, you add diagnostic and other details.

+* If your feedback is a **Suggestion**, the app takes you directly to the **Attachments (optional)** section.

+* If your feedback is a **Problem** and you feel the problem merits more urgent attention, you can specify this problem as a high priority or blocking issue.

+In the **Attachments (optional)** section, you should supply as much comprehensive information as possible. If a screen doesn't look right, [attach a screenshot](#attach-a-screenshot). If you're reporting a problem other than a screen issue, it's best to follow the steps in [Recreate my problem](#recreate-my-problem) and then use the steps in [Attach a file](#attach-a-file) to attach the log files.

+### Attach a screenshot

+If you're reporting an issue with the way a screen appears, submit a screenshot.

+* Select **Choose a screenshot** to add an image.

+* You can either create a new screenshot, or select one you previously created.

+### Recreate my problem

+The **Recreate my problem** option provides us with crucial information. This option has you recreate the problem while recording data. You can review and edit the data before you submit the problem.

+1. To use this option, first select the following items:

+ * **Include data about Azure VPN Client (Default)**

+ * **Include screenshots of each step**

+1. Press the **Start recording** button.

+1. Reproduce the issue you're experiencing with the Azure VPN Client.

+1. Once you reproduce the issue, press **Stop recording**.

+ :::image type="content" source="./media/feedback-hub-azure-vpn-client/stop-recording.png" alt-text="Screenshot showing the Azure VPN Client recording." lightbox="./media/feedback-hub-azure-vpn-client/stop-recording.png":::

+### Attach a file

+Attach the Azure VPN Client **log files**. It's best if you attach the file after you recreate the problem to make sure the problem is included in the log file. To attach the client log files:

+1. Select **Attach a file** and locate the log files for the Azure VPN client. Log files are stored locally in the following folder: **%localappdata%\Packages\Microsoft.AzureVpn_8wekyb3d8bbwe\LocalState\LogFiles**.

+1. From the LogFiles folder, select **Azure VPNClient.log** and **Azure VpnCxn.log**.

+ :::image type="content" source="./media/feedback-hub-azure-vpn-client/locate-files.png" alt-text="Screenshot showing the Azure VPN client log files." lightbox="./media/feedback-hub-azure-vpn-client/locate-files.png":::

+### Submit the problem

+1. Review the files listed in the **Attached** section. You can view images by selecting **View**.

+1. If everything is correct, select **Save a local copy of diagnostics** and **I agree to send attached files**.

+ :::image type="content" source="./media/feedback-hub-azure-vpn-client/attached-log-files.png" alt-text="Screenshot the attached files to submit." lightbox="./media/feedback-hub-azure-vpn-client/attached-log-files.png":::

+1. Select **Submit**.

+1. The **Thank you for your feedback!** message appears at the end of the collection process.

+## View your feedback

+You can view your feedback in Feedback Hub.

+1. Open Feedback Hub.

+1. In the left pane, select **Feedback**. Then, select **My feedback**

+## Feedback Hub and Azure Support tickets

+If you need immediate attention for your issue, open an Azure Support ticket and share the Feedback Hub identification information. To find the Feedback Hub item identifiers:

+1. Open Feedback Hub.

+1. In the left pane, select **Feedback**. Then, select **My feedback**.

+1. Locate and select the **Problem** to view more details and access the identifier for your collection logs.

+1. Select **Share** to see the identifier associated with the generated logs.

+1. Select **Other sharing option** to access the URI associated with the diagnostic logs that were sent to Microsoft.

+1. Copy the **Short Link** and the **URI**.

+ :::image type="content" source="./media/feedback-hub-azure-vpn-client/copy-links.png" alt-text="Screenshot showing the Problem links to copy." lightbox="./media/feedback-hub-azure-vpn-client/copy-links.png":::

+1. Report the **Short Link** and **URI** to the Microsoft Azure ticket to associate the diagnostic logs to your support case.

+## Next steps

+For more information about FeedBack Hub, see [Send feedback to Microsoft with the Feedback Hub app](https://support.microsoft.com/windows/send-feedback-to-microsoft-with-the-feedback-hub-app-f59187f8-8739-22d6-ba93-f66612949332).

+For Application Gateway v2 Web Application Firewalls running Core Rule Set 3.2, or newer, the maximum request body size enforcement and max file upload size enforcement can be disabled and the Web Application Firewall no longer rejects a request, or file upload, for being too large. When maximum request body size enforcement and max file upload size enforcement are disabled within the Web Application Firewall, Application Gateway's limits determine the maximum size allowable. For more information, see [Application Gateway limits](../../azure-resource-manager/management/azure-subscription-service-limits.md#application-gateway-limits).

+For Policy Web Application Firewalls running Core Rule Set 3.2 (or newer), request body inspection can be enabled/disabled independently of request body size enforcement and file upload size limits. Additionally, policy Web Application Firewalls running Core Rule Set 3.2 (or newer) can set the maximum request body inspection limit independently of the maximum request body size. The maximum request body inspection limit tells the Web Application Firewall how deep into a request it should inspect and apply rules; setting a lower value for this field can improve Web Application Firewall performance but might allow for uninspected malicious content to pass through your Web Application Firewall.

+If you're an Application Gateway v2 Web Application Firewall customer running Core Rule Set 3.2 or later and you have issues with requests, or file uploads, getting rejected incorrectly for maximum size, or if you see requests not getting inspected fully, you might need to verify that all values are set correctly. Using PowerShell or the Azure Command Line Interface you can verify what each value is set to, and update any values as needed.

+- PowerShell: "RequestBodyCheck"

+- Controls if your Web Application Firewall inspects the request body and apply managed and custom rules to the request body traffic per your Web Application Firewall policyΓÇÖs settings.

+- PowerShell: "RequestBodyInspectLimitInKB"

+- Controls how deep into a request body the Web Application Firewall inspects and applies managed/custom rules. Generally speaking, youΓÇÖd want to set this to the max possible setting, but some customers might want to set it to a lower value to improve performance.

+- PowerShell: "RequestBodyEnforcement"

+- Control if your Web Application Firewall enforces a max size limit on request bodies; when turned off it does not reject any requests for being too large.

+- PowerShell: "MaxRequestBodySizeInKB"

+- PowerShell: "FileUploadEnforcement"

+- Controls if your Web Application Firewall enforces a max size limit on file uploads; when turned off it does not reject any file uploads for being too large.

+- PowerShell: "FileUploadLimitInMB"

+You can use these commands to update the policy settings to the desired values for inspection limit and max size limitation related fields. You can swap out 'RequestBodyEnforcement' in the following example for one of the other values that you want to update.

+az network application-gateway waf-policy update --name <WAF Policy name> --resource-group <WAF policy RG> --set policySettings.request_body_inspect_limit_in_kb='128' policySettings.max_request_body_size_in_kb='128' policySettings.file_upload_limit_in_mb='100' --query policySettings -o table

+True 100 128 Detection True True 128 Enabled