+| {OIDC:IdToken} | The `id token` query string parameter. | N/A |

+The validation techniques we've used in step 1, step 2 and step 3 aren't applicable for all scenarios. If your business rules are too complex to be defined at claim declaration level, you can configure a [Validation Technical](validation-technical-profile.md), and then call it from a [Self-Asserted Technical Profile](self-asserted-technical-profile.md).

+Support for containers is currently available with Document Intelligence version `2022-08-31 (GA)` for all models and `2023-07-31 (GA)` for Read and Layout only:

+* [REST API `2023-07-31 (GA)`](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2023-07-31/operations/AnalyzeDocument)

+* [SDKs targeting `REST API 2023-07-31 (GA)`](../sdk-overview-v3-1.md)

+**This content applies to:**  **v3.0 (GA)**  **v3.1 (GA)**

+With Document Intelligence containers, you can build an application architecture optimized to take advantage of both robust cloud capabilities and edge locality. Containers provide a minimalist, isolated environment that can be easily deployed on-premises and in the cloud. In this article, we show you how to configure the Document Intelligence container run-time environment by using the `docker compose` command arguments. Document Intelligence features are supported by seven Document Intelligence feature containersΓÇö**Read**, **Layout**, **Business Card**,**ID Document**, **Receipt**, **Invoice**, **Custom**. These containers have both required and optional settings. For a few examples, see the [Example docker-compose.yml file](#example-docker-composeyml-file) section.

+Support for containers is currently available with Document Intelligence version `2022-08-31 (GA)` for all models and `2023-07-31 (GA)` for Read and Layout only:

+* [REST API `2023-07-31 (GA)`](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2023-07-31/operations/AnalyzeDocument)

+* [SDKs targeting `REST API 2023-07-31 (GA)`](../sdk-overview-v3-1.md)

+**This content applies to:**  **v3.0 (GA)**  **v3.1 (GA)**

+Support for containers is currently available with Document Intelligence version `2022-08-31 (GA)` for all models and `2023-07-31 (GA)` for Read and Layout only:

+* [REST API `2023-07-31 (GA)`](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2023-07-31/operations/AnalyzeDocument)

+* [SDKs targeting `REST API 2023-07-31 (GA)`](../sdk-overview-v3-1.md)

+**This content applies to:**  **v3.1 (GA)**

+## Microsoft container registry (MCR)

+Document Intelligence container images can be found within the [**Microsoft Artifact Registry** (also know as Microsoft Container Registry(MCR))](https://mcr.microsoft.com/catalog?search=document%20intelligence), the primary registry for all Microsoft published container images.

+The following containers support DocumentIntelligence v3.0 models and features:

+| Container name |image |

+|||

+|[**Document Intelligence Studio**](https://mcr.microsoft.com/product/azure-cognitive-services/form-recognizer/studio/tags)| `mcr.microsoft.com/azure-cognitive-services/form-recognizer/studio:latest`|

+| [**Read 3.1**](https://mcr.microsoft.com/product/azure-cognitive-services/form-recognizer/read-3.1/tags) |`mcr.microsoft.com/azure-cognitive-services/form-recognizer/read-3.1:latest`|

+| [**Layout 3.1**](https://mcr.microsoft.com/en-us/product/azure-cognitive-services/form-recognizer/layout-3.1/tags) |`mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.1:latest`|

+- [Text to speech](./text-to-speech-quickstart.md). [**Added in 2024-02-15-preview**]

+ Title: Quickstart - Getting started with Azure OpenAI Assistants (Preview)

+description: Walkthrough on how to get started with Azure OpenAI assistants with new features like code interpreter and retrieval.

+zone_pivot_groups: openai-quickstart

+recommendations: false

+# Quickstart: Get started using Azure OpenAI Assistants (Preview)

+Azure OpenAI Assistants (Preview) allows you to create AI assistants tailored to your needs through custom instructions and augmented by advanced tools like code interpreter, and custom functions.

+ Title: Azure OpenAI Service Assistant API concepts

+description: Learn about the concepts behind the Azure OpenAI Assistants API.

+recommendations: false

+# Azure OpenAI Assistants API (Preview)

+Assistants, a new feature of Azure OpenAI Service, is now available in public preview. Assistants API makes it easier for developers to create applications with sophisticated copilot-like experiences that can sift through data, suggest solutions, and automate tasks.

+## Overview

+Previously, building custom AI assistants needed heavy lifting even for experienced developers. While the chat completions API is lightweight and powerful, it's inherently stateless, which means that developers had to manage conversation state and chat threads, tool integrations, retrieval documents and indexes, and execute code manually.

+The Assistants API, as the stateful evolution of the chat completion API, provides a solution for these challenges.

+Assistants API supports persistent automatically managed threads. This means that as a developer you no longer need to develop conversation state management systems and work around a modelΓÇÖs context window constraints. The Assistants API will automatically handle the optimizations to keep the thread below the max context window of your chosen model. Once you create a Thread, you can simply append new messages to it as users respond. Assistants can also access multiple tools in parallel, if needed. These tools include:

+- [Code Interpreter](../how-to/code-interpreter.md)

+- [Function calling](../how-to/assistant-functions.md)

+Assistant API is built on the same capabilities that power OpenAIΓÇÖs GPT product. Some possible use cases range from AI-powered product recommender, sales analyst app, coding assistant, employee Q&A chatbot, and more. Start building on the no-code Assistants playground on the Azure OpenAI Studio or start building with the API.

+> [!IMPORTANT]

+> Retrieving untrusted data using Function calling, Code Interpreter with file input, and Assistant Threads functionalities could compromise the security of your Assistant, or the application that uses the Assistant. Learn about mitigation approaches [here](https://aka.ms/oai/assistant-rai).

+## Assistants playground

+We provide a walkthrough of the Assistants playground in our [quickstart guide](../assistants-quickstart.md). This provides a no-code environment to test out the capabilities of assistants.

+## Assistants components

+| **Component** | **Description** |

+|||

+| **Assistant** | Custom AI that uses Azure OpenAI models in conjunction with tools. |

+|**Thread** | A conversation session between an Assistant and a user. Threads store Messages and automatically handle truncation to fit content into a modelΓÇÖs context.|

+| **Message** | A message created by an Assistant or a user. Messages can include text, images, and other files. Messages are stored as a list on the Thread. |

+|**Run** | Activation of an Assistant to begin running based on the contents of the Thread. The Assistant uses its configuration and the ThreadΓÇÖs Messages to perform tasks by calling models and tools. As part of a Run, the Assistant appends Messages to the Thread.|

+|**Run Step** | A detailed list of steps the Assistant took as part of a Run. An Assistant can call tools or create Messages during itΓÇÖs run. Examining Run Steps allows you to understand how the Assistant is getting to its final results. |

+## See also

+* Learn more about Assistants and [Code Interpreter](../how-to/code-interpreter.md)

+* Learn more about Assistants and [function calling](../how-to/assistant-functions.md)

+* [Azure OpenAI Assistants API samples](https://github.com/Azure-Samples/azureai-samples/tree/main/scenarios/Assistants)

+| [Text to speech](#text-to-speech-models-preview) (Preview) | A series of models in preview that can synthesize text to speech. |

+## Text to speech (Preview)

+The OpenAI text to speech models, currently in preview, can be used to synthesize text to speech.

+You can also use the OpenAI text to speech voices via Azure AI Speech. To learn more, see [OpenAI text to speech voices via Azure OpenAI Service or via Azure AI Speech](../../speech-service/openai-voices.md#openai-text-to-speech-voices-via-azure-openai-service-or-via-azure-ai-speech) guide.

+## Model summary table and region availability

+### GPT-4 and GPT-4 Turbo Preview models

+GPT-4 version 0314 is the first version of the model released. Version 0613 is the second version of the model and adds function calling support.

+> Version `0314` of `gpt-4` and `gpt-4-32k` will be retired no earlier than July 5, 2024. Version `0613` of `gpt-4` and `gpt-4-32k` will be retired no earlier than September 30, 2024. See [model updates](../how-to/working-with-models.md#model-updates) for model upgrade behavior.

+GPT-4 version 0125-preview is an updated version of the GPT-4 Turbo preview previously released as version 1106-preview. GPT-4 versio 0125-preview completes tasks such as code generation more completely compared to gpt-4-1106-preview. Because of this, depending on the task, customers may find that GPT-4-0125-preview generates more output compared to the gpt-4-1106-preview. We recommend customers compare the outputs of the new model. GPT-4-0125-preview also addresses bugs in gpt-4-1106-preview with UTF-8 handling for non-English languages.

+> [!IMPORTANT]

+>

+> - `gpt-4` version 0125-preview replaces version 1106-preview. Deployments of `gpt-4` version 1106-preview set to "Auto-update to default" and "Upgrade when expired" will start to be upgraded on February 20, 2024 and will complete upgrades within 2 weeks. Deployments of `gpt-4` version 1106-preview set to "No autoupgrade" will stop working starting February 20, 2024. If you have a deployment of `gpt-4` version 1106-preview, you can test version `0125-preview` in the available regions below.

+| `gpt-4` (0125-preview)**¹**<br>**GPT-4 Turbo Preview** | Input: 128,000 <br> Output: 4,096 | Apr 2023 |

+**¹** GPT-4 Turbo Preview = `gpt-4` (0125-preview). To deploy this model, under **Deployments** select model **gpt-4**. For **Model version** select **0125-preview**.

+> We don't recommend using preview models in production. We will upgrade all deployments of preview models to future preview versions and a stable version. Models designated preview do not follow the standard Azure OpenAI model lifecycle.

+| gpt-4 (0125-preview) | East US <br> North Central US <br> South Central US <br> |

+| `gpt-35-turbo` (1106) | North Central US <br> Sweden Central | Input: 16,385<br> Output: 4,096 | Sep 2021|

+### Text to speech models (Preview)

+| Model ID | Model Availability |

+| | | :: |

+| `tts-1` | North Central US <br> Sweden Central |

+| `tts-1-hd` | North Central US <br> Sweden Central |

+### Assistants (Preview)

+For Assistants you need a combination of a supported model, and a supported region. Certain tools and capabilities require the latest models. For example [parallel function](../how-to/assistant-functions.md) calling requires the latest 1106 models.

+| Region | `gpt-35-turbo (1106)` | `gpt-4 (1106-preview)` | `gpt-4 (0613)` | `gpt-4 (0314)` | `gpt-35-turbo (0301)` | `gpt-35-turbo (0613)` | `gpt-35-turbo-16k (0613)` | `gpt-4-32k (0314)` | `gpt-4-32k (0613)` |

+|||||||||||

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

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

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

+ b. Otherwise, the service estimates the incremental change to utilization required to serve the request by combining prompt tokens and the specified `max_tokens` in the call. If the `max_tokens` parameter is not specified, the service will estimate a value. This estimation can lead to lower concurrency than expected when the number of actual generated tokens is small. For highest concurrency, ensure that the `max_tokens` value is as close as possible to the true generation size.

+#### How many concurrent calls can I have on my deployment?

+The number of concurrent calls you can have at one time is dependent on each call's shape. The service will continue to accept calls until the utilization is above 100%. To determine the approximate number of concurrent calls you can model out the maximum requests per minute for a particular call shape in the [capacity calculator](https://oai.azure.com/portal/calculator). If `max_tokens` is empty, you can assume a value of 1000

+## Ingestion parameters

+You can use the following parameter to change how your data is ingested in Azure OpenAI Studio, Azure AI Studio, and the ingestion API. Changing the parameter requires re-ingesting your data into Azure Search.

+|Parameter name | Description |

+|||

+| **Chunk size** | Azure OpenAI on your data processes your documents by splitting them into chunks before indexing them in Azure Search. The chunk size is the maximum number of tokens for any chunk in the search index. The default chunk size is 1024 tokens. However, given the uniqueness of your data, you may find a different chunk size (such as 256, 512, or 1536 tokens for example) more effective. Adjusting the chunk size can enhance the performance of the chat bot. While finding the optimal chunk size requires some trial and error, start by considering the nature of your dataset. A smaller chunk size is generally better for datasets with direct facts and less context, while a larger chunk size might be beneficial for more contextual information, though it can affect retrieval performance. This is the `chunkSize` parameter in the API.|

+## Runtime parameters

+You can modify the following additional settings in the **Data parameters** section in Azure OpenAI Studio and [the API](../reference.md#completions-extensions). You do not need to re-ingest your your data when you update these parameters.

+| **Limit responses to your data** | This flag configures the chatbot's approach to handling queries unrelated to the data source or when search documents are insufficient for a complete answer. When this setting is disabled, the model supplements its responses with its own knowledge in addition to your documents. When this setting is enabled, the model attempts to only rely on your documents for responses. This is the `inScope` parameter in the API. |

+|**Top K Documents** | This parameter is an integer that can be set to 3, 5, 10, or 20, and controls the number of document chunks provided to the large language model for formulating the final response. By default, this is set to 5. The search process can be noisy and sometimes, due to chunking, relevant information may be spread across multiple chunks in the search index. Selecting a top-K number, like 5, ensures that the model can extract relevant information, despite the inherent limitations of search and chunking. However, increasing the number too high can potentially distract the model. Additionally, the maximum number of documents that can be effectively used depends on the version of the model, as each has a different context size and capacity for handling documents. If you find that responses are missing important context, try increasing this parameter. Conversely, if you think the model is providing irrelevant information alongside useful data, consider decreasing it. When experimenting with the [chunk size](#ingestion-parameters), we recommend adjusting the top-K parameter to achieve the best performance. Usually, it is beneficial to change the top-K value in the opposite direction of your chunk size adjustment. For example, if you decrease the chunk size from the default of 1024, you might want to increase the top-K value to 10 or 20. This ensures a similar amount of information is provided to the model, as reducing the chunk size decreases the amount of information in the 5 documents given to the model. This is the `topNDocuments` parameter in the API. |

+| **Strictness** | Determines the system's aggressiveness in filtering search documents based on their similarity scores. The system queries Azure Search or other document stores, then decides which documents to provide to large language models like ChatGPT. Filtering out irrelevant documents can significantly enhance the performance of the end-to-end chatbot. Some documents are excluded from the top-K results if they have low similarity scores before forwarding them to the model. This is controlled by an integer value ranging from 1 to 5. Setting this value to 1 means that the system will minimally filter documents based on search similarity to the user query. Conversely, a setting of 5 indicates that the system will aggressively filter out documents, applying a very high similarity threshold. If you find that the chatbot omits relevant information, lower the filter's strictness (set the value closer to 1) to include more documents. Conversely, if irrelevant documents distract the responses, increase the threshold (set the value closer to 5). This is the `strictness` parameter in the API. |

+ Title: 'How to use Azure OpenAI Assistants function calling'

+description: Learn how to use Assistants function calling

+recommendations: false

+# Azure OpenAI Assistants function calling

+The Assistants API supports function calling, which allows you to describe the structure of functions to an Assistant and then return the functions that need to be called along with their arguments.

+## Function calling support

+### Supported models

+The [models page](../concepts/models.md#assistants-preview) contains the most up-to-date information on regions/models where Assistants are supported.

+To use all features of function calling including parallel functions, you need to use the latest models.

+### API Version

+- `2024-02-15-preview`

+## Example function definition

+# [Python 1.x](#tab/python)

+```python

+from openai import AzureOpenAI

+

+client = AzureOpenAI(

+ api_key=os.getenv("AZURE_OPENAI_KEY"),

+ api_version="2024-02-15-preview",

+ azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")

+ )

+assistant = client.beta.assistants.create(

+ instructions="You are a weather bot. Use the provided functions to answer questions.",

+ model="gpt-4-1106-preview", #Replace with model deployment name

+ tools=[{

+ "type": "function",

+ "function": {

+ "name": "getCurrentWeather",

+ "description": "Get the weather in location",

+ "parameters": {

+ "type": "object",

+ "properties": {

+ "location": {"type": "string", "description": "The city and state e.g. San Francisco, CA"},

+ "unit": {"type": "string", "enum": ["c", "f"]}

+ },

+ "required": ["location"]

+ }

+ }

+ }, {

+ "type": "function",

+ "function": {

+ "name": "getNickname",

+ "description": "Get the nickname of a city",

+ "parameters": {

+ "type": "object",

+ "properties": {

+ "location": {"type": "string", "description": "The city and state e.g. San Francisco, CA"},

+ },

+ "required": ["location"]

+ }

+ }

+ }]

+)

+```

+# [REST](#tab/rest)

+> [!NOTE]

+> With Azure OpenAI the `model` parameter requires model deployment name. If your model deployment name is different than the underlying model name then you would adjust your code to ` "model": "{your-custom-model-deployment-name}"`.

+```console

+curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-02-15-preview \

+ -H "api-key: $AZURE_OPENAI_KEY" \

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

+ -d '{

+ "instructions": "You are a weather bot. Use the provided functions to answer questions.",

+ "tools": [{

+ "type": "function",

+ "function": {

+ "name": "getCurrentWeather",

+ "description": "Get the weather in location",

+ "parameters": {

+ "type": "object",

+ "properties": {

+ "location": {"type": "string", "description": "The city and state e.g. San Francisco, CA"},

+ "unit": {"type": "string", "enum": ["c", "f"]}

+ },

+ "required": ["location"]

+ }

+ }

+ },

+ {

+ "type": "function",

+ "function": {

+ "name": "getNickname",

+ "description": "Get the nickname of a city",

+ "parameters": {

+ "type": "object",

+ "properties": {

+ "location": {"type": "string", "description": "The city and state e.g. San Francisco, CA"}

+ },

+ "required": ["location"]

+ }

+ }

+ }],

+ "model": "gpt-4-1106-preview"

+ }'

+```

+## Reading the functions

+When you initiate a **Run** with a user Message that triggers the function, the **Run** will enter a pending status. After it processes, the run will enter a requires_action state that you can verify by retrieving the **Run**.

+```json

+{

+ "id": "run_abc123",

+ "object": "thread.run",

+ "assistant_id": "asst_abc123",

+ "thread_id": "thread_abc123",

+ "status": "requires_action",

+ "required_action": {

+ "type": "submit_tool_outputs",

+ "submit_tool_outputs": {

+ "tool_calls": [

+ {

+ "id": "call_abc123",

+ "type": "function",

+ "function": {

+ "name": "getCurrentWeather",

+ "arguments": "{\"location\":\"San Francisco\"}"

+ }

+ },

+ {

+ "id": "call_abc456",

+ "type": "function",

+ "function": {

+ "name": "getNickname",

+ "arguments": "{\"location\":\"Los Angeles\"}"

+ }

+ }

+ ]

+ }

+ },

+...

+```

+## Submitting function outputs

+You can then complete the **Run** by submitting the tool output from the function(s) you call. Pass the `tool_call_id` referenced in the `required_action` object above to match output to each function call.

+# [Python 1.x](#tab/python)

+```python

+from openai import AzureOpenAI

+

+client = AzureOpenAI(

+ api_key=os.getenv("AZURE_OPENAI_KEY"),

+ api_version="2024-02-15-preview",

+ azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")

+ )

+run = client.beta.threads.runs.submit_tool_outputs(

+ thread_id=thread.id,

+ run_id=run.id,

+ tool_outputs=[

+ {

+ "tool_call_id": call_ids[0],

+ "output": "22C",

+ },

+ {

+ "tool_call_id": call_ids[1],

+ "output": "LA",

+ },

+ ]

+)

+```

+# [REST](#tab/rest)

+```console

+curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/runs/run_123/submit_tool_outputs?api-version=2024-02-15-preview \

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

+ -H "api-key: $AZURE_OPENAI_KEY" \

+ -d '{

+ "tool_outputs": [{

+ "tool_call_id": "call_abc123",

+ "output": "{"temperature": "22", "unit": "celsius"}"

+ }, {

+ "tool_call_id": "call_abc456",

+ "output": "{"nickname": "LA"}"

+ }]

+ }'

+```

+After you submit tool outputs, the **Run** will enter the `queued` state before it continues execution.

+## See also

+* Learn more about how to use Assistants with our [How-to guide on Assistants](../how-to/assistant.md).

+* [Azure OpenAI Assistants API samples](https://github.com/Azure-Samples/azureai-samples/tree/main/scenarios/Assistants)

+ Title: 'How to create Assistants with Azure OpenAI Service'

+description: Learn how to create helpful AI Assistants with tools like Code Interpreter

+recommendations: false

+# Getting started with Azure OpenAI Assistants (Preview)

+Azure OpenAI Assistants (Preview) allows you to create AI assistants tailored to your needs through custom instructions and augmented by advanced tools like code interpreter, and custom functions. In this article we'll provide an in-depth walkthrough of getting started with the Assistants API.

+## Assistants support

+### Region and model support

+The [models page](../concepts/models.md#assistants-preview) contains the most up-to-date information on regions/models where Assistants are currently supported.

+### API Version

+- `2024-02-15-preview`

+### Supported file types

+|File format|MIME Type|Code Interpreter |

+||||

+|.c| text/x-c |✅|

+|.cpp|text/x-c++ |✅|

+|.csv|application/csv|✅|

+|.docx|application/vnd.openxmlformats-officedocument.wordprocessingml.document|✅|

+|.html|text/html|✅|

+|.java|text/x-java|✅|

+|.json|application/json|✅|

+|.md|text/markdown| ✅ |

+|.pdf|application/pdf|✅|

+|.php|text/x-php|✅|

+|.pptx|application/vnd.openxmlformats-officedocument.presentationml.presentation|✅|

+|.py|text/x-python|✅|

+|.py|text/x-script.python|✅|

+|.rb|text/x-ruby|✅|

+|.tex|text/x-tex|✅|

+|.txt|text/plain|✅|

+|.css|text/css|✅|

+|.jpeg|image/jpeg|✅|

+|.jpg|image/jpeg|✅|

+|.js|text/javascript|✅|

+|.gif|image/gif|✅|

+|.png|image/png|✅|

+|.tar|application/x-tar|✅|

+|.ts|application/typescript|✅|

+|.xlsx|application/vnd.openxmlformats-officedocument.spreadsheetml.sheet|✅|

+|.xml|application/xml or "text/xml"|✅|

+|.zip|application/zip|✅|

+### Tools

+An individual assistant can access up to 128 tools including `code interpreter`, but you can also define your own custom tools via [functions](./assistant-functions.md).

+### Files

+Files can be uploaded via Studio, or programmatically. The `file_ids` parameter is required to give tools like `code_interpreter` access to files. When using the File upload endpoint, you must have the `purpose` set to assistants to be used with the Assistants API.

+## Assistants playground

+We provide a walkthrough of the Assistants playground in our [quickstart guide](../assistants-quickstart.md). This provides a no-code environment to test out the capabilities of assistants.

+## Assistants components

+| **Component** | **Description** |

+|||

+| **Assistant** | Custom AI that uses Azure OpenAI models in conjunction with tools. |

+|**Thread** | A conversation session between an Assistant and a user. Threads store Messages and automatically handle truncation to fit content into a modelΓÇÖs context.|

+| **Message** | A message created by an Assistant or a user. Messages can include text, images, and other files. Messages are stored as a list on the Thread. |

+|**Run** | Activation of an Assistant to begin running based on the contents of the Thread. The Assistant uses its configuration and the ThreadΓÇÖs Messages to perform tasks by calling models and tools. As part of a Run, the Assistant appends Messages to the Thread.|

+|**Run Step** | A detailed list of steps the Assistant took as part of a Run. An Assistant can call tools or create Messages during itΓÇÖs run. Examining Run Steps allows you to understand how the Assistant is getting to its final results. |

+## Setting up your first Assistant

+### Create an assistant

+For this example we'll create an assistant that writes code to generate visualizations using the capabilities of the `code_interpreter` tool. The examples below are intended to be run sequentially in an environment like [Jupyter Notebooks](https://jupyter.org/).

+```Python

+import os

+import json

+from openai import AzureOpenAI

+

+client = AzureOpenAI(

+ api_key=os.getenv("AZURE_OPENAI_KEY"),

+ api_version="2024-02-15-preview",

+ azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")

+ )

+# Create an assistant

+assistant = client.beta.assistants.create(

+ name="Data Visualization",

+ instructions=f"You are a helpful AI assistant who makes interesting visualizations based on data."

+ f"You have access to a sandboxed environment for writing and testing code."

+ f"When you are asked to create a visualization you should follow these steps:"

+ f"1. Write the code."

+ f"2. Anytime you write new code display a preview of the code to show your work."

+ f"3. Run the code to confirm that it runs."

+ f"4. If the code is successful display the visualization."

+ f"5. If the code is unsuccessful display the error message and try to revise the code and rerun going through the steps from above again.",

+ tools=[{"type": "code_interpreter"}],

+ model="gpt-4-1106-preview" #You must replace this value with the deployment name for your model.

+)

+```

+There are a few details you should note from the configuration above:

+- We enable this assistant to access code interpreter with the line ` tools=[{"type": "code_interpreter"}],`. This gives the model access to a sand-boxed python environment to run and execute code to help formulating responses to a user's question.

+- In the instructions we remind the model that it can execute code. Sometimes the model needs help guiding it towards the right tool to solve a given query. If you know, you want to use a particular library to generate a certain response that you know is part of code interpreter it can help to provide guidance by saying something like "Use Matplotlib to do x."

+- Since this is Azure OpenAI the value you enter for `model=` **must match the deployment name**. By convention our docs will often use a deployment name that happens to match the model name to indicate which model was used when testing a given example, but in your environment the deployment names can be different and that is the name that you should enter in the code.

+Next we're going to print the contents of assistant that we just created to confirm that creation was successful:

+```python

+print(assistant.model_dump_json(indent=2))

+```

+```json

+{

+ "id": "asst_7AZSrv5I3XzjUqWS40X5UgRr",

+ "created_at": 1705972454,

+ "description": null,

+ "file_ids": [],

+ "instructions": "You are a helpful AI assistant who makes interesting visualizations based on data.You have access to a sandboxed environment for writing and testing code.When you are asked to create a visualization you should follow these steps:1. Write the code.2. Anytime you write new code display a preview of the code to show your work.3. Run the code to confirm that it runs.4. If the code is successful display the visualization.5. If the code is unsuccessful display the error message and try to revise the code and rerun going through the steps from above again.",

+ "metadata": {},

+ "model": "gpt-4-1106-preview",

+ "name": "Data Visualization",

+ "object": "assistant",

+ "tools": [

+ {

+ "type": "code_interpreter"

+ }

+ ]

+}

+```

+### Create a thread

+Now let's create a thread

+```python

+# Create a thread

+thread = client.beta.threads.create()

+print(thread)

+```

+```output

+Thread(id='thread_6bunpoBRZwNhovwzYo7fhNVd', created_at=1705972465, metadata={}, object='thread')

+```

+A thread is essentially the record of the conversation session between the assistant and the user. It's similar to the messages array/list in a typical chat completions API call. One of the key differences, is unlike a chat completions messages array, you don't need to track tokens with each call to make sure that you're remaining below the context length of the model. Threads abstract away this management detail and will compress the thread history as needed in order to allow the conversation to continue. The ability for threads to accomplish this with larger conversations is enhanced when using the latest models, which have larger context lengths as well as support for the latest features.

+Next create the first user question to add to the thread

+```python

+# Add a user question to the thread

+message = client.beta.threads.messages.create(

+ thread_id=thread.id,

+ role="user",

+ content="Create a visualization of a sinewave"

+)

+```

+### List thread messages

+```python

+thread_messages = client.beta.threads.messages.list(thread.id)

+print(thread_messages.model_dump_json(indent=2))

+```

+```json

+{

+ "data": [

+ {

+ "id": "msg_JnkmWPo805Ft8NQ0gZF6vA2W",

+ "assistant_id": null,

+ "content": [

+ {

+ "text": {

+ "annotations": [],

+ "value": "Create a visualization of a sinewave"

+ },

+ "type": "text"

+ }

+ ],

+ "created_at": 1705972476,

+ "file_ids": [],

+ "metadata": {},

+ "object": "thread.message",

+ "role": "user",

+ "run_id": null,

+ "thread_id": "thread_6bunpoBRZwNhovwzYo7fhNVd"

+ }

+ ],

+ "object": "list",

+ "first_id": "msg_JnkmWPo805Ft8NQ0gZF6vA2W",

+ "last_id": "msg_JnkmWPo805Ft8NQ0gZF6vA2W",

+ "has_more": false

+}

+```

+### Run thread

+```python

+run = client.beta.threads.runs.create(

+ thread_id=thread.id,

+ assistant_id=assistant.id,

+ #instructions="New instructions" #You can optionally provide new instructions but these will override the default instructions

+)

+```

+We could also pass an `instructions` parameter here, but this would override the existing instructions that we have already provided for the assistant.

+### Retrieve thread status

+```python

+# Retrieve the status of the run

+run = client.beta.threads.runs.retrieve(

+ thread_id=thread.id,

+ run_id=run.id

+)

+status = run.status

+print(status)

+```

+```output

+completed

+```

+Depending on the complexity of the query you run, the thread could take longer to execute. In that case you can create a loop to monitor the [run status](#run-status-definitions) of the thread with code like the example below:

+```python

+import time

+from IPython.display import clear_output

+start_time = time.time()

+status = run.status

+while status not in ["completed", "cancelled", "expired", "failed"]:

+ time.sleep(5)

+ run = client.beta.threads.runs.retrieve(thread_id=thread.id,run_id=run.id)

+ print("Elapsed time: {} minutes {} seconds".format(int((time.time() - start_time) // 60), int((time.time() - start_time) % 60)))

+ status = run.status

+ print(f'Status: {status}')

+ clear_output(wait=True)

+messages = client.beta.threads.messages.list(

+ thread_id=thread.id

+)

+print(f'Status: {status}')

+print("Elapsed time: {} minutes {} seconds".format(int((time.time() - start_time) // 60), int((time.time() - start_time) % 60)))

+print(messages.model_dump_json(indent=2))

+```

+When a Run is `in_progress` or in other nonterminal states the thread is locked. When a thread is locked new messages can't be added, and new runs can't be created.

+### List thread messages post run

+Once the run status indicates successful completion, you can list the contents of the thread again to retrieve the model's and any tools response:

+```python

+messages = client.beta.threads.messages.list(

+ thread_id=thread.id

+)

+print(messages.model_dump_json(indent=2))

+```

+```json

+{

+ "data": [

+ {

+ "id": "msg_M5pz73YFsJPNBbWvtVs5ZY3U",

+ "assistant_id": "asst_eHwhP4Xnad0bZdJrjHO2hfB4",

+ "content": [

+ {

+ "text": {

+ "annotations": [],

+ "value": "Is there anything else you would like to visualize or any additional features you'd like to add to the sine wave plot?"

+ },

+ "type": "text"

+ }

+ ],

+ "created_at": 1705967782,

+ "file_ids": [],

+ "metadata": {},

+ "object": "thread.message",

+ "role": "assistant",

+ "run_id": "run_AGQHJrrfV3eM0eI9T3arKgYY",

+ "thread_id": "thread_ow1Yv29ptyVtv7ixbiKZRrHd"

+ },

+ {

+ "id": "msg_oJbUanImBRpRran5HSa4Duy4",

+ "assistant_id": "asst_eHwhP4Xnad0bZdJrjHO2hfB4",

+ "content": [

+ {

+ "image_file": {

+ "file_id": "assistant-1YGVTvNzc2JXajI5JU9F0HMD"

+ },

+ "type": "image_file"

+ },

+ {

+ "text": {

+ "annotations": [],

+ "value": "Here is the visualization of a sine wave: \n\nThe wave is plotted using values from 0 to \\( 4\\pi \\) on the x-axis, and the corresponding sine values on the y-axis. I've also added grid lines for easier reading of the plot."

+ },

+ "type": "text"

+ }

+ ],

+ "created_at": 1705967044,

+ "file_ids": [],

+ "metadata": {},

+ "object": "thread.message",

+ "role": "assistant",

+ "run_id": "run_8PsweDFn6gftUd91H87K0Yts",

+ "thread_id": "thread_ow1Yv29ptyVtv7ixbiKZRrHd"

+ },

+ {

+ "id": "msg_Pu3eHjM10XIBkwqh7IhnKKdG",

+ "assistant_id": null,

+ "content": [

+ {

+ "text": {

+ "annotations": [],

+ "value": "Create a visualization of a sinewave"

+ },

+ "type": "text"

+ }

+ ],

+ "created_at": 1705966634,

+ "file_ids": [],

+ "metadata": {},

+ "object": "thread.message",

+ "role": "user",

+ "run_id": null,

+ "thread_id": "thread_ow1Yv29ptyVtv7ixbiKZRrHd"

+ }

+ ],

+ "object": "list",

+ "first_id": "msg_M5pz73YFsJPNBbWvtVs5ZY3U",

+ "last_id": "msg_Pu3eHjM10XIBkwqh7IhnKKdG",

+ "has_more": false

+}

+```

+### Retrieve file ID

+We had requested that the model generate an image of a sine wave. In order to download the image, we first need to retrieve the images file ID.

+```python

+data = json.loads(messages.model_dump_json(indent=2)) # Load JSON data into a Python object

+image_file_id = data['data'][1]['content'][0]['image_file']['file_id']

+print(image_file_id) # Outputs: assistant-1YGVTvNzc2JXajI5JU9F0HMD

+```

+### Download image

+```python

+from openai import AzureOpenAI

+

+client = AzureOpenAI(

+ api_key=os.getenv("AZURE_OPENAI_KEY"),

+ api_version="2024-02-15-preview",

+ azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")

+ )

+content = client.files.content(image_file_id)

+image= content.write_to_file("sinewave.png")

+```

+Open the image locally once it's downloaded:

+```python

+from PIL import Image

+# Display the image in the default image viewer

+image = Image.open("sinewave.png")

+image.show()

+```

+### Ask a follow-up question on the thread

+Since the assistant didn't quite follow our instructions and include the code that was run in the text portion of its response lets explicitly ask for that information.

+```python

+# Add a new user question to the thread

+message = client.beta.threads.messages.create(

+ thread_id=thread.id,

+ role="user",

+ content="Show me the code you used to generate the sinewave"

+)

+```

+Again we'll need to run and retrieve the status of the thread:

+```python

+run = client.beta.threads.runs.create(

+ thread_id=thread.id,

+ assistant_id=assistant.id,

+ #instructions="New instructions" #You can optionally provide new instructions but these will override the default instructions

+)

+# Retrieve the status of the run

+run = client.beta.threads.runs.retrieve(

+ thread_id=thread.id,

+ run_id=run.id

+)

+status = run.status

+print(status)

+```

+```output

+completed

+```

+Once the run status reaches completed, we'll list the messages in the thread again which should now include the response to our latest question.

+```python

+messages = client.beta.threads.messages.list(

+ thread_id=thread.id

+)

+print(messages.model_dump_json(indent=2))

+```

+```json

+{

+ "data": [

+ {

+ "id": "msg_oaF1PUeozAvj3KrNnbKSy4LQ",

+ "assistant_id": "asst_eHwhP4Xnad0bZdJrjHO2hfB4",

+ "content": [

+ {

+ "text": {

+ "annotations": [],

+ "value": "Certainly, here is the code I used to generate the sine wave visualization:\n\n```python\nimport numpy as np\nimport matplotlib.pyplot as plt\n\n# Generating data for the sinewave\nx = np.linspace(0, 4 * np.pi, 1000) # Generate values from 0 to 4*pi\ny = np.sin(x) # Compute the sine of these values\n\n# Plotting the sine wave\nplt.plot(x, y)\nplt.title('Sine Wave')\nplt.xlabel('x')\nplt.ylabel('sin(x)')\nplt.grid(True)\nplt.show()\n```\n\nThis code snippet uses `numpy` to generate an array of x values and then computes the sine for each x value. It then uses `matplotlib` to plot these values and display the resulting graph."

+ },

+ "type": "text"

+ }

+ ],

+ "created_at": 1705969710,

+ "file_ids": [],

+ "metadata": {},

+ "object": "thread.message",

+ "role": "assistant",

+ "run_id": "run_oDS3fH7NorCUVwROTZejKcZN",

+ "thread_id": "thread_ow1Yv29ptyVtv7ixbiKZRrHd"

+ },

+ {

+ "id": "msg_moYE3aNwFYuRq2aXpxpt2Wb0",

+ "assistant_id": null,

+ "content": [

+ {

+ "text": {

+ "annotations": [],

+ "value": "Show me the code you used to generate the sinewave"

+ },

+ "type": "text"

+ }

+ ],

+ "created_at": 1705969678,

+ "file_ids": [],

+ "metadata": {},

+ "object": "thread.message",

+ "role": "user",

+ "run_id": null,

+ "thread_id": "thread_ow1Yv29ptyVtv7ixbiKZRrHd"

+ },

+ {

+ "id": "msg_M5pz73YFsJPNBbWvtVs5ZY3U",

+ "assistant_id": "asst_eHwhP4Xnad0bZdJrjHO2hfB4",

+ "content": [

+ {

+ "text": {

+ "annotations": [],

+ "value": "Is there anything else you would like to visualize or any additional features you'd like to add to the sine wave plot?"

+ },

+ "type": "text"

+ }

+ ],

+ "created_at": 1705967782,

+ "file_ids": [],

+ "metadata": {},

+ "object": "thread.message",

+ "role": "assistant",

+ "run_id": "run_AGQHJrrfV3eM0eI9T3arKgYY",

+ "thread_id": "thread_ow1Yv29ptyVtv7ixbiKZRrHd"

+ },

+ {

+ "id": "msg_oJbUanImBRpRran5HSa4Duy4",

+ "assistant_id": "asst_eHwhP4Xnad0bZdJrjHO2hfB4",

+ "content": [

+ {

+ "image_file": {

+ "file_id": "assistant-1YGVTvNzc2JXajI5JU9F0HMD"

+ },

+ "type": "image_file"

+ },

+ {

+ "text": {

+ "annotations": [],

+ "value": "Here is the visualization of a sine wave: \n\nThe wave is plotted using values from 0 to \\( 4\\pi \\) on the x-axis, and the corresponding sine values on the y-axis. I've also added grid lines for easier reading of the plot."

+ },

+ "type": "text"

+ }

+ ],

+ "created_at": 1705967044,

+ "file_ids": [],

+ "metadata": {},

+ "object": "thread.message",

+ "role": "assistant",

+ "run_id": "run_8PsweDFn6gftUd91H87K0Yts",

+ "thread_id": "thread_ow1Yv29ptyVtv7ixbiKZRrHd"

+ },

+ {

+ "id": "msg_Pu3eHjM10XIBkwqh7IhnKKdG",

+ "assistant_id": null,

+ "content": [

+ {

+ "text": {

+ "annotations": [],

+ "value": "Create a visualization of a sinewave"

+ },

+ "type": "text"

+ }

+ ],

+ "created_at": 1705966634,

+ "file_ids": [],

+ "metadata": {},

+ "object": "thread.message",

+ "role": "user",

+ "run_id": null,

+ "thread_id": "thread_ow1Yv29ptyVtv7ixbiKZRrHd"

+ }

+ ],

+ "object": "list",

+ "first_id": "msg_oaF1PUeozAvj3KrNnbKSy4LQ",

+ "last_id": "msg_Pu3eHjM10XIBkwqh7IhnKKdG",

+ "has_more": false

+}

+```

+To extract only the response to our latest question:

+```python

+data = json.loads(messages.model_dump_json(indent=2))

+code = data['data'][0]['content'][0]['text']['value']

+print(code)

+```

+*Certainly, here is the code I used to generate the sine wave visualization:*

+```python

+import numpy as np

+import matplotlib.pyplot as plt

+# Generating data for the sinewave

+x = np.linspace(0, 4 * np.pi, 1000) # Generate values from 0 to 4*pi

+y = np.sin(x) # Compute the sine of these values

+# Plotting the sine wave

+plt.plot(x, y)

+plt.title('Sine Wave')

+plt.xlabel('x')

+plt.ylabel('sin(x)')

+plt.grid(True)

+plt.show()

+```

+### Dark mode

+Let's add one last question to the thread to see if code interpreter can swap the chart to dark mode for us.

+```python

+# Add a user question to the thread

+message = client.beta.threads.messages.create(

+ thread_id=thread.id,

+ role="user",

+ content="I prefer visualizations in darkmode can you change the colors to make a darkmode version of this visualization."

+)

+# Run the thread

+run = client.beta.threads.runs.create(

+ thread_id=thread.id,

+ assistant_id=assistant.id,

+)

+# Retrieve the status of the run

+run = client.beta.threads.runs.retrieve(

+ thread_id=thread.id,

+ run_id=run.id

+)

+status = run.status

+print(status)

+```

+```output

+completed

+```

+```python

+messages = client.beta.threads.messages.list(

+ thread_id=thread.id

+)

+print(messages.model_dump_json(indent=2))

+```

+```json

+{

+ "data": [

+ {

+ "id": "msg_KKzOHCArWGvGpuPo0pVZTHgV",

+ "assistant_id": "asst_eHwhP4Xnad0bZdJrjHO2hfB4",

+ "content": [

+ {

+ "text": {

+ "annotations": [],

+ "value": "You're viewing the dark mode version of the sine wave visualization in the image above. The plot is set against a dark background with a cyan colored sine wave for better contrast and visibility. If there's anything else you'd like to adjust or any other assistance you need, feel free to let me know!"

+ },

+ "type": "text"

+ }

+ ],

+ "created_at": 1705971199,

+ "file_ids": [],

+ "metadata": {},

+ "object": "thread.message",

+ "role": "assistant",

+ "run_id": "run_izZFyTVB1AlFM1VVMItggRn4",

+ "thread_id": "thread_ow1Yv29ptyVtv7ixbiKZRrHd"

+ },

+ {

+ "id": "msg_30pXFVYNgP38qNEMS4Zbozfk",

+ "assistant_id": null,

+ "content": [

+ {

+ "text": {

+ "annotations": [],

+ "value": "I prefer visualizations in darkmode can you change the colors to make a darkmode version of this visualization."

+ },

+ "type": "text"

+ }

+ ],

+ "created_at": 1705971194,

+ "file_ids": [],

+ "metadata": {},

+ "object": "thread.message",

+ "role": "user",

+ "run_id": null,

+ "thread_id": "thread_ow1Yv29ptyVtv7ixbiKZRrHd"

+ },

+ {

+ "id": "msg_3j31M0PaJLqO612HLKVsRhlw",

+ "assistant_id": "asst_eHwhP4Xnad0bZdJrjHO2hfB4",

+ "content": [

+ {

+ "image_file": {

+ "file_id": "assistant-kfqzMAKN1KivQXaEJuU0u9YS"

+ },

+ "type": "image_file"

+ },

+ {

+ "text": {

+ "annotations": [],

+ "value": "Here is the dark mode version of the sine wave visualization. I've used the 'dark_background' style in Matplotlib and chosen a cyan color for the plot line to ensure it stands out against the dark background."

+ },

+ "type": "text"

+ }

+ ],

+ "created_at": 1705971123,

+ "file_ids": [],

+ "metadata": {},

+ "object": "thread.message",

+ "role": "assistant",

+ "run_id": "run_B91erEPWro4bZIfryQeIDDlx",

+ "thread_id": "thread_ow1Yv29ptyVtv7ixbiKZRrHd"

+ },

+ {

+ "id": "msg_FgDZhBvvM1CLTTFXwgeJLdua",

+ "assistant_id": null,

+ "content": [

+ {

+ "text": {

+ "annotations": [],

+ "value": "I prefer visualizations in darkmode can you change the colors to make a darkmode version of this visualization."

+ },

+ "type": "text"

+ }

+ ],

+ "created_at": 1705971052,

+ "file_ids": [],

+ "metadata": {},

+ "object": "thread.message",

+ "role": "user",

+ "run_id": null,

+ "thread_id": "thread_ow1Yv29ptyVtv7ixbiKZRrHd"

+ },

+ {

+ "id": "msg_oaF1PUeozAvj3KrNnbKSy4LQ",

+ "assistant_id": "asst_eHwhP4Xnad0bZdJrjHO2hfB4",

+ "content": [

+ {

+ "text": {

+ "annotations": [],

+ "value": "Certainly, here is the code I used to generate the sine wave visualization:\n\n```python\nimport numpy as np\nimport matplotlib.pyplot as plt\n\n# Generating data for the sinewave\nx = np.linspace(0, 4 * np.pi, 1000) # Generate values from 0 to 4*pi\ny = np.sin(x) # Compute the sine of these values\n\n# Plotting the sine wave\nplt.plot(x, y)\nplt.title('Sine Wave')\nplt.xlabel('x')\nplt.ylabel('sin(x)')\nplt.grid(True)\nplt.show()\n```\n\nThis code snippet uses `numpy` to generate an array of x values and then computes the sine for each x value. It then uses `matplotlib` to plot these values and display the resulting graph."

+ },

+ "type": "text"

+ }

+ ],

+ "created_at": 1705969710,

+ "file_ids": [],

+ "metadata": {},

+ "object": "thread.message",

+ "role": "assistant",

+ "run_id": "run_oDS3fH7NorCUVwROTZejKcZN",

+ "thread_id": "thread_ow1Yv29ptyVtv7ixbiKZRrHd"

+ },

+ {

+ "id": "msg_moYE3aNwFYuRq2aXpxpt2Wb0",

+ "assistant_id": null,

+ "content": [

+ {

+ "text": {

+ "annotations": [],

+ "value": "Show me the code you used to generate the sinewave"

+ },

+ "type": "text"

+ }

+ ],

+ "created_at": 1705969678,

+ "file_ids": [],

+ "metadata": {},

+ "object": "thread.message",

+ "role": "user",

+ "run_id": null,

+ "thread_id": "thread_ow1Yv29ptyVtv7ixbiKZRrHd"

+ },

+ {

+ "id": "msg_M5pz73YFsJPNBbWvtVs5ZY3U",

+ "assistant_id": "asst_eHwhP4Xnad0bZdJrjHO2hfB4",

+ "content": [

+ {

+ "text": {

+ "annotations": [],

+ "value": "Is there anything else you would like to visualize or any additional features you'd like to add to the sine wave plot?"

+ },

+ "type": "text"

+ }

+ ],

+ "created_at": 1705967782,

+ "file_ids": [],

+ "metadata": {},

+ "object": "thread.message",

+ "role": "assistant",

+ "run_id": "run_AGQHJrrfV3eM0eI9T3arKgYY",

+ "thread_id": "thread_ow1Yv29ptyVtv7ixbiKZRrHd"

+ },

+ {

+ "id": "msg_oJbUanImBRpRran5HSa4Duy4",

+ "assistant_id": "asst_eHwhP4Xnad0bZdJrjHO2hfB4",

+ "content": [

+ {

+ "image_file": {

+ "file_id": "assistant-1YGVTvNzc2JXajI5JU9F0HMD"

+ },

+ "type": "image_file"

+ },

+ {

+ "text": {

+ "annotations": [],

+ "value": "Here is the visualization of a sine wave: \n\nThe wave is plotted using values from 0 to \\( 4\\pi \\) on the x-axis, and the corresponding sine values on the y-axis. I've also added grid lines for easier reading of the plot."

+ },

+ "type": "text"

+ }

+ ],

+ "created_at": 1705967044,

+ "file_ids": [],

+ "metadata": {},

+ "object": "thread.message",

+ "role": "assistant",

+ "run_id": "run_8PsweDFn6gftUd91H87K0Yts",

+ "thread_id": "thread_ow1Yv29ptyVtv7ixbiKZRrHd"

+ },

+ {

+ "id": "msg_Pu3eHjM10XIBkwqh7IhnKKdG",

+ "assistant_id": null,

+ "content": [

+ {

+ "text": {

+ "annotations": [],

+ "value": "Create a visualization of a sinewave"

+ },

+ "type": "text"

+ }

+ ],

+ "created_at": 1705966634,

+ "file_ids": [],

+ "metadata": {},

+ "object": "thread.message",

+ "role": "user",

+ "run_id": null,

+ "thread_id": "thread_ow1Yv29ptyVtv7ixbiKZRrHd"

+ }

+ ],

+ "object": "list",

+ "first_id": "msg_KKzOHCArWGvGpuPo0pVZTHgV",

+ "last_id": "msg_Pu3eHjM10XIBkwqh7IhnKKdG",

+ "has_more": false

+}

+```

+Extract the new image file ID and download and display the image:

+```python

+data = json.loads(messages.model_dump_json(indent=2)) # Load JSON data into a Python object

+image_file_id = data['data'][0]['content'][0]['image_file']['file_id'] # index numbers can vary if you have had a different conversation over the course of the thread.

+print(image_file_id)

+content = client.files.content(image_file_id)

+image= content.write_to_file("dark_sine.png")

+# Display the image in the default image viewer

+image = Image.open("dark_sine.png")

+image.show()

+```

+## Additional reference

+### Run status definitions

+|**Status**| **Definition**|

+||--|

+|`queued`| When Runs are first created or when you complete the required_action, they are moved to a queued status. They should almost immediately move to in_progress.|

+|`in_progress` | While in_progress, the Assistant uses the model and tools to perform steps. You can view progress being made by the Run by examining the Run Steps.|

+|`completed` | The Run successfully completed! You can now view all Messages the Assistant added to the Thread, and all the steps the Run took. You can also continue the conversation by adding more user Messages to the Thread and creating another Run.|

+|`requires_action` | When using the Function calling tool, the Run will move to a required_action state once the model determines the names and arguments of the functions to be called. You must then run those functions and submit the outputs before the run proceeds. If the outputs are not provided before the expires_at timestamp passes (roughly 10-mins past creation), the run will move to an expired status.|

+|`expired` | This happens when the function calling outputs weren't submitted before expires_at and the run expires. Additionally, if the runs take too long to execute and go beyond the time stated in expires_at, our systems will expire the run.|

+|`cancelling`| You can attempt to cancel an in_progress run using the Cancel Run endpoint. Once the attempt to cancel succeeds, status of the Run moves to canceled. Cancelation is attempted but not guaranteed.|

+|`cancelled` |Run was successfully canceled.|

+|`failed` |You can view the reason for the failure by looking at the `last_error` object in the Run. The timestamp for the failure will be recorded under failed_at.|

+## Message annotations

+Assistant message annotations are different from the [content filtering annotations](../concepts/content-filter.md) that are present in completion and chat completion API responses. Assistant annotations can occur within the content array of the object. Annotations provide information around how you should annotate the text in the responses to the user.

+When annotations are present in the Message content array, you'll see illegible model-generated substrings in the text that you need to replace with the correct annotations. These strings might look something like `【13†source】` or `sandbox:/mnt/data/file.csv`. Here’s a Python code snippet from OpenAI that replaces these strings with the information present in the annotations.

+```Python

+from openai import AzureOpenAI

+

+client = AzureOpenAI(

+ api_key=os.getenv("AZURE_OPENAI_KEY"),

+ api_version="2024-02-15-preview",

+ azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")

+ )

+# Retrieve the message object

+message = client.beta.threads.messages.retrieve(

+ thread_id="...",

+ message_id="..."

+)

+# Extract the message content

+message_content = message.content[0].text

+annotations = message_content.annotations

+citations = []

+# Iterate over the annotations and add footnotes

+for index, annotation in enumerate(annotations):

+ # Replace the text with a footnote

+ message_content.value = message_content.value.replace(annotation.text, f' [{index}]')

+ # Gather citations based on annotation attributes

+ if (file_citation := getattr(annotation, 'file_citation', None)):

+ cited_file = client.files.retrieve(file_citation.file_id)

+ citations.append(f'[{index}] {file_citation.quote} from {cited_file.filename}')

+ elif (file_path := getattr(annotation, 'file_path', None)):

+ cited_file = client.files.retrieve(file_path.file_id)

+ citations.append(f'[{index}] Click <here> to download {cited_file.filename}')

+ # Note: File download functionality not implemented above for brevity

+# Add footnotes to the end of the message before displaying to user

+message_content.value += '\n' + '\n'.join(citations)

+```

+|Message annotation | Description |

+|||

+| `file_citation` | File citations are created by the retrieval tool and define references to a specific quote in a specific file that was uploaded and used by the Assistant to generate the response. |

+|`file_path` | File path annotations are created by the code_interpreter tool and contain references to the files generated by the tool. |

+## See also

+* Learn more about Assistants and [Code Interpreter](./code-interpreter.md)

+* Learn more about Assistants and [function calling](./assistant-functions.md)

+* [Azure OpenAI Assistants API samples](https://github.com/Azure-Samples/azureai-samples/tree/main/scenarios/Assistants)

+ Title: 'How to use Azure OpenAI Assistants Code Interpreter'

+description: Learn how to use Assistants Code Interpreter

+recommendations: false

+# Azure OpenAI Assistants Code Interpreter (Preview)

+Code Interpreter allows the Assistants API to write and run Python code in a sandboxed execution environment. With Code Interpreter enabled, your Assistant can run code iteratively to solve more challenging code, math, and data analysis problems. When your Assistant writes code that fails to run, it can iterate on this code by modifying and running different code until the code execution succeeds.

+> [!IMPORTANT]

+> Code Interpreter has [additional charges](https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/) beyond the token based fees for Azure OpenAI usage. If your Assistant calls Code Interpreter simultaneously in two different threads, two code interpreter sessions are created. Each session is active by default for one hour.

+## Code interpreter support

+### Supported models

+The [models page](../concepts/models.md#assistants-preview) contains the most up-to-date information on regions/models where Assistants and code interpreter are supported.

+We recommend using assistants with the latest models to take advantage of the new features, as well as the larger context windows, and more up-to-date training data.

+### API Version

+- `2024-02-15-preview`

+### Supported file types

+|File format|MIME Type|

+|||

+|.c| text/x-c |

+|.cpp|text/x-c++ |

+|.csv|application/csv|

+|.docx|application/vnd.openxmlformats-officedocument.wordprocessingml.document|

+|.html|text/html|

+|.java|text/x-java|

+|.json|application/json|

+|.md|text/markdown|

+|.pdf|application/pdf|

+|.php|text/x-php|

+|.pptx|application/vnd.openxmlformats-officedocument.presentationml.presentation|

+|.py|text/x-python|

+|.py|text/x-script.python|

+|.rb|text/x-ruby|

+|.tex|text/x-tex|

+|.txt|text/plain|

+|.css|text/css|

+|.jpeg|image/jpeg|

+|.jpg|image/jpeg|

+|.js|text/javascript|

+|.gif|image/gif|

+|.png|image/png|

+|.tar|application/x-tar|

+|.ts|application/typescript|

+|.xlsx|application/vnd.openxmlformats-officedocument.spreadsheetml.sheet|

+|.xml|application/xml or "text/xml"|

+|.zip|application/zip|

+## Enable Code Interpreter

+# [Python 1.x](#tab/python)

+```python

+from openai import AzureOpenAI

+

+client = AzureOpenAI(

+ api_key=os.getenv("AZURE_OPENAI_KEY"),

+ api_version="2024-02-15-preview",

+ azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")

+ )

+assistant = client.beta.assistants.create(

+ instructions="You are an AI assistant that can write code to help answer math questions",

+ model="<REPLACE WITH MODEL DEPLOYMENT NAME>", # replace with model deployment name.

+ tools=[{"type": "code_interpreter"}]

+)

+```

+# [REST](#tab/rest)

+> [!NOTE]

+> With Azure OpenAI the `model` parameter requires model deployment name. If your model deployment name is different than the underlying model name then you would adjust your code to ` "model": "{your-custom-model-deployment-name}"`.

+```console

+curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-02-15-preview \

+ -H "api-key: $AZURE_OPENAI_KEY" \

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

+ -d '{

+ "instructions": "You are an AI assistant that can write code to help answer math questions.",

+ "tools": [

+ { "type": "code_interpreter" }

+ ],

+ "model": "gpt-4-1106-preview"

+ }'

+```

+## Upload file for Code Interpreter

+# [Python 1.x](#tab/python)

+```python

+from openai import AzureOpenAI

+

+client = AzureOpenAI(

+ api_key=os.getenv("AZURE_OPENAI_KEY"),

+ api_version="2024-02-15-preview",

+ azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")

+ )

+# Upload a file with an "assistants" purpose

+file = client.files.create(

+ file=open("speech.py", "rb"),

+ purpose='assistants'

+)

+# Create an assistant using the file ID

+assistant = client.beta.assistants.create(

+ instructions="You are an AI assistant that can write code to help answer math questions.",

+ model="gpt-4-1106-preview",

+ tools=[{"type": "code_interpreter"}],

+ file_ids=[file.id]

+)

+```

+# [REST](#tab/rest)

+```console

+# Upload a file with an "assistants" purpose

+curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/files?api-version=2024-02-15-preview \

+ -H "api-key: $AZURE_OPENAI_KEY" \

+ -F purpose="assistants" \

+ -F file="@c:\\path_to_file\\file.csv"

+# Create an assistant using the file ID

+curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-02-15-preview \

+ -H "api-key: $AZURE_OPENAI_KEY" \

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

+ -d '{

+ "instructions": "You are an AI assistant that can write code to help answer math questions.",

+ "tools": [

+ { "type": "code_interpreter" }

+ ],

+ "model": "gpt-4-1106-preview",

+ "file_ids": ["file_123abc456"]

+ }'

+```

+### Pass file to an individual thread

+In addition to making files accessible at the Assistants level you can pass files so they're only accessible to a particular thread.

+# [Python 1.x](#tab/python)

+```python

+from openai import AzureOpenAI

+

+client = AzureOpenAI(

+ api_key=os.getenv("AZURE_OPENAI_KEY"),

+ api_version="2024-02-15-preview",

+ azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")

+ )

+thread = client.beta.threads.create(

+ messages=[

+ {

+ "role": "user",

+ "content": "I need to solve the equation `3x + 11 = 14`. Can you help me?",

+ "file_ids": ["file.id"] # file id will look like: "assistant-R9uhPxvRKGH3m0x5zBOhMjd2"

+ }

+ ]

+)

+```

+# [REST](#tab/rest)

+```console

+curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/<YOUR-THREAD-ID>/messages?api-version=2024-02-15-preview \

+ -H "api-key: $AZURE_OPENAI_KEY" \

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

+ -d '{

+ "role": "user",

+ "content": "I need to solve the equation `3x + 11 = 14`. Can you help me?",

+ "file_ids": ["file_123abc456"]

+ }'

+```

+## Download files generated by Code Interpreter

+Files generated by Code Interpreter can be found in the Assistant message responses

+```json

+ {

+ "id": "msg_oJbUanImBRpRran5HSa4Duy4",

+ "assistant_id": "asst_eHwhP4Xnad0bZdJrjHO2hfB4",

+ "content": [

+ {

+ "image_file": {

+ "file_id": "file-1YGVTvNzc2JXajI5JU9F0HMD"

+ },

+ "type": "image_file"

+ },

+ # ...

+ }

+```

+You can download these generated files by passing the files to the files API:

+# [Python 1.x](#tab/python)

+```python

+from openai import AzureOpenAI

+

+client = AzureOpenAI(

+ api_key=os.getenv("AZURE_OPENAI_KEY"),

+ api_version="2024-02-15-preview",

+ azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")

+ )

+image_data = client.files.content("file-abc123")

+image_data_bytes = image_data.read()

+with open("./my-image.png", "wb") as file:

+ file.write(image_data_bytes)

+```

+# [REST](#tab/rest)

+```console

+curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/files/<YOUR-FILE-ID>/content?api-version=2024-02-15-preview \

+ -H "api-key: $AZURE_OPENAI_KEY" \

+ --output image.png

+```

+## See also

+* Learn more about how to use Assistants with our [How-to guide on Assistants](../how-to/assistant.md).

+* [Azure OpenAI Assistants API samples](https://github.com/Azure-Samples/azureai-samples/tree/main/scenarios/Assistants)

+ Title: Fine-tuning function calls with Azure OpenAI Service

+description: Learn how to improve function calling performance with Azure OpenAI fine-tuning

+#

+# Fine-tuning and function calling

+Models that use the chat completions API support [function calling](../how-to/function-calling.md). Unfortunately, functions defined in your chat completion calls don't always perform as expected. Fine-tuning your model with function calling examples can improve model output by enabling you to:

+* Get similarly formatted responses even when the full function definition isn't present. (Allowing you to potentially save money on prompt tokens.)

+* Get more accurate and consistent outputs.

+> [!IMPORTANT]

+> The `functions` and `function_call` parameters have been deprecated with the release of the [`2023-12-01-preview`](https://github.com/Azure/azure-rest-api-specs/blob/main/specification/cognitiveservices/data-plane/AzureOpenAI/inference/preview/2023-12-01-preview/inference.json) version of the API. However, the fine-tuning API currently requires use of the legacy parameters.

+## Constructing a training file

+When constructing a training file of function calling examples, you would take a function definition like this:

+```json

+{

+ "messages": [

+ {"role": "user", "content": "What is the weather in San Francisco?"},

+ {"role": "assistant", "function_call": {"name": "get_current_weather", "arguments": "{\"location\": \"San Francisco, USA\", \"format\": \"celsius\"}"}

+ ],

+ "functions": [{

+ "name": "get_current_weather",

+ "description": "Get the current weather",

+ "parameters": {

+ "type": "object",

+ "properties": {

+ "location": {"type": "string", "description": "The city and country, eg. San Francisco, USA"},

+ "format": {"type": "string", "enum": ["celsius", "fahrenheit"]}

+ },

+ "required": ["location", "format"]

+ }

+ }]

+}

+```

+And express the information as a single line within your `.jsonl` training file as below:

+```jsonl

+{"messages": [{"role": "user", "content": "What is the weather in San Francisco?"}, {"role": "assistant", "function_call": {"name": "get_current_weather", "arguments": "{\"location\": \"San Francisco, USA\", \"format\": \"celsius\"}"}}], "functions": [{"name": "get_current_weather", "description": "Get the current weather", "parameters": {"type": "object", "properties": {"location": {"type": "string", "description": "The city and country, eg. San Francisco, USA"}, "format": {"type": "string", "enum": ["celsius", "fahrenheit"]}}, "required": ["location", "format"]}}]}

+```

+As with all fine-tuning training your example file requires at least 10 examples.

+## Optimize for cost

+OpenAI recommends that if you're trying to optimize to use fewer prompt tokens post fine-tuning your model on the full function definitions you can experiment with:

+* Omit function and parameter descriptions: remove the description field from function and parameters.

+* Omit parameters: remove the entire properties field from the parameters object.

+* Omit function entirely: remove the entire function object from the functions array.

+## Optimize for quality

+Alternatively, if you're trying to improve the quality of the function calling output, it's recommended that the function definitions present in the fine-tuning training dataset and subsequent chat completion calls remain identical.

+## Customize model responses to function outputs

+Fine-tuning based on function calling examples can also be used to improve the model's response to function outputs. To accomplish this, you include examples consisting of function response messages and assistant response messages where the function response is interpreted and put into context by the assistant.

+```json

+{

+ "messages": [

+ {"role": "user", "content": "What is the weather in San Francisco?"},

+ {"role": "assistant", "function_call": {"name": "get_current_weather", "arguments": "{\"location\": \"San Francisco, USA\", \"format\": \"celcius\"}"}}

+ {"role": "function", "name": "get_current_weather", "content": "21.0"},

+ {"role": "assistant", "content": "It is 21 degrees celsius in San Francisco, CA"}

+ ],

+ "functions": [...] // same as before

+}

+```

+As with the example before, this example is artificially expanded for readability. The actual entry in the `.jsonl` training file would be a single line:

+```jsonl

+{"messages": [{"role": "user", "content": "What is the weather in San Francisco?"}, {"role": "assistant", "function_call": {"name": "get_current_weather", "arguments": "{\"location\": \"San Francisco, USA\", \"format\": \"celcius\"}"}}, {"role": "function", "name": "get_current_weather", "content": "21.0"}, {"role": "assistant", "content": "It is 21 degrees celsius in San Francisco, CA"}], "functions": []}

+```

+## Next steps

+- Explore the fine-tuning capabilities in the [Azure OpenAI fine-tuning tutorial](../tutorials/fine-tune.md).

+- Review fine-tuning [model regional availability](../concepts/models.md#fine-tuning-models)

+## Troubleshooting

+### How do I enable fine-tuning? Create a custom model is greyed out in Azure OpenAI Studio?

+In order to successfully access fine-tuning, you need **Cognitive Services OpenAI Contributor assigned**. Even someone with high-level Service Administrator permissions would still need this account explicitly set in order to access fine-tuning. For more information, please review the [role-based access control guidance](/azure/ai-services/openai/how-to/role-based-access-control#cognitive-services-openai-contributor).

+

+## Next steps

+- Explore the fine-tuning capabilities in the [Azure OpenAI fine-tuning tutorial](../tutorials/fine-tune.md).

+- Review fine-tuning [model regional availability](../concepts/models.md#fine-tuning-models)

+When **Auto-update to default** is selected your model deployment will be automatically updated within two weeks of a change in the default version. For a preview version, it will update automatically when a new preview version is available starting two weeks after the new preview version is released.

+Azure OpenAI Service gives customers advanced language AI with OpenAI GPT-4, GPT-3, Codex, DALL-E, Whisper, and text to speech models with the security and enterprise promise of Azure. Azure OpenAI co-develops the APIs with OpenAI, ensuring compatibility and a smooth transition from one to the other.

+The text to speech models, currently in preview, can be used to synthesize text to speech.

+| Max training jobs queued | 20 |

+| Max Files per resource (fine-tuning) | 30 |

+| Total size of all files per resource (fine-tuning) | 1 GB |

+| Max files per Assistant/thread | 20 |

+| Max file size for Assistants | 512 MB |

+| Assistants token limit | 2,000,000 token limit |

+description: Learn how to use Azure OpenAI's REST API. In this article, you learn about authorization options, how to structure a request and receive a response.

+With the Completions operation, the model generates one or more predicted completions based on a provided prompt. The service can also return the probabilities of alternative tokens at each position.

+| ```prompt``` | string or array | Optional | ```<\|endoftext\|>``` | The prompt(s) to generate completions for, encoded as a string, or array of strings. Note that ```<\|endoftext\|>``` is the document separator that the model sees during training, so if a prompt isn't specified the model generates as if from the beginning of a new document. |

+| ```temperature``` | number | Optional | 1 | What sampling temperature to use, between 0 and 2. Higher values means the model takes more risks. Try 0.9 for more creative applications, and 0 (`argmax sampling`) for ones with a well-defined answer. We generally recommend altering this or top_p but not both. |

+| ```logit_bias``` | map | Optional | null | Modify the likelihood of specified tokens appearing in the completion. Accepts a json object that maps tokens (specified by their token ID in the GPT tokenizer) to an associated bias value from -100 to 100. You can use this tokenizer tool (which works for both GPT-2 and GPT-3) to convert text to token IDs. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect varies per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token. As an example, you can pass {"50256": -100} to prevent the <\|endoftext\|> token from being generated. |

+| ```stream``` | boolean | Optional | False | Whether to stream back partial progress. If set, tokens are sent as data-only server-sent events as they become available, with the stream terminated by a data: [DONE] message.|

+| ```logit_bias``` | object | Optional | null | Modify the likelihood of specified tokens appearing in the completion. Accepts a json object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect varies per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.|

+|```function_call```| | Optional | | `[Deprecated in 2023-12-01-preview replacement paremeter is tools_choice]`Controls how the model responds to function calls. "none" means the model doesn't call a function, and responds to the end-user. "auto" means the model can pick between an end-user or calling a function. Specifying a particular function via {"name": "my_function"} forces the model to call that function. "none" is the default when no functions are present. "auto" is the default if functions are present. This parameter requires API version [`2023-07-01-preview`](https://github.com/Azure/azure-rest-api-specs/blob/main/specification/cognitiveservices/data-plane/AzureOpenAI/inference/preview/2023-07-01-preview/generated.json) |

+|```tools```| string (The type of the tool. Only [`function`](#function) is supported.) | Optional | |A list of tools the model can call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model can generate JSON inputs for. This parameter requires API version [`2023-12-01-preview`](https://github.com/Azure/azure-rest-api-specs/blob/main/specification/cognitiveservices/data-plane/AzureOpenAI/inference/preview/2023-12-01-preview/generated.json) |

+|```tool_choice```| string or object | Optional | none is the default when no functions are present. auto is the default if functions are present. | Controls which (if any) function is called by the model. none means the model won't call a function and instead generates a message. auto means the model can pick between generating a message or calling a function. Specifying a particular function via {"type: "function", "function": {"name": "my_function"}} forces the model to call that function. This parameter requires API version [`2023-12-01-preview`](https://github.com/Azure/azure-rest-api-specs/blob/main/specification/cognitiveservices/data-plane/AzureOpenAI/inference/preview/2023-12-01-preview/inference.json)|

+| arguments | string | The arguments to call the function with, as generated by the model in JSON format. The model doesn't always generate valid JSON, and might fabricate parameters not defined by your function schema. Validate the arguments in your code before calling your function. |

+| description | string | A description of what the function does. The model uses this description when selecting the function and interpreting its parameters. |

+| `stream` | boolean | Optional | false | If set, partial message deltas are sent, like in ChatGPT. Tokens are sent as data-only server-sent events as they become available, with the stream terminated by a message `"messages": [{"delta": {"content": "[DONE]"}, "index": 2, "end_turn": true}]` |

+| `stop` | string or array | Optional | null | Up to two sequences where the API will stop generating further tokens. |

+| `inScope` | boolean | Optional | true | If set, this value limits responses specific to the grounding data content. |

+| `embeddingDeploymentName` | string | Optional | null | The Ada embedding model deployment name within the same Azure OpenAI resource. Used instead of `embeddingEndpoint` and `embeddingKey` for [vector search](./concepts/use-your-data.md#search-options). Should only be used when both the `embeddingEndpoint` and `embeddingKey` parameters are defined. When this parameter is provided, Azure OpenAI on your data use an internal call to evaluate the Ada embedding model, rather than calling the Azure OpenAI endpoint. This enables you to use vector search in private networks and private endpoints. Billing remains the same whether this parameter is defined or not. Available in regions where embedding models are [available](./concepts/models.md#embeddings-models) starting in API versions `2023-06-01-preview` and later.|

+| `queryType` | string | Optional | simple | Indicates which query option is used for Azure AI Search. Available types: `simple`, `semantic`, `vector`, `vectorSimpleHybrid`, `vectorSemanticHybrid`. |

+| `searchServiceAdminKey` | string | Optional | null | If provided, the key is used to authenticate with the `searchServiceEndpoint`. If not provided, the system-assigned identity of the Azure OpenAI resource will be used. In this case, the system-assigned identity must have "Search Service Contributor" role assignment on the search resource. |

+| `embeddingEndpoint` | string | Optional | null | Not required if you use semantic or only keyword search. It's required if you use vector, hybrid, or hybrid + semantic search |

+| `embeddingKey` | string | Optional | null | The key of the embedding endpoint. This is required if the embedding endpoint isn't empty. |

+| `url` | string | Optional | null | If URL isn't null, the provided url is crawled into the provided storage container and then ingested accordingly.|

+| ```your-resource-name``` | string | Required | The name of your Azure OpenAI resource. |

+| ```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). |

+| ```your-resource-name``` | string | Required | The name of your Azure OpenAI resource. |

+## Text to speech

+Synthesize text to speech.

+```http

+POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/speech?api-version={api-version}

+```

+**Path parameters**

+| Parameter | Type | Required? | Description |

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

+| ```your-resource-name``` | string | Required | The name of your Azure OpenAI resource. |

+| ```deployment-id``` | string | Required | The name of your text to speech model deployment such as *MyTextToSpeechDeployment*. You're required to first deploy a text to speech model (such as `tts-1` or `tts-1-hd`) before you can make calls. |

+| ```api-version``` | string | Required |The API version to use for this operation. This value follows the YYYY-MM-DD format. |

+**Supported versions**

+- `2024-02-15-preview`

+**Request body**

+| Parameter | Type | Required? | Default | Description |

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

+| ```model```| string | Yes | N/A | One of the available TTS models: `tts-1` or `tts-1-hd` |

+| ```input``` | string | Yes | N/A | The text to generate audio for. The maximum length is 4096 characters. Specify input text in the language of your choice.¹ |

+| ```voice``` | string | Yes | N/A | The voice to use when generating the audio. Supported voices are `alloy`, `echo`, `fable`, `onyx`, `nova`, and `shimmer`. Previews of the voices are available in the [OpenAI text to speech guide](https://platform.openai.com/docs/guides/text-to-speech/voice-options). |

+¹ The text to speech models generally support the same languages as the Whisper model. For the list of supported languages, see the [OpenAI documentation](https://platform.openai.com/docs/guides/speech-to-text/supported-languages).

+### Example request

+```console

+curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/audio/speech?api-version=2024-02-15-preview \

+ -H "api-key: $YOUR_API_KEY" \

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

+ -d '{

+ "model": "tts-hd",

+ "input": "I'm excited to try text to speech.",

+ "voice": "alloy"

+}' --output speech.mp3

+```

+### Example response

+The speech is returned as an audio file from the previous request.

+Learn about [Models, and fine-tuning with the REST API](/rest/api/azureopenai/fine-tuning?view=rest-azureopenai-2023-10-01-preview).

+ Title: 'Text to speech with Azure OpenAI Service'

+description: Use the Azure OpenAI Service for text to speech with OpenAI voices.

+recommendations: false

+# Quickstart: Text to speech with the Azure OpenAI Service

+In this quickstart, you use the Azure OpenAI Service for text to speech with OpenAI voices.

+The available voices are: `alloy`, `echo`, `fable`, `onyx`, `nova`, and `shimmer`. For more information, see [Azure OpenAI Service reference documentation for text to speech](./reference.md#text-to-speech).

+## Prerequisites

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

+- Access granted to Azure OpenAI Service in the desired Azure subscription.

+- An Azure OpenAI resource created in the North Central US or Sweden Central regions with the `tts-1` or `tts-1-hd` model deployed. For more information, see [Create a resource and deploy a model with Azure OpenAI](how-to/create-resource.md).

+> [!NOTE]

+> Currently, you must submit an application to access Azure OpenAI Service. To apply for access, complete [this form](https://aka.ms/oai/access).

+## Set up

+### Retrieve key and endpoint

+To successfully make a call against Azure OpenAI, you need an **endpoint** and a **key**.

+|Variable name | Value |

+|--|-|

+| `AZURE_OPENAI_ENDPOINT` | This value can be found in the **Keys & Endpoint** section when examining your resource from the Azure portal. Alternatively, you can find the value in the **Azure OpenAI Studio** > **Playground** > **Code View**. An example endpoint is: `https://aoai-docs.openai.azure.com/`.|

+| `AZURE_OPENAI_KEY` | This value can be found in the **Keys & Endpoint** section when examining your resource from the Azure portal. You can use either `KEY1` or `KEY2`.|

+Go to your resource in the Azure portal. The **Endpoint and Keys** can be found in the **Resource Management** section. Copy your endpoint and access key as you need both for authenticating your API calls. You can use either `KEY1` or `KEY2`. Always having two keys allows you to securely rotate and regenerate keys without causing a service disruption.

+Create and assign persistent environment variables for your key and endpoint.

+### Environment variables

+# [Command Line](#tab/command-line)

+```CMD

+setx AZURE_OPENAI_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE"

+```

+```CMD

+setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

+```

+# [PowerShell](#tab/powershell)

+```powershell

+[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_KEY', 'REPLACE_WITH_YOUR_KEY_VALUE_HERE', 'User')

+```

+```powershell

+[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_ENDPOINT', 'REPLACE_WITH_YOUR_ENDPOINT_HERE', 'User')

+```

+# [Bash](#tab/bash)

+```Bash

+echo export AZURE_OPENAI_KEY="REPLACE_WITH_YOUR_KEY_VALUE_HERE" >> /etc/environment && source /etc/environment

+```

+```Bash

+echo export AZURE_OPENAI_ENDPOINT="REPLACE_WITH_YOUR_ENDPOINT_HERE" >> /etc/environment && source /etc/environment

+```

+## Clean up resources

+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.

+- [Portal](../multi-service-resource.md?pivots=azportal#clean-up-resources)

+- [Azure CLI](../multi-service-resource.md?pivots=azcli#clean-up-resources)

+## Next steps

+* Learn more about how to work with text to speech with Azure OpenAI Service in the [Azure OpenAI Service reference documentation](./reference.md#text-to-speech).

+* For more examples, check out the [Azure OpenAI Samples GitHub repository](https://aka.ms/AOAICodeSamples)

+## February 2024

+### Assistants API public preview

+Azure OpenAI now supports the API that powers OpenAI's GPTs. Azure OpenAI Assistants (Preview) allows you to create AI assistants tailored to your needs through custom instructions and advanced tools like code interpreter, and custom functions. To learn more, see:

+- [Quickstart](./assistants-quickstart.md)

+- [Concepts](./concepts/assistants.md)

+- [In-depth Python how-to](./how-to/assistant.md)

+- [Code Interpreter](./how-to/code-interpreter.md)

+- [Function calling](./how-to/assistant-functions.md)

+- [Assistants model & region availability](./concepts/models.md#assistants-preview)

+- [Assistants Samples](https://github.com/Azure-Samples/azureai-samples/tree/main/scenarios/Assistants)

+### OpenAI text to speech voices public preview

+Azure OpenAI Service now supports text to speech APIs with OpenAI's voices. Get AI-generated speech from the text you provide. To learn more, see the [overview guide](../speech-service/openai-voices.md) and try the [quickstart](./text-to-speech-quickstart.md).

+> [!NOTE]

+> Azure AI Speech also supports OpenAI text to speech voices. To learn more, see [OpenAI text to speech voices via Azure OpenAI Service or via Azure AI Speech](../speech-service/openai-voices.md#openai-text-to-speech-voices-via-azure-openai-service-or-via-azure-ai-speech) guide.

+### New Fine-tuning capabilities and model support

+- [Continuous fine-tuning](https://aka.ms/oai/fine-tuning-continuous)

+- [Fine-tuning & function calling](./how-to/fine-tuning-functions.md)

+- [`gpt-35-turbo 1106` support](./concepts/models.md#fine-tuning-models)

+### Chunk size parameter for Azure OpenAI on your data

+- You can now set the [chunk size](./concepts/use-your-data.md#ingestion-parameters) parameter when your data is ingested. Adjusting the chunk size can enhance the model's responses by setting the maximum number of tokens for any given chunk of your data in the search index.

+- New [custom parameters](./concepts/use-your-data.md#runtime-parameters) for determining the number of retrieved documents and strictness.

+> [!NOTE]

+> Currently, you must submit an application to access Azure OpenAI Service. To apply for access, complete [this form](https://aka.ms/oai/access).

+ <version>1.35.0</version>

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

+Multilingual voices can support more languages. This expansion enhances your ability to express content in various languages, to overcome language barriers and foster a more inclusive global communication environment.

+Use this table to understand all supported speaking languages for each multilingual neural voice. If the voice doesnΓÇÖt speak the language of the input text, the Speech service doesnΓÇÖt output synthesized audio. The table is sorted by the number of supported languages in descending order. The primary locale for each voice is indicated by the prefix in its name, such as the voice `en-US-AndrewMultilingualNeural`, its primary locale is `en-US`.

+The table in this section summarizes the 26 locales supported for pronunciation assessment, and each language is available on all [Speech to text regions](regions.md#speech-service). Latest update extends support from English to 25 more languages and quality enhancements to existing features, including accuracy, fluency and miscue assessment. You should specify the language that you're learning or practicing improving pronunciation. The default language is set as `en-US`. If you know your target learning language, [set the locale](how-to-pronunciation-assessment.md#get-pronunciation-assessment-results) accordingly. For example, if you're learning British English, you should specify the language as `en-GB`. If you're teaching a broader language, such as Spanish, and are uncertain about which locale to select, you can run various accent models (`es-ES`, `es-MX`) to determine the one that achieves the highest score to suit your specific scenario.

+ Title: What are OpenAI text to speech voices?

+description: Learn about OpenAI text to speech voices that you can use with speech synthesis.

+#customer intent: As a user who implements text to speech, I want to understand the options and differences between available OpenAI text to speech voices in Azure AI services.

+# What are OpenAI text to speech voices?

+Like Azure AI Speech voices, OpenAI text to speech voices deliver high-quality speech synthesis to convert written text into natural sounding spoken audio. This unlocks a wide range of possibilities for immersive and interactive user experiences.

+OpenAI text to speech voices are available via two model variants: `Neural` and `NeuralHD`.

+- `Neural`: Optimized for real-time use cases with the lowest latency, but lower quality than `NeuralHD`.

+- `NeuralHD`: Optimized for quality.

+## Available text to speech voices in Azure AI services

+You might ask: If I want to use an OpenAI text to speech voice, should I use it via the Azure OpenAI Service or via Azure AI Speech? What are the scenarios that guide me to use one or the other?

+Each voice model offers distinct features and capabilities, allowing you to choose the one that best suits your specific needs. You want to understand the options and differences between available text to speech voices in Azure AI services.

+You can choose from the following text to speech voices in Azure AI

+- OpenAI text to speech voices in [Azure OpenAI Service](../openai/reference.md#text-to-speech). Available in the following regions: North Central US and Sweden Central.

+- OpenAI text to speech voices in [Azure AI Speech](./language-support.md?tabs=tts#multilingual-voices). Available in the following regions: North Central US and Sweden Central.

+- Azure AI Speech service [text to speech voices](./language-support.md?tabs=tts#prebuilt-neural-voices). Available in dozens of regions. See the [region list](regions.md#speech-service).

+## OpenAI text to speech voices via Azure OpenAI Service or via Azure AI Speech?

+If you want to use OpenAI text to speech voices, you can choose whether to use them via [Azure OpenAI](../openai/text-to-speech-quickstart.md) or via [Azure AI Speech](./get-started-text-to-speech.md#openai-text-to-speech-voices-in-azure-ai-speech). In either case, the speech synthesis result is the same.

+Here's a comparison of features between OpenAI text to speech voices in Azure OpenAI Service and OpenAI text to speech voices in Azure AI Speech.

+| Feature | Azure OpenAI Service (OpenAI voices) | Azure AI Speech (OpenAI voices) | Azure AI Speech voices |

+||||

+| **Region** | North Central US, Sweden Central | North Central US, Sweden Central | Available in dozens of regions. See the [region list](regions.md#speech-service).|

+| **Voice variety** | 6 | 6 | More than 400 |

+| **Multilingual voice number** | 6 | 6 | 14 |

+| **Max multilingual language coverage** | 57 | 57 | 77 |

+| **Speech Synthesis Markup Language (SSML) support** | Not supported | Support for [a subset of SSML elements](#ssml-elements-supported-by-openai-text-to-speech-voices-in-azure-ai-speech). | Support for the [full set of SSML](speech-synthesis-markup-structure.md) in Azure AI Speech. |

+| **Development options** | REST API | Speech SDK, Speech CLI, REST API | Speech SDK, Speech CLI, REST API |

+| **Deployment option** | Cloud only | Cloud only | Cloud, embedded, hybrid, and containers. |

+| **Real-time or batch synthesis** | Real-time | Real-time and batch synthesis | Real-time and batch synthesis |

+| **Latency** | greater than 500 ms | greater than 500 ms | less than 300 ms |

+| **Sample rate of synthesized audio** | 24 kHz | 8, 16, 24, and 48 kHz | 8, 16, 24, and 48 kHz |

+| **Speech output audio format** | opus, mp3, aac, flac | opus, mp3, pcm, truesilk | opus, mp3, pcm, truesilk |

+## SSML elements supported by OpenAI text to speech voices in Azure AI Speech

+The [Speech Synthesis Markup Language (SSML)](./speech-synthesis-markup.md) with input text determines the structure, content, and other characteristics of the text to speech output. For example, you can use SSML to define a paragraph, a sentence, a break or a pause, or silence. You can wrap text with event tags such as bookmark or viseme that can be processed later by your application.

+The following table outlines the Speech Synthesis Markup Language (SSML) elements supported by OpenAI text to speech voices in Azure AI speech. Only a subset of SSML tags are supported for OpenAI voices. See [SSML document structure and events](speech-synthesis-markup-structure.md) for more information.

+| SSML element name | Description |

+| | |

+| `<speak>` | Encloses the entire content to be spoken. ItΓÇÖs the root element of an SSML document. |

+| `<voice>` | Specifies a voice used for text to speech output. |

+| `<sub>` | Indicates that the alias attribute's text value should be pronounced instead of the element's enclosed text. |

+| `<say-as>` | Indicates the content type, such as number or date, of the element's text.<br/><br/>All of the `interpret-as` property values are supported for this element except `interpret-as="name"`. For example, `<say-as interpret-as="date" format="dmy">10-12-2016</say-as>` is supported, but `<say-as interpret-as="name">ED</say-as>` isn't supported. For more information, see [pronunciation with SSML](./speech-synthesis-markup-pronunciation.md#say-as-element). |

+| `<s>` | Denotes sentences. |

+| `<lang>` | Indicates the default locale for the language that you want the neural voice to speak. |

+| `<break>` | Use to override the default behavior of breaks or pauses between words. |

+## Next steps

+- [Try the text to speech quickstart in Azure AI Speech](get-started-text-to-speech.md#openai-text-to-speech-voices-in-azure-ai-speech)

+- [Try the text to speech via Azure OpenAI Service](../openai/text-to-speech-quickstart.md)

+By default, multilingual voices can autodetect the language of the input text and speak in the language of the default locale of the input text without using SSML. Optionally, you can use the `<lang xml:lang>` element to adjust the speaking language for these voices to set the preferred accent such as `en-GB` for British English. You can adjust the speaking language at both the sentence level and word level. For information about the supported languages for multilingual voice, see [Multilingual voices with the lang element](#multilingual-voices-with-the-lang-element) for a table showing the `<lang>` syntax and attribute definitions.

+| Voice | Supported language number | Supported languages | Auto-detected default locale for each language |

+|`en-US-AndrewMultilingualNeural`^1,2 (Male)<br/>`en-US-AvaMultilingualNeural`^1,2 (Female)<br/>`en-US-BrianMultilingualNeural`^1,2 (Male)<br/>`en-US-EmmaMultilingualNeural`^1,2 (Female)| 77 | Afrikaans, Albanian, Amharic, Arabic, Armenian, Azerbaijani, Bahasa Indonesian, Bangla, Basque, Bengali, Bosnian, Bulgarian, Burmese, Catalan, Chinese Cantonese, Chinese Mandarin, Chinese Taiwanese, Croatian, Czech, Danish, Dutch, English, Estonian, Filipino, Finnish, French, Galician, Georgian, German, Greek, Hebrew, Hindi, Hungarian, Icelandic, Irish, Italian, Japanese, Javanese, Kannada, Kazakh, Khmer, Korean, Lao, Latvian, Lithuanian, Macedonian, Malay, Malayalam, Maltese, Mongolian, Nepali, Norwegian Bokmål, Pashto, Persian, Polish, Portuguese, Romanian, Russian, Serbian, Sinhala, Slovak, Slovene, Somali, Spanish, Sundanese, Swahili, Swedish，Tamil, Telugu, Thai, Turkish, Ukrainian, Urdu, Uzbek, Vietnamese, Welsh, Zulu |`af-ZA`, `am-ET`, `ar-EG`, `az-AZ`, `bg-BG`, `bn-BD`, `bn-IN`, `bs-BA`, `ca-ES`, `cs-CZ`, `cy-GB`, `da-DK`, `de-DE`, `el-GR`, `en-US`, `es-ES`, `et-EE`, `eu-ES`, `fa-IR`, `fi-FI`, `fil-PH`, `fr-FR`, `ga-IE`, `gl-ES`, `he-IL`, `hi-IN`, `hr-HR`, `hu-HU`, `hy-AM`, `id-ID`, `is-IS`, `it-IT`, `ja-JP`, `jv-ID`, `ka-GE`, `kk-KZ`, `km-KH`, `kn-IN`, `ko-KR`, `lo-LA`, `lt-LT`, `lv-LV`, `mk-MK`, `ml-IN`, `mn-MN`, `ms-MY`, `mt-MT`, `my-MM`, `nb-NO`, `ne-NP`, `nl-NL`, `pl-PL`, `ps-AF`, `pt-BR`, `ro-RO`, `ru-RU`, `si-LK`, `sk-SK`, `sl-SI`, `so-SO`, `sq-AL`, `sr-RS`, `su-ID`, `sv-SE`, `sw-KE`, `ta-IN`, `te-IN`, `th-TH`, `tr-TR`, `uk-UA`, `ur-PK`, `uz-UZ`, `vi-VN`, `zh-CN`, `zh-HK`, `zh-TW`, `zu-ZA`.|

+² Those are neural multilingual voices in Azure AI Speech. All multilingual voices (except `en-US-JennyMultilingualNeural`) can speak in the language in default locale of the input text without [using SSML](#adjust-speaking-languages). However, you can still use the `<lang xml:lang>` element to adjust the speaking accent of each language to set preferred accent such as British accent (`en-GB`) for English. The primary locale for each voice is indicated by the prefix in its name, such as the voice `en-US-AndrewMultilingualNeural`, its primary locale is `en-US`. Check the [full list](https://speech.microsoft.com/portal/voicegallery) of supported locales through SSML.

+ Title: Azure AI hub resource concepts

+description: This article introduces concepts about Azure AI hub resources.

+# Azure AI hub resources

+The Azure AI hub resource is the top-level Azure resource for AI Studio and provides the working environment for a team to build and manage AI applications. In Azure, resources enable access to Azure services for individuals and teams. Resources also provide a container for billing, security configuration and monitoring.

+The Azure AI hub resource can be used to access [multiple Azure AI services](#azure-ai-services-api-access-keys) with a single setup. Previously, different Azure AI services including [Azure OpenAI](../../ai-services/openai/overview.md), [Azure Machine Learning](../../machine-learning/overview-what-is-azure-machine-learning.md), [Azure AI Speech](../../ai-services/speech-service/overview.md), required their individual setup.

+In this article, you learn more about Azure AI hub resource's capabilities, and how to set up Azure AI for your organization. You can see the resources created in the [Azure portal](https://portal.azure.com/) and in [Azure AI Studio](https://ai.azure.com).

+The Azure AI hub resource provides the collaboration environment for a team to build and manage AI applications, catering to two personas:

+* To AI developers, the Azure AI hub resource provides the working environment for building AI applications granting access to various tools for AI model building. Tools can be used together, and lets you use and produce shareable components including datasets, indexes, models. An Azure AI hub resource allows you to configure connections to external resources, provide compute resources used by tools and [endpoints and access keys to prebuilt AI models](#azure-ai-services-api-access-keys). When you use a project to customize AI capabilities, it's hosted by an Azure AI hub resource and can access the same shared resources.

+* To IT administrators, team leads and risk officers, the Azure AI hub resource provides a single pane of glass on projects created by a team, audit connections that are in use to external resources, and other governance controls to help meet cost and compliance requirements. Security settings are configured on the Azure AI hub resource, and once set up apply to all projects created under it, allowing administrators to enable developers to self-serve create projects to organize work.

+Various management concepts are available on Azure AI hub resources to support team leads and admins to centrally manage a team's environment.

+* **Security configuration** including public network access, [virtual networking](#virtual-networking), customer-managed key encryption, and privileged access to whom can create projects for customization. Security settings configured on the Azure AI hub resource automatically pass down to each project. A managed virtual network is shared between all projects that share the same Azure AI hub resource.

+* **Compute and quota allocation** is managed as shared capacity for all projects in AI Studio that share the same Azure AI hub resource. This includes compute instance as managed cloud-based workstation for an individual. Compute instance can be used across projects by the same user.

+* **AI services access keys** to endpoints for prebuilt AI models are managed on the Azure AI hub resource scope. Use these endpoints to access foundation models from Azure OpenAI, Speech, Vision, and Content Safety with one [API key](#azure-ai-services-api-access-keys)

+* **Policy** enforced in Azure on the Azure AI hub resource scope applies to all projects managed under it.

+* **Dependent Azure resources** are set up once per Azure AI hub resource and associated projects and used to store artifacts you generate while working in AI Studio such as logs or when uploading data. See [Azure AI dependencies](#azure-ai-dependencies) for more details.

+An Azure AI hub resource provides the hosting environment for [Azure AI projects](../how-to/create-projects.md) in AI Studio. A project is an organizational container that has tools for AI customization and orchestration, lets you organize your work, save state across different tools like prompt flow, and collaborate with others. For example, you can share uploaded files and connections to data sources.

+Multiple projects can use an Azure AI hub resource, and a project can be used by multiple users. A project also helps you keep track of billing, and manage access and provides data isolation. Every project has dedicated storage containers to let you upload files and share it with only other project members when using the 'data' experiences.

+Projects let you create and group reusable components that can be used across tools in AI Studio:

+| Project connections | Connections to external resources like data storage providers that only you and other project members can use. They complement shared connections on the Azure AI hub resource accessible to all projects.|

+> In AI Studio you can also manage language and notification settings that apply to all Azure AI Studio projects that you can access regardless of the Azure AI hub resource or project.

+The Azure AI hub resource exposes API endpoints and keys for prebuilt AI services that are created by Microsoft such as Azure OpenAI Service. Which precise services are available to you is subject to your Azure region and your chosen Azure AI services provider at the time of setup ('advanced' option):

+* If you create an Azure AI hub resource together with an existing Azure OpenAI Service resource, you only have capabilities for Azure OpenAI Service. Use this option if you'd like to reuse existing Azure OpenAI quota and models deployments. Currently, there's no upgrade path to get Speech and Vision capabilities after the AI hub is created.

+* If you create an Azure AI hub resource together with an Azure AI services provider, you can use Azure OpenAI Service and other AI services such as Speech and Vision. Currently, this option is only available via the Azure AI CLI and SDK.

+To understand the full layering of Azure AI hub resources and its Azure dependencies including the Azure AI services provider, and how these is represented in Azure AI Studio and in the Azure portal, see [Find Azure AI Studio resources in the Azure portal](#find-azure-ai-studio-resources-in-the-azure-portal).

+Large language models that can be used to generate text, speech, images, and more, are hosted by the Azure AI hub resource. Fine-tuned models and open models deployed from the [model catalog](../how-to/model-catalog.md) are always created in the project context for isolation.

+Azure AI hub resources, compute resources, and projects share the same Microsoft-managed Azure virtual network. After you configure the managed networking settings during the Azure AI hub resource creation process, all new projects created using that Azure AI hub resource will inherit the same virtual network settings. Therefore, any changes to the networking settings are applied to all current and new project in that Azure AI hub resource. By default, Azure AI hub resources provide public network access.

+To establish a private inbound connection to your Azure AI hub resource environment, create an Azure Private Link endpoint on the following scopes:

+* The Azure AI hub resource

+While projects show up as their own tracking resources in the Azure portal, they don't require their own private link endpoints to be accessed. New projects that are created after Azure AI hub resource setup, do automatically get added to the network-isolated environment.

+Connections can be set up as shared with all projects in the same Azure AI hub resource, or created exclusively for one project. To manage project connections via Azure AI Studio, navigate to a project page, then navigate to **Settings** > **Connections**. To manage shared connections, navigate to the **Manage** page. As an administrator, you can audit both shared and project-scoped connections on an Azure AI hub resource level to have a single pane of glass of connectivity across projects.

+Azure AI Studio layers on top of existing Azure services including Azure AI and Azure Machine Learning services. While this might not be visible on the display names in Azure portal, AI Studio, or when using the SDK or CLI, some of these architectural details become apparent when you work with the Azure REST APIs, use Azure cost reporting, or use infrastructure-as-code templates such as Azure Bicep or Azure Resource Manager. From an Azure Resource Provider perspective, Azure AI Studio resource types map to the following resource provider kinds:

+|Azure AI hub resources|Microsoft.MachineLearningServices/workspace|hub|

+When you create a new Azure AI hub resource, a set of dependent Azure resources are required to store data that you upload or get generated when working in AI Studio. If not provided by you, these resources are automatically created.

+|Azure AI services|Either Azure AI services multi-service provider, or Azure OpenAI Service. Provides API endpoints and keys for prebuilt AI services.|

+In general, an Azure AI hub resource and project don't have a fixed monthly cost, and you're only charged for usage in terms of compute hours and tokens used. Azure Key Vault, Storage, and Application Insights charge transaction and volume-based, dependent on the amount of data stored with your Azure AI projects.

+If you require to group costs of these different services together, we recommend creating Azure AI hub resources in one or more dedicated resource groups and subscriptions in your Azure environment.

+> This section assumes that the Azure AI hub resource and Azure AI project are in the same resource group.

+1. In [Azure AI Studio](https://ai.azure.com), go to **Build** > **Settings** to view your Azure AI project resources such as connections and API keys. There's a link to your Azure AI hub resource in Azure AI Studio and links to view the corresponding project resources in the [Azure portal](https://portal.azure.com).

+ :::image type="content" source="../media/concepts/azureai-project-view-ai-studio.png" alt-text="Screenshot of the Azure AI project and related resources in the Azure AI Studio." lightbox="../media/concepts/azureai-project-view-ai-studio.png":::

+1. Select the AI hub name to view your Azure AI hub's projects and shared connections. There's also a link to view the corresponding resources in the [Azure portal](https://portal.azure.com).

+ :::image type="content" source="../media/concepts/azureai-resource-view-ai-studio.png" alt-text="Screenshot of the Azure AI hub resource and related resources in the Azure AI Studio." lightbox="../media/concepts/azureai-resource-view-ai-studio.png":::

+1. Select **View in the Azure Portal** to see your Azure AI hub resource in the Azure portal.

+ :::image type="content" source="../media/concepts/ai-hub-azure-portal.png" alt-text="Screenshot of the Azure AI hub resource in the Azure portal." lightbox="../media/concepts/ai-hub-azure-portal.png":::

+ - Select the **AI Services provider** to see the keys and endpoints needed to authenticate your requests to Azure AI services such as Azure OpenAI. For more information, see [Azure AI services API access keys](#azure-ai-services-api-access-keys).

+ - Also from the Azure AI hub page, you can select the **Project resource group** to find your Azure AI project.

+- [Quickstart: Analyze images and video with GPT-4 for Vision in the playground](../quickstarts/multimodal-vision.md)

+Connections in Azure AI Studio are a way to authenticate and consume both Microsoft and third-party resources within your Azure AI projects. For example, connections can be used for prompt flow, training data, and deployments. [Connections can be created](../how-to/connections-add.md) exclusively for one project or shared with all projects in the same Azure AI hub resource.

+You can create connections to Azure AI services such as Azure OpenAI and Azure AI Content Safety. You can then use the connection in a prompt flow tool such as the LLM tool.

+Connections allow you to securely store credentials, authenticate access, and consume data and information. Secrets associated with connections are securely persisted in the corresponding Azure Key Vault, adhering to robust security and compliance standards. As an administrator, you can audit both shared and project-scoped connections on an Azure AI hub resource level (link to connection rbac).

+Azure connections serve as key vault proxies, and interactions with connections are direct interactions with an Azure key vault. Azure AI Studio connections store API keys securely, as secrets, in a key vault. The key vault [Azure role-based access control (Azure RBAC)](./rbac-ai-studio.md) controls access to these connection resources. A connection references the credentials from the key vault storage location for further use. You won't need to directly deal with the credentials after they are stored in the Azure AI hub resource's key vault. You have the option to store the credentials in the YAML file. A CLI command or SDK can override them. We recommend that you avoid credential storage in a YAML file, because a security breach could lead to a credential leak.

+Azure OpenAI allows you to get access to the latest OpenAI models with the enterprise features from Azure. Learn more about [how to deploy OpenAI models in AI Studio](../how-to/deploy-models-openai.md).

+At the model level, it's important to understand the models you use and what fine-tuning steps might have been taken by the model developers to align the model towards its intended uses and to reduce the risk of potentially harmful uses and outcomes. Azure AI Studio's model catalog enables you to explore models from Azure OpenAI Service, Meta, etc., organized by collection and task. In the [model catalog](../how-to/model-catalog.md), you can explore model cards to understand model capabilities and limitations, experiment with sample inferences, and assess model performance. You can further compare multiple models side-by-side through benchmarks to select the best one for your use case. Then, you can enhance model performance by fine-tuning with your training data.

+In this article, you learn how to manage access (authorization) to an Azure AI hub resource. Azure Role-based access control is used to manage access to Azure resources, such as the ability to create new resources or use existing ones. Users in your Microsoft Entra ID are assigned specific roles, which grant access to resources. Azure provides both built-in roles and the ability to create custom roles.

+## Azure AI hub resource vs Azure AI project

+In the Azure AI Studio, there are two levels of access: the Azure AI hub resource and the Azure AI project. The resource is home to the infrastructure (including virtual network setup, customer-managed keys, managed identities, and policies) as well as where you configure your Azure AI services. Azure AI hub resource access can allow you to modify the infrastructure, create new Azure AI hub resources, and create projects. Azure AI projects are a subset of the Azure AI hub resource that act as workspaces that allow you to build and deploy AI systems. Within a project you can develop flows, deploy models, and manage project assets. Project access lets you develop AI end-to-end while taking advantage of the infrastructure setup on the Azure AI hub resource.

+## Default roles for the Azure AI hub resource

+The Azure AI Studio has built-in roles that are available by default. In addition to the Reader, Contributor, and Owner roles, the Azure AI Studio has a new role called Azure AI Developer. This role can be assigned to enable users to create connections, compute, and projects, but not let them create new Azure AI hub resources or change permissions of the existing Azure AI hub resource.

+Here's a table of the built-in roles and their permissions for the Azure AI hub resource:

+| Owner | Full access to the Azure AI hub resource, including the ability to manage and create new Azure AI hub resources and assign permissions. This role is automatically assigned to the Azure AI hub resource creator|

+| Contributor | User has full access to the Azure AI hub resource, including the ability to create new Azure AI hub resources, but isn't able to manage Azure AI hub resource permissions on the existing resource. |

+| Azure AI Developer | Perform all actions except create new Azure AI hub resources and manage the Azure AI hub resource permissions. For example, users can create projects, compute, and connections. Users can assign permissions within their project. Users can interact with existing Azure AI resources such as Azure OpenAI, Azure AI Search, and Azure AI services. |

+| Reader | Read only access to the Azure AI hub resource. This role is automatically assigned to all project members within the Azure AI hub resource. |

+The key difference between Contributor and Azure AI Developer is the ability to make new Azure AI hub resources. If you don't want users to make new Azure AI hub resources (due to quota, cost, or just managing how many Azure AI hub resources you have), assign the AI Developer role.

+Only the Owner and Contributor roles allow you to make an Azure AI hub resource. At this time, custom roles won't grant you permission to make Azure AI hub resources.

+When a user gets access to a project, two more roles are automatically assigned to the project user. The first role is Reader on the Azure AI hub resource. The second role is the Inference Deployment Operator role, which allows the user to create deployments on the resource group that the project is in. This role is composed of these two permissions: ```"Microsoft.Authorization/*/read"``` and ```"Microsoft.Resources/deployments/*"```.

+| IT admin | Owner of the Azure AI hub resource | The IT admin can ensure the Azure AI hub resource is set up to their enterprise standards and assign managers the Contributor role on the resource if they want to enable managers to make new Azure AI hub resources or they can assign managers the Azure AI Developer role on the resource to not allow for new Azure AI hub resource creation. |

+| Managers | Contributor or Azure AI Developer on the Azure AI hub resource | Managers can create projects for their team and create shared resources (ex: compute and connections) for their group at the Azure AI hub resource level. |

+## Access to resources created outside of the Azure AI hub resource

+When you create an Azure AI hub resource, the built-in role-based access control permissions grant you access to use the resource. However, if you wish to use resources outside of what was created on your behalf, you need to ensure both:

+- Your Azure AI hub resource is allowed to access it.

+For example, if you're trying to consume a new Blob storage, you need to ensure that Azure AI hub resource's managed identity is added to the Blob Storage Reader role for the Blob. If you're trying to use a new Azure AI Search source, you might need to add the Azure AI hub resource to the Azure AI Search's role assignments.

+If you're an owner of an Azure AI hub resource, you can add and remove roles for the Studio. Within the Azure AI Studio, go to **Manage** and select your Azure AI hub resource. Then select **Permissions** to add and remove users for the Azure AI hub resource. You can also manage permissions from the Azure portal under **Access Control (IAM)** or through the Azure CLI. For example, use the [Azure CLI](/cli/azure/) to assign the Azure AI Developer role to "joe@contoso.com" for resource group "this-rg" with the following command:

+> In order to make a new Azure AI hub resource, you need the Owner or Contributor role. At this time, a custom role, even with all actions allowed, will not enable you to make an Azure AI hub resource.

+- [How to create an Azure AI hub resource](../how-to/create-azure-ai-resource.md)

+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.

+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.

+| 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. |

+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.

+- Azure AI

+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.

+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).

+- `ai service resource` lets you list, create or delete Azure AI hub resources.

+- `ai service project` lets you list, create, or delete Azure AI projects.

+Azure AI offers commitment tier pricing, each offering a discounted rate compared to the pay-as-you-go pricing model. With commitment tier pricing, you can commit to using the Azure AI hub resources and features for a fixed fee, enabling you to have a predictable total cost based on the needs of your workload.

+- [Managed identity configurations](#managed-identity-configuration) to allow Azure AI hub resources access your storage account if it's private.

+Use one of the following methods to create an Azure AI hub resource with a private endpoint. Each of these methods __requires an existing virtual network__:

+Create your Azure AI hub resource with the Azure AI CLI. Run the following command and follow the prompts. For more information, see [Get started with Azure AI CLI](cli-install.md).

+- [Learn more about Azure AI hub resources](../concepts/ai-resources.md)

+Connections are a way to authenticate and consume both Microsoft and third-party resources within your Azure AI projects. For example, connections can be used for prompt flow, training data, and deployments. [Connections can be created](../how-to/connections-add.md) exclusively for one project or shared with all projects in the same Azure AI hub resource.

+When you [create a new connection](#create-a-new-connection), you enter the following information for the service connection type you selected. You can create a connection that's only available for the current project or available for all projects associated with the Azure AI hub resource.

+> When you create a connection from the **Manage** page, the connection is always created at the Azure AI hub resource level and shared accross all associated projects.

+When you create resources for an Azure AI hub resource, resources for other Azure services are also created. They are:

+| [Azure AI services](https://azure.microsoft.com/pricing/details/cognitive-services/) | You pay to use services such as Azure OpenAI, Speech, Content Safety, Vision, Document Intelligence, and Language. Costs vary for each service and for some features within each service. For more information about provisioning of Azure AI services, see [Azure AI hub resources](../concepts/ai-resources.md#azure-ai-services-api-access-keys).|

+| [Azure AI Search](https://azure.microsoft.com/pricing/details/search/) | An example use case is to store data in a [vector search index](./index-add.md). |

+| [Azure Machine Learning](https://azure.microsoft.com/pricing/details/machine-learning/) | Compute instances are needed to run [Visual Studio Code (Web or Desktop)](./develop-in-vscode.md) and [prompt flow](./prompt-flow.md) via Azure AI Studio.<br/><br/>When you create a compute instance, the virtual machine (VM) stays on so it's available for your work.<br/><br/>Enable idle shutdown to save on cost when the VM is idle for a specified time period.<br/><br/>Or set up a schedule to automatically start and stop the compute instance to save cost when you aren't planning to use it. |

+| [Azure Blob Storage](https://azure.microsoft.com/pricing/details/storage/blobs/) | Can be used to store [Azure AI project](./create-projects.md) files. |

+Before you delete an Azure AI hub resource in the Azure portal or with Azure CLI, the following sub resources are common costs that accumulate even when you aren't actively working in the workspace. If you're planning on returning to your Azure AI hub resource at a later time, these resources might continue to accrue costs:

+After you delete an Azure AI hub resource in the Azure portal or with Azure CLI, the following resources continue to exist. They continue to accrue costs until you delete them.

+- Application Insights (if you enabled it for your Azure AI hub resource)

+As you use Azure AI Studio with Azure AI hub resources, you incur costs. Azure resource usage unit costs vary by time intervals (seconds, minutes, hours, and days) or by unit usage (bytes, megabytes, and so on). You can see the incurred costs in [cost analysis](../../cost-management-billing/costs/quick-acm-cost-analysis.md?WT.mc_id=costmanagementcontent_docsacmhorizontal_-inproduct-learn).

+When you use cost analysis, you view Azure AI hub resource costs in graphs and tables for different time intervals. Some examples are by day, current and prior month, and year. You also view costs against budgets and forecasted costs. Switching to longer views over time can help you identify spending trends. And you see where overspending might have occurred. If you've created budgets, you can also easily see where they're exceeded.

+> Your Azure AI project costs are only a subset of your overall application or solution costs. You need to monitor costs for all Azure resources used in your application or solution. See [Azure AI hub resources](../concepts/ai-resources.md) for more information.

+1. Expand **contoso_ai_resource** to see the costs for services underlying the [Azure AI](../concepts/ai-resources.md#azure-ai-hub-resources) resource. You can also apply a filter to focus on other costs in your resource group.

+ Title: How to create and manage an Azure AI hub resource

+description: This article describes how to create and manage an Azure AI hub resource

+# How to create and manage an Azure AI hub resource

+As an administrator, you can create and manage Azure AI hub resources. Azure AI hub resources provide a hosting environment for the projects of a team, and help you as an IT admin centrally set up security settings and govern usage and spend. You can create and manage an Azure AI hub resource from the Azure portal or from the Azure AI Studio.

+In this article, you learn how to create and manage an Azure AI hub resource in Azure AI Studio (for getting started) and from the Azure portal (for advanced security setup).

+## Create an Azure AI hub resource in AI Studio

+To create a new Azure AI hub resource, you need either the Owner or Contributor role on the resource group or on an existing Azure AI hub resource. If you are unable to create an Azure AI hub resource due to permissions, reach out to your administrator. If your organization is using [Azure Policy](../../governance/policy/overview.md), don't create the resource in AI Studio. Create the Azure AI hub resource [in the Azure portal](#create-a-secure-azure-ai-hub-resource-in-the-azure-portal) instead.

+Follow these steps to create a new Azure AI hub resource in AI Studio.

+1. Go to the **Manage** page in [Azure AI Studio](https://ai.azure.com).

+1. Select **+ New AI hub**.

+1. Enter your AI hub name, subscription, resource group, and location details.

+1. In the **Azure OpenAI** dropdown, you can select an existing Azure OpenAI resource to bring all your deployments into AI Studio. If you do not bring one, we will create one for you.

+ :::image type="content" source="../media/how-to/resource-create-advanced.png" alt-text="Screenshot of the Create an Azure AI hub resource wizard with the option to set basic information." lightbox="../media/how-to/resource-create-advanced.png":::

+1. Optionally, connect an existing Azure AI Search instance to share search indices with all projects in this Azure AI hub resource. An Azure AI Search instance isn't created for you if you don't provide one.

+1. Select **Next**.

+1. On the **Review and finish** page, you see the **AI Services** provider for you to access the Azure AI services such as Azure OpenAI.

+ :::image type="content" source="../media/how-to/resource-create-studio-review.png" alt-text="Screenshot of the review and finish page for creating an AI hub." lightbox="../media/how-to/resource-create-studio-review.png":::

+1. Select **Create**.

+When the AI hub is created, you can see it on the **Manage** page in AI Studio. You can see that initially no projects are created in the AI hub. You can [create a new project](./create-projects.md).

+## Create a secure Azure AI hub resource in the Azure portal

+If your organization is using [Azure Policy](../../governance/policy/overview.md), set up an Azure AI hub resource that meets your organization's requirements instead of using AI Studio for resource creation.

+1. Enter your AI hub name, subscription, resource group, and location details.

+1. For advanced settings, select **Next: Resources** to specify resources, networking, encryption, identity, and tags.

+ :::image type="content" source="../media/how-to/resource-create-basics.png" alt-text="Screenshot of the option to set Azure AI hub resource basic information." lightbox="../media/how-to/resource-create-basics.png":::

+1. Select an existing **Azure AI services** resource or create a new one. New Azure AI services include multiple API endpoints for Speech, Content Safety and Azure OpenAI. You can also bring an existing Azure OpenAI resource. Optionally, choose an existing **Storage account**, **Key vault**, **Container Registry**, and **Application insights** to host artifacts generated when you use AI Studio.

+ :::image type="content" source="../media/how-to/resource-create-resources.png" alt-text="Screenshot of the Create an Azure AI hub resource with the option to set resource information." lightbox="../media/how-to/resource-create-resources.png":::

+ :::image type="content" source="../media/how-to/resource-create-networking.png" alt-text="Screenshot of the Create an Azure AI hub resource with the option to set network isolation information." lightbox="../media/how-to/resource-create-networking.png":::

+ :::image type="content" source="../media/how-to/resource-create-encryption.png" alt-text="Screenshot of the Create an Azure AI hub resource with the option to select your encryption type." lightbox="../media/how-to/resource-create-encryption.png":::

+ :::image type="content" source="../media/how-to/resource-create-identity.png" alt-text="Screenshot of the Create an Azure AI hub resource with the option to select a managed identity." lightbox="../media/how-to/resource-create-identity.png":::

+ >If you select **User assigned identity**, your identity needs to have the `Cognitive Services Contributor` role in order to successfully create a new Azure AI hub resource.

+ :::image type="content" source="../media/how-to/resource-create-tags.png" alt-text="Screenshot of the Create an Azure AI hub resource with the option to add tags." lightbox="../media/how-to/resource-create-tags.png":::

+## Manage your Azure AI hub resource from the Azure portal

+### Azure AI hub resource keys

+View your keys and endpoints for your Azure AI hub resource from the overview page within the Azure portal.

+Manage role assignments from **Access control (IAM)** within the Azure portal. Learn more about Azure AI hub resource [role-based access control](../concepts/rbac-ai-studio.md).

+1. Select **+ Add** to add users to your Azure AI hub resource

+ :::image type="content" source="../media/how-to/resource-rbac-role.png" alt-text="Screenshot of the page to add a role within the Azure AI hub resource Azure portal view." lightbox="../media/how-to/resource-rbac-role.png":::

+ :::image type="content" source="../media/how-to/resource-rbac-members.png" alt-text="Screenshot of the add members page within the Azure AI hub resource Azure portal view." lightbox="../media/how-to/resource-rbac-members.png":::

+Azure AI hub resource networking settings can be set during resource creation or changed in the **Networking** tab in the Azure portal view. Creating a new Azure AI hub resource invokes a Managed Virtual Network. This streamlines and automates your network isolation configuration with a built-in Managed Virtual Network. The Managed Virtual Network settings are applied to all projects created within an Azure AI hub resource.

+At Azure AI hub resource creation, select between the networking isolation modes: **Public**, **Private with Internet Outbound**, and **Private with Approved Outbound**. To secure your resource, select either **Private with Internet Outbound** or Private with Approved Outbound for your networking needs. For the private isolation modes, a private endpoint should be created for inbound access. Read more information on Network Isolation and Managed Virtual Network Isolation [here](../../machine-learning/how-to-managed-network.md). To create a secure Azure AI hub resource, follow the tutorial [here](../../machine-learning/tutorial-create-secure-workspace.md).

+At Azure AI hub resource creation in the Azure portal, creation of associated Azure AI services, Storage account, Key vault, Application insights, and Container registry is given. These resources are found on the Resources tab during creation.

+To connect to Azure AI services (Azure OpenAI, Azure AI Search, and Azure AI Content Safety) or storage accounts in Azure AI Studio, create a private endpoint in your virtual network. Ensure the PNA flag is disabled when creating the private endpoint connection. For more about Azure AI services connections, follow documentation [here](../../ai-services/cognitive-services-virtual-networks.md). You can optionally bring your own (BYO) search, but this requires a private endpoint connection from your virtual network.

+Projects that use the same Azure AI hub resource, share their encryption configuration. Encryption mode can be set only at the time of Azure AI hub resource creation between Microsoft-managed keys and Customer-managed keys.

+From the Azure portal view, navigate to the encryption tab, to find the encryption settings for your Azure AI hub resource.

+For Azure AI hub resources that use CMK encryption mode, you can update the encryption key to a new key version. This update operation is constrained to keys and key versions within the same Key Vault instance as the original key.

+## Manage your Azure AI hub resource from the Manage tab within the AI Studio

+On the **Manage** page in [Azure AI Studio](https://ai.azure.com), you have the options to create a new Azure AI hub resource, manage an existing Azure AI hub resource, or view your quota.

+### Managing an Azure AI hub resource

+You can view all Projects that use this Azure AI hub resource. Be linked to the Azure portal to manage the Resource Configuration. Manage who has access to this Azure AI hub resource. View all of the connections within the resource. Manage who has access to this Azure AI hub resource.

+Within Permissions you can view who has access to the Azure AI hub resource and also manage permissions. Learn more about [permissions](../concepts/rbac-ai-studio.md).

+1. Enter the member's name in **Add member** and assign a **Role**. For most users, we recommend the AI Developer role. This permission applies to the entire Azure AI hub resource. If you wish to only grant access to a specific Project, manage permissions in the [Project](create-projects.md)

+View and manage computes for your Azure AI hub resource. Create computes, delete computes, and review all compute resources you have in one place.

+From the Connections page, you can view all Connections in your Azure AI hub resource by their Name, Authentication method, Category type, if the connection is shared to all projects in the resource or specifically to a Project, Target, Owner, and Provisioning state.

+Learn more on how to [create and manage Connections](connections-add.md). Connections created in the Azure AI hub resource Manage page are automatically shared across all projects. If you want to make a project specific connection, make that within the Project.

+View and configure policies for your Azure AI hub resource. See all the policies you have in one place. Policies are applied across all Projects.

+Here you're linked to the Azure portal to review the cost analysis information for your Azure AI hub resource.

+- [Learn more about Azure AI hub resources](../concepts/ai-resources.md)

+Projects are hosted by an Azure AI hub resource that provides enterprise-grade security and a collaborative environment. For more information about the Azure AI projects and resources model, see [Azure AI hub resources](../concepts/ai-resources.md).

+## Create a project

+1. Select an Azure AI hub resource from the dropdown to host your project. If you don't have access to an Azure AI hub resource yet, select **Create a new resource**.

+ > To create an Azure AI hub resource, you must have **Owner** or **Contributor** permissions on the selected resource group. It's recommended to share an Azure AI hub resource with your team. This lets you share configurations like data connections with all projects, and centrally manage security settings and spend.

+1. If you're creating a new Azure AI hub resource, enter a name.

+ > Especially for getting started it's recommended to create a new resource group for your project. This allows you to easily manage the project and all of its resources together. When you create a project, several resources are created in the resource group, including an Azure AI hub resource, a container registry, and a storage account.

+1. Enter the **Location** for the Azure AI hub resource and then select **Next**. The location is the region where the Azure AI hub resource is hosted. The location of the Azure AI hub resource is also the location of the project. Azure AI services availability differs per region. For example, certain models might not be available in certain regions.

+1. On the **Review and finish** page, you see the **AI Services** provider for you to access the Azure AI services such as Azure OpenAI.

+1. Review the project details and then select **Create a project**.

+Once a project is created, you can access the **Tools**, **Components**, and **Settings** assets in the left navigation panel. For a project that uses an Azure AI hub with support for Azure OpenAI, you see the **Playground** navigation option under **Tools**.

+In the project details page (select **Build** > **Settings**), you can find information about the project, such as the project name, description, and the Azure AI hub resource that hosts the project. You can also find the project ID, which is used to identify the project in the Azure AI Studio API.

+- Name: The name of the project corresponds to the selected project in the left panel.

+- AI hub: The Azure AI hub resource that hosts the project.

+- Location: The location of the Azure AI hub resource that hosts the project. For supported locations, see [Azure AI Studio regions](../reference/region-support.md).

+- Subscription: The subscription that hosts the Azure AI hub resource that hosts the project.

+- Resource group: The resource group that hosts the Azure AI hub resource that hosts the project.

+Select **View in the Azure portal** to navigate to the project resources in the Azure portal.

+- [Deploy a web app for chat on your data](../tutorials/deploy-chat-web-app.md)

+- [Learn more about Azure AI hub resources](../concepts/ai-resources.md)

+* [Azure AI Search](?tabs=azure-ai-search): If you have an existing [Azure AI Search](/azure/search/search-what-is-azure-search) index, you can use it as a data source.

+If you have an existing [Azure AI Search](/azure/search/search-what-is-azure-search) index, you can use it as a data source.

+ :::image type="content" source="../media/data-add/use-your-image-data/add-image-data-ai-search.png" alt-text="A screenshot showing the Azure AI Search index selection." lightbox="../media/data-add/use-your-image-data/add-image-data-ai-search.png":::

+ :::image type="content" source="../media/data-add/use-your-image-data/add-your-data-ai-search-review-finish.png" alt-text="Screenshot of the review and finish page for adding data via Azure AI Search." lightbox="../media/data-add/use-your-image-data/add-your-data-ai-search-review-finish.png":::

+ :::image type="content" source="../media/data-add/use-your-image-data/add-image-data-blob.png" alt-text="A screenshot showing the Azure storage account and Azure AI Search index selection." lightbox="../media/data-add/use-your-image-data/add-image-data-blob.png":::

+Llama 2 models can be deployed to real-time endpoints in AI Studio. When deployed to real-time endpoints, you can select all the details about on the infrastructure running the model including the virtual machines used to run it and the number of instances to handle the load you're expecting. Models deployed in this modality consume quota from your subscription. All the models in the Llama family can be deployed to real-time endpoints.

+> It's recommended that you work within this project directory. Files, folders, and repos you include in your project directory persist on your host machine (your compute instance). Files stored in the code and data folders will persist even when the compute instance is stopped or restarted, but will be lost if the compute is deleted. However, the shared files are saved in your Azure AI hub resource's storage account, and therefore aren't lost if the compute instance is deleted.

+- [Quickstart: Analyze images and video with GPT-4 for Vision in the playground](../quickstarts/multimodal-vision.md)

+|Application Insights diagnostics| If you enable this, system metrics during inference time (such as token count, flow latency, flow request, and etc.) will be collected into Azure AI hub resource default Application Insights.|

+The endpoint needs to access Azure resources such as the Azure Container Registry or your Azure AI hub resource connections for inferencing. You can allow the endpoint permission to access Azure resources via giving permission to its managed identity.

+When you create the deployment, Azure tries to pull the user container image from the Azure AI hub resource Azure Container Registry (ACR) and mounts the user model and code artifacts into the user container from the Azure AI hub resource storage account.

+ > The **Azure Machine Learning Workspace Connection Secrets Reader** role is a built-in role which has permission to get Azure AI hub resource connections.

+1. For **user-assigned** identity, you need to grant permissions to the Azure AI hub resource container registry and storage account as well. You can find the container registry and storage account in the Azure AI hub resource overview page in Azure portal.

+ Go to the Azure AI hub resource container registry overview page, select **Access control**, and select **Add role assignment**, and assign **ACR pull |Pull container image** to the endpoint identity.

+ Go to the Azure AI hub resource default storage overview page, select **Access control**, and select **Add role assignment**, and assign **Storage Blob Data Reader** to the endpoint identity.

+1. (optional) For **user-assigned** identity, if you want to monitor the endpoint related metrics like CPU/GPU/Disk/Memory utilization, you need to grant **Workspace metrics writer** role of Azure AI hub resource to the identity as well.

+#### 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:

+If the Azure AI hub resource the project uses was created through Azure portal:

+> [!TIP]

+> You can also try GPT-4 Turbo with Vision capabilities in the Azure AI Studio playground. For more information, see [GPT-4 Turbo with Vision on your images and videos in Azure AI Studio playground](../quickstarts/multimodal-vision.md).

+You can conveniently access these links from the **All Azure AI** menu at the top-right corner of AI Studio.

+The prompt samples are designed to assist AI Studio users in finding and utilizing prompts for common use-cases and quickly get started. Users can explore the catalog, view available prompts, and easily open them in a playground for further customization and fine-tuning.

+On the **Explore** page, select **Models** > **Prompt catalog** from the left menu to learn more and try it out.

+- An [Azure AI hub resource](../../how-to/create-azure-ai-resource.md) with a GPT-4 Turbo with Vision model deployed in one of the regions that support GPT-4 Turbo with Vision: Australia East, Switzerland North, Sweden Central, and West US. When you deploy from your project's **Deployments** page, select: `gpt-4` as the model name and `vision-preview` as the model version.

+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/python-tool/custom-connection-meta.png" alt-text="Screenshot that shows add extra meta to custom connection in AI Studio." lightbox = "./media/python-tool/custom-connection-meta.png":::

+ :::image type="content" source="./media/serp-api-tool/serp-connection-meta.png" alt-text="Screenshot that shows add extra meta to custom connection in AI Studio." lightbox = "./media/serp-api-tool/serp-connection-meta.png":::

+- Creating Azure AI hub resource-level quotas.

+Use quotas to manage compute target allocation between multiple Azure AI hub resources in the same subscription.

+By default, all Azure AI hub resources share the same quota as the subscription-level quota for VM families. However, you can set a maximum quota for individual VM families for more granular cost control and governance on Azure AI hub resources in a subscription. Quotas for individual VM families let you share capacity and avoid resource contention issues.

+The Azure AI SDK is a family of packages that provide access to Azure AI services such as Azure OpenAI.

+"Use of Azure OpenAI models in Azure Machine Learning requires Azure OpenAI Services resources. This subscription or region doesn't have access to this model."

+1. Go to your project in [Azure AI Studio](https://ai.azure.com) and select the settings icon on the lower left corner.

+2. Select your Azure AI hub resource name under **Resource configurations** on the **Settings** page.

+3. On the Azure AI hub overview page, select your storage account name. This should be the name of storage account listed in the error message you received. You'll be taken to the storage account page in the [Azure portal](https://portal.azure.com).

+4. On the storage account page, select **Containers** under **Data Storage** on the left menu.

+5. Select the container name listed in the error message you received.

+* An [Azure AI hub resource](../how-to/create-azure-ai-resource.md) and [project](../how-to/create-projects.md) in Azure AI Studio.

+- An [Azure AI hub resource](../how-to/create-azure-ai-resource.md) with a chat model deployed. For more information about model deployment, see the [resource deployment guide](../../ai-services/openai/how-to/create-resource.md).

+- An [Azure AI hub resource](../how-to/create-azure-ai-resource.md) with a GPT-4 Turbo with Vision model deployed in one of the [regions that support GPT-4 Turbo with Vision](../../ai-services/openai/concepts/models.md#gpt-4-and-gpt-4-turbo-preview-model-availability): Australia East, Switzerland North, Sweden Central, and West US. When you deploy from your Azure AI project's **Deployments** page, select: `gpt-4` as the model name and `vision-preview` as the model version.

+- An [Azure AI hub resource](../how-to/create-azure-ai-resource.md) with a model deployed. For more information about model deployment, see the [resource deployment guide](../../ai-services/openai/how-to/create-resource.md).

+Azure AI Studio is currently available in preview in the following Azure regions. You can create [Azure AI hub resources](../how-to/create-azure-ai-resource.md) and projects in these regions.

+Azure AI Speech capabilities including custom neural voice vary in regional availability due to underlying hardware availability. See [Speech service supported regions](../../ai-services/speech-service/regions.md) for an overview.

+- An [Azure AI hub resource](../how-to/create-azure-ai-resource.md) and [project](../how-to/create-projects.md) in Azure AI Studio.

+In this tutorial, your web app is deployed to the same resource group as your Azure AI hub resource. Later you configure authentication for the web app in the Azure portal.

+1. In Azure AI Studio, select **Manage** from the top menu and then select **Details**. If you have multiple Azure AI hub resources, select the one you want to use in order to see its details.

+1. You should now be in the Azure portal, viewing the contents of the resource group where you deployed the Azure AI hub resource.

+ - **Resource group**: Select a resource group in which to deploy the web app. You can use the same resource group as the Azure AI hub resource.

+ - **Location**: Select a location in which to deploy the web app. You can use the same location as the Azure AI hub resource.

+1. Return to the browser tab containing the Azure portal (or re-open the [Azure portal](https://portal.azure.com?azure-portal=true) in a new browser tab) and view the contents of the resource group where you deployed the Azure AI hub resource and web app (you might need to refresh the view the see the web app).

+- You need an Azure AI hub resource and your user role must be **Azure AI Developer**, **Contributor**, or **Owner** on the Azure AI hub resource. For more information, see [Azure AI hub resources](../concepts/ai-resources.md) and [Azure AI roles](../concepts/rbac-ai-studio.md).

+ - If your role is **Contributor** or **Owner**, you can [create an Azure AI hub resource in this tutorial](#create-an-azure-ai-project-in-azure-ai-studio).

+ - If your role is **Azure AI Developer**, the Azure AI hub resource must already be created.

+Your Azure AI project is used to organize your work and save state while building your copilot. During this tutorial, your project contains your data, prompt flow runtime, evaluations, and other resources. For more information about the Azure AI projects and resources model, see [Azure AI hub resources](../concepts/ai-resources.md).

+1. Select an Azure AI hub resource from the dropdown to host your project. If you don't have access to an Azure AI hub resource yet, select **Create a new resource**.

+ > To create an Azure AI hub resource, you must have **Owner** or **Contributor** permissions on the selected resource group. It's recommended to share an Azure AI hub resource with your team. This lets you share configurations like data connections with all projects, and centrally manage security settings and spend.

+1. If you're creating a new Azure AI hub resource, enter a name.

+ > Especially for getting started it's recommended to create a new resource group for your project. This allows you to easily manage the project and all of its resources together. When you create a project, several resources are created in the resource group, including an Azure AI hub resource, a container registry, and a storage account.

+1. Enter the **Location** for the Azure AI hub resource and then select **Next**. The location is the region where the Azure AI hub resource is hosted. The location of the Azure AI hub resource is also the location of the project.

+ > Azure AI hub resources and services availability differ per region. For example, certain models might not be available in certain regions. The resources in this tutorial are created in the **East US 2** region.

+This article is for people who use screen readers such as Microsoft's Narrator, JAWS, NVDA or Apple's Voiceover. You learn how to use the Azure AI Studio with a screen reader.

+In **Explore** you can explore the different capabilities of Azure AI before creating a project. You can find this page in the primary navigation landmark.

+Within **Explore**, you can [explore many capabilities](../how-to/models-foundation-azure-ai.md) found within the secondary navigation. These include [model catalog](../how-to/model-catalog.md), model leaderboard, and pages for Azure AI services such as Speech, Vision, and Content Safety.

+- [Model catalog](../how-to/model-catalog.md) contains three main areas: Announcements, Models and Filters. You can use Search and Filters to narrow down model selection

+1. In [Azure AI Studio](https://ai.azure.com), navigate to the **Build** tab in the primary navigation.

+1. Press the **Tab** key until you hear *New project* and select this button.

+When you first arrive, the playground mode dropdown is set to **Chat** by default. In this mode, the playground is composed of the command toolbar and three main panes: **Assistant setup**, **Chat session**, and **Configuration**. If you added your own data in the playground, the **Citations** pane also appears when selecting a citation as part of the model response.

+The assistant setup pane is where you can set up the chat assistant according to your organization's needs.

+The chat session pane is where you can chat to the model and test out your assistant

+- After you send a message, the model might take some time to respond, especially if the response is long. You hear a screen reader announcement "Message received from the chatbot" when the model finishes composing a response.

+Microsoft wants to provide the best possible experience for all our customers. If you have a disability or questions related to accessibility, contact the Microsoft Disability Answer Desk for technical assistance. The Disability Answer Desk support team is trained in using many popular assistive technologies. They can offer assistance in English, Spanish, French, and American Sign Language. Go to the Microsoft Disability Answer Desk site to find out the contact details for your region.

+If you're a government, commercial, or enterprise customer, contact the enterprise Disability Answer Desk.

+- Directly from the studio you can interact with a project code-first via the [Azure AI SDK](how-to/sdk-install.md) and [Azure AI CLI](how-to/cli-install.md).

+- Build together as one team. Your [Azure AI hub resource](./concepts/ai-resources.md) provides enterprise-grade security, and a collaborative environment with shared files and connections to pretrained models, data and compute.

+- Organize your way. Your [Azure AI project](./how-to/create-projects.md) helps you save state, allowing you iterate from first idea, to first prototype, and then first production deployment. Also easily invite others to collaborate along this journey.

+Wherever you're at or going in Azure AI Studio, use the **Home**, **Explore**, **Build**, and **Manage** tabs to find your way around.

+- Evaluate, deploy, and continuously monitor your AI application and app performance.

+- Centralized backend infrastructure to reduce complexity for developers.

+- A single Azure AI hub resource for enterprise configuration, unified data story, and built-in governance.

+## Azure AI Studio enterprise chat solution demo

+Azure AI Studio is available in most regions where Azure AI services are available. For more information, see [region support for Azure AI Studio](reference/region-support.md).

+> You can now update the `outboundType` after cluster creation.

+## Updating `outboundType` after cluster creation

+- This feature is currently available in the following regions: West Central US, East Asia, UK South, East US, Australia Central, Australia East, Brazil South, Canada Central, Central India, East US 2, France Central, and Germany West Central, Israel Central, Italy North, Japan East, JioIndia West, Korea Central, Malaysia South, Mexico Central, North Central US, North Europe, Norway East, Qatar Central, South Africa North, Sweden Central, Switzerland North, Taiwan North, UAE North, UK West, West US 2, Australia Central 2, Austrial South East, Austria East, Belgium Central, Brazil South East, Canada East, Central US, Chile Central, France South, Germany North, Israel North West, Japan West, Jio India Central.

+ az network public-ip show --resource-group <node resource group name> --name myAKSPublicIP --query ipAddress --output tsv

+ service.beta.kubernetes.io/azure-load-balancer-resource-group: <node resource group name>

+ service.beta.kubernetes.io/azure-load-balancer-resource-group: <node resource group name>

+ "description": "adding a new logger with user-assigned managed identity",

+* The upgrade process involves creating a new compute in parallel to the old compute. The old compute takes 15-45 mins to be deleted with an option to delay it for up to 48 hours. The 48 hour delay option is only available for VNet injected services.

+ **VNet-injected instances:** Yes, you can. If there's a failure during the migration process, the instance will automatically roll back to the stv1 platform. However, if you encounter any other issues post migration, you can roll back only if you have requested an extension to the old gateway purge. By default, the old gateway is purged in 15 mins that can be extended up to 48 hours by contacting support in advance. You should make sure to contact support before the old gateway is purged, if a rollback is required.

+ **Non-VNet injected instances:** If there is a failure during the migration process, the instance will automatically roll back to the stv1 platform. If the migration completes successfully, a rollback is not possible.

+| **Manual Verification** | Confirm the domain by using either a DNS TXT record or an HTML page, which applies only to **Standard** certificates per the following note. The steps are provided after you select the option. The HTML page option doesn't work for web apps with "HTTPS Only' enabled. For subdomain verification, the domain verification token needs to be added to the root domain. |

+When you're deploying onto dedicated hardware (hosts), you're limited in scaling across all App Service plans to the number of cores in this type of environment. An App Service Environment that's deployed on dedicated hosts has 132 vCores available. I1v2 uses two vCores, I2v2 uses four vCores, and I3v2 uses eight vCores per instance. Only I1v2, I2v2 and I3v2 SKU sizes are available on App Service Environment deployed on dedicated hosts.

+description: Learn about the language runtime support policy for Azure App Service.

+description: Learn how to buy an App Service domain and use it as a custom domain for your app Azure App Service.

+[At-scale assessment of .NET web apps](/training/modules/migrate-app-service-migration-assistant/)

+The virtual network integration feature is used in Azure App Service dedicated compute pricing tiers. If your app is in an [App Service Environment](./environment/overview.md), it already integrates with a virtual network and doesn't require you to configure virtual network integration feature to reach resources in the same virtual network. For more information on all the networking features, see [App Service networking features](./networking-features.md).

+* **Network security groups (NSGs)**: You can block outbound traffic with an NSG that you use on your integration subnet. The inbound rules don't apply because you can't use virtual network integration to provide inbound access to your app.

+When you want your apps in your plan to reach a virtual network that apps in another plan already connect to, select a different subnet than the one being used by the pre-existing virtual network integration.

+If the virtual network is in a different subscription than the app, you must ensure that the subscription with the virtual network is registered for the `Microsoft.Web` resource provider. You can explicitly register the provider [by following this documentation](../azure-resource-manager/management/resource-providers-and-types.md#register-resource-provider), but it also automatically registers when creating the first web app in a subscription.

+Through application routing or configuration routing options, you can configure what traffic is sent through the virtual network integration. Traffic is only subject to [network routing](#network-routing) if sent through the virtual network integration.

+Application routing applies to traffic that is sent from your app after it starts. See [configuration routing](#configuration-routing) for traffic during startup. When you configure application routing, you can either route all traffic or only private traffic (also known as [RFC1918](https://datatracker.ietf.org/doc/html/rfc1918#section-3) traffic) into your virtual network. You configure this behavior through the outbound internet traffic setting. If outbound internet traffic routing is disabled, your app only routes private traffic into your virtual network. If you want to route all your outbound app traffic into your virtual network, make sure that outbound internet traffic is enabled.

+### Routing app settings

+App Service has existing app settings to configure application and configuration routing. Site properties override the app settings if both exist. Site properties have the advantage of being auditable with Azure Policy and validated at the time of configuration. We recommend you to use site properties.

+You can still use the existing `WEBSITE_VNET_ROUTE_ALL` app setting to configure application routing.

+App settings also exist for some configuration routing options. These app settings are named `WEBSITE_CONTENTOVERVNET` and `WEBSITE_PULL_IMAGE_OVER_VNET`.

+You can use route tables to route outbound traffic from your app without restriction. Common destinations can include firewall devices or gateways. You can also use a [network security group](../virtual-network/network-security-groups-overview.md) (NSG) to block outbound traffic to resources in your virtual network or the internet. An NSG that you apply to your integration subnet is in effect regardless of any route tables applied to your integration subnet.

+* Only one App Service plan virtual network integration connection per integration subnet is supported.

+If you deleted the app or the App Service plan without disconnecting the virtual network integration first, you aren't able to do any update/delete operations on the virtual network or subnet that was used for the integration with the deleted resource. A subnet delegation 'Microsoft.Web/serverFarms' remains assigned to your subnet and prevents the update and delete operations.

+[Using Azure PowerShell with Azure Resource Manager](../azure-resource-manager/management/manage-resources-powershell.md).

+ Title: 'Tutorial: Authenticate users E2E'

+ Title: 'Tutorial: Authenticate users E2E to Azure'

+ Title: 'Tutorial: PHP app with MySQL and Redis'

+#Customer intent: As a web developer, I want to leverage background tasks to keep my application running smoothly.

+ :::image type="content" source="./media/managed-identity/add-managed-identity-app-service.png" alt-text="Screenshot of how to add a managed identity in App Service.":::

+1. In the [Azure portal](https://portal.azure.com), select the App Configuration store that you created in the [quickstart](../azure-app-configuration/quickstart-azure-functions-csharp.md).

+> Don't create a Windows Server 2012/R2 ESU License for only Dev/Test or Disaster Recovery workloads. You shouldn't provision an ESU License only for non-billable workloads. Moreover, you'll be billed fully for all of the cores provisioned with an ESU license, and any dev/test cores on the license won't be billed as long as they're tagged accordingly based on the following qualifications.

+- **Billable ESU License.** You must already have provisioned and activated a WS2012 Arc ESU License intended to be linked to regular Azure Arc-enabled servers running in production environments (i.e., normally billed ESU scenarios). This license should be provisioned only for billable cores, not cores that are eligible for free Extended Security Updates, for example, dev/test cores.

+- You have 8 Windows Server 2012 R2 Standard instances, each with 8 physical cores. Six of these Windows Server 2012 R2 Standard machines are for production, and 2 of these Windows Server 2012 R2 Standard machines are eligible for free ESUs through the Visual Studio Dev Test subscription.

+ - You should first provision and activate a regular ESU License for Windows Server 2012/R2 that's Standard edition and has 48 physical cores to cover the 6 production machines. You should link this regular, production ESU license to your 6 production servers.

+ - Next, you should reuse this existing license, don't add any more cores or provision a separate license, and link this license to your 2 non-production Windows Server 2012 R2 standard machines. You should tag the ESU license and the 2 non-production Windows Server 2012 R2 Standard machines with Name: "ESU Usage" and Value: "WS2012 VISUAL STUDIO DEV TEST".

+ - This will result in an ESU license for 48 cores, and you'll be billed for those 48 cores. You won't be charged for the additional 16 cores of the dev test servers that you added to this license, as long as the ESU license and the dev test server resources are tagged appropriately.

+> You needed a regular production license to start with, and you'll be billed only for the production cores.

+*Last updated: January 2024*

+| [Azure Managed Grafana](../../managed-grafana/index.yml) | &#x2705; | &#x2705; |

+| [Azure AI Health Bot](/healthbot/) | &#x2705; | &#x2705; |

+| [Azure AI Search](../../search/index.yml) (formerly Azure Cognitive Search) | &#x2705; | &#x2705; |

+| [Omnichannel for Customer Service (Formerly Dynamics 365 Chat and Omnichannel Engagement Hub)](/dynamics365/omnichannel/introduction-omnichannel) | &#x2705; | &#x2705; |

+| [Microsoft Defender Vulnerability Management](/microsoft-365/security/defender-vulnerability-management/) | &#x2705; | &#x2705; |

+| [Azure Stack](/azure-stack/operator/azure-stack-usage-reporting) | &#x2705; | &#x2705; | &#x2705; | &#x2705; | &#x2705; |

+| January 2024 |**Known Issues**<ul><li>The agent extension code size is beyond the deployment limit set by Arc, thus 1.29.5 will not install on Arc enabled servers. Fix is coming in 1.29.6.</li></ul>**Windows**<ul><li>Added support for Transport Layer Security 1.3</li><li>Reverted a change to enable multiple IIS subscriptions to use same filter. Feature will be redeployed once memory leak is fixed.</li><li>Improved ETW event throughput rate</li></ul>**Linux**<ul><li>Fix Error messages logged intended for mdsd.err went to mdsd.warn instead in 1.29.4 only. Likely error messages: "Exception while uploading to Gig-LA : ...", "Exception while uploading to ODS: ...", "Failed to upload to ODS: ..."</li><li>Syslog time zones incorrect: AMA now uses machine current time when AMA receives an event to populate the TimeGenerated field. The previous behavior parsed the time zone from the Syslog event which caused incorrect times if a device sent an event from a time zone different than the AMA collector machine.</li></ul> | 1.23.0 | 1.29.5 |

+ - `Bring Your Own User-Assigned Identity`: If set to `false`, it creates the built-in user-assigned managed identity in the predefined resource group and assigns it to all the machines that the policy is applied to. Location of the resource group can be configured in the `Built-In-Identity-RG Location` parameter.

+ If set to `true`, you can instead use an existing user-assigned identity that is automatically assigned to all the machines that the policy is applied to.

+ - `Bring Your Own User-Assigned Managed Identity`: If set to `false`, it configures the agent to use the built-in user-assigned managed identity created by the preceding policy. If set to `true`, it configures the agent to use an existing user-assigned identity.

+ - `Built-In-Identity-RG Location`: If you use built-in user-assigned managed identity, specify the location where the identity and the resource group should be created. This parameter is only used when 'Bring Your Own User-Assigned Managed Identity' parameter is false.

+| Microsoft Graph | [MicrosoftGraphActivityLogs](/azure/azure-monitor/reference/tables/microsoftgraphactivitylogs) |

+Customer-managed key is delivered on [dedicated clusters](./logs-dedicated-clusters.md) providing higher protection level and control. Data is encrypted in storage twice, once at the service level using Microsoft-managed keys or Customer-managed keys, and once at the infrastructure level, using two different [encryption algorithms](../../storage/common/storage-service-encryption.md#about-azure-storage-service-side-encryption) and two different keys. [double encryption](../../storage/common/storage-service-encryption.md#doubly-encrypt-data-with-infrastructure-encryption) protects against a scenario where one of the encryption algorithms or keys may be compromised. Dedicated cluster also lets you protect data with [Lockbox](#customer-lockbox).

+> | serverGroupsv2 | Yes | No |

+> | serversv2 | Yes | No |

+By default, web client connects to SignalR Service using an internal access. This access token isn't associated with an authenticated identity.

+ You're prompted to authorize the chat app's access to your GitHub account. Select the **Authorize** button.

+Resiliency and disaster recovery is a common need for online systems. Azure SignalR Service already provides 99.9% availability, however it's still a regional service.

+When there's a region-wide outage, your service instance doesn't fail over to another region because it's always running in the one region.

+- **Enable Geo-Replication** (Easy way). This feature handles regional failover for you automatically. When enabled, there's only one Azure SignalR instance and no code changes are introduced. Check [geo-replication](howto-enable-geo-replication.md) for details.

+- **Utilize Multiple Endpoints in Service SDK**. Our service SDK supports multiple SignalR service instances and automatically switches to other instances when some of them are unavailable. With this feature, you're able to recover when a disaster takes place, but you need to set up the right system topology by yourself. You learn how to do so **in this document**.

+To ensure cross region resiliency for SignalR service, you need to set up multiple service instances in different regions. So when one region is down, the others can be used as backup.

+Primary is an instance responsible for receiving online traffic, while secondary serves as a fallback instance that is fully functional.

+In our SDK implementation, negotiate only returns primary endpoints, so clients only connect to primary endpoints in normal cases.

+One distinguishing characteristic of a weak connection is that it's unable to accept client connection routing due to the location of secondary instance in another region. Routing a client to another region isn't an optimal choice (increases latency).

+One typical setup for cross region scenario is to have two or more pairs of SignalR service instances and app servers.

+But when a client is connected, it routes to the app server in the same region to achieve optimal network latency.

+The following diagram illustrates such topology:

+In the ConnectionString, `<name>` is the name of the endpoint and `<role>` is its role (primary or secondary).

+In this article, you learned how to configure your application to achieve resiliency for SignalR service. To understand more details about server/client connection and connection routing in SignalR service, you can read [this article](signalr-concept-internals.md) for SignalR service internals.

+description: Use Azure Event Grid to subscribe to Azure SignalR Service events. These events can also trigger other downstream services.

+Azure SignalR Service events are reliably sent to the Event Grid service that provides reliable delivery services to your applications through rich retry policies and dead-letter delivery. To learn more, see [Event Grid message delivery and retry](../event-grid/delivery-and-retry.md).

+Azure SignalR Service events are only active when client connections are in a serverless state. If a client doesn't route to a hub server, it goes into the serverless state. Classic mode only works when the hub that client connections connect to doesn't have a hub server. Serverless mode is recommended as a best practice. To learn more details about service mode, see [How to choose Service Mode](https://github.com/Azure/azure-signalr/blob/dev/docs/faq.md#what-is-the-meaning-of-service-mode-defaultserverlessclassic-how-can-i-choose).

+Event Grid uses [event subscriptions](../event-grid/concepts.md#event-subscriptions) to route event messages to subscribers. Azure SignalR Service event subscriptions support two types of events:

+Azure SignalR Service events contain all the information you need to respond to the changes in your data. You can identify an Azure SignalR Service event with the eventType property starts with **Microsoft.SignalRService**. Additional information about the usage of Event Grid event properties is documented at [Event Grid event schema](../event-grid/event-schema.md).

+Here's an example of a client connection connected event:

+SignalR is currently available in [two versions](/aspnet/core/signalr/version-differences) for use with web applications:

+- ASP.NET SignalR

+- new ASP.NET Core SignalR

+ASP.NET Core SignalR is a rewrite of the previous version. As a result, ASP.NET Core SignalR isn't backward compatible with the earlier SignalR version. The APIs and behaviors are different. The Azure SignalR Service supports both versions.

+Azure SignalR Service lets you host your actual web application on multiple platforms (Windows, Linux, and macOS) [Azure App Service](../app-service/overview.md), [IIS](/aspnet/core/host-and-deploy/iis/index), [Nginx](/aspnet/core/host-and-deploy/linux-nginx), [Apache](/aspnet/core/host-and-deploy/linux-apache), [Docker](/aspnet/core/host-and-deploy/docker/index). You can also use self-hosting in your own process.

+Azure SignalR Service is the best choice if the goals for your application include:

+- supporting the latest functionality for updating web clients with real-time content updates,

+- running across multiple platforms (Azure, Windows, Linux, and macOS)

+- hosting in different environments

+For ASP.NET Core SignalR, another reason might be you have no requirements to actually host a web application at all. The logic of your web application might use [Serverless computing](https://azure.microsoft.com/overview/serverless-computing/). For example, maybe your code is only hosted and executed on demand with [Azure Functions](../azure-functions/index.yml) triggers. This scenario can be challenging because your code only runs on-demand and doesn't maintain long connections with clients. Azure SignalR Service can handle this situation since the service already manages connections for you. For more information, see [overview on how to use SignalR Service with Azure Functions](signalr-concept-azure-functions.md). Since ASP.NET SignalR uses a different protocol, such Serverless mode isn't supported for ASP.NET SignalR.

+This quickstart walks you through the process of creating an Azure SignalR Service using an Azure Resource Manager (ARM) template. You can deploy the Azure SignalR Service through the Azure portal, PowerShell, or CLI.

+If your environment meets the prerequisites and you're familiar with using ARM templates, select the **Deploy to Azure** button. The template opens in the Azure portal once you sign in.

+To deploy the Azure SignalR Service using the ARM template, Select the following link in the Azure portal:

+4. If you want, enter a new **Name** and the **Location** (For example **eastus2**) of the Azure SignalR Service. If you don't specify a name, it generates automatically. The Azure SignalR Service's location can be the same or different from the region of the resource group. If you don't specify a location, it defaults to the same region as your resource group.

+5. Choose the **Pricing Tier** (**Free_F1** or **Standard_S1**), enter the **Capacity** (number of SignalR units), and choose a **Service Mode** of **Default** (requires hub server), **Serverless** (doesn't allow any server connection), or **Classic** (routed to hub server only if hub has server connection). Now, choose whether to **Enable Connectivity Logs** or **Enable Messaging Logs**.

+Run the following interactive code to view details about your Azure SignalR Service. You have to enter the name of the new service and the resource group.

+Run the following interactive code to view details about your Azure SignalR Service. You have to enter the name of the new service and the resource group.

+Azure SignalR Service provides [REST API](https://github.com/Azure/azure-signalr/blob/dev/docs/rest-api.md) to support server-to-client communication scenarios such as broadcasting. You can choose any programming language that can make REST API calls. You can post messages to all connected clients, a specific client by name, or a group of clients.

+In this quickstart, you learn how to send messages from a command-line app to connected client apps in C#.

+While the service is being deployed, let's switch to prepare the code. Clone the [sample app from GitHub](https://github.com/aspnet/AzureSignalR-samples.git), set the SignalR Service connection string, and run the application locally.

+You also learn how to generate an access token to authenticate with Azure SignalR Service.

+You can also run the following command to start a server or client

+## <a name="usage"> </a> Integration with non-Microsoft services

+The Azure SignalR service allows non-Microsoft services to integrate with the system.

+`1.0` | `POST` | `https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>` | `{"target": "<method-name>", "arguments": [...]}`

+`1.0` | `POST` | `https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/groups/<group-name>` | `{"target": "<method-name>", "arguments": [...]}`

+`1.0` | `POST` | `https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/users/<user-id>` | `{"target": "<method-name>", "arguments": [...]}`

+User subscription mode requires [Azure Key Vault](/azure/key-vault/general/overview). The key vault must be in the same subscription and region as the Batch account.

+1. On the **Access configuration** tab, select either **Azure role-based access control** or **Vault access policy** under **Permission model**, and under **Resource access**, check all 3 checkboxes for **Azure Virtual Machine for deployment**, **Azure Resource Manager for template deployment** and **Azure Disk Encryption for volume encryption**.

+You can also grant access to the key vault manually in [Azure portal](https://portal.azure.com).

+#### If the Key Vault permission model is **Azure role-based access control**:

+1. Select **Access control (IAM)** from the left navigation of the key vault page.

+1. At the top of the **Access control (IAM)** page, select **Add** > **Add role assignment**.

+1. On the **Add role assignment** screen, under **Role** tab, under **Job function roles** sub tab, select either **Key Vault Secrets Officer** or **Key Vault Administrator** role for the Batch account, and then select **Next**.

+1. On the **Members** tab, select **Select members**. On the **Select members** screen, search for and select **Microsoft Azure Batch**, and then select **Select**.

+1. Click the **Review + create** button on the bottom to go to **Review + assign** tab, and click the **Review + create** button on the bottom again.

+For detailed steps, see [Assign Azure roles by using the Azure portal](../role-based-access-control/role-assignments-portal.md).

+#### If the Key Vault permission model is **Vault access policy**:

+- Follow the [IoT Plug an Play conventions](../iot/concepts-developer-guide-device.md) to implement of telemetry, properties, and commands.

+Prior to certifying your device through the certification process for IoT Plug and Play, you will want to validate that the device implementation matches the telemetry, properties and commands defined in the [Digital Twins Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl) device model locally prior to submitting to the [Azure IoT Public Model Repository](../iot/concepts-model-repository.md).

+- Send the model ID during [DPS registration](../iot/concepts-developer-guide-device.md#dps-payload) in the DPS provisioning payload.

+- Announce the model ID during the [MQTT connection](../iot/concepts-developer-guide-device.md#model-id-announcement).

+For IoT Plug and Play issues related to the model repository, refer to [our Docs guidance about the device model repository](../iot/concepts-model-repository.md).

+1. Easy integration with Azure IoT based solutions using the [Digital Twin APIs](../iot/concepts-digital-twin.md) : Azure IoT Hub and Azure IoT Central

+| **Resources** | [Public Preview Refresh updates](../iot/overview-iot-plug-and-play.md) |

+| **Resources** | [Model repository](../iot/overview-iot-plug-and-play.md) |

+| **Resources** | [Microsoft defined interface](../iot/overview-iot-plug-and-play.md) |

+zone_pivot_groups: acs-plat-web-ios-android

+This article describes how to migrate an existing Twilio Video implementation to the [Azure Communication Services' Calling SDK](../concepts/voice-video-calling/calling-sdk-features.md). Both Twilio Video and Azure Communication Services' Calling SDK for WebJS are also cloud-based platforms that enable developers to add voice and video calling features to their web applications.

+You can find more information on [Getting started with CVM worker nodes with a lift and shift workload to CVM node pool.](../aks/use-cvm.md).

+You can find more information at [Confidential Containers with Azure Kubernetes Service](../aks/confidential-containers-overview.md).

+But with these features of confidentiality, the product should additioanally its ease of use: it supports all unmodified Linux containers with high Kubernetes feature conformance. Additionally, it supports heterogenous node pools (GPU, general-purpose nodes) in a single cluster to optimize for cost.

+- [Azure portal](#azure-portal) (bearer token not required)

+### Azure portal

+To configure virtual network private ports using the Azure portal, follow these steps:

+1. In the [Azure portal](https://portal.azure.com), find and open your Standard logic app resource.

+1. On the logic app menu, under **Settings**, select **Configuration**.

+1. On the **Configuration** page, select **General settings**.

+1. Under **Platform settings**, in the **VNet Private Ports** box, enter the ports that you want to use.

+* Custom partitioning is only available for API for NoSQL in Azure Cosmos DB. API for MongoDB, Gremlin and Cassandra are in preview at this time.

+## May 2023

+### Data Factory in Microsoft Fabric

+[Data factory in Microsoft Fabric](/fabric/data-factory/) provides cloud-scale data movement and data transformation services that allow you to solve the most complex data factory and ETL scenarios. It's intended to make your data factory experience easy to use, powerful, and truly enterprise-grade.

+## January 2024

+### Data movement

+- The new Salesforce connector now supports OAuth authentication on Bulk API 2.0 for both source and sink. [Learn more](connector-salesforce.md)

+- The new Salesforce Service Cloud connector now supports OAuth authentication on Bulk API 2.0 for both source and sink. [Learn more](connector-salesforce-service-cloud.md)

+- The Google Ads connector now supports upgrading to the newer driver version with the native Google Ads Query Language (GAQL). [Learn more](connector-google-adwords.md#upgrade-the-google-ads-driver-version)

+### Region expansion

+Azure Data Factory is now available in Israel Central and Italy North. You can co-locate your ETL workflow in this new region if you are utilizing the region for storing and managing your modern data warehouse. [Learn more](https://techcommunity.microsoft.com/t5/azure-data-factory-blog/continued-region-expansion-azure-data-factory-is-generally/ba-p/4029391)

+In every account where enablement of this capability is completed, all images stored in ECR that meet the criteria for scan triggers are scanned for vulnerabilities without any extra configuration of users or registries. Recommendations with vulnerability reports are provided for all images in ECR as well as images that are currently running in EKS that were pulled from an ECR registry or any other Defender for Cloud supported registry (ACR, GCR, or GAR). Images are scanned shortly after being added to a registry, and rescanned for new vulnerabilities once every 24 hours.

+> Effective September 20, 2023, the secrets scanning (CredScan) tool within the Microsoft Security DevOps (MSDO) Extension for Azure DevOps has been deprecated. MSDO secrets scanning will be replaced with [GitHub Advanced Security for Azure DevOps](https://azure.microsoft.com/products/devops/github-advanced-security).

+Microsoft Defender for Cloud improves compute posture for Azure, AWS and GCP environments with machine scanning. For requirements and support, see the [compute support matrix in Defender for Cloud](support-matrix-defender-for-servers.md).

+- Threat detection with [agentless malware scanning](agentless-malware-scanning.md), using [Microsoft Defender Antivirus](/microsoft-365/security/defender-endpoint/microsoft-defender-antivirus-windows).

+One of the biggest challenges that security teams face today is the number of security issues they face on a daily basis. There are numerous security issues that need to be resolved and never enough resources to address them all.

+The cloud security graph is a graph-based context engine that exists within Defender for Cloud. The cloud security graph collects data from your multicloud environment and other data sources. For example, the cloud assets inventory, connections and lateral movement possibilities between resources, exposure to internet, permissions, network connections, vulnerabilities and more. The data collected is then used to build a graph representing your multicloud environment.

+Attack path analysis is a graph-based algorithm that scans the cloud security graph. The scans expose exploitable paths that attackers might use to breach your environment to reach your high-impact assets. Attack path analysis exposes attack paths and suggests recommendations as to how best remediate issues that will break the attack path and prevent successful breach.

+By running graph-based queries on the cloud security graph with the cloud security explorer, you can proactively identify security risks in your multicloud environments. Your security team can use the query builder to search for and locate risks, while taking your organization's specific contextual and conventional information into account.

+| **State** | **Azure storage accounts** | **AWS S3 Buckets** | **GCP Storage Buckets** |

+| | | | |

+|**Exposed to the internet** | An Azure storage account is considered exposed to the internet if either of these settings enabled:<br/><br/> Storage_account_name > **Networking** > **Public network access** > **Enabled from all networks**<br/><br/> or<br/><br/> Storage_account_name > **Networking** > **Public network access** > **Enable from selected virtual networks and IP addresses**. | An AWS S3 bucket is considered exposed to the internet if the AWS account/AWS S3 bucket policies don't have a condition set for IP addresses. | All GCP storage buckets are exposed to the internet by default. |

+|**Allows public access** | An Azure storage account container is considered as allowing public access if these settings are enabled on the storage account:<br/><br/> Storage_account_name > **Configuration** > **Allow blob public access** > **Enabled**.<br/><br/>and **either** of these settings:<br/><br/> Storage_account_name > **Containers** > container_name > **Public access level** set to **Blob (anonymous read access for blobs only)**<br/><br/> Or, storage_account_name > **Containers** > container_name > **Public access level** set to **Container (anonymous read access for containers and blobs)**. | An AWS S3 bucket is considered to allow public access if both the AWS account and the AWS S3 bucket have **Block all public access** set to **Off**, and **either** of these settings is set:<br/><br/> In the policy, **RestrictPublicBuckets** isn't enabled, and the **Principal** setting is set to * and **Effect** is set to **Allow**.<br/><br/> Or, in the access control list, **IgnorePublicAcl** isn't enabled, and permission is allowed for **Everyone**, or for **Authenticated users**. | A GCP storage bucket is considered to allow public access if: it has an IAM (Identity and Access Management) role that meets these criteria: <br/><br/> The role is granted to the principal **allUsers** or **allAuthenticatedUsers**. <br/><br/>The role has at least one storage permission that *isn't* **storage.buckets.create** or **storage.buckets.list**. Public access in GCP is called ΓÇ£Public to internetΓÇ£.|

+Defender for Azure Cosmos DB uses advanced threat detection capabilities, and [Microsoft Threat Intelligence](https://www.microsoft.com/insidetrack/microsoft-uses-threat-intelligence-to-protect-detect-and-respond-to-threats) data to provide contextual security alerts. Those alerts also include steps to mitigate the detected threats and prevent future attacks.

+You can [enable protection for all your databases](quickstart-enable-database-protections.md) (recommended), or [enable Microsoft Defender for Azure Cosmos DB](quickstart-enable-database-protections.md) at either the subscription level, or the resource level.

+Defender for Azure Cosmos DB continually analyzes the telemetry stream generated by the Azure Cosmos DB service. When potentially malicious activities are detected, security alerts are generated. These alerts are displayed in Defender for Cloud together with the details of the suspicious activity along with the relevant investigation steps, remediation actions, and security recommendations.

+Defender for Azure Cosmos DB doesn't access the Azure Cosmos DB account data, and doesn't have any effect on its performance.

+|Release state:| General Availability (GA) |

+Microsoft Defender for Azure Cosmos DB uses advanced threat detection capabilities and Microsoft Threat Intelligence data. Defender for Azure Cosmos DB continuously monitors your Azure Cosmos DB accounts for threats such as SQL injection, compromised identities and data exfiltration.

+This service provides action-oriented security alerts in Microsoft Defender for Cloud with details of the suspicious activity and guidance on how to mitigate the threats.

+You can use this information to quickly remediate security issues and improve the security of your Azure Cosmos DB accounts.

+Alerts include details of the incident that triggered them, and recommendations on how to investigate and remediate threats. Alerts can be exported to Microsoft Sentinel or any other third-party SIEM or any other external tool. To learn how to stream alerts, see [Stream alerts to a SIEM, SOAR, or IT classic deployment model solution](export-to-siem.md).

+Threat intelligence security alerts are triggered for:

+ Due to the structure and capabilities of Azure Cosmos DB queries, many known SQL injection attacks canΓÇÖt work in Azure Cosmos DB. However, there are some variations of SQL injections that can succeed and might result in exfiltrating data from your Azure Cosmos DB accounts. Defender for Azure Cosmos DB detects both successful and failed attempts, and helps you harden your environment to prevent these threats.

+ For example, access from a TOR exit node, known suspicious IP addresses, unusual applications, and unusual locations.

+ For example, suspicious key-listing patterns that resemble known malicious lateral movement techniques and suspicious data extraction patterns.

+In this article, you learned about Microsoft Defender for Azure Cosmos DB.

+Microsoft Defender for Cloud is now integrated with Microsoft Defender XDR. This integration allows security teams to access Defender for Cloud alerts and incidents within the Microsoft Defender Portal. This integration provides richer context to investigations that span cloud resources, devices, and identities.

+The partnership with Microsoft Defender XDR allows security teams to get the complete picture of an attack, including suspicious and malicious events that happen in their cloud environment. Security teams can accomplish this goal through immediate correlations of alerts and incidents.

+Incidents and alerts are now part of [Microsoft Defender XDR's public API](/microsoft-365/security/defender/api-overview). This integration allows exporting of security alerts data to any system using a single API. As Microsoft Defender for Cloud, we're committed to providing our users with the best possible security solutions, and this integration is a significant step towards achieving that goal.

+## Investigation experience in Microsoft Defender XDR

+| Incidents | All Defender for Cloud incidents are integrated to Microsoft Defender XDR. <br> - Searching for cloud resource assets in the [incident queue](/microsoft-365/security/defender/incident-queue) is supported. <br> - The [attack story](/microsoft-365/security/defender/investigate-incidents#attack-story) graph shows cloud resource. <br> - The [assets tab](/microsoft-365/security/defender/investigate-incidents#assets) in an incident page shows the cloud resource. <br> - Each virtual machine has its own entity page containing all related alerts and activity. <br> <br> There are no duplications of incidents from other Defender workloads. |

+| Alerts | All Defender for Cloud alerts, including multicloud, internal and external providersΓÇÖ alerts, are integrated to Microsoft Defender XDR. Defenders for Cloud alerts show on the Microsoft Defender XDR [alert queue](/microsoft-365/security/defender-endpoint/alerts-queue-endpoint-detection-response). <br>Microsoft Defender XDR<br> The `cloud resource` asset shows up in the Asset tab of an alert. Resources are clearly identified as an Azure, Amazon, or a Google Cloud resource. <br> <br> Defenders for Cloud alerts are automatically be associated with a tenant. <br> <br> There are no duplications of alerts from other Defender workloads.|

+| Unified API | Defender for Cloud alerts and incidents are now included in [Microsoft Defender XDRΓÇÖs public API](/microsoft-365/security/defender/api-overview), allowing customers to export their security alerts data into other systems using one API. |

+Learn more about [handling alerts in Microsoft Defender XDR](/microsoft-365/security/defender/microsoft-365-security-center-defender-cloud).

+Then, enable the `Tenant-based Microsoft Defender for Cloud (Preview)` connector to synchronize your subscriptions with your tenant-based Defender for Cloud incidents to stream through the Microsoft 365 Defender incidents connector.

+The connector is available through the Microsoft Defender for Cloud solution, version 3.0.0, in the Content Hub. If you have an earlier version of this solution, you can upgrade it in the Content Hub.

+You can use automation rules to close incidents immediately and prevent specific types of Defender for Cloud alerts from becoming incidents. You can also use the built-in tuning capabilities in the Microsoft 365 Defender portal to prevent alerts from becoming incidents.

+Customers who integrated their Microsoft 365 Defender incidents into Sentinel and want to keep their subscription-based settings and avoid tenant-based syncing can [opt out of syncing incidents and alerts](/microsoft-365/security/defender/microsoft-365-security-center-defender-cloud) through the Microsoft 365 Defender connector.

+Microsoft Defender for Cloud's Defender for Servers plans contains components that monitor your environments to provide extended coverage on your servers. Each of these components can be enabled, disabled or configured to your meet your specific requirements.

+With Microsoft Defender for Servers, you enable the protections provided by [Microsoft Defender for Endpoint](/microsoft-365/security/defender-endpoint/microsoft-defender-endpoint) to your server resources. Defender for Endpoint includes automatic agent deployment to your servers, and security data integration with Defender for Cloud.

+To disable The Defender for Servers plan or any of the features of the plan, navigate to the Environment settings page of the relevant subscription or workspace and toggle the relevant switch to **Off**.

+Defender for Cloud includes Foundational CSPM capabilities and access to [Microsoft Defender XDR](/microsoft-365/security/defender/microsoft-365-defender) for free. You can add additional paid plans to secure all aspects of your cloud resources. To learn more about these plans and their costs, see the Defender for Cloud [pricing page](https://azure.microsoft.com/pricing/details/defender-for-cloud/).

+The integration between Microsoft Defender for Cloud and Microsoft Defender XDR brings your cloud environments into Microsoft Defender XDR. With Defender for Cloud's alerts and cloud correlations integrated into Microsoft Defender XDR, SOC teams can now access all security information from a single interface.

+ > [!NOTE]

+ > To simulate agentless alerts for Defender for Containers, Azure Arc isn't a prerequisite.

+Defender for Cloud natively integrates with [Microsoft Defender XDR](/microsoft-365/security/defender/microsoft-365-defender) allows you to use Defender XDR's incidents and alerts API to stream alerts and incidents into non-Microsoft solutions. Defender for Cloud customers can access one API for all Microsoft security products and can use this integration as an easier way to export alerts and incidents.

+Learn how to [integrate SIEM tools with Defender XDR](/microsoft-365/security/defender/configure-siem-defender).

+Microsoft Sentinel includes built-in connectors for Microsoft Defender for Cloud at the subscription and tenant levels.

+### Set up the Azure services

+1. Enter the required parameters.

+**If you're streaming alerts to QRadar**:

+1. Create a consumer group.

+ | Syslog server | No | If you want to stream Azure Monitor data directly to a syslog server, you can use a [solution based on an Azure function](https://github.com/miguelangelopereira/azuremonitor2syslog/).|

+ | LogRhythm | No| Instructions to set up LogRhythm to collect logs from an event hub are available [here](https://logrhythm.com/six-tips-for-securing-your-azure-cloud-environment/).|

+ |Logz.io | Yes | For more information, see [Getting started with monitoring and logging using Logz.io for Java apps running on Azure](/azure/developer/java/fundamentals/java-get-started-with-logzio)|

+To protect all of your existing and future resources, we recommend you [enable Defender for Servers on your entire Azure subscription](#enable-on-an-azure-subscription-aws-account-or-gcp-project).

+You can exclude specific resources or manage security configurations at a lower hierarchy level by enabling the Defender for Servers plan at the resource level. You can enable the plan on the resource level with REST API or at scale.

+[Overview of Microsoft Defender for Servers](defender-for-servers-introduction.md).

+description: Enable developer teams to spin up infrastructure for deploying apps with project-based templates, while adding governance for Azure resource types, security, and cost.

+ Title: Create a deployment environment

+description: Learn how to create and access an environment in Azure Deployment Environments through the developer portal. An environment has all Azure resource preconfigured for deploying your application.

+This quickstart shows you how to create and access an [environment](concept-environments-key-concepts.md#environments) in Azure Deployment Environments by using the developer portal.

+As a developer, you can create environments associated with a [project](concept-environments-key-concepts.md#projects) in Azure Deployment Environments. An environment has all Azure resource preconfigured for deploying your application.

+ Title: Set up a dev center for Azure Deployment Environments

+description: Learn how to set up the resources to get started with Azure Deployment Environments. Configure a dev center, attach an identity, and attach a catalog for using IaC templates.

+A dev center is the top-level resource for getting started with Azure Deployment Environments that contains the collection of development projects. In the dev center, you specify the common configuration for your projects, such as catalogs with application templates, and the types of environments development teams can deploy to.

+A platform engineering team typically sets up the dev center, attaches external catalogs to the dev center, creates projects, and provides access to development teams. Development teams then create [environments](concept-environments-key-concepts.md#environments) by using [environment definitions](concept-environments-key-concepts.md#environment-definitions), connect to individual resources, and deploy applications. To learn more about the components of Azure Deployment Environments, see [Key concepts for Azure Deployment Environments](concept-environments-key-concepts.md).

+ Title: Create a project in Azure Deployment Environments

+description: Learn how to create a project for a dev center Azure Deployment Environments. In a project, you can define environment types and environments that are specific to a software development project.

+# Quickstart: Create and configure a project in Azure Deployment Environments

+This quickstart shows you how to create a project in Azure Deployment Environments, then associate the project with the dev center you created in [Quickstart: Create and configure a dev center](./quickstart-create-and-configure-devcenter.md). After you complete this quickstart, developers can use the developer portal to create environments in the project to deploy their applications.

+A project contains the specific configuration for environment types and environment definitions related to a development project. For example, you might create a project for the implementation of an ecommerce application, which has a development, staging, and production environment. For another project, you might define a different configuration.

+ Title: 'Tutorial: Access a dev box with a remote desktop client'

+description: In this tutorial, you learn how to connect to and access your dev box in Microsoft Dev Box by using a remote desktop (RDP) client app.

+In this tutorial, you download and use a remote desktop (RDP) client application to connect to and access a dev box.

+Alternately, you can access your dev box through the browser from the Microsoft Dev Box developer portal.

+You can use a remote desktop client application to access your dev box in Microsoft Dev Box. Remote desktop clients are available for many operating systems and devices.

+DTDL is based on JSON-LD and is programming-language independent. DTDL isn't exclusive to Azure Digital Twins. It is also used to represent device data in other IoT services such as [IoT Plug and Play](../iot/overview-iot-plug-and-play.md).

+> [IoT Plug and Play](../iot/overview-iot-plug-and-play.md) devices use a small syntax variant to describe their functionality. This syntax variant is a semantically compatible subset of the DTDL that is used in Azure Digital Twins. When using the parser library, you do not need to know which syntax variant was used to create the DTDL for your digital twin. The parser will always, by default, return the same model for both IoT Plug and Play and Azure Digital Twins syntax.

+>Version 2 of DTDL is also used for data models throughout other Azure IoT services, including [IoT Plug and Play](../iot/overview-iot-plug-and-play.md) and [Time Series Insights](../time-series-insights/overview-what-is-tsi.md). This compatibility helps you connect your Azure Digital Twins solution with other parts of the Azure ecosystem.

+ * [ΓÇ£SELECTΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_select) privilege at the server level on the source.

+ * If migrating views, user must have the [ΓÇ£SHOW VIEWΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_show-view) privilege on the source server and the [ΓÇ£CREATE VIEWΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_create-view) privilege on the target server.

+ * If migrating triggers, user must have the [ΓÇ£TRIGGERΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_trigger) privilege on the source and target server.

+ * If migrating routines (procedures and/or functions), the user must have the [ΓÇ£CREATE ROUTINEΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_create-routine) and [ΓÇ£ALTER ROUTINEΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_alter-routine) privileges granted at the server level on the target.

+ * If migrating events, the user must have the [ΓÇ£EVENTΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_event) privilege on the source and target server.

+ * If migrating users/logins, the user must have the ["CREATE USER"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_create-user) privilege on the target server.

+ * ["DROP"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_drop) privilege at the server level on the target, in order to drop tables that might already exist. For example, when retrying a migration.

+ * ["REFERENCES"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_references) privilege at the server level on the target, in order to create tables with foreign keys.

+ * If migrating to MySQL 8.0, the user must have the ["SESSION_VARIABLES_ADMIN"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_session-variables-admin) privilege on the target server.

+ * ["CREATE"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_create) privilege at the server level on the target.

+ * ["INSERT"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_insert) privilege at the server level on the target.

+ * ["UPDATE"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_update) privilege at the server level on the target.

+ * ["DELETE"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_delete) privilege at the server level on the target.

+ * [ΓÇ£SELECTΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_select) privilege at the server level on the source.

+ * If migrating views, user must have the [ΓÇ£SHOW VIEWΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_show-view) privilege on the source server and the [ΓÇ£CREATE VIEWΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_create-view) privilege on the target server.

+ * If migrating triggers, user must have the [ΓÇ£TRIGGERΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_trigger) privilege on the source and target server.

+ * If migrating routines (procedures and/or functions), the user must have the [ΓÇ£CREATE ROUTINEΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_create-routine) and [ΓÇ£ALTER ROUTINEΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_alter-routine) privileges granted at the server level on the target.

+ * If migrating events, the user must have the [ΓÇ£EVENTΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_event) privilege on the source and target server.

+ * If migrating users/logins, the user must have the ["CREATE USER"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_create-user) privilege on the target server.

+ * ["DROP"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_drop) privilege at the server level on the target, in order to drop tables that might already exist. For example, when retrying a migration.

+ * ["REFERENCES"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_references) privilege at the server level on the target, in order to create tables with foreign keys.

+ * If migrating to MySQL 8.0, the user must have the ["SESSION_VARIABLES_ADMIN"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_session-variables-admin) privilege on the target server.

+ * ["CREATE"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_create) privilege at the server level on the target.

+ * ["INSERT"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_insert) privilege at the server level on the target.

+ * ["UPDATE"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_update) privilege at the server level on the target.

+ * ["DELETE"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_delete) privilege at the server level on the target.

+ * [ΓÇ£SELECTΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_select) privilege at the server level on the source.

+ * If migrating views, user must have the [ΓÇ£SHOW VIEWΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_show-view) privilege on the source server and the [ΓÇ£CREATE VIEWΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_create-view) privilege on the target server.

+ * If migrating triggers, user must have the [ΓÇ£TRIGGERΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_trigger) privilege on the source and target server.

+ * If migrating routines (procedures and/or functions), the user must have the [ΓÇ£CREATE ROUTINEΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_create-routine) and [ΓÇ£ALTER ROUTINEΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_alter-routine) privileges granted at the server level on the target.

+ * If migrating events, the user must have the [ΓÇ£EVENTΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_event) privilege on the source and target server.

+ * If migrating users/logins, the user must have the ["CREATE USER"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_create-user) privilege on the target server.

+ * ["DROP"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_drop) privilege at the server level on the target, in order to drop tables that might already exist. For example, when retrying a migration.

+ * ["REFERENCES"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_references) privilege at the server level on the target, in order to create tables with foreign keys.

+ * If migrating to MySQL 8.0, the user must have the ["SESSION_VARIABLES_ADMIN"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_session-variables-admin) privilege on the target server.

+ * ["CREATE"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_create) privilege at the server level on the target.

+ * ["INSERT"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_insert) privilege at the server level on the target.

+ * ["UPDATE"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_update) privilege at the server level on the target.

+ * ["DELETE"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_delete) privilege at the server level on the target.

+ * [ΓÇ£SELECTΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_select) privilege at the server level on the source.

+ * If migrating views, user must have the [ΓÇ£SHOW VIEWΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_show-view) privilege on the source server and the [ΓÇ£CREATE VIEWΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_create-view) privilege on the target server.

+ * If migrating triggers, user must have the [ΓÇ£TRIGGERΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_trigger) privilege on the source and target server.

+ * If migrating routines (procedures and/or functions), the user must have the [ΓÇ£CREATE ROUTINEΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_create-routine) and [ΓÇ£ALTER ROUTINEΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_alter-routine) privileges granted at the server level on the target.

+ * If migrating events, the user must have the [ΓÇ£EVENTΓÇ¥](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_event) privilege on the source and target server.

+ * If migrating users/logins, the user must have the ["CREATE USER"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_create-user) privilege on the target server.

+ * ["DROP"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_drop) privilege at the server level on the target, in order to drop tables that might already exist. For example, when retrying a migration.

+ * ["REFERENCES"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_references) privilege at the server level on the target, in order to create tables with foreign keys.

+ * If migrating to MySQL 8.0, the user must have the ["SESSION_VARIABLES_ADMIN"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_session-variables-admin) privilege on the target server.

+ * ["CREATE"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_create) privilege at the server level on the target.

+ * ["INSERT"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_insert) privilege at the server level on the target.

+ * ["UPDATE"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_update) privilege at the server level on the target.

+ * ["DELETE"](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_delete) privilege at the server level on the target.

+Event Grid's **Partner Events** allows customers to **subscribe to events** that originate in a registered system using the same mechanism they would use for any other event source on Azure, such as an Azure service. Those registered systems integrate with Event Grid are known as "partners". This feature also enables customers to **send events** to partner systems that support receiving and routing events to customer's solutions/endpoints in their platform. Typically, partners are software-as-a-service (SaaS) or [ERP](https://en.wikipedia.org/wiki/Enterprise_resource_planning) providers, but they might be corporate platforms wishing to make their events available to internal teams. They purposely integrate with Event Grid to realize end-to-end customer use cases that end on Azure (customers subscribe to events sent by partner) or end on a partner system (customers subscribe to Microsoft events sent by Azure Event Grid). Customers bank on Azure Event Grid to send events published by a partner to supported destinations such as webhooks, Azure Functions, Azure Event Hubs, or Azure Service Bus, to name a few. Customers also rely on Azure Event Grid to route events that originate in Microsoft services, such as Outlook, Teams, or Microsoft Entra ID, so that customer's solutions can react to them. With Partner Events, customers can build event-driven solutions across platforms and network boundaries to receive or send events reliably, securely and at a scale.

+ $appRole = New-Object Microsoft.Graph.PowerShell.Models.MicrosoftGraphAppRole

+ $appRole.AllowedMemberTypes += "Application";

+ $appRole.AllowedMemberTypes += "User";

+ # Creates Azure Event Grid Microsoft Entra Application if not exists

+ # But Azure Event Grid Entra Application Id is different for different clouds

+ $eventGridSP = Get-MgServicePrincipal -Filter ("appId eq '" + $eventGridAppId + "'")

+ if ($eventGridSP.DisplayName -match "Microsoft.EventGrid")

+ Write-Host "The Event Grid Microsoft Entra Application is already defined.`n"

+ Write-Host "Creating the Azure Event Grid Microsoft Entra Application"

+ $eventGridSP = New-MgServicePrincipal -AppId $eventGridAppId

+ # Creates the Azure app role for the webhook Microsoft Entra application

+ $eventGridRoleName = "AzureEventGridSecureWebhookSubscriber" # You don't need to modify this role name

+ $app = Get-MgApplication -ObjectId $webhookAppObjectId

+ Write-Host "Microsoft Entra App roles before addition of the new role..."

+ Write-Host $appRoles.DisplayName

+ if ($appRoles.DisplayName -match $eventGridRoleName)

+ Write-Host "Creating the Azure Event Grid role in Microsoft Entra Application: " $webhookAppObjectId

+ $appRoles += $newRole

+ Update-MgApplication -ApplicationId $webhookAppObjectId -AppRoles $appRoles

+ Write-Host "Microsoft Entra App roles after addition of the new role..."

+ Write-Host $appRoles.DisplayName

+ $servicePrincipal = Get-MgServicePrincipal -Filter ("appId eq '" + $app.AppId + "'")

+ $eventSubscriptionWriterSP = Get-MgServicePrincipal -Filter ("appId eq '" + $eventSubscriptionWriterAppId + "'")

+ Write-Host "Create new Microsoft Entra Application"

+ $eventSubscriptionWriterSP = New-MgServicePrincipal -AppId $eventSubscriptionWriterAppId

+ Write-Host "Creating the Microsoft Entra Application role assignment: " $eventSubscriptionWriterAppId

+ New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $eventSubscriptionWriterSP.Id -PrincipalId $eventSubscriptionWriterSP.Id -ResourceId $servicePrincipal.Id -AppRoleId $eventGridAppRole.Id

+ Write-Host "The Microsoft Entra Application role is already defined.`n"

+ # Creates the service app role assignment for Event Grid Microsoft Entra Application

+ New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $eventGridSP.Id -PrincipalId $eventGridSP.Id -ResourceId $servicePrincipal.Id -AppRoleId $eventGridAppRole.Id

+ Write-Host ">> Webhook's Microsoft Entra Application Id: $($app.AppId)"

+ Write-Host ">> Webhook's Microsoft Entra Application ObjectId Id: $($app.ObjectId)"

+For more information, see [Secure WebHook delivery with Microsoft Entra ID in Azure Event Grid](../secure-webhook-delivery.md).

+1. Add service principal of user who is creating the subscription to the AzureEventGridSecureWebhookSubscriber role.

+## Sample script

+$webhookAppId = "[REPLACE_WITH_YOUR_ID]"

+ $appRole = New-Object Microsoft.Graph.PowerShell.Models.MicrosoftGraphAppRole

+ $appRole.AllowedMemberTypes += "Application";

+ $appRole.AllowedMemberTypes += "User";

+ # Creates Azure Event Grid Microsoft Entra Application if not exists

+ # But Azure Event Grid Microsoft Entra Application Id is different for different clouds

+ $eventGridSP = Get-MgServicePrincipal -Filter ("appId eq '" + $eventGridAppId + "'")

+ if ($eventGridSP.DisplayName -match "Microsoft.EventGrid")

+ Write-Host "The Event Grid Microsoft Entra Application is already defined.`n"

+ Write-Host "Creating the Azure Event Grid Microsoft Entra Application"

+ $eventGridSP = New-MgServicePrincipal -AppId $eventGridAppId

+ # Creates the Azure app role for the webhook Microsoft Entra application

+ $eventGridRoleName = "AzureEventGridSecureWebhookSubscriber" # You don't need to modify this role name

+ $app = Get-MgApplication -ApplicationId $webhookAppObjectId

+ Write-Host "Microsoft Entra App roles before addition of the new role..."

+ Write-Host $appRoles.DisplayName

+ if ($appRoles.DisplayName -match $eventGridRoleName)

+ Write-Host "Creating the Azure Event Grid role in Microsoft Entra Application: " $webhookAppObjectId

+ $appRoles += $newRole

+ Update-MgApplication -ApplicationId $webhookAppObjectId -AppRoles $appRoles

+ Write-Host "Microsoft Entra App roles after addition of the new role..."

+ Write-Host $appRoles.DisplayName

+ $servicePrincipal = Get-MgServicePrincipal -Filter ("appId eq '" + $app.AppId + "'")

+ Write-Host "Creating the Microsoft Entra App Role assignment for user: " $eventSubscriptionWriterUserPrincipalName

+ $eventSubscriptionWriterUser = Get-MgUser -UserId $eventSubscriptionWriterUserPrincipalName

+ New-MgUserAppRoleAssignment -UserId $eventSubscriptionWriterUser.Id -PrincipalId $eventSubscriptionWriterUser.Id -ResourceId $servicePrincipal.Id -AppRoleId $eventGridAppRole.Id

+ Write-Host "The Microsoft Entra User Application role is already defined.`n"

+ # Creates the service app role assignment for Event Grid Microsoft Entra Application

+ New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $eventGridSP.Id -PrincipalId $eventGridSP.Id -ResourceId $servicePrincipal.Id -AppRoleId $eventGridAppRole.Id

+ Write-Host ">> Webhook's Microsoft Entra Application Id: $($app.AppId)"

+ Write-Host ">> Webhook's Microsoft Entra Application Object Id: $($app.Id)"

+For more information, see [Secure WebHook delivery with Microsoft Entra ID in Azure Event Grid](../secure-webhook-delivery.md).

+1. Create a Microsoft Entra application for the webhook configured to work with the Microsoft Entra (single tenant).

+ $webhookAadTenantId = "[REPLACE_WITH_YOUR_TENANT_ID]"

+ Connect-MgGraph -TenantId $webhookAadTenantId -Scopes "Application.ReadWrite.All, AppRoleAssignment.ReadWrite.All"

+ New-MgServicePrincipalAppRoleAssignment: Error occurred while executing NewServicePrincipalAppRoleAssignment

+1. Create a Microsoft Entra application for the Event Grid subscription writer configured to work with the Microsoft Entra (Single tenant).

+4. Create a Microsoft Entra application for the webhook configured to work with the Microsoft Entra (Single tenant).

+ $webhookAadTenantId = "[REPLACE_WITH_YOUR_TENANT_ID]"

+ Connect-MgGraph -TenantId $webhookAadTenantId -Scopes "Application.ReadWrite.All, AppRoleAssignment.ReadWrite.All"

+ az login --service-principal -u [REPLACE_WITH_EVENT_GRID_SUBSCRIPTION_WRITER_APP_ID] -p [REPLACE_WITH_EVENT_GRID_SUBSCRIPTION_WRITER_APP_SECRET_VALUE] --tenant [REPLACE_WITH_TENANT_ID]

+ az eventgrid system-topic event-subscription create --name [REPLACE_WITH_SUBSCRIPTION_NAME] -g [REPLACE_WITH_RESOURCE_GROUP] --system-topic-name [REPLACE_WITH_SYSTEM_TOPIC] --endpoint [REPLACE_WITH_WEBHOOK_ENDPOINT] --event-delivery-schema [REPLACE_WITH_WEBHOOK_EVENT_SCHEMA] --azure-active-directory-tenant-id [REPLACE_WITH_TENANT_ID] --azure-active-directory-application-id-or-uri [REPLACE_WITH_APPLICATION_ID_FROM_SCRIPT] --endpoint-type webhook

+1. Create a Microsoft Entra application for the Event Grid subscription writer configured to work with any Microsoft Entra (multitenant).

+1. Create a Microsoft Entra Application for the webhook configured to work with the Microsoft Entra (single tenant).

+ $webhookAadTenantId = "[REPLACE_WITH_YOUR_TENANT_ID]"

+ Connect-MgGraph -TenantId $webhookAadTenantId -Scopes "Application.ReadWrite.All, AppRoleAssignment.ReadWrite.All"

+ New-MgServicePrincipalAppRoleAssignment: Error occurred while executing NewServicePrincipalAppRoleAssignment

+ az login --service-principal -u [REPLACE_WITH_APP_ID] -p [REPLACE_WITH_SECRET_VALUE] --tenant [REPLACE_WITH_TENANT_ID]

+ az eventgrid system-topic event-subscription create --name [REPLACE_WITH_SUBSCRIPTION_NAME] -g [REPLACE_WITH_RESOURCE_GROUP] --system-topic-name [REPLACE_WITH_SYSTEM_TOPIC] --endpoint [REPLACE_WITH_WEBHOOK_ENDPOINT] --event-delivery-schema [REPLACE_WITH_WEBHOOK_EVENT_SCHEMA] --azure-active-directory-tenant-id [REPLACE_WITH_TENANT_B_ID] --azure-active-directory-application-id-or-uri [REPLACE_WITH_APPLICATION_ID_FROM_SCRIPT] --endpoint-type webhook

+## SQL

+## Synapse

+## Stack HCI

+|Trino |Yes** |Yes**|

+### Metastore configuration

+Configure external Hive metastore database in `config.properties` file:

+```json

+{

+ "fileName": "config.properties",

+ "values": {

+ "hive.metastore.hdi.metastoreDbConnectionURL": "jdbc:sqlserver://mysqlserver1.database.windows.net;database=myhmsdb1;encrypt=true;trustServerCertificate=true;create=false;loginTimeout=30",

+ "hive.metastore.hdi.metastoreDbConnectionUserName": "trinoadmin",

+ "hive.metastore.hdi.metastoreDbConnectionPasswordSecret": "hms-db-pwd",

+ "hive.metastore.hdi.metastoreWarehouseDir": "abfs://container1@myadlsgen2account1.dfs.core.windows.net/hive/warehouse"

+ }

+}

+```

+| Property| Description| Example|

+||||

+|hive.metastore.hdi.metastoreDbConnectionURL|JDBC connection string to database.|jdbc:sqlserver://mysqlserver1.database.windows.net;database=myhmsdb1;encrypt=true;trustServerCertificate=true;create=false;loginTimeout=30|

+|hive.metastore.hdi.metastoreDbConnectionUserName|SQL user name to connect to database.|trinoadmin|

+|hive.metastore.hdi.metastoreDbConnectionPasswordSecret|Secret referenceName configured in secretsProfile with password.|hms-db-pwd|

+|hive.metastore.hdi.metastoreWarehouseDir|ABFS URI to location in storage where data is stored.|`abfs://container1@myadlsgen2account1.dfs.core.windows.net/hive/warehouse`|

+### Metastore authentication

+Configure authentication to external Hive metastore database specifying Azure Key Vault secrets.

+> [!NOTE]

+> `referenceName` should match value provided in `hive.metastore.hdi.metastoreDbConnectionPasswordSecret`

+```json

+"secretsProfile": {

+ "keyVaultResourceId": "/subscriptions/{USER_SUBSCRIPTION_ID}/resourceGroups/{USER_RESOURCE_GROUP}/providers/Microsoft.KeyVault/vaults/{USER_KEYVAULT_NAME}",

+ "secrets": [

+ {

+ "referenceName": "hms-db-pwd",

+ "type": "secret",

+ "keyVaultObjectName": "hms-db-pwd"

+ } ]

+},

+```

+### Catalog configuration

+In order for a Trino catalog to use external Hive metastore it should specify `hive.metastore=hdi` property. For more information, see [Add catalogs to existing cluster](trino-add-catalogs.md):

+```

+{

+ "fileName": "hive1.properties",

+ "values": {

+ "connector.name": "hive",

+ "hive.metastore": "hdi"

+ }

+}

+```

+### Complete example

+To configure external Hive metastore to an existing Trino cluster, add the required sections in your cluster ARM template by referring to the following example:

+ {

+ "component": "common",

+ "files": [

+ {

+ "fileName": "config.properties",

+ "values": {

+ "hive.metastore.hdi.metastoreDbConnectionURL": "jdbc:sqlserver://mysqlserver1.database.windows.net;database=myhmsdb1;encrypt=true;trustServerCertificate=true;create=false;loginTimeout=30",

+ "hive.metastore.hdi.metastoreDbConnectionUserName": "trinoadmin",

+ "hive.metastore.hdi.metastoreDbConnectionPasswordSecret": "hms-db-pwd",

+ "hive.metastore.hdi.metastoreWarehouseDir": "abfs://container1@myadlsgen2account1.dfs.core.windows.net/hive/warehouse"

+ }

+ }

+ ]

+ },

+ "connector.name": "hive",

+ "hive.metastore": "hdi"

+ ]

+## Alternative configuration

+Alternatively external Hive metastore database parameters can be specified in `trinoProfile.catalogOptions.hive` together with `hive.metastore=hdi` catalog property:

+| Property| Description| Example|

+||||

+|trinoProfile.catalogOptions.hive|List of Hive or iceberg or delta catalogs with parameters of external Hive metastore database, require parameters for each. To use external metastore database, catalog must be present in this list.

+|trinoProfile.catalogOptions.hive[*].catalogName|Name of Trino catalog configured in `serviceConfigsProfiles`, which configured to use external Hive metastore database.|hive1|

+|trinoProfile.catalogOptions.hive[*].metastoreDbConnectionURL|JDBC connection string to database.|jdbc:sqlserver://mysqlserver1.database.windows.net;database=myhmsdb1;encrypt=true;trustServerCertificate=true;create=false;loginTimeout=30|

+|trinoProfile.catalogOptions.hive[*].metastoreDbConnectionUserName|SQL user name to connect to database.|trinoadmin|

+|trinoProfile.catalogOptions.hive[*].metastoreDbConnectionPasswordSecret|Secret referenceName configured in secretsProfile with password.|hms-db-pwd|

+|trinoProfile.catalogOptions.hive[*].metastoreWarehouseDir|ABFS URI to location in storage where data is stored.|`abfs://container1@myadlsgen2account1.dfs.core.windows.net/hive/warehouse`|

+### Complete example

+```json

+{

+ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",

+ "contentVersion": "1.0.0.0",

+ "parameters": {},

+ "resources": [

+ {

+ "type": "microsoft.hdinsight/clusterpools/clusters",

+ "apiVersion": "<api-version>",

+ "name": "<cluster-pool-name>/<cluster-name>",

+ "location": "<region, e.g. westeurope>",

+ "tags": {},

+ "properties": {

+ "clusterType": "Trino",

+ "clusterProfile": {

+ "secretsProfile": {

+ "keyVaultResourceId": "/subscriptions/{USER_SUBSCRIPTION_ID}/resourceGroups/{USER_RESOURCE_GROUP}/providers/Microsoft.KeyVault/vaults/{USER_KEYVAULT_NAME}",

+ "secrets": [

+ {

+ "referenceName": "hms-db-pwd",

+ "type": "secret",

+ "keyVaultObjectName": "hms-db-pwd"

+ } ]

+ },

+ "serviceConfigsProfiles": [

+ {

+ "serviceName": "trino",

+ "configs": [

+ {

+ "component": "catalogs",

+ "files": [

+ {

+ "fileName": "hive1.properties",

+ "values": {

+ "connector.name": "hive",

+ "hive.metastore": "hdi"

+ }

+ }

+ ]

+ }

+ ]

+ }

+ ],

+ "trinoProfile": {

+ "catalogOptions": {

+ "hive": [

+ {

+ "catalogName": "hive1",

+ "metastoreDbConnectionURL": "jdbc:sqlserver://mysqlserver1.database.windows.net;database=myhmsdb1;encrypt=true;trustServerCertificate=true;create=false;loginTimeout=30",

+ "metastoreDbConnectionUserName": "trinoadmin",

+ "metastoreDbConnectionPasswordSecret": "hms-db-pwd",

+ "metastoreWarehouseDir": "abfs://container1@myadlsgen2account1.dfs.core.windows.net/hive/warehouse"

+ }

+ ]

+ }

+ }

+ }

+ }

+ }

+ ]

+}

+```

+The [device implementation](tutorial-connect-device.md) should follow the [IoT Plug and Play conventions](../../iot/concepts-convention.md) to ensure that it can communicate with IoT Central. For more information, see the various language [SDKs and samples](../../iot-develop/about-iot-sdks.md).

+[IoT Plug and Play](../../iot/overview-iot-plug-and-play.md) defines a set of [conventions](../../iot/concepts-convention.md) that a device should follow when it implements a Digital Twin Definition Language (DTDL) model.

+To learn more about device models, see the [IoT Plug and Play modeling guide](../../iot/concepts-modeling-guide.md)

+To learn more about the IoT Plug and Play conventions, see [IoT Plug and Play conventions](../../iot/concepts-convention.md).

+To learn more about the format of the JSON messages that a device exchanges with IoT Central, see [Telemetry, property, and command payloads](../../iot/concepts-message-payloads.md).

+To learn more about device error codes, see [Troubleshooting device connections](troubleshooting.md).

+A solution builder adds device templates to an IoT Central application. A device developer writes the device code that implements the behaviors defined in the device template. To learn more about the data that a device exchanges with IoT Central, see [Telemetry, property, and command payloads](../../iot/concepts-message-payloads.md).

+To learn more about DTDL models, see the [IoT Plug and Play modeling guide](../../iot/concepts-modeling-guide.md).

+Now that you've learned about device templates, a suggested next step is to read [Telemetry, property, and command payloads](../../iot/concepts-message-payloads.md) to learn more about the data a device exchanges with IoT Central.

+- The device must follow the [IoT Plug and Play conventions](../../iot/concepts-convention.md).

+Components let you group and reuse device capabilities. To learn more about components and device models, see the [IoT Plug and Play modeling guide](../../iot/concepts-modeling-guide.md).

+If you don't see data arriving in your destination service, see [Troubleshoot issues with data exports from your Azure IoT Central application](troubleshooting.md).

+If you don't see data arriving in your destination service, see [Troubleshoot issues with data exports from your Azure IoT Central application](troubleshooting.md).

+If you don't see data arriving in your destination service, see [Troubleshoot issues with data exports from your Azure IoT Central application](troubleshooting.md).

+If you don't see data arriving in your destination service, see [Troubleshoot issues with data exports from your Azure IoT Central application](troubleshooting.md).

+A suggested next step is to learn [Troubleshoot why data from your devices isn't showing up in Azure IoT Central](troubleshooting.md).

+1. Select the ellipsis to add an inherited interface or component to the root interface. To learn more about interfaces and component see [multiple components](../../iot/concepts-modeling-guide.md) in the modeling guide.

+To learn more about how devices implement commands, see [Telemetry, property, and command payloads > Commands and long running commands](../../iot/concepts-message-payloads.md#commands).

+| Message Format | Convert to or manipulate JSON messages. | CSV to JSON | At ingress. IoT Central only accepts value JSON messages. To learn more, see [Telemetry, property, and command payloads](../../iot/concepts-message-payloads.md). |

+To learn about the IoT Pug and Play command conventions, see [IoT Plug and Play conventions](../../iot/concepts-convention.md).

+To learn more about the command data that a device exchanges with IoT Central, see [Telemetry, property, and command payloads](../../iot/concepts-message-payloads.md).

+To learn about the Digital Twin Definition Language (DTDL) that Azure IoT Central uses to define commands in a device template, see [IoT Plug and Play conventions > Commands](../../iot/concepts-convention.md#commands).

+Now that you've learned how to use commands in your Azure IoT Central application, see [Telemetry, property, and command payloads](../../iot/concepts-message-payloads.md) to learn more about command parameters and [Create and connect a client application to your Azure IoT Central application](tutorial-connect-device.md) to see complete code samples in different languages.

+* [Telemetry, property, and command payloads](../../iot/concepts-message-payloads.md)

+To learn about the IoT Pug and Play property conventions, see [IoT Plug and Play conventions](../../iot/concepts-convention.md).

+To learn more about the property data that a device exchanges with IoT Central, see [Telemetry, property, and command payloads](../../iot/concepts-message-payloads.md).

+To learn about the Digital Twin Definition Language (DTDL) that Azure IoT Central uses to define properties in a device template, see [IoT Plug and Play conventions > Read-only properties](../../iot/concepts-convention.md#read-only-properties).

+A device sends property updates as a JSON payload. For more information, see [Telemetry, property, and command payloads](../../iot/concepts-message-payloads.md).

+The response message should include the `ac` and `av` fields. The `ad` field is optional. To learn more, see [IoT Plug and Play conventions > Writable properties](../../iot/concepts-convention.md#writable-properties).

+* [IoT Plug and Play conventions](../../iot/concepts-convention.md)

+* [Telemetry, property, and command payloads](../../iot/concepts-message-payloads.md)

+The [troubleshooting guide](troubleshooting.md) helps you to diagnose and remediate common issues. You can use the **Devices** page to block devices that appear to be malfunctioning until the problem is resolved.

+ Title: Troubleshooting in Azure IoT Central

+description: Troubleshoot and resolve issues with device connections and data export configurations in your IoT Central application

+#Customer intent: As a device developer, I want to understand why data from my devices isn't showing up in IoT Central, and the steps I can take to rectify the issue.

+# Troubleshooting in Azure IoT Central

+This article includes troubleshooting guidance for device connectivity issues and data export configuration issues in your IoT Central applications.

+## Device connectivity issues

+This section helps you determine if your data is reaching IoT Central.

+If you haven't already done so, install the `az cli` tool and `azure-iot` extension.

+To learn how to install the `az cli`, see [Install the Azure CLI](/cli/azure/install-azure-cli).

+To [install](/cli/azure/azure-cli-reference-for-IoT#extension-reference-installation) the `azure-iot` extension, run the following command:

+```azurecli

+az extension add --name azure-iot

+```

+> [!NOTE]

+> You may be prompted to install the `uamqp` library the first time you run an extension command.

+When you've installed the `azure-iot` extension, start your device to see if the messages it's sending are making their way to IoT Central.

+Use the following commands to sign in the subscription where you have your IoT Central application:

+```azurecli

+az login

+az account set --subscription <your-subscription-id>

+```

+To monitor the telemetry your device is sending, use the following command:

+```azurecli

+az iot central diagnostics monitor-events --app-id <iot-central-app-id> --device-id <device-name>

+```

+If the device has connected successfully to IoT Central, you see output similar to the following example:

+```output

+Monitoring telemetry.

+Filtering on device: device-001

+{

+ "event": {

+ "origin": "device-001",

+ "module": "",

+ "interface": "",

+ "component": "",

+ "payload": {

+ "temp": 65.57910343679293,

+ "humid": 36.16224660107426

+ }

+ }

+}

+```

+To monitor the property updates your device is exchanging with IoT Central, use the following preview command:

+```azurecli

+az iot central diagnostics monitor-properties --app-id <iot-central-app-id> --device-id <device-name>

+```

+If the device successfully sends property updates, you see output similar to the following example:

+```output

+Changes in reported properties:

+version : 32

+{'state': 'true', 'name': {'value': {'value': 'Contoso'}, 'status': 'completed', 'desiredVersion': 7, 'ad': 'completed', 'av': 7, 'ac

+': 200}, 'brightness': {'value': {'value': 2}, 'status': 'completed', 'desiredVersion': 7, 'ad': 'completed', 'av': 7, 'ac': 200}, 'p

+rocessorArchitecture': 'ARM', 'swVersion': '1.0.0'}

+```

+If you see data appear in your terminal, then the data is making it as far as your IoT Central application.

+If you don't see any data appear after a few minutes, try pressing the `Enter` or `return` key on your keyboard, in case the output is stuck.

+If you're still not seeing any data appear on your terminal, it's likely that your device is having network connectivity issues, or isn't sending data correctly to IoT Central.

+### Check the provisioning status of your device

+If your data isn't appearing in the CLI monitor, check the provisioning status of your device by running the following command:

+```azurecli

+az iot central device registration-info --app-id <iot-central-app-id> --device-id <device-name>

+```

+The following output shows an example of a device that's blocked from connecting:

+```json

+{

+ "@device_id": "v22upeoqx6",

+ "device_registration_info": {

+ "device_status": "blocked",

+ "display_name": "Environmental Sensor - v22upeoqx6",

+ "id": "v22upeoqx6",

+ "instance_of": "urn:krhsi_k0u:modelDefinition:w53jukkazs",

+ "simulated": false

+ },

+ "dps_state": {

+ "error": "Device is blocked from connecting to IoT Central application. Unblock the device in IoT Central and retry. Learn more:

+https://aka.ms/iotcentral-docs-dps-SAS",

+ "status": null

+ }

+}

+```

+| Device provisioning status | Description | Possible mitigation |

+| - | - | - |

+| Provisioned | No immediately recognizable issue. | N/A |

+| Registered | The device hasn't yet connected to IoT Central. | Check your device logs for connectivity issues. |

+| Blocked | The device is blocked from connecting to IoT Central. | Device is blocked from connecting to the IoT Central application. Unblock the device in IoT Central and retry. To learn more, see [Device status values](howto-manage-devices-individually.md#device-status-values). |

+| Unapproved | The device isn't approved. | Device isn't approved to connect to the IoT Central application. Approve the device in IoT Central and retry. To learn more, see [Device status values](howto-manage-devices-individually.md#device-status-values) |

+| Unassigned | The device isn't assigned to a device template. | Assign the device to a device template so that IoT Central knows how to parse the data. |

+Learn more about [Device status values in the UI](howto-manage-devices-individually.md#device-status-values) and [Device status values in the REST API](howto-manage-devices-with-rest-api.md#get-a-device).

+### Error codes

+If you're still unable to diagnose why your data isn't showing up in `monitor-events`, the next step is to look for error codes reported by your device.

+Start a debugging session on your device, or collect logs from your device. Check for any error codes that the device reports.

+The following tables show the common error codes and possible actions to mitigate.

+If you're seeing issues related to your authentication flow:

+| Error code | Description | Possible Mitigation |

+| - | - | - |

+| 400 | The body of the request isn't valid. For example, it can't be parsed, or the object can't be validated. | Ensure that you're sending the correct request body as part of the attestation flow, or use a device SDK. |

+| 401 | The authorization token can't be validated. For example, it has expired or doesn't apply to the request's URI. This error code is also returned to devices as part of the TPM attestation flow. | Ensure that your device has the correct credentials. |

+| 404 | The Device Provisioning Service instance, or a resource such as an enrollment doesn't exist. | [File a ticket with customer support](https://portal.azure.com/#blade/Microsoft_Azure_Support/HelpAndSupportBlade/overview). |

+| 412 | The `ETag` in the request doesn't match the `ETag` of the existing resource, as per RFC7232. | [File a ticket with customer support](https://portal.azure.com/#blade/Microsoft_Azure_Support/HelpAndSupportBlade/overview). |

+| 429 | The service is throttling operations. For specific service limits, see [IoT Hub Device Provisioning Service limits](../../azure-resource-manager/management/azure-subscription-service-limits.md#iot-hub-device-provisioning-service-limits). | Reduce message frequency, split responsibilities among more devices. |

+| 500 | An internal error occurred. | [File a ticket with customer support](https://portal.azure.com/#blade/Microsoft_Azure_Support/HelpAndSupportBlade/overview) to see if they can help you further. |

+### Detailed authorization error codes

+| Error | Sub error code | Notes |

+| - | - | - |

+| 401 Unauthorized | 401002 | The device is using invalid or expired credentials. DPS reports this error. |

+| 401 Unauthorized | 400209 | The device is either waiting for approval by an operator or an operator has blocked it. |

+| 401 IoTHubUnauthorized | | The device is using expired security token. IoT Hub reports this error. |

+| 401 IoTHubUnauthorized | DEVICE_DISABLED | The device is disabled in this IoT hub and has moved to another IoT hub. Reprovision the device. |

+| 401 IoTHubUnauthorized | DEVICE_BLOCKED | An operator has blocked this device. |

+### File upload error codes

+Here's a list of common error codes you might see when a device tries to upload a file to the cloud. Remember that before your device can upload a file, you must configure [device file uploads](howto-configure-file-uploads.md) in your application.

+| Error code | Description | Possible Mitigation |

+| - | - | - |

+| 403006 | You've exceeded the number of concurrent file upload operations. Each device client is limited to 10 concurrent file uploads. | Ensure the device promptly notifies IoT Central that the file upload operation has completed. If that doesn't work, try reducing the request timeout. |

+## Unmodeled data issues

+When you've established that your device is sending data to IoT Central, the next step is to ensure that your device is sending data in a valid format.

+To detect which categories your issue is in, run the most appropriate Azure CLI command for your scenario:

+- To validate telemetry, use the preview command:

+ ```azurecli

+ az iot central diagnostics validate-messages --app-id <iot-central-app-id> --device-id <device-name>

+ ```

+- To validate property updates, use the preview command:

+ ```azurecli

+ az iot central diagnostics validate-properties --app-id <iot-central-app-id> --device-id <device-name>

+ ```

+You may be prompted to install the `uamqp` library the first time you run a `validate` command.

+The three common types of issue that cause device data to not appear in IoT Central are:

+- Device template to device data mismatch.

+- Data is invalid JSON.

+- Old versions of IoT Edge cause telemetry from components to display incorrectly as unmodeled data.

+### Device template to device data mismatch

+A device must use the same name and casing as used in the device template for any telemetry field names in the payload it sends. The following output shows an example warning message where the device is sending a telemetry value called `Temperature`, when it should be `temperature`:

+```output

+Validating telemetry.

+Filtering on device: sample-device-01.

+Exiting after 300 second(s), or 10 message(s) have been parsed (whichever happens first).

+[WARNING] [DeviceId: sample-device-01] [TemplateId: urn:modelDefinition:ofhmazgddj:vmjwwjuvdzg] Device is sending data that has not been defined in the device template. Following capabilities have NOT been defined in the device template '['Temperature']'. Following capabilities have been defined in the device template (grouped by components) '{'thermostat1': ['temperature', 'targetTemperature', 'maxTempSinceLastReboot', 'getMaxMinReport'], 'thermostat2': ['temperature', 'targetTemperature', 'maxTempSinceLastReboot', 'getMaxMinReport'], 'deviceInformation': ['manufacturer', 'model', 'swVersion', 'osName', 'processorArchitecture', 'processorManufacturer', 'totalStorage', 'totalMemory']}'.

+```

+A device must use the same name and casing as used in the device template for any property names in the payload it sends. The following output shows an example warning message where the property `osVersion` isn't defined in the device template:

+```output

+Command group 'iot central diagnostics' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

+[WARNING] [DeviceId: sample-device-01] [TemplateId: urn:modelDefinition:ofhmazgddj:vmjwwjuvdzg] Device is sending data that has not been defined in the device template. Following capabilities have NOT been defined in the device template '['osVersion']'. Following capabilities have been defined in the device template (grouped by components) '{'thermostat1': ['temperature', 'targetTemperature', 'maxTempSinceLastReboot', 'getMaxMinReport', 'rundiagnostics'], 'thermostat2': ['temperature', 'targetTemperature', 'maxTempSinceLastReboot', 'getMaxMinReport', 'rundiagnostics'], 'deviceInformation': ['manufacturer', 'model', 'swVersion', 'osName', 'processorArchitecture', 'processorManufacturer', 'totalStorage', 'totalMemory']}'.

+```

+A device must use the data types defined in the device template for any telemetry or property values. For example, you see a schema mismatch if the type defined in the device template is boolean, but the device sends a string. The following output shows an example error message where the device using a string value for a property that's defined as a double:

+```output

+Command group 'iot central diagnostics' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

+Validating telemetry.

+Filtering on device: sample-device-01.

+Exiting after 300 second(s), or 10 message(s) have been parsed (whichever happens first).

+[ERROR] [DeviceId: sample-device-01] [TemplateId: urn:modelDefinition:ofhmazgddj:vmjwwjuvdzg] Datatype of telemetry field 'temperature' does not match the datatype double. Data sent by the device : curr_temp. For more information, see: https://aka.ms/iotcentral-payloads

+```

+The validation commands also report an error if the same telemetry name is defined in multiple interfaces, but the device isn't IoT Plug and Play compliant.

+If you prefer to use a GUI, use the IoT Central **Raw data** view to see if something isn't being modeled.

+When you've detected the issue, you may need to update device firmware, or create a new device template that models previously unmodeled data.

+If you chose to create a new template that models the data correctly, migrate devices from your old template to the new template. To learn more, see [Manage devices in your Azure IoT Central application](howto-manage-devices-individually.md).

+### Invalid JSON

+If there are no errors reported, but a value isn't appearing, then it's probably malformed JSON in the payload the device sends. To learn more, see [Telemetry, property, and command payloads](../../iot/concepts-message-payloads.md).

+You can't use the validate commands or the **Raw data** view in the UI to detect if the device is sending malformed JSON.

+### IoT Edge version

+To display telemetry from components hosted in IoT Edge modules correctly, use [IoT Edge version 1.2.4](https://github.com/Azure/azure-iotedge/releases/tag/1.2.4) or later. If you use an earlier version, telemetry from components in IoT Edge modules displays as *_unmodeleddata*.

+## Data export managed identity issues

+You're using a managed identity to authorize the connection to an export destination. Data isn't arriving at the export destination.

+Before you configure or enable the export destination, make sure that you complete the following steps:

+- Enable the managed identity for the IoT Central application. To verify that the managed identity is enabled, go to the **Identity** page for your application in the Azure portal or use the following CLI command:

+ ```azurecli

+ az iot central app identity show --name {your app name} --resource-group {your resource group name}

+ ```

+- Configure the permissions for the managed identity. To view the assigned permissions, select **Azure role assignments** on the **Identity** page for your app in the Azure portal or use the `az role assignment list` CLI command. The required permissions are:

+ | Destination | Permission |

+ |-||

+ | Azure Blob storage | Storage Blob Data Contributor |

+ | Azure Service Bus | Azure Service Bus Data Sender |

+ | Azure Event Hubs | Azure Event Hubs Data Sender |

+ | Azure Data Explorer | Admin |

+ If the permissions were not set correctly before you created the destination in your IoT Central application, try removing the destination and then adding it again.

+- Configure any virtual networks, private endpoints, and firewall policies.

+> [!NOTE]

+> If you're using a managed identity to authorize the connection to an export destination, IoT Central doesn't export data from simulated devices.

+To learn more, see [Export data](howto-export-data.md?tabs=managed-identity).

+## Data export destination connection issues

+The export definition page shows information about failed connections to the export destination:

+## Next steps

+If you need more help, you can contact the Azure experts on the [Microsoft Q&A and Stack Overflow forums](https://azure.microsoft.com/support/community/). Alternatively, you can file an [Azure support ticket](https://portal.azure.com/#create/Microsoft.Support).

+For more information, see [Azure IoT support and help options](../../iot/iot-support-help.md).

+* [IoT Plug and Play (PnP)](../iot/overview-iot-plug-and-play.md) devices *may* use the payload to send their model ID when they register with DPS. You can find examples of this usage in the PnP samples in the SDK or sample repositories. For example, [C# PnP thermostat](https://github.com/Azure/azure-iot-sdk-csharp/blob/main/iothub/device/samples/solutions/PnpDeviceSamples/Thermostat/Program.cs) or [Node.js PnP temperature controller](https://github.com/Azure/azure-iot-sdk-node/blob/main/device/samples/javascript/pnp_temperature_controller.js).

+* [IoT Central](../iot-central/core/overview-iot-central.md) devices that connect through DPS *should* follow [IoT Plug and Play conventions](..//iot/concepts-convention.md) and send their model ID when they register. IoT Central uses the model ID to assign the device to the correct device template. To learn more, see [Device implementation and best practices for IoT Central](../iot-central/core/concepts-device-implementation.md).

+* The *interface layer* builds on top of [Azure IoT Plug and Play](../iot/overview-iot-plug-and-play.md), allowing for messaging to flow between the Device Update agent and Device Update service.

+Device Update for IoT Hub uses [IoT Plug and Play](../iot/overview-iot-plug-and-play.md) to discover and manage devices that are over-the-air update capable. The Device Update service sends and receives properties and messages to and from devices using IoT Plug and Play interfaces.

+* Understand the [IoT Plug and Play device client](../iot/concepts-developer-guide-device.md).

+Model ID is how smart devices advertise their capabilities to Azure IoT applications with IoT Plug and Play.To learn more on how to build smart devices to advertise their capabilities to Azure IoT applications visit [IoT Plug and Play device developer guide](../iot/concepts-developer-guide-device.md).

+Device Update for IoT Hub requires the IoT Plug and Play smart device to announce a model ID as part of the device connection. [Learn how to announce a model ID](../iot/concepts-developer-guide-device.md#model-id-announcement).

+>The device or module must add the `{"__t": "c"}` marker to indicate that the element refers to a component. For more information, see [IoT Plug and Play conventions](../iot/concepts-convention.md#sample-multiple-components-writable-property).

+The device information interface is a concept used within [IoT Plug and Play architecture](../iot/overview-iot-plug-and-play.md). It contains device-to-cloud properties that provide information about the hardware and operating system of the device. Device Update for IoT Hub uses the `DeviceInformation.manufacturer` and `DeviceInformation.model` properties for telemetry and diagnostics. To learn more, see this [example of the device information interface](https://devicemodels.azure.com/dtmi/azure/devicemanagement/deviceinformation-1.json).

+The expected component name in your model is **deviceInformation** when this interface is implemented. [Learn about Azure IoT Plug and Play Components](../iot/concepts-modeling-guide.md)

+You can enable properties in IoT Hub using [Device twins](iot-hub-devguide-device-twins.md) or [Plug and Play](../iot/overview-iot-plug-and-play.md).

+To learn more about the differences between device twins and Plug and Play, see [Plug and Play](../iot/concepts-digital-twin.md#device-twins-and-digital-twins).

+To learn how [Azure IoT Plug and Play](../iot/overview-iot-plug-and-play.md) uses these options to control IoT Plug and Play devices, see [IoT Plug and Play service developer guide](../iot/concepts-developer-guide-service.md).

+To learn how device twins relate to the device model used by an Azure IoT Plug and Play device, see [Understand IoT Plug and Play digital twins](../iot/concepts-digital-twin.md).

+> IoT Plug and Play defines a schema that uses several additional properties to synchronize changes to desired and reported properties. If your solution uses IoT Plug and Play, you must follow the Plug and Play conventions when updating twin properties. For more information and an example, see [Writable properties in IoT Plug and Play](../iot/concepts-convention.md#writable-properties).

+For example, if a route is created with the data source set to **Device Twin Change Events**, IoT Hub sends messages to the endpoint that contain the change in the device twin. Similarly, if a route is created with the data source set to **Device Lifecycle Events**, IoT Hub sends a message indicating whether the device or module was deleted or created. For more information about device lifecycle events, see [Device and module lifecycle notifications](./iot-hub-devguide-identity-registry.md#device-and-module-lifecycle-notifications). When using [Azure IoT Plug and Play](../iot/overview-iot-plug-and-play.md), a developer can create routes with the data source set to **Digital Twin Change Events** and IoT Hub sends messages whenever a digital twin property is set or changed, a digital twin is replaced, or when a change event happens for the underlying device twin. Finally, if a route is created with data source set to **Device Connection State Events**, IoT Hub sends a message indicating whether the device was connected or disconnected.

+> IoT Plug and Play defines a schema that uses several additional properties to synchronize changes to desired and reported properties. If your solution uses IoT Plug and Play, you must follow the Plug and Play conventions when updating twin properties. For more information and an example, see [Writable properties in IoT Plug and Play](../iot/concepts-convention.md#writable-properties).

+* [**IoT Hub device SDKs**](#azure-iot-hub-device-sdks) enable you to build apps that run on your IoT devices using the device client or module client. These apps send telemetry to your IoT hub, and optionally receive messages, jobs, methods, or twin updates from your IoT hub. You can use these SDKs to build device apps that use [Azure IoT Plug and Play](../iot/overview-iot-plug-and-play.md) conventions and models to advertise their capabilities to IoT Plug and Play-enabled applications. You can also use the module client to author [modules](../iot-edge/iot-edge-modules.md) for [Azure IoT Edge runtime](../iot-edge/about-iot-edge.md).

+During public preview, IoT Hub device streams are available in the Central US, East US EUAP, North Europe, and Southeast Asia regions. Please make sure you create your hub in one of these regions.

+| [IoT Plug and Play](../iot/overview-iot-plug-and-play.md) | | Yes |

+ Title: IoT Plug and Play architecture | Microsoft Docs

+description: Understand the key architectural elements of an IoT Plug and Play solution.

+# IoT Plug and Play architecture

+IoT Plug and Play enables solution builders to integrate IoT devices with their solutions without any manual configuration. At the core of IoT Plug and Play, is a device _model_ that describes a device's capabilities to an IoT Plug and Play-enabled application. This model is structured as a set of interfaces that define:

+- _Properties_ that represent the read-only or writable state of a device or other entity. For example, a device serial number may be a read-only property and a target temperature on a thermostat may be a writable property.

+- _Telemetry_ that's the data emitted by a device, whether the data is a regular stream of sensor readings, an occasional error, or an information message.

+- _Commands_ that describe a function or operation that can be done on a device. For example, a command could reboot a gateway or take a picture using a remote camera.

+Every model and interface has a unique ID.

+The following diagram shows the key elements of an IoT Plug and Play solution:

+## Model repository

+The [model repository](./concepts-model-repository.md) is a store for model and interface definitions. You define models and interfaces using the [Digital Twins Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md).

+The web UI lets you manage the models and interfaces.

+The model repository has built-in role-based access controls that let you manage access to interface definitions.

+## Devices

+A device builder implements the code to run on an IoT device using one of the [Azure IoT device SDKs](../iot-develop/about-iot-sdks.md). The device SDKs help the device builder to:

+- Connect securely to an IoT hub.

+- Register the device with your IoT hub and announce the model ID that identifies the collection of DTDL interfaces the device implements.

+- Synchronize the properties defined in the DTDL interfaces between the device and your IoT hub.

+- Add command handlers for the commands defined in the DTDL interfaces.

+- Send telemetry to the IoT hub.

+## IoT Edge gateway

+An IoT Edge gateway acts as an intermediary to connect IoT Plug and Play devices that can't connect directly to an IoT hub. To learn more, see [How an IoT Edge device can be used as a gateway](../iot-edge/iot-edge-as-gateway.md).

+## IoT Edge modules

+An _IoT Edge module_ lets you deploy and manage business logic on the edge. Azure IoT Edge modules are the smallest unit of computation managed by IoT Edge, and can contain Azure services (such as Azure Stream Analytics) or your own solution-specific code.

+The _IoT Edge hub_ is one of the modules that make up the Azure IoT Edge runtime. It acts as a local proxy for IoT Hub by exposing the same protocol endpoints as IoT Hub. This consistency means that clients (whether devices or modules) can connect to the IoT Edge runtime just as they would to IoT Hub.

+The device SDKs help a module builder to:

+- Use the IoT Edge hub to connect securely to your IoT hub.

+- Register the module with your IoT hub and announce the model ID that identifies the collection of DTDL interfaces the device implements.

+- Synchronize the properties defined in the DTDL interfaces between the device and your IoT hub.

+- Add command handlers for the commands defined in the DTDL interfaces.

+- Send telemetry to the IoT hub.

+## IoT Hub

+[IoT Hub](../iot-hub/about-iot-hub.md) is a cloud-hosted service that acts as a central message hub for bi-directional communication between your IoT solution and the devices it manages.

+An IoT hub:

+- Makes the model ID implemented by a device available to a backend solution.

+- Maintains the digital twin associated with each IoT Plug and Play device connected to the hub.

+- Forwards telemetry streams to other services for processing or storage.

+- Routes digital twin change events to other services to enable device monitoring.

+## Backend solution

+A backend solution monitors and controls connected devices by interacting with digital twins in the IoT hub. Use one of the Azure IoT service SDKs to implement your backend solution. To understand the capabilities of a connected device, the solution backend:

+1. Retrieves the model ID the device registered with the IoT hub.

+1. Uses the model ID to retrieve the interface definitions from any model repository.

+1. Uses the model parser to extract information from the interface definitions.

+The backend solution can use the information from the interface definitions to:

+- Read property values reported by devices.

+- Update writable properties on a device.

+- Call commands implemented by a device.

+- Understand the format of telemetry sent by a device.

+## Next steps

+Now that you have an overview of the architecture of an IoT Plug and Play solution, the next steps are to learn more about:

+- [The model repository](./concepts-model-repository.md)

+- [Digital twin model integration](./concepts-model-discovery.md)

+- [Developing for IoT Plug and Play](./concepts-developer-guide-device.md)

+ Title: IoT Plug and Play conventions | Microsoft Docs

+description: Description of the conventions IoT Plug and Play expects devices to use when they send telemetry and properties, and handle commands and property updates.

+# IoT Plug and Play conventions

+IoT Plug and Play devices should follow a set of conventions when they exchange messages with an IoT hub. IoT Plug and Play devices use the MQTT protocol to communicate with IoT Hub. IoT Hub also supports the AMQP protocol which available in some IoT device SDKs.

+A device can include [modules](../iot-hub/iot-hub-devguide-module-twins.md), or be implemented in an [IoT Edge module](../iot-edge/about-iot-edge.md) hosted by the IoT Edge runtime.

+You describe the telemetry, properties, and commands that an IoT Plug and Play device implements with a [Digital Twins Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md) _model_. There are two types of model referred to in this article:

+- **No component** - A model with no components. The model declares telemetry, properties, and commands as top-level elements in the contents section of the main interface. In the Azure IoT explorer tool, this model appears as a single _default component_.

+- **Multiple components** - A model composed of two or more interfaces. A main interface, which appears as the _default component_, with telemetry, properties, and commands. One or more interfaces declared as components with more telemetry, properties, and commands.

+For more information, see [IoT Plug and Play modeling guide](concepts-modeling-guide.md).

+## Identify the model

+To announce the model it implements, an IoT Plug and Play device or module includes the model ID in the MQTT connection packet by adding `model-id` to the `USERNAME` field.

+To identify the model that a device or module implements, a service can get the model ID from:

+- The device twin `modelId` field.

+- The digital twin `$metadata.$model` field.

+- A digital twin change notification.

+## Telemetry

+- Telemetry sent from a no component device doesn't require any extra metadata. The system adds the `dt-dataschema` property.

+- Telemetry sent from a device using components must add the component name to the telemetry message.

+- When using MQTT, add the `$.sub` property with the component name to the telemetry topic, the system adds the `dt-subject` property.

+- When using AMQP, add the `dt-subject` property with the component name as a message annotation.

+> [!NOTE]

+> Telemetry from components requires one message per component.

+For more telemetry examples, see [Payloads > Telemetry](concepts-message-payloads.md#telemetry)

+## Read-only properties

+A device sets a read-only property which it then reports to the back-end application.

+### Sample no component read-only property

+A device or module can send any valid JSON that follows the DTDL rules.

+DTDL that defines a property on an interface:

+```json

+{

+ "@context": "dtmi:dtdl:context;2",

+ "@id": "dtmi:example: Thermostat;1",

+ "@type": "Interface",

+ "contents": [

+ {

+ "@type": "Property",

+ "name": "temperature",

+ "schema": "double"

+ }

+ ]

+}

+```

+Sample reported property payload:

+```json

+"reported" :

+{

+ "temperature" : 21.3

+}

+```

+### Sample multiple components read-only property

+The device or module must add the `{"__t": "c"}` marker to indicate that the element refers to a component.

+DTDL that references a component:

+```json

+{

+ "@context": "dtmi:dtdl:context;2",

+ "@id": "dtmi:com:example:TemperatureController;1",

+ "@type": "Interface",

+ "displayName": "Temperature Controller",

+ "contents": [

+ {

+ "@type" : "Component",

+ "schema": "dtmi:com:example:Thermostat;1",

+ "name": "thermostat1"

+ }

+ ]

+}

+```

+DTDL that defines the component:

+```json

+{

+ "@context": "dtmi:dtdl:context;2",

+ "@id": "dtmi:com:example:Thermostat;1",

+ "@type": "Interface",

+ "contents": [

+ {

+ "@type": "Property",

+ "name": "temperature",

+ "schema": "double"

+ }

+ ]

+}

+```

+Sample reported property payload:

+```json

+"reported": {

+ "thermostat1": {

+ "__t": "c",

+ "temperature": 21.3

+ }

+}

+```

+For more read-only property examples, see [Payloads > Properties](concepts-message-payloads.md#properties).

+## Writable properties

+A back-end application sets a writable property that IoT Hub then sends to the device.

+The device or module should confirm that it received the property by sending a reported property. The reported property should include:

+- `value` - the actual value of the property (typically the received value, but the device may decide to report a different value).

+- `ac` - an acknowledgment code that uses an HTTP status code.

+- `av` - an acknowledgment version that refers to the `$version` of the desired property. You can find this value in the desired property JSON payload.

+- `ad` - an optional acknowledgment description.

+### Acknowledgment responses

+When reporting writable properties the device should compose the acknowledgment message, by using the four fields in the previous list, to indicate the actual device state, as described in the following table:

+|Status(ac)|Version(av)|Value(value)|Description(av)|

+|:|:|:|:|

+|200|Desired version|Desired value|Desired property value accepted|

+|202|Desired version|Value accepted by the device|Desired property value accepted, update in progress (should finish with 200)|

+|203|0|Value set by the device|Property set from the device, not reflecting any desired|

+|400|Desired version|Actual value used by the device|Desired property value not accepted|

+|500|Desired version|Actual value used by the device|Exception when applying the property|

+When a device starts up, it should request the device twin, and check for any writable property updates. If the version of a writable property increased while the device was offline, the device should send a reported property response to confirm that it received the update.

+When a device starts up for the first time, it can send an initial value for a reported property if it doesn't receive an initial desired property from the IoT hub. In this case, the device can send the default value with `av` to `0` and `ac` to `203`. For example:

+```json

+"reported": {

+ "targetTemperature": {

+ "value": 20.0,

+ "ac": 203,

+ "av": 0,

+ "ad": "initialize"

+ }

+}

+```

+A device can use the reported property to provide other information to the hub. For example, the device could respond with a series of in-progress messages such as:

+```json

+"reported": {

+ "targetTemperature": {

+ "value": 35.0,

+ "ac": 202,

+ "av": 3,

+ "ad": "In-progress - reporting current temperature"

+ }

+}

+```

+When the device reaches the target temperature, it sends the following message:

+```json

+"reported": {

+ "targetTemperature": {

+ "value": 20.0,

+ "ac": 200,

+ "av": 4,

+ "ad": "Reached target temperature"

+ }

+}

+```

+A device could report an error such as:

+```json

+"reported": {

+ "targetTemperature": {

+ "value": 120.0,

+ "ac": 500,

+ "av": 3,

+ "ad": "Target temperature out of range. Valid range is 10 to 99."

+ }

+}

+```

+### Object type

+If a writable property is defined as an object, the service must send a complete object to the device. The device should acknowledge the update by sending sufficient information back to the service for the service to understand how the device has acted on the update. This response could include:

+- The entire object.

+- Just the fields that the device updated.

+- A subset of the fields.

+For large objects, consider minimizing the size of the object you include in the acknowledgment.

+The following example shows a writable property defined as an `Object` with four fields:

+DTDL:

+```json

+{

+ "@type": "Property",

+ "name": "samplingRange",

+ "schema": {

+ "@type": "Object",

+ "fields": [

+ {

+ "name": "startTime",

+ "schema": "dateTime"

+ },

+ {

+ "name": "lastTime",

+ "schema": "dateTime"

+ },

+ {

+ "name": "count",

+ "schema": "integer"

+ },

+ {

+ "name": "errorCount",

+ "schema": "integer"

+ }

+ ]

+ },

+ "displayName": "Sampling range"

+ "writable": true

+}

+```

+To update this writable property, send a complete object from the service that looks like the following example:

+```json

+{

+ "samplingRange": {

+ "startTime": "2021-08-17T12:53:00.000Z",

+ "lastTime": "2021-08-17T14:54:00.000Z",

+ "count": 100,

+ "errorCount": 5

+ }

+}

+```

+The device responds with an acknowledgment that looks like the following example:

+```json

+{

+ "samplingRange": {

+ "ac": 200,

+ "av": 5,

+ "ad": "Weighing status updated",

+ "value": {

+ "startTime": "2021-08-17T12:53:00.000Z",

+ "lastTime": "2021-08-17T14:54:00.000Z",

+ "count": 100,

+ "errorCount": 5

+ }

+ }

+}

+```

+### Sample no component writable property

+When a device receives multiple desired properties in a single payload, it can send the reported property responses across multiple payloads or combine the responses into a single payload.

+A device or module can send any valid JSON that follows the DTDL rules.

+DTDL:

+```json

+{

+ "@context": "dtmi:dtdl:context;2",

+ "@id": "dtmi:example: Thermostat;1",

+ "@type": "Interface",

+ "contents": [

+ {

+ "@type": "Property",

+ "name": "targetTemperature",

+ "schema": "double",

+ "writable": true

+ },

+ {

+ "@type": "Property",

+ "name": "targetHumidity",

+ "schema": "double",

+ "writable": true

+ }

+ ]

+}

+```

+Sample desired property payload:

+```json

+"desired" :

+{

+ "targetTemperature" : 21.3,

+ "targetHumidity" : 80,

+ "$version" : 3

+}

+```

+Sample reported property first payload:

+```json

+"reported": {

+ "targetTemperature": {

+ "value": 21.3,

+ "ac": 200,

+ "av": 3,

+ "ad": "complete"

+ }

+}

+```

+Sample reported property second payload:

+```json

+"reported": {

+ "targetHumidity": {

+ "value": 80,

+ "ac": 200,

+ "av": 3,

+ "ad": "complete"

+ }

+}

+```

+> [!NOTE]

+> You could choose to combine these two reported property payloads into a single payload.

+### Sample multiple components writable property

+The device or module must add the `{"__t": "c"}` marker to indicate that the element refers to a component.

+The marker is sent only for updates to properties defined in a component. Updates to properties defined in the default component don't include the marker, see [Sample no component writable property](#sample-no-component-writable-property).

+When a device receives multiple reported properties in a single payload, it can send the reported property responses across multiple payloads or combine the responses into a single payload.

+The device or module should confirm that it received the properties by sending reported properties:

+DTDL that references a component:

+```json

+{

+ "@context": "dtmi:dtdl:context;2",

+ "@id": "dtmi:com:example:TemperatureController;1",

+ "@type": "Interface",

+ "displayName": "Temperature Controller",

+ "contents": [

+ {

+ "@type" : "Component",

+ "schema": "dtmi:com:example:Thermostat;1",

+ "name": "thermostat1"

+ }

+ ]

+}

+```

+DTDL that defines the component:

+```json

+{

+ "@context": "dtmi:dtdl:context;2",

+ "@id": "dtmi:com:example:Thermostat;1",

+ "@type": "Interface",

+ "contents": [

+ {

+ "@type": "Property",

+ "name": "targetTemperature",

+ "schema": "double",

+ "writable": true

+ }

+ ]

+}

+```

+Sample desired property payload:

+```json

+"desired": {

+ "thermostat1": {

+ "__t": "c",

+ "targetTemperature": 21.3,

+ "targetHumidity": 80,

+ "$version" : 3

+ }

+}

+```

+Sample reported property first payload:

+```json

+"reported": {

+ "thermostat1": {

+ "__t": "c",

+ "targetTemperature": {

+ "value": 23,

+ "ac": 200,

+ "av": 3,

+ "ad": "complete"

+ }

+ }

+}

+```

+Sample reported property second payload:

+```json

+"reported": {

+ "thermostat1": {

+ "__t": "c",

+ "targetHumidity": {

+ "value": 80,

+ "ac": 200,

+ "av": 3,

+ "ad": "complete"

+ }

+ }

+}

+```

+> [!NOTE]

+> You could choose to combine these two reported property payloads into a single payload.

+For more writable property examples, see [Payloads > Properties](concepts-message-payloads.md#writable-property-types).

+## Commands

+No component interfaces use the command name without a prefix.

+On a device or module, multiple component interfaces use command names with the following format: `componentName*commandName`.

+For more command examples, see [Payloads > Commands](concepts-message-payloads.md#commands).

+> [!TIP]

+> IoT Central has its own conventions for implementing [Long-running commands](../iot-central/core/howto-use-commands.md#long-running-commands) and [Offline commands](../iot-central/core/howto-use-commands.md#offline-commands).

+## Next steps

+Now that you've learned about IoT Plug and Play conventions, here are some other resources:

+- [Digital Twins Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md)

+- [C device SDK](https://github.com/Azure/azure-iot-sdk-c/)

+- [IoT REST API](/rest/api/iothub/device)

+- [IoT Plug and Play modeling guide](concepts-modeling-guide.md)

+ Title: Device developer guide - IoT Plug and Play | Microsoft Docs

+description: "Description of IoT Plug and Play for device developers. Includes examples in the following languages: C, C#, Java, JavaScript, Python, and Embedded C."

+zone_pivot_groups: programming-languages-set-twenty-seven

+#- id: programming-languages-set-twenty-seven

+# Title: Embedded C

+# IoT Plug and Play device developer guide

+IoT Plug and Play lets you build IoT devices that advertise their capabilities to Azure IoT applications. IoT Plug and Play devices don't require manual configuration when a customer connects them to IoT Plug and Play-enabled applications such as IoT Central.

+You can implement an IoT device directly by using [modules](../iot-hub/iot-hub-devguide-module-twins.md), or by using [IoT Edge modules](../iot-edge/about-iot-edge.md).

+This guide describes the basic steps required to create a device, module, or IoT Edge module that follows the [IoT Plug and Play conventions](../iot/concepts-convention.md).

+To build an IoT Plug and Play device, module, or IoT Edge module, follow these steps:

+1. Ensure your device is using either the MQTT or MQTT over WebSockets protocol to connect to Azure IoT Hub.

+1. Create a [Digital Twins Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md) model to describe your device. To learn more, see [Understand components in IoT Plug and Play models](concepts-modeling-guide.md).

+1. Update your device or module to announce the `model-id` as part of the device connection.

+1. Implement telemetry, properties, and commands that follow the [IoT Plug and Play conventions](concepts-convention.md)

+Once your device or module implementation is ready, use the [Azure IoT explorer](../iot/howto-use-iot-explorer.md) to validate that the device follows the IoT Plug and Play conventions.

+## Next steps

+Now that you've learned about IoT Plug and Play device development, here are some other resources:

+- [Digital Twins Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md)

+- [C device SDK](https://github.com/Azure/azure-iot-sdk-c/)

+- [IoT REST API](/rest/api/iothub/device)

+- [Understand components in IoT Plug and Play models](concepts-modeling-guide.md)

+- [IoT Plug and Play service developer guide](concepts-developer-guide-service.md)

+ Title: Service developer guide - IoT Plug and Play | Microsoft Docs

+description: Description of IoT Plug and Play for service developers

+zone_pivot_groups: programming-languages-set-ten

+# - id: programming-languages-set-ten

+# Title: Python

+# IoT Plug and Play service developer guide

+IoT Plug and Play lets you build IoT devices that advertise their capabilities to Azure IoT applications. IoT Plug and Play devices don't require manual configuration when a customer connects them to IoT Plug and Play-enabled applications.

+IoT Plug and Play lets you use devices that have announced their model ID with your IoT hub. For example, you can access the properties and commands of a device directly.

+If you're using IoT Central, you can use the IoT Central UI and REST API to interact with IoT Plug and Play devices connected to your application.

+## Service SDKs

+Use the Azure IoT service SDKs in your solution to interact with devices and modules. For example, you can use the service SDKs to read and update twin properties and invoke commands. Supported languages include C#, Java, Node.js, and Python.

+The service SDKs let you access device information from a solution component such as a desktop or web application. The service SDKs include two namespaces and object models that you can use to retrieve the model ID:

+- Iot Hub service client. This service exposes the model ID as a device twin property.

+- Digital Twins client. The new Digital Twins API operates on [Digital Twins Definition Language (DTDL)](concepts-digital-twin.md) model constructs such as components, properties, and commands. The Digital Twin APIs make it easier for solution builders to create IoT Plug and Play solutions.

+## Next steps

+Now that you've learned about device modeling, here are some more resources:

+- [Digital Twins Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md)

+- [C device SDK](https://github.com/Azure/azure-iot-sdk-c/)

+- [IoT REST API](/rest/api/iothub/device)

+- [IoT Plug and Play modeling guide](concepts-modeling-guide.md)

+ Title: Understand IoT Plug and Play digital twins

+description: Understand how IoT Plug and Play uses digital twins

+# Understand IoT Plug and Play digital twins

+An IoT Plug and Play device implements a model described by the [Digital Twins Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md) schema. A model describes the set of components, properties, commands, and telemetry messages that a particular device can have.

+> [!NOTE]

+> DTDL isn't exclusive to IoT Plug and Play. Other IoT services, such as [Azure Digital Twins](../digital-twins/overview.md), use it to represent entire environments such as buildings and energy networks.

+The Azure IoT service SDKs include APIs that let a service interact a device's digital twin. For example, a service can read device properties from the digital twin or use the digital twin to call a command on a device. To learn more, see [IoT Hub digital twin examples](concepts-developer-guide-service.md#iot-hub-digital-twin-examples).

+The example IoT Plug and Play device in this article implements a [Temperature Controller model](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/samples/TemperatureController.json) that has [Thermostat](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/samples/Thermostat.json) components.

+## Device twins and digital twins

+Along with a digital twin, Azure IoT Hub also maintains a *device twin* for every connected device. A device twin is similar to a digital twin in that it's a representation of a device's properties. An IoT hub initializes a digital twin and a device twin the first time an IoT Plug and Play device is provisioned. The Azure IoT service SDKs include APIs for interacting with device twins.

+Device twins are JSON documents that store device state information, including metadata, configurations, and conditions. To learn more, see [IoT Hub service client examples](concepts-developer-guide-service.md#iot-hub-service-client-examples). Device and solution builders can both use the same set of device twin APIs and SDKs to implement devices and solutions using IoT Plug and Play conventions. In a device twin, the state of a writable property is split across the *desired properties* and *reported properties* sections. All read-only properties are available within the reported properties section.

+The digital twin APIs operate on high-level DTDL constructs such as components, properties, and commands and makes it easier for solution builders to create IoT Plug and Play solutions. In a digital twin, there's a unified view of the current and desired state of the property. The synchronization state for a given property is stored in the corresponding default component `$metadata` section.

+### Device twin JSON example

+The following snippet shows an IoT Plug and Play device twin formatted as a JSON object:

+```json

+{

+ "deviceId": "sample-device",

+ "modelId": "dtmi:com:example:TemperatureController;1",

+ "version": 15,

+ "properties": {

+ "desired": {

+ "thermostat1": {

+ "__t": "c",

+ "targetTemperature": 21.8

+ },

+ "$metadata": {...},

+ "$version": 4

+ },

+ "reported": {

+ "serialNumber": "alwinexlepaho8329",

+ "thermostat1": {

+ "maxTempSinceLastReboot": 25.3,

+ "__t": "c",

+ "targetTemperature": {

+ "value": 21.8,

+ "ac": 200,

+ "ad": "Successfully executed patch",

+ }

+ },

+ "$metadata": {...},

+ "$version": 11

+ }

+ }

+}

+```

+### Digital twin example

+The following snippet shows the digital twin formatted as a JSON object:

+```json

+{

+ "$dtId": "sample-device",

+ "serialNumber": "alwinexlepaho8329",

+ "thermostat1": {

+ "maxTempSinceLastReboot": 25.3,

+ "targetTemperature": 21.8,

+ "$metadata": {

+ "targetTemperature": {

+ "desiredValue": 21.8,

+ "desiredVersion": 4,

+ "ackVersion": 4,

+ "ackCode": 200,

+ "ackDescription": "Successfully executed patch",

+ "lastUpdateTime": "2020-07-17T06:11:04.9309159Z"

+ },

+ "maxTempSinceLastReboot": {

+ "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"

+ }

+ }

+ },

+ "$metadata": {

+ "$model": "dtmi:com:example:TemperatureController;1",

+ "serialNumber": {

+ "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"

+ }

+ }

+}

+```

+The following table describes the fields in the digital twin JSON object:

+| Field name | Description |

+| | |

+| `$dtId` | A user-provided string representing the ID of the device digital twin. |

+| `{propertyName}` | The value of a property in JSON. |

+| `$metadata.$model` | [Optional] The ID of the model interface that characterizes this digital twin. |

+| `$metadata.{propertyName}.desiredValue` | [Only for writable properties] The desired value of the specified property. |

+| `$metadata.{propertyName}.desiredVersion` | [Only for writable properties] The version of the desired value maintained by IoT Hub.|

+| `$metadata.{propertyName}.ackVersion` | [Required, only for writable properties] The version acknowledged by the device implementing the digital twin, it must by greater or equal to desired version. |

+| `$metadata.{propertyName}.ackCode` | [Required, only for writable properties] The `ack` code returned by the device app implementing the digital twin. |

+| `$metadata.{propertyName}.ackDescription` | [Optional, only for writable properties] The `ack` description returned by the device app implementing the digital twin. |

+| `$metadata.{propertyName}.lastUpdateTime` | IoT Hub maintains the timestamp of the last update of the property by the device. The timestamps are in UTC and encoded in the ISO8601 format YYYY-MM-DDTHH:MM:SS.mmmZ. |

+| `{componentName}` | A JSON object containing the component's property values and metadata. |

+| `{componentName}.{propertyName}` | The value of the component's property in JSON. |

+| `{componentName}.$metadata` | The metadata information for the component. |

+### Properties

+Properties are data fields that represent the state of an entity just like the properties in many object-oriented programming languages.

+#### Read-only property

+DTDL schema:

+```json

+{

+ "@type": "Property",

+ "name": "serialNumber",

+ "displayName": "Serial Number",

+ "description": "Serial number of the device.",

+ "schema": "string"

+}

+```

+In this example, `alwinexlepaho8329` is the current value of the `serialNumber` read-only property reported by the device.

+The following snippets show the side-by-side JSON representation of the `serialNumber` property:

+ :::column span="":::

+ **Device twin**

+```json

+"properties": {

+ "reported": {

+ "serialNumber": "alwinexlepaho8329"

+ }

+}

+```

+ :::column-end:::

+ :::column span="":::

+ **Digital twin**

+```json

+"serialNumber": "alwinexlepaho8329"

+```

+ :::column-end:::

+#### Writable property

+The following examples show a writable property in the default component.

+DTDL:

+```json

+{

+ "@type": "Property",

+ "name": "fanSpeed",

+ "displayName": "Fan Speed",

+ "writable": true,

+ "schema": "double"

+}

+```

+ :::column span="":::

+ **Device twin**

+```json

+{

+ "properties": {

+ "desired": {

+ "fanSpeed": 2.0,

+ },

+ "reported": {

+ "fanSpeed": {

+ "value": 3.0,

+ "ac": 200,

+ "av": 1,

+ "ad": "Successfully executed patch version 1"

+ }

+ }

+ },

+}

+```

+ :::column-end:::

+ :::column span="":::

+ **Digital twin**

+```json

+{

+ "fanSpeed": 3.0,

+ "$metadata": {

+ "fanSpeed": {

+ "desiredValue": 2.0,

+ "desiredVersion": 2,

+ "ackVersion": 1,

+ "ackCode": 200,

+ "ackDescription": "Successfully executed patch version 1",

+ "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"

+ }

+ }

+}

+```

+ :::column-end:::

+In this example, `3.0` is the current value of the `fanSpeed` property reported by the device. `2.0` is the desired value set by the solution. The desired value and synchronization state of a root-level property is set within root-level `$metadata` for a digital twin. When the device comes online, it can apply this update and report back the updated value.

+### Components

+Components let you build a model interface as an assembly of other interfaces. For example, the [Thermostat](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/samples/Thermostat.json) interface can be incorporated as components `thermostat1` and `thermostat2` in the [Temperature Controller model](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/samples/TemperatureController.json) model.

+In a device twin, a component is identified by the `{ "__t": "c"}` marker. In a digital twin, the presence of `$metadata` marks a component.

+In this example, `thermostat1` is a component with two properties:

+- `maxTempSinceLastReboot` is a read-only property.

+- `targetTemperature` is a writable property that's been successfully synchronized by the device. The desired value and synchronization state of these properties are in the component's `$metadata`.

+The following snippets show the side-by-side JSON representation of the `thermostat1` component:

+ :::column span="":::

+ **Device twin**

+```json

+"properties": {

+ "desired": {

+ "thermostat1": {

+ "__t": "c",

+ "targetTemperature": 21.8

+ },

+ "$metadata": {

+ },

+ "$version": 4

+ },

+ "reported": {

+ "thermostat1": {

+ "maxTempSinceLastReboot": 25.3,

+ "__t": "c",

+ "targetTemperature": {

+ "value": 21.8,

+ "ac": 200,

+ "ad": "Successfully executed patch",

+ "av": 4

+ }

+ },

+ "$metadata": {

+ },

+ "$version": 11

+ }

+}

+```

+ :::column-end:::

+ :::column span="":::

+ **Digital twin**

+```json

+"thermostat1": {

+ "maxTempSinceLastReboot": 25.3,

+ "targetTemperature": 21.8,

+ "$metadata": {

+ "targetTemperature": {

+ "desiredValue": 21.8,

+ "desiredVersion": 4,

+ "ackVersion": 4,

+ "ackCode": 200,

+ "ackDescription": "Successfully executed patch",

+ "lastUpdateTime": "2020-07-17T06:11:04.9309159Z"

+ },

+ "maxTempSinceLastReboot": {

+ "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"

+ }

+ }

+}

+```

+ :::column-end:::

+## Digital twin APIs

+The digital twin APIs include **Get Digital Twin**, **Update Digital Twin**, **Invoke Component Command** and **Invoke Command** operations more managing a digital twin. You can either use the [REST APIs](/rest/api/iothub/service/digitaltwin) directly or through one of the [service SDKs](concepts-developer-guide-service.md#service-sdks).

+## Digital twin change events

+When digital twin change events are enabled, an event is triggered whenever the current or desired value of the component or property changes. Digital twin change events are generated in [JSON Patch](http://jsonpatch.com/) format. Corresponding events are generated in the device twin format if twin change events are enabled.

+To learn how to enable routing for device and digital twin events, see [Use IoT Hub message routing to send device-to-cloud messages to different endpoints](../iot-hub/iot-hub-devguide-messages-d2c.md#non-telemetry-events). To understand the message format, see [Create and read IoT Hub messages](../iot-hub/iot-hub-devguide-messages-construct.md).

+For example, the following digital twin change event is triggered when `targetTemperature` is set by the solution:

+```json

+iothub-connection-device-id:sample-device

+iothub-enqueuedtime:7/17/2020 6:11:04 AM

+iothub-message-source:digitalTwinChangeEvents

+correlation-id:275d463fa034

+content-type:application/json-patch+json

+content-encoding:utf-8

+[

+ {

+ "op": "add",

+ "path": "/thermostat1/$metadata/targetTemperature",

+ "value": {

+ "desiredValue": 21.8,

+ "desiredVersion": 4

+ }

+ }

+]

+```

+The following digital twin change event is triggered when the device reports that the above desired change was applied:

+```json

+iothub-connection-device-id:sample-device

+iothub-enqueuedtime:7/17/2020 6:11:05 AM

+iothub-message-source:digitalTwinChangeEvents

+correlation-id:275d464a2c80

+content-type:application/json-patch+json

+content-encoding:utf-8

+[

+ {

+ "op": "add",

+ "path": "/thermostat1/$metadata/targetTemperature/ackCode",

+ "value": 200

+ },

+ {

+ "op": "add",

+ "path": "/thermostat1/$metadata/targetTemperature/ackDescription",

+ "value": "Successfully executed patch"

+ },

+ {

+ "op": "add",

+ "path": "/thermostat1/$metadata/targetTemperature/ackVersion",

+ "value": 4

+ },

+ {

+ "op": "add",

+ "path": "/thermostat1/$metadata/targetTemperature/lastUpdateTime",

+ "value": "2020-07-17T06:11:04.9309159Z"

+ },

+ {

+ "op": "add",

+ "path": "/thermostat1/targetTemperature",

+ "value": 21.8

+ }

+]

+```

+> [!NOTE]

+> Twin change notification messages are doubled when turned on in both device and digital twin change notification.

+## Next steps

+Now that you've learned about digital twins, here are some more resources:

+- [How to use IoT Plug and Play digital twin APIs](howto-manage-digital-twin.md)

+- [Interact with a device from your solution](./tutorial-service.md)

+- [IoT Digital Twin REST API](/rest/api/iothub/service/digitaltwin)

+- [Azure IoT explorer](../iot/howto-use-iot-explorer.md)

+ Title: Plug and Play device message payloads

+description: Understand the format of the telemetry, property, and command messages that a Plug and Play device can exchange with a service.

+# This article applies to device developers.

+# Telemetry, property, and command payloads

+A [device model](concepts-modeling-guide.md) defines the:

+* Telemetry a device sends to a service.

+* Properties a device synchronizes with a service.

+* Commands that the service calls on a device.

+> [!TIP]

+> Azure IoT Central is a service that follows the Plug and Play conventions. In IoT Central, the device model is part of a [device template](../iot-central/core/concepts-device-templates.md). IoT Central currently supports [DTDL v2](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.v2.md) with an [IoT Central extension](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.iotcentral.v2.md). An IoT Central application expects to receive UTF-8 encoded JSON data.

+This article describes the JSON payloads that devices send and receive for telemetry, properties, and commands defined in a DTDL device model.

+The article doesn't describe every possible type of telemetry, property, and command payload, but the examples illustrate key types.

+Each example shows a snippet from the device model that defines the type and example JSON payloads to illustrate how the device should interact with a Plug and Play aware service such as IoT Central.

+The example JSON snippets in this article use [Digital Twin Definition Language (DTDL) V2](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.v2.md). There are also some [DTDL extensions that IoT Central](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.iotcentral.v2.md) uses.

+For sample device code that shows some of these payloads in use, see the [Connect a sample IoT Plug and Play device application running on Linux or Windows to IoT Hub tutorial](./tutorial-connect-device.md) or the [Create and connect a client application to your Azure IoT Central application](../iot-central/core/tutorial-connect-device.md) tutorial.

+## View raw data

+If you're using IoT Central, you can view the raw data that a device sends to an application. This view is useful for troubleshooting issues with the payload sent from a device. To view the raw data a device is sending:

+1. Navigate to the device from the **Devices** page.

+1. Select the **Raw data** tab:

+ :::image type="content" source="media/concepts-message-payloads/raw-data.png" alt-text="Screenshot that shows the raw data view." lightbox="media/concepts-message-payloads/raw-data.png":::

+ On this view, you can select the columns to display and set a time range to view. The **Unmodeled data** column shows data from the device that doesn't match any property or telemetry definitions in the device template.

+For more troubleshooting tips, see [Troubleshoot why data from your devices isn't showing up in Azure IoT Central](../iot-central/core/troubleshoot-connection.md).

+## Telemetry

+To learn more about the DTDL telemetry naming rules, see [DTDL > Telemetry](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.v2.md#telemetry). You can't start a telemetry name using the `_` character.

+Don't create telemetry types with the following names. IoT Central uses these reserved names internally. If you try to use these names, IoT Central will ignore your data:

+* `EventEnqueuedUtcTime`

+* `EventProcessedUtcTime`

+* `PartitionId`

+* `EventHub`

+* `User`

+* `$metadata`

+* `$version`

+### Telemetry in components

+If the telemetry is defined in a component, add a custom message property called `$.sub` with the name of the component as defined in the device model. To learn more, see [Tutorial: Connect an IoT Plug and Play multiple component device applications](tutorial-multiple-components.md). This tutorial shows how to use different programming languages to send telemetry from a component.

+> [!IMPORTANT]

+> To display telemetry from components hosted in IoT Edge modules correctly, use [IoT Edge version 1.2.4](https://github.com/Azure/azure-iotedge/releases/tag/1.2.4) or later. If you use an earlier version, telemetry from your components in IoT Edge modules displays as *_unmodeleddata*.

+### Telemetry in inherited interfaces

+If the telemetry is defined in an inherited interface, your device sends the telemetry as if it is defined in the root interface. Given the following device model:

+```json

+[

+ {

+ "@id": "dtmi:contoso:device;1",

+ "@type": "Interface",

+ "contents": [

+ {

+ "@type": [

+ "Property",

+ "Cloud",

+ "StringValue"

+ ],

+ "displayName": {

+ "en": "Device Name"

+ },

+ "name": "DeviceName",

+ "schema": "string"

+ }

+ ],

+ "displayName": {

+ "en": "Contoso Device"

+ },

+ "extends": [

+ "dtmi:contoso:sensor;1"

+ ],

+ "@context": [

+ "dtmi:iotcentral:context;2",

+ "dtmi:dtdl:context;2"

+ ]

+ },

+ {

+ "@context": [

+ "dtmi:iotcentral:context;2",

+ "dtmi:dtdl:context;2"

+ ],

+ "@id": "dtmi:contoso:sensor;1",

+ "@type": [

+ "Interface",

+ "NamedInterface"

+ ],

+ "contents": [

+ {

+ "@type": [

+ "Telemetry",

+ "NumberValue"

+ ],

+ "displayName": {

+ "en": "Meter Voltage"

+ },

+ "name": "MeterVoltage",

+ "schema": "double"

+ }

+ ],

+ "displayName": {

+ "en": "Contoso Sensor"

+ },

+ "name": "ContosoSensor"

+ }

+]

+```

+The device sends meter voltage telemetry using the following payload. The device doesn't include the interface name in the payload:

+```json

+{

+ "MeterVoltage": 5.07

+}

+```

+### Primitive types

+This section shows examples of primitive telemetry types that a device can stream.

+The following snippet from a device model shows the definition of a `boolean` telemetry type:

+```json

+{

+ "@type": "Telemetry",

+ "displayName": {

+ "en": "BooleanTelemetry"

+ },

+ "name": "BooleanTelemetry",

+ "schema": "boolean"

+}

+```

+A device client should send the telemetry as JSON that looks like the following example:

+```json

+{ "BooleanTelemetry": true }

+```

+The following snippet from a device model shows the definition of a `string` telemetry type:

+```json

+{

+ "@type": "Telemetry",

+ "displayName": {

+ "en": "StringTelemetry"

+ },

+ "name": "StringTelemetry",

+ "schema": "string"

+}

+```

+A device client should send the telemetry as JSON that looks like the following example:

+```json

+{ "StringTelemetry": "A string value - could be a URL" }

+```

+The following snippet from a device model shows the definition of an `integer` telemetry type:

+```json

+{

+ "@type": "Telemetry",

+ "displayName": {

+ "en": "IntegerTelemetry"

+ },

+ "name": "IntegerTelemetry",

+ "schema": "integer"

+}

+```

+A device client should send the telemetry as JSON that looks like the following example:

+```json

+{ "IntegerTelemetry": 23 }

+```

+The following snippet from a device model shows the definition of a `double` telemetry type:

+```json

+{

+ "@type": "Telemetry",

+ "displayName": {

+ "en": "DoubleTelemetry"

+ },

+ "name": "DoubleTelemetry",

+ "schema": "double"

+}

+```

+A device client should send the telemetry as JSON that looks like the following example:

+```json

+{ "DoubleTelemetry": 56.78 }

+```

+The following snippet from a device model shows the definition of a `dateTime` telemetry type:

+```json

+{

+ "@type": "Telemetry",

+ "displayName": {

+ "en": "DateTimeTelemetry"

+ },

+ "name": "DateTimeTelemetry",

+ "schema": "dateTime"

+}

+```

+A device client should send the telemetry as JSON that looks like the following example - `DateTime` types must be in ISO 8061 format:

+```json

+{ "DateTimeTelemetry": "2020-08-30T19:16:13.853Z" }

+```

+The following snippet from a device model shows the definition of a `duration` telemetry type:

+```json

+{

+ "@type": "Telemetry",

+ "displayName": {

+ "en": "DurationTelemetry"

+ },

+ "name": "DurationTelemetry",

+ "schema": "duration"

+}

+```

+A device client should send the telemetry as JSON that looks like the following example - durations must be in ISO 8601 format:

+```json

+{ "DurationTelemetry": "PT10H24M6.169083011336625S" }

+```

+### Complex types

+This section shows examples of complex telemetry types that a device can stream.

+The following snippet from a device model shows the definition of an `Enum` telemetry type:

+```json

+{

+ "@type": "Telemetry",

+ "displayName": {

+ "en": "EnumTelemetry"

+ },

+ "name": "EnumTelemetry",

+ "schema": {

+ "@type": "Enum",

+ "displayName": {

+ "en": "Enum"

+ },

+ "valueSchema": "integer",

+ "enumValues": [

+ {

+ "displayName": {

+ "en": "Item1"

+ },

+ "enumValue": 0,

+ "name": "Item1"

+ },

+ {

+ "displayName": {

+ "en": "Item2"

+ },

+ "enumValue": 1,

+ "name": "Item2"

+ },

+ {

+ "displayName": {

+ "en": "Item3"

+ },

+ "enumValue": 2,

+ "name": "Item3"

+ }

+ ]

+ }

+}

+```

+A device client should send the telemetry as JSON that looks like the following example. Possible values are `0`, `1`, and `2` that display in IoT Central as `Item1`, `Item2`, and `Item3`:

+```json

+{ "EnumTelemetry": 1 }

+```

+The following snippet from a device model shows the definition of an `Object` telemetry type. This object has three fields with types `dateTime`, `integer`, and `Enum`:

+```json

+{

+ "@type": "Telemetry",

+ "displayName": {

+ "en": "ObjectTelemetry"

+ },

+ "name": "ObjectTelemetry",

+ "schema": {

+ "@type": "Object",

+ "displayName": {

+ "en": "Object"

+ },

+ "fields": [

+ {

+ "displayName": {

+ "en": "Property1"

+ },

+ "name": "Property1",

+ "schema": "dateTime"

+ },

+ {

+ "displayName": {

+ "en": "Property2"

+ },

+ "name": "Property2",

+ "schema": "integer"

+ },

+ {

+ "displayName": {

+ "en": "Property3"

+ },

+ "name": "Property3",

+ "schema": {

+ "@type": "Enum",

+ "displayName": {

+ "en": "Enum"

+ },

+ "valueSchema": "integer",

+ "enumValues": [

+ {

+ "displayName": {

+ "en": "Item1"

+ },

+ "enumValue": 0,

+ "name": "Item1"

+ },

+ {

+ "displayName": {

+ "en": "Item2"

+ },

+ "enumValue": 1,

+ "name": "Item2"

+ },

+ {

+ "displayName": {

+ "en": "Item3"

+ },

+ "enumValue": 2,

+ "name": "Item3"

+ }

+ ]

+ }

+ }

+ ]

+ }

+}

+```

+A device client should send the telemetry as JSON that looks like the following example. `DateTime` types must be ISO 8061 compliant. Possible values for `Property3` are `0`, `1`, and that display in IoT Central as `Item1`, `Item2`, and `Item3`:

+```json

+{

+ "ObjectTelemetry": {

+ "Property1": "2020-09-09T03:36:46.195Z",

+ "Property2": 37,

+ "Property3": 2

+ }

+}

+```

+The following snippet from a device model shows the definition of a `vector` telemetry type:

+```json

+{

+ "@type": "Telemetry",

+ "displayName": {

+ "en": "VectorTelemetry"

+ },

+ "name": "VectorTelemetry",

+ "schema": "vector"

+}

+```

+A device client should send the telemetry as JSON that looks like the following example:

+```json

+{

+ "VectorTelemetry": {

+ "x": 74.72395045538597,

+ "y": 74.72395045538597,

+ "z": 74.72395045538597

+ }

+}

+```

+The following snippet from a device model shows the definition of a `geopoint` telemetry type:

+```json

+{

+ "@type": "Telemetry",

+ "displayName": {

+ "en": "GeopointTelemetry"

+ },

+ "name": "GeopointTelemetry",

+ "schema": "geopoint"

+}

+```

+> [!NOTE]

+> The **geopoint** schema type is part of the [IoT Central extension](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.iotcentral.v2.md) to DTDL. IoT Central currently supports the **geopoint** schema type and the **location** semantic type for backwards compatibility.

+A device client should send the telemetry as JSON that looks like the following example. IoT Central displays the value as a pin on a map:

+```json

+{

+ "GeopointTelemetry": {

+ "lat": 47.64263,

+ "lon": -122.13035,

+ "alt": 0

+ }

+}

+```

+### Event and state types

+This section shows examples of telemetry events and states that a device sends to an IoT Central application.

+> [!NOTE]

+> The **event** and **state** schema types are part of the [IoT Central extension](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.iotcentral.v2.md) to DTDL.

+The following snippet from a device model shows the definition of a `integer` event type:

+```json

+{

+ "@type": [

+ "Telemetry",

+ "Event"

+ ],

+ "displayName": {

+ "en": "IntegerEvent"

+ },

+ "name": "IntegerEvent",

+ "schema": "integer"

+}

+```

+A device client should send the event data as JSON that looks like the following example:

+```json

+{ "IntegerEvent": 74 }

+```

+The following snippet from a device model shows the definition of a `integer` state type:

+```json

+{

+ "@type": [

+ "Telemetry",

+ "State"

+ ],

+ "displayName": {

+ "en": "IntegerState"

+ },

+ "name": "IntegerState",

+ "schema": {

+ "@type": "Enum",

+ "valueSchema": "integer",

+ "enumValues": [

+ {

+ "displayName": {

+ "en": "Level1"

+ },

+ "enumValue": 1,

+ "name": "Level1"

+ },

+ {

+ "displayName": {

+ "en": "Level2"

+ },

+ "enumValue": 2,

+ "name": "Level2"

+ },

+ {

+ "displayName": {

+ "en": "Level3"

+ },

+ "enumValue": 3,

+ "name": "Level3"

+ }

+ ]

+ }

+}

+```

+A device client should send the state as JSON that looks like the following example. Possible integer state values are `1`, `2`, or `3`:

+```json

+{ "IntegerState": 2 }

+```

+## Properties

+To learn more about the DTDL property naming rules, see [DTDL > Property](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.v2.md#property). You can't start a property name using the `_` character.

+### Properties in components

+If the property is defined in a component, wrap the property in the component name. The following example sets the `maxTempSinceLastReboot` in the `thermostat2` component. The marker `__t` indicates that this section defines a component:

+```json

+{

+ "thermostat2" : {

+ "__t" : "c",

+ "maxTempSinceLastReboot" : 38.7

+ }

+}

+```

+To learn more, see [Tutorial: Create and connect a client application to your Azure IoT Central application](./tutorial-connect-device.md).

+### Primitive types

+This section shows examples of primitive property types that a device sends to a service.

+The following snippet from a device model shows the definition of a `boolean` property type:

+```json

+{

+ "@type": "Property",

+ "displayName": {

+ "en": "BooleanProperty"

+ },

+ "name": "BooleanProperty",

+ "schema": "boolean",

+ "writable": false

+}

+```

+A device client should send a JSON payload that looks like the following example as a reported property in the device twin:

+```json

+{ "BooleanProperty": false }

+```

+The following snippet from a device model shows the definition of a `long` property type:

+```json

+{

+ "@type": "Property",

+ "displayName": {

+ "en": "LongProperty"

+ },

+ "name": "LongProperty",

+ "schema": "long",

+ "writable": false

+}

+```

+A device client should send a JSON payload that looks like the following example as a reported property in the device twin:

+```json

+{ "LongProperty": 439 }

+```

+The following snippet from a device model shows the definition of a `date` property type:

+```json

+{

+ "@type": "Property",

+ "displayName": {

+ "en": "DateProperty"

+ },

+ "name": "DateProperty",

+ "schema": "date",

+ "writable": false

+}

+```

+A device client should send a JSON payload that looks like the following example as a reported property in the device twin. `Date` types must be ISO 8061 compliant:

+```json

+{ "DateProperty": "2020-05-17" }

+```

+The following snippet from a device model shows the definition of a `duration` property type:

+```json

+{

+ "@type": "Property",

+ "displayName": {

+ "en": "DurationProperty"

+ },

+ "name": "DurationProperty",

+ "schema": "duration",

+ "writable": false

+}

+```

+A device client should send a JSON payload that looks like the following example as a reported property in the device twin - durations must be ISO 8601 Duration compliant:

+```json

+{ "DurationProperty": "PT10H24M6.169083011336625S" }

+```

+The following snippet from a device model shows the definition of a `float` property type:

+```json

+{

+ "@type": "Property",

+ "displayName": {

+ "en": "FloatProperty"

+ },

+ "name": "FloatProperty",

+ "schema": "float",

+ "writable": false

+}

+```

+A device client should send a JSON payload that looks like the following example as a reported property in the device twin:

+```json

+{ "FloatProperty": 1.9 }

+```

+The following snippet from a device model shows the definition of a `string` property type:

+```json

+{

+ "@type": "Property",

+ "displayName": {

+ "en": "StringProperty"

+ },

+ "name": "StringProperty",

+ "schema": "string",

+ "writable": false

+}

+```

+A device client should send a JSON payload that looks like the following example as a reported property in the device twin:

+```json

+{ "StringProperty": "A string value - could be a URL" }

+```

+### Complex types

+This section shows examples of complex property types that a device sends to a service.

+The following snippet from a device model shows the definition of an `Enum` property type:

+```json

+{

+ "@type": "Property",

+ "displayName": {

+ "en": "EnumProperty"

+ },

+ "name": "EnumProperty",

+ "writable": false,

+ "schema": {

+ "@type": "Enum",

+ "displayName": {

+ "en": "Enum"

+ },

+ "valueSchema": "integer",

+ "enumValues": [

+ {

+ "displayName": {

+ "en": "Item1"

+ },

+ "enumValue": 0,

+ "name": "Item1"

+ },

+ {

+ "displayName": {

+ "en": "Item2"

+ },

+ "enumValue": 1,

+ "name": "Item2"

+ },

+ {

+ "displayName": {

+ "en": "Item3"

+ },

+ "enumValue": 2,

+ "name": "Item3"

+ }

+ ]

+ }

+}

+```

+A device client should send a JSON payload that looks like the following example as a reported property in the device twin. Possible values are `0`, `1`, and that display in IoT Central as `Item1`, `Item2`, and `Item3`:

+```json

+{ "EnumProperty": 1 }

+```

+The following snippet from a device model shows the definition of an `Object` property type. This object has two fields with types `string` and `integer`:

+```json

+{

+ "@type": "Property",

+ "displayName": {

+ "en": "ObjectProperty"

+ },

+ "name": "ObjectProperty",

+ "writable": false,

+ "schema": {

+ "@type": "Object",

+ "displayName": {

+ "en": "Object"