-| [Phone sign-up and sign-in](phone-authentication-user-flows.md) | GA | GA | |

-| [Conditional Access and Identity Protection](conditional-access-user-flow.md) | GA | GA | Not available for SAML applications |

-| [Multi-language support](localization.md)| GA | GA | |

-| [Custom domains](custom-domain.md)| GA | GA | |

-| [Page layout version](page-layout.md) | GA | GA | |

-| [JavaScript](javascript-and-page-layout.md) | GA | GA | |

-| [Password complexity](password-complexity.md) | GA | GA | |

-|[Apple](identity-provider-apple-id.md) | GA | GA | |

-|[WeChat](identity-provider-wechat.md) | Preview | GA | |

-| [Default SSO session provider](custom-policy-reference-sso.md#defaultssosessionprovider) | GA | |

-| [External login session provider](custom-policy-reference-sso.md#externalloginssosessionprovider) | GA | |

-| [SAML SSO session provider](custom-policy-reference-sso.md#samlssosessionprovider) | GA | |

-| [OAuth SSO Session Provider](custom-policy-reference-sso.md#oauthssosessionprovider) | GA| |

-| [Phone factor authentication](phone-factor-technical-profile.md) | GA | |

-|Subscription Owner<br>Subscription Contributor|View reviews for a workload, triage recommendations linked to those reviews, manage review recommendation lifecycle.|

-|Advisor Recommendations Contributor (Assessments and Reviews)|View review recommendations, accept review recommendations, manage review recommendations' lifecycle.|

-| F0 | 10 |

-| S0 | 10 |

-In the simple case without the _reasoning_ feature, the Groundedness detection API classifies the ungroundedness of the submitted content as `true` or `false` and provides a confidence score.

-> [!TIP]

-> To test a summarization task instead of a question answering (QnA) task, use the following sample JSON body:

->

-> ```json

-> {

-> "Domain": "Medical",

-> "Task": "Summarization",

-> "Text": "Ms Johnson has been in the hospital after experiencing a stroke.",

-> "GroundingSources": ["Our patient, Ms. Johnson, presented with persistent fatigue, unexplained weight loss, and frequent night sweats. After a series of tests, she was diagnosed with HodgkinΓÇÖs lymphoma, a type of cancer that affects the lymphatic system. The diagnosis was confirmed through a lymph node biopsy revealing the presence of Reed-Sternberg cells, a characteristic of this disease. She was further staged using PET-CT scans. Her treatment plan includes chemotherapy and possibly radiation therapy, depending on her response to treatment. The medical team remains optimistic about her prognosis given the high cure rate of HodgkinΓÇÖs lymphoma."],

-> "Reasoning": false

-> }

-> ```

-| **reasoning** | (Optional) Specifies whether to use the reasoning feature. The default value is `false`. If `true`, you need to bring your own Azure OpenAI resources to provide an explanation. Be careful: using reasoning increases the processing time and incurs extra fees.| Boolean |

-| **confidenceScore** | The confidence value of the _ungrounded_ designation. The score ranges from 0 to 1. | Float |

-| -**`Text`** | The specific text that is ungrounded. | String |

-In order to use your Azure OpenAI resource to enable the reasoning feature, use Managed Identity to allow your Content Safety resource to access the Azure OpenAI resource:

-In your request to the Groundedness detection API, set the `"Reasoning"` body parameter to `true`, and provide the other needed parameters:

-| **llmResource** | (Optional) If you want to use your own Azure OpenAI resources instead of our default GPT resources, add this field and include the subfields for the resources used. If you don't want to use your own resources, remove this field from the input. | String |

-| - `resourceType `| Specifies the type of resource being used. Currently it only allows `AzureOpenAI`. | Enum|

-| **confidenceScore** | The confidence value of the _ungrounded_ designation. The score ranges from 0 to 1. | Float |

-| -**`Text`** | The specific text that is ungrounded. | String |

-| -**`Reason`** | Offers explanations for detected ungroundedness. | String |

-* [Language detection overview](overview.md)

-You can use NER resolutions to implement actions or retrieve further information. For example, your service can extract datetime entities to extract dates and times that will be provided to a meeting scheduling system.

-Use this article to get an overview of the new API changes starting from `2023-04-15-preview` version. This API change mainly introduces two new concepts (`entity types` and `entity tags`) replacing the `category` and `subcategory` fields in the current Generally Available API.

-The changes introduce better flexibility for named entity recognition, including:

-* More granular entity recognition through introducing the tags list where an entity could be tagged by more than one entity tag.

-| Temperature | Numeric, Dimension, Temperature |

-| Speed | Numeric, Dimension, Speed |

-| Weight | Numeric, Dimension, Weight |

-| Height | Numeric, Dimension, Height |

-| Length | Numeric, Dimension, Length |

-| Volume | Numeric, Dimension, Volume |

-| Area | Numeric, Dimension, Area |

-| Information | Numeric, Dimension, Information |

-| ComputingProduct | Product, ComputingProduct |

-Named Entity Recognition (NER) is one of the features offered by [Azure AI Language](../overview.md), a collection of machine learning and AI algorithms in the cloud for developing intelligent applications that involve written language. The NER feature can identify and categorize entities in unstructured text. For example: people, places, organizations, and quantities.

-* An Azure Language Service resource and custom question qnswering project. If you donΓÇÖt have one already, then [create one](../quickstart/sdk.md).

-* [Using Azure OpenAI on your data](../../../openai/concepts/use-your-data.md)

-> Version `0613` of `gpt-35-turbo` and `gpt-35-turbo-16k` will be retired no earlier than June 13, 2024. Version `0301` of `gpt-35-turbo` will be retired no earlier than July 5, 2024. See [model updates](../how-to/working-with-models.md#model-updates) for model upgrade behavior.

-## To Avoid Fabrication or Ungrounded Content

-You need to connect to a data source to upload your data. When you want to use your data to chat with an Azure OpenAI model, your data is chunked in a search index so that relevant data can be found based on user queries. For some data sources such as uploading files from your local machine (preview) or data contained in a blob storage account (preview), Azure AI Search is used.

-When you choose the following data sources, your data is ingested into an Azure AI Search index.

-# [Azure Cosmos DB for MongoDB vCore](#tab/mongo-db)

-* [Azure Cosmos DB for MongoDB vCore](/azure/cosmos-db/mongodb/vcore/introduction) account

-* Only Azure Cosmos DB for MongoDB vCore is supported.

-* The search type is limited to [Azure Cosmos DB for MongoDB vCore vector search](/azure/cosmos-db/mongodb/vcore/vector-search) with an Azure OpenAI embedding model.

-To add Azure Cosmos DB for MongoDB vCore as a data source, you will need an existing Azure Cosmos DB for MongoDB vCore index containing your data, and a deployed Azure OpenAI Ada embeddings model that will be used for vector search.

-1. In the [Azure OpenAI portal](https://oai.azure.com/portal) chat playground, select **Add your data**. In the panel that appears, select **Azure Cosmos DB for MongoDB vCore** as the data source.

-When you add your Azure Cosmos DB for MongoDB vCore data source, you can specify data fields to properly map your data for retrieval.

-### Failed ingestion jobs

-To troubleshoot a failed job, always look out for errors or warnings specified either in the API response or Azure OpenAI studio. Here are some of the common errors and warnings:

-description: Learn about the options for how to use the GPT-35-Turbo and GPT-4 models

-zone_pivot_groups: openai-chat

-# Learn how to work with the GPT-35-Turbo and GPT-4 models

-The GPT-35-Turbo and GPT-4 models are language models that are optimized for conversational interfaces. The models behave differently than the older GPT-3 models. Previous models were text-in and text-out, meaning they accepted a prompt string and returned a completion to append to the prompt. However, the GPT-35-Turbo and GPT-4 models are conversation-in and message-out. The models expect input formatted in a specific chat-like transcript format, and return a completion that represents a model-written message in the chat. While this format was designed specifically for multi-turn conversations, you'll find it can also work well for non-chat scenarios too.

-In Azure OpenAI there are two different options for interacting with these type of models:

-The Chat Completion API is a new dedicated API for interacting with the GPT-35-Turbo and GPT-4 models. This API is the preferred method for accessing these models. **It is also the only way to access the new GPT-4 models**.

-ChatML uses the same [completion API](../reference.md#completions) that you use for other models like text-davinci-002, it requires a unique token based prompt format known as Chat Markup Language (ChatML). This provides lower level access than the dedicated Chat Completion API, but also requires additional input validation, only supports gpt-35-turbo models, and **the underlying format is more likely to change over time**.

-This article walks you through getting started with the GPT-35-Turbo and GPT-4 models. It's important to use the techniques described here to get the best results. If you try to interact with the models the same way you did with the older model series, the models will often be verbose and provide less useful responses.

-| `Generated Completion Tokens` | Usage | Sum | Number of generated tokens (output) from an OpenAI model. Applies to PayGo, PTU, and PTU-manged SKUs | `ApiName`, `ModelDeploymentName`,`ModelName`, `Region`|

-| `Processed FineTuned Training Hours` | Usage |Sum| Number of Training Hours Processed on an OpenAI FineTuned Model | `ApiName`, `ModelDeploymentName`,`ModelName`, `Region`|

-| `Processed Inference Tokens` | Usage | Sum| Number of inference tokens processed by an OpenAI model. Calculated as prompt tokens (input) + generated tokens. Applies to PayGo, PTU, and PTU-manged SKUs.|`ApiName`, `ModelDeploymentName`,`ModelName`, `Region`|

-| `Processed Prompt Tokens` | Usage | Sum | Total number of prompt tokens (input) processed on an OpenAI model. Applies to PayGo, PTU, and PTU-managed SKUs.|`ApiName`, `ModelDeploymentName`,`ModelName`, `Region`|

-description: Learn how to generate reproducible output (preview) with Azure OpenAI Service

-By default if you ask an Azure OpenAI Chat Completion model the same question multiple times you are likely to get a different response. The responses are therefore considered to be non-deterministic. Reproducible output is a new preview feature that allows you to selectively change the default behavior towards producing more deterministic outputs.

- api_version="2023-12-01-preview"

- model="gpt-4-1106-preview", # Model = should match the deployment name you chose for your 1106-preview model deployment

- max_tokens =200,

- api_version = '2023-12-01-preview' # may change in the future

- max_tokens = 200

-In the beginning, there was nothingness, a vast expanse of empty space, a blank canvas waiting to be painted with the wonders of existence. Then, approximately 13.8 billion years ago, something extraordinary happened, an event that would mark the birth of the universe ΓÇô the Big Bang.

-The Big Bang was not an explosion in the conventional sense but rather an expansion, an incredibly rapid stretching of space that took place everywhere in the universe at once. In just a fraction of a second, the universe grew from smaller than a single atom to an incomprehensibly large expanse.

-In these first moments, the universe was unimaginably hot and dense, filled with a seething soup of subatomic particles and radiant energy. As the universe expanded, it began to cool, allowing the first particles to form. Protons and neutrons came together to create the first simple atomic nuclei in a process known as nucleosynthesis.

-For hundreds of thousands of years, the universe continued to cool and expand

-Once upon a time, in the vast expanse of nothingness, there was a moment that would come to define everything. This moment, a tiny fraction of a second that would be forever known as the Big Bang, marked the birth of the universe as we know it.

-Before this moment, there was no space, no time, just an infinitesimally small point of pure energy, a singularity where all the laws of physics as we understand them did not apply. Then, suddenly, this singular point began to expand at an incredible rate. In a cosmic symphony of creation, matter, energy, space, and time all burst forth into existence.

-The universe was a hot, dense soup of particles, a place of unimaginable heat and pressure. It was in this crucible of creation that the simplest elements were formed. Hydrogen and helium, the building blocks of the cosmos, came into being.

-As the universe continued to expand and cool, these primordial elements began to co

-Once upon a time, in the vast expanse of nothingness, there was a singularity, an infinitely small and infinitely dense point where all the mass and energy of what would become the universe were concentrated. This singularity was like a tightly wound cosmic spring holding within it the potential of everything that would ever exist.

-Then, approximately 13.8 billion years ago, something extraordinary happened. This singularity began to expand in an event we now call the Big Bang. In just a fraction of a second, the universe grew exponentially during a period known as cosmic inflation. It was like a symphony's first resounding chord, setting the stage for a cosmic performance that would unfold over billions of years.

-As the universe expanded and cooled, the fundamental forces of nature that we know today ΓÇô gravity, electromagnetism, and the strong and weak nuclear forces ΓÇô began to take shape. Particles of matter were created and began to clump together under the force of gravity, forming the first atoms

- api_version="2023-12-01-preview"

- model="gpt-4-1106-preview", # Model = should match the deployment name you chose for your 1106-preview model deployment

- max_tokens =200,

- api_version = '2023-12-01-preview' # may change in the future

- max_tokens = 200

-In the beginning, there was nothing but a vast emptiness, a void without form or substance. Then, from this nothingness, a singular event occurred that would change the course of existence foreverΓÇöThe Big Bang.

-Around 13.8 billion years ago, an infinitely hot and dense point, no larger than a single atom, began to expand at an inconceivable speed. This was the birth of our universe, a moment where time and space came into being. As this primordial fireball grew, it cooled, and the fundamental forces that govern the cosmosΓÇögravity, electromagnetism, and the strong and weak nuclear forcesΓÇöbegan to take shape.

-Matter coalesced into the simplest elements, hydrogen and helium, which later formed vast clouds in the expanding universe. These clouds, driven by the force of gravity, began to collapse in on themselves, creating the first stars. The stars were crucibles of nuclear fusion, forging heavier elements like carbon, nitrogen, and oxygen

-In the beginning, there was nothing but a vast emptiness, a void without form or substance. Then, from this nothingness, a singular event occurred that would change the course of existence foreverΓÇöThe Big Bang.

-Around 13.8 billion years ago, an infinitely hot and dense point, no larger than a single atom, began to expand at an inconceivable speed. This was the birth of our universe, a moment where time and space came into being. As this primordial fireball grew, it cooled, and the fundamental forces that govern the cosmosΓÇögravity, electromagnetism, and the strong and weak nuclear forcesΓÇöbegan to take shape.

-Matter coalesced into the simplest elements, hydrogen and helium, which later formed vast clouds in the expanding universe. These clouds, driven by the force of gravity, began to collapse in on themselves, creating the first stars. The stars were crucibles of nuclear fusion, forging heavier elements like carbon, nitrogen, and oxygen

-In the beginning, there was nothing but a vast emptiness, a void without form or substance. Then, from this nothingness, a singular event occurred that would change the course of existence foreverΓÇöThe Big Bang.

-Around 13.8 billion years ago, an infinitely hot and dense point, no larger than a single atom, began to expand at an inconceivable speed. This was the birth of our universe, a moment where time and space came into being. As this primordial fireball grew, it cooled, and the fundamental forces that govern the cosmosΓÇögravity, electromagnetism, and the strong and weak nuclear forcesΓÇöbegan to take shape.

-Matter coalesced into the simplest elements, hydrogen and helium, which later formed vast clouds in the expanding universe. These clouds, driven by the force of gravity, began to collapse in on themselves, creating the first stars. The stars were crucibles of nuclear fusion, forging heavier elements like carbon, nitrogen, and oxygen

-By using the same `seed` parameter of 42 for each of our three requests we're able to produce much more consistent (in this case identical) results.

-## Resources configuration

-See the [ingestion API reference article](/azure/ai-services/openai/reference#start-an-ingestion-job) for details on the request and response objects used by the ingestion API.

-The Whisper models, currently in preview, can be used to transcribe and translate speech to text.

- "n": 3,

-| ```file```| file | Yes | N/A | The audio file object (not file name) to transcribe, in one of these formats: `flac`, `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `ogg`, `wav`, or `webm`.<br/><br/>The file size limit for the Azure OpenAI Whisper model is 25 MB. If you need to transcribe a file larger than 25 MB, break it into chunks. Alternatively you can use the Azure AI Speech [batch transcription](../speech-service/batch-transcription-create.md#use-a-whisper-model) API.<br/><br/>You can get sample audio files from the [Azure AI Speech SDK repository at GitHub](https://github.com/Azure-Samples/cognitive-services-speech-sdk/tree/master/sampledata/audiofiles). |

-Azure OpenAI is deployed as a part of the Azure AI services. All Azure AI services rely on the same set of management APIs for creation, update, and delete operations. The management APIs are also used for deploying models within an OpenAI resource.

-If you want to clean up and remove an OpenAI resource, you can delete the resource. Before deleting the resource, you must first delete any deployed models.

-If you created an OpenAI resource solely for completing this tutorial and want to clean up and remove an OpenAI resource, you'll need to delete your deployed models, and then delete the resource or associated resource group if it's dedicated to your test resource. Deleting the resource group also deletes any other resources associated with it.

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

-pip install openai requests tiktoken

-pip install "openai==0.28.1" requests tiktoken

-setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE"

-setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

-

- azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT"),

- api_key=os.getenv("AZURE_OPENAI_API_KEY"),

- api_version="2024-02-01" # This API version or later is required to access fine-tuning for turbo/babbage-002/davinci-002

- file=open(training_file_name, "rb"), purpose="fine-tune"

- file=open(validation_file_name, "rb"), purpose="fine-tune"

-openai.api_key = os.getenv("AZURE_OPENAI_API_KEY")

- file=open(training_file_name, "rb"), purpose="fine-tune", user_provided_filename="training_set.jsonl"

- file=open(validation_file_name, "rb"), purpose="fine-tune", user_provided_filename="validation_set.jsonl"

- training_file=training_file_id,

- validation_file=validation_file_id,

- model="gpt-35-turbo-0613", # Enter base model name. Note that in Azure OpenAI the model name contains dashes and cannot contain dot/period characters.

- training_file=training_file_id,

- validation_file=validation_file_id,

- model="gpt-35-turbo-0613",

-

-

-#Retrieve fine_tuned_model name

-#Retrieve fine_tuned_model name

-token= os.getenv("TEMP_AUTH_TOKEN")

-subscription = "<YOUR_SUBSCRIPTION_ID>"

-model_deployment_name ="YOUR_CUSTOM_MODEL_DEPLOYMENT_NAME"

-deploy_params = {'api-version': "2023-05-01"}

- "sku": {"name": "standard", "capacity": 1},

- azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT"),

- api_key=os.getenv("AZURE_OPENAI_API_KEY"),

- api_version="2024-02-01"

- model="gpt-35-turbo-ft", # model = "Custom deployment name you chose for your fine-tuning model"

- messages=[

-openai.api_base = os.getenv("AZURE_OPENAI_ENDPOINT")

- engine="gpt-35-turbo-ft", # engine = "Custom deployment name you chose for your fine-tuning model"

- messages=[

-You can delete the deployment in [Azure OpenAI Studio](https://oai.azure.com/), via [REST API](/rest/api/aiservices/accountmanagement/deployments/delete?tabs=HTTP), [Azure CLI](/cli/azure/cognitiveservices/account/deployment#az-cognitiveservices-account-deployment-delete()), or other supported deployment methods.

-

-If you want to clean up and remove an OpenAI or Azure AI Search resource, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it.

-**Content filtering is temporarily off** by default. Azure content moderation works differently than OpenAI. Azure OpenAI runs content filters during the generation call to detect harmful or abusive content and filters them from the response. [Learn MoreΓÇï](./concepts/content-filter.md)

-If you want to clean up and remove an OpenAI resource, you can delete the resource. Before deleting the resource, you must first delete any deployed models.

-description: Provides an overview of available Azure AI REST APIs with links to reference documentation.

-# Azure AI REST API reference

-This article provides an overview of available Azure AI REST APIs with links to service and feature level reference documentation.

-|  [Azure AI Search](../../search/index.yml) | Bring AI-powered cloud search to your mobile and web apps | [Azure AI Search API](/rest/api/searchservice) |

-| </br>&bullet; [fine-tuning](/rest/api/azureopenai/fine-tuning) |

-|  [Bot Service](/composer/) | Create bots and connect them across channels | [Bot Service API](/azure/bot-service/rest-api/bot-framework-rest-connector-api-reference?view=azure-bot-service-4.0&preserve-view=true) |

-|  [Content Safety](../../ai-services/content-safety/index.yml) | An AI service that detects unwanted contents | [Content Safety API](https://westus.dev.cognitive.microsoft.com/docs/services/content-safety-service-2023-10-15-preview/operations/TextBlocklists_AddOrUpdateBlocklistItems) |

-|  [Custom Vision](../../ai-services/custom-vision-service/index.yml) | Customize image recognition for your business applications. |**Custom Vision APIs**<br>&bullet; [prediction](https://westus2.dev.cognitive.microsoft.com/docs/services/Custom_Vision_Prediction_3.1/operations/5eb37d24548b571998fde5f3)<br>&bullet; [training](https://westus2.dev.cognitive.microsoft.com/docs/services/Custom_Vision_Training_3.3/operations/5eb0bcc6548b571998fddebd)|

-|  [Document Intelligence](../../ai-services/document-intelligence/index.yml) | Turn documents into intelligent data-driven solutions | [Document Intelligence API](/rest/api/aiservices/document-models?view=rest-aiservices-2023-07-31&preserve-view=true) |

-|  |

-|  [Language](../../ai-services/language-service/index.yml) | Build apps with industry-leading natural language understanding capabilities | [REST API](/rest/api/language/) |

-|  |

-| |

-|  [Video Indexer](/azure/azure-video-indexer) | Extract actionable insights from your videos | [Video Indexer API](/rest/api/videoindexer/accounts?view=rest-videoindexer-2024-01-01&preserve-view=true) |

-|  [Vision](../../ai-services/computer-vision/index.yml) | Analyze content in images and videos | [Vision API](https://eastus.dev.cognitive.microsoft.com/docs/services/Cognitive_Services_Unified_Vision_API_2024-02-01/operations/61d65934cd35050c20f73ab6) |

-|  [Anomaly Detector](../../ai-services/Anomaly-Detector/index.yml) <br>(deprecated 2023) | Identify potential problems early on | [Anomaly Detector API](https://westus2.dev.cognitive.microsoft.com/docs/services/AnomalyDetector-v1-1/operations/CreateMultivariateModel) |

-|  |

-|  [Language understanding (LUIS)](../../ai-services/luis/index.yml) <br>(deprecated 2023) | Understand natural language in your apps | [LUIS API](https://westus.dev.cognitive.microsoft.com/docs/services/luis-endpoint-api-v3-0/operations/5cb0a9459a1fe8fa44c28dd8) |

-|  [Metrics Advisor](../../ai-services/metrics-advisor/index.yml) <br>(deprecated 2023) | An AI service that detects unwanted contents | [Metrics Advisor API](https://westus.dev.cognitive.microsoft.com/docs/services/MetricsAdvisor/operations/createDataFeed) |

-|  [Personalizer](../../ai-services/personalizer/index.yml) <br>(deprecated 2023) | Create rich, personalized experiences for each user | [Personalizer API](https://westus2.dev.cognitive.microsoft.com/docs/services/personalizer-api/operations/Rank) |

-|  [QnA maker](../../ai-services/qnamaker/index.yml) <br>(deprecated 2022) | Distill information into easy-to-navigate questions and answers | [QnA Maker API](https://westus.dev.cognitive.microsoft.com/docs/services/5a93fcf85b4ccd136866eb37/operations/5ac266295b4ccd1554da75ff) |

-# Azure AI SDK reference

-To create a transcription, use the [Transcriptions_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Create) operation of the [Speech to text REST API](rest-speech-to-text.md#transcriptions). Construct the request body according to the following instructions:

-Make an HTTP POST request that uses the URI as shown in the following [Transcriptions_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Create) example.

-The top-level `self` property in the response body is the transcription's URI. Use this URI to [get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Get) details such as the URI of the transcriptions and transcription report files. You also use this URI to [update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Update) or [delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Delete) a transcription.

-You can query the status of your transcriptions with the [Transcriptions_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Get) operation.

-Call [Transcriptions_Delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Delete)

-Here are some property options that you can use to configure a transcription when you call the [Transcriptions_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Create) operation.

-|`diarization`|Indicates that the Speech service should attempt diarization analysis on the input, which is expected to be a mono channel that contains multiple voices. The feature isn't available with stereo recordings.<br/><br/>Diarization is the process of separating speakers in audio data. The batch pipeline can recognize and separate multiple speakers on mono channel recordings.<br/><br/>Specify the minimum and maximum number of people who might be speaking. You must also set the `diarizationEnabled` property to `true`. The [transcription file](batch-transcription-get.md#transcription-result-file) contains a `speaker` entry for each transcribed phrase.<br/><br/>You need to use this property when you expect three or more speakers. For two speakers, setting `diarizationEnabled` property to `true` is enough. For an example of the property usage, see [Transcriptions_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Create).<br/><br/>The maximum number of speakers for diarization must be less than 36 and more or equal to the `minSpeakers` property. For an example, see [Transcriptions_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Create).<br/><br/>When this property is selected, source audio length can't exceed 240 minutes per file.<br/><br/>**Note**: This property is only available with Speech to text REST API version 3.1 and later. If you set this property with any previous version, such as version 3.0, it's ignored and only two speakers are identified.|

-|`timeToLive`|A duration after the transcription job is created, when the transcription results will be automatically deleted. The value is an ISO 8601 encoded duration. For example, specify `PT12H` for 12 hours. As an alternative, you can call [Transcriptions_Delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Delete) regularly after you retrieve the transcription results.|

-Whisper models by batch transcription are supported in the East US, Southeast Asia, and West Europe regions.

-You can make a [Models_ListBaseModels](https://westus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-2-preview2/operations/Models_ListBaseModels) request to get available base models for all locales.

-To get the status of the transcription job, call the [Transcriptions_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Get) operation of the [Speech to text REST API](rest-speech-to-text.md).

-The [Transcriptions_ListFiles](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_ListFiles) operation returns a list of result files for a transcription. A [transcription report](#transcription-report-file) file is provided for each submitted batch transcription job. In addition, one [transcription](#transcription-result-file) file (the end result) is provided for each successfully transcribed audio file.

-Batch transcription is used to transcribe a large amount of audio data in storage. Both the [Speech to text REST API](rest-speech-to-text.md#transcriptions) and [Speech CLI](spx-basics.md) support batch transcription.

-[Speech to text REST API](rest-speech-to-text.md) fully supports BYOS-enabled Speech resources. However, because the data is now stored within the BYOS-enabled Storage account, requests like [Get Transcription Files](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_ListFiles) interact with the BYOS-associated Storage account Blob storage, instead of Speech service internal resources. It allows using the same REST API based code for both "regular" and BYOS-enabled Speech resources.

-For maximum security use the `sasValidityInSeconds` parameter with the value set to `0` in the requests, that return data file URLs, like [Get Transcription Files](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_ListFiles) request. Here's an example request URL:

-> If `sasValidityInSeconds` parameter is omitted in [Get Transcription Files](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_ListFiles) request or similar ones, then a [User delegation SAS](../../storage/common/storage-sas-overview.md) with the validity of 30 days will be generated for each data file URL returned. This SAS is signed by the system assigned managed identity of your BYOS-enabled Speech resource. Because of it, the SAS allows access to the data, even if storage account key access is disabled. See details [here](../../storage/common/shared-key-authorization-prevent.md#understand-how-disallowing-shared-key-affects-sas-tokens).

-[Speech to text REST API](rest-speech-to-text.md) fully supports BYOS-enabled Speech resources. However, because the data is now stored within the BYOS-enabled Storage account, requests like [Get Base Model Logs](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_ListBaseModelLogs) interact with the BYOS-associated Storage account Blob storage, instead of Speech service internal resources. It allows using the same REST API based code for both "regular" and BYOS-enabled Speech resources.

-For maximum security use the `sasValidityInSeconds` parameter with the value set to `0` in the requests, that return data file URLs, like [Get Base Model Logs](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_ListBaseModelLogs) request. Here's an example request URL:

-> If `sasValidityInSeconds` parameter is omitted in [Get Base Model Logs](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_ListBaseModelLogs) request or similar ones, then a [User delegation SAS](../../storage/common/storage-sas-overview.md) with the validity of 30 days will be generated for each data file URL returned. This SAS is signed by the system assigned managed identity of your BYOS-enabled Speech resource. Because of it, the SAS allows access to the data, even if storage account key access is disabled. See details [here](../../storage/common/shared-key-authorization-prevent.md#understand-how-disallowing-shared-key-affects-sas-tokens).

-[Speech to text REST API](rest-speech-to-text.md) fully supports BYOS-enabled Speech resources. However, because the data is now stored within the BYOS-enabled Storage account, requests like [Get Dataset Files](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_ListFiles) interact with the BYOS-associated Storage account Blob storage, instead of Speech service internal resources. It allows using the same REST API based code for both "regular" and BYOS-enabled Speech resources.

-For maximum security use the `sasValidityInSeconds` parameter with the value set to `0` in the requests, that return data file URLs, like [Get Dataset Files](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_ListFiles) request. Here's an example request URL:

-> If `sasValidityInSeconds` parameter is omitted in [Get Dataset Files](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_ListFiles) request or similar ones, then a [User delegation SAS](../../storage/common/storage-sas-overview.md) with the validity of 30 days will be generated for each data file URL returned. This SAS is signed by the system assigned managed identity of your BYOS-enabled Speech resource. Because of it, the SAS allows access to the data, even if storage account key access is disabled. See details [here](../../storage/common/shared-key-authorization-prevent.md#understand-how-disallowing-shared-key-affects-sas-tokens).

- <version>1.36.0</version>

- implementation 'com.microsoft.cognitiveservices.speech:client-sdk-embedded:1.36.0@aar'

-To create a project, use the [Projects_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_Create) operation of the [Speech to text REST API](rest-speech-to-text.md). Construct the request body according to the following instructions:

-Make an HTTP POST request using the URI as shown in the following [Projects_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_Create) example. Replace `YourSubscriptionKey` with your Speech resource key, replace `YourServiceRegion` with your Speech resource region, and set the request body properties as previously described.

-The top-level `self` property in the response body is the project's URI. Use this URI to [get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_Get) details about the project's evaluations, datasets, models, endpoints, and transcriptions. You also use this URI to [update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_Update) or [delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_Delete) a project.

-To create an endpoint and deploy a model, use the [Endpoints_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_Create) operation of the [Speech to text REST API](rest-speech-to-text.md). Construct the request body according to the following instructions:

-Make an HTTP POST request using the URI as shown in the following [Endpoints_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_Create) example. Replace `YourSubscriptionKey` with your Speech resource key, replace `YourServiceRegion` with your Speech resource region, and set the request body properties as previously described.

-The top-level `self` property in the response body is the endpoint's URI. Use this URI to [get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_Get) details about the endpoint's project, model, and logs. You also use this URI to [update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_Update) or [delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_Delete) the endpoint.

-To redeploy the custom endpoint with a new model, use the [Endpoints_Update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_Update) operation of the [Speech to text REST API](rest-speech-to-text.md). Construct the request body according to the following instructions:

-To get logs for an endpoint, start by using the [Endpoints_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_Get) operation of the [Speech to text REST API](rest-speech-to-text.md).

-To create a test, use the [Evaluations_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_Create) operation of the [Speech to text REST API](rest-speech-to-text.md). Construct the request body according to the following instructions:

-The top-level `self` property in the response body is the evaluation's URI. Use this URI to [get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_Get) details about the evaluation's project and test results. You also use this URI to [update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_Update) or [delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_Delete) the evaluation.

-To get test results, start by using the [Evaluations_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_Get) operation of the [Speech to text REST API](rest-speech-to-text.md).

-To create a test, use the [Evaluations_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_Create) operation of the [Speech to text REST API](rest-speech-to-text.md). Construct the request body according to the following instructions:

-The top-level `self` property in the response body is the evaluation's URI. Use this URI to [get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_Get) details about the evaluation's project and test results. You also use this URI to [update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_Update) or [delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_Delete) the evaluation.

-To get test results, start by using the [Evaluations_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_Get) operation of the [Speech to text REST API](rest-speech-to-text.md).

-|Batch transcription |[Batch transcription](batch-transcription.md) requests for expired models fail with a 4xx error. |In each [Transcriptions_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Create) REST API request body, set the `model` property to a base model or custom model that isn't expired. Otherwise don't include the `model` property to always use the latest base model. |

-To get the training and transcription expiration dates for a base model, use the [Models_GetBaseModel](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_GetBaseModel) operation of the [Speech to text REST API](rest-speech-to-text.md). You can make a [Models_ListBaseModels](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_ListBaseModels) request to get available base models for all locales.

-To get the transcription expiration date for your custom model, use the [Models_GetCustomModel](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_GetCustomModel) operation of the [Speech to text REST API](rest-speech-to-text.md).

-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 20 hours of your audio training data, and can process about 10 hours of data per day. In other regions, the Speech service uses up to 8 hours of your audio data, and can process about 1 hour of data per day. After the model is trained, you can copy the model to another region as needed with the [Models_CopyTo](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_CopyTo) REST API.

-To create a model with datasets for training, use the [Models_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_Create) operation of the [Speech to text REST API](rest-speech-to-text.md). Construct the request body according to the following instructions:

-The top-level `self` property in the response body is the model's URI. Use this URI to [get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_GetCustomModel) details about the model's project, manifest, and deprecation dates. You also use this URI to [update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_Update) or [delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_Delete) the model.

-To copy a model to another Speech resource, use the [Models_CopyTo](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_CopyTo) operation of the [Speech to text REST API](rest-speech-to-text.md). Construct the request body according to the following instructions:

-To connect a new model to a project of the Speech resource where the model was copied, use the [Models_Update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_Update) operation of the [Speech to text REST API](rest-speech-to-text.md). Construct the request body according to the following instructions:

-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_CopyTo](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_CopyTo) 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.

-To create a dataset and connect it to an existing project, use the [Datasets_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_Create) operation of the [Speech to text REST API](rest-speech-to-text.md). Construct the request body according to the following instructions:

-The top-level `self` property in the response body is the dataset's URI. Use this URI to [get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_Get) details about the dataset's project and files. You also use this URI to [update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_Update) or [delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_Delete) the dataset.

-The required Transcription ID is the GUID value contained in the main `self` element of the Response body returned by requests, like [Transcriptions_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Create).

-The following is and example response body of a [Transcriptions_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Create) request. GUID value `537216f8-0620-4a10-ae2d-00bdb423b36f` found in the first `self` element is the Transcription ID.

-> Use the same technique to determine different IDs required for debugging issues related to [custom speech](custom-speech-overview.md), like uploading a dataset using [Datasets_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_Create) request.

-> You can also see all existing transcriptions and their Transcription IDs for a given Speech resource by using [Transcriptions_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Get) request.

-To identify languages with [Batch transcription REST API](batch-transcription.md), use `languageIdentification` property in the body of your [Transcriptions_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Create) request.

-To turn off logging for a custom endpoint, use the [Endpoints_Update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_Update) operation of the [Speech to text REST API](rest-speech-to-text.md). Construct the request body according to the following instructions:

-Here's a sample output of [Endpoints_ListLogs](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_ListLogs). For simplicity, only one log set is shown:

-description: This document helps developers migrate code from v2 to v3 of the Speech to text REST API.speech-to-text REST API.

-# Migrate code from v2.0 to v3.0 of the REST API

-> [!IMPORTANT]

-> The Speech to text REST API v2.0 is retired as of February 29, 2024. Please migrate your applications to the Speech to text REST API v3.2. Complete the steps in this article and then see the Speech to text REST API [v3.0 to v3.1](migrate-v3-0-to-v3-1.md) and [v3.1 to v3.2](migrate-v3-1-to-v3-2.md) migration guides for additional requirements.

-## Forward compatibility

-All entities from v2.0 can also be found in the v3.0 API under the same identity. Where the schema of a result has changed (such as transcriptions), the result of a GET in the v3 version of the API uses the v3 schema. The result of a GET in the v2 version of the API uses the same v2 schema. Newly created entities on v3 aren't available in responses from v2 APIs.

-## Migration steps

-This is a summary list of items you need to be aware of when you're preparing for migration. Details are found in the individual links. Depending on your current use of the API not all steps listed here might apply. Only a few changes require nontrivial changes in the calling code. Most changes just require a change to item names.

-General changes:

-1. [Change the host name](#host-name-changes)

-1. [Rename the property ID to self in your client code](#identity-of-an-entity)

-1. [Change code to iterate over collections of entities](#working-with-collections-of-entities)

-1. [Rename the property name to displayName in your client code](#name-of-an-entity)

-1. [Adjust the retrieval of the metadata of referenced entities](#accessing-referenced-entities)

-1. If you use Batch transcription:

- * [Adjust code for creating batch transcriptions](#creating-transcriptions)

- * [Adapt code to the new transcription results schema](#format-of-v3-transcription-results)

- * [Adjust code for how results are retrieved](#getting-the-content-of-entities-and-the-results)

-1. If you use Custom model training/testing APIs:

- * [Apply modifications to custom model training](#customizing-models)

- * [Change how base and custom models are retrieved](#retrieving-base-and-custom-models)

- * [Rename the path segment accuracy tests to evaluations in your client code](#accuracy-tests)

-1. If you use endpoints APIs:

- * [Change how endpoint logs are retrieved](#retrieving-endpoint-logs)

-1. Other minor changes:

- * [Pass all custom properties as customProperties instead of properties in your POST requests](#using-custom-properties)

- * [Read the location from response header Location instead of Operation-Location](#response-headers)

-## Breaking changes

-### Host name changes

-Endpoint host names changed from `{region}.cris.ai` to `{region}.api.cognitive.microsoft.com`. Paths to the new endpoints no longer contain `api/` because it's part of the hostname. The [Speech to text REST API v3.0](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0) reference documentation lists valid regions and paths.

->[!IMPORTANT]

->Change the hostname from `{region}.cris.ai` to `{region}.api.cognitive.microsoft.com` where region is the region of your speech subscription. Also remove `api/`from any path in your client code.

-### Identity of an entity

-The property `id` is now `self`. In v2, an API user had to know how our paths on the API are being created. This was non-extensible and required unnecessary work from the user. The property `id` (uuid) is replaced by `self` (string), which is location of the entity (URL). The value is still unique between all your entities. If `id` is stored as a string in your code, a rename is enough to support the new schema. You can now use the `self` content as the URL for the `GET`, `PATCH`, and `DELETE` REST calls for your entity.

-If the entity has more functionality available through other paths, they're listed under `links`. The following example for transcription shows a separate method to `GET` the content of the transcription:

->[!IMPORTANT]

->Rename the property `id` to `self` in your client code. Change the type from `uuid` to `string` if needed.

-**v2 transcription:**

-```json

-{

- "id": "9891c965-bb32-4880-b14b-6d44efb158f3",

- "createdDateTime": "2019-01-07T11:34:12Z",

- "lastActionDateTime": "2019-01-07T11:36:07Z",

- "status": "Succeeded",

- "locale": "en-US",

- "name": "Transcription using locale en-US"

-}

-```

-**v3 transcription:**

-```json

-{

- "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/transcriptions/9891c965-bb32-4880-b14b-6d44efb158f3",

- "createdDateTime": "2019-01-07T11:34:12Z",

- "lastActionDateTime": "2019-01-07T11:36:07Z",

- "status": "Succeeded",

- "locale": "en-US",

- "displayName": "Transcription using locale en-US",

- "links": {

- "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/transcriptions/9891c965-bb32-4880-b14b-6d44efb158f3/files"

- }

-}

-```

-Depending on your code's implementation, it might not be enough to rename the property. We recommend using the returned `self` and `links` values as the target urls of your REST calls, rather than generating paths in your client. By using the returned URLs, you can be sure that future changes in paths won't break your client code.

-### Working with collections of entities

-Previously the v2 API returned all available entities in a result. To allow a more fine grained control over the expected response size in v3, all collection results are paginated. You have control over the count of returned entities and the starting offset of the page. This behavior makes it easy to predict the runtime of the response processor.

-The basic shape of the response is the same for all collections:

-```json

-{

- "values": [

- {

- }

- ],

- "@nextLink": "https://{region}.api.cognitive.microsoft.com/speechtotext/v3.0/{collection}?skip=100&top=100"

-}

-```

-The `values` property contains a subset of the available collection entities. The count and offset can be controlled using the `skip` and `top` query parameters. When `@nextLink` isn't `null`, there's more data available and the next batch of data can be retrieved by doing a GET on `$.@nextLink`.

-This change requires calling the `GET` for the collection in a loop until all elements are returned.

->[!IMPORTANT]

->When the response of a GET to `speechtotext/v3.1/{collection}` contains a value in `$.@nextLink`, continue issuing `GETs` on `$.@nextLink` until `$.@nextLink` is not set to retrieve all elements of that collection.

-### Creating transcriptions

-A detailed description on how to create batches of transcriptions can be found in [Batch transcription How-to](./batch-transcription.md).

-The v3 transcription API lets you set specific transcription options explicitly. All (optional) configuration properties can now be set in the `properties` property.

-Version v3 also supports multiple input files, so it requires a list of URLs rather than a single URL as v2 did. The v2 property name `recordingsUrl` is now `contentUrls` in v3. The functionality of analyzing sentiment in transcriptions is removed in v3. See [Text Analysis](https://azure.microsoft.com/services/cognitive-services/text-analytics/) for sentiment analysis options.

-The new property `timeToLive` under `properties` can help prune the existing completed entities. The `timeToLive` specifies a duration after which a completed entity is deleted automatically. Set it to a high value (for example `PT12H`) when the entities are continuously tracked, consumed, and deleted and therefore usually processed long before 12 hours have passed.

-**v2 transcription POST request body:**

-```json

-{

- "locale": "en-US",

- "name": "Transcription using locale en-US",

- "recordingsUrl": "https://contoso.com/mystoragelocation",

- "properties": {

- "AddDiarization": "False",

- "AddWordLevelTimestamps": "False",

- "PunctuationMode": "DictatedAndAutomatic",

- "ProfanityFilterMode": "Masked"

- }

-}

-```

-**v3 transcription POST request body:**

-```json

-{

- "locale": "en-US",

- "displayName": "Transcription using locale en-US",

- "contentUrls": [

- "https://contoso.com/mystoragelocation",

- "https://contoso.com/myotherstoragelocation"

- ],

- "properties": {

- "diarizationEnabled": false,

- "wordLevelTimestampsEnabled": false,

- "punctuationMode": "DictatedAndAutomatic",

- "profanityFilterMode": "Masked"

- }

-}

-```

->[!IMPORTANT]

->Rename the property `recordingsUrl` to `contentUrls` and pass an array of urls instead of a single url. Pass settings for `diarizationEnabled` or `wordLevelTimestampsEnabled` as `bool` instead of `string`.

-### Format of v3 transcription results

-The schema of transcription results has changed slightly to align with transcriptions created by real-time endpoints. Find an in-depth description of the new format in the [Batch transcription How-to](./batch-transcription.md). The schema of the result is published in our [GitHub sample repository](https://aka.ms/csspeech/samples) under `samples/batch/transcriptionresult_v3.schema.json`.

-Property names are now camel-cased and the values for `channel` and `speaker` now use integer types. Formats for durations now use the structure described in ISO 8601, which matches duration formatting used in other Azure APIs.

-Sample of a v3 transcription result. The differences are described in the comments.

-```json

-{

- "source": "...", // (new in v3) was AudioFileName / AudioFileUrl

- "timestamp": "2020-06-16T09:30:21Z", // (new in v3)

- "durationInTicks": 41200000, // (new in v3) was AudioLengthInSeconds

- "duration": "PT4.12S", // (new in v3)

- "combinedRecognizedPhrases": [ // (new in v3) was CombinedResults

- {

- "channel": 0, // (new in v3) was ChannelNumber

- "lexical": "hello world",

- "itn": "hello world",

- "maskedITN": "hello world",

- "display": "Hello world."

- }

- ],

- "recognizedPhrases": [ // (new in v3) was SegmentResults

- {

- "recognitionStatus": "Success", //

- "channel": 0, // (new in v3) was ChannelNumber

- "offset": "PT0.07S", // (new in v3) new format, was OffsetInSeconds

- "duration": "PT1.59S", // (new in v3) new format, was DurationInSeconds

- "offsetInTicks": 700000.0, // (new in v3) was Offset

- "durationInTicks": 15900000.0, // (new in v3) was Duration

- // possible transcriptions of the current phrase with confidences

- "nBest": [

- {

- "confidence": 0.898652852,phrase

- "speaker": 1,

- "lexical": "hello world",

- "itn": "hello world",

- "maskedITN": "hello world",

- "display": "Hello world.",

- "words": [

- {

- "word": "hello",

- "offset": "PT0.09S",

- "duration": "PT0.48S",

- "offsetInTicks": 900000.0,

- "durationInTicks": 4800000.0,

- "confidence": 0.987572

- },

- {

- "word": "world",

- "offset": "PT0.59S",

- "duration": "PT0.16S",

- "offsetInTicks": 5900000.0,

- "durationInTicks": 1600000.0,

- "confidence": 0.906032

- }

- ]

- }

- ]

- }

- ]

-}

-```

->[!IMPORTANT]

->Deserialize the transcription result into the new type as shown previously. Instead of a single file per audio channel, distinguish channels by checking the property value of `channel` for each element in `recognizedPhrases`. There is now a single result file for each input file.

-### Getting the content of entities and the results

-In v2, the links to the input or result files are inline with the rest of the entity metadata. As an improvement in v3, there's a clear separation between entity metadata (which is returned by a GET on `$.self`) and the details and credentials to access the result files. This separation helps protect customer data and allows fine control over the duration of validity of the credentials.

-In v3, `links` include a sub-property called `files` in case the entity exposes data (datasets, transcriptions, endpoints, or evaluations). A GET on `$.links.files` returns a list of files and a SAS URL

-to access the content of each file. To control the validity duration of the SAS URLs, the query parameter `sasValidityInSeconds` can be used to specify the lifetime.

-**v2 transcription:**

-```json

-{

- "id": "9891c965-bb32-4880-b14b-6d44efb158f3",

- "status": "Succeeded",

- "reportFileUrl": "https://contoso.com/report.txt?st=2018-02-09T18%3A07%3A00Z&se=2018-02-10T18%3A07%3A00Z&sp=rl&sv=2017-04-17&sr=b&sig=6c044930-3926-4be4-be76-f728327c53b5",

- "resultsUrls": {

- "channel_0": "https://contoso.com/audiofile1.wav?st=2018-02-09T18%3A07%3A00Z&se=2018-02-10T18%3A07%3A00Z&sp=rl&sv=2017-04-17&sr=b&sig=6c044930-3926-4be4-be76-f72832e6600c",

- "channel_1": "https://contoso.com/audiofile2.wav?st=2018-02-09T18%3A07%3A00Z&se=2018-02-10T18%3A07%3A00Z&sp=rl&sv=2017-04-17&sr=b&sig=3e0163f1-0029-4d4a-988d-3fba7d7c53b5"

- }

-}

-```

-**v3 transcription:**

-```json

-{

- "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/transcriptions/9891c965-bb32-4880-b14b-6d44efb158f3",

- "links": {

- "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/transcriptions/9891c965-bb32-4880-b14b-6d44efb158f3/files"

- }

-}

-```

-**A GET on `$.links.files` would result in:**

-```json

-{

- "values": [

- {

- "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/transcriptions/9891c965-bb32-4880-b14b-6d44efb158f3/files/f23e54f5-ed74-4c31-9730-2f1a3ef83ce8",

- "name": "Name",

- "kind": "Transcription",

- "properties": {

- "size": 200

- },

- "createdDateTime": "2020-01-13T08:00:00Z",

- "links": {

- "contentUrl": "https://customspeech-usw.blob.core.windows.net/artifacts/mywavefile1.wav.json?st=2018-02-09T18%3A07%3A00Z&se=2018-02-10T18%3A07%3A00Z&sp=rl&sv=2017-04-17&sr=b&sig=e05d8d56-9675-448b-820c-4318ae64c8d5"

- }

- },

- {

- "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/transcriptions/9891c965-bb32-4880-b14b-6d44efb158f3/files/28bc946b-c251-4a86-84f6-ea0f0a2373ef",

- "name": "Name",

- "kind": "TranscriptionReport",

- "properties": {

- "size": 200

- },

- "createdDateTime": "2020-01-13T08:00:00Z",

- "links": {

- "contentUrl": "https://customspeech-usw.blob.core.windows.net/artifacts/report.json?st=2018-02-09T18%3A07%3A00Z&se=2018-02-10T18%3A07%3A00Z&sp=rl&sv=2017-04-17&sr=b&sig=e05d8d56-9675-448b-820c-4318ae64c8d5"

- }

- }

- ],

- "@nextLink": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/transcriptions/9891c965-bb32-4880-b14b-6d44efb158f3/files?skip=2&top=2"

-}

-```

-The `kind` property indicates the format of content of the file. For transcriptions, the files of kind `TranscriptionReport` are the summary of the job and files of the kind `Transcription` are the result of the job itself.

->[!IMPORTANT]

->To get the results of operations, use a `GET` on `/speechtotext/v3.0/{collection}/{id}/files`, they are no longer contained in the responses of `GET` on `/speechtotext/v3.0/{collection}/{id}` or `/speechtotext/v3.0/{collection}`.

-### Customizing models

-Before v3, there was a distinction between an _acoustic model_ and a _language model_ when a model was being trained. This distinction resulted in the need to specify multiple models when creating endpoints or transcriptions. To simplify this process for a caller, we removed the differences and made everything depend on the content of the datasets that are being used for model training. With this change, the model creation now supports mixed datasets (language data and acoustic data). Endpoints and transcriptions now require only one model.

-With this change, the need for a `kind` in the `POST` operation is removed and the `datasets[]` array can now contain multiple datasets of the same or mixed kinds.

-To improve the results of a trained model, the acoustic data is automatically used internally during language training. In general, models created through the v3 API deliver more accurate results than models created with the v2 API.

->[!IMPORTANT]

->To customize both the acoustic and language model part, pass all of the required language and acoustic datasets in `datasets[]` of the POST to `/speechtotext/v3.0/models`. This will create a single model with both parts customized.

-### Retrieving base and custom models

-To simplify getting the available models, v3 has separated the collections of "base models" from the customer owned "customized models". The two routes are now

-`GET /speechtotext/v3.0/models/base` and `GET /speechtotext/v3.0/models/`.

-In v2, all models were returned together in a single response.

->[!IMPORTANT]

->To get a list of provided base models for customization, use `GET` on `/speechtotext/v3.0/models/base`. You can find your own customized models with a `GET` on `/speechtotext/v3.0/models`.

-### Name of an entity

-The `name` property is now `displayName`. This is consistent with other Azure APIs to not indicate identity properties. The value of this property must not be unique and can be changed after entity creation with a `PATCH` operation.

-**v2 transcription:**

-```json

-{

- "name": "Transcription using locale en-US"

-}

-```

-**v3 transcription:**

-```json

-{

- "displayName": "Transcription using locale en-US"

-}

-```

->[!IMPORTANT]

->Rename the property `name` to `displayName` in your client code.

-### Accessing referenced entities

-In v2, referenced entities were always inlined, for example the used models of an endpoint. The nesting of entities resulted in large responses and consumers rarely consumed the nested content. To shrink the response size and improve performance, the referenced entities are no longer inlined in the response. Instead, a reference to the other entity appears, and can directly be used for a subsequent `GET` (it's a URL as well), following the same pattern as the `self` link.

-**v2 transcription:**

-```json

-{

- "id": "9891c965-bb32-4880-b14b-6d44efb158f3",

- "models": [

- {

- "id": "827712a5-f942-4997-91c3-7c6cde35600b",

- "modelKind": "Language",

- "lastActionDateTime": "2019-01-07T11:36:07Z",

- "status": "Running",

- "createdDateTime": "2019-01-07T11:34:12Z",

- "locale": "en-US",

- "name": "Acoustic model",

- "description": "Example for an acoustic model",

- "datasets": [

- {

- "id": "702d913a-8ba6-4f66-ad5c-897400b081fb",

- "dataImportKind": "Language",

- "lastActionDateTime": "2019-01-07T11:36:07Z",

- "status": "Succeeded",

- "createdDateTime": "2019-01-07T11:34:12Z",

- "locale": "en-US",

- "name": "Language dataset",

- }

- ]

- },

- ]

-}

-```

-**v3 transcription:**

-```json

-{

- "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/transcriptions/9891c965-bb32-4880-b14b-6d44efb158f3",

- "model": {

- "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/models/021a72d0-54c4-43d3-8254-27336ead9037"

- }

-}

-```

-If you need to consume the details of a referenced model as shown in the above example, just issue a GET on `$.model.self`.

->[!IMPORTANT]

->To retrieve the metadata of referenced entities, issue a GET on `$.{referencedEntity}.self`, for example to retrieve the model of a transcription do a `GET` on `$.model.self`.

-### Retrieving endpoint logs

-Version v2 of the service supported logging endpoint results. To retrieve the results of an endpoint with v2, you would create a "data export", which represented a snapshot of the results defined by a time range. The process of exporting batches of data was inflexible. The v3 API gives access to each individual file and allows iteration through them.

-**A successfully running v3 endpoint:**

-```json

-{

- "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/endpoints/afa0669c-a01e-4693-ae3a-93baf40f26d6",

- "links": {

- "logs": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/endpoints/afa0669c-a01e-4693-ae3a-93baf40f26d6/files/logs"

- }

-}

-```

-**Response of GET `$.links.logs`:**

-```json

-{

- "values": [

- {

- "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/endpoints/6d72ad7e-f286-4a6f-b81b-a0532ca6bcaa/files/logs/2019-09-20_080000_3b5f4628-e225-439d-bd27-8804f9eed13f.wav",

- "name": "2019-09-20_080000_3b5f4628-e225-439d-bd27-8804f9eed13f.wav",

- "kind": "Audio",

- "properties": {

- "size": 12345

- },

- "createdDateTime": "2020-01-13T08:00:00Z",

- "links": {

- "contentUrl": "https://customspeech-usw.blob.core.windows.net/artifacts/2019-09-20_080000_3b5f4628-e225-439d-bd27-8804f9eed13f.wav?st=2018-02-09T18%3A07%3A00Z&se=2018-02-10T18%3A07%3A00Z&sp=rl&sv=2017-04-17&sr=b&sig=e05d8d56-9675-448b-820c-4318ae64c8d5"

- }

- }

- ],

- "@nextLink": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/endpoints/afa0669c-a01e-4693-ae3a-93baf40f26d6/files/logs?top=2&SkipToken=2!188!MDAwMDk1ITZhMjhiMDllLTg0MDYtNDViMi1hMGRkLWFlNzRlOGRhZWJkNi8yMDIwLTA0LTAxLzEyNDY0M182MzI5NGRkMi1mZGYzLTRhZmEtOTA0NC1mODU5ZTcxOWJiYzYud2F2ITAwMDAyOCE5OTk5LTEyLTMxVDIzOjU5OjU5Ljk5OTk5OTlaIQ--"

-}

-```

-Pagination for endpoint logs works similar to all other collections, except that no offset can be specified. Due to the large amount of available data, pagination is determined by the server.

-In v3, each endpoint log can be deleted individually by issuing a `DELETE` operation on the `self` of a file, or by using `DELETE` on `$.links.logs`. To specify an end date, the query parameter `endDate` can be added to the request.

-> [!IMPORTANT]

-> Instead of creating log exports on `/api/speechtotext/v2.0/endpoints/{id}/data` use `/v3.0/endpoints/{id}/files/logs/` to access log files individually.

-### Using custom properties

-To separate custom properties from the optional configuration properties, all explicitly named properties are now located in the `properties` property and all properties defined by the callers are now located in the `customProperties` property.

-**v2 transcription entity:**

-```json

-{

- "properties": {

- "customerDefinedKey": "value",

- "diarizationEnabled": "False",

- "wordLevelTimestampsEnabled": "False"

- }

-}

-```

-**v3 transcription entity:**

-```json

-{

- "properties": {

- "diarizationEnabled": false,

- "wordLevelTimestampsEnabled": false

- },

- "customProperties": {

- "customerDefinedKey": "value"

- }

-}

-```

-This change also lets you use correct types on all explicitly named properties under `properties` (for example boolean instead of string).

->[!IMPORTANT]

->Pass all custom properties as `customProperties` instead of `properties` in your `POST` requests.

-### Response headers

-v3 no longer returns the `Operation-Location` header in addition to the `Location` header on `POST` requests. The value of both headers in v2 was the same. Now only `Location` is returned.

-Because the new API version is now managed by Azure API management (APIM), the throttling related headers `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` aren't contained in the response headers.

->[!IMPORTANT]

->Read the location from response header `Location` instead of `Operation-Location`. In case of a 429 response code, read the `Retry-After` header value instead of `X-RateLimit-Limit`, `X-RateLimit-Remaining`, or `X-RateLimit-Reset`.

-### Accuracy tests

-Accuracy tests have been renamed to evaluations because the new name describes better what they represent. The new paths are: `https://{region}.api.cognitive.microsoft.com/speechtotext/v3.0/evaluations`.

->[!IMPORTANT]

->Rename the path segment `accuracytests` to `evaluations` in your client code.

-## Next steps

-* [Speech to text REST API](rest-speech-to-text.md)

-* [Speech to text REST API v3.0 reference](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0)

-In the [Transcriptions_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Create) operation the following three properties are added:

-The `filter` property is added to the [Transcriptions_List](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_List), [Transcriptions_ListFiles](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_ListFiles), and [Projects_ListTranscriptions](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_ListTranscriptions) operations. The `filter` expression can be used to select a subset of the available resources. You can filter by `displayName`, `description`, `createdDateTime`, `lastActionDateTime`, `status`, and `locale`. For example: `filter=createdDateTime gt 2022-02-01T11:00:00Z`

-To support model adaptation with [structured text in markdown](how-to-custom-speech-test-and-train.md#structured-text-data-for-training) data, the [Datasets_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_Create) operation now supports the **LanguageMarkdown** data kind. For more information, see [upload datasets](how-to-custom-speech-upload-data.md#upload-datasets).

-The [Models_ListBaseModels](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_ListBaseModels) and [Models_GetBaseModel](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_GetBaseModel) operations return information on the type of adaptation supported by each base model.

-The [Models_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_Create) operation has a new `customModelWeightPercent` property where you can specify the weight used when the Custom Language Model (trained from plain or structured text data) is combined with the Base Language Model. Valid values are integers between 1 and 100. The default value is currently 30.

-Added the [Models_ListFiles](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_ListFiles) operation to get the files of the model identified by the given ID.

-Added the [Models_GetFile](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_GetFile) operation to get one specific file (identified with fileId) from a model (identified with ID). This lets you retrieve a **ModelReport** file that provides information on the data processed during training.

-The name of each `operationId` in version 3.1 is prefixed with the object name. For example, the `operationId` for "Create Model" changed from [CreateModel](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/CreateModel) in version 3.0 to [Models_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_Create) in version 3.1.

-|Path|Method|Version 3.1 Operation ID|Version 3.0 Operation ID|

-|||||

-|`/datasets`|GET|[Datasets_List](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_List)|[GetDatasets](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetDatasets)|

-|`/datasets`|POST|[Datasets_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_Create)|[CreateDataset](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/CreateDataset)|

-|`/datasets/{id}`|DELETE|[Datasets_Delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_Delete)|[DeleteDataset](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteDataset)|

-|`/datasets/{id}`|GET|[Datasets_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_Get)|[GetDataset](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetDataset)|

-|`/datasets/{id}`|PATCH|[Datasets_Update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_Update)|[UpdateDataset](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/UpdateDataset)|

-|`/datasets/{id}/blocks:commit`|POST|[Datasets_CommitBlocks](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_CommitBlocks)|Not applicable|

-|`/datasets/{id}/blocks`|GET|[Datasets_GetBlocks](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_GetBlocks)|Not applicable|

-|`/datasets/{id}/blocks`|PUT|[Datasets_UploadBlock](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_UploadBlock)|Not applicable|

-|`/datasets/{id}/files`|GET|[Datasets_ListFiles](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_ListFiles)|[GetDatasetFiles](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetDatasetFiles)|

-|`/datasets/{id}/files/{fileId}`|GET|[Datasets_GetFile](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_GetFile)|[GetDatasetFile](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetDatasetFile)|

-|`/datasets/locales`|GET|[Datasets_ListSupportedLocales](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_ListSupportedLocales)|[GetSupportedLocalesForDatasets](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetSupportedLocalesForDatasets)|

-|`/datasets/upload`|POST|[Datasets_Upload](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_Upload)|[UploadDatasetFromForm](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/UploadDatasetFromForm)|

-|`/endpoints`|GET|[Endpoints_List](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_List)|[GetEndpoints](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetEndpoints)|

-|`/endpoints`|POST|[Endpoints_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_Create)|[CreateEndpoint](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/CreateEndpoint)|

-|`/endpoints/{id}`|DELETE|[Endpoints_Delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_Delete)|[DeleteEndpoint](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteEndpoint)|

-|`/endpoints/{id}`|GET|[Endpoints_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_Get)|[GetEndpoint](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetEndpoint)|

-|`/endpoints/{id}`|PATCH|[Endpoints_Update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_Update)|[UpdateEndpoint](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/UpdateEndpoint)|

-|`/endpoints/{id}/files/logs`|DELETE|[Endpoints_DeleteLogs](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_DeleteLogs)|[DeleteEndpointLogs](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteEndpointLogs)|

-|`/endpoints/{id}/files/logs`|GET|[Endpoints_ListLogs](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_ListLogs)|[GetEndpointLogs](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetEndpointLogs)|

-|`/endpoints/{id}/files/logs/{logId}`|DELETE|[Endpoints_DeleteLog](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_DeleteLog)|[DeleteEndpointLog](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteEndpointLog)|

-|`/endpoints/{id}/files/logs/{logId}`|GET|[Endpoints_GetLog](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_GetLog)|[GetEndpointLog](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetEndpointLog)|

-|`/endpoints/base/{locale}/files/logs`|DELETE|[Endpoints_DeleteBaseModelLogs](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_DeleteBaseModelLogs)|[DeleteBaseModelLogs](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteBaseModelLogs)|

-|`/endpoints/base/{locale}/files/logs`|GET|[Endpoints_ListBaseModelLogs](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_ListBaseModelLogs)|[GetBaseModelLogs](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetBaseModelLogs)|

-|`/endpoints/base/{locale}/files/logs/{logId}`|DELETE|[Endpoints_DeleteBaseModelLog](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_DeleteBaseModelLog)|[DeleteBaseModelLog](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteBaseModelLog)|

-|`/endpoints/base/{locale}/files/logs/{logId}`|GET|[Endpoints_GetBaseModelLog](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_GetBaseModelLog)|[GetBaseModelLog](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetBaseModelLog)|

-|`/endpoints/locales`|GET|[Endpoints_ListSupportedLocales](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_ListSupportedLocales)|[GetSupportedLocalesForEndpoints](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetSupportedLocalesForEndpoints)|

-|`/evaluations`|GET|[Evaluations_List](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_List)|[GetEvaluations](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetEvaluations)|

-|`/evaluations`|POST|[Evaluations_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_Create)|[CreateEvaluation](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/CreateEvaluation)|

-|`/evaluations/{id}`|DELETE|[Evaluations_Delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_Delete)|[DeleteEvaluation](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteEvaluation)|

-|`/evaluations/{id}`|GET|[Evaluations_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_Get)|[GetEvaluation](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetEvaluation)|

-|`/evaluations/{id}`|PATCH|[Evaluations_Update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_Update)|[UpdateEvaluation](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/UpdateEvaluation)|

-|`/evaluations/{id}/files`|GET|[Evaluations_ListFiles](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_ListFiles)|[GetEvaluationFiles](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetEvaluationFiles)|

-|`/evaluations/{id}/files/{fileId}`|GET|[Evaluations_GetFile](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_GetFile)|[GetEvaluationFile](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetEvaluationFile)|

-|`/evaluations/locales`|GET|[Evaluations_ListSupportedLocales](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_ListSupportedLocales)|[GetSupportedLocalesForEvaluations](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetSupportedLocalesForEvaluations)|

-|`/healthstatus`|GET|[HealthStatus_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/HealthStatus_Get)|[GetHealthStatus](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetHealthStatus)|

-|`/models`|GET|[Models_ListCustomModels](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_ListCustomModels)|[GetModels](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetModels)|

-|`/models`|POST|[Models_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_Create)|[CreateModel](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/CreateModel)|

-|`/models/{id}:copyto`¹|POST|[Models_CopyTo](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_CopyTo)|[CopyModelToSubscription](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/CopyModelToSubscription)|

-|`/models/{id}`|DELETE|[Models_Delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_Delete)|[DeleteModel](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteModel)|

-|`/models/{id}`|GET|[Models_GetCustomModel](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_GetCustomModel)|[GetModel](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetModel)|

-|`/models/{id}`|PATCH|[Models_Update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_Update)|[UpdateModel](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/UpdateModel)|

-|`/models/{id}/files`|GET|[Models_ListFiles](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_ListFiles)|Not applicable|

-|`/models/{id}/files/{fileId}`|GET|[Models_GetFile](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_GetFile)|Not applicable|

-|`/models/{id}/manifest`|GET|[Models_GetCustomModelManifest](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_GetCustomModelManifest)|[GetModelManifest](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetModelManifest)|

-|`/models/base`|GET|[Models_ListBaseModels](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_ListBaseModels)|[GetBaseModels](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetBaseModels)|

-|`/models/base/{id}`|GET|[Models_GetBaseModel](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_GetBaseModel)|[GetBaseModel](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetBaseModel)|

-|`/models/base/{id}/manifest`|GET|[Models_GetBaseModelManifest](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_GetBaseModelManifest)|[GetBaseModelManifest](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetBaseModelManifest)|

-|`/models/locales`|GET|[Models_ListSupportedLocales](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_ListSupportedLocales)|[GetSupportedLocalesForModels](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetSupportedLocalesForModels)|

-|`/projects`|GET|[Projects_List](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_List)|[GetProjects](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetProjects)|

-|`/projects`|POST|[Projects_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_Create)|[CreateProject](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/CreateProject)|

-|`/projects/{id}`|DELETE|[Projects_Delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_Delete)|[DeleteProject](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteProject)|

-|`/projects/{id}`|GET|[Projects_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_Get)|[GetProject](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetProject)|

-|`/projects/{id}`|PATCH|[Projects_Update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_Update)|[UpdateProject](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/UpdateProject)|

-|`/projects/{id}/datasets`|GET|[Projects_ListDatasets](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_ListDatasets)|[GetDatasetsForProject](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetDatasetsForProject)|

-|`/projects/{id}/endpoints`|GET|[Projects_ListEndpoints](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_ListEndpoints)|[GetEndpointsForProject](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetEndpointsForProject)|

-|`/projects/{id}/evaluations`|GET|[Projects_ListEvaluations](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_ListEvaluations)|[GetEvaluationsForProject](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetEvaluationsForProject)|

-|`/projects/{id}/models`|GET|[Projects_ListModels](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_ListModels)|[GetModelsForProject](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetModelsForProject)|

-|`/projects/{id}/transcriptions`|GET|[Projects_ListTranscriptions](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_ListTranscriptions)|[GetTranscriptionsForProject](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetTranscriptionsForProject)|

-|`/projects/locales`|GET|[Projects_ListSupportedLocales](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_ListSupportedLocales)|[GetSupportedProjectLocales](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetSupportedProjectLocales)|

-|`/transcriptions`|GET|[Transcriptions_List](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_List)|[GetTranscriptions](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetTranscriptions)|

-|`/transcriptions`|POST|[Transcriptions_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Create)|[CreateTranscription](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/CreateTranscription)|

-|`/transcriptions/{id}`|DELETE|[Transcriptions_Delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Delete)|[DeleteTranscription](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteTranscription)|

-|`/transcriptions/{id}`|GET|[Transcriptions_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Get)|[GetTranscription](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetTranscription)|

-|`/transcriptions/{id}`|PATCH|[Transcriptions_Update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Update)|[UpdateTranscription](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/UpdateTranscription)|

-|`/transcriptions/{id}/files`|GET|[Transcriptions_ListFiles](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_ListFiles)|[GetTranscriptionFiles](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetTranscriptionFiles)|

-|`/transcriptions/{id}/files/{fileId}`|GET|[Transcriptions_GetFile](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_GetFile)|[GetTranscriptionFile](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetTranscriptionFile)|

-|`/transcriptions/locales`|GET|[Transcriptions_ListSupportedLocales](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_ListSupportedLocales)|[GetSupportedLocalesForTranscriptions](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetSupportedLocalesForTranscriptions)|

-|`/webhooks`|GET|[WebHooks_List](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/WebHooks_List)|[GetHooks](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetHooks)|

-|`/webhooks`|POST|[WebHooks_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/WebHooks_Create)|[CreateHook](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/CreateHook)|

-|`/webhooks/{id}:ping`²|POST|[WebHooks_Ping](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/WebHooks_Ping)|[PingHook](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/PingHook)|

-|`/webhooks/{id}:test`³|POST|[WebHooks_Test](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/WebHooks_Test)|[TestHook](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/TestHook)|

-|`/webhooks/{id}`|DELETE|[WebHooks_Delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/WebHooks_Delete)|[DeleteHook](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteHook)|

-|`/webhooks/{id}`|GET|[WebHooks_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/WebHooks_Get)|[GetHook](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetHook)|

-|`/webhooks/{id}`|PATCH|[WebHooks_Update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/WebHooks_Update)|[UpdateHook](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/UpdateHook)|

-¹ The `/models/{id}/copyto` operation (includes '/') in version 3.0 is replaced by the `/models/{id}:copyto` operation (includes ':') in version 3.1.

-² The `/webhooks/{id}/ping` operation (includes '/') in version 3.0 is replaced by the `/webhooks/{id}:ping` operation (includes ':') in version 3.1.

-³ The `/webhooks/{id}/test` operation (includes '/') in version 3.0 is replaced by the `/webhooks/{id}:test` operation (includes ':') in version 3.1.

-* [Speech to text REST API v3.1 reference](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1)

-* [Speech to text REST API v3.0 reference](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0)

-To support model adaptation with [custom display text formatting](how-to-custom-speech-test-and-train.md#custom-display-text-formatting-data-for-training) data, the [Datasets_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-2-preview2/operations/Datasets_Create) operation supports the **OutputFormatting** data kind. For more information, see [upload datasets](how-to-custom-speech-upload-data.md#upload-datasets).

-* [Speech to text REST API v3.2 (preview)](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-2-preview2)

-* [Speech to text REST API v3.1 reference](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1)

-* [Speech to text REST API v3.0 reference](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0)

-This article describes how to use [Power Automate](/power-automate/getting-started) and the [Azure AI services for Batch Speech to text connector](/connectors/cognitiveservicesspe/) to transcribe audio files from an Azure Storage container. The connector uses the [Batch Transcription REST API](batch-transcription.md), but you don't need to write any code to use it. If the connector doesn't meet your requirements, you can still use the [REST API](rest-speech-to-text.md#transcriptions) directly.

-2. Run the [Models_CopyTo](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_CopyTo) operation to replicate the custom model to all prepared regions (Secondary).

-> [See the Speech to text REST API v3.2 (preview)](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-2-preview2)

-> [See the Speech to text REST API v3.1 reference documentation](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/)

-> [See the Speech to text REST API v3.0 reference documentation](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/)

-## Datasets

-Datasets are applicable for [custom speech](custom-speech-overview.md). You can use datasets to train and test the performance of different models. For example, you can compare the performance of a model trained with a specific dataset to the performance of a model trained with a different dataset.

-See [Upload training and testing datasets](how-to-custom-speech-upload-data.md?pivots=rest-api) for examples of how to upload datasets. This table includes all the operations that you can perform on datasets.

-|Path|Method|Version 3.1|Version 3.0|

-|||||

-|`/datasets`|GET|[Datasets_List](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_List)|[GetDatasets](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetDatasets)|

-|`/datasets`|POST|[Datasets_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_Create)|[CreateDataset](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/CreateDataset)|

-|`/datasets/{id}`|DELETE|[Datasets_Delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_Delete)|[DeleteDataset](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteDataset)|

-|`/datasets/{id}`|GET|[Datasets_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_Get)|[GetDataset](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetDataset)|

-|`/datasets/{id}`|PATCH|[Datasets_Update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_Update)|[UpdateDataset](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/UpdateDataset)|

-|`/datasets/{id}/blocks:commit`|POST|[Datasets_CommitBlocks](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_CommitBlocks)|Not applicable|

-|`/datasets/{id}/blocks`|GET|[Datasets_GetBlocks](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_GetBlocks)|Not applicable|

-|`/datasets/{id}/blocks`|PUT|[Datasets_UploadBlock](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_UploadBlock)|Not applicable|

-|`/datasets/{id}/files`|GET|[Datasets_ListFiles](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_ListFiles)|[GetDatasetFiles](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetDatasetFiles)|

-|`/datasets/{id}/files/{fileId}`|GET|[Datasets_GetFile](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_GetFile)|[GetDatasetFile](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetDatasetFile)|

-|`/datasets/locales`|GET|[Datasets_ListSupportedLocales](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_ListSupportedLocales)|[GetSupportedLocalesForDatasets](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetSupportedLocalesForDatasets)|

-|`/datasets/upload`|POST|[Datasets_Upload](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Datasets_Upload)|[UploadDatasetFromForm](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/UploadDatasetFromForm)|

-## Endpoints

-Endpoints are applicable for [custom speech](custom-speech-overview.md). You must deploy a custom endpoint to use a custom speech model.

-See [Deploy a model](how-to-custom-speech-deploy-model.md?pivots=rest-api) for examples of how to manage deployment endpoints. This table includes all the operations that you can perform on endpoints.

-|Path|Method|Version 3.1|Version 3.0|

-|||||

-|`/endpoints`|GET|[Endpoints_List](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_List)|[GetEndpoints](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetEndpoints)|

-|`/endpoints`|POST|[Endpoints_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_Create)|[CreateEndpoint](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/CreateEndpoint)|

-|`/endpoints/{id}`|DELETE|[Endpoints_Delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_Delete)|[DeleteEndpoint](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteEndpoint)|

-|`/endpoints/{id}`|GET|[Endpoints_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_Get)|[GetEndpoint](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetEndpoint)|

-|`/endpoints/{id}`|PATCH|[Endpoints_Update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_Update)|[UpdateEndpoint](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/UpdateEndpoint)|

-|`/endpoints/{id}/files/logs`|DELETE|[Endpoints_DeleteLogs](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_DeleteLogs)|[DeleteEndpointLogs](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteEndpointLogs)|

-|`/endpoints/{id}/files/logs`|GET|[Endpoints_ListLogs](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_ListLogs)|[GetEndpointLogs](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetEndpointLogs)|

-|`/endpoints/{id}/files/logs/{logId}`|DELETE|[Endpoints_DeleteLog](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_DeleteLog)|[DeleteEndpointLog](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteEndpointLog)|

-|`/endpoints/{id}/files/logs/{logId}`|GET|[Endpoints_GetLog](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_GetLog)|[GetEndpointLog](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetEndpointLog)|

-|`/endpoints/base/{locale}/files/logs`|DELETE|[Endpoints_DeleteBaseModelLogs](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_DeleteBaseModelLogs)|[DeleteBaseModelLogs](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteBaseModelLogs)|

-|`/endpoints/base/{locale}/files/logs`|GET|[Endpoints_ListBaseModelLogs](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_ListBaseModelLogs)|[GetBaseModelLogs](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetBaseModelLogs)|

-|`/endpoints/base/{locale}/files/logs/{logId}`|DELETE|[Endpoints_DeleteBaseModelLog](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_DeleteBaseModelLog)|[DeleteBaseModelLog](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteBaseModelLog)|

-|`/endpoints/base/{locale}/files/logs/{logId}`|GET|[Endpoints_GetBaseModelLog](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_GetBaseModelLog)|[GetBaseModelLog](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetBaseModelLog)|

-|`/endpoints/locales`|GET|[Endpoints_ListSupportedLocales](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Endpoints_ListSupportedLocales)|[GetSupportedLocalesForEndpoints](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetSupportedLocalesForEndpoints)|

-## Evaluations

-Evaluations are applicable for [custom speech](custom-speech-overview.md). You can use evaluations to compare the performance of different models. For example, you can compare the performance of a model trained with a specific dataset to the performance of a model trained with a different dataset.

-See [Test recognition quality](how-to-custom-speech-inspect-data.md?pivots=rest-api) and [Test accuracy](how-to-custom-speech-evaluate-data.md?pivots=rest-api) for examples of how to test and evaluate custom speech models. This table includes all the operations that you can perform on evaluations.

-|Path|Method|Version 3.1|Version 3.0|

-|||||

-|`/evaluations`|GET|[Evaluations_List](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_List)|[GetEvaluations](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetEvaluations)|

-|`/evaluations`|POST|[Evaluations_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_Create)|[CreateEvaluation](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/CreateEvaluation)|

-|`/evaluations/{id}`|DELETE|[Evaluations_Delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_Delete)|[DeleteEvaluation](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteEvaluation)|

-|`/evaluations/{id}`|GET|[Evaluations_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_Get)|[GetEvaluation](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetEvaluation)|

-|`/evaluations/{id}`|PATCH|[Evaluations_Update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_Update)|[UpdateEvaluation](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/UpdateEvaluation)|

-|`/evaluations/{id}/files`|GET|[Evaluations_ListFiles](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_ListFiles)|[GetEvaluationFiles](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetEvaluationFiles)|

-|`/evaluations/{id}/files/{fileId}`|GET|[Evaluations_GetFile](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_GetFile)|[GetEvaluationFile](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetEvaluationFile)|

-|`/evaluations/locales`|GET|[Evaluations_ListSupportedLocales](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Evaluations_ListSupportedLocales)|[GetSupportedLocalesForEvaluations](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetSupportedLocalesForEvaluations)|

-## Health status

-Health status provides insights about the overall health of the service and subcomponents.

-|Path|Method|Version 3.1|Version 3.0|

-|||||

-|`/healthstatus`|GET|[HealthStatus_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/HealthStatus_Get)|[GetHealthStatus](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetHealthStatus)|

-## Models

-Models are applicable for [custom speech](custom-speech-overview.md) and [Batch Transcription](batch-transcription.md). You can use models to transcribe audio files. For example, you can use a model trained with a specific dataset to transcribe audio files.

-See [Train a model](how-to-custom-speech-train-model.md?pivots=rest-api) and [custom speech model lifecycle](how-to-custom-speech-model-and-endpoint-lifecycle.md?pivots=rest-api) for examples of how to train and manage custom speech models. This table includes all the operations that you can perform on models.

-|Path|Method|Version 3.1|Version 3.0|

-|||||

-|`/models`|GET|[Models_ListCustomModels](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_ListCustomModels)|[GetModels](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetModels)|

-|`/models`|POST|[Models_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_Create)|[CreateModel](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/CreateModel)|

-|`/models/{id}:copyto`¹|POST|[Models_CopyTo](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_CopyTo)|[CopyModelToSubscription](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/CopyModelToSubscription)|

-|`/models/{id}`|DELETE|[Models_Delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_Delete)|[DeleteModel](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteModel)|

-|`/models/{id}`|GET|[Models_GetCustomModel](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_GetCustomModel)|[GetModel](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetModel)|

-|`/models/{id}`|PATCH|[Models_Update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_Update)|[UpdateModel](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/UpdateModel)|

-|`/models/{id}/files`|GET|[Models_ListFiles](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_ListFiles)|Not applicable|

-|`/models/{id}/files/{fileId}`|GET|[Models_GetFile](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_GetFile)|Not applicable|

-|`/models/{id}/manifest`|GET|[Models_GetCustomModelManifest](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_GetCustomModelManifest)|[GetModelManifest](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetModelManifest)|

-|`/models/base`|GET|[Models_ListBaseModels](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_ListBaseModels)|[GetBaseModels](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetBaseModels)|

-|`/models/base/{id}`|GET|[Models_GetBaseModel](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_GetBaseModel)|[GetBaseModel](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetBaseModel)|

-|`/models/base/{id}/manifest`|GET|[Models_GetBaseModelManifest](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_GetBaseModelManifest)|[GetBaseModelManifest](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetBaseModelManifest)|

-|`/models/locales`|GET|[Models_ListSupportedLocales](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_ListSupportedLocales)|[GetSupportedLocalesForModels](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetSupportedLocalesForModels)|

-## Projects

-Projects are applicable for [custom speech](custom-speech-overview.md). Custom speech projects contain models, training and testing datasets, and deployment endpoints. Each project is specific to a [locale](language-support.md?tabs=stt). For example, you might create a project for English in the United States.

-See [Create a project](how-to-custom-speech-create-project.md?pivots=rest-api) for examples of how to create projects. This table includes all the operations that you can perform on projects.

-|Path|Method|Version 3.1|Version 3.0|

-|||||

-|`/projects`|GET|[Projects_List](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_List)|[GetProjects](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetProjects)|

-|`/projects`|POST|[Projects_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_Create)|[CreateProject](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/CreateProject)|

-|`/projects/{id}`|DELETE|[Projects_Delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_Delete)|[DeleteProject](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteProject)|

-|`/projects/{id}`|GET|[Projects_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_Get)|[GetProject](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetProject)|

-|`/projects/{id}`|PATCH|[Projects_Update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_Update)|[UpdateProject](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/UpdateProject)|

-|`/projects/{id}/datasets`|GET|[Projects_ListDatasets](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_ListDatasets)|[GetDatasetsForProject](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetDatasetsForProject)|

-|`/projects/{id}/endpoints`|GET|[Projects_ListEndpoints](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_ListEndpoints)|[GetEndpointsForProject](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetEndpointsForProject)|

-|`/projects/{id}/evaluations`|GET|[Projects_ListEvaluations](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_ListEvaluations)|[GetEvaluationsForProject](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetEvaluationsForProject)|

-|`/projects/{id}/models`|GET|[Projects_ListModels](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_ListModels)|[GetModelsForProject](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetModelsForProject)|

-|`/projects/{id}/transcriptions`|GET|[Projects_ListTranscriptions](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_ListTranscriptions)|[GetTranscriptionsForProject](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetTranscriptionsForProject)|

-|`/projects/locales`|GET|[Projects_ListSupportedLocales](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Projects_ListSupportedLocales)|[GetSupportedProjectLocales](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetSupportedProjectLocales)|

-## Transcriptions

-Transcriptions are applicable for [Batch Transcription](batch-transcription.md). Batch transcription is used to transcribe a large amount of audio in storage. You should send multiple files per request or point to an Azure Blob Storage container with the audio files to transcribe.

-See [Create a transcription](batch-transcription-create.md?pivots=rest-api) for examples of how to create a transcription from multiple audio files. This table includes all the operations that you can perform on transcriptions.

-|Path|Method|Version 3.1|Version 3.0|

-|||||

-|`/transcriptions`|GET|[Transcriptions_List](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_List)|[GetTranscriptions](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetTranscriptions)|

-|`/transcriptions`|POST|[Transcriptions_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Create)|[CreateTranscription](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/CreateTranscription)|

-|`/transcriptions/{id}`|DELETE|[Transcriptions_Delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Delete)|[DeleteTranscription](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteTranscription)|

-|`/transcriptions/{id}`|GET|[Transcriptions_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Get)|[GetTranscription](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetTranscription)|

-|`/transcriptions/{id}`|PATCH|[Transcriptions_Update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Update)|[UpdateTranscription](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/UpdateTranscription)|

-|`/transcriptions/{id}/files`|GET|[Transcriptions_ListFiles](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_ListFiles)|[GetTranscriptionFiles](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetTranscriptionFiles)|

-|`/transcriptions/{id}/files/{fileId}`|GET|[Transcriptions_GetFile](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_GetFile)|[GetTranscriptionFile](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetTranscriptionFile)|

-|`/transcriptions/locales`|GET|[Transcriptions_ListSupportedLocales](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_ListSupportedLocales)|[GetSupportedLocalesForTranscriptions](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetSupportedLocalesForTranscriptions)|

-## Web hooks

-Web hooks are applicable for [custom speech](custom-speech-overview.md) and [Batch Transcription](batch-transcription.md). In particular, web hooks apply to [datasets](#datasets), [endpoints](#endpoints), [evaluations](#evaluations), [models](#models), and [transcriptions](#transcriptions). Web hooks can be used to receive notifications about creation, processing, completion, and deletion events.

-This table includes all the web hook operations that are available with the Speech to text REST API.

-|Path|Method|Version 3.1|Version 3.0|

-|||||

-|`/webhooks`|GET|[WebHooks_List](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/WebHooks_List)|[GetHooks](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetHooks)|

-|`/webhooks`|POST|[WebHooks_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/WebHooks_Create)|[CreateHook](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/CreateHook)|

-|`/webhooks/{id}:ping`¹|POST|[WebHooks_Ping](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/WebHooks_Ping)|[PingHook](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/PingHook)|

-|`/webhooks/{id}:test`²|POST|[WebHooks_Test](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/WebHooks_Test)|[TestHook](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/TestHook)|

-|`/webhooks/{id}`|DELETE|[WebHooks_Delete](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/WebHooks_Delete)|[DeleteHook](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/DeleteHook)|

-|`/webhooks/{id}`|GET|[WebHooks_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/WebHooks_Get)|[GetHook](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/GetHook)|

-|`/webhooks/{id}`|PATCH|[WebHooks_Update](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/WebHooks_Update)|[UpdateHook](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-0/operations/UpdateHook)|

-¹ The `/webhooks/{id}/ping` operation (includes '/') in version 3.0 is replaced by the `/webhooks/{id}:ping` operation (includes ':') in version 3.1.

-² The `/webhooks/{id}/test` operation (includes '/') in version 3.0 is replaced by the `/webhooks/{id}:test` operation (includes ':') in version 3.1.

-| Max text size when you're using the `text` parameter in the [Models_Create](https://westcentralus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Models_Create/) API request | 200 KB | 500 KB |

-The [Swagger specification](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1) has options that allow you to quickly test for various paths. However, sometimes it's desirable to generate code for all paths, creating a single library of calls that you can base future solutions on. Let's take a look at the process to generate a Python library.

-1. In a browser, go to the Swagger specification for your [region](regions.md#speech-service):

- `https://<your-region>.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1`

-1. On that page, select **API definition**, and select **Swagger**. Copy the URL of the page that appears.

-1. In a new browser, go to [https://editor.swagger.io](https://editor.swagger.io)

-1. Select **File**, select **Import URL**, paste the URL, and select **OK**.

- "MicrosoftAppId": "3be0abc2-ca07-475e-b6c3-90c4476c4370",

- "MicrosoftAppPassword": "-zRhJZ~1cnc7ZIlj4Qozs_eKN.8Cq~U38G"

-description: Understand the parameters, headers, and body messages for the container Translate method of Azure AI Translator to translate text.

-#

-# Container: Translate

-Translate text.

-## Request URL

-Send a `POST` request to:

-```HTTP

-http://localhost:{port}/translate?api-version=3.0

-```

-Example: http://<span></span>localhost:5000/translate?api-version=3.0

-## Request parameters

-Request parameters passed on the query string are:

-### Required parameters

-| Query parameter | Description |

-| | |

-| api-version | _Required parameter_. <br>Version of the API requested by the client. Value must be `3.0`. |

-| from | _Required parameter_. <br>Specifies the language of the input text. Find which languages are available to translate from by looking up [supported languages](../reference/v3-0-languages.md) using the `translation` scope.|

-| to | _Required parameter_. <br>Specifies the language of the output text. The target language must be one of the [supported languages](../reference/v3-0-languages.md) included in the `translation` scope. For example, use `to=de` to translate to German. <br>It's possible to translate to multiple languages simultaneously by repeating the parameter in the query string. For example, use `to=de&to=it` to translate to German and Italian. |

-### Optional parameters

-| Query parameter | Description |

-| | |

-| textType | _Optional parameter_. <br>Defines whether the text being translated is plain text or HTML text. Any HTML needs to be a well-formed, complete element. Possible values are: `plain` (default) or `html`. |

-| includeSentenceLength | _Optional parameter_. <br>Specifies whether to include sentence boundaries for the input text and the translated text. Possible values are: `true` or `false` (default). |

-Request headers include:

-| Headers | Description |

-| | |

-| Authentication header(s) | _Required request header_. <br>See [available options for authentication](../reference/v3-0-reference.md#authentication). |

-| Content-Type | _Required request header_. <br>Specifies the content type of the payload. <br>Accepted value is `application/json; charset=UTF-8`. |

-| Content-Length | _Required request header_. <br>The length of the request body. |

-| X-ClientTraceId | _Optional_. <br>A client-generated GUID to uniquely identify the request. You can omit this header if you include the trace ID in the query string using a query parameter named `ClientTraceId`. |

-## Request body

-The body of the request is a JSON array. Each array element is a JSON object with a string property named `Text`, which represents the string to translate.

-```json

-[

- {"Text":"I would really like to drive your car around the block a few times."}

-]

-```

-The following limitations apply:

-* The array can have at most 100 elements.

-* The entire text included in the request can't exceed 10,000 characters including spaces.

-## Response body

-A successful response is a JSON array with one result for each string in the input array. A result object includes the following properties:

-* `translations`: An array of translation results. The size of the array matches the number of target languages specified through the `to` query parameter. Each element in the array includes:

-* `to`: A string representing the language code of the target language.

-* `text`: A string giving the translated text.

-* `sentLen`: An object returning sentence boundaries in the input and output texts.

-* `srcSentLen`: An integer array representing the lengths of the sentences in the input text. The length of the array is the number of sentences, and the values are the length of each sentence.

-* `transSentLen`: An integer array representing the lengths of the sentences in the translated text. The length of the array is the number of sentences, and the values are the length of each sentence.

- Sentence boundaries are only included when the request parameter `includeSentenceLength` is `true`.

- * `sourceText`: An object with a single string property named `text`, which gives the input text in the default script of the source language. `sourceText` property is present only when the input is expressed in a script that's not the usual script for the language. For example, if the input were Arabic written in Latin script, then `sourceText.text` would be the same Arabic text converted into Arab script.

-Examples of JSON responses are provided in the [examples](#examples) section.

-## Response headers

-| Headers | Description |

-| | |

-| X-RequestId | Value generated by the service to identify the request. It's used for troubleshooting purposes. |

-| X-MT-System | Specifies the system type that was used for translation for each 'to' language requested for translation. The value is a comma-separated list of strings. Each string indicates a type: </br></br>&FilledVerySmallSquare; Custom - Request includes a custom system and at least one custom system was used during translation.</br>&FilledVerySmallSquare; Team - All other requests |

-## Response status codes

-If an error occurs, the request will also return a JSON error response. The error code is a 6-digit number combining the 3-digit HTTP status code followed by a 3-digit number to further categorize the error. Common error codes can be found on the [v3 Translator reference page](../reference/v3-0-reference.md#errors).

-## Examples

-### Translate a single input

-This example shows how to translate a single sentence from English to Simplified Chinese.

-```curl

-curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

-```

-The response body is:

-```

-[

- {

- "translations":[

- {"text":"你好, 你叫什么名字？","to":"zh-Hans"}

- ]

- }

-]

-```

-The `translations` array includes one element, which provides the translation of the single piece of text in the input.

-### Translate multiple pieces of text

-Translating multiple strings at once is simply a matter of specifying an array of strings in the request body.

-```curl

-curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}, {'Text':'I am fine, thank you.'}]"

-```

-The response contains the translation of all pieces of text in the exact same order as in the request.

-The response body is:

-```

-[

- {

- "translations":[

- {"text":"你好, 你叫什么名字？","to":"zh-Hans"}

- ]

- },

- {

- "translations":[

- {"text":"我很好，谢谢你。","to":"zh-Hans"}

- ]

- }

-]

-```

-### Translate to multiple languages

-This example shows how to translate the same input to several languages in one request.

-```curl

-curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=zh-Hans&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

-```

-The response body is:

-```

-[

- {

- "translations":[

- {"text":"你好, 你叫什么名字？","to":"zh-Hans"},

- {"text":"Hallo, was ist dein Name?","to":"de"}

- ]

- }

-]

-```

-### Translate content with markup and decide what's translated

-It's common to translate content that includes markup such as content from an HTML page or content from an XML document. Include query parameter `textType=html` when translating content with tags. In addition, it's sometimes useful to exclude specific content from translation. You can use the attribute `class=notranslate` to specify content that should remain in its original language. In the following example, the content inside the first `div` element won't be translated, while the content in the second `div` element will be translated.

-```

-<div class="notranslate">This will not be translated.</div>

-<div>This will be translated. </div>

-```

-Here's a sample request to illustrate.

-```curl

-curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=zh-Hans&textType=html" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'<div class=\"notranslate\">This will not be translated.</div><div>This will be translated.</div>'}]"

-```

-The response is:

-```

-[

- {

- "translations":[

- {"text":"<div class=\"notranslate\">This will not be translated.</div><div>这将被翻译。</div>","to":"zh-Hans"}

- ]

- }

-]

-```

-### Translate with dynamic dictionary

-If you already know the translation you want to apply to a word or a phrase, you can supply it as markup within the request. The dynamic dictionary is only safe for proper nouns such as personal names and product names.

-The markup to supply uses the following syntax.

-```

-<mstrans:dictionary translation="translation of phrase">phrase</mstrans:dictionary>

-```

-For example, consider the English sentence "The word wordomatic is a dictionary entry." To preserve the word _wordomatic_ in the translation, send the request:

-```

-curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The word <mstrans:dictionary translation=\"wordomatic\">word or phrase</mstrans:dictionary> is a dictionary entry.'}]"

-```

-The result is:

-```

-[

- {

- "translations":[

- {"text":"Das Wort \"wordomatic\" ist ein W├╢rterbucheintrag.","to":"de"}

- ]

- }

-]

-```

-This feature works the same way with `textType=text` or with `textType=html`. The feature should be used sparingly. The appropriate and far better way of customizing translation is by using Custom Translator. Custom Translator makes full use of context and statistical probabilities. If you've created training data that shows your work or phrase in context, you'll get much better results. [Learn more about Custom Translator](../custom-translator/concepts/customization.md).

-## Request limits

-Each translate request is limited to 10,000 characters, across all the target languages you're translating to. For example, sending a translate request of 3,000 characters to translate to three different languages results in a request size of 3000x3 = 9,000 characters, which satisfy the request limit. You're charged per character, not by the number of requests. It's recommended to send shorter requests.

-The following table lists array element and character limits for the Translator **translation** operation.

-| Operation | Maximum size of array element | Maximum number of array elements | Maximum request size (characters) |

-|:-|:-|:-|:-|

-| translate | 10,000 | 100 | 10,000 |

-description: Learn how to run Azure AI Translator containers in disconnected environments.

-#

-<!-- markdownlint-disable MD036 -->

-<!-- markdownlint-disable MD001 -->

-# Use Translator containers in disconnected environments

- Azure AI Translator containers allow you to use Translator Service APIs with the benefits of containerization. Disconnected containers are offered through commitment tier pricing offered at a discounted rate compared to pay-as-you-go pricing. With commitment tier pricing, you can commit to using Translator Service features for a fixed fee, at a predictable total cost, based on the needs of your workload.

-## Get started

-Before attempting to run a Docker container in an offline environment, make sure you're familiar with the following requirements to successfully download and use the container:

-* Host computer requirements and recommendations.

-* The Docker `pull` command to download the container.

-* How to validate that a container is running.

-* How to send queries to the container's endpoint, once it's running.

-## Request access to use containers in disconnected environments

-Complete and submit the [request form](https://aka.ms/csdisconnectedcontainers) to request access to the containers disconnected from the Internet.

-Access is limited to customers that meet the following requirements:

-* Your organization should be identified as strategic customer or partner with Microsoft.

-* Disconnected containers are expected to run fully offline, hence your use cases must meet at least one of these or similar requirements:

- * Environment or device(s) with zero connectivity to internet.

- * Remote location that occasionally has internet access.

- * Organization under strict regulation of not sending any kind of data back to cloud.

-* Application completed as instructed. Make certain to pay close attention to guidance provided throughout the application to ensure you provide all the necessary information required for approval.

-## Create a new resource and purchase a commitment plan

-1. Create a [Translator resource](https://portal.azure.com/#create/Microsoft.CognitiveServicesTextTranslation) in the Azure portal.

-1. Enter the applicable information to create your resource. Be sure to select **Commitment tier disconnected containers** as your pricing tier.

- > [!NOTE]

- >

- > * You will only see the option to purchase a commitment tier if you have been approved by Microsoft.

- :::image type="content" source="../media/create-resource-offline-container.png" alt-text="A screenshot showing resource creation on the Azure portal.":::

-1. Select **Review + Create** at the bottom of the page. Review the information, and select **Create**.

-## Gather required parameters

-There are three required parameters for all Azure AI services' containers:

-* The end-user license agreement (EULA) must be present with a value of *accept*.

-* The endpoint URL for your resource from the Azure portal.

-* The API key for your resource from the Azure portal.

-Both the endpoint URL and API key are needed when you first run the container to configure it for disconnected usage. You can find the key and endpoint on the **Key and endpoint** page for your resource in the Azure portal:

- :::image type="content" source="../media/quickstarts/keys-and-endpoint-portal.png" alt-text="Screenshot of Azure portal keys and endpoint page.":::

-> [!IMPORTANT]

-> You will only use your key and endpoint to configure the container to run in a disconnected environment. After you configure the container, you won't need the key and endpoint values to send API requests. Store them securely, for example, using Azure Key Vault. Only one key is necessary for this process.

-## Download a Docker container with `docker pull`

-Download the Docker container that has been approved to run in a disconnected environment. For example:

-|Docker pull command | Value |Format|

-|-|-||

-|&bullet; **`docker pull [image]`**</br>&bullet; **`docker pull [image]:latest`**|The latest container image.|&bullet; mcr.microsoft.com/azure-cognitive-services/translator/text-translation</br> </br>&bullet; mcr.microsoft.com/azure-cognitive-services/translator/text-translation: latest |

-|||

-|&bullet; **`docker pull [image]:[version]`** | A specific container image |mcr.microsoft.com/azure-cognitive-services/translator/text-translation:1.0.019410001-amd64 |

- **Example Docker pull command**

-```docker

-docker pull mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest

-```

-## Configure the container to run in a disconnected environment

-Now that you've downloaded your container, you need to execute the `docker run` command with the following parameters:

-* **`DownloadLicense=True`**. This parameter downloads a license file that enables your Docker container to run when it isn't connected to the internet. It also contains an expiration date, after which the license file is invalid to run the container. You can only use the license file in corresponding approved container.

-* **`Languages={language list}`**. You must include this parameter to download model files for the [languages](../language-support.md) you want to translate.

-> [!IMPORTANT]

-> The `docker run` command will generate a template that you can use to run the container. The template contains parameters you'll need for the downloaded models and configuration file. Make sure you save this template.

-The following example shows the formatting for the `docker run` command with placeholder values. Replace these placeholder values with your own values.

-| Placeholder | Value | Format|

-|-|-||

-| `[image]` | The container image you want to use. | `mcr.microsoft.com/azure-cognitive-services/translator/text-translation` |

-| `{LICENSE_MOUNT}` | The path where the license is downloaded, and mounted. | `/host/license:/path/to/license/directory` |

- | `{MODEL_MOUNT_PATH}`| The path where the machine translation models are downloaded, and mounted. Your directory structure must be formatted as **/usr/local/models** | `/host/translator/models:/usr/local/models`|

-| `{ENDPOINT_URI}` | The endpoint for authenticating your service request. You can find it on your resource's **Key and endpoint** page, in the Azure portal. | `https://<your-custom-subdomain>.cognitiveservices.azure.com` |

-| `{API_KEY}` | The key for your Text Translation resource. You can find it on your resource's **Key and endpoint** page, in the Azure portal. |`{string}`|

-| `{LANGUAGES_LIST}` | List of language codes separated by commas. It's mandatory to have English (en) language as part of the list.| `en`, `fr`, `it`, `zu`, `uk` |

-| `{CONTAINER_LICENSE_DIRECTORY}` | Location of the license folder on the container's local filesystem. | `/path/to/license/directory` |

- **Example `docker run` command**

-```docker

-docker run --rm -it -p 5000:5000 \

-[image]

-```

-### Translator translation models and container configuration

-After you've [configured the container](#configure-the-container-to-run-in-a-disconnected-environment), the values for the downloaded translation models and container configuration will be generated and displayed in the container output:

-```bash

- -e MODELS= usr/local/models/model1/, usr/local/models/model2/

- -e TRANSLATORSYSTEMCONFIG=/usr/local/models/Config/5a72fa7c-394b-45db-8c06-ecdfc98c0832

-```

-## Run the container in a disconnected environment

-Once the license file has been downloaded, you can run the container in a disconnected environment with your license, appropriate memory, and suitable CPU allocations. The following example shows the formatting of the `docker run` command with placeholder values. Replace these placeholders values with your own values.

-Whenever the container is run, the license file must be mounted to the container and the location of the license folder on the container's local filesystem must be specified with `Mounts:License=`. In addition, an output mount must be specified so that billing usage records can be written.

-Placeholder | Value | Format|

-|-|-||

-| `[image]`| The container image you want to use. | `mcr.microsoft.com/azure-cognitive-services/translator/text-translation` |

- `{MEMORY_SIZE}` | The appropriate size of memory to allocate for your container. | `16g` |

-| `{NUMBER_CPUS}` | The appropriate number of CPUs to allocate for your container. | `4` |

-| `{LICENSE_MOUNT}` | The path where the license is located and mounted. | `/host/translator/license:/path/to/license/directory` |

-|`{MODEL_MOUNT_PATH}`| The path where the machine translation models are downloaded, and mounted. Your directory structure must be formatted as **/usr/local/models** | `/host/translator/models:/usr/local/models`|

-|`{MODELS_DIRECTORY_LIST}`|List of comma separated directories each having a machine translation model. | `/usr/local/models/enu_esn_generalnn_2022240501,/usr/local/models/esn_enu_generalnn_2022240501` |

-| `{OUTPUT_PATH}` | The output path for logging [usage records](#usage-records). | `/host/output:/path/to/output/directory` |

-| `{CONTAINER_LICENSE_DIRECTORY}` | Location of the license folder on the container's local filesystem. | `/path/to/license/directory` |

-| `{CONTAINER_OUTPUT_DIRECTORY}` | Location of the output folder on the container's local filesystem. | `/path/to/output/directory` |

-|`{TRANSLATOR_CONFIG_JSON}`| Translator system configuration file used by container internally.| `/usr/local/models/Config/5a72fa7c-394b-45db-8c06-ecdfc98c0832` |

- **Example `docker run` command**

-```docker

-docker run --rm -it -p 5000:5000 --memory {MEMORY_SIZE} --cpus {NUMBER_CPUS} \

-[image]

-```

-## Other parameters and commands

-Here are a few more parameters and commands you may need to run the container:

-#### Usage records

-When operating Docker containers in a disconnected environment, the container will write usage records to a volume where they're collected over time. You can also call a REST API endpoint to generate a report about service usage.

-#### Arguments for storing logs

-When run in a disconnected environment, an output mount must be available to the container to store usage logs. For example, you would include `-v /host/output:{OUTPUT_PATH}` and `Mounts:Output={OUTPUT_PATH}` in the following example, replacing `{OUTPUT_PATH}` with the path where the logs are stored:

- **Example `docker run` command**

-```docker

-docker run -v /host/output:{OUTPUT_PATH} ... <image> ... Mounts:Output={OUTPUT_PATH}

-```

-#### Environment variable names in Kubernetes deployments

-Some Azure AI Containers, for example Translator, require users to pass environmental variable names that include colons (`:`) when running the container. This will work fine when using Docker, but Kubernetes does not accept colons in environmental variable names.

-To resolve this, you can replace colons with two underscore characters (`__`) when deploying to Kubernetes. See the following example of an acceptable format for environmental variable names:

-```Kubernetes

- env:

- - name: Mounts__License

- value: "/license"

- - name: Mounts__Output

- value: "/output"

-```

-This example replaces the default format for the `Mounts:License` and `Mounts:Output` environment variable names in the docker run command.

-#### Get records using the container endpoints

-The container provides two endpoints for returning records regarding its usage.

-#### Get all records

-The following endpoint provides a report summarizing all of the usage collected in the mounted billing record directory.

-```HTTP

-https://<service>/records/usage-logs/

-```

- **Example HTTPS endpoint**

- `http://localhost:5000/records/usage-logs`

-The usage-logs endpoint returns a JSON response similar to the following example:

-```json

-{

-"apiType": "string",

-"serviceName": "string",

-"meters": [

-{

- "name": "string",

- "quantity": 256345435

- }

- ]

-}

-```

-#### Get records for a specific month

-The following endpoint provides a report summarizing usage over a specific month and year:

-```HTTP

-https://<service>/records/usage-logs/{MONTH}/{YEAR}

-```

-This usage-logs endpoint returns a JSON response similar to the following example:

-```json

-{

- "apiType": "string",

- "serviceName": "string",

- "meters": [

- {

- "name": "string",

- "quantity": 56097

- }

- ]

-}

-```

-### Purchase a different commitment plan for disconnected containers

-Commitment plans for disconnected containers have a calendar year commitment period. When you purchase a plan, you're charged the full price immediately. During the commitment period, you can't change your commitment plan, however you can purchase more unit(s) at a pro-rated price for the remaining days in the year. You have until midnight (UTC) on the last day of your commitment, to end a commitment plan.

-You can choose a different commitment plan in the **Commitment tier pricing** settings of your resource under the **Resource Management** section.

-### End a commitment plan

- If you decide that you don't want to continue purchasing a commitment plan, you can set your resource's autorenewal to **Do not auto-renew**. Your commitment plan expires on the displayed commitment end date. After this date, you won't be charged for the commitment plan. You're still able to continue using the Azure resource to make API calls, charged at pay-as-you-go pricing. You have until midnight (UTC) on the last day of the year to end a commitment plan for disconnected containers. If you do so, you avoid charges for the following year.

-## Troubleshooting

-Run the container with an output mount and logging enabled. These settings enable the container to generate log files that are helpful for troubleshooting issues that occur while starting or running the container.

-> [!TIP]

-> For more troubleshooting information and guidance, see [Disconnected containers Frequently asked questions (FAQ)](../../containers/disconnected-container-faq.yml).

-That's it! You've learned how to create and run disconnected containers for Azure AI Translator Service.

-## Next steps

-> [!div class="nextstepaction"]

-> [Request parameters for Translator text containers](translator-container-supported-parameters.md)

-description: Use the Docker container for Translator API to translate text.

-#

-recommendations: false

-keywords: on-premises, Docker, container, identify

-# Install and run Translator containers

-Containers enable you to run several features of the Translator service in your own environment. Containers are great for specific security and data governance requirements. In this article you learn how to download, install, and run a Translator container.

-Translator container enables you to build a translator application architecture that is optimized for both robust cloud capabilities and edge locality.

-See the list of [languages supported](../language-support.md) when using Translator containers.

-> [!IMPORTANT]

->

-> * To use the Translator container, you must submit an online request and have it approved. For more information, _see_ [Request approval to run container](#request-approval-to-run-container).

-> * Translator container supports limited features compared to the cloud offerings. For more information, _see_ [**Container translate methods**](translator-container-supported-parameters.md).

-<!-- markdownlint-disable MD033 -->

-## Prerequisites

-To get started, you need an active [**Azure account**](https://azure.microsoft.com/free/cognitive-services/). If you don't have one, you can [**create a free account**](https://azure.microsoft.com/free/).

-You also need:

-| Required | Purpose |

-|--|--|

-| Familiarity with Docker | <ul><li>You should have a basic understanding of Docker concepts like registries, repositories, containers, and container images, as well as knowledge of basic `docker` [terminology and commands](/dotnet/architecture/microservices/container-docker-introduction/docker-terminology).</li></ul> |

-| Docker Engine | <ul><li>You need the Docker Engine installed on a [host computer](#host-computer). Docker provides packages that configure the Docker environment on [macOS](https://docs.docker.com/docker-for-mac/), [Windows](https://docs.docker.com/docker-for-windows/), and [Linux](https://docs.docker.com/engine/installation/#supported-platforms). For a primer on Docker and container basics, see the [Docker overview](https://docs.docker.com/engine/docker-overview/).</li><li> Docker must be configured to allow the containers to connect with and send billing data to Azure. </li><li> On **Windows**, Docker must also be configured to support **Linux** containers.</li></ul> |

-| Translator resource | <ul><li>An Azure [Translator](https://portal.azure.com/#create/Microsoft.CognitiveServicesTextTranslation) regional resource (not `global`) with an associated API key and endpoint URI. Both values are required to start the container and can be found on the resource overview page.</li></ul>|

-|Optional|Purpose|

-||-|

-|Azure CLI (command-line interface) |<ul><li> The [Azure CLI](/cli/azure/install-azure-cli) enables you to use a set of online commands to create and manage Azure resources. It's available to install in Windows, macOS, and Linux environments and can be run in a Docker container and Azure Cloud Shell.</li></ul> |

-## Required elements

-All Azure AI containers require three primary elements:

-* **EULA accept setting**. An end-user license agreement (EULA) set with a value of `Eula=accept`.

-* **API key** and **Endpoint URL**. The API key is used to start the container. You can retrieve the API key and Endpoint URL values by navigating to the Translator resource **Keys and Endpoint** page and selecting the `Copy to clipboard` <span class="docon docon-edit-copy x-hidden-focus"></span> icon.

-> [!IMPORTANT]

->

-> * Keys are used to access your Azure AI resource. Do not share your keys. Store them securely, for example, using Azure Key Vault. We also recommend regenerating these keys regularly. Only one key is necessary to make an API call. When regenerating the first key, you can use the second key for continued access to the service.

-## Host computer

-## Container requirements and recommendations

-The following table describes the minimum and recommended CPU cores and memory to allocate for the Translator container.

-| Container | Minimum |Recommended | Language Pair |

-|--|||-|

-| Translator |`2` cores, `4 GB` memory |`4` cores, `8 GB` memory | 2 |

-* Each core must be at least 2.6 gigahertz (GHz) or faster.

-* The core and memory correspond to the `--cpus` and `--memory` settings, which are used as part of the `docker run` command.

-> [!NOTE]

->

-> * CPU core and memory correspond to the `--cpus` and `--memory` settings, which are used as part of the docker run command.

->

-> * The minimum and recommended specifications are based on Docker limits, not host machine resources.

-## Request approval to run container

-Complete and submit the [**Azure AI services

-Application for Gated Services**](https://aka.ms/csgate-translator) to request access to the container.

-## Translator container image

-The Translator container image can be found on the `mcr.microsoft.com` container registry syndicate. It resides within the `azure-cognitive-services/translator` repository and is named `text-translation`. The fully qualified container image name is `mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest`.

-To use the latest version of the container, you can use the `latest` tag. You can find a full list of [tags on the MCR](https://mcr.microsoft.com/product/azure-cognitive-services/translator/text-translation/tags).

-## Get container images with **docker commands**

-> [!IMPORTANT]

->

-> * The docker commands in the following sections use the back slash, `\`, as a line continuation character. Replace or remove this based on your host operating system's requirements.

-> * The `EULA`, `Billing`, and `ApiKey` options must be specified to run the container; otherwise, the container won't start.

-Use the [docker run](https://docs.docker.com/engine/reference/commandline/run/) command to download a container image from Microsoft Container registry and run it.

-```Docker

-docker run --rm -it -p 5000:5000 --memory 12g --cpus 4 \

-mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest

-```

-The above command:

-* Downloads and runs a Translator container from the container image.

-* Allocates 12 gigabytes (GB) of memory and four CPU core.

-* Exposes TCP port 5000 and allocates a pseudo-TTY for the container

-* Accepts the end-user agreement (EULA)

-* Configures billing endpoint

-* Downloads translation models for languages English, French, Spanish, Arabic, and Russian

-* Automatically removes the container after it exits. The container image is still available on the host computer.

-### Run multiple containers on the same host

-If you intend to run multiple containers with exposed ports, make sure to run each container with a different exposed port. For example, run the first container on port 5000 and the second container on port 5001.

-You can have this container and a different Azure AI container running on the HOST together. You also can have multiple containers of the same Azure AI container running.

-## Query the container's Translator endpoint

- The container provides a REST-based Translator endpoint API. Here's an example request:

-```curl

-curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-HANS"

- -H "Content-Type: application/json" -d "[{'Text':'Hello, what is your name?'}]"

-```

-> [!NOTE]

-> If you attempt the cURL POST request before the container is ready, you'll end up getting a *Service is temporarily unavailable* response. Wait until the container is ready, then try again.

-## Stop the container

-## Troubleshoot

-### Validate that a container is running

-There are several ways to validate that the container is running:

-* The container provides a homepage at `/` as a visual validation that the container is running.

-* You can open your favorite web browser and navigate to the external IP address and exposed port of the container in question. Use the following request URLs to validate the container is running. The example request URLs listed point to `http://localhost:5000`, but your specific container may vary. Keep in mind that you're navigating to your container's **External IP address** and exposed port.

-| Request URL | Purpose |

-|--|--|

-| `http://localhost:5000/` | The container provides a home page. |

-| `http://localhost:5000/ready` | Requested with GET. Provides a verification that the container is ready to accept a query against the model. This request can be used for Kubernetes [liveness and readiness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/). |

-| `http://localhost:5000/status` | Requested with GET. Verifies if the api-key used to start the container is valid without causing an endpoint query. This request can be used for Kubernetes [liveness and readiness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/). |

-| `http://localhost:5000/swagger` | The container provides a full set of documentation for the endpoints and a **Try it out** feature. With this feature, you can enter your settings into a web-based HTML form and make the query without having to write any code. After the query returns, an example CURL command is provided to demonstrate the HTTP headers and body format that's required. |

-## Text translation code samples

-### Translate text with swagger

-#### English &leftrightarrow; German

-Navigate to the swagger page: `http://localhost:5000/swagger/https://docsupdatetracker.net/index.html`

-1. Select **POST /translate**

-1. Select **Try it out**

-1. Enter the **From** parameter as `en`

-1. Enter the **To** parameter as `de`

-1. Enter the **api-version** parameter as `3.0`

-1. Under **texts**, replace `string` with the following JSON

-```json

- [

- {

- "text": "hello, how are you"

- }

- ]

-```

-Select **Execute**, the resulting translations are output in the **Response Body**. You should expect something similar to the following response:

-```json

-"translations": [

- {

- "text": "hallo, wie geht es dir",

- "to": "de"

- }

- ]

-```

-### Translate text with Python

-```python

-import requests, json

-url = 'http://localhost:5000/translate?api-version=3.0&from=en&to=fr'

-headers = { 'Content-Type': 'application/json' }

-body = [{ 'text': 'Hello, how are you' }]

-request = requests.post(url, headers=headers, json=body)

-response = request.json()

-print(json.dumps(

- response,

- sort_keys=True,

- indent=4,

- ensure_ascii=False,

- separators=(',', ': ')))

-```

-### Translate text with C#/.NET console app

-Launch Visual Studio, and create a new console application. Edit the `*.csproj` file to add the `<LangVersion>7.1</LangVersion>` nodeΓÇöspecifies C# 7.1. Add the [Newtoonsoft.Json](https://www.nuget.org/packages/Newtonsoft.Json/) NuGet package, version 11.0.2.

-In the `Program.cs` replace all the existing code with the following script:

-```csharp

-using Newtonsoft.Json;

-using System;

-using System.Net.Http;

-using System.Text;

-using System.Threading.Tasks;

-namespace TranslateContainer

-{

- class Program

- {

- const string ApiHostEndpoint = "http://localhost:5000";

- const string TranslateApi = "/translate?api-version=3.0&from=en&to=de";

- static async Task Main(string[] args)

- {

- var textToTranslate = "Sunny day in Seattle";

- var result = await TranslateTextAsync(textToTranslate);

- Console.WriteLine(result);

- Console.ReadLine();

- }

- static async Task<string> TranslateTextAsync(string textToTranslate)

- {

- var body = new object[] { new { Text = textToTranslate } };

- var requestBody = JsonConvert.SerializeObject(body);

- var client = new HttpClient();

- using (var request =

- new HttpRequestMessage

- {

- Method = HttpMethod.Post,

- RequestUri = new Uri($"{ApiHostEndpoint}{TranslateApi}"),

- Content = new StringContent(requestBody, Encoding.UTF8, "application/json")

- })

- {

- // Send the request and await a response.

- var response = await client.SendAsync(request);

- return await response.Content.ReadAsStringAsync();

- }

- }

- }

-}

-```

-## Summary

-In this article, you learned concepts and workflows for downloading, installing, and running Translator container. Now you know:

-* Translator provides Linux containers for Docker.

-* Container images are downloaded from the container registry and run in Docker.

-* You can use the REST API to call 'translate' operation in Translator container by specifying the container's host URI.

-## Next steps

-> [!div class="nextstepaction"]

-> [Learn more about Azure AI containers](../../cognitive-services-container-support.md?context=%2fazure%2fcognitive-services%2ftranslator%2fcontext%2fcontext)

-description: Get answers to frequently asked questions about Document Translation.

-When text is translated from the source to target language, the overall length of translated text can differ from source. The result could be reflow of text across pages. The same fonts aren't always available in both source and target language. In general, the same font style is applied in target language to retain formatting closer to source.

-No. The text in an image within a document isn't translated.

-No. The service can't translate encrypted or password-protected documents. If your scanned or text-embedded PDFs are password-locked, you must remove the lock before submission.

-No. Don't include SAS token-appended URLS. Managed identities eliminate the need for you to include shared access signature tokens (SAS) with your HTTP requests.

-description: This article provides instructions on how to install and get started with the Azure AI CLI.

- - ignite-2023

-# Get started with the Azure AI CLI

-The Azure AI command-line interface (CLI) is a cross-platform command-line tool to connect to Azure AI services and execute control-plane and data-plane operations without having to write any code. The Azure AI CLI allows the execution of commands through a terminal using interactive command-line prompts or via script.

-You can easily use the Azure AI CLI to experiment with key Azure AI features and see how they work with your use cases. Within minutes, you can set up all the required Azure resources needed, and build a customized copilot using Azure OpenAI chat completions APIs and your own data. You can try it out interactively, or script larger processes to automate your own workflows and evaluations as part of your CI/CD system.

-## Prerequisites

-To use the Azure AI CLI, you need to install the prerequisites:

- * The Azure AI SDK, following the instructions [here](./sdk-install.md)

- * The Azure CLI (not the Azure `AI` CLI), following the instructions [here](/cli/azure/install-azure-cli)

- * The .NET SDK, following the instructions [here](/dotnet/core/install/) for your operating system and distro

-> [!NOTE]

-> If you launched VS Code from the Azure AI Studio, you don't need to install the prerequisites. See options without installing later in this article.

-## Install the CLI

-The following set of commands are provided for a few popular operating systems.

-# [Windows](#tab/windows)

-To install the .NET SDK, Azure CLI, and Azure AI CLI, run the following command.

-```bash

-dotnet tool install --prerelease --global Azure.AI.CLI

-```

-To update the Azure AI CLI, run the following command:

-```bash

-dotnet tool update --prerelease --global Azure.AI.CLI

-```

-# [Linux](#tab/linux)

-To install the .NET SDK, Azure CLI, and Azure AI CLI on Debian and Ubuntu, run the following command:

-```

-curl -sL https://aka.ms/InstallAzureAICLIDeb | bash

-```

-Alternatively, you can run the following command:

-```bash

-dotnet tool install --prerelease --global Azure.AI.CLI

-```

-To update the Azure AI CLI, run the following command:

-```bash

-dotnet tool update --prerelease --global Azure.AI.CLI

-```

-# [macOS](#tab/macos)

-To install the .NET SDK, Azure CLI, and Azure AI CLI on macOS 10.14 or later, run the following command:

-```bash

-dotnet tool install --prerelease --global Azure.AI.CLI

-```

-To update the Azure AI CLI, run the following command:

-```bash

-dotnet tool update --prerelease --global Azure.AI.CLI

-```

-## Run the Azure AI CLI without installing it

-You can install the Azure AI CLI locally as described previously, or run it using a preconfigured Docker container in VS Code.

-### Option 1: Using VS Code (web) in Azure AI Studio

-VS Code (web) in Azure AI Studio creates and runs the development container on a compute instance. To get started with this approach, follow the instructions in [Work with Azure AI projects in VS Code](develop-in-vscode.md).

-Our prebuilt development environments are based on a docker container that has the Azure AI SDK generative packages, the Azure AI CLI, the Prompt flow SDK, and other tools. It's configured to run VS Code remotely inside of the container. The docker container is similar to [this Dockerfile](https://github.com/Azure/aistudio-copilot-sample/blob/main/.devcontainer/Dockerfile), and is based on [Microsoft's Python 3.10 Development Container Image](https://mcr.microsoft.com/en-us/product/devcontainers/python/about).

-### OPTION 2: Visual Studio Code Dev Container

-You can run the Azure AI CLI in a Docker container using VS Code Dev Containers:

-1. Follow the [installation instructions](https://code.visualstudio.com/docs/devcontainers/containers#_installation) for VS Code Dev Containers.

-1. Clone the [aistudio-copilot-sample](https://github.com/Azure/aistudio-copilot-sample) repository and open it with VS Code:

- ```

- git clone https://github.com/azure/aistudio-copilot-sample

- code aistudio-copilot-sample

- ```

-1. Select the **Reopen in Dev Containers** button. If it doesn't appear, open the command palette (`Ctrl+Shift+P` on Windows and Linux, `Cmd+Shift+P` on Mac) and run the `Dev Containers: Reopen in Container` command.

-## Try the Azure AI CLI

-The AI CLI offers many capabilities, including an interactive chat experience, tools to work with prompt flows and search and speech services, and tools to manage AI services.

-If you plan to use the AI CLI as part of your development, we recommend you start by running `ai init`, which guides you through setting up your Azure resources and connections in your development environment.

-Try `ai help` to learn more about these capabilities.

-### ai init

-The `ai init` command allows interactive and non-interactive selection or creation of Azure AI hub resources. When an Azure AI hub resource is selected or created, the associated resource keys and region are retrieved and automatically stored in the local AI configuration datastore.

-You can initialize the Azure AI CLI by running the following command:

-```bash

-ai init

-```

-If you run the Azure AI CLI with VS Code (Web) coming from Azure AI Studio, your development environment will already be configured. The `ai init` command takes fewer steps: you confirm the existing project and attached resources.

-If your development environment hasn't already been configured with an existing project, or you select the **Initialize something else** option, there will be a few flows you can choose when running `ai init`: **Initialize a new AI project**, **Initialize an existing AI project**, or **Initialize standalone resources**.

-The following table describes the scenarios for each flow.

-| Scenario | Description |

-| | |

-| Initialize a new AI project | Choose if you don't have an existing AI project that you have been working with in the Azure AI Studio. The `ai init` command walks you through creating or attaching resources. |

-| Initialize an existing AI project | Choose if you have an existing AI project you want to work with. The `ai init` command checks your existing linked resources, and asks you to set anything that hasn't been set before. |

-| Initialize standalone resources| Choose if you're building a simple solution connected to a single AI service, or if you want to attach more resources to your development environment |

-Working with an AI project is recommended when using the Azure AI Studio and/or connecting to multiple AI services. Projects come with An Azure AI hub resource that houses related projects and shareable resources like compute and connections to services. Projects also allow you to connect code to cloud resources (storage and model deployments), save evaluation results, and host code behind online endpoints. You're prompted to create and/or attach Azure AI Services to your project.

-Initializing standalone resources is recommended when building simple solutions connected to a single AI service. You can also choose to initialize more standalone resources after initializing a project.

-The following resources can be initialized standalone, or attached to projects:

-#### Initializing a new AI project

-1. Run `ai init` and choose **Initialize new AI project**.

-1. Select your subscription. You might be prompted to sign in through an interactive flow.

-1. Select your Azure AI hub resource, or create a new one. An Azure AI hub resource can have multiple projects that can share resources.

-1. Select the name of your new project. There are some suggested names, or you can enter a custom one. Once you submit, the project might take a minute to create.

-1. Select the resources you want to attach to the project. You can skip resource types you don't want to attach.

-1. `ai init` checks you have the connections you need for the attached resources, and your development environment is configured with your new project.

-#### Initializing an existing AI project

-1. Enter `ai init` and choose "Initialize an existing AI project".

-1. Select your subscription. You might be prompted to sign in through an interactive flow.

-1. Select the project from the list.

-1. Select the resources you want to attach to the project. There should be a default selection based on what is already attached to the project. You can choose to create new resources to attach.

-1. `ai init` checks you have the connections you need for the attached resources, and your development environment is configured with the project.

-#### Initializing standalone resources

-1. Enter `ai init` and choose "Initialize standalone resources".

-1. Select the type of resource you want to initialize.

-1. Select your subscription. You might be prompted to sign in through an interactive flow.

-1. Choose the desired resources from the list(s). You can create new resources to attach inline.

-1. `ai init` checks you have the connections you need for the attached resources, and your development environment is configured with attached resources.

-## Project connections

-When working the Azure AI CLI, you want to use your project's connections. Connections are established to attached resources and allow you to integrate services with your project. You can have project-specific connections, or connections shared at the Azure AI hub resource level. For more information, see [Azure AI hub resources](../concepts/ai-resources.md) and [connections](../concepts/connections.md).

-When you run `ai init` your project connections get set in your development environment, allowing seamless integration with AI services. You can view these connections by running `ai service connection list`, and further manage these connections with `ai service connection` subcommands.

-Any updates you make to connections in the Azure AI CLI is reflected in [Azure AI Studio](https://ai.azure.com), and vice versa.

-## ai dev

-`ai dev` helps you configure the environment variables in your development environment.

-After running `ai init`, you can run the following command to set a `.env` file populated with environment variables you can reference in your code.

-```bash

-ai dev new .env

-```

-## ai service

-`ai service` helps you manage your connections to resources and services.

-## ai flow

-`ai flow` lets you work with prompt flows in an interactive way. You can create new flows, invoke and test existing flows, serve a flow locally to test an application experience, upload a local flow to the Azure AI Studio, or deploy a flow to an endpoint.

-The following steps help you test out each capability. They assume you have run `ai init`.

-1. Run `ai flow new --name mynewflow` to create a new flow folder based on a template for a chat flow.

-1. Open the `flow.dag.yaml` file that was created in the previous step.

- 1. Update the `deployment_name` to match the chat deployment attached to your project. You can run `ai config @chat.deployment` to get the correct name.

- 1. Update the connection field to be **Default_AzureOpenAI**. You can run `ai service connection list` to verify your connection names.

-1. `ai flow invoke --name mynewflow --input question=hello` - this runs the flow with provided input and return a response.

-1. `ai flow serve --name mynewflow` - this will locally serve the application and you can test interactively in a new window.

-1. `ai flow package --name mynewflow` - this packages the flow as a Dockerfile.

-1. `ai flow upload --name mynewflow` - this uploads the flow to the AI Studio, where you can continue working on it with the prompt flow UI.

-1. You can deploy an uploaded flow to an online endpoint for inferencing via the Azure AI Studio UI, see [Deploy a flow for real-time inference](./flow-deploy.md) for more details.

-

-### Project connections with flows

-As mentioned in step 2 above, your flow.dag.yaml should reference connection and deployment names matching those attached to your project.

-If you're working in your own development environment (including Codespaces), you might need to manually update these fields so that your flow runs connected to Azure resources.

-If you launched VS Code from the AI Studio, you are in an Azure-connected custom container experience, and you can work directly with flows stored in the `shared` folder. These flow files are the same underlying files prompt flow references in the Studio, so they should already be configured with your project connections and deployments. To learn more about the folder structure in the VS Code container experience, see [Work with Azure AI projects in VS Code](develop-in-vscode.md)

-## ai chat

-Once you have initialized resources and have a deployment, you can chat interactively or non-interactively with the AI language model using the `ai chat` command. The CLI has more examples of ways to use the `ai chat` capabilities, simply enter `ai chat` to try them. Once you have tested the chat capabilities, you can add in your own data.

-# [Terminal](#tab/terminal)

-Here's an example of interactive chat:

-```bash

-ai chat --interactive --system @prompt.txt

-```

-Here's an example of non-interactive chat:

-```bash

-ai chat --system @prompt.txt --user "Tell me about Azure AI Studio"

-```

-# [PowerShell](#tab/powershell)

-Here's an example of interactive chat:

-```powershell

-ai --% chat --interactive --system @prompt.txt

-```

-Here's an example of non-interactive chat:

-```powershell

-ai --% chat --system @prompt.txt --user "Tell me about Azure AI Studio"

-```

-> [!NOTE]

-> If you're using PowerShell, use the `--%` stop-parsing token to prevent the terminal from interpreting the `@` symbol as a special character.

-#### Chat with your data

-Once you have tested the basic chat capabilities, you can add your own data using an Azure AI Search vector index.

-1. Create a search index based on your data

-1. Interactively chat with an AI system grounded in your data

-1. Clear the index to prepare for other chat explorations

-```bash

-ai search index update --name <index_name> --files "*.md"

-ai chat --index-name <index_name> --interactive

-```

-When you use `search index update` to create or update an index (the first step above), `ai config` stores that index name. Run `ai config` in the CLI to see more usage details.

-If you want to set a different existing index for subsequent chats, use:

-```bash

-ai config --set search.index.name <index_name>

-```

-If you want to clear the set index name, use

-```bash

-ai config --clear search.index.name

-```

-## ai help

-The Azure AI CLI is interactive with extensive `help` commands. You can explore capabilities not covered in this document by running:

-```bash

-ai help

-```

-## Next steps

-Not available in AI CLI, but you can use [Azure Machine Learning CLI](../../machine-learning/how-to-managed-network.md#configure-a-managed-virtual-network-to-allow-internet-outbound). Use your Azure AI hub name as workspace name in Azure Machine Learning CLI.

-Not available in AI CLI, but you can use [Azure Machine Learning CLI](../../machine-learning/how-to-managed-network.md#configure-a-managed-virtual-network-to-allow-only-approved-outbound). Use your Azure AI hub name as workspace name in Azure Machine Learning CLI.

-Not available in AI CLI, but you can use [Azure Machine Learning CLI](../../machine-learning/how-to-managed-network.md#manage-outbound-rules). Use your Azure AI hub name as workspace name in Azure Machine Learning CLI.

-description: Learn how to configure a private link for Azure AI

-# How to configure a private link for Azure AI

-We have two network isolation aspects. One is the network isolation to access an Azure AI. Another is the network isolation of computing resources in your Azure AI and Azure AI projects such as Compute Instance, Serverless and Managed Online Endpoint. This document explains the former highlighted in the diagram. You can use private link to establish the private connection to your Azure AI and its default resources. This article is for Azure AI. For information on Azure AI Services, see the [Azure AI Services documentation](/azure/ai-services/cognitive-services-virtual-networks).

-You get several Azure AI default resources in your resource group. You need to configure following network isolation configurations.

-* You must have an existing virtual network to create the private endpoint in.

-After creating the Azure AI, use the [Azure networking CLI commands](/cli/azure/network/private-endpoint#az-network-private-endpoint-create) to create a private link endpoint for the Azure AI.

-# [Azure portal](#tab/azure-portal)

-1. From the [Azure portal](https://portal.azure.com), go to Azure AI Studio and choose __+ New Azure AI__.

-1. Choose network isolation mode in __Networking__ tab.

-1. Scroll down to __Workspace Inbound access__ and choose __+ Add__.

-1. Input required fields. When selecting the __Region__, select the same region as your virtual network.

-## Add a private endpoint to an Azure AI

-Use one of the following methods to add a private endpoint to an existing Azure AI:

-Use the [Azure networking CLI commands](/cli/azure/network/private-endpoint#az-network-private-endpoint-create) to create a private link endpoint for the Azure AI.

-# [Azure portal](#tab/azure-portal)

-1. From the [Azure portal](https://portal.azure.com), select your Azure AI.

-1. From the left side of the page, select __Networking__ and then select the __Private endpoint connections__ tab.

-1. When selecting the __Region__, select the same region as your virtual network.

-1. When selecting __Resource type__, use azuremlworkspace.

-1. Set the __Resource__ to your workspace name.

-Finally, select __Create__ to create the private endpoint.

-You can remove one or all private endpoints for an Azure AI. Removing a private endpoint removes the Azure AI from the VNet that the endpoint was associated with. Removing the private endpoint might prevent the Azure AI from accessing resources in that VNet, or resources in the VNet from accessing the workspace. For example, if the VNet doesn't allow access to or from the public internet.

-> Removing the private endpoints for a workspace __doesn't make it publicly accessible__. To make the workspace publicly accessible, use the steps in the [Enable public access](#enable-public-access) section.

-# [Azure portal](#tab/azure-portal)

-1. From the [Azure portal](https://portal.azure.com), select your Azure AI.

-1. From the left side of the page, select __Networking__ and then select the __Private endpoint connections__ tab.

-1. Select the endpoint to remove and then select __Remove__.

-In some situations, you might want to allow someone to connect to your secured Azure AI over a public endpoint, instead of through the VNet. Or you might want to remove the workspace from the VNet and re-enable public access.

-> Enabling public access doesn't remove any private endpoints that exist. All communications between components behind the VNet that the private endpoint(s) connect to are still secured. It enables public access only to the Azure AI, in addition to the private access through any private endpoints.

-# [Azure CLI](#tab/cli)

-Not available in AI CLI, but you can use [Azure Machine Learning CLI](../../machine-learning/how-to-configure-private-link.md#enable-public-access). Use your Azure AI name as workspace name in Azure Machine Learning CLI.

-1. From the [Azure portal](https://portal.azure.com), select your Azure AI.

-This is required if you make your storage account private. Our services need to read/write data in your private storage account using [Allow Azure services on the trusted services list to access this storage account](../../storage/common/storage-network-security.md#grant-access-to-trusted-azure-services) with below managed identity configurations. Enable system assigned managed identity of Azure AI Service and Azure AI Search, configure role-based access control for each managed identity.

-| `Storage File Data Privileged Contributor` | Azure AI project | Storage Account | Read/Write prompt flow data. | [Prompt flow doc](../../machine-learning/prompt-flow/how-to-secure-prompt-flow.md#secure-prompt-flow-with-workspace-managed-virtual-network) |

-| `Storage Blob Data Contributor` | Azure AI Search | Storage Account | Read blob and write knowledge store | [Search doc](../../search/search-howto-managed-identities-data-sources.md)|

-See [Azure Machine Learning custom dns doc](../../machine-learning/how-to-custom-dns.md#example-custom-dns-server-hosted-in-vnet) for the DNS forwarding configurations.

-If you need to configure custom dns server without dns forwarding, the following is the required A records.

-See [this documentation](../../machine-learning/how-to-custom-dns.md#find-the-ip-addresses) to check your private IP addresses for your A records. To check AI-PROJECT-GUID, go to Azure portal > Your Azure AI Project > JSON View > workspaceId.

-* Private Azure AI services and Azure AI Search aren't supported.

-* You might encounter problems trying to access the private endpoint for your Azure AI if you're using Mozilla Firefox. This problem might be related to DNS over HTTPS in Mozilla Firefox. We recommend using Microsoft Edge or Google Chrome.

-Note that disabling SSH prevents SSH access from the public internet. When a private virtual network is used, users can still SSH from within the virtual network.

-Azure AI Studio supports developing in VS Code - Web and Desktop. In each scenario, your VS Code instance is remotely connected to a prebuilt custom container running on a virtual machine, also known as a compute instance. To work in your local environment instead, or to learn more, follow the steps in [Install the Azure AI SDK](sdk-install.md) and [Install the Azure AI CLI](cli-install.md).

-python --version # ensure you've >=3.8

-## Create an index

-1. Choose your **Source data**. You can choose source data from a list of your recent data sources, a storage URL on the cloud or even upload files and folders from the local machine. You can also add a connection to another data source such as Azure Blob Storage.

- 1. The search type defaults to **Hybrid + Semantic**, which is a combination of keyword search, vector search and semantic search to give the best possible search results.

- 1. For the hybrid option to work, you need an embedding model. Choose the Azure OpenAI resource, which has the embedding model

-

-1. Use the prefilled name or type your own name for New Vector index name

-

- > [!NOTE]

- > If you see a **DeploymentNotFound** error, you need to assign more permissions. See [mitigate DeploymentNotFound error](#mitigate-deploymentnotfound-error) for more details.

-### Mitigate DeploymentNotFound error

-When you try to create a vector index, you might see the following error at the **Review + Finish** step:

-**Failed to create vector index. DeploymentNotFound: A valid deployment for the model=text-embedding-ada-002 was not found in the workspace connection=Default_AzureOpenAI provided.**

-This can happen if you are trying to create an index using an **Owner**, **Contributor**, or **Azure AI Developer** role at the project level. To mitigate this error, you might need to assign more permissions using either of the following methods.

-> [!NOTE]

-> You need to be assigned the **Owner** role of the resource group or higher scope (like Subscription) to perform the operation in the next steps. This is because only the Owner role can assign roles to others. See details [here](/azure/role-based-access-control/built-in-roles).

-#### Method 1: Assign more permissions to the user on the Azure AI hub resource

-If the Azure AI hub resource the project uses was created through Azure AI Studio:

-1. Sign in to [Azure AI Studio](https://aka.ms/azureaistudio) and select your project via **Build** > **Projects**.

-1. Select **AI project settings** from the collapsible left menu.

-1. From the **Resource Configuration** section, select the link for your resource group name that takes you to the Azure portal.

-1. In the Azure portal under **Overview** > **Resources** select the Azure AI service type. It's named similar to "YourAzureAIResourceName-aiservices."

- :::image type="content" source="../media/roles-access/resource-group-azure-ai-service.png" alt-text="Screenshot of Azure AI service in a resource group." lightbox="../media/roles-access/resource-group-azure-ai-service.png":::

-1. Select **Access control (IAM)** > **+ Add** to add a role assignment.

-1. Add the **Cognitive Services OpenAI User** role to the user who wants to make an index. `Cognitive Services OpenAI Contributor` and `Cognitive Services Contributor` also work, but they assign more permissions than needed for creating an index in Azure AI Studio.

-> [!NOTE]

-> You can also opt to assign more permissions [on the resource group](#method-2-assign-more-permissions-on-the-resource-group). However, that method assigns more permissions than needed to mitigate the **DeploymentNotFound** error.

-#### Method 2: Assign more permissions on the resource group

-If the Azure AI hub resource the project uses was created through Azure portal:

-1. Sign in to [Azure AI Studio](https://aka.ms/azureaistudio) and select your project via **Build** > **Projects**.

-1. Select **AI project settings** from the collapsible left menu.

-1. From the **Resource Configuration** section, select the link for your resource group name that takes you to the Azure portal.

-1. Select **Access control (IAM)** > **+ Add** to add a role assignment.

-1. Add the **Cognitive Services OpenAI User** role to the user who wants to make an index. `Cognitive Services OpenAI Contributor` and `Cognitive Services Contributor` also work, but they assign more permissions than needed for creating an index in Azure AI Studio.

- :::image type="content" source="../media/index-retrieve/configure-index-lookup-tool.png" alt-text="Screenshot of Configure Index Lookup." lightbox="../media/index-retrieve/configure-index-lookup-tool.png":::

-description: This article introduces the Azure OpenAI GPT-4 Turbo with Vision tool for flows in Azure AI Studio.

-The prompt flow *Azure OpenAI GPT-4 Turbo with Vision* tool enables you to use your Azure OpenAI GPT-4 Turbo with Vision model deployment to analyze images and provide textual responses to questions about them.

- Currently, access to this service is granted only by application. You can apply for access to Azure OpenAI by completing the form at <a href="https://aka.ms/oai/access" target="_blank">https://aka.ms/oai/access</a>. Open an issue on this repo to contact us if you have an issue.

- :::image type="content" source="../../media/prompt-flow/azure-openai-gpt-4-vision-tool.png" alt-text="Screenshot of the Azure OpenAI GPT-4 Turbo with Vision tool added to a flow in Azure AI Studio." lightbox="../../media/prompt-flow/azure-openai-gpt-4-vision-tool.png":::

-1. Enter values for the Azure OpenAI GPT-4 Turbo with Vision tool input parameters described [here](#inputs). For example, you can use this example prompt:

-1. Specify an image to analyze in the `image_input` input parameter. For example, you can upload an image or enter the URL of an image to analyze. Otherwise you can paste or drag and drop an image into the tool.

-1. Add more tools to your flow as needed, or select **Run** to run the flow.

-1. The outputs are described [here](#outputs).

-The following are available input parameters:

-| prompt | string | Text prompt that the language model uses to generate its response. The Jinja template for composing prompts in this tool follows a similar structure to the chat API in the LLM tool. To represent an image input within your prompt, you can use the syntax ``. Image input can be passed in the `user`, `system` and `assistant` messages. | Yes |

-| max\_tokens | integer | Maximum number of tokens to generate in the response. Default is 512. | No |

-| temperature | float | Randomness of the generated text. Default is 1. | No |

-| stop | list | Stopping sequence for the generated text. Default is null. | No |

-| top_p | float | Probability of using the top choice from the generated tokens. Default is 1. | No |

-| presence\_penalty | float | Value that controls the model's behavior regarding repeating phrases. Default is 0. | No |

-| frequency\_penalty | float | Value that controls the model's behavior regarding generating rare phrases. Default is 0. | No |

-The following are available output parameters:

-| Return Type | Description |

-## Next step

-description: This article introduces the Content Safety tool for flows in Azure AI Studio.

-The prompt flow *Content Safety* tool enables you to use Azure AI Content Safety in Azure AI Studio.

-Create an Azure Content Safety connection:

-1. Complete all steps in the **Create a new connection** dialog box. You can use an Azure AI hub resource or Azure AI Content Safety resource. An Azure AI hub resource that supports multiple Azure AI services is recommended.

- :::image type="content" source="../../media/prompt-flow/content-safety-tool.png" alt-text="Screenshot of the Content Safety tool added to a flow in Azure AI Studio." lightbox="../../media/prompt-flow/content-safety-tool.png":::

-1. Enter values for the Content Safety tool input parameters described [here](#inputs).

-1. Add more tools to your flow as needed, or select **Run** to run the flow.

-1. The outputs are described [here](#outputs).

-The following are available input parameters:

-| hate_category | string | The moderation sensitivity for Hate category. You can choose from four options: *disable*, *low_sensitivity*, *medium_sensitivity*, or *high_sensitivity*. The *disable* option means no moderation for hate category. The other three options mean different degrees of strictness in filtering out hate content. The default option is *medium_sensitivity*. | Yes |

-| sexual_category | string | The moderation sensitivity for Sexual category. You can choose from four options: *disable*, *low_sensitivity*, *medium_sensitivity*, or *high_sensitivity*. The *disable* option means no moderation for sexual category. The other three options mean different degrees of strictness in filtering out sexual content. The default option is *medium_sensitivity*. | Yes |

-| self_harm_category | string | The moderation sensitivity for Self-harm category. You can choose from four options: *disable*, *low_sensitivity*, *medium_sensitivity*, or *high_sensitivity*. The *disable* option means no moderation for self-harm category. The other three options mean different degrees of strictness in filtering out self_harm content. The default option is *medium_sensitivity*. | Yes |

-| violence_category | string | The moderation sensitivity for Violence category. You can choose from four options: *disable*, *low_sensitivity*, *medium_sensitivity*, or *high_sensitivity*. The *disable* option means no moderation for violence category. The other three options mean different degrees of strictness in filtering out violence content. The default option is *medium_sensitivity*. | Yes |

-You can use the following parameters as inputs for this tool:

-| action_by_category | string | A binary value for each category: *Accept* or *Reject*. This value shows if the text meets the sensitivity level that you set in the request parameters for that category. |

-| suggested_action | string | An overall recommendation based on the four categories. If any category has a *Reject* value, the `suggested_action` is *Reject* as well. |

-description: This article introduces the Embedding tool for flows in Azure AI Studio.

-The prompt flow *Embedding* tool enables you to convert text into dense vector representations for various natural language processing tasks

-> For chat and completion tools, check out the [LLM tool](llm-tool.md).

- :::image type="content" source="../../media/prompt-flow/embedding-tool.png" alt-text="Screenshot of the Embedding tool added to a flow in Azure AI Studio." lightbox="../../media/prompt-flow/embedding-tool.png":::

-1. Enter values for the Embedding tool input parameters described [here](#inputs).

-1. Add more tools to your flow as needed, or select **Run** to run the flow.

-1. The outputs are described [here](#outputs).

-The following are available input parameters:

-| input | string | the input text to embed | Yes |

-| model, deployment_name | string | instance of the text-embedding engine to use | Yes |

-> Vector, Vector DB and Faiss Index Lookup tools are deprecated and will be retired soon. [Migrated to the new Index Lookup tool (preview).](index-lookup-tool.md#how-to-migrate-from-legacy-tools-to-the-index-lookup-tool)

-description: This article introduces the Index Lookup tool for flows in Azure AI Studio.

-The prompt flow *Index Lookup* tool enables the usage of common vector indices (such as Azure AI Search, FAISS, and Pinecone) for retrieval augmented generation (RAG) in prompt flow. The tool automatically detects the indices in the workspace and allows the selection of the index to be used in the flow.

- :::image type="content" source="../../media/prompt-flow/configure-index-lookup-tool.png" alt-text="Screenshot of the Index Lookup tool added to a flow in Azure AI Studio." lightbox="../../media/prompt-flow/configure-index-lookup-tool.png":::

-1. Enter values for the Index Lookup tool [input parameters](#inputs). The [LLM tool](llm-tool.md) can generate the vector input.

-1. Add more tools to your flow as needed, or select **Run** to run the flow.

-1. To learn more about the returned output, see [outputs](#outputs).

-The following are available input parameters:

-| mlindex_content | string | Type of index to be used. Input depends on the index type. An example of an Azure AI Search index JSON can be seen below the table. | Yes |

-Here's an example of an Azure AI Search index input.

-The following JSON format response is an example returned by the tool that includes the top-k scored entities. The entity follows a generic schema of vector search result provided by the `promptflow-vectordb` SDK. For the Vector Index Search, the following fields are populated:

-| Field Name | Type | Description |

-| metadata | dict | Customized key-value pairs provided by user when creating the index |

-| page_content | string | Content of the vector chunk being used in the lookup |

-| score | float | Depends on index type defined in Vector Index. If index type is Faiss, score is L2 distance. If index type is Azure AI Search, score is cosine similarity. |

-

-## How to migrate from legacy tools to the Index Lookup tool

-The Index Lookup tool looks to replace the three deprecated legacy index tools, the [Vector Index Lookup tool](./vector-index-lookup-tool.md), the [Vector DB Lookup tool](./vector-db-lookup-tool.md) and the [Faiss Index Lookup tool](./faiss-index-lookup-tool.md).

-If you have a flow that contains one of these tools, follow the steps below to upgrade your flow.

-1. Update your runtime. In order to do this navigate to the "AI project settings tab on the left blade in AI Studio. From there you should see a list of Prompt flow runtimes. Select the name of the runtime you want to update, and click on the ΓÇ£UpdateΓÇ¥ button near the top of the panel. Wait for the runtime to update itself.

-1. Navigate to your flow. You can do this by clicking on the ΓÇ£Prompt flowΓÇ¥ tab on the left blade in AI Studio, clicking on the ΓÇ£FlowsΓÇ¥ pivot tab, and then clicking on the name of your flow.

-1. Once inside the flow, click on the ΓÇ£+ More toolsΓÇ¥ button near the top of the pane. A dropdown should open and click on ΓÇ£Index Lookup [Preview]ΓÇ¥ to add an instance of the Index Lookup tool.

- :::image type="content" source="../../media/prompt-flow/upgrade-index-tools/index-dropdown.png" alt-text="Screenshot of the More Tools dropdown in promptflow." lightbox="../../media/prompt-flow/upgrade-index-tools/index-dropdown.png":::

-1. Name the new node and click ΓÇ£AddΓÇ¥.

- :::image type="content" source="../../media/prompt-flow/upgrade-index-tools/save-node.png" alt-text="Screenshot of the index lookup node with name." lightbox="../../media/prompt-flow/upgrade-index-tools/save-node.png":::

-1. In the new node, click on the ΓÇ£mlindex_contentΓÇ¥ textbox. This should be the first textbox in the list.

- :::image type="content" source="../../media/prompt-flow/upgrade-index-tools/mlindex-box.png" alt-text="Screenshot of the expanded Index Lookup node with the mlindex_content box outlined in red." lightbox="../../media/prompt-flow/upgrade-index-tools/mlindex-box.png":::

-1. In the Generate drawer that appears, follow the instructions below to upgrade from the three legacy tools:

- - If using the legacy **Vector Index Lookup** tool, select ΓÇ£Registered Index" in the ΓÇ£index_typeΓÇ¥ dropdown. Select your vector index asset from the ΓÇ£mlindex_asset_idΓÇ¥ dropdown.

- - If using the legacy **Faiss Index Lookup** tool, select ΓÇ£FaissΓÇ¥ in the ΓÇ£index_typeΓÇ¥ dropdown and specify the same path as in the legacy tool.

- - If using the legacy **Vector DB Lookup** tool, select AI Search or Pinecone depending on the DB type in the ΓÇ£index_typeΓÇ¥ dropdown and fill in the information as necessary.

-1. After filling in the necessary information, click save.

-1. Upon returning to the node, there should be information populated in the ΓÇ£mlindex_contentΓÇ¥ textbox. Click on the ΓÇ£queriesΓÇ¥ textbox next, and select the search terms you want to query. YouΓÇÖll want to select the same value as the input to the ΓÇ£embed_the_questionΓÇ¥ node, typically either ΓÇ£\${inputs.question}ΓÇ¥ or ΓÇ£${modify_query_with_history.output}ΓÇ¥ (the former if youΓÇÖre in a standard flow and the latter if youΓÇÖre in a chat flow).

- :::image type="content" source="../../media/prompt-flow/upgrade-index-tools/mlindex-with-content.png" alt-text="Screenshot of the expanded Index Lookup node with index information in the cells." lightbox="../../media/prompt-flow/upgrade-index-tools/mlindex-with-content.png":::

-1. Select a query type by clicking on the dropdown next to ΓÇ£query_type.ΓÇ¥ ΓÇ£VectorΓÇ¥ will produce identical results as the legacy flow, but depending on your index configuration, other options including "Hybrid" and "Semantic" may be available.

- :::image type="content" source="../../media/prompt-flow/upgrade-index-tools/vector-search.png" alt-text="Screenshot of the expanded Index Lookup node with vector search outlined in red." lightbox="../../media/prompt-flow/upgrade-index-tools/vector-search.png":::

-1. Edit downstream components to consume the output of your newly added node, instead of the output of the legacy Vector Index Lookup node.

-1. Delete the Vector Index Lookup node and its parent embedding node.

-description: This article introduces the LLM tool for flows in Azure AI Studio.

-The prompt flow *LLM* tool enables you to use large language models (LLM) for natural language processing.

-Prepare a prompt as described in the [prompt tool](prompt-tool.md#prerequisites) documentation. The LLM tool and Prompt tool both support [Jinja](https://jinja.palletsprojects.com/en/3.1.x/) templates. For more information and best practices, see [prompt engineering techniques](../../../ai-services/openai/concepts/advanced-prompt-engineering.md).

- :::image type="content" source="../../media/prompt-flow/llm-tool.png" alt-text="Screenshot of the LLM tool added to a flow in Azure AI Studio." lightbox="../../media/prompt-flow/llm-tool.png":::

-1. From the **Api** drop-down list, select *chat* or *completion*.

-1. Enter values for the LLM tool input parameters described [here](#inputs). If you selected the *chat* API, see [chat inputs](#chat-inputs). If you selected the *completion* API, see [text completion inputs](#text-completion-inputs). For information about how to prepare the prompt input, see [prerequisites](#prerequisites).

-1. Add more tools to your flow as needed, or select **Run** to run the flow.

-1. The outputs are described [here](#outputs).

-The following are available input parameters:

-| prompt | string | text prompt for the language model | Yes |

-| model, deployment_name | string | the language model to use | Yes |

-| max\_tokens | integer | the maximum number of tokens to generate in the completion. Default is 16. | No |

-| temperature | float | the randomness of the generated text. Default is 1. | No |

-| stop | list | the stopping sequence for the generated text. Default is null. | No |

-| suffix | string | text appended to the end of the completion | No |

-| top_p | float | the probability of using the top choice from the generated tokens. Default is 1. | No |

-| logprobs | integer | the number of log probabilities to generate. Default is null. | No |

-| echo | boolean | value that indicates whether to echo back the prompt in the response. Default is false. | No |

-| presence\_penalty | float | value that controls the model's behavior regarding repeating phrases. Default is 0. | No |

-| frequency\_penalty | float | value that controls the model's behavior regarding generating rare phrases. Default is 0. | No |

-| best\_of | integer | the number of best completions to generate. Default is 1. | No |

-| logit\_bias | dictionary | the logit bias for the language model. Default is empty dictionary. | No |

-| prompt | string | text prompt that the language model should reply to | Yes |

-| model, deployment_name | string | the language model to use | Yes |

-| max\_tokens | integer | the maximum number of tokens to generate in the response. Default is inf. | No |

-| temperature | float | the randomness of the generated text. Default is 1. | No |

-| stop | list | the stopping sequence for the generated text. Default is null. | No |

-| top_p | float | the probability of using the top choice from the generated tokens. Default is 1. | No |

-| presence\_penalty | float | value that controls the model's behavior regarding repeating phrases. Default is 0. | No |

-| frequency\_penalty | float | value that controls the model's behavior regarding generating rare phrases. Default is 0. | No |

-| logit\_bias | dictionary | the logit bias for the language model. Default is empty dictionary. | No |

-| API | Return Type | Description |

-| Completion | string | The text of one predicted completion |

-| Chat | string | The text of one response of conversation |

-The following table provides an index of tools in prompt flow.

-| Tool (set) name | Description | Environment | Package name |

-| [LLM](./llm-tool.md) | Use Azure OpenAI large language models (LLM) for tasks such as text completion or chat. | Default | [promptflow-tools](https://pypi.org/project/promptflow-tools/) |

-| [Prompt](./prompt-tool.md) | Craft a prompt by using Jinja as the templating language. | Default | [promptflow-tools](https://pypi.org/project/promptflow-tools/) |

-| [Python](./python-tool.md) | Run Python code. | Default | [promptflow-tools](https://pypi.org/project/promptflow-tools/) |

-| [Azure OpenAI GPT-4 Turbo with Vision](./azure-open-ai-gpt-4v-tool.md) | Use AzureOpenAI GPT-4 Turbo with Vision model deployment to analyze images and provide textual responses to questions about them. | Default | [promptflow-tools](https://pypi.org/project/promptflow-tools/) |

-| [Content Safety (Text)](./content-safety-tool.md) | Use Azure AI Content Safety to detect harmful content. | Default | [promptflow-tools](https://pypi.org/project/promptflow-tools/) |

-| [Index Lookup*](./index-lookup-tool.md) | Search an Azure Machine Learning Vector Index for relevant results using one or more text queries. | Default | [promptflow-vectordb](https://pypi.org/project/promptflow-vectordb/) |

-| [Vector Index Lookup*](./vector-index-lookup-tool.md) | Search text or a vector-based query from a vector index. | Default | [promptflow-vectordb](https://pypi.org/project/promptflow-vectordb/) |

-| [Faiss Index Lookup*](./faiss-index-lookup-tool.md) | Search a vector-based query from the Faiss index file. | Default | [promptflow-vectordb](https://pypi.org/project/promptflow-vectordb/) |

-| [Vector DB Lookup*](./vector-db-lookup-tool.md) | Search a vector-based query from an existing vector database. | Default | [promptflow-vectordb](https://pypi.org/project/promptflow-vectordb/) |

-| [Embedding](./embedding-tool.md) | Use Azure OpenAI embedding models to create an embedding vector that represents the input text. | Default | [promptflow-tools](https://pypi.org/project/promptflow-tools/) |

-| [Serp API](./serp-api-tool.md) | Use Serp API to obtain search results from a specific search engine. | Default | [promptflow-tools](https://pypi.org/project/promptflow-tools/) |

-| [Azure AI Language tools*](https://microsoft.github.io/promptflow/integrations/tools/azure-ai-language-tool.html) | This collection of tools is a wrapper for various Azure AI Language APIs, which can help effectively understand and analyze documents and conversations. The capabilities currently supported include: Abstractive Summarization, Extractive Summarization, Conversation Summarization, Entity Recognition, Key Phrase Extraction, Language Detection, PII Entity Recognition, Conversational PII, Sentiment Analysis, Conversational Language Understanding, Translator. You can learn how to use them by the [Sample flows](https://github.com/microsoft/promptflow/tree/e4542f6ff5d223d9800a3687a7cfd62531a9607c/examples/flows/integrations/azure-ai-language). Support contact: taincidents@microsoft.com | Custom | [promptflow-azure-ai-language](https://pypi.org/project/promptflow-azure-ai-language/) |

-_*The asterisk marks indicate custom tools, which are created by the community that extend prompt flow's capabilities for specific use cases. They aren't officially maintained or endorsed by prompt flow team. When you encounter questions or issues for these tools, please prioritize using the support contact if it is provided in the description._

-To discover more custom tools developed by the open-source community, see [More custom tools](https://microsoft.github.io/promptflow/integrations/tools/https://docsupdatetracker.net/index.html).

-## Remarks

-description: This article introduces the Prompt tool for flows in Azure AI Studio.

-The prompt flow *Prompt* tool offers a collection of textual templates that serve as a starting point for creating prompts. These templates, based on the [Jinja](https://jinja.palletsprojects.com/en/3.1.x/) template engine, facilitate the definition of prompts. The tool proves useful when prompt tuning is required prior to feeding the prompts into the large language model (LLM) in prompt flow.

-Prepare a prompt. The [LLM tool](llm-tool.md) and Prompt tool both support [Jinja](https://jinja.palletsprojects.com/en/3.1.x/) templates.

-In this example, the prompt incorporates Jinja templating syntax to dynamically generate the welcome message and personalize it based on the user's name. It also presents a menu of options for the user to choose from. Depending on whether the user_name variable is provided, it either addresses the user by name or uses a generic greeting.

-For more information and best practices, see [prompt engineering techniques](../../../ai-services/openai/concepts/advanced-prompt-engineering.md).

- :::image type="content" source="../../media/prompt-flow/prompt-tool.png" alt-text="Screenshot of the Prompt tool added to a flow in Azure AI Studio." lightbox="../../media/prompt-flow/prompt-tool.png":::

-1. Enter values for the Prompt tool input parameters described [here](#inputs). For information about how to prepare the prompt input, see [prerequisites](#prerequisites).

-1. Add more tools (such as the [LLM tool](llm-tool.md)) to your flow as needed, or select **Run** to run the flow.

-1. The outputs are described [here](#outputs).

-The following are available input parameters:

-| prompt | string | The prompt template in Jinja | Yes |

-| Inputs | - | List of variables of prompt template and its assignments | - |

-Inputs

-| Variable | Type | Sample Value |

-Outputs

-Inputs

-| Variable | Type | Sample Value |

-Outputs

-description: This article introduces the Python tool for flows in Azure AI Studio.

-The prompt flow *Python* tool offers customized code snippets as self-contained executable nodes. You can quickly create Python tools, edit code, and verify results.

- :::image type="content" source="../../media/prompt-flow/python-tool.png" alt-text="Screenshot of the Python tool added to a flow in Azure AI Studio." lightbox="../../media/prompt-flow/python-tool.png":::

-1. Enter values for the Python tool input parameters described [here](#inputs). For example, in the **Code** input text box you can enter the following Python code:

-1. Add more tools to your flow as needed, or select **Run** to run the flow.

-1. The outputs are described [here](#outputs). Given the previous example Python code input, if the input message is "world", the output is `hello world`.

-The list of inputs will change based on the arguments of the tool function, after you save the code. Adding type to arguments and return values help the tool show the types properly.

-| Code | string | Python code snippet | Yes |

-| Inputs | - | List of tool function parameters and its assignments | - |

-The output is the `return` value of the python tool function. For example, consider the following python tool function:

-If the input message is "world", the output is `hello world`.

-| Connection | param: CustomConnection | Connection type will be handled specially |

-Parameters with `Connection` type annotation will be treated as connection inputs, which means:

-> [!Note]

-> `Union[...]` type annotation is only supported for connection type, for example, `param: Union[CustomConnection, OpenAIConnection]`.

-## Consume custom connection in the Python tool

-If you're developing a python tool that requires calling external services with authentication, you can use the custom connection in prompt flow. It allows you to securely store the access key and then retrieve it in your python code.

-Create a custom connection that stores all your LLM API KEY or other required credentials.

-1. Go to **AI project settings**, then select **New Connection**.

-1. Select **Custom** service. You can define your connection name, and you can add multiple *Key-value pairs* to store your credentials and keys by selecting **Add key-value pairs**.

- > Make sure at least one key-value pair is set as secret, otherwise the connection will not be created successfully. You can set one Key-Value pair as secret by **is secret** checked, which will be encrypted and stored in your key value.

- :::image type="content" source="../../media/prompt-flow/create-connection.png" alt-text="Screenshot that shows create connection in AI Studio." lightbox = "../../media/prompt-flow/create-connection.png":::

- :::image type="content" source="../../media/prompt-flow/custom-connection-keys.png" alt-text="Screenshot that shows add extra meta to custom connection in AI Studio." lightbox = "../../media/prompt-flow/custom-connection-keys.png":::

-

-### Consume custom connection in Python

-To consume a custom connection in your python code, follow these steps:

-1. In the code section in your python node, import custom connection library `from promptflow.connections import CustomConnection`, and define an input parameter of type `CustomConnection` in the tool function.

-1. Parse the input to the input section, then select your target custom connection in the value dropdown.

-description: This article introduces the Serp API tool for flows in Azure AI Studio.

-The prompt flow *Serp API* tool provides a wrapper to the [SerpAPI Google Search Engine Results API](https://serpapi.com/search-api) and [SerpApi Bing Search Engine Results API](https://serpapi.com/bing-search-api).

-You can use the tool to retrieve search results from many different search engines, including Google and Bing. You can specify a range of search parameters, such as the search query, location, device type, and more.

-Sign up at [SERP API homepage](https://serpapi.com/)

-Create a Serp connection:

- - `api_key`: Your_Serp_API_key. You must check the **is secret** checkbox to keep the API key secure.

- :::image type="content" source="../../media/prompt-flow/serp-custom-connection-keys.png" alt-text="Screenshot that shows add extra meta to custom connection in AI Studio." lightbox = "../../media/prompt-flow/serp-custom-connection-keys.png":::

-The connection is the model used to establish connections with Serp API. Get your API key from the SerpAPI account dashboard.

-| Type | Name | API KEY |

- :::image type="content" source="../../media/prompt-flow/serp-api-tool.png" alt-text="Screenshot of the Serp API tool added to a flow in Azure AI Studio." lightbox="../../media/prompt-flow/serp-api-tool.png":::

-1. Enter values for the Serp API tool input parameters described [here](#inputs).

-1. Add more tools to your flow as needed, or select **Run** to run the flow.

-1. The outputs are described [here](#outputs).

-The following are available input parameters:

-| location | string | The geographic location to execute the search from. | No |

-The json representation from serpapi query.

-| Engine | Return Type | Output |

-> Vector, Vector DB and Faiss Index Lookup tools are deprecated and will be retired soon. [Migrated to the new Index Lookup tool (preview).](index-lookup-tool.md#how-to-migrate-from-legacy-tools-to-the-index-lookup-tool)

-> Vector, Vector DB and Faiss Index Lookup tools are deprecated and will be retired soon. [Migrated to the new Index Lookup tool (preview).](index-lookup-tool.md#how-to-migrate-from-legacy-tools-to-the-index-lookup-tool)

-### Remarks about adding your data

-Although it's beyond the scope of this tutorial, to understand more about how the model uses your data, you can export the playground setup to prompt flow.

-Following through from there you can see the graphical representation of how the model uses your data to construct the response. For more information about prompt flow, see [prompt flow](../how-to/prompt-flow.md).

- > Evaluation with AI-assisted metrics needs to call another GPT model to do the calculation. For best performance, use a GPT-4 or gpt-35-turbo-16k model. If you didn't previously deploy a GPT-4 or gpt-35-turbo-16k model, you can deploy another model by following the steps in [Deploy a chat model](#deploy-a-chat-model). Then return to this step and select the model you deployed.

- > The evaluation process may take up lots of tokens, so it's recommended to use a model which can support >=16k tokens.

-1. Install the [Azure AI CLI](../how-to/cli-install.md). The Azure AI CLI is a command-line interface for managing Azure AI resources. It's used to configure resources needed for your copilot.

-In this section, you use the [Azure AI CLI](../how-to/cli-install.md) to configure resources needed for your copilot:

-* You need an Azure [storage account][azure-storage-account].

-|DiskIOPSReadWrite | [UltraSSD disk][ultra-ssd-disks] IOPS Capability (minimum: 2 IOPS/GiB) | 100~160000 | No | `500`|

-|DiskMBpsReadWrite | [UltraSSD disk][ultra-ssd-disks] Throughput Capability(minimum: 0.032/GiB) | 1~2000 | No | `100`|

-It's not supported to reduce the size of a PVC (to prevent data loss). You can edit an existing storage class using the `kubectl edit sc` command, or you can create your own custom storage class. For example, if you want to use a disk of size 4 TiB, you must create a storage class that defines `cachingmode: None` because [disk caching isn't supported for disks 4 TiB and larger][disk-host-cache-setting]. For more information about storage classes and creating your own storage class, see [Storage options for applications in AKS][storage-class-concepts].

-This section provides guidance for cluster administrators who want to create one or more persistent volumes that include details of Azure Disks storage for use by a workload.

-### Static provisioning parameters for PersistentVolume

-The following table includes parameters you can use to define a PersistentVolume.

- # Output

-2. Create a disk using the [`az disk create`][az-disk-create] command. Specify the node resource group name and a name for the disk resource, such as *myAKSDisk*. The following example creates a *20*GiB disk, and outputs the ID of the disk after it's created. If you need to create a disk for use with Windows Server containers, add the `--os-type windows` parameter to correctly format the disk.

-* You can connect to and expose applications internally or externally.

-* You can build highly available applications by load balancing your applications.

-* You can restrict the flow of network traffic into or between pods and nodes to improve security.

-* You can configure Ingress traffic for SSL/TLS termination or routing of multiple components for your more complex applications.

-* [Services and ServiceTypes](#services)

-* [Azure virtual networks](#azure-virtual-networks)

-* [Ingress controllers](#ingress-controllers)

-* [Network policies](#network-policies)

-## Services

-To simplify the network configuration for application workloads, Kubernetes uses *Services* to logically group a set of pods together and provide network connectivity. You can specify a Kubernetes *ServiceType* to define the type of Service you want. For example, if you want to expose a Service on an external IP address outside of your cluster. For more information, see the Kubernetes documentation on [Publishing Services (ServiceTypes)][service-types].

-The following ServiceTypes are available:

-* **ClusterIP**

-

- ClusterIP creates an internal IP address for use within the AKS cluster. The ClusterIP Service is good for *internal-only applications* that support other workloads within the cluster. ClusterIP is the default used if you don't explicitly specify a type for a Service.

- ![Diagram showing ClusterIP traffic flow in an AKS cluster][aks-clusterip]

-* **NodePort**

- NodePort creates a port mapping on the underlying node that allows the application to be accessed directly with the node IP address and port.

- ![Diagram showing NodePort traffic flow in an AKS cluster][aks-nodeport]

-* **LoadBalancer**

- LoadBalancer creates an Azure load balancer resource, configures an external IP address, and connects the requested pods to the load balancer backend pool. To allow customers' traffic to reach the application, load balancing rules are created on the desired ports.

- ![Diagram showing Load Balancer traffic flow in an AKS cluster][aks-loadbalancer]

- For HTTP load balancing of inbound traffic, another option is to use an [Ingress controller](#ingress-controllers).

-* **ExternalName**

- Creates a specific DNS entry for easier application access.

-Either the load balancers and services IP address can be dynamically assigned, or you can specify an existing static IP address. You can assign both internal and external static IP addresses. Existing static IP addresses are often tied to a DNS entry.

-You can create both *internal* and *external* load balancers. Internal load balancers are only assigned a private IP address, so they can't be accessed from the Internet.

-Learn more about Services in the [Kubernetes docs][k8s-service].

-* ***Kubenet* networking**

-* ***Azure Container Networking Interface (CNI)* networking**

-* **kubenet**

- * Conserves IP address space.

- * Uses Kubernetes internal or external load balancers to reach pods from outside of the cluster.

- * You manually manage and maintain user-defined routes (UDRs).

- * Maximum of 400 nodes per cluster.

-* **Azure CNI**

-* The Azure platform can automatically create and configure the virtual network resources when you create an AKS cluster.

-* You can manually create and configure the virtual network resources and attach to those resources when you create your AKS cluster.

-* If you manually create the virtual network resources for an AKS cluster, you're supported when configuring your own UDRs or service endpoints.

-* If the Azure platform automatically creates the virtual network resources for your AKS cluster, you can't manually change those AKS-managed resources to configure your own UDRs or service endpoints.

-* Easy configuration of managed NGINX Ingress controllers based on Kubernetes NGINX Ingress controller.

-* Integration with Azure DNS for public and private zone management.

-* SSL termination with certificates stored in Azure Key Vault.

-* Back-end applications are only exposed to required frontend services.

-* Database components are only accessible to the application tiers that connect to them.

-* [Kubernetes / AKS clusters and workloads][aks-concepts-clusters-workloads]

-* [Kubernetes / AKS access and identity][aks-concepts-identity]

-* [Kubernetes / AKS security][aks-concepts-security]

-* [Kubernetes / AKS storage][aks-concepts-storage]

-* [Kubernetes / AKS scale][aks-concepts-scale]

-[aks-clusterip]: ./media/concepts-network/aks-clusterip.png

-[aks-nodeport]: ./media/concepts-network/aks-nodeport.png

-[k8s-service]: https://kubernetes.io/docs/concepts/services-networking/service/

-[service-types]: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types

- az group create -n myResourceGroup -l eastus2

-2. Create an AKS cluster with Azure Key Vault provider for Secrets Store CSI Driver capability using the [`az aks create`][az-aks-create] command and enable the `azure-keyvault-secrets-provider` add-on.

- > az aks create -n myAKSCluster -g myResourceGroup --enable-addons azure-keyvault-secrets-provider --enable-oidc-issuer --enable-workload-identity

- az aks create -n myAKSCluster -g myResourceGroup --enable-addons azure-keyvault-secrets-provider

-3. The add-on creates a user-assigned managed identity, `azureKeyvaultSecretsProvider`, to access Azure resources. The following example uses this identity to connect to the key vault that stores the secrets, but you can also use other [identity access methods][identity-access-methods]. Take note of the identity's `clientId` in the output.

- ```json

- az keyvault create -n <keyvault-name> -g myResourceGroup -l eastus2 --enable-rbac-authorization

- az keyvault update -n <keyvault-name> -g myResourceGroup -l eastus2 --enable-rbac-authorization

- az keyvault secret set --vault-name <keyvault-name> -n ExampleSecret --value MyAKSExampleSecret

- > The **Containers** category includes both Kubernetes applications and standalone container images. This walkthrough is specific to Kubernetes applications. If you find that the steps to deploy an offer differ in some way, you're most likely trying to deploy a container image-based offer instead of a Kubernetes application-based offer.

-description: Deploy a Java application with Open Liberty/WebSphere Liberty on an Azure Kubernetes Service (AKS) cluster

-# Deploy a Java application with Open Liberty or WebSphere Liberty on an Azure Kubernetes Service (AKS) cluster

-* Run your Java, Java EE, Jakarta EE, or MicroProfile application on the Open Liberty or WebSphere Liberty runtime.

-* Build the application Docker image using Open Liberty or WebSphere Liberty container images.

-* Deploy the containerized application to an AKS cluster using the Open Liberty Operator or WebSphere Liberty Operator.

-The Open Liberty Operator simplifies the deployment and management of applications running on Kubernetes clusters. With the Open Liberty or WebSphere Liberty Operator, you can also perform more advanced operations, such as gathering traces and dumps.

-For more information on Open Liberty, see [the Open Liberty project page](https://openliberty.io/). For more information on IBM WebSphere Liberty, see [the WebSphere Liberty product page](https://www.ibm.com/cloud/websphere-liberty).

-This article uses the Azure Marketplace offer for Open/WebSphere Liberty to accelerate your journey to AKS. The offer automatically provisions a number of Azure resources including an Azure Container Registry (ACR) instance, an AKS cluster, an Azure App Gateway Ingress Controller (AGIC) instance, the Liberty Operator, and optionally a container image including Liberty and your application. To see the offer, visit the [Azure portal](https://aka.ms/liberty-aks). If you prefer manual step-by-step guidance for running Liberty on AKS that doesn't utilize the automation enabled by the offer, see [Manually deploy a Java application with Open Liberty or WebSphere Liberty on an Azure Kubernetes Service (AKS) cluster](/azure/developer/java/ee/howto-deploy-java-liberty-app-manual).

-This article is intended to help you quickly get to deployment. Before going to production, you should explore [Tuning Liberty](https://www.ibm.com/docs/was-liberty/base?topic=tuning-liberty).

-* You can use Azure Cloud Shell or a local terminal.

-* This article requires at least version 2.31.0 of Azure CLI. If using Azure Cloud Shell, the latest version is already installed.

-> You can also execute this guidance from the [Azure Cloud Shell](/azure/cloud-shell/quickstart). This approach has all the prerequisite tools pre-installed, with the exception of Docker.

-> :::image type="icon" source="~/reusable-content/ce-skilling/azure/media/cloud-shell/launch-cloud-shell-button.png" alt-text="Button to launch the Azure Cloud Shell." border="false" link="https://shell.azure.com":::

-* If running the commands in this guide locally (instead of Azure Cloud Shell):

- * Prepare a local machine with Unix-like operating system installed (for example, Ubuntu, Azure Linux, macOS, Windows Subsystem for Linux).

- * Install a Java SE implementation, version 17 or later. (for example, [Eclipse Open J9](https://www.eclipse.org/openj9/)).

- * Install [Maven](https://maven.apache.org/download.cgi) 3.5.0 or higher.

- * Install [Docker](https://docs.docker.com/get-docker/) for your OS.

-* Make sure you're assigned either the `Owner` role or the `Contributor` and `User Access Administrator` roles in the subscription. You can verify it by following steps in [List role assignments for a user or group](../role-based-access-control/role-assignments-list-portal.md#list-role-assignments-for-a-user-or-group).

-## Create a Liberty on AKS deployment using the portal

-The following steps guide you to create a Liberty runtime on AKS. After completing these steps, you have an Azure Container Registry and an Azure Kubernetes Service cluster for deploying your containerized application.

-1. Visit the [Azure portal](https://portal.azure.com/). In the search box at the top of the page, type *IBM WebSphere Liberty and Open Liberty on Azure Kubernetes Service*. When the suggestions start appearing, select the one and only match that appears in the **Marketplace** section. If you prefer, you can go directly to the offer with this shortcut link: [https://aka.ms/liberty-aks](https://aka.ms/liberty-aks).

-1. In the **Basics** pane:

- 1. Create a new resource group. Because resource groups must be unique within a subscription, pick a unique name. An easy way to have unique names is to use a combination of your initials, today's date, and some identifier. For example, `ejb0913-java-liberty-project-rg`.

- 1. Select *East US* as **Region**.

-

- Create environment variables in your shell for the resource group names for the cluster and the database.

-

- ### [Bash](#tab/in-bash)

-

- ```bash

- export RESOURCE_GROUP_NAME=<your-resource-group-name>

- export DB_RESOURCE_GROUP_NAME=<your-resource-group-name>

- ```

-

- ### [PowerShell](#tab/in-powershell)

-

- ```powershell

- $Env:RESOURCE_GROUP_NAME="<your-resource-group-name>"

- $Env:DB_RESOURCE_GROUP_NAME="<your-resource-group-name>"

- ```

-

-

-1. Select **Next**, enter the **AKS** pane. This pane allows you to select an existing AKS cluster and Azure Container Registry (ACR), instead of causing the deployment to create a new one, if desired. This capability enables you to use the sidecar pattern, as shown in the [Azure architecture center](/azure/architecture/patterns/sidecar). You can also adjust the settings for the size and number of the virtual machines in the AKS node pool. The remaining values do not need to be changed from their default values.

-1. Select **Next**, enter the **Load Balancing** pane. Next to **Connect to Azure Application Gateway?** select **Yes**. This section lets you customize the following deployment options.

- 1. You can customize the **virtual network** and **subnet** into which the deployment will place the resources. The remaining values do not need to be changed from their default values.

- 1. You can provide the **TLS/SSL certificate** presented by the Azure Application Gateway. Leave the values at the default to cause the offer to generate a self-signed certificate. Don't go to production using a self-signed certificate. For more information about self-signed certificates, see [Create a self-signed public certificate to authenticate your application](../active-directory/develop/howto-create-self-signed-certificate.md).

- 1. You can select **Enable cookie based affinity**, also known as sticky sessions. We want sticky sessions enabled for this article, so ensure this option is selected.

-1. Select **Next**, enter the **Operator and application** pane. This quickstart uses all defaults in this pane. However, it lets you customize the following deployment options.

- 1. You can deploy WebSphere Liberty Operator by selecting **Yes** for option **IBM supported?**. Leaving the default **No** deploys Open Liberty Operator.

- 1. You can deploy an application for your selected Operator by selecting **Yes** for option **Deploy an application?**. Leaving the default **No** doesn't deploy any application.

-1. Select **Review + create** to validate your selected options. In the ***Review + create** pane, when you see **Create** light up after validation pass, select **Create**. The deployment may take up to 20 minutes. While you wait for the deployment to complete, you can follow the steps in the section [Create an Azure SQL Database](#create-an-azure-sql-database). After completing that section, come back here and continue.

-If you navigated away from the **Deployment is in progress** page, the following steps will show you how to get back to that page. If you're still on the page that shows **Your deployment is complete**, you can skip to the third step.

-1. In the upper left of any portal page, select the hamburger menu and select **Resource groups**.

-1. In the box with the text **Filter for any field**, enter the first few characters of the resource group you created previously. If you followed the recommended convention, enter your initials, then select the appropriate resource group.

-1. In the list of resources in the resource group, select the resource with **Type** of **Container registry**.

-1. In the navigation pane, under **Settings** select **Access keys**.

-1. Save aside the values for **Login server**, **Registry name**, **Username**, and **password**. You may use the copy icon at the right of each field to copy the value of that field to the system clipboard.

-1. Navigate again to the resource group into which you deployed the resources.

-1. Select the bottom-most deployment in the list. The **Deployment name** will match the publisher ID of the offer. It will contain the string `ibm`.

-1. In the left pane, select **Outputs**.

-1. Using the same copy technique as with the preceding values, save aside the values for the following outputs:

- * `appDeploymentTemplateYaml` if you select **No** to **Deploy an application?** when deploying the Marketplace offer; or `appDeploymentYaml` if you select **yes** to **Deploy an application?**.

- Paste the value of `appDeploymentTemplateYaml` or `appDeploymentYaml` into a Bash shell, append `| grep secretName`, and execute. This command will output the Ingress TLS secret name, such as `- secretName: secret785e2c`. Save aside the value for `secretName` from the output.

- Paste the quoted string in `appDeploymentTemplateYaml` or `appDeploymentYaml` into a PowerShell, append `| ForEach-Object { [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($_)) } | Select-String "secretName"`, and execute. This command will output the Ingress TLS secret name, such as `- secretName: secret785e2c`. Save aside the value for `secretName` from the output.

-

-These values will be used later in this article. Note that several other useful commands are listed in the outputs.

-> [!NOTE]

-> You may notice a similar output named **appDeploymentYaml**. The difference between output *appDeploymentTemplateYaml* and *appDeploymentYaml* is:

-> * *appDeploymentTemplateYaml* is populated if and only if the deployment **does not include** an application.

-> * *appDeploymentYaml* is populated if and only if the deployment **does include** an application.

-## Create an Azure SQL Database

-Now that the database and AKS cluster have been created, we can proceed to preparing AKS to host your Open Liberty application.

-Clone the sample code for this guide. The sample is on [GitHub](https://github.com/Azure-Samples/open-liberty-on-aks).

-There are a few samples in the repository. We'll use *java-app/*. Here's the file structure of the application.

-If you see a message about being in "detached HEAD" state, this message is safe to ignore. It just means you have checked out a tag.

-In the *aks* directory, there are five deployment files. *db-secret.xml* is used to create [Kubernetes Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) with DB connection credentials. The file *openlibertyapplication-agic.yaml* is used in this quickstart to deploy the Open Liberty Application with AGIC. If desired, you can deploy the application without AGIC using the file *openlibertyapplication.yaml*. Use the file *webspherelibertyapplication-agic.yaml* or *webspherelibertyapplication.yaml* to deploy the WebSphere Liberty Application with or without AGIC if you deployed WebSphere Liberty Operator in section [Create a Liberty on AKS deployment using the portal](#create-a-liberty-on-aks-deployment-using-the-portal).

-In the *docker* directory, there are two files to create the application image with either Open Liberty or WebSphere Liberty. These files are *Dockerfile* and *Dockerfile-wlp*, respectively. You use the file *Dockerfile* to build the application image with Open Liberty in this quickstart. Similarly, use the file *Dockerfile-wlp* to build the application image with WebSphere Liberty if you deployed WebSphere Liberty Operator in section [Create a Liberty on AKS deployment using the portal](#create-a-liberty-on-aks-deployment-using-the-portal).

-In directory *liberty/config*, the *server.xml* file is used to configure the DB connection for the Open Liberty and WebSphere Liberty cluster.

-Now that you've gathered the necessary properties, you can build the application. The POM file for the project reads many variables from the environment. As part of the Maven build, these variables are used to populate values in the YAML files located in *src/main/aks*. You can do something similar for your application outside Maven if you prefer.

-# The following variables will be used for deployment file generation into target.

-# The following variables will be used for deployment file generation into target.

-$Env:LOGIN_SERVER=<Azure-Container-Registry-Login-Server-URL>

-$Env:REGISTRY_NAME=<Azure-Container-Registry-name>

-$Env:USER_NAME=<Azure-Container-Registry-username>

-$Env:PASSWORD=<Azure-Container-Registry-password>

-$Env:DB_SERVER_NAME=<server-name>.database.windows.net

-$Env:DB_NAME=<database-name>

-$Env:DB_USER=<server-admin-login>@<server-name>

-$Env:DB_PASSWORD=<server-admin-password>

-$Env:INGRESS_TLS_SECRET=<ingress-TLS-secret-name>

-You can now run and test the project locally before deploying to Azure. For convenience, we use the `liberty-maven-plugin`. To learn more about the `liberty-maven-plugin`, see [Building a web application with Maven](https://openliberty.io/guides/maven-intro.html). For your application, you can do something similar using any other mechanism, such as your local IDE. You can also consider using the `liberty:devc` option intended for development with containers. You can read more about `liberty:devc` in the [Liberty docs](https://openliberty.io/docs/latest/development-mode.html#_container_support_for_dev_mode).

-1. Start the application using `liberty:run`. `liberty:run` will also use the environment variables defined in the previous step.

-1. Verify the application works as expected. You should see a message similar to `[INFO] [AUDIT] CWWKZ0003I: The application javaee-cafe updated in 1.930 seconds.` in the command output if successful. Go to `http://localhost:9080/` in your browser and verify the application is accessible and all functions are working.

-1. Press <kbd>Ctrl</kbd>+<kbd>C</kbd> to stop.

-### Build image for AKS deployment

-You can now run the `docker build` command to build the image.

-You can now use the following steps to test the Docker image locally before deploying to Azure.

-1. Run the image using the following command. Note we're using the environment variables defined previously.

-1. Once the container starts, go to `http://localhost:9080/` in your browser to access the application.

-1. Press <kbd>Ctrl</kbd>+<kbd>C</kbd> to stop.

-### Upload image to ACR

-Upload the built image to the ACR created in the offer.

- Paste the value of **cmdToConnectToCluster** into a Bash shell and execute.

-1. Apply the DB secret.

- You'll see the output `secret/db-secret-sql created`.

-1. Apply the deployment file.

- You should see output similar to the following example to indicate that all the pods are running:

-1. Verify the results.

- 1. Get **ADDRESS** of the Ingress resource deployed with the application

- Copy the value of **ADDRESS** from the output, this is the frontend public IP address of the deployed Azure Application Gateway.

- 1. Go to `https://<ADDRESS>` to test the application. For your convenience, this shell command will create an environment variable whose value you can paste straight into the browser.

- If the web page doesn't render correctly or returns a `502 Bad Gateway` error, that's because the app is still starting in the background. Wait for a few minutes and then try again.

-To avoid Azure charges, you should clean up unnecessary resources. When the cluster is no longer needed, use the [az group delete](/cli/azure/group#az-group-delete) command to remove the resource group, container service, container registry, and all related resources.

-* [Open Liberty Server Configuration](https://openliberty.io/docs/ref/config/)

-Quarkus dev mode enables live reload with background compilation. If you modify any aspect of your app source code and refresh your browser, you can see the changes. If there are any issues with compilation or deployment, an error page lets you know. Quarkus dev mode listens for a debugger on port 5005. If you want to wait for the debugger to attach before running, pass `-Dsuspend` on the command line. If you donΓÇÖt want the debugger at all, you can use `-Ddebug=false`.

-1. If you have successfully created the image, then it should now be in your local machineΓÇÖs Docker repository. You can verify the image creation by using the following command:

-When you're performing [canary upgrade for Istio](./istio-upgrade.md), you need create a separate ConfigMap for the new revision in the `aks-istio-system` namespace **before initiating the canary upgrade**. This way the configuration is available when the new revision's control plane is deployed on cluster. For example, if you're upgrading the mesh from asm-1-18 to asm-1-19, you need to copy changes over from `istio-shared-configmap-asm-1-18` to create a new ConfigMap called `istio-shared-configmap-asm-1-19` in the `aks-istio-system` namespace.

-| **Field** | **Supported** |

-|--||

-| proxyListenPort | false |

-| proxyInboundListenPort | false |

-| proxyHttpPort | false |

-| connectTimeout | false |

-| tcpKeepAlive | false |

-| defaultConfig | true |

-| outboundTrafficPolicy | true |

-| extensionProviders | true |

-| defaultProvideres | true |

-| accessLogFile | true |

-| accessLogFormat | true |

-| accessLogEncoding | true |

-| enableTracing | true |

-| enableEnvoyAccessLogService | true |

-| disableEnvoyListenerLog | true |

-| trustDomain | false |

-| trustDomainAliases | false |

-| caCertificates | false |

-| defaultServiceExportTo | false |

-| defaultVirtualServiceExportTo | false |

-| defaultDestinationRuleExportTo | false |

-| localityLbSetting | false |

-| dnsRefreshRate | false |

-| h2UpgradePolicy | false |

-| enablePrometheusMerge | true |

-| discoverySelectors | true |

-| pathNormalization | false |

-| defaultHttpRetryPolicy | false |

-| serviceSettings | false |

-| meshMTLS | false |

-| tlsDefaults | false |

-## Minor version upgrade

-Istio add-on allows upgrading the minor version using [canary upgrade process][istio-canary-upstream]. When an upgrade is initiated, the control plane of the new (canary) revision is deployed alongside the old (stable) revision's control plane. You can then manually roll over data plane workloads while using monitoring tools to track the health of workloads during this process. If you don't observe any issues with the health of your workloads, you can complete the upgrade so that only the new revision remains on the cluster. Else, you can roll back to the previous revision of Istio.

-If the cluster is currently using a supported minor version of Istio, upgrades are only allowed one minor version at a time. If the cluster is using an unsupported version of Istio, you must upgrade to the lowest supported minor version of Istio for that Kubernetes version. After that, upgrades can again be done one minor version at a time.

-Azure Kubernetes Service (AKS) is a managed Kubernetes service that lets you quickly deploy and manage clusters. In this quickstart, you learn to:

-## Create a resource group

-An [Azure resource group][azure-resource-group] is a logical group in which Azure resources are deployed and managed. When you create a resource group, you're prompted to specify a location. This location is the storage location of your resource group metadata and where your resources run in Azure if you don't specify another region during resource creation.

-The following example creates a resource group named *myResourceGroup* in the *eastus* location.

-Create a resource group using the [az group create][az-group-create] command.

- ```azurecli

- az group create --name myResourceGroup --location eastus

- ```

- The following sample output resembles successful creation of the resource group:

- ```output

- {

- "id": "/subscriptions/<guid>/resourceGroups/myResourceGroup",

- "location": "eastus",

- "managedBy": null,

- "name": "myResourceGroup",

- "properties": {

- "provisioningState": "Succeeded"

- },

- "tags": null

- }

- ```

-To create an AKS cluster, use the [az aks create][az-aks-create] command. The following example creates a cluster named *myAKSCluster* with one node and enables a system-assigned managed identity.

- ```azurecli

- az aks create \

- --resource-group myResourceGroup \

- --name myAKSCluster \

- --enable-managed-identity \

- --node-count 1 \

- --generate-ssh-keys

- ```

- After a few minutes, the command completes and returns JSON-formatted information about the cluster.

- > [!NOTE]

- > When you create a new cluster, AKS automatically creates a second resource group to store the AKS resources. For more information, see [Why are two resource groups created with AKS?](../faq.md#why-are-two-resource-groups-created-with-aks)

-To manage a Kubernetes cluster, use the Kubernetes command-line client, [kubectl][kubectl]. `kubectl` is already installed if you use Azure Cloud Shell. To install `kubectl` locally, call the [az aks install-cli][az-aks-install-cli] command.

- ```azurecli

- az aks get-credentials --resource-group myResourceGroup --name myAKSCluster

- ```azurecli

- The following sample output shows the single node created in the previous steps. Make sure the node status is *Ready*.

- ```output

- NAME STATUS ROLES AGE VERSION

- aks-nodepool1-11853318-vmss000000 Ready agent 2m26s v1.27.7

- ```

-1. Deploy the application using the [kubectl apply][kubectl-apply] command and specify the name of your YAML manifest.

- ```azurecli

- The following sample output shows the deployments and

- ```output

- deployment.apps/rabbitmq created

- service/rabbitmq created

- deployment.apps/order-service created

- service/order-service created

- deployment.apps/product-service created

- service/product-service created

- deployment.apps/store-front created

- service/store-front created

- ```

-When the application runs, a Kubernetes service exposes the application front end to the internet. This process can take a few minutes to complete.

-1. Check the status of the deployed pods using the [kubectl get pods][kubectl-get] command. Make sure all pods are `Running` before proceeding.

- ```console

- kubectl get pods

- ```

-1. Check for a public IP address for the store-front application. Monitor progress using the [kubectl get service][kubectl-get] command with the `--watch` argument.

- ```azurecli

- kubectl get service store-front --watch

- ```

- The **EXTERNAL-IP** output for the `store-front` service initially shows as *pending*:

- ```output

- NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE

- store-front LoadBalancer 10.0.100.10 <pending> 80:30025/TCP 4h4m

- ```

-1. Once the **EXTERNAL-IP** address changes from *pending* to an actual public IP address, use `CTRL-C` to stop the `kubectl` watch process.

- The following sample output shows a valid public IP address assigned to the service:

- ```output

- NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE

- store-front LoadBalancer 10.0.100.10 20.62.159.19 80:30025/TCP 4h5m

- ```

-1. Open a web browser to the external IP address of your service to see the Azure Store app in action.

- :::image type="content" source="media/quick-kubernetes-deploy-cli/aks-store-application.png" alt-text="Screenshot of AKS Store sample application." lightbox="media/quick-kubernetes-deploy-cli/aks-store-application.png":::

-If you don't plan on going through the [AKS tutorial][aks-tutorial], clean up unnecessary resources to avoid Azure charges. Call the [az group delete][az-group-delete] command to remove the resource group, container service, and all related resources.

- ```azurecli

- az group delete --name myResourceGroup --yes --no-wait

- ```

- > [!NOTE]

- > The AKS cluster was created with a system-assigned managed identity, which is the default identity option used in this quickstart. The platform manages this identity so you don't need to manually remove it.

-1. Check the status of the deployed pods using the [kubectl get pods][kubectl-get] command. Make all pods are `Running` before proceeding.

-[kubernetes-service]: ../concepts-network.md#services

-[kubernetes-service]: ../concepts-network.md#services

-[kubernetes-service]: ../concepts-network.md#services

-Sometimes deployment or other processes running within pods on nodes in a cluster can run for periods of time longer than expected due to various reasons. While it's important to allow those processes to gracefully terminate when they're no longer needed, there are circumstances where you need to release control of node pools and clusters with long running operations using an *abort* command.

-## Disable OutboundNAT for Windows (Preview)

-* If you're using Kubernetes version 1.25 or older, you need to [update your deployment configuration][upgrade-kubernetes].

-* You need to install or update `aks-preview` and register the feature flag.

- 1. Install or update `aks-preview` using the [`az extension add`][az-extension-add] or [`az extension update`][az-extension-update] command.

- ```azurecli-interactive

- # Install aks-preview

- az extension add --name aks-preview

- # Update aks-preview

- az extension update --name aks-preview

- ```

- 2. Register the feature flag using the [`az feature register`][az-feature-register] command.

- ```azurecli-interactive

- az feature register --namespace Microsoft.ContainerService --name DisableWindowsOutboundNATPreview

- ```

- 3. Check the registration status using the [`az feature list`][az-feature-list] command.

- ```azurecli-interactive

- az feature list -o table --query "[?contains(name, 'Microsoft.ContainerService/DisableWindowsOutboundNATPreview')].{Name:name,State:properties.state}"

- ```

- 4. Refresh the registration of the `Microsoft.ContainerService` resource provider using the [`az provider register`][az-provider-register] command.

- ```azurecli-interactive

- az provider register --namespace Microsoft.ContainerService

- ```

-The Kubernetes community releases minor versions roughly every three months. Recently, the Kubernetes community has [increased the support window for each version from nine months to one year](https://kubernetes.io/blog/2020/08/31/kubernetes-1-19-feature-one-year-support/), starting with version 1.19.

- 1.17.7

- 1.17.8

-Aim to run the latest patch release of the minor version you're running. For example, if your production cluster is on **`1.17.7`**, **`1.17.8`** is the latest available patch version available for the *1.17* series. You should upgrade to **`1.17.8`** as soon as possible to ensure your cluster is fully patched and supported.

-| 1.25 | Aug 2022 | Oct 2022 | Dec 2022 | Jan 14, 2024 | Until 1.29 GA |

-| 1.25 | Azure policy 1.0.1<br>Metrics-Server 0.6.3<br>KEDA 2.9.3<br>Open Service Mesh 1.2.3<br>Core DNS V1.9.4<br>Overlay VPA 0.11.0<br>Azure-Keyvault-SecretsProvider 1.4.1<br>Application Gateway Ingress Controller (AGIC) 1.5.3<br>Image Cleaner v1.1.1<br>Azure Workload identity v1.0.0<br>MDC Defender 1.0.56<br>Azure Active Directory Pod Identity 1.8.13.6<br>GitOps 1.7.0<br>KMS 0.5.0| Cilium 1.12.8<br>CNI 1.4.44<br> Cluster Autoscaler 1.8.5.3<br> | OS Image Ubuntu 18.04 Cgroups V1 <br>ContainerD 1.7<br>Azure Linux 2.0<br>Cgroups V1<br>ContainerD 1.6<br>| Ubuntu 22.04 by default with cgroupv2 and Overlay VPA 0.13.0 |CgroupsV2 - If you deploy Java applications with the JDK, prefer to use JDK 11.0.16 and later or JDK 15 and later, which fully support cgroup v2

-AKS allows you to create a cluster without specifying the exact patch version. When you create a cluster without designating a patch, the cluster runs the minor version's latest GA patch. For example, if you create a cluster with **`1.21`**, your cluster runs **`1.21.7`**, which is the latest GA patch version of *1.21*. If you want to upgrade your patch version in the same minor version, please use [auto-upgrade](./auto-upgrade-cluster.md).

- "currentKubernetesVersion": "1.21.7",

-The supported window of Kubernetes versions on AKS is known as "N-2": (N (Latest release) - 2 (minor versions)), and ".letter" is representative of patch versions.

-For example, if AKS introduces *1.17.a* today, support is provided for the following versions:

-New minor version | Supported Version List

-1.17.a | 1.17.a, 1.17.b, 1.16.c, 1.16.d, 1.15.e, 1.15.f

-When a new minor version is introduced, the oldest minor version and patch releases supported are deprecated and removed. For example, let's say the current supported version list is:

-1.17.a

-1.17.b

-1.16.c

-1.16.d

-1.15.e

-1.15.f

-When AKS releases 1.18.\*, all the 1.15.\* versions go out of support 30 days later.

-1.17.8, 1.17.7, 1.16.10, 1.16.9

-If AKS releases `1.17.9` and `1.16.11`, the oldest patch versions are deprecated and removed, and the supported version list becomes:

-1.17.*9*, 1.17.*8*, 1.16.*11*, 1.16.*10*

-Platform support policy applies to clusters in an n-3 version (where n is the latest supported AKS GA minor version), before the cluster drops to n-4. For example, Kubernetes v1.25 is considered platform support when v1.28 is the latest GA version. However, during the v1.29 GA release, v1.25 will then auto-upgrade to v1.26. If you are a running an n-2 version, the moment it becomes n-3 it also becomes deprecated, and you enter into the platform support policy.

-For example, if your *kube-apiserver* is at *1.17*, then you can use versions *1.16* to *1.18* of `kubectl` with that *kube-apiserver*.

-When you deploy an AKS cluster with Azure portal, Azure CLI, Azure PowerShell, the cluster defaults to the N-1 minor version and latest patch. For example, if AKS supports *1.17.a*, *1.17.b*, *1.16.c*, *1.16.d*, *1.15.e*, and *1.15.f*, the default version selected is *1.16.c*.

-* If the oldest supported AKS version is *1.15.a* and you're on *1.14.b* or older, you're outside of support.

-* When you successfully upgrade from *1.14.b* to *1.15.a* or higher, you're back within our support policies.

-* *1.12.x* -> *1.13.x*: allowed.

-* *1.13.x* -> *1.14.x*: allowed.

-* *1.12.x* -> *1.14.x*: not allowed.

-To upgrade from *1.12.x* -> *1.14.x*:

-1. Upgrade from *1.12.x* -> *1.13.x*.

-2. Upgrade from *1.13.x* -> *1.14.x*.

-Skipping multiple versions can only be done when upgrading from an unsupported version back into the minimum supported version. For example, you can upgrade from an unsupported *1.10.x* to a supported *1.15.x* if *1.15* is the minimum supported minor version.

-When performing an upgrade from an _unsupported version_ that skips two or more minor versions, the upgrade is performed without any guarantee of functionality and is excluded from the service-level agreements and limited warranty. If your version is significantly out of date, we recommend that you re-create the cluster.

-No. You aren't allowed to add node pools of the deprecated version to your cluster. You can add node pools of a new version, but it might require you to update the control plane first.

-> At this time, using Calico network policies with Windows nodes is available on new clusters by using Kubernetes version 1.20 or later with Calico 3.17.2 and requires that you use Azure CNI networking. Windows nodes on AKS clusters with Calico enabled also have [Direct Server Return (DSR)][dsr] enabled by default.

-Windows Server 2022 is the default OS for Kubernetes version 1.25 and later. Windows Server 2019 will retire after Kubernetes version 1.32 reaches end of life (EOL). Windows Server 2022 will retire after Kubernetes version 1.34 reaches its end of life (EOL). For more information, see [AKS release notes][aks-release-notes]. To stay up to date on the latest Windows Server OS versions and learn more about our roadmap of what's planned for support on AKS, see our [AKS public roadmap](https://github.com/azure/aks/projects/1).

-Windows pods on AKS clusters that use the Calico Network Policy enable [Floating IP][dsr] by default.

-| [Managed domain certificates](configure-custom-domain.md?tabs=managed#domain-certificate-options) | Developer, Basic, Standard, Premium | ✔️ | ✔️ | ❌ |

-|Implicit | Returns access token immediately without an extra authorization code exchange step | Clients that can't protect a secret or token such as mobile apps and single-page apps<br/><br/>Generally not recommended because of inherent risks of returning access token in HTTP redirect without confirmation that it's received by client |

-## Next steps

-For more information about using OAuth 2.0 and API Management, see [Protect a web API backend in Azure API Management using OAuth 2.0 authorization with Microsoft Entra ID](api-management-howto-protect-backend-with-aad.md).

-See all [upcoming breaking changes and feature retirements](overview.md).

-You can have one managed portal and multiple self-hosted portals. The content of all portals is stored in the same API Management service, so they will be identical. If you want to differentiate portals' appearance and functionality, you can self-host them with your own custom widgets that dynamically customize pages on runtime, for example based on the URL.

-If your API Management service is in an internal VNet, your developer portal is only accessible from within the network. The management endpoint's host name must resolve to the internal VIP of the service from the machine you use to access the portal's administrative interface. Make sure the management endpoint is registered in the DNS. In case of misconfiguration, you will see an error: `Unable to start the portal. See if settings are specified correctly in the configuration (...)`.

-The call failure may also be caused by an TLS/SSL certificate, which is assigned to a custom domain and is not trusted by the browser. As a mitigation, you can remove the management endpoint custom domain. API Management will fall back to the default endpoint with a trusted certificate.

-If your local version of the developer portal cannot save or retrieve information from the storage account or API Management instance, the SAS tokens may have expired. You can fix that by generating new tokens. For instructions, refer to the tutorial to [self-host the developer portal](developer-portal-self-host.md#step-2-configure-json-files-static-website-and-cors-settings).

-description: Learn how to configure local metrics and logs for Azure API Management self-hosted gateway on a Kubernetes cluster

-Below is a sample YAML configuration for deploying StatsD and Prometheus to the Kubernetes cluster where a self-hosted gateway is deployed. It also creates a [Service](https://kubernetes.io/docs/concepts/services-networking/service/) for each. The self-hosted gateway will publish metrics to the StatsD Service. We will access the Prometheus dashboard via its Service.

-Save the configurations to a file named `metrics.yaml` and use the below command to deploy everything to the cluster:

-Once the deployment finishes, run the below command to check the Pods are running. Note that your pod name will be different.

-Run the below command to check the Services are running. Take a note of the `CLUSTER-IP` and `PORT` of the StatsD Service, we would need it later. You can visit the Prometheus dashboard using its `EXTERNAL-IP` and `PORT`.

-Now that both StatsD and Prometheus have been deployed, we can update the configurations of the self-hosted gateway to start emitting metrics through StatsD. The feature can be enabled or disabled using the `telemetry.metrics.local` key in the ConfigMap of the self-hosted gateway Deployment with additional options. Below is a breakdown of the available options:

-| telemetry.metrics.local.statsd.sampling | n/a | Specifies metrics sampling rate. Value can be between 0 and 1. e.g., `0.5`|

-Here is a sample configuration:

-Now we have everything deployed and configured, the self-hosted gateway should report metrics via StatsD. Prometheus will pick up the metrics from StatsD. Go to the Prometheus dashboard using the `EXTERNAL-IP` and `PORT` of the Prometheus Service.

-| request_backend_duration_seconds | Number of milliseconds spent on overall backend IO (connecting, sending and receiving bytes) |

-| request_client_duration_seconds | Number of milliseconds spent on overall client IO (connecting, sending and receiving bytes) |

-The self-hosted gateway also supports a number of protocols including `localsyslog`, `rfc5424`, and `journal`. The below table summarizes all the options supported.

-| telemetry.logs.local.localsyslog.endpoint | n/a | Specifies localsyslog endpoint. |

-| telemetry.logs.local.localsyslog.facility | n/a | Specifies localsyslog [facility code](https://en.wikipedia.org/wiki/Syslog#Facility). e.g., `7`

-| telemetry.logs.local.rfc5424.facility | n/a | Specifies facility code per [rfc5424](https://tools.ietf.org/html/rfc5424). e.g., `7` |

-Here is a sample configuration of local logging:

-### Using local syslog logs on Azure Kubernetes Service (AKS)

-When configuring to use localsyslog on Azure Kubernetes Service, you can choose two ways to explore the logs:

-* To learn more about the [observability capabilities of the Azure API Management gateways](observability.md).

-* To learn more about the self-hosted gateway, see [Azure API Management self-hosted gateway overview](self-hosted-gateway-overview.md)

-* Learn about [configuring and persisting logs in the cloud](how-to-configure-cloud-metrics-logs.md)

-8. Depending on your scenario, you might need to change the [service type](../aks/concepts-network.md#services).

-| gateway.name | Id of the self-hosted gateway resource. | Yes, when using Microsoft Entra authentication | N/A | v2.3+ |

-| telemetry.logs.local.localsyslog.endpoint | localsyslog endpoint. | Yes if `telemetry.logs.local` is set to `localsyslog`; otherwise no. | N/A | v2.0+ |

-| client-application-ids | Contains a list of acceptable client application IDs. If multiple `application-id` elements are present, then each value is tried until either all are exhausted (in which case validation fails) or until one succeeds. If a client application ID isn't provided, one or more `audience` claims should be specified. Policy expressions aren't allowed. | No |

-This guide provides key concepts and instructions for containerization of Windows apps in App Service. If you've never used Azure App Service, follow the [custom container quickstart](quickstart-custom-container.md) and [tutorial](tutorial-custom-container.md) first.

-This guide provides key concepts and instructions for containerization of Linux apps in App Service. If you've never used Azure App Service, follow the [custom container quickstart](quickstart-custom-container.md) and [tutorial](tutorial-custom-container.md) first. There's also a [multi-container app quickstart](quickstart-multi-container.md) and [tutorial](tutorial-multi-container-app.md). For sidecar containers (preview), see [Tutorial: Configure a sidecar container for custom container in Azure App Service (preview)](tutorial-custom-container-sidecar.md).

-Use the following steps to configure your web app to pull from ACR using managed identity. The steps use system-assigned managed identity, but you can use user-assigned managed identity as well.

- Replace `<app-name>` with the name you used in the previous step. The output of the command (filtered by the `--query` and `--output` arguments) is the service principal ID of the assigned identity, which you use shortly.

-1. (Optional) If your app uses a [user-assigned managed identity](overview-managed-identity.md#add-a-user-assigned-identity), make sure this is configured on the web app and then set the `acrUserManagedIdentityID` property to specify its client ID:

-To connect and pull from a registry inside a virtual network or on-premises, your app must integrate with a virtual network. This is also needed for Azure Container Registry with private endpoint. When your network and DNS resolution is configured, you enable the routing of the image pull through the virtual network by configuring the `vnetImagePullEnabled` site setting:

-Navigate to `https://<app-name>.scm.azurewebsites.net/DebugConsole` and select the **LogFiles** folder to see the individual log files. To download the entire **LogFiles** directory, select the **Download** icon to the left of the directory name. You can also access this folder using an FTP client.

-By default all Windows Containers deployed in Azure App Service have a memory limit configured. The following table lists the default settings per App Service Plan SKU.

-The value is defined in MB and must be less and equal to the total physical memory of the host. For example, in an App Service plan with 8GB RAM, the cumulative total of `WEBSITE_MEMORY_LIMIT_MB` for all the apps must not exceed 8 GB. Information on how much memory is available for each pricing tier can be found in [App Service pricing](https://azure.microsoft.com/pricing/details/app-service/windows/), in the **Premium v3 service plan** section.

-App Service considers a container to be successfully started when the container starts and responds to an HTTP ping. The health ping request contains the header `User-Agent= "App Service Hyper-V Container Availability Check"`. If the container starts but doesn't respond to a ping after a certain amount of time, App Service logs an event in the Docker log, saying that the container didn't start.

-Further troubleshooting information is available at the Azure App Service OSS blog: [Enabling SSH on Linux Web App for Containers](https://azureossd.github.io/2022/04/27/2022-Enabling-SSH-on-Linux-Web-App-for-Containers/https://docsupdatetracker.net/index.html#troubleshooting)

- - ${WEBAPP_STORAGE_HOME}/site/wwwroot:/var/www/html

- - ${WEBAPP_STORAGE_HOME}/phpmyadmin:/var/www/phpmyadmin

- - ${WEBAPP_STORAGE_HOME}/LogFiles:/var/log

-1. Configure your Web App details, corresponding Azure resources will be created if not exist.

-> Your .jar application must be named `app.jar` for App Service to identify and run your application. The Maven Plugin (mentioned above) will automatically rename your application for you during deployment. If you don't wish to rename your JAR to *app.jar*, you can upload a shell script with the command to run your .jar app. Paste the absolute path to this script in the [Startup File](./faq-app-service-linux.yml) textbox in the Configuration section of the portal. The startup script doesn't run from the directory into which it's placed. Therefore, always use absolute paths to reference files in your startup script (for example: `java -jar /home/myapp/myapp.jar`).

-To deploy .ear files, [use FTP](deploy-ftp.md). Your .ear application will be deployed to the context root defined in your application's configuration. For example, if the context root of your app is `<context-root>myapp</context-root>`, then you can browse the site at the `/myapp` path: `http://my-app-name.azurewebsites.net/myapp`. If you want your web app to be served in the root path, ensure that your app sets the context root to the root path: `<context-root>/</context-root>`. For more information, see [Setting the context root of a web application](https://docs.jboss.org/jbossas/guides/webguide/r2/en/html/ch06.html).

-All Java runtimes on Azure App Service come with the JDK Flight Recorder for profiling Java workloads. You can use this to record JVM, system, and application events and troubleshoot problems in your applications.

-Azure Blob Storage logging for Linux based App Services can only be configured using [Azure Monitor](./troubleshoot-diagnostic-logs.md#send-logs-to-azure-monitor)

-Set the app setting `JAVA_COPY_ALL` to `true` to copy your app contents to the local worker from the shared file system. This helps address file-locking issues.

-Turn on support for web sockets in the Azure portal in the **Application settings** for the application. You'll need to restart the application for the setting to take effect.

-Set up app authentication in the Azure portal with the **Authentication and Authorization** option. From there, you can enable authentication using Microsoft Entra ID or social sign-ins like Facebook, Google, or GitHub. Azure portal configuration only works when configuring a single authentication provider. For more information, see [Configure your App Service app to use Microsoft Entra sign-in](configure-authentication-provider-aad.md) and the related articles for other identity providers. If you need to enable multiple sign-in providers, follow the instructions in the [customize sign-ins and sign-outs](configure-authentication-customize-sign-in-out.md) article.

-Your Tomcat application can access the user's claims directly from the servlet by casting the Principal object to a Map object. The Map object will map each claim type to a collection of the claims for that type. In the code below, `request` is an instance of `HttpServletRequest`.

-Follow the instructions in the [Secure a custom DNS name with an TLS/SSL binding in Azure App Service](configure-ssl-bindings.md) to upload an existing TLS/SSL certificate and bind it to your application's domain name. By default your application will still allow HTTP connections-follow the specific steps in the tutorial to enforce TLS/SSL.

-By default, any public or private certificates [uploaded to App Service Linux](configure-ssl-certificate.md) will be loaded into the respective Java Key Stores as the container starts. After uploading your certificate, you'll need to restart your App Service for it to be loaded into the Java Key Store. Public certificates are loaded into the Key Store at `$JRE_HOME/lib/security/cacerts`, and private certificates are stored in `$JRE_HOME/lib/security/client.jks`.

-More configuration may be necessary for encrypting your JDBC connection with certificates in the Java Key Store. Refer to the documentation for your chosen JDBC driver.

-To enable Application Insights from the Azure portal, go to **Application Insights** on the left-side menu and select **Turn on Application Insights**. By default, a new application insights resource of the same name as your Web App will be used. You can choose to use an existing application insights resource, or change the name. Select **Apply** at the bottom

-To enable via the Azure CLI, you'll need to create an Application Insights resource and set a couple app settings on the Azure portal to connect Application Insights to your web app.

-2. Create an Application Insights resource using the CLI command below. Replace the placeholders with your desired resource name and group.

-2. Download the Java agent from NewRelic, it will have a file name similar to *newrelic-java-x.x.x.zip*.

-3. Copy your license key, you'll need it to configure the agent later.

-2. Download the Java agent from NewRelic, it will have a file name similar to *newrelic-java-x.x.x.zip*.

-2. Download the Java agent from the AppDynamics website, the file name will be similar to *AppServerAgent-x.x.x.xxxxx.zip*

-2. Download the Java agent from the AppDynamics website, the file name will be similar to *AppServerAgent-x.x.x.xxxxx.zip*

- This connection string is accessible to our application as an environment variable named `CUSTOMCONNSTR_<your-string-name>`. For example, the connection string we created above will be named `CUSTOMCONNSTR_exampledb`.

-These instructions apply to all database connections. You'll need to fill placeholders with your chosen database's driver class name and JAR file. Provided is a table with class names and driver downloads for common databases.

-For Windows sites, create a file named `startup.cmd` or `startup.ps1` in the `wwwroot` directory. This will automatically be executed before the Tomcat server starts.

- # In case previous config could not be completed or a new config should be forcefully installed

- # In case previous config could not be completed or a new config should be forcefully installed

-Finally, you'll place the driver JARs in the Tomcat classpath and restart your App Service. Ensure that the JDBC driver files are available to the Tomcat classloader by placing them in the */home/site/lib* directory. In the [Cloud Shell](https://shell.azure.com), run `az webapp deploy --type=lib` for each driver JAR:

-These instructions apply to all database connections. You'll need to fill placeholders with your chosen database's driver class name and JAR file. Provided is a table with class names and driver downloads for common databases.

-Adding a shared, server-level data source will require you to edit Tomcat's server.xml. First, upload a [startup script](./faq-app-service-linux.yml) and set the path to the script in **Configuration** > **Startup Command**. You can upload the startup script using [FTP](deploy-ftp.md).

-An example xsl file is provided below. The example xsl file adds a new connector node to the Tomcat server.xml.

-2. Create an XML module definition file for the JDBC driver. The example shown below is a module definition for PostgreSQL.

-1. Put your JBoss CLI commands into a file named `jboss-cli-commands.cli`. The JBoss commands must add the module and register it as a data source. The example below shows the JBoss CLI commands for PostgreSQL.

-1. Create a startup script, `startup_script.sh` that calls the JBoss CLI commands. The example below shows how to call your `jboss-cli-commands.cli`. Later you'll configure App Service to run this script when the container starts.

-To confirm that the datasource was added to the JBoss server, SSH into your webapp and run `$JBOSS_HOME/bin/jboss-cli.sh --connect`. Once you're connected to JBoss run the `/subsystem=datasources:read-resource` to print a list of the data sources.

-App Service allows users to choose the major version of the JVM, such as Java 8 or Java 11, and the patch version, such as 1.8.0_232 or 11.0.5. You can also choose to have the patch version automatically updated as new minor versions become available. In most cases, production sites should use pinned patch JVM versions. This will prevent unanticipated outages during a patch version autoupdate. All Java web apps use 64-bit JVMs, this isn't configurable.

-If you're using Tomcat, you can choose to pin the patch version of Tomcat. On Windows, you can pin the patch versions of the JVM and Tomcat independently. On Linux, you can pin the patch version of Tomcat; the patch version of the JVM will also be pinned but isn't separately configurable.

-If you choose to pin the minor version, you'll need to periodically update the JVM minor version on the site. To ensure that your application runs on the newer minor version, create a staging slot and increment the minor version on the staging site. Once you have confirmed the application runs correctly on the new minor version, you can swap the staging and production slots.

-App Service supports clustering for JBoss EAP versions 7.4.1 and greater. To enable clustering, your web app must be [integrated with a virtual network](overview-vnet-integration.md). When the web app is integrated with a virtual network, the web app will restart and JBoss EAP will automatically start up with a clustered configuration. The JBoss EAP instances will communicate over the subnet specified in the virtual network integration, using the ports shown in the `WEBSITES_PRIVATE_PORTS` environment variable at runtime. You can disable clustering by creating an app setting named `WEBSITE_DISABLE_CLUSTERING` with any value.

-> If you're enabling your virtual network integration with an ARM template, you'll need to manually set the property `vnetPrivatePorts` to a value of `2`. If you enable virtual network integration from the CLI or Portal, this property will be set for you automatically.

-When clustering is enabled, the JBoss EAP instances use the FILE_PING JGroups discovery protocol to discover new instances and persist the cluster information like the cluster members, their identifiers, and their IP addresses. On App Service, these files are under `/home/clusterinfo/`. The first EAP instance to start will obtain read/write permissions on the cluster membership file. Other instances will read the file, find the primary node, and coordinate with that node to be included in the cluster and added to the file.

-Java developers can customize the server settings, troubleshoot issues, and deploy applications to Tomcat with confidence if they know about the server.xml file and configuration details of Tomcat. Some of these may be:

-* Customizing Tomcat configuration: By understanding the server.xml file and Tomcat's configuration details, developers can fine-tune the server settings to match the needs of their applications.

-* Debugging: When an application is deployed on a Tomcat server, developers need to know the server configuration to debug any issues that may arise. This includes checking the server logs, examining the configuration files, and identifying any errors that might be occurring.

-* Troubleshooting Tomcat issues: Inevitably, Java developers will encounter issues with their Tomcat server, such as performance problems or configuration errors. By understanding the server.xml file and Tomcat's configuration details, developers can quickly diagnose and troubleshoot these issues, which can save time and effort.

-As you provision an App Service with Tomcat to host your Java workload (a WAR file or a JAR file), there are certain settings that you get out of the box for Tomcat configuration. You can refer to the [Official Apache Tomcat Documentation](https://tomcat.apache.org/) for detailed information, including the default configuration for Tomcat Web Server.

-Please note that the latest versions of Tomcat will have these server.xml. (8.5.58 and 9.0.38 onward). Older versions of Tomcat do not use transforms and may have different behavior as a result.

-Following are example CLI commands that you may use to alter the values of conectionTimeout, maxThreads, or maxConnections:

-* errorReportValveClass uses our custom error report valve

- - name: 'Checkout Github Action'

-The custom domain suffix defines a root domain that can be used by the App Service Environment. In the public variation of Azure App Service, the default root domain for all web apps is *azurewebsites.net*. For ILB App Service Environments, the default root domain is *appserviceenvironment.net*. However, since an ILB App Service Environment is internal to a customer's virtual network, customers can use a root domain in addition to the default one that makes sense for use within a company's internal virtual network. For example, a hypothetical Contoso Corporation might use a default root domain of *internal.contoso.com* for apps that are intended to only be resolvable and accessible within Contoso's virtual network. An app in this virtual network could be reached by accessing *APP-NAME.internal.contoso.com*.

-If the certificate used for the custom domain suffix contains a Subject Alternate Name (SAN) entry for **.scm.CUSTOM-DOMAIN*, the scm site will then also be reachable from *APP-NAME.scm.CUSTOM-DOMAIN*. You can only access scm over custom domain using basic authentication. Single sign-on is only possible with the default root domain.

-The connection to the custom domain suffix endpoint will need to use Server Name Indication (SNI) for TLS based connections.

-A [managed identity](../../active-directory/managed-identities-azure-resources/overview.md) is used to authenticate against the Azure Key Vault where the SSL/TLS certificate is stored. If you don't currently have a managed identity associated with your App Service Environment, you'll need to configure one.

-You can use either a system assigned or user assigned managed identity. To create a user assigned managed identity, see [manage user-assigned managed identities](../../active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities.md). If you'd like to use a system assigned managed identity and don't already have one assigned to your App Service Environment, the Custom domain suffix portal experience will guide you through the creation process. Alternatively, you can go to the **Identity** page for your App Service Environment and configure and assign your managed identities there.

-To assign a user assigned managed identity, select "Add", and find the managed identity you want to use.

-If you use a vault access policy, the managed identity will need at a minimum the "Get" secrets permission for the key vault.

-If you choose to use Azure role-based access control to manage access to your key vault, you'll need to give your managed identity at a minimum the "Key Vault Secrets User" role.

-The certificate for custom domain suffix must be stored in an Azure Key Vault. The certificate must be uploaded in .PFX format. Certificates in .PEM format are not supported at this time. App Service Environment will use the managed identity you selected to get the certificate. The key vault must be publicly accessible, however you can lock down the key vault by restricting access to your App Service Environment's outbound IPs. You can find your App Service Environment's outbound IPs under "Default outbound addresses" on the **IP addresses** page for your App Service Environment. You'll need to add both IPs to your key vault's firewall rules. For more information on key vault network security and firewall rules, see [Configure Azure Key Vault firewalls and virtual networks](../../key-vault/general/network-security.md#key-vault-firewall-enabled-ipv4-addresses-and-rangesstatic-ips). The key vault also must not have any [private endpoint connections](../../private-link/private-endpoint-overview.md).

-Your certificate must be a wildcard certificate for the selected custom domain name. For example, *internal.contoso.com* would need a certificate covering **.internal.contoso.com*. If the certificate used by the custom domain suffix contains a Subject Alternate Name (SAN) entry for scm, for example **.scm.internal.contoso.com*, the scm site will also available using the custom domain suffix.

-If you rotate your certificate in Azure Key Vault, the App Service Environment will pick up the change within 24 hours.

-1. Select the managed identity you've defined for your App Service Environment. You can use either a system assigned or user assigned managed identity. You'll be able to configure your managed identity if you haven't done so already directly from the custom domain suffix page using the "Add identity" option in the managed identity selection box.

-1. Select "Save" at the top of the page. To see the latest configuration updates, you may need to refresh your browser page.

-1. It will take a few minutes for the custom domain suffix configuration to be set. Select "Refresh" at the top of the page to check the status. The banner will update with the latest progress. Once complete, the banner will state that the custom domain suffix is configured.

-To configure a custom domain suffix for your App Service Environment using an Azure Resource Manager template, you'll need to include the below properties. Ensure that you've met the [prerequisites](#prerequisites) and that your managed identity and certificate are accessible and have the appropriate permissions for the Azure Key Vault.

-You'll need to configure the managed identity and ensure it exists before assigning it in your template. For more information on managed identities, see the [managed identity overview](../../active-directory/managed-identities-azure-resources/overview.md).

-1. The **provisioningState** under **customDnsSuffixConfiguration** will provide a status on the configuration update.

-To access your apps in your App Service Environment using your custom domain suffix, you'll need to either configure your own DNS server or configure DNS in an Azure private DNS zone for your custom domain.

-1. Optionally create a zone for scm sub-domain with a * A record that points to the inbound IP address used by your App Service Environment

-1. Create an Azure DNS private zone named for your custom domain. In the example below, the custom domain is *internal.contoso.com*.

-However, just like apps running on the public multi-tenant service, you can also configure custom host names for individual apps, and then configure unique SNI [TLS/SSL certificate bindings for individual apps](./overview-certificates.md#tls-settings).

-If your permissions or network settings for your managed identity, key vault, or App Service Environment aren't set appropriately, you won't be able to configure a custom domain suffix, and you'll receive an error similar to the example below. Review the [prerequisites](#prerequisites) to ensure you've set the needed permissions. You'll also see a similar error message if the App Service platform detects that your certificate is degraded or expired.

-If your migration included a custom domain suffix, the domain appeared in the **Essentials** section of the **Overview** page of the portal for App Service Environment v1/v2, but it no longer appears there in App Service Environment v3. Instead, for App Service Environment v3, go to the **Custom domain suffix** page to confirm that your custom domain suffix is configured correctly. You can also remove the configuration if you no longer need it or configure one if you didn't have one previously.

-# Use the side-by-side migration feature to migrate App Service Environment v2 to App Service Environment v3 (Preview)

-> The migration feature described in this article is used for side-by-side (different subnet) automated migration of App Service Environment v2 to App Service Environment v3 and is currently **in preview**.

-You have two App Service Environments at this stage in the migration process. Your apps are running in both environments. You need to update any dependent resources to use the new IP inbound address for your new App Service Environment v3. For internal facing (ILB) App Service Environments, you need to update your private DNS zones to point to the new inbound IP address. You should account for both the old and new inbound IP at this point. You can remove the dependencies on the previous IP address after you complete the next step.

-> [!IMPORTANT]

-> During the preview, the new inbound IP might be returned incorrectly due to a known bug. Open a support ticket to receive the correct IP addresses for your App Service Environment v3.

->

-## 11. Redirect customer traffic and complete migration

-This step is your opportunity to test and validate your new App Service Environment v3. Your App Service Environment v2 front ends are still running, but the backing compute is an App Service Environment v3. If you're able to access your apps without issues, that means you're ready to complete the migration.

-Once you confirm your apps are working as expected, you can redirect customer traffic to your new App Service Environment v3 front ends by running the following command. This command also deletes your old environment.

-If you find any issues or decide at this point that you no longer want to proceed with the migration, contact support to revert the migration. Don't run the above command if you need to revert the migration. For more information, see [Revert migration](side-by-side-migrate.md#redirect-customer-traffic-and-complete-migration).

-If your migration includes a custom domain suffix, for App Service Environment v3, the custom domain isn't displayed in the **Essentials** section of the **Overview** page of the portal as it is for App Service Environment v1/v2. Instead, for App Service Environment v3, go to the **Custom domain suffix** page where you can confirm your custom domain suffix is configured correctly.

-# Migration to App Service Environment v3 using the side-by-side migration feature (Preview)

-> The migration feature described in this article is used for side-by-side (different subnet) automated migration of App Service Environment v2 to App Service Environment v3 and is currently **in preview**.

-You receive the new inbound IP address once migration is complete but before you make the [DNS change to redirect customer traffic to your new App Service Environment v3](#redirect-customer-traffic-and-complete-migration). You don't get the inbound IP at this point in the process because there are dependencies on App Service Environment v3 resources that get created during the migration step. You have a chance to update any resources that are dependent on the new inbound IP before you redirect traffic to your new App Service Environment v3.

-When this step completes, your application traffic is still going to your old App Service Environment front ends and the inbound IP that was assigned to it. However, you also now have an App Service Environment v3 with all of your apps.

-The new inbound IP address is given so that you can set up new endpoints with services like [Traffic Manager](../../traffic-manager/traffic-manager-overview.md) or [Azure Front Door](../../frontdoor/front-door-overview.md) and update any of your private DNS zones. Don't move on to the next step until you account for these changes. There's downtime if you don't update dependent resources with the new inbound IP. **It's your responsibility to update any and all resources that are impacted by the IP address change associated with the new App Service Environment v3. Don't move on to the next step until you've made all required updates.**

-### Redirect customer traffic and complete migration

-The final step is to redirect traffic to your new App Service Environment v3 and complete the migration. The platform does this change for you, but only when you initiate it. Before you do this step, you should review your new App Service Environment v3 and perform any needed testing to validate that it's functioning as intended. Your App Service Environment v2 front ends are still running, but the backing compute is an App Service Environment v3. If you're able to access your apps without issues, that means you're ready to complete the migration.

-|**3**|**Testing and troubleshooting**|Upgrading using one of the automated migration features requires a 3-6 hour service window. If you use the side-by-side migration feature, you have the opportunity to [test and validate your App Service Environment v3](side-by-side-migrate.md#redirect-customer-traffic-and-complete-migration) before completing the upgrade. Support teams are monitoring upgrades to ensure success. If you have a support plan and you need technical help, create a [support request](https://portal.azure.com/#blade/Microsoft_Azure_Support/HelpAndSupportBlade/newsupportrequest).|

-Those who receive notifications include account administrators, service administrators, and coadministrators. Contributors, readers, or other roles won't directly receive notifications, unless they opt in to receive notification emails, using [Service Health Alerts](../service-health/alerts-activity-log-service-notifications-portal.md).

-\*\* Upcoming versions

-\* Alpine 3.16 is the last supported Alpine distribution in App Service. It's recommended to pin to a version to avoid switching over to Ubuntu automatically. Make sure you test and switch to Java offering supported by Ubuntu based distributions when possible. -->

-Major version updates will be provided through new runtime options in Azure App Service. Customers update to these newer versions of Java by configuring their App Service deployment and are responsible for testing and ensuring the major update meets their needs.

-Patches and fixes for major security vulnerabilities will be released as soon as they become available in Microsoft builds of the OpenJDK. A "major" vulnerability is defined by a base score of 9.0 or higher on the [NIST Common Vulnerability Scoring System, version 2](https://nvd.nist.gov/vuln-metrics/cvss).

-Tomcat 8.0 has reached [End of Life as of September 30, 2018](https://tomcat.apache.org/tomcat-80-eol.html). While the runtime is still available on Azure App Service, Azure won't apply security updates to Tomcat 8.0. If possible, migrate your applications to Tomcat 8.5 or 9.0. Both Tomcat 8.5 and 9.0 are available on Azure App Service. For more information, see the [official Tomcat site](https://tomcat.apache.org/whichversion.html).

-| **Python** | linuxFxVersion="PYTHON&#124;3.7" |

-| `WEBSITE_DYNAMIC_CACHE` | Due to network file shared nature to allow access for multiple instances, the dynamic cache improves performance by caching the recently accessed files locally on an instance. Cache is invalidated when file is modified. The cache location is `%SYSTEMDRIVE%\local\DynamicCache` (same `%SYSTEMDRIVE%\local` quota is applied). By default, full content caching is enabled (set to `1`), which includes both file content and directory/file metadata (timestamps, size, directory content). To conserve local disk use, set to `2` to cache only directory/file metadata (timestamps, size, directory content). To turn off caching, set to `0`. |

- 1. **SQLAzure** is selected by default as the database engine. Azure SQL Database is a fully managed platform as a service (PaaS) database engine that's always running on the latest stable version of the SQL Server.

-> [!IMPORTANT]

-> Application Gateway IPv6 support is now generally available. Updates to the Azure portal for IPv6 support are currently being deployed across all regions and will be fully available within the next few weeks. In the meantime to use the portal to create an IPv6 Application Gateway continue using the [preview registration process](/azure/azure-resource-manager/management/preview-features?tabs=azure-portal) in the Azure portal to opt in for **Allow Application Gateway IPv6 Access**.

-The IPv6 Application Gateway preview is available to all public cloud regions where Application Gateway v2 SKU is supported. It's also available in [Microsoft Azure operated by 21Vianet](https://www.azure.cn/) and [Azure Government](https://azure.microsoft.com/overview/clouds/government/)

-Use the [preview registration process](/azure/azure-resource-manager/management/preview-features?tabs=azure-portal) in the Azure portal to **Allow Application Gateway IPv6 Access**. This is required until the feature is completely rolled out in the Azure portal.

- > For the Application Gateway v2 SKU, there must be a **Public** frontend IP configuration. A private IPv6 frontend IP configuration (Only ILB mode) is currently not supported for the IPv6 Application Gateway preview.

- > IPv6 Application Gateway (preview) supports up to 4 frontend IP addresses: two IPv4 addresses (Public and Private) and two IPv6 addresses (Public and Private)

-#### [For a single VM](#tab/singlevm)

-#### [For multiple VMs](#tab/multiplevms)

-description: Enable Azure RBAC to authorize access to your Azure App Configuration instance

-Besides using Hash-based Message Authentication Code (HMAC), Azure App Configuration supports using Microsoft Entra ID to authorize requests to App Configuration instances. Microsoft Entra ID allows you to use Azure role-based access control (Azure RBAC) to grant permissions to a security principal. A security principal may be a user, a [managed identity](../active-directory/managed-identities-azure-resources/overview.md) or an [application service principal](../active-directory/develop/app-objects-and-service-principals.md). To learn more about roles and role assignments, see [Understanding different roles](../role-based-access-control/overview.md).

-1. The security principal's identity is authenticated and an OAuth 2.0 token is returned. The resource name to request a token is `https://login.microsoftonline.com/{tenantID}` where `{tenantID}` matches the Microsoft Entra tenant ID to which the service principal belongs.

-The authentication step requires that an application request contains an OAuth 2.0 access token at runtime. If an application is running within an Azure entity, such as an Azure Functions app, an Azure Web App, or an Azure VM, it can use a managed identity to access the resources. To learn how to authenticate requests made by a managed identity to Azure App Configuration, see [Authenticate access to Azure App Configuration resources with Microsoft Entra ID and managed identities for Azure Resources](howto-integrate-azure-managed-service-identity.md).

-description: Learn how to disable access key authentication for an Azure App Configuration instance

-Disabling access key authentication will delete all access keys. If any running applications are using access keys for authentication they will begin to fail once access key authentication is disabled. Enabling access key authentication again will generate a new set of access keys and any applications attempting to use the old access keys will still fail.

-> Additionally, it is recommended to read the [limitations](#limitations) section below to verify the limitations won't affect the intended usage of the resource.

-2. Locate the **Access keys** setting under **Settings**.

- :::image type="content" border="true" source="./media/access-keys-blade.png" alt-text="Screenshot showing how to access an Azure App Configuration resources access key blade":::

-To verify that access key authentication is no longer permitted, a request can be made to list the access keys for the Azure App Configuration resource. If access key authentication is disabled there will be no access keys and the list operation will return an empty list.

-2. Locate the **Access keys** setting under **Settings**.

- :::image type="content" border="true" source="./media/access-keys-blade.png" alt-text="Screenshot showing how to access an Azure App Configuration resources access key blade":::

-If access key authentication is disabled then an empty list will be returned.

-Be careful to restrict assignment of these roles only to those who require the ability to create an App Configuration resource or update its properties. Use the principle of least privilege to ensure that users have the fewest permissions that they need to accomplish their tasks. For more information about managing access with Azure RBAC, see [Best practices for Azure RBAC](../role-based-access-control/best-practices.md).

-## Limitations

-The capability to disable access key authentication has the following limitation:

-### ARM template access

-When access key authentication is disabled, the capability to read/write key-values in an [ARM template](./quickstart-resource-manager.md) will be disabled as well. This is because access to the Microsoft.AppConfiguration/configurationStores/keyValues resource used in ARM templates requires an Azure Resource Manager role, such as contributor or owner. When access key authentication is disabled, access to the resource requires one of the Azure App Configuration [data plane roles](concept-enable-rbac.md), therefore ARM template access is rejected.

-1. Create a new Java file named *MessageProperties.java*, and add the following lines:

- public class MessageProperties {

- private final MessageProperties properties;

- public HelloController(MessageProperties properties) {

-1. In the main application Java file, add `@EnableConfigurationProperties` to enable the *MessageProperties.java* configuration properties class to take effect and register it with the Spring container.

- @EnableConfigurationProperties(MessageProperties.class)

-This quickstart describes how to :

-Accessing key-value data inside an ARM template requires an Azure Resource Manager role, such as contributor or owner. Access via one of the Azure App Configuration [data plane roles](concept-enable-rbac.md) currently is not supported.

-> [!NOTE]

-> Key-value data access inside an ARM template is disabled if access key authentication is disabled. For more information, see [disable access key authentication](./howto-disable-access-key-authentication.md#limitations).

-description: Use Azure CLI script - Importing configuration to Azure App Configuration

-Additional App Configuration CLI script samples can be found in the [Azure App Configuration CLI samples](../cli-samples.md).

-**Image tag**:`v1.28.0_2024-03-12`|

-|`arcdata` Azure CLI extension version|1.5.12 ([Download](https://aka.ms/az-cli-arcdata-ext))|

-|Arc-enabled Kubernetes helm chart extension version|1.28.0|

-In addition, Arc resource bridge requires connectivity to the Arc-enabled Kubernetes endpoints shown here.

-For issues encountered with Arc resource bridge, collect logs for further investigation using the Azure CLI [`az arcappliance logs`](/cli/azure/arcappliance/logs) command. This command needs to be run from the same management machine that was used to run commands to deploy the Arc resource bridge. If you are using a different machine to collect logs, you need to run the `az arcappliance get-credentials` command first before collecting logs.

-If you are unsure of your appliance VM IP, there is also the option to use the kubeconfig. You can retrieve the kubeconfig by running the [get-credentials command](/cli/azure/arcappliance) then run the logs command.

-If the resource bridge is offline, this is typically due to a networking change in the infrastructure, environment or cluster that stops the appliance VM from being able to communicate with its counterpart Azure resource. If you are unable to determine what changed, you can reboot the appliance VM, collect logs and submit a support ticket for further investigation.

-### Private Link is unsupported

-### .local not supported

-While trying to deploy Arc Resource Bridge, a "KVA timeout error" might appear. The "KVA timeout error" is a generic error that can be the result of a variety of network misconfigurations that involve the management machine, Appliance VM, or Control Plane IP not having communication with each other, to the internet, or required URLs. This communication failure is often due to issues with DNS resolution, proxy settings, network configuration, or internet access.

-For clarity, "management machine" refers to the machine where deployment CLI commands are being run. "Appliance VM" is the VM that hosts Arc resource bridge. "Control Plane IP" is the IP of the control plane for the Kubernetes management cluster in the Appliance VM.

-1. The management machine must be able to communicate with the Appliance VM IP and Control Plane IP. Ping the Control Plane IP and Appliance VM IP from the management machine and verify there is a response from both IPs.

-### `az arcappliance prepare` failure

-The `arcappliance` extension for Azure CLI enables a [prepare](/cli/azure/arcappliance/prepare) command, which enables you to download an OVA template to your vSphere environment. This OVA file is used to deploy the Azure Arc resource bridge. The `az arcappliance prepare` command uses the vSphere SDK and can result in the following error:

-```azurecli

-$ az arcappliance prepare vmware --config-file <path to config>

-Error: Error in reading OVA file: failed to parse ovf: strconv.ParseInt: parsing "3670409216":

-value out of range.

-```

-This error occurs when you run the Azure CLI commands in a 32-bit context, which is the default behavior. The vSphere SDK only supports running in a 64-bit context. The specific error returned from the vSphere SDK is `Unable to import ova of size 6GB using govc`. To resolve the error, install and use Azure CLI 64-bit.

-When you deploy the resource bridge on VMware vCenter, if you have been using the same template to deploy and delete the appliance multiple times, you might encounter the following error:

-`Appliance cluster deployment failed with error:

-Error: An error occurred during host configuration`

-To resolve this issue, delete the existing template manually. Then run [`az arcappliance prepare`](/cli/azure/arcappliance/prepare) to download a new template for deployment.

-When deploying the resource bridge on VMware vCenter, you specify the folder in which the template and VM will be created. The folder must be VM and template folder type. Other types of folder, such as storage folders, network folders, or host and cluster folders, can't be used by the resource bridge deployment.

-Billing for Extended Security Updates (ESUs) is impacted by three factors:

-Billing is monthly. Decrementing, deactivating, or deleting a license will result in charges for up to five more calendar days from the time of decrement, deactivation, or deletion. Reduction in billing isn't immediate. This is an Azure-billed service and can be used to decrement a customer's Microsoft Azure Consumption Commitment (MACC) and be eligible for Azure Consumption Discount (ACD).

-Licenses that are provisioned after the End of Support (EOS) date of October 10, 2023 are charged a back bill for the time elapsed since the EOS date. For example, an ESU license provisioned in December 2023 will be back-billed for October and November upon provisioning. Enrolling late in WS2012 ESUs makes you eligible for all the critical security patches up to that point. The back-billing charge reflects the value of these critical security patches.

-If you deactivate and then later reactivate a license, you'll be billed for the window during which the license was deactivated. It isn't possible to evade charges by deactivating a license before a critical security patch and reactivating it shortly before.

-There are some scenarios in which you may be eligible to receive Extended Security Updates patches at no additional cost. Two of these scenarios supported by Azure Arc are (1) [Dev/Test (Visual Studio)](/azure/devtest/offer/overview-what-is-devtest-offer-visual-studio) and (2) [Disaster Recovery (Entitled benefit DR instances from Software Assurance](https://www.microsoft.com/en-us/licensing/licensing-programs/software-assurance-by-benefits) or subscription only). Both of these scenarios require the customer is already using Windows Server 2012/R2 ESUs enabled by Azure Arc for billable, production machines.

->

-> You needed a regular production license to start with, and you'll be billed only for the production cores.

->

- - [Configure Windows machines](https://ms.portal.azure.com/#view/Microsoft_Azure_Policy/CreateAssignmentBladeV2/assignMode~/0/definitionId/%2Fproviders%2FMicrosoft.Authorization%2FpolicySetDefinitions%2F9575b8b7-78ab-4281-b53b-d3c1ace2260b)

- - [Configure Linux machines](https://ms.portal.azure.com/#view/Microsoft_Azure_Policy/InitiativeDetailBlade/id/%2Fproviders%2FMicrosoft.Authorization%2FpolicySetDefinitions%2F118f04da-0375-44d1-84e3-0fd9e1849403/scopes~/%5B%22%2Fsubscriptions%2Fd05f0ffc-ace9-4dfc-bd6d-d9ec0a212d16%22%2C%22%2Fsubscriptions%2F6e967edb-425b-4a33-ae98-f1d2c509dda3%22%2C%22%2Fsubscriptions%2F5f2bd58b-42fc-41da-bf41-58690c193aeb%22%2C%22%2Fsubscriptions%2F2dad32d6-b188-49e6-9437-ca1d51cec4dd%22%5D)

-You'll also need to attest to the number of associated cores (broken down by the number of 2-core and 16-core packs).

-An additional scenario (scenario 1, below) is a candidate for VM/Virtual core licensing when the WS2012 VMs are running on a newer Windows Server host (that is, Windows Server 2016 or later).

-Each WS2012 ESU license can cover up to and including 10,000 cores. If you need ESUs for more than 10,000 cores, split the total number of cores across multiple licenses. Additionally, only 800 licenses can be created in a single resource group. Use additional resource groups if you need to create more than 800 license resources.

-In all cases, you're required to attest to conformance with SA or SPLA. There is no exception for these requirements. Software Assurance or an equivalent Server Subscription is required for you to purchase Extended Security Updates on-premises and in hosted environments. You will be able to purchase Extended Security Updates from Enterprise Agreement (EA), Enterprise Subscription Agreement (EAS), a Server & Cloud Enrollment (SCE), and Enrollment for Education Solutions (EES). On Azure, you do not need Software Assurance to get free Extended Security Updates, but Software Assurance or Server Subscription is required to take advantage of the Azure Hybrid Benefit.

->

-> This feature only applies to Windows Server 2022 and later. It was released in the [Cumulative Update of 10/10/2023](https://support.microsoft.com/en-us/topic/october-10-2023-kb5031364-os-build-20348-2031-7f1d69e7-c468-4566-887a-1902af791bbc).

->

-To uninstall Azure Arc Setup, follow these steps:

-1. In the Server Manager, navigate to the **Remove Roles and Features Wizard**. (See [Remove roles, role services, and features by using the remove Roles and Features Wizard](/windows-server/administration/server-manager/install-or-uninstall-roles-role-services-or-features#remove-roles-role-services-and-features-by-using-the-remove-roles-and-features-wizard) for more information.)

-> [!NOTE]

-> Uninstalling Azure Arc Setup does not uninstall the Azure Connected Machine agent from the machine. For instructions on uninstalling the agent, see [Managing and maintaining the Connected Machine agent](manage-agent.md).

->

- > [!NOTE]

- > Only Azure Arc-enabled servers in the same subscription and region as your Private Link Scope is shown.

- :::image type="content" source="./media/private-link-security/select-servers-private-link-scope.png" lightbox="./media/private-link-security/select-servers-private-link-scope.png" alt-text="Selecting Azure Arc resources" border="true":::

-## Flush data (preview)

-## Next steps

-## Next steps

-If preserving the data in the cache isn't a requirement, consider flushing the data prior to scaling. Flushing the cache helps the scaling operation complete more quickly so the new capacity is available sooner. See more details on [how to initiate flush operation.](cache-administration.md#flush-data-preview)

- > - If your cache data export to Firewall-enabled storage accounts fails, refer to [How to export if I have firewall enabled on my storage account?](#how-to-export-if-i-have-firewall-enabled-on-my-storage-account)

-### How to export if I have firewall enabled on my storage account?

-For firewall enabled storage accounts, we need to check ΓÇ£Allow Azure services on the trusted services list to access this storage accountΓÇ¥ then, use managed identity (System/User assigned) and provision Storage Blob Data Contributor RBAC role for that object ID.

-More information here - [Managed identity for storage accounts - Azure Cache for Redis](cache-managed-identity.md)

- > [!NOTE]

- > This functionality does not yet support authentication for connecting to a cache instance.

- >

-2. Open the **Access control (IAM)** from the Resource menu. Then, select **Add**, and **Add role assignment**.

-3. Search for the **Storage Blob Data Contributor** on the Role pane. Select it and **Next**.

-4. Select the **Members** tab. Under **Assign access to** select **Managed Identity**, and select on **Select members**. A sidebar pops up next to the working pane.

-5. Use the drop-down under **Managed Identity** to choose either a **User-assigned managed identity** or a **System-assigned managed identity**. If you have many managed identities, you can search by name. Choose the managed identities you want and then **Select**. Then, **Review + assign** to confirm.

-6. You can confirm if the identity has been assigned successfully by checking your storage account's role assignments under **Storage Blob Data Contributor**.

-2. Change the **Authentication Method** to **Managed Identity** and select the storage account you configured earlier in the article. select **Save**.

-3. Data persistence backups can now be saved to the storage account using managed identity authentication.

-2. If importing data, choose the blob storage location that holds your chosen RDB file. If exporting data, type your desired blob name prefix and storage container. In both situations, you must use the storage account you've configured for managed identity access.

-3. Under **Authentication Method**, choose **Managed Identity** and select **Import** or **Export**, respectively.

-## Next steps

-> When using private link, you cannot export or import data to a to a storage account that has firewall enabled unless you're using [managed identity to autenticate to the storage account](cache-managed-identity.md).

-> For more information, see [How to export if I have firewall enabled on my storage account?](cache-how-to-import-export-data.md#how-to-export-if-i-have-firewall-enabled-on-my-storage-account)

-The Bicep file used in this quickstart is from [Azure Quickstart Templates](https://azure.microsoft.com/resources/templates/redis-cache/).

-description: You can use Redis modules with your Azure Cache for Redis instances.

-Only the `RediSearch` and `RedisJSON` modules can be used concurrently with [active geo-replication](cache-how-to-active-geo-replication.md).

-Additionally, **RediSearch** can function as a secondary index, expanding your cache beyond a key-value structure and offering more sophisticated queries.

-**RediSearch** also includes functionality to perform [vector similarity queries](https://redis.io/docs/stack/search/reference/vectors/) such as K-nearest neighbor (KNN) search. This feature allows Azure Cache for Redis to be used as a vector database, which is useful in AI use-cases like [semantic answer engines or any other application that requires the comparison of embeddings vectors](https://redis.com/blog/rediscover-redis-for-vector-similarity-search/) generated by machine learning models.

-You can use **RediSearch** is used in a wide variety of additional use-cases, including real-time inventory, enterprise search, and in indexing external databases. [For more information, see the RediSearch documentation page](https://redis.io/docs/stack/search/).

-For more information, see [RedisBloom](https://redis.io/docs/stack/bloom/).

-For more information, see [RedisTimeSeries](https://redis.io/docs/stack/timeseries/).

-For more information, see [RedisJSON](https://redis.io/docs/stack/json/).

-## Next steps

-# Tutorial: Get started with Azure Functions triggers in Azure Cache for Redis

-1. If you haven't installed the Azure Functions extension for VS Code, search for **Azure Functions** on the **EXTENSIONS** menu, and then select **Install**. If you don't have the C# extension installed, install it, too.

-1. Create a new local folder on your computer to hold the project that you're building. This tutorial uses _RedisAzureFunctionDemo_ as an example.

- - **.NET 6.0 LTS** as the .NET runtime.

-You need to install `Microsoft.Azure.WebJobs.Extensions.Redis`, the NuGet package for the Redis extension that allows Redis keyspace notifications to be used as triggers in Azure Functions.

-dotnet add package Microsoft.Azure.WebJobs.Extensions.Redis --version 0.3.1-preview

-## Set up the example code

-1. Go back to VS Code and add a file called _RedisFunctions.cs_ to the project.

- using StackExchange.Redis;

- namespace Microsoft.Azure.WebJobs.Extensions.Redis.Samples

- public static class RedisSamples

- public const string connectionString = "redisConnectionString";

- [FunctionName(nameof(PubSubTrigger))]

- public static void PubSubTrigger(

- [RedisPubSubTrigger(connectionString, "pubsubTest")] string message,

- ILogger logger)

- {

- logger.LogInformation(message);

- }

- [FunctionName(nameof(KeyspaceTrigger))]

- public static void KeyspaceTrigger(

- [RedisPubSubTrigger(connectionString, "__keyspace@0__:keyspaceTest")] string message,

- ILogger logger)

- {

- logger.LogInformation(message);

- }

- [FunctionName(nameof(KeyeventTrigger))]

- public static void KeyeventTrigger(

- [RedisPubSubTrigger(connectionString, "__keyevent@0__:del")] string message,

- ILogger logger)

- {

- logger.LogInformation(message);

- }

- [FunctionName(nameof(ListTrigger))]

- public static void ListTrigger(

- [RedisListTrigger(connectionString, "listTest")] string entry,

- ILogger logger)

- {

- logger.LogInformation(entry);

- }

- [FunctionName(nameof(StreamTrigger))]

- public static void StreamTrigger(

- [RedisStreamTrigger(connectionString, "streamTest")] string entry,

- ILogger logger)

- {

- logger.LogInformation(entry);

- }