+ `PUT https://graph.microsoft.com/beta/servicePrincipals/[object-id]/synchronization/jobs/[new-job-id]/schema`

+- **Matching based on a combination of attributes isn't supported:** Most applications don't support querying based on two properties. Therefore, it's not possible to match based on a combination of attributes. It's possible to evaluate single properties on after another.

+> Provisioning of group objects (properties and members) is a distinct concept from [assigning groups](../manage-apps/assign-user-or-group-access-portal.md) to an application. It's possible to assign a group to an application, but only provision the user objects contained in the group. Provisioning of full group objects isn't required to use groups in assignments.

+- For Azure Active Directory writeback to Workday or SuccessFactors, it's supported to update relevant metadata for supported attributes (XPATH and JSONPath), but isn't supported to add new Workday or SuccessFactors attributes beyond those included in the default schema

+> When a directory extension attribute in Azure AD doesn't show up automatically in your attribute mapping drop-down, you can manually add it to the "Azure AD attribute list". When manually adding Azure AD directory extension attributes to your provisioning app, note that directory extension attribute names are case-sensitive. For example: If you have a directory extension attribute named `extension_53c9e2c0exxxxxxxxxxxxxxxx_acmeCostCenter`, make sure you enter it in the same format as defined in the directory.

+When you're editing the list of supported attributes, the following properties are provided:

+These instructions are only applicable to SCIM-enabled applications. Applications such as ServiceNow and Salesforce aren't integrated with Azure AD using SCIM, and therefore they don't require this specific namespace when adding a custom attribute.

+Custom attributes can't be referential attributes, multi-value or complex-typed attributes. Custom multi-value and complex-typed extension attributes are currently supported only for applications in the gallery. The custom extension schema header is omitted in the example because it isn't sent in requests from the Azure AD SCIM client. This issue will be fixed in the future and the header will be sent in the request.

+- Mapping an appRoleAssignment in Azure AD to a role in your application requires that you transform the attribute using an [expression](../app-provisioning/functions-for-customizing-application-data.md). The appRoleAssignment attribute **shouldn't be mapped directly** to a role attribute without using an expression to parse the role details.

+ - Ensure that multiple roles aren't assigned to a user. We can't guarantee which role will be provisioned.

+ - The POST contains the role type. The PATCH request doesn't contain type. We're working on sending the type in both POST and PATCH requests.

+- Adding a photo attribute to be provisioned to an app isn't supported today as you can't specify the format to sync the photo. You can request the feature on [User Voice](https://feedback.azure.com/d365community/forum/22920db1-ad25-ec11-b6e6-000d3a4f0789)

+- The attribute IsSoftDeleted is often part of the default mappings for an application. IsSoftdeleted can be true in one of four scenarios (the user is out of scope due to being unassigned from the application, the user is out of scope due to not meeting a scoping filter, the user has been soft deleted in Azure AD, or the property AccountEnabled is set to false on the user). It's not recommended to remove the IsSoftDeleted attribute from your attribute mappings.

+- The Azure AD provisioning service doesn't support provisioning null values.

+- They primary key, typically "ID", shouldn't be included as a target attribute in your attribute mappings.

+Some SSO settings have specific dependencies that can take time to set up, so avoid change control delays by ensuring dependencies are addressed ahead of time. This includes domain joining connector hosts to perform SSO using Kerberos Constrained Delegation (KCD) and taking care of other time-consuming activities.

+## Migration between policies

+- In recent updates we removed the ability to target individual users. Previously targeted users will remain in the policy but we recommend moving them to a targeted group.

+If this option is set to **Yes**, users resetting their password receive an email notifying them that their password has been changed. The email is sent via the SSPR portal to their primary and alternate email addresses that are stored in Azure AD. If no primary or alternate email address is defined SSPR will attempt email notification via the users User Principal Name (UPN). No one else is notified of the reset event.

+1. [Microsoft Authenticator push notifications](concept-authentication-authenticator-app.md)

+Users register themselves for the passwordless authentication method of Azure AD. For users who already registered the Microsoft Authenticator app for [multi-factor authentication](./concept-mfa-howitworks.md), skip to the next section, [enable phone sign-in](#enable-phone-sign-in).

+### Direct phone Sign-in registration

+Users can register for passwordless phone sign-in directly within the Microsoft Authenticator app without the need to first registering Microsoft Authenticator with their account, all while never accruing a password. Here's how:

+1. Acquire a [Temporary Access Pass](../authentication/howto-authentication-temporary-access-pass.md) from your Admin or Organization.

+2. Download and install the Microsoft Authenticator app on your mobile device.

+3. Open Microsoft Authenticator and click **Add account** and then choose **Work or school account.**

+4. Choose **Sign in**.

+5. Follow the instructions to sign-in with your account using the Temporary Access Pass provided by your Admin or Organization.

+6. Once signed-in, continue following the additional steps to set up phone sign-in.

+### Guided registration with My Sign-ins

+To register the Microsoft Authenticator app, follow these steps:

+- The following settings are known to interfere with the ability to use and reset passwords on Windows devices:

+When an error is returned, the `"error"` key contains a machine-readable code. If the `"error"` is, for example, an `"interaction_required"`, you may prompt the user to provide additional information to complete the authentication process. If the `"error"` is `"invalid_grant"`, you may prompt the user to reenter their credentials. The following snippet is an example of error handling in MSAL for Python.

+```python

+from msal import ConfidentialClientApplication

+authority_url = "https://login.microsoftonline.com/your_tenant_id"

+client_id = "your_client_id"

+client_secret = "your_client_secret"

+scopes = ["https://graph.microsoft.com/.default"]

+app = ConfidentialClientApplication(client_id, authority=authority_url, client_credential=client_secret)

+result = app.acquire_token_silent(scopes=scopes, account=None)

+if not result:

+ result = app.acquire_token_silent(scopes=scopes)

+if "access_token" in result:

+ print("Access token: %s" % result["access_token"])

+else:

+ print("Error: %s" % result.get("error"))

+```

+When an error is returned, the `"error_description"` key also contains a human-readable message, and there is typically also an `"error_code"` key which contains a machine-readable Microsoft identity platform error code. For more information about the various Microsoft identity platform error codes, see [Authentication and authorization error codes](./reference-aadsts-error-codes.md).

+In MSAL for Python, exceptions are rare because most errors are handled by returning an error value. The `ValueError` exception is only thrown when there's an issue with how you're attempting to use the library, such as when API parameter(s) are malformed.

+| Office 365 E5 | ENTERPRISEPREMIUM | c7df2760-2c81-4ef7-b578-5b5392b571df | DYN365_CDS_O365_P3 (28b0fa46-c39a-4188-89e2-58e979a6b014)<br/>CDS_O365_P3 (afa73018-811e-46e9-988f-f75d2b1b8430)<br/>LOCKBOX_ENTERPRISE (9f431833-0334-42de-a7dc-70aa40db46db)<br/>MIP_S_Exchange (cd31b152-6326-4d1b-ae1b-997b625182e6)<br/>EXCHANGE_S_ENTERPRISE (efb87545-963c-4e0d-99df-69c6916d9eb0)<br/>GRAPH_CONNECTORS_SEARCH_INDEX (a6520331-d7d4-4276-95f5-15c0933bc757)<br/>INFORMATION_BARRIERS (c4801e8a-cb58-4c35-aca6-f2dcc106f287)<br/>Content_Explorer (d9fa6af4-e046-4c89-9226-729a0786685d)<br/>ContentExplorer_Standard (2b815d45-56e4-4e3a-b65c-66cb9175b560)<br/>MIP_S_CLP2 (efb0351d-3b08-4503-993d-383af8de41e3)<br/>MIP_S_CLP1 (5136a095-5cf0-4aff-bec3-e84448b38ea5)<br/>MYANALYTICS_P2 (33c4f319-9bdd-48d6-9c4d-410b750a4a5a)<br/>MICROSOFT_COMMUNICATION_COMPLIANCE (a413a9ff-720c-4822-98ef-2f37c2a21f4c)<br/>M365_ADVANCED_AUDITING (2f442157-a11c-46b9-ae5b-6e39ff4e5849)<br/>OFFICESUBSCRIPTION (43de0ff5-c92c-492b-9116-175376d08c38)<br/>MCOMEETADV (3e26ee1f-8a5f-4d52-aee2-b81ce45c8f40)<br/>MTP (bf28f719-7844-4079-9c78-c1307898e192)<br/>MCOEV (4828c8ec-dc2e-4779-b502-87ac9ce28ab7)<br/>RMS_S_ENTERPRISE (bea4c11e-220a-4e6d-8eb8-8ea15d019f90)<br/>MICROSOFTBOOKINGS (199a5c09-e0ca-4e37-8f7c-b05d533e1ea2)<br/>COMMUNICATIONS_DLP (6dc145d6-95dd-4191-b9c3-185575ee6f6b)<br/>CUSTOMER_KEY (6db1f1db-2b46-403f-be40-e39395f08dbb)<br/>DATA_INVESTIGATIONS (46129a58-a698-46f0-aa5b-17f6586297d9)<br/>ATP_ENTERPRISE (f20fedf3-f3c3-43c3-8267-2bfdd51c0939)<br/>THREAT_INTELLIGENCE (8e0c0a52-6a6c-4d40-8370-dd62790dcd70)<br/>EXCEL_PREMIUM (531ee2f8-b1cb-453b-9c21-d2180d014ca5)<br/>FORMS_PLAN_E5 (e212cbc7-0961-4c40-9825-01117710dcb1)<br/>INFO_GOVERNANCE (e26c2fcc-ab91-4a61-b35c-03cdc8dddf66)<br/>KAIZALA_STANDALONE (0898bdbb-73b0-471a-81e5-20f1fe4dd66e)<br/>EXCHANGE_ANALYTICS (34c0d7a0-a70f-4668-9238-47f9fc208882)<br/>PROJECTWORKMANAGEMENT (b737dad2-2f6c-4c65-90e3-ca563267e8b9)<br/>RECORDS_MANAGEMENT (65cc641f-cccd-4643-97e0-a17e3045e541)<br/>MICROSOFT_SEARCH (94065c59-bc8e-4e8b-89e5-5138d471eaff)<br/>Deskless (8c7d2df8-86f0-4902-b2ed-a0458298f3b3)<br/>STREAM_O365_E5 (6c6042f5-6f01-4d67-b8c1-eb99d36eed3e)<br/>TEAMS1 (57ff2da0-773e-42df-b2af-ffb7a2317929)<br/>INTUNE_O365 (882e1d05-acd1-4ccb-8708-6ee03664b117)<br/>EQUIVIO_ANALYTICS (4de31727-a228-4ec3-a5bf-8e45b5ca48cc)<br/>ADALLOM_S_O365 (8c098270-9dd4-4350-9b30-ba4703f3b36b)<br/>PAM_ENTERPRISE (b1188c4c-1b36-4018-b48b-ee07604f6feb)<br/>SHAREPOINTWAC (e95bec33-7c88-4a70-8e19-b10bd9d0c014)<br/>FLOW_O365_P3 (07699545-9485-468e-95b6-2fca3738be01)<br/>BI_AZURE_P2 (70d33638-9c74-4d01-bfd3-562de28bd4ba)<br/>POWER_VIRTUAL_AGENTS_O365_P3 (ded3d325-1bdc-453e-8432-5bac26d7a014)<br/>POWERAPPS_O365_P3 (9c0dab89-a30c-4117-86e7-97bda240acd2)<br/>PREMIUM_ENCRYPTION (617b097b-4b93-4ede-83de-5f075bb5fb2f)<br/>PROJECT_O365_P3 (b21a6b06-1988-436e-a07b-51ec6d9f52ad)<br/>COMMUNICATIONS_COMPLIANCE (41fcdd7d-4733-4863-9cf4-c65b83ce2df4)<br/>SHAREPOINTENTERPRISE (5dbe027f-2339-4123-9542-606e4d348a72)<br/>MCOSTANDARD (0feaeb32-d00e-4d66-bd5a-43b5b83db82c)<br/>SWAY (a23b959c-7ce8-4e57-9140-b90eb88a9e97)<br/>BPOS_S_TODO_3 (3fb82609-8c27-4f7b-bd51-30634711ee67)<br/>VIVAENGAGE_CORE (a82fbf69-b4d7-49f4-83a6-915b2cf354f4)<br/>VIVA_LEARNING_SEEDED (b76fb638-6ba6-402a-b9f9-83d28acb3d86)<br/>WHITEBOARD_PLAN3 (4a51bca5-1eff-43f5-878c-177680f191af)<br/>YAMMER_ENTERPRISE (7547a3fe-08ee-4ccb-b430-5077c5041653) | Common Data Service - O365 P3 (28b0fa46-c39a-4188-89e2-58e979a6b014)<br/>Common Data Service for Teams_P3 (afa73018-811e-46e9-988f-f75d2b1b8430)<br/>Customer Lockbox (9f431833-0334-42de-a7dc-70aa40db46db)<br/>Data Classification in Microsoft 365 (cd31b152-6326-4d1b-ae1b-997b625182e6)<br/>Exchange Online (Plan 2) (efb87545-963c-4e0d-99df-69c6916d9eb0)<br/>Graph Connectors Search with Index (a6520331-d7d4-4276-95f5-15c0933bc757)<br/>Information Barriers (c4801e8a-cb58-4c35-aca6-f2dcc106f287)<br/>Information Protection and Governance Analytics ΓÇô Premium (d9fa6af4-e046-4c89-9226-729a0786685d)<br/>Information Protection and Governance Analytics ΓÇô Standard (2b815d45-56e4-4e3a-b65c-66cb9175b560)<br/>Information Protection for Office 365 ΓÇô Premium (efb0351d-3b08-4503-993d-383af8de41e3)<br/>Information Protection for Office 365 ΓÇô Standard (5136a095-5cf0-4aff-bec3-e84448b38ea5)<br/>Insights by MyAnalytics (33c4f319-9bdd-48d6-9c4d-410b750a4a5a)<br/>M365 Communication Compliance (a413a9ff-720c-4822-98ef-2f37c2a21f4c)<br/>Microsoft 365 Advanced Auditing (2f442157-a11c-46b9-ae5b-6e39ff4e5849)<br/>Microsoft 365 Apps for enterprise (43de0ff5-c92c-492b-9116-175376d08c38)<br/>Microsoft 365 Audio Conferencing (3e26ee1f-8a5f-4d52-aee2-b81ce45c8f40)<br/>Microsoft 365 Defender (bf28f719-7844-4079-9c78-c1307898e192)<br/>Microsoft 365 Phone System (4828c8ec-dc2e-4779-b502-87ac9ce28ab7)<br/>Microsoft Azure Active Directory Rights (bea4c11e-220a-4e6d-8eb8-8ea15d019f90)<br/>Microsoft Bookings (199a5c09-e0ca-4e37-8f7c-b05d533e1ea2)<br/>Microsoft Communications DLP (6dc145d6-95dd-4191-b9c3-185575ee6f6b)<br/>Microsoft Customer Key (6db1f1db-2b46-403f-be40-e39395f08dbb)<br/>Microsoft Data Investigations (46129a58-a698-46f0-aa5b-17f6586297d9)<br/>Microsoft Defender for Office 365 (Plan 1) (f20fedf3-f3c3-43c3-8267-2bfdd51c0939)<br/>Microsoft Defender for Office 365 (Plan 2) (8e0c0a52-6a6c-4d40-8370-dd62790dcd70)<br/>Microsoft Excel Advanced Analytics (531ee2f8-b1cb-453b-9c21-d2180d014ca5)<br/>Microsoft Forms (Plan E5) (e212cbc7-0961-4c40-9825-01117710dcb1)<br/>Microsoft Information Governance (e26c2fcc-ab91-4a61-b35c-03cdc8dddf66)<br/>Microsoft Kaizala (0898bdbb-73b0-471a-81e5-20f1fe4dd66e)<br/>Microsoft MyAnalytics (Full) (34c0d7a0-a70f-4668-9238-47f9fc208882)<br/>Microsoft Planner (b737dad2-2f6c-4c65-90e3-ca563267e8b9)<br/>Microsoft Records Management (65cc641f-cccd-4643-97e0-a17e3045e541)<br/>Microsoft Search (94065c59-bc8e-4e8b-89e5-5138d471eaff)<br/>Microsoft StaffHub (8c7d2df8-86f0-4902-b2ed-a0458298f3b3)<br/>Microsoft Stream for O365 E5 SKU (6c6042f5-6f01-4d67-b8c1-eb99d36eed3e)<br/>Microsoft Teams (57ff2da0-773e-42df-b2af-ffb7a2317929)<br/>Mobile Device Management for Office 365 (882e1d05-acd1-4ccb-8708-6ee03664b117)<br/>Office 365 Advanced eDiscovery (4de31727-a228-4ec3-a5bf-8e45b5ca48cc)<br/>Office 365 Advanced Security Management (8c098270-9dd4-4350-9b30-ba4703f3b36b)<br/>Office 365 Privileged Access Management (b1188c4c-1b36-4018-b48b-ee07604f6feb)<br/>Office for the web (e95bec33-7c88-4a70-8e19-b10bd9d0c014)<br/>Power Automate for Office 365 (07699545-9485-468e-95b6-2fca3738be01)<br/>Power BI Pro (70d33638-9c74-4d01-bfd3-562de28bd4ba)<br/>Power Virtual Agents for Office 365 P3 (ded3d325-1bdc-453e-8432-5bac26d7a014)<br/>PowerApps for Office 365 Plan 3 (9c0dab89-a30c-4117-86e7-97bda240acd2)<br/>Premium Encryption in Office 365 (617b097b-4b93-4ede-83de-5f075bb5fb2f)<br/>Project for Office (Plan E5) (b21a6b06-1988-436e-a07b-51ec6d9f52ad)<br/>Microsoft Communications Compliance (41fcdd7d-4733-4863-9cf4-c65b83ce2df4)<br/>SharePoint (Plan 2) (5dbe027f-2339-4123-9542-606e4d348a72)<br/>Skype for Business Online (Plan 2) (0feaeb32-d00e-4d66-bd5a-43b5b83db82c)<br/>Sway (a23b959c-7ce8-4e57-9140-b90eb88a9e97)<br/>To-Do (Plan 3) (3fb82609-8c27-4f7b-bd51-30634711ee67)<br/>VIVAENGAGE_CORE (a82fbf69-b4d7-49f4-83a6-915b2cf354f4)<br/>Viva Learning Seeded (b76fb638-6ba6-402a-b9f9-83d28acb3d86)<br/>Whiteboard (Plan 3) (4a51bca5-1eff-43f5-878c-177680f191af)<br/>Yammer Enterprise (7547a3fe-08ee-4ccb-b430-5077c5041653) |

+ - Source tenant ID: {sourceTenantId}

+ - Target tenant ID: {targetTenantId}

+ "tenantId": "{sourceTenantId}"

+ "tenantId": "{sourceTenantId}",

+ PUT https://graph.microsoft.com/beta/policies/crossTenantAccessPolicy/partners/{sourceTenantId}/identitySynchronization

+ PATCH https://graph.microsoft.com/beta/policies/crossTenantAccessPolicy/partners/{sourceTenantId}

+ "tenantId": "{targetTenantId}"

+ "tenantId": "{targetTenantId}",

+ PATCH https://graph.microsoft.com/beta/policies/crossTenantAccessPolicy/partners/{targetTenantId}

+ "appOwnerTenantId": "{targetTenantId}",

+ "value": "{targetTenantId}"

+ "value": "{targetTenantId}"

+ "tenantId": "{targetTenantId}",

+1. In the **Admin Credentials** section, enter your ServiceNow admin credentials and username. Select **Test Connection** to ensure that Azure AD can connect to ServiceNow. If the connection fails, ensure that your ServiceNow account has admin permissions and try again.

+ test.server: |

+ Title: Use Draft and the DevX extension for Visual Studio Code with Azure Kubernetes Service (AKS) (preview)

+description: Learn how to use Draft and the DevX extension for Visual Studio Code with Azure Kubernetes Service (AKS)

+# Use Draft and the DevX extension for Visual Studio Code with Azure Kubernetes Service (AKS) (preview)

+[Draft][draft] is an open-source project that streamlines Kubernetes development by taking a non-containerized application and generating the DockerFiles, Kubernetes manifests, Helm charts, Kustomize configurations, and other artifacts associated with a containerized application. The Azure Kubernetes Service (AKS) DevX extension for Visual Studio Code enhances non-cluster experiences, allowing you to create deployment files to deploy your applications to AKS. Draft is the available feature included in the DevX extension.

+This article shows you how to use Draft with the DevX extension to draft a DockerFile, draft a Kubernetes deployment and service, and build an image on Azure Container Registry (ACR).

+## Before you begin

+* You need an Azure resource group and an AKS cluster with an attached ACR. To attach an ACR to your AKS cluster, use `az aks update -n <cluster-name> -g <resource-group-name> --attach-acr <acr-name>` or follow the instructions in [Authenticate with ACR from AKS][aks-acr-authenticate].

+* Download and install the [Azure Kubernetes Service DevX Extension for Visual Studio Code][devx-extension].

+## Draft with the DevX extension for Visual Studio Code

+To get started with Draft in Visual Studio Code, press **Ctrl + Shift + P** in your Visual Studio Code window and enter **AKS Developer**. From here, you'll see available Draft commands:

+* Get started

+* Draft a DockerFile

+* Draft a Kubernetes Deployment and Service

+* Build an Image on Azure Container Registry

+### Get started

+The `Get started` command shows you all the steps you need to get up and running on AKS.

+1. Press **Ctrl + Shift + P** to open the command palette.

+2. Enter **AKS Developer**.

+3. Select **AKS Developer: Get started**.

+You'll see the following getting started page:

+### Draft a DockerFile

+`Draft a DockerFile` adds the minimum required DockerFile to your project directory.

+1. Press **Ctrl + Shift + P** to open the command palette.

+2. Enter **AKS Developer**.

+3. Select **AKS Developer: Draft a DockerFile**.

+### Draft a Kubernetes Deployment and Service

+`Draft a Kubernetes Deployment and Service` adds the appropriate deployment and service files to your application, which allows you to deploy to your AKS cluster. The supported deployment types include: Helm, Kustomize, and Kubernetes manifests.

+1. Press **Ctrl + Shift + P** to open the command palette.

+2. Enter **AKS Developer**.

+3. Select **AKS Developer: Draft a Kubernetes Deployment and Service**.

+### Build an Image on Azure Container Registry

+`Build an Image on Azure Container Registry` builds an image on your ACR to use in your deployment files.

+1. Press **Ctrl + Shift + P** to open the command palette.

+2. Enter **AKS Developer**.

+3. Select **AKS Developer: Build an Image on Azure Container Registry**.

+## Next steps

+In this article, you learned how to use Draft and the DevX extension for Visual Studio Code with AKS. To use Draft with the Azure CLI, see [Draft for AKS][draft-aks-cli].

+<!-- LINKS -->

+[draft-aks-cli]: ../aks/draft.md

+[aks-acr-authenticate]: ../aks/cluster-container-registry-integration.md

+[devx-extension]: https://marketplace.visualstudio.com/items?itemName=ms-kubernetes-tools.aks-devx-tools

+[draft]: https://github.com/Azure/draft

+Configure the cluster agent nodes to use host-based encryption when the cluster is created.

+> [!NOTE]

+> After you enable host-based encryption on your cluster, make sure you provide the proper access to your Azure Key Vault to enable encryption at rest. For more information, see [Control access][control-keys] and [Azure built-in roles for Key Vault data plane operations][akv-built-in-roles].

+## Next steps

+- Review [best practices for AKS cluster security][best-practices-security].

+- Read more about [host-based encryption](../virtual-machines/disk-encryption.md#encryption-at-hostend-to-end-encryption-for-your-vm-data).

+[control-keys]: ../key-vault/general/best-practices.md#control-access-to-your-vault

+[akv-built-in-roles]: ../key-vault/general/rbac-guide.md#azure-built-in-roles-for-key-vault-data-plane-operations

+ Title: Configure Metrics Server VPA in Azure Kubernetes Service (AKS)

+description: Learn how to vertically autoscale your Metrics Server pods on an Azure Kubernetes Service (AKS) cluster.

+# Configure Metrics Server VPA in Azure Kubernetes Service (AKS)

+[Metrics Server][metrics-server-overview] is a scalable, efficient source of container resource metrics for Kubernetes built-in autoscaling pipelines. With Azure Kubernetes Service (AKS), vertical pod autoscaling is enabled for the Metrics Server. The Metrics Server is commonly used by other Kubernetes add ons, such as the [Horizontal Pod Autoscaler][horizontal-pod-autoscaler].

+Vertical Pod Autoscaler (VPA) enables you to adjust the resource limit when the Metrics Server is experiencing consistent CPU and memory resource constraints.

+## Before you begin

+AKS cluster is running Kubernetes version 1.24 and higher.

+## Metrics server throttling

+If the Metrics Server throttling rate is high, and the memory usage of its two pods is unbalanced, this indicates the Metrics Server requires more resources than the default values specified.

+To update the coefficient values, create a ConfigMap in the overlay *kube-system* namespace to override the values in the Metrics Server specification. Perform the following steps to update the metrics server.

+1. Create a ConfigMap file named *metrics-server-config.yaml* and copy in the following manifest.

+ ```yml

+ apiVersion: v1

+ kind: ConfigMap

+ metadata:

+ name: metrics-server-config

+ namespace: kube-system

+ labels:

+ kubernetes.io/cluster-service: "true"

+ addonmanager.kubernetes.io/mode: EnsureExists

+ data:

+ NannyConfiguration: |-

+ apiVersion: nannyconfig/v1alpha1

+ kind: NannyConfiguration

+ baseCPU: 100m

+ cpuPerNode: 1m

+ baseMemory: 100Mi

+ memoryPerNode: 8Mi

+ ```

+ In the ConfigMap example, the resource limit and request are changed to the following:

+ * cpu: (100+1n) millicore

+ * memory: (100+8n) mebibyte

+ Where *n* is the number of nodes.

+2. Create the ConfigMap using the [kubectl apply][kubectl-apply] command and specify the name of your YAML manifest:

+ ```bash

+ kubectl apply -f metrics-server-config.yaml

+ ```

+3. Restart the Metrics Server pods. There are two Metrics server pods, and the following command deletes all of them.

+ ```bash

+ kubectl -n kube-system delete po metrics-server-pod-name

+ ```

+4. To verify the updated resources took effect, run the following command to review the Metrics Server VPA log.

+ ```bash

+ kubectl -n kube-system logs metrics-server-pod-name -c metrics-server-vpa

+ ```

+ The following example output resembles the results showing the updated throttling settings were applied.

+ ```output

+ ERROR: logging before flag.Parse: I0315 23:12:33.956112 1 pod_nanny.go:68] Invoked by [/pod_nanny --config-dir=/etc/config --cpu=44m --extra-cpu=0.5m --memory=51Mi --extra-memory=4Mi --poll-period=180000 --threshold=5 --deployment=metrics-server --container=metrics-server]

+ ERROR: logging before flag.Parse: I0315 23:12:33.956159 1 pod_nanny.go:69] Version: 1.8.14

+ ERROR: logging before flag.Parse: I0315 23:12:33.956171 1 pod_nanny.go:85] Watching namespace: kube-system, pod: metrics-server-545d8b77b7-5nqq9, container: metrics-server.

+ ERROR: logging before flag.Parse: I0315 23:12:33.956175 1 pod_nanny.go:86] storage: MISSING, extra_storage: 0Gi

+ ERROR: logging before flag.Parse: I0315 23:12:33.957441 1 pod_nanny.go:116] cpu: 100m, extra_cpu: 1m, memory: 100Mi, extra_memory: 8Mi

+ ERROR: logging before flag.Parse: I0315 23:12:33.957456 1 pod_nanny.go:145] Resources: [{Base:{i:{value:100 scale:-3} d:{Dec:<nil>} s:100m Format:DecimalSI} ExtraPerNode:{i:{value:0 scale:-3} d:{Dec:<nil>} s: Format:DecimalSI} Name:cpu} {Base:{i:{value:104857600 scale:0} d:{Dec:<nil>} s:100Mi Format:BinarySI} ExtraPerNode:{i:{value:0 scale:0} d:{Dec:<nil>} s: Format:BinarySI} Name:memory

+ ```

+Be cautious of the *baseCPU*, *cpuPerNode*, *baseMemory*, and the *memoryPerNode*, because the ConfigMap isn't validated by AKS. As a recommended practice, increase the value gradually to avoid unnecessary resource consumption. Proactively monitor resource usage when updating or creating the ConfigMap. A large number of resource requests could negatively impact the node.

+## Manually configure Metrics Server resource usage

+The Metrics Server VPA adjusts resource usage by the number of nodes. If the cluster scales up or down often, the Metrics Server might restart frequently. In this case, you can bypass VPA and manually control its resource usage. This method to configure VPA isn't to be performed in addition to the steps described in the previous section.

+If you would like to bypass VPA for Metrics Server and manually control its resource usage, perform the following steps.

+1. Create a ConfigMap file named *metrics-server-config.yaml* and copy in the following manifest.

+ ```yml

+ apiVersion: v1

+ kind: ConfigMap

+ metadata:

+ name: metrics-server-config

+ namespace: kube-system

+ labels:

+ kubernetes.io/cluster-service: "true"

+ addonmanager.kubernetes.io/mode: EnsureExists

+ data:

+ NannyConfiguration: |-

+ apiVersion: nannyconfig/v1alpha1

+ kind: NannyConfiguration

+ baseCPU: 100m

+ cpuPerNode: 0m

+ baseMemory: 100Mi

+ memoryPerNode: 0Mi

+ ```

+ In this ConfigMap example, it changes the resource limit and request to the following:

+ * cpu: 100 millicore

+ * memory: 100 mebibyte

+ Changing the number of nodes doesn't trigger autoscaling.

+2. Create the ConfigMap using the [kubectl apply][kubectl-apply] command and specify the name of your YAML manifest:

+ ```yml

+ kubectl apply -f metrics-server-config.yaml

+ ```

+3. Restart the Metrics Server pods. There are two Metrics server pods, and the following command deletes all of them.

+ ```bash

+ kubectl -n kube-system delete po metrics-server-pod-name

+ ```

+4. To verify the updated resources took affect, run the following command to review the Metrics Server VPA log.

+ ```bash

+ kubectl -n kube-system logs metrics-server-pod-name -c metrics-server-vpa

+ ```

+ The following example output resembles the results showing the updated throttling settings were applied.

+ ```output

+ ERROR: logging before flag.Parse: I0315 23:12:33.956112 1 pod_nanny.go:68] Invoked by [/pod_nanny --config-dir=/etc/config --cpu=44m

+ --extra-cpu=0.5m --memory=51Mi --extra-memory=4Mi --poll-period=180000 --threshold=5 --deployment=metrics-server --container=metrics-server]

+ ERROR: logging before flag.Parse: I0315 23:12:33.956159 1 pod_nanny.go:69] Version: 1.8.14

+ ERROR: logging before flag.Parse: I0315 23:12:33.956171 1 pod_nanny.go:85] Watching namespace: kube-system, pod: metrics-server-545d8b77b7-5nqq9, container: metrics-server.

+ ERROR: logging before flag.Parse: I0315 23:12:33.956175 1 pod_nanny.go:86] storage: MISSING, extra_storage: 0Gi

+ ERROR: logging before flag.Parse: I0315 23:12:33.957441 1 pod_nanny.go:116] cpu: 100m, extra_cpu: 0m, memory: 100Mi, extra_memory: 0Mi

+ ERROR: logging before flag.Parse: I0315 23:12:33.957456 1 pod_nanny.go:145] Resources: [{Base:{i:{value:100 scale:-3} d:{Dec:<nil>} s:100m Format:DecimalSI} ExtraPerNode:{i:{value:0 scale:-3} d:{Dec:<nil>} s: Format:DecimalSI} Name:cpu} {Base:{i:{value:104857600 scale:0} d:{Dec:<nil>} s:100Mi Format:BinarySI}

+ ExtraPerNode:{i:{value:0 scale:0} d:{Dec:<nil>} s: Format:BinarySI} Name:memory}]

+ ```

+## Troubleshooting

+1. If you use the following configmap, the Metrics Server VPA customizations aren't applied. You need add a unit for `baseCPU`.

+ ```yml

+ apiVersion: v1

+ kind: ConfigMap

+ metadata:

+ name: metrics-server-config

+ namespace: kube-system

+ labels:

+ kubernetes.io/cluster-service: "true"

+ addonmanager.kubernetes.io/mode: EnsureExists

+ data:

+ NannyConfiguration: |-

+ apiVersion: nannyconfig/v1alpha1

+ kind: NannyConfiguration

+ baseCPU: 100

+ cpuPerNode: 1m

+ baseMemory: 100Mi

+ memoryPerNode: 8Mi

+ ```

+

+ The following example output resembles the results showing the updated throttling settings aren't applied.

+

+ ```output

+ ERROR: logging before flag.Parse: I0316 23:32:08.383389 1 pod_nanny.go:68] Invoked by [/pod_nanny --config-dir=/etc/config --cpu=44m

+ --extra-cpu=0.5m --memory=51Mi --extra-memory=4Mi --poll-period=180000 --threshold=5 --deployment=metrics-server --container=metrics-server]

+ ERROR: logging before flag.Parse: I0316 23:32:08.383430 1 pod_nanny.go:69] Version: 1.8.14

+ ERROR: logging before flag.Parse: I0316 23:32:08.383441 1 pod_nanny.go:85] Watching namespace: kube-system, pod: metrics-server-7d78876589-hcrff, container: metrics-server.

+ ERROR: logging before flag.Parse: I0316 23:32:08.383446 1 pod_nanny.go:86] storage: MISSING, extra_storage: 0Gi

+ ERROR: logging before flag.Parse: I0316 23:32:08.384554 1 pod_nanny.go:192] Unable to decode Nanny Configuration from config map, using default parameters

+ ERROR: logging before flag.Parse: I0316 23:32:08.384565 1 pod_nanny.go:116] cpu: 44m, extra_cpu: 0.5m, memory: 51Mi, extra_memory: 4Mi

+ ERROR: logging before flag.Parse: I0316 23:32:08.384589 1 pod_nanny.go:145] Resources: [{Base:{i:{value:44 scale:-3} d:{Dec:<nil>} s:44m Format:DecimalSI} ExtraPerNode:{i:{value:5 scale:-4} d:{Dec:<nil>} s: Format:DecimalSI} Name:cpu} {Base:{i:{value:53477376 scale:0} d:{Dec:<nil>} s:51Mi Format:BinarySI} ExtraPerNode:{i:{value:4194304 scale:0}

+ d:{Dec:<nil>} s:4Mi Format:BinarySI} Name:memory}]

+ ```

+2. For Kubernetes version 1.23 and higher clusters, Metrics Server has a *PodDisruptionBudget*. It ensures the number of available Metrics Server pods is at least one. If you get something like this after running `kubectl -n kube-system get po`, it's possible that the customized resource usage is small. Increase the coefficient values to resolve it.

+ ```output

+ metrics-server-679b886d4-pxwdf 1/2 CrashLoopBackOff 6 (36s ago) 6m33s

+ metrics-server-679b886d4-svxxx 1/2 CrashLoopBackOff 6 (54s ago) 6m33s

+ metrics-server-7d78876589-hcrff 2/2 Running 0 37m

+ ```

+## Next steps

+Metrics Server is a component in the core metrics pipeline. For more information see, [Metrics Server API design][metrics-server-api-design].

+<!-- EXTERNAL LINKS -->

+[kubectl-apply]: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#apply

+[metrics-server-overview]: https://kubernetes-sigs.github.io/metrics-server/

+[metrics-server-api-design]: https://github.com/kubernetes/design-proposals-archive/blob/main/instrumentation/resource-metrics-api.md

+<! INTERNAL LINKS >

+[horizontal-pod-autoscaler]: concepts-scale.md#horizontal-pod-autoscaler

+- You configured an IP-based certificate binding, and the app's IP address has changed because of it. [Remap the A record](configure-ssl-bindings.md#2-remap-records-for-ip-based-ssl) in your DNS entries to the new IP address.

+ By default, values for app settings are hidden in the portal for security. To see a hidden value of an app setting, select its **Value** field. To see the hidden values of all app settings, select the **Show values** button.

+1. To add a new app setting, select **New application setting**. To edit a setting, select the **Edit** button on the right side.

+1. When finished, select **Update**. Don't forget to select **Save** back in the **Configuration** page.

+Select the **Advanced edit** button. Edit the settings in the text area. When finished, select **Update**. Don't forget to select **Save** back in the **Configuration** page.

+You can also configure arrays in app settings as shown in the following table.

+ By default, values for connection strings are hidden in the portal for security. To see a hidden value of a connection string, select its **Value** field. To see the hidden values of all connection strings, select the **Show value** button.

+1. To add a new connection string, select **New connection string**. To edit a connection string, select the **Edit** button on the right side.

+1. When finished, select **Update**. Don't forget to select **Save** back in the **Configuration** page.

+Select the **Advanced edit** button. Edit the connection strings in the text area. When finished, select **Update**. Don't forget to select **Save** back in the **Configuration** page.

+ - **Platform bitness**: 32-bit or 64-bit. For Windows apps only.

+ - **Web sockets**: For [ASP.NET SignalR] or [socket.io](https://socket.io/), for example.

+ - **Always On**: Keeps the app loaded even when there's no traffic. When **Always On** isn't turned on (default), the app is unloaded after 20 minutes without any incoming requests. The unloaded app can cause high latency for new requests because of its warm-up time. When **Always On** is turned on, the front-end load balancer sends a GET request to the application root every five minutes. The continuous ping prevents the app from being unloaded.

+

+ Always On is required for continuous WebJobs or for WebJobs that are triggered using a CRON expression.

+ - **HTTPS Only**: When enabled, all HTTP traffic is redirected to HTTPS.

+ - **Minimum TLS version**: Select the minimum TLS encryption version required by your app.

+The default document is the web page that's displayed at the root URL of an App Service app. The first matching file in the list is used. If the app uses modules that route based on URL instead of serving static content, there's no need for default documents.

+1. To add a default document, select **New document**. To remove a default document, select **Delete** to its right.

+1. Select **New virtual application or directory**.

+1. Select **OK**.

+1. Select **New handler mapping**. Configure the handler as follows:

+1. Select **OK**.

+- [Scale up your App Service app](manage-scale-up.md) to one of the supported pricing tiers: **Basic**, **Standard**, **Premium**.

+- [Map a domain name to your app](app-service-web-tutorial-custom-domain.md) or [buy and configure it in Azure](manage-custom-dns-buy-domain.md).

+## 1. Add the binding

+In the <a href="https://portal.azure.com" target="_blank">Azure portal</a>:

+1. From the left menu, select **App Services** > **\<app-name>**.

+1. From the left navigation of your app, select **Custom domains**

+1. Next to the custom domain, select **Add binding**

+ :::image type="content" source="media/configure-ssl-bindings/secure-domain-launch.png" alt-text="A screenshot showing how to launch the Add TLS/SSL Binding dialog.":::

+1. If your app already has a certificate for the selected custom domain, you can select it in **Certificate**. If not, you must add a certificate using one of the selections in **Source**.

+ - **Create App Service Managed Certificate** - Let App Service create a managed certificate for your selected domain. This option is the simplest. For more information, see [Create a free managed certificate](configure-ssl-certificate.md#create-a-free-managed-certificate).

+ - **Import App Service Certificate** - In **App Service Certificate**, choose an App Service certificate you've purchased for your selected domain. To purchase an App Service certificate, see [Import an App Service certificate](configure-ssl-certificate.md#buy-and-import-app-service-certificate).

+ - **Upload certificate (.pfx)** - Follow the workflow at [Upload a private certificate](configure-ssl-certificate.md#upload-a-private-certificate) to upload a PFX certificate from your local machine and specify the certificate password.

+ - **Import from Key Vault** - Select **Select key vault certificate** and select the certificate in the dialog.

+1. In **TLS/SSL type**, choose between **SNI SSL** and **IP based SSL**.

+ - **[SNI SSL](https://en.wikipedia.org/wiki/Server_Name_Indication)**: Multiple SNI SSL bindings may be added. This option allows multiple TLS/SSL certificates to secure multiple domains on the same IP address. Most modern browsers (including Internet Explorer, Chrome, Firefox, and Opera) support SNI (for more information, see [Server Name Indication](https://wikipedia.org/wiki/Server_Name_Indication)).

+

+1. When adding a new certificate, validate the new certificate by selecting **Validate**.

+1. Select **Add**.

+ Once the operation is complete, the custom domain's TLS/SSL state is changed to **Secure**.

+

+ :::image type="content" source="media/configure-ssl-bindings/secure-domain-finished.png" alt-text="A screenshot showing the custom domain secured by a certificate binding.":::

+

+## 2. Remap records for IP based SSL

+This step is needed only for IP based SSL. For an SNI SSL binding, skip to [Test HTTPS for your custom domain](#3-test-https).

+## 3. Test HTTPS

+Your application code can inspect the protocol via the "x-appservice-proto" header. The header has a value of `http` or `https`.

+## Frequently asked questions

+- [How do I make sure that the app's IP address doesn't change when I make changes to the certificate binding?](#how-do-i-make-sure-that-the-apps-ip-address-doesnt-change-when-i-make-changes-to-the-certificate-binding)

+- [Can I disable the forced redirect from HTTP to HTTPS?](#can-i-disable-the-forced-redirect-from-http-to-https)

+- [How can I change the minimum TLS versions for the app?](#how-can-i-change-the-minimum-tls-versions-for-the-app)

+- [How do I handle TLS termination in App Service?](#how-do-i-handle-tls-termination-in-app-service)

+<a name="prevent-ip-changes"></a>

+#### How do I make sure that the app's IP address doesn't change when I make changes to the certificate binding?

+<a name="enforce-https"></a>

+#### Can I disable the forced redirect from HTTP to HTTPS?

+By default, App Service forces a redirect from HTTP requests to HTTPS. To disable this behavior, see [Configure general settings](configure-common.md#configure-general-settings).

+<a name="enforce-tls-versions"></a>

+#### How can I change the minimum TLS versions for the app?

+Your app allows [TLS](https://wikipedia.org/wiki/Transport_Layer_Security) 1.2 by default, which is the recommended TLS level by industry standards, such as [PCI DSS](https://wikipedia.org/wiki/Payment_Card_Industry_Data_Security_Standard). To enforce different TLS versions, see [Configure general settings](configure-common.md#configure-general-settings).

+<a name="handle-tls-termination"></a>

+#### How do I handle TLS termination in App Service?

+| Upload a public certificate | Public certificates aren't used to secure custom domains, but you can load them into your code if you need them to access remote resources. |

+- Isn't supported on apps that aren't publicly accessible.

+1. To secure a custom domain with this certificate, you still have to create a certificate binding. Follow the steps in [Secure a custom DNS name with a TLS/SSL binding in Azure App Service](configure-ssl-bindings.md).

+[Key Vault](../key-vault/general/overview.md) is an Azure service that helps safeguard cryptographic keys and secrets used by cloud applications and services. For App Service certificates, the storage of choice is Key Vault. After you finish the certificate purchase process, you must complete a few more steps before you start using this certificate.

+1. To secure a custom domain with this certificate, you still have to create a certificate binding. Follow the steps in [Secure a custom DNS name with a TLS/SSL binding in Azure App Service](configure-ssl-bindings.md).

+By default, the App Service resource provider doesn't have access to your key vault. To use a key vault for a certificate deployment, you must [authorize read access for the resource provider to the key vault](../key-vault/general/assign-access-policy-cli.md).

+1. To secure a custom domain with this certificate, you still have to create a certificate binding. Follow the steps in [Secure a custom DNS name with a TLS/SSL binding in Azure App Service](configure-ssl-bindings.md).

+If your certificate authority gives you multiple certificates in the certificate chain, you must merge the certificates following the same order.

+1. When you're prompted, specify a password for the export operation. When you upload your TLS/SSL certificate to App Service later, you must provide this password.

+1. To secure a custom domain with this certificate, you still have to create a certificate binding. Follow the steps in [Secure a custom DNS name with a TLS/SSL binding in Azure App Service](configure-ssl-bindings.md).

+To prevent accidental deletion, Azure puts a lock on the App Service certificate. So, to delete the certificate, you must first remove the delete lock on the certificate.

+Sometimes you might want a dedicated, static IP address for your app. To get a static inbound IP address, you need to [secure a custom DNS name with an IP-based certificate binding](configure-ssl-bindings.md). If you don't actually need TLS functionality to secure your app, you can even upload a self-signed certificate for this binding. In an IP-based TLS binding, the certificate is bound to the IP address itself, so App Service provisions a static IP address to make it happen.

+- [IP-based SSL binding](configure-ssl-bindings.md) The binding is configured on a certificate at the app level. Costs are accrued for each binding. For **Standard** tier and above, the first IP-based binding is not charged.

+App Service automatically syncs your certificate within 24 hours. When you rotate or update a certificate, sometimes the application is still retrieving the old certificate and not the newly updated certificate. The reason is that the job to sync the certificate resource hasn't run yet. To resolve this problem, sync the certificate, which automatically updates the hostname bindings for the certificate in App Service without causing any downtime to your apps.

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

+description: Learn how to use App Service authentication and authorization to secure your App Service apps end-to-end to a downstream Azure service.

+keywords: app service, azure app service, authN, authZ, secure, security, multi-tiered, azure active directory, azure ad

+ms.devlang: javascript

+zone_pivot_groups: app-service-platform-windows-linux

+# Requires non-internal subscription - internal subscriptons doesn't provide permission to correctly configure AAD apps

+# Tutorial: Flow authentication from App Service through back-end API to Microsoft Graph

+Learn how to create and configure a backend App service to accept a frontend app's user credential, then exchange that credential for a downstream Azure service. This allows a user to sign in to a frontend App service, pass their credential to a backend App service, then access an Azure service with the same identity.

+In this tutorial, you learn how to:

+> [!div class="checklist"]

+>

+> * Configure the backend authentication app to provide a token scoped for the downstream Azure service

+> * Use JavaScript code to exchange the [signed-in user's access token](configure-authentication-oauth-tokens.md#retrieve-tokens-in-app-code) for a new token for downstream service.

+> * Use JavaScript code to access downstream service.

+## Prerequisites

+Complete the previous tutorial, [Access Microsoft Graph from a secured JavaScript app as the user](tutorial-auth-aad.md), before starting this tutorial but don't remove the resources at the end of the tutorial. This tutorial assumes you have the two App services and their corresponding authentication apps.

+The previous tutorial used the Azure Cloud Shell as the shell for the Azure CLI. This tutorial continues that usage.

+## Architecture

+The tutorial shows how to pass the user credential provided by the frontend app to the backend app then on to an Azure service. In this tutorial, the downstream service is Microsoft Graph. The user's credential is used to get their profile from Microsoft Graph.

+**Authentication flow** for a user to get Microsoft Graph information in this architecture:

+[Previous tutorial](tutorial-auth-aad.md) covered:

+1. Sign in user to a frontend App service configured to use Active Directory as the identity provider.

+1. The frontend App service passes user's token to backend App service.

+1. The backend App is secured to allow the frontend to make an API request. The user's access token has an audience for the backend API and scope of `user_impersonation`.

+1. The backend app registration already has the Microsoft Graph with the scope `User.Read`. This is added by default to all app registrations.

+1. At the end of the previous tutorial, a _fake_ profile was returned to the frontend app because Graph wasn't connected.

+This tutorial extends the architecture:

+1. Grant admin consent to bypass the user consent screen for the back-end app.

+1. Change the application code to convert the access token sent from the front-end app to an access token with the required permission for Microsoft Graph.

+1. Provide code to have backend app **exchange token** for new token with scope of downstream Azure service such as Microsoft Graph.

+1. Provide code to have backend app **use new token** to access downstream service as the current authenticate user.

+1. **Redeploy** backend app with `az webapp up`.

+1. At the end of this tutorial, a _real_ profile is returned to the frontend app because Graph is connected.

+This tutorial doesn't:

+* Change the frontend app from the previous tutorial.

+* Change the backend authentication app's scope permission because `User.Read` is added by default to all authentication apps.

+## 1. Configure admin consent for the backend app

+In the previous tutorial, when the user signed in to the frontend app, a pop-up displayed asking for user consent.

+In this tutorial, in order to read user profile from Microsoft Graph, the back-end app needs to exchange the signed-in user's [access token](../active-directory/develop/access-tokens.md) for a new access token with the required permissions for Microsoft Graph. Because the user isn't directly connected to the backend app, they can't access the consent screen interactively. You must work around this by configuring the back-end app's app registration in Azure AD to [grant admin consent](../active-directory/manage-apps/grant-admin-consent.md?pivots=portal). This is a setting change typically done by an Active Directory administrator.

+1. Open the Azure portal and search for your research for the backend App Service.

+1. Find the **Settings -> Authentication** section.

+1. Select the identity provider to go to the authentication app.

+1. In the authentication app, select **Manage -> API permissions**.

+1. Select **Grant admin consent for Default Directory**.

+ :::image type="content" source="./media/tutorial-connect-app-app-graph-javascript/azure-portal-authentication-app-api-permission-admin-consent-area.png" alt-text="Screenshot of Azure portal authentication app with admin consent button highlighted.":::

+1. In the pop-up window, select **Yes** to confirm the consent.

+1. Verify the **Status** column says **Granted for Default Directory**. With this setting, the back-end app is no longer required to show a consent screen to the signed-in user and can directly request an access token. The signed-in user has access to the `User.Read` scope setting because that is the default scope with which the app registration is created.

+ :::image type="content" source="./media/tutorial-connect-app-app-graph-javascript/azure-portal-authentication-app-api-permission-admin-consent-granted.png" alt-text="Screenshot of Azure portal authentication app with admin consent granted in status column.":::

+## 2. Install npm packages

+In the previous tutorial, the backend app didn't need any npm packages for authentication because the only authentication was provided by configuring the identity provider in the Azure portal. In this tutorial, the signed-in user's access token for the back-end API must be exchanged for an access token with Microsoft Graph in its scope. This exchange is completed with two libraries because this exchange doesn't use App Service authentication anymore, but Azure Active Directory and MSAL.js directly.

+* [@azure/msal-node](https://www.npmjs.com/package/@azure/msal-node) - exchange token

+* [@microsoft/microsoft-graph-client](https://www.npmjs.com/package/@microsoft/microsoft-graph-client) - connect to Microsoft Graph

+1. Open the Azure Cloud Shell and change into the sample directory's backend app:

+ ```azurecli-interactive

+ cd js-e2e-web-app-easy-auth-app-to-app/backend

+ ```

+1. Install the Azure MSAL npm package:

+ ```azurecli-interactive

+ npm install @azure/msal-node

+ ```

+1. Install the Microsoft Graph npm package:

+ ```azurecli-interactive

+ npm install @microsoft/microsoft-graph-client

+ ```

+## 3. Add code to exchange current token for Microsoft Graph token

+The source code to complete this step is provided for you. Use the following steps to include it.

+1. Open the `./src/server.js` file.

+1. Uncomment the following dependency at the top of the file:

+ ```javascript

+ import { getGraphProfile } from './with-graph/graph';

+ ```

+1. In the same file, uncomment the `graphProfile` variable:

+ ```javascript

+ let graphProfile={};

+ ```

+1. In the same file, uncomment the following `getGraphProfile` lines in the `get-profile` route to get the profile from Microsoft Graph:

+ ```javascript

+ // where did the profile come from

+ profileFromGraph=true;

+ // get the profile from Microsoft Graph

+ graphProfile = await getGraphProfile(accessToken);

+ // log the profile for debugging

+ console.log(`profile: ${JSON.stringify(graphProfile)}`);

+ ```

+1. Save the changes: <kbd>Ctrl</kbd> + <kbd>s</kbd>.

+1. Redeploy the backend app:

+ ```azurecli-interactive

+ az webapp up --resource-group myAuthResourceGroup --name <back-end-app-name>

+## 4. Inspect backend code to exchange backend API token for the Microsoft Graph token

+In order to change the backend API audience token for a Microsoft Graph token, the backend app needs to find the Tenant ID and use that as part of the MSAL.js configuration object. Because the backend app with configured with Microsoft as the identity provider, the Tenant ID and several other required values are already in the App service app settings.

+The following code is already provided for you in the sample app. You need to understand why it's there and how it works so that you can apply this work to other apps you build that need this same functionality.

+### Inspect code for getting the Tenant ID

+1. Open the `./backend/src/with-graph/auth.js` file.

+2. Review the `getTenantId()` function.

+ ```javascript

+ export function getTenantId() {

+

+ const openIdIssuer = process.env.WEBSITE_AUTH_OPENID_ISSUER;

+ const backendAppTenantId = openIdIssuer.replace(/https:\/\/sts\.windows\.net\/(.{1,36})\/v2\.0/gm, '$1');

+

+ return backendAppTenantId;

+ }

+ ```

+3. This function gets the current tenant ID from the `WEBSITE_AUTH_OPENID_ISSUER` environment variable. The ID is parsed out of the variable with a regular expression.

+### Inspect code to get Graph token using MSAL.js

+1. Still in the `./backend/src/with-graph/auth.js` file, review the `getGraphToken()` function.

+1. Build the MSAL.js configuration object, use the MSAL configuration to create the clientCredentialAuthority. Configure the on-behalf-off request. Then use the acquireTokenOnBehalfOf to exchange the backend API access token for a Graph access token.

+ ```javascript

+ // ./backend/src/auth.js

+ // Exchange current bearerToken for Graph API token

+ // Env vars were set by App Service

+ export async function getGraphToken(backEndAccessToken) {

+

+ const config = {

+ // MSAL configuration

+ auth: {

+ // the backend's authentication CLIENT ID

+ clientId: process.env.WEBSITE_AUTH_CLIENT_ID,

+ // the backend's authentication CLIENT SECRET

+ clientSecret: process.env.MICROSOFT_PROVIDER_AUTHENTICATION_SECRET,

+ // OAuth 2.0 authorization endpoint (v2)

+ // should be: https://login.microsoftonline.com/BACKEND-TENANT-ID

+ authority: `https://login.microsoftonline.com/${getTenantId()}`

+ },

+ // used for debugging

+ system: {

+ loggerOptions: {

+ loggerCallback(loglevel, message, containsPii) {

+ console.log(message);

+ },

+ piiLoggingEnabled: true,

+ logLevel: MSAL.LogLevel.Verbose,

+ }

+ }

+ };

+

+ const clientCredentialAuthority = new MSAL.ConfidentialClientApplication(config);

+

+ const oboRequest = {

+ oboAssertion: backEndAccessToken,

+ // this scope must already exist on the backend authentication app registration

+ // and visible in resources.azure.com backend app auth config

+ scopes: ["https://graph.microsoft.com/.default"]

+ }

+

+ // This example has App service validate token in runtime

+ // from headers that can't be set externally

+

+ // If you aren't using App service's authentication,

+ // you must validate your access token yourself

+ // before calling this code

+ try {

+ const { accessToken } = await clientCredentialAuthority.acquireTokenOnBehalfOf(oboRequest);

+ return accessToken;

+ } catch (error) {

+ console.log(`getGraphToken:error.type = ${error.type} ${error.message}`);

+ }

+ }

+ ```

+## 5. Inspect backend code to access Microsoft Graph with the new token

+To access Microsoft Graph as a user signed in to the frontend application, the changes include:

+* Configuration of the Active Directory app registration with an API permission to the downstream service, Microsoft Graph, with the necessary scope of `User.Read`.

+* Grant admin consent to bypass the user consent screen for the back-end app.

+* Change the application code to convert the access token sent from the front-end app to an access token with the required permission for the downstream service, Microsoft Graph.

+Now that the code has the correct token for Microsoft Graph, use it to create a client to Microsoft Graph then get the user's profile.

+1. Open the `./backend/src/graph.js`

+2. In the `getGraphProfile()` function, get the token, then the authenticated client from the token then get the profile.

+ ```javascript

+ //

+ import graph from "@microsoft/microsoft-graph-client";

+ import { getGraphToken } from "./auth.js";

+

+ // Create client from token with Graph API scope

+ export function getAuthenticatedClient(accessToken) {

+ const client = graph.Client.init({

+ authProvider: (done) => {

+ done(null, accessToken);

+ }

+ });

+

+ return client;

+ }

+ export async function getGraphProfile(accessToken) {

+ // exchange current backend token for token with

+ // graph api scope

+ const graphToken = await getGraphToken(accessToken);

+

+ // use graph token to get Graph client

+ const graphClient = getAuthenticatedClient(graphToken);

+

+ // get profile of user

+ const profile = await graphClient

+ .api('/me')

+ .get();

+

+ return profile;

+ }

+ ```

+## 6. Test your changes

+1. Use the frontend web site in a browser. The URL is in the format of `https://<front-end-app-name>.azurewebsites.net/`. You may need to refresh your token if it's expired.

+1. Select `Get user's profile`. This passes your authentication in the bearer token to the backend.

+1. The backend end responds with the _real_ Microsoft Graph profile for your account.

+ :::image type="content" source="./media/tutorial-connect-app-app-graph-javascript/browser-profile-from-microsoft-graph.png" alt-text="Screenshot of web browser showing frontend application after successfully getting real profile from backend app.":::

+## 7. Clean up

+## Frequently asked questions

+#### I got an error `80049217`, what does it mean?

+This error, `CompactToken parsing failed with error code: 80049217`, means the backend App service isn't authorized to return the Microsoft Graph token. This error is caused because the app registration is missing the `User.Read` permission.

+#### I got an error `AADSTS65001`, what does it mean?

+This error, `AADSTS65001: The user or administrator has not consented to use the application with ID \<backend-authentication-id>. Send an interactive authorization request for this user and resource`, means the backend authentication app hasn't been configured for Admin consent. Because the error shows up in the log for the backend app, the frontend application can't tell the user why they didn't see their profile in the frontend app.

+#### How do I connect to a different downstream Azure service as user?

+This tutorial demonstrates an API app authenticated to **Microsoft Graph**, however, the same general steps can be applied to access any Azure service on behalf of the user.

+1. No change to the frontend application. Only changes to the backend's authentication app registration and backend app source code.

+1. Exchange the user's token scoped for backend API for a token to the downstream service you want to access.

+1. Use token in downstream service's SDK to create the client.

+1. Use downstream client to access service functionality.

+## Next steps

+* [Tutorial: Create a secure n-tier app in Azure App Service](tutorial-secure-ntier-app.md)

+* [Deploy a Node.js + MongoDB web app to Azure](tutorial-nodejs-mongodb-app.md)

+ Install-Package Microsoft.Data.SqlClient -Version 5.1.0

+ ### [macOS/Linux](#tab/mac-linux)

+With the introduction of [**custom classification models**](./concept-custom-classifier.md), you can choose to use a [**composed model**](./concept-composed-models.md) or [**classification model**](concept-custom-classifier.md) as an explicit step before analysis. For a deeper understanding of when to use a classification or composed model, _see_ [**Custom classification models**](concept-custom-classifier.md#compare-custom-classification-and-composed-models).

+ Title: Custom classification model - Form Recognizer

+description: Use the custom classification model to train a model to identify and split the documents you process within your application.

+# Custom classification model

+Custom classification models are deep-learning-model types that combine layout and language features to accurately detect and identify documents you process within your application. Custom classification models can classify each page in an input file to identify the document(s) within and can also identify multiple documents or multiple instances of a single document within an input file.

+Custom classification models can analyze a single- or multi-file documents to identify if any of the trained document types are contained within an input file. Here are the currently supported scenarios:

+Training a custom classifier requires at least two distinct classes and a minimum of five samples per class.

+### Compare custom classification and composed models

+A custom classification model can replace [a composed model](concept-composed-models.md) in some scenarios but there are a few differences to be aware of:

+|Analyze a single document of unknown type belonging to one of the types trained for extraction model processing.| &#9679; Requires multiple calls. </br> &#9679; Call the classification model based on the document class. This step allows for a confidence-based check before invoking the extraction model analysis.</br> &#9679; Invoke the extraction model. | &#9679; Requires a single call to a composed model containing the model corresponding to the input document type. |

+Classification models currently only support English language documents.

+Custom classification models require a minimum of five samples per class to train. If the classes are similar, adding extra training samples improves model accuracy.

+Custom classification models are only available in the [v3.0 API](v3-migration-guide.md) starting with API version ```2023-02-28-preview```. [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio) provides a no-code user interface to interactively train a custom classifier.

+When using the REST API, if you've organized your documents by folders, you can use the ```azureBlobSource``` property of the request to train a classification model.

+Learn to create custom classification models:

+> [**Build a custom classification model**](how-to-guides/build-a-custom-classifier.md)

+Custom models now include [custom classification models](./concept-custom-classifier.md) for scenarios where you need to identify the document type prior to invoking the extraction model. Classifier models are available starting with the ```2023-02-28-preview``` API. A classification model can be paired with a custom extraction model to analyze and extract fields from forms and documents specific to your business to create a document processing solution. Standalone custom extraction models can be combined to create [composed models](concept-composed-models.md).

+### Custom classification model

+ Document classification is a new scenario supported by Form Recognizer with the ```2023-02-28-preview``` API. the document classifier API supports classification and splitting scenarios. Train a classification model to identify the different types of documents your application supports. The input file for the classification model can contain multiple documents and classifies each document within an associated page range. See [custom classification](concept-custom-classifier.md) models to learn more.

+1. Label your documents to build and test your custom classification model.

+| [Custom classification model](#custom-classifier)| The **Custom classification model** can classify each page in an input file to identify the document(s) within and can also identify multiple documents or multiple instances of a single document within an input file.

+The general document model is ideal for extracting common key-value pairs from forms and documents. It's a pretrained model and can be directly invoked via the REST API and the SDKs. You can use the general document model as an alternative to training a custom model.

+The custom classification model enables you to identify the document type prior to invoking the extraction model. The classification model is available starting with the 2023-02-28-preview. Training a custom classification model requires at least two distinct classes and a minimum of five samples per class.

+> [Learn more: custom classification model](concept-custom-classifier.md)

+description: Learn how to label, and build a custom document classification model.

+# Build and train a custom classification model

+Custom classification models can classify each page in an input file to identify the document(s) within. Classifier models can also identify multiple documents or multiple instances of a single document in the input file. Form Recognizer custom models require as few as five training documents per document class to get started. To get started training a custom classification model, you need at least **five documents** for each class and **two classes** of documents.

+## Custom classification model input requirements

+1. In the Studio, select the **Custom classification model** tile, on the custom models section of the page and select the **Create a project** button.

+Congratulations you've trained a custom classification model in the Form Recognizer Studio! Your model is ready for use with the REST API or the SDK to analyze documents.

+* [**Health insurance card**](https://formrecognizer.appliedai.azure.com/studio): extract insurer, member, prescription, group number and other key information from US health insurance cards.

+* [**Custom extraction models**](https://formrecognizer.appliedai.azure.com/studio): extract information from forms and documents with custom extraction models. Quickly train a model by labeling as few as five sample documents.

+* [**Custom classification model**](https://formrecognizer.appliedai.azure.com/studio): train a custom classifier to distinguish between the different document types within your applications. Quickly train a model with as few as two classes and five samples per class.

+* [**Custom classification model**](concept-custom-classifier.md) is a new capability within Form Recognizer starting with the ```2023-02-28-preview``` API. Try the document classification capability using the [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio/document-classifier/projects) or the [REST API](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2023-02-28-preview/operations/GetClassifyDocumentResult).

+> - Azure Automation Agent-based User Hybrid Runbook Worker (Windows and Linux) will retire on **31 August 2024** and wouldn't be supported after that date. You must complete migrating existing Agent-based User Hybrid Runbook Workers to Extension-based Workers before 31 August 2024. Moreover, starting **1 October 2023**, creating new Agent-based Hybrid Workers wouldn't be possible. [Learn more](migrate-existing-agent-based-hybrid-worker-to-extension-based-workers.md).

+> - Azure Automation Run As Account will retire on September 30, 2023 and will be replaced with Managed Identities. Before that date, you'll need to start migrating your runbooks to use [managed identities](automation-security-overview.md#managed-identities). For more information, see [migrating from an existing Run As accounts to managed identity](migrate-run-as-accounts-managed-identity.md#sample-scripts) to start migrating the runbooks from Run As account to managed identities before September 30, 2023.

+> [!IMPORTANT]

+> Azure Automation Agent-based User Hybrid Runbook Worker (Windows and Linux) will retire on **31 August 2024** and wouldn't be supported after that date. You must complete migrating existing Agent-based User Hybrid Runbook Workers to Extension-based Workers before 31 August 2024. Moreover, starting **1 October 2023**, creating new Agent-based Hybrid Workers wouldn't be possible. [Learn more](migrate-existing-agent-based-hybrid-worker-to-extension-based-workers.md).

+> [!IMPORTANT]

+> Azure Automation Agent-based User Hybrid Runbook Worker (Windows and Linux) will retire on **31 August 2024** and wouldn't be supported after that date. You must complete migrating existing Agent-based User Hybrid Runbook Workers to Extension-based Workers before 31 August 2024. Moreover, starting **1 October 2023**, creating new Agent-based Hybrid Workers wouldn't be possible. [Learn more](migrate-existing-agent-based-hybrid-worker-to-extension-based-workers.md).

+> [!IMPORTANT]

+> Azure Automation Agent-based User Hybrid Runbook Worker (Windows and Linux) will retire on **31 August 2024** and wouldn't be supported after that date. You must complete migrating existing Agent-based User Hybrid Runbook Workers to Extension-based Workers before 31 August 2024. Moreover, starting **1 October 2023**, creating new Agent-based Hybrid Workers wouldn't be possible. [Learn more](migrate-existing-agent-based-hybrid-worker-to-extension-based-workers.md).

+> [!IMPORTANT]

+> Azure Automation Agent-based User Hybrid Runbook Worker (Windows and Linux) will retire on **31 August 2024** and wouldn't be supported after that date. You must complete migrating existing Agent-based User Hybrid Runbook Workers to Extension-based Workers before 31 August 2024. Moreover, starting **1 October 2023**, creating new Agent-based Hybrid Workers wouldn't be possible. [Learn more](migrate-existing-agent-based-hybrid-worker-to-extension-based-workers.md).

+> [!IMPORTANT]

+> Azure Automation Agent-based User Hybrid Runbook Worker (Windows and Linux) will retire on **31 August 2024** and wouldn't be supported after that date. You must complete migrating existing Agent-based User Hybrid Runbook Workers to Extension-based Workers before 31 August 2024. Moreover, starting **1 October 2023**, creating new Agent-based Hybrid Workers wouldn't be possible. [Learn more](migrate-existing-agent-based-hybrid-worker-to-extension-based-workers.md).

+> [!IMPORTANT]

+> Azure Automation Agent-based User Hybrid Runbook Worker (Windows and Linux) will retire on **31 August 2024** and wouldn't be supported after that date. You must complete migrating existing Agent-based User Hybrid Runbook Workers to Extension-based Workers before 31 August 2024. Moreover, starting **1 October 2023**, creating new Agent-based Hybrid Workers wouldn't be possible. [Learn more](../migrate-existing-agent-based-hybrid-worker-to-extension-based-workers.md)

+- [How do I check if soft delete is enabled on my storage account?](#how-do-i-check-if-soft-delete-is-enabled-on-my-storage-account)

+In a suitable folder, run the following commands to create and activate a virtual environment named `.venv`. Make sure that you're using Python 3.9, 3.8, or 3.7, which are supported by Azure Functions.

+ The [az functionapp create](/cli/azure/functionapp#az-functionapp-create) command creates the function app in Azure. If you're using Python 3.9, 3.8, or 3.7, change `--runtime-version` to `3.9`, `3.8`, or `3.7`, respectively. You must supply `--os-type linux` because Python functions can't run on Windows, which is the default.

+ The [New-AzFunctionApp](/powershell/module/az.functions/new-azfunctionapp) cmdlet creates the function app in Azure. If you're using Python 3.9, 3.8, or 3.7, change `-RuntimeVersion` to `3.9`, `3.8`, or `3.7`, respectively.

+ value: '~4'

+ "value": "~4"

+ value: '~4'

+ "value": "~4"

+ value: '~4'

+ FUNCTIONS_EXTENSION_VERSION: '~4'

+ "value": "~4"

+ "FUNCTIONS_EXTENSION_VERSION": "~4",

+### Logging from created threads

+To see logs coming from your created threads, include the [`context`](/python/api/azure-functions/azure.functions.context) argument in the function's signature. This argument contains an attribute `thread_local_storage` which stores a local `invocation_id`. This can be set to the function's current `invocation_id` to ensure the context is changed.

+```python

+import azure.functions as func

+import logging

+import threading

+def main(req, context):

+ logging.info('Python HTTP trigger function processed a request.')

+ t = threading.Thread(target=log_function, args=(context,))

+ t.start()

+def log_function(context):

+ context.thread_local_storage.invocation_id = context.invocation_id

+ logging.info('Logging from thread.')

+```

+| `thread_local_storage` | The thread local storage of the function. Contains a local `invocation_id` for [logging from created threads](#logging-from-created-threads). |

+Storage accounts secured by using firewalls or virtual private networks also can't be used in the portal creation flow. For more information, see [Restrict your storage account to a virtual network](functions-networking-options.md#restrict-your-storage-account-to-a-virtual-network).

+**Azure** (also known as Azure Commercial, Azure Public, or Azure Global) maintains the following authorizations that pertain to all Azure public regions in the United States:

+| [Azure Resource Manager](../../azure-resource-manager/management/index.yml) | &#x2705; | &#x2705; | &#x2705; | &#x2705; | &#x2705; |

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

+| [Cost Management and Billing](../../cost-management-billing/index.yml) | &#x2705; | &#x2705; | &#x2705; | &#x2705; | |

+| [Dynamics 365 Customer Voice](/dynamics365/customer-voice/about) (formerly Forms Pro) | &#x2705; | &#x2705; | &#x2705; | &#x2705; | |

+| [GitHub AE](https://docs.github.com/en/github-ae@latest/admin/overview/about-github-ae) | &#x2705; | &#x2705; | &#x2705; | | |

+| [Microsoft Azure Government portal](../documentation-government-get-started-connect-with-portal.md) | &#x2705; | &#x2705; | &#x2705;| &#x2705; | |

+| [Power Apps](/powerapps/) | &#x2705; | &#x2705; | &#x2705; | &#x2705; | |

+| [Service Health](../../service-health/index.yml) | &#x2705; | &#x2705; | &#x2705; | &#x2705; | |

+| [Synapse Link for Dataverse](/powerapps/maker/data-platform/export-to-data-lake) | &#x2705; | &#x2705; | &#x2705; | | |

+- [Security Technical Implementation Guides (STIGs)](https://public.cyber.mil/stigs/)

+- [Security Technical Implementation Guides (STIGs)](https://public.cyber.mil/stigs/)

+* An [Azure Maps account]

+* A [subscription key]

+* A [Creator resource]

+[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+[Creator resource]: how-to-manage-creator.md

+zone_pivot_groups: drawing-package-version

+This guide shows you how to prepare your Drawing Package for the Azure Maps [Conversion service v2]. A Drawing Package contains one or more DWG drawing files for a single facility and a manifest file describing the DWG files.

+If you don't have your own package to reference along with this guide, you may download the [sample drawing package v2].

+You may choose any CAD software to open and prepare your facility drawing files. However, this guide is created using Autodesk's AutoCAD® software. Any commands referenced in this guide are meant to be executed using Autodesk's AutoCAD® software.

+> [!TIP]

+> For more information about drawing package requirements that aren't covered in this guide, see [Drawing Package Requirements].

+## Glossary of terms

+For easy reference, here are some terms and definitions that are important as you read this guide.

+| Term | Definition |

+|:--|:|

+| Layer | An AutoCAD DWG layer from the drawing file. |

+| Entity | An AutoCAD DWG entity from the drawing file. |

+| Level | An area of a building at a set elevation. For example, the floor of a building.ΓÇ»|

+| Feature | An object that combines a geometry with more metadata information. |

+| Feature classes | A common blueprint for features. For example, a *unit* is a feature class, and an *office* is a feature. |

+## Step 1: DWG file requirements

+When preparing your facility drawing files for the Conversion service, make sure to follow these preliminary requirements and recommendations:

+* Facility drawing files must be saved in DWG format, which is the native file format for Autodesk's AutoCAD® software.

+* The Conversion service works with the AutoCAD DWG file format. AC1032 is the internal format version for the DWG files, and it's a good idea to select AC1032 for the internal DWG file format version.

+* A DWG file can only contain a single floor. A floor of a facility must be provided in its own separate DWG file. So, if you have five floors in a facility, you must create five separate DWG files.

+## Step 2: Prepare the DWG files

+This part of the guide shows you how to use CAD commands to ensure that your DWG files meet the requirements of the Conversion service.

+You may choose any CAD software to open and prepare your facility drawing files. However, this guide is created using Autodesk's AutoCAD® software. Any commands referenced in this guide are meant to be executed using Autodesk's AutoCAD® software.

+### Bind External References

+Each floor of a facility must be provided as one DWG file. If there are no external references, then nothing more needs to be done. However, if there are any external references, they must be bound to a single drawing. To bind an external reference, you may use the `XREF` command. After binding, each external reference drawing will be added as a block reference. If you need to make changes to any of these layers, remember to explode the block references by using the `XPLODE` command.

+### Unit of measurement

+The drawings can be created using any unit of measurement. However, all drawings must use the same unit of measurement. So, if one floor of the facility is using millimeters, then all other floors (drawings) must also be in millimeters. You can verify or modify the measurement unit by using the `UNITS` command and setting the ΓÇ£Insertion scaleΓÇ¥ value.

+The following image shows the **Drawing Units** window within Autodesk's AutoCAD® software that you can use to verify the unit of measurement.

+### Alignment

+Each floor of a facility is provided as an individual DWG file. As a result, it's possible that the floors don't align perfectly, as required by the Azure Maps Conversion service. To verify alignment, use a reference point such as an elevator or column that spans multiple floors. Use the `XATTACH` command to load all floor drawings, then the `MOVE` command with the reference points to realign any floors that require it.

+### Layers

+Ensure that each layer of a drawing contains entities of one feature class. If a layer contains entities for walls, then it shouldn't have other entities such as units or doors. However, a feature class can be composed of multiple layers. For example, you can have three layers in the drawing that contain wall entities.

+For a better understanding of layers and feature classes, see [Drawing Package Requirements].

+## Step 3: Prepare the manifest

+The drawing package Manifest is a JSON file. The Manifest tells the Azure Maps Conversion service how to read the facility DWG files and metadata. Some examples of this information could be the specific information each DWG layer contains, or the geographical location of the facility.

+To achieve a successful conversion, all ΓÇ£requiredΓÇ¥ properties must be defined. A sample manifest file can be found inside the [sample drawing package v2]. This guide doesn't cover properties supported by the manifest. For more information about manifest properties, see [Manifest File Properties].

+The manifest can be created manually in any text editor, or can be created using the Azure Maps Creator onboarding tool. This guide provides examples for each.

+### The Azure Maps Creator onboarding tool

+You can use the [Azure Maps Creator onboarding tool] to create new and edit existing [manifest files].

+To process the DWG files, enter the geography of your Azure Maps Creator resource, the subscription key of your Azure Maps account and the path and filename of the DWG ZIP package, the select **Process**. This process can take several minutes to complete.

+### Facility levels

+The facility level specifies which DWG file to use for which level. A level must have a level name and ordinal that describes that vertical order of each level in the facility, along with a **Vertical Extent** describing the height of each level in meters.

+The following example is taken from the [sample drawing package v2]. The facility has two levels: ground and level 2. The filename contains the full file name and path of the file relative to the manifest file within the drawing package.

+### DWG layers

+The `dwgLayers` object is used to specify the DWG layer names where feature classes can be found. To receive a properly converted facility, it's important to provide the correct layer names. For example, a DWG wall layer must be provided as a wall layer and not as a unit layer. The drawing can have other layers such as furniture or plumbing; but, the Azure Maps Conversion service ignores anything not specified in the manifest.

+Defining text properties enables you to associate text entities that fall inside the bounds of a feature. Once defined they can be used to style and display elements on your indoor map

+> [!IMPORTANT]

+> Wayfinding support for `Drawing Package 2.0` will be supported in the near future. The following feature class should be defined (non-case sensitive) in order to use [wayfinding]. `Wall` will be treated as an obstruction for a given path request. `Stair` and `Elevator` will be treated as level connectors to navigate across floors:

+>

+> 1. Wall

+> 2. Stair

+> 3. Elevator

+### georeference

+Georeferencing is used to specify the exterior profile, location and rotation of the facility.

+The [facility level] defines the exterior profile as it appears on the map and is selected from the list of DWG layers in the **Exterior** drop-down list.

+The **Anchor Point Longitude** and **Anchor Point Latitude** specify the facility's location, the default value is zero (0).

+The **Anchor Point Angle** is specified in degrees between true north and the drawing's vertical (Y) axis, the default value is zero (0).

+You position the facility's location by entering either an address or longitude and latitude values. You can also pan the map to make minor adjustments to the facility's location.

+### Review and download

+When finished, select the **Review + Download** button to view the manifest. When you finished verifying that it's ready, select the **Download** button to save it locally so that you can include it in the drawing package to import into your Azure Maps Creator resource.

+## Step 4: Prepare the drawing package

+You should now have all the DWG drawings prepared to meet Azure Maps Conversion service requirements. A manifest file has also been created to help describe the facility. All files need to be compressed into a single archive file, with the `.zip` extension. It's important that the manifest file is named `manifest.json` and is placed in the root directory of the drawing package. All other files can be in any directory of the drawing package if the filename includes the relative path to the manifest. For an example of a drawing package, see the [sample drawing package v2].

+<! Drawing Package v1 links>

+[sample drawing package]: https://github.com/Azure-Samples/am-creator-indoor-data-examples/tree/master/Drawing%20Package%201.0

+<! Drawing Package v2 links>

+[Conversion service v2]: https://aka.ms/creator-conversion

+[sample drawing package v2]: https://github.com/Azure-Samples/am-creator-indoor-data-examples/tree/master/Drawing%20Package%202.0

+[Azure Maps Creator onboarding tool]: https://azure.github.io/azure-maps-creator-onboarding-tool

+[manifest files]: /azure/azure-maps/drawing-requirements#manifest-file-requirements

+[wayfinding]: creator-indoor-maps.md#wayfinding-preview

+[facility level]: drawing-requirements.md#facility-level

+zone_pivot_groups: drawing-package-version

+You can convert uploaded drawing packages into map data by using the Azure Maps [Conversion service v2]. This article describes the drawing package requirements for the Conversion API. To view a sample package, you can download the [sample drawing package v2].

+For a guide on how to prepare your drawing package, see [Conversion Drawing Package Guide].

+## Changes and Revisions

+- Added support for user defined feature classes.

+- Simplified requirements of DWG layers.

+## Prerequisites

+The drawing package includes drawings saved in DWG format, which is the native file format for Autodesk's AutoCAD® software.

+You can choose any CAD software to produce the drawings in the drawing package.

+The [Conversion service v2] converts the drawing package into map data. The Conversion service works with the AutoCAD DWG file format AC1032.

+## Glossary of terms

+For easy reference, here are some terms and definitions that are important as you read this article.

+| Term | Definition |

+|:|:-|

+| Layer | An AutoCAD DWG layer from the drawing file. |

+| Entity| An AutoCAD DWG entity from the drawing file. |

+| Xref | A file in AutoCAD DWG file format, attached to the primary drawing as an external reference. |

+| Level | An area of a facility at a set elevation. For example, the floor of a facility. |

+|Feature| An instance of an object produced from the Conversion service that combines a geometry with metadata information. |

+|Feature classes| A common blueprint for features. |

+## Drawing package structure

+A drawing package is a ZIP archive that contains the following files:

+- DWG files in AutoCAD DWG file format.

+- A *manifest.json* file that describes the DWG files in the drawing package.

+The drawing package must be compressed into a single archive file, with the .zip extension. The DWG files can be organized in any way inside the drawing package, but the manifest file must be in the root directory. The next sections explain the conversion process and requirements for both the DWG and manifest files, and the content of these files. To view a sample package, you can download the [sample drawing package v2].

+## DWG file conversion process

+The Azure Maps Conversion service converts DWG file(s) of a facility to map data representing a facility and features of a facility.

+The Azure Maps Conversion service creates:

+- **Facility Feature**: The top-level feature of a facility that all levels of a facility are associated to.

+- **Level features**: One Level feature is created for each floor of a facility. All features on a level are associated with a level.

+- **User defined features**: DWG layers are mapped to a user defined [feature class](#featureclass) and become instances of the feature class.

+<!--DWG layers are mapped to a user defined [feature class](#featureclass). All mapped DWG layer entities become instances of the feature class.-->

+## DWG file requirements

+Each DWG file must adhere to these requirements:

+- The DWG file can't contain features from multiple facilities.

+- The DWG file can't contain features from multiple levels. For example, a facility with three levels has three DWG files in the drawing package.

+- All data of a single level must be contained in a single DWG file. Any external references (*xrefs*) must be bound to the parent drawing.

+- The DWG file must define layer(s) representing the boundary of that level.

+- The DWG must reference the same measurement system and unit of measurement as other DWG files in the drawing package.

+- The DWG file must be aligned when stacked on top of another level from the same facility.

+## DWG layer requirements

+### Feature classes

+One or more DWG layer(s) can be mapped to a user defined feature class. One instance of the feature is created from an entity on the mapped layer. For example, DWG layers chair, table, and couch are mapped to a feature class called furniture. A furniture feature is created for every entity from the defined layers. Additionally:

+- All layers should be separated to represent different feature types of the facility.

+- All entities must fall inside the bounds of the level perimeter.

+- Supported AutoCAD entity types: text, mtext, point, arc, circle, line, polyline, ellipse.

+### Feature class properties

+Text entities that fall within the bounds of a closed shape can be associated to that feature as a property. For example, a room feature class might have text that describes the room name and another the room type [sample drawing package v2]. Additionally:

+- Only TEXT and MTEXT entities will be associated to the feature as a property. All other entity types will be ignored.

+- TEXT and MTEXT justification point must fall within the bounds of the closed shape.

+- If more than one TEXT property is within the bounds of the closed shape and both are mapped to one property, one will randomly be selected.

+### Facility level

+The DWG file for each level must contain a layer to define that level's perimeter. For example, if a facility contains two levels, then it needs to have two DWG files, each with a layer that defines that level's perimeter.

+No matter how many entity drawings are in the level perimeter layer, the resulting facility dataset contains only one level feature for each DWG file. Additionally:

+- Level perimeters must be drawn as Polygon, Polyline (closed), Circle, or Ellipse (closed).

+- Level perimeters may overlap but are dissolved into one geometry.

+- The resulting level feature must be at least 4 square meters.

+- The resulting level feature must not be greater than 400,000 square meters.

+If the layer contains multiple overlapping Polylines, the Polylines are dissolved into a single Level feature. Instead, if the layer contains

+multiple nonoverlapping Polylines, the resulting Level feature has a multi-polygonal representation.

+You can see an example of the Level perimeter layer as the 'GROS$' layer in the [sample drawing package v2].

+## Manifest file requirements

+The drawing package must contain a manifest file at the root level and the file must be named **manifest.json**. It describes the DWG files

+allowing the  [Conversion service v2] to parse their content. Only the files identified by the manifest are used. Files that are in the drawing package, but aren't properly listed in the manifest, are ignored.

+The file paths in the buildingLevels object of the manifest file must be relative to the root of the drawing package. The DWG file name must exactly match the name of the facility level. For example, a DWG file for the "Basement" level is *Basement.dwg*. A DWG file for level 2 is named as *level_2.dwg*. Filenames can't contain spaces, you can use an underscore to replace any spaces.

+Although there are requirements when you use the manifest objects, not all objects are required. The following table shows the required and optional objects for the 2023-03-01-preview [Conversion service v2].

+> [!NOTE]

+> Unless otherwise specified, all string properties are limited to one thousand characters.

+### Manifest JSON file

+| Property | Type | Required | Description  |

+|-|-|-|--|

+| `version` | number | TRUE | Manifest schema version. Currently version 2.0 |

+|`buildingLevels`| [BuildingLevels](#buildinglevels) object  | TRUE | Specifies the levels of the facility and the files containing the design of the levels. |

+|`featureClasses`|Array of [featureClass] objects| TRUE | List of feature class objects that define how layers are read from the DWG drawing file.|

+| `georeference` |[Georeference](#georeference) object| FALSE | Contains numerical geographic information for the facility drawing.     |

+| `facilityName` | string | FALSE | The name of the facility. |

+The next sections detail the requirements for each object.

+#### buildingLevels

+| Property | Type | Required | Description |

+|--||-||

+|`dwgLayers`| Array of strings | TRUE | Names of layers that define the exterior profile of the facility. |

+| `levels` | Array of level objects | TRUE | A level refers to a unique floor in the facility defined in a DWG file, the height of each level and vertical order in which they appear. |

+#### level

+| Property | Type | Required | Description |

+|-||-||

+| `levelName` | string | TRUE | The name of the level. For example: Floor 1, Lobby, Blue Parking, or Basement. |

+| `ordinal` | integer | TRUE | Defines the vertical order of levels. All `ordinal` values must be unique within a facility.|

+| `filename` | string | TRUE | The path and name of the DWG file representing the level in a facility. The path must be relative to the root of the drawing package.  |

+|`verticalExtent`| number | FALSE | Floor-to-ceiling vertical height (thickness) of the level in meters. |

+#### featureClass

+| Property | Type | Required | Description |

+||-|-||

+| `dwgLayers`| Array of strings| TRUE| The name of each layer that defines the feature class. Each entity on the specified layer is converted to an instance of the feature class. The `dwgLayer` name that a feature is converted from ends up as a property of that feature. |

+| `featureClassName` | String | TRUE | The name of the feature class. Typical examples include room, workspace or wall.|

+|`featureClassProperties`| Array of [featureClassProperty] objects | TRUE | Specifies text layers in the DWG file associated to the feature as a property. For example, a label that falls inside the bounds of a space, such as a room number.|

+#### featureClassProperty

+| Property | Type | Required | Description |

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

+| `dwgLayers` | Array of strings | TRUE | The name of each layer that defines the feature class property. Each entity on the specified layer is converted to a property. Only the DWG `TEXT` and `MTEXT` entities are converted to properties. All other entities are ignored. |

+|`featureClassPropertyName`| String | TRUE | Name of the feature class property, for example, spaceName or spaceUseType.|

+#### georeference

+| Property | Type | Required | Description |

+|-|--|-|-|

+| `lat` | number | TRUE | Decimal representation of degrees latitude at the facility drawing's origin. The origin coordinates must be in WGS84 Web Mercator (EPSG:3857). |

+| `lon` | number | TRUE | Decimal representation of degrees longitude at the facility drawing's origin. The origin coordinates must be in WGS84 Web Mercator (EPSG:3857). |

+| `angle` | number | TRUE | The clockwise angle, in degrees, between true north and the drawing's vertical (Y) axis. |

+### Sample drawing package manifest

+The JSON in this example shows the manifest file for the sample drawing package. Go to the [sample drawing package v2] for Azure Maps Creator on GitHub to download the entire package.

+#### Manifest file

+```json

+{

+ "version": "2.0",

+ "buildingLevels": {

+ "dwgLayers": [

+ "GROS$"

+ ],

+ "levels": [

+ {

+ "filename": "Ground.dwg",

+ "levelName": "level 1",

+ "ordinal": 0

+ },

+ {

+ "filename": "Level_2.dwg",

+ "levelName": "level 2",

+ "ordinal": 1

+ }

+ ]

+ },

+ "georeference": {

+ "lat": 47.63529901,

+ "lon": -122.13355885,

+ "angle": 0

+ },

+ "featureClasses": [

+ {

+ "featureClassName": "room",

+ "dwgLayers": [

+ "RM$"

+ ],

+ "featureClassProperties": [

+ {

+ "featureClassPropertyName": "name",

+ "dwgLayers": [

+ "A-IDEN-NUMR-EXST"

+ ]

+ },

+ {

+ "featureClassPropertyName": "roomType",

+ "dwgLayers": [

+ "A-IDEN-NAME-EXST"

+ ]

+ }

+ ]

+ },

+ {

+ "featureClassName": "wall",

+ "dwgLayers": [

+ "A-WALL-EXST",

+ "A-WALL-CORE-EXST",

+ "A-GLAZ-SILL-EXST",

+ "A-GLAZ-SHEL-SILL-EXST",

+ "A-GLAZ-SHEL-EXST",

+ "A-GLAZ-EXST"

+ ]

+ },

+ {

+ "featureClassName": "workspace",

+ "dwgLayers": [

+ "A-BOMA"

+ ]

+ },

+ {

+ "featureClassName": "workspaceFurniture",

+ "dwgLayers": [

+ "A-FURN-SYTM-EXST"

+ ]

+ },

+ {

+ "featureClassName": "buildingFurniture",

+ "dwgLayers": [

+ "A-FURN-FREE-EXST"

+ ]

+ }

+ ],

+ "facilityName": "Contoso Building"

+}

+```

+<! Drawing Package v1 links>

+[Drawing package]: https://github.com/Azure-Samples/am-creator-indoor-data-examples/tree/master/Drawing%20Package%201.0

+[sample drawing package]: https://github.com/Azure-Samples/am-creator-indoor-data-examples/tree/master/Drawing%20Package%201.0

+<! Drawing Package v2 links>

+[Conversion service v2]: https://aka.ms/creator-conversion

+[sample drawing package v2]: https://github.com/Azure-Samples/am-creator-indoor-data-examples/tree/master/Drawing%20Package%202.0

+[Georeference]: drawing-package-guide.md#georeference

+[featureClass]: #featureclass

+[featureClassProperty]: #featureclassproperty

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+[storage account overview]: /azure/storage/common/storage-account-overview

+[create storage account]: /azure/storage/common/storage-account-create?tabs=azure-portal

+[managed identity]: /azure/active-directory/managed-identities-azure-resources/overview

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+- Each [level] contains [units], [structures], [verticalPenetrations] and [openings]. All of the items defined in the level must be fully contained within the Level geometry.

+[Subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+[Subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+[Subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+[Subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+

+ΓÇ» ΓÇ» # Print the search results

+ if len(result.results) > 0:

+ print("Starbucks search result nearby Seattle:")

+ for result_item in result.results:

+ print(f"* {result_item.address.street_number } {result_item.address.street_name }")

+ print(f" {result_item.address.municipality } {result_item.address.country_code } {result_item.address.postal_code }")

+ print(f" Coordinate: {result_item.position.lat}, {result_item.position.lon}")

+

+ # Print reuslts if any

+ if len(result.results) > 0:

+ΓÇ» ΓÇ» print(f"Coordinate: {result.results[0].position.lat}, {result.results[0].position.lon}")

+ else:

+ print("No address found")

+[Subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+[Subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+* An [Azure Maps account]

+* A [subscription key]

+[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+* An [Azure Maps account]

+* A [subscription key]

+[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+* An [Azure Maps account]

+* A [subscription key]

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+* An [Azure Maps account]

+* A [subscription key]

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+Azure Maps [Search service] includes API that offers various capabilities to help developers to search addresses, places, business listings by name or category, and other geographic information. For example, [Search Fuzzy] allows users to search for an address or Point of Interest (POI).

+* An [Azure Maps account]

+* A [subscription key]

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+- [Subscription key](quick-demo-map-app.md#get-the-subscription-key-for-your-account).

+const subscriptionKey = "<Your Azure Maps Subscription Key>";

+ - `Subscription key` is your Azure Maps subscription key.

+* An [Azure Maps account]

+* A [subscription key]

+* Obtain your Azure Active Directory (AAD) credentials with [authentication options]

+ * Load the Azure Maps Web SDK source code locally using the [azure-maps-control](https://www.npmjs.com/package/azure-maps-control) npm package and host it with your app. This package also includes TypeScript definitions.

+ If you're using a subscription key for authentication, copy and paste the following script element inside the `<head>` element, and below the first `<script>` element. Replace `<Your Azure Maps Key>` with your Azure Maps subscription key.

+[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+[authentication options]: /javascript/api/azure-maps-control/atlas.authenticationoptions

+* An [Azure Maps account]

+* A [subscription key]

+[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+[Subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+[Sample Drawing package]: https://github.com/Azure-Samples/am-creator-indoor-data-examples/tree/master/Drawing%20Package%202.0-->

+> [!NOTE]

+> [!NOTE]

+> [!NOTE]

+If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/) before you begin.

+* An [Azure Maps account]

+* A [subscription key]

+Loading a map in both SDKs follows the same set of steps;

+Both Bing and Azure Maps provide a module that adds the ability for the user to draw and edit shapes on the map using the mouse or other input device. They both support drawing pushpins, lines, and polygons. Azure Maps also provides options for drawing circles and rectangles.

+[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/) before you begin.

+* An [Azure Maps account]

+* A [subscription key]

+> [!NOTE]

+> For more information on authentication in Azure Maps, see [manage authentication in Azure Maps](how-to-manage-authentication.md).

+[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+If you don't have an Azure subscription, create a [free account] before you begin.

+* An [Azure Maps account]

+* A [subscription key]

+> [!NOTE]

+> For more information on authentication in Azure Maps, see [manage authentication in Azure Maps].

+[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+[free account]: https://azure.microsoft.com/free/

+[manage authentication in Azure Maps]: how-to-manage-authentication.md

+If you don't have an Azure subscription, create a [free account] before you begin.

+* An [Azure Maps account]

+* A [subscription key]

+> [!NOTE]

+> For more information on authentication in Azure Maps, see [manage authentication in Azure Maps].

+[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+[free account]: https://azure.microsoft.com/free/

+[manage authentication in Azure Maps]: how-to-manage-authentication.md

+If you don't have an Azure subscription, create a [free account] before you begin.

+* An [Azure Maps account]

+* A [subscription key]

+> [!NOTE]

+> For more information on authentication in Azure Maps, see [manage authentication in Azure Maps].

+[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+[free account]: https://azure.microsoft.com/free/

+[manage authentication in Azure Maps]: how-to-manage-authentication.md

+If you don't have an Azure subscription, create a [free account] before you begin.

+* An [Azure Maps account]

+* A [subscription key]

+> [!NOTE]

+> For more information on authentication in Azure Maps, see [manage authentication in Azure Maps].

+[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+[free account]: https://azure.microsoft.com/free/

+[manage authentication in Azure Maps]: how-to-manage-authentication.md

+If you don't have an Azure subscription, create a [free account] before you begin.

+* An [Azure Maps account]

+* A [subscription key]

+> [!NOTE]

+> For more information on authentication in Azure Maps, see [manage authentication in Azure Maps].

+> [Migrate a web app](migrate-from-google-maps-web-app.md)

+[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+[free account]: https://azure.microsoft.com/free/

+[manage authentication in Azure Maps]: how-to-manage-authentication.md

+## Get the subscription key for your account

+If you don't have an Azure subscription, create a [free account] before you begin.

+* An [Azure Maps account]

+* A [subscription key]

+* [ΓÇÄXcode]

+> [!NOTE]

+> For more information on authentication in Azure Maps, see [manage authentication in Azure Maps].

+[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+[free account]: https://azure.microsoft.com/free/

+[manage authentication in Azure Maps]: how-to-manage-authentication.md

+[ΓÇÄXcode]: https://apps.apple.com/cz/app/xcode/id497799835?mt=12

+> [!NOTE]

+> [!NOTE]

+> [!NOTE]

+* [Visual Studio Code] is recommended for this tutorial, but you can use any suitable integrated development environment (IDE).

+* An [Azure Maps account]

+* A [subscription key]

+> [!NOTE]

+> For more information on authentication in Azure Maps, see [manage authentication in Azure Maps].

+ //Add your Azure Maps subscription key to the map SDK.

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+* An [Azure Maps account]

+* A [subscription key]

+* A [Creator resource]

+* Download the [Sample drawing package]

+ https://us.atlas.microsoft.com/conversions?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=2023-03-01-preview&udid={udid}&inputType=DWG&dwgPackageVersion=2.0

+ https://us.atlas.microsoft.com/datasets?api-version=2023-03-01-preview&conversionId={conversionId}&subscription-key={Your-Azure-Maps-Subscription-key}

+ https://us.atlas.microsoft.com/datasets/operations/{operationId}?api-version=2023-03-01-preview&subscription-key={Your-Azure-Maps-Subscription-key}

+ https://us.atlas.microsoft.com/tilesets?api-version=2023-03-01-preview&datasetID={datasetId}&subscription-key={Your-Azure-Maps-Primary-Subscription-key}

+ https://us.atlas.microsoft.com/tilesets/operations/{operationId}?api-version=2023-03-01-preview&subscription-key={Your-Azure-Maps-Subscription-key}

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+* An [Azure Maps account]

+* A [subscription key]

+> [!NOTE]

+> For more information on authentication in Azure Maps, see [manage authentication in Azure Maps].

+[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+[manage authentication in Azure Maps]: how-to-manage-authentication.md

+If you don't have an Azure subscription, create a [free account] before you begin.

+* An [Azure Maps account]

+* A [subscription key]

+* A [resource group]

+* The [rentalCarSimulation] C# project

+This tutorial uses the [Postman] application, but you can choose a different API development environment.

+The rental cars are equipped with IoT devices that regularly send telemetry data to IoT Hub. The telemetry includes the current location and indicates whether the car's engine is running. The device location schema adheres to the IoT [Plug and Play schema for geospatial data]. The rental car's device telemetry schema looks like the following JSON code:

+In this tutorial, you only track one vehicle. After you set up the Azure services, you need to download the [rentalCarSimulation] C# project to run the vehicle simulator. The entire process, from event to function execution, is summarized in the following steps:

+4. The function logs the vehicle device location coordinates, event time, and the device ID. It then uses the [Spatial Geofence Get API] to determine whether the car has driven outside the geofence. If it has traveled outside the geofence boundaries, the function stores the location data received from the event into a blob container. The function also queries the [Search Address Reverse] to translate the coordinate location to a street address, and stores it with the rest of the device location data.

+To store car violation tracking data, create a [general-purpose v2 storage account] in your resource group. If you haven't created a resource group, follow the directions in [create resource groups][resource group]. In this tutorial, you'll name your resource group *ContosoRental*.

+To create a storage account, follow the instructions in [create a storage account]. In this tutorial, name the storage account *contosorentalstorage*, but in general you can name it anything you like.

+Next, use the [Postman] app to [upload the geofence] to Azure Maps. The geofence defines the authorized geographical area for our rental vehicle. You'll be using the geofence in your Azure function to determine whether a car has moved outside the geofence area.

+3. Select **Body** > **raw** for the input format, and choose **JSON** from the drop-down list. [Open the JSON data file], and copy the JSON into the body section. Select **Send**.

+5. To check the status of the API call, create a **GET** HTTP request on the `status URL`. You'll need to append your subscription key to the URL for authentication. The **GET** request should like the following URL:

+To create an IoT hub in the *ContosoRental* resource group, follow the steps in [create an IoT hub].

+Devices can't connect to the IoT hub unless they're registered in the IoT hub identity registry. Here, you'll create a single device with the name, *InVehicleDevice*. To create and register the device within your IoT hub, follow the steps in [register a new device in the IoT hub]. Make sure to copy the primary connection string of your device. You'll need it later.

+Azure Functions is a serverless compute service that allows you to run small pieces of code ("functions"), without the need to explicitly provision or manage compute infrastructure. To learn more, see [Azure Functions].

+Here's the [C# script] code that your function will contain.

+1. For **Storage account**, select the storage account you created in [Create an Azure storage account]. Select **Review + create**.

+1. In the left menu, select the **Code + Test** pane. Copy and paste the [C# script] into the code window.

+ * Replace **SUBSCRIPTION_KEY** with your Azure Maps account subscription key.

+ * Replace **UDID** with the `udid` of the geofence you uploaded in [Upload a geofence].

+ * The `CreateBlobAsync` function in the script creates a blob per event in the data storage account. Replace the **ACCESS_KEY**, **ACCOUNT_NAME**, and **STORAGE_CONTAINER_NAME** with your storage account's access key, account name, and data storage container. These values were generated when you created your storage account in [Create an Azure storage account].

+When you add an Event Grid subscription to the Azure function, a messaging route is automatically created in the specified IoT hub. Message routing allows you to route different data types to various endpoints. For example, you can route device telemetry messages, device life-cycle events, and device twin change events. For more information, see [Use IoT Hub message routing].

+>There are various ways to query IoT device-to-cloud messages. To learn more about message routing syntax, see [IoT Hub message routing].

+When your Azure function is running, you can now send telemetry data to the IoT hub, which will route it to Event Grid. Use a C# application to simulate location data for an in-vehicle device of a rental car. To run the application, you need [.NET Core SDK 3.1] on your development computer. Follow these steps to send simulated telemetry data to the IoT hub:

+1. If you haven't done so already, download the [rentalCarSimulation] C# project.

+* [Get Search Address Reverse]

+* [Get Geofence]

+* [Azure Maps REST APIs]

+* [IoT Plug and Play]

+* [Azure certified devices]

+[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+[free account]: https://azure.microsoft.com/free/

+[resource group]: ../azure-resource-manager/management/manage-resource-groups-portal.md#create-resource-groups

+[rentalCarSimulation]: https://github.com/Azure-Samples/iothub-to-azure-maps-geofencing/tree/master/src/rentalCarSimulation

+[Postman]: https://www.postman.com/

+[Plug and Play schema for geospatial data]: https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v1-preview/schemas/geospatial.md

+[Spatial Geofence Get API]: /rest/api/maps/spatial/getgeofence

+[Search Address Reverse]: /rest/api/maps/search/getsearchaddressreverse

+[general-purpose v2 storage account]: ../storage/common/storage-account-overview.md

+[create a storage account]: ../storage/common/storage-account-create.md?tabs=azure-portal

+[upload the geofence]: ./geofence-geojson.md

+[Open the JSON data file]: https://raw.githubusercontent.com/Azure-Samples/iothub-to-azure-maps-geofencing/master/src/Data/geofence.json?token=AKD25BYJYKDJBJ55PT62N4C5LRNN4

+[create an IoT hub]: ../iot-develop/quickstart-send-telemetry-iot-hub.md?pivots=programming-language-csharp#create-an-iot-hub

+[register a new device in the IoT hub]: ../iot-hub/iot-hub-create-through-portal.md#register-a-new-device-in-the-iot-hub

+[Azure Functions]: ../azure-functions/functions-overview.md

+[C# script]: https://github.com/Azure-Samples/iothub-to-azure-maps-geofencing/blob/master/src/Azure%20Function/run.csx

+[Create an Azure storage account]: #create-an-azure-storage-account

+[Upload a geofence]: #upload-a-geofence

+[Use IoT Hub message routing]: ../iot-hub/iot-hub-devguide-messages-d2c.md

+[IoT Hub message routing]: ../iot-hub/iot-hub-devguide-routing-query-syntax.md

+[.NET Core SDK 3.1]: https://dotnet.microsoft.com/download/dotnet/3.1

+[Get Search Address Reverse]: /rest/api/maps/search/getsearchaddressreverse

+[Get Geofence]: /rest/api/maps/spatial/getgeofence

+[Azure Maps REST APIs]: /rest/api/maps/spatial/getgeofence

+[IoT Plug and Play]: ../iot-develop/index.yml

+[Azure certified devices]: https://devicecatalog.azure.com/

+* An [Azure Maps account]

+* A [subscription key]

+> For more information on authentication in Azure Maps, see [manage authentication in Azure Maps].

+[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+[manage authentication in Azure Maps]: how-to-manage-authentication.md

+This tutorial shows you how to use the Azure Maps [Route service API] and [Map control] to display route directions from start to end point. In this tutorial, you'll learn how to:

+> * Define the display rendering of the route by defining [Symbol layers] and [Line layers].

+> * Get route directions from start and end points using the [Get Route directions API].

+See the [route] tutorial in GitHub for the source code. See [Route to a destination] for a live sample.

+* An [Azure Maps account]

+* A [subscription key]

+3. Next, add the following JavaScript code to the `GetMap` function, just beneath the code added in the last step. This code creates a map control and initializes it using your Azure Maps subscription keys that you provide. Make sure and replace the string `<Your Azure Maps Key>` with the Azure Maps primary key that you copied from your Maps account.

+ // Replace <Your Azure Maps Key> with your Azure Maps subscription key. https://aka.ms/am-primaryKey

+ * [atlas] is the namespace that contains the Azure Maps API and related visual components.

+ * [atlas.Map] provides the control for a visual and interactive web map.

+In this tutorial, we'll render the route using a line layer. The start and end points will be rendered using a symbol layer. For more information on adding line layers, see [Add a line layer to a map](map-add-line-layer.md). To learn more about symbol layers, see [Add a symbol layer to a map].

+ Next, a symbol layer is created and attached to the data source. This layer specifies how the start and end points are rendered.Expressions have been added to retrieve the icon image and text label information from properties on each point object. To learn more about expressions, see [Data-driven style expressions].

+ * This code creates two [GeoJSON Point objects] to represent start and end points, which are then added to the data source.

+ For more information about the Map control's setCamera property, see the [setCamera(CameraOptions | CameraBoundsOptions & AnimationOptions)] property.

+> The Azure Maps Route services offer APIs to plan routes based on different route types such as *fastest*, *shortest*, *eco*, or *thrilling* routes based on distance, traffic conditions, and mode of transport used. The service also lets users plan future routes based on historical traffic conditions. Users can see the prediction of route durations for any given time. For more information, see [Get Route directions API].

+ * Use [MapControlCredential] to share authentication between a map control and the service module when creating a new [pipeline] object.

+ * The [routeURL] represents a URL to Azure Maps [Route] operations.

+* For the completed code used in this tutorial, see the [route] tutorial on GitHub.

+* To view this sample live, see [Route to a destination] on the **Azure Maps Code Samples** site.

+[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+[Route service API]: /rest/api/maps/route

+[Map control]: ./how-to-use-map-control.md

+[Symbol layers]: map-add-pin.md

+[Line layers]: map-add-line-layer.md

+[Get Route directions API]: /rest/api/maps/route/getroutedirections

+[route]: https://github.com/Azure-Samples/AzureMapsCodeSamples/tree/master/Samples/Tutorials/Route

+[Route to a destination]: https://samples.azuremaps.com/?sample=route-to-a-destination

+[atlas]: /javascript/api/azure-maps-control/atlas

+[atlas.Map]: /javascript/api/azure-maps-control/atlas.map

+[Add a symbol layer to a map]: map-add-pin.md

+[Data-driven style expressions]: data-driven-style-expressions-web-sdk.md

+[GeoJSON Point objects]: https://en.wikipedia.org/wiki/GeoJSON

+[setCamera(CameraOptions | CameraBoundsOptions & AnimationOptions)]: /javascript/api/azure-maps-control/atlas.map#setcamera-cameraoptionscameraboundsoptionsanimationoptions-

+[MapControlCredential]: /javascript/api/azure-maps-rest/atlas.service.mapcontrolcredential

+[pipeline]: /javascript/api/azure-maps-rest/atlas.service.pipeline

+[routeURL]: /javascript/api/azure-maps-rest/atlas.service.routeurl

+If you don't have an Azure subscription, create a [free account] before you begin.

+* An [Azure Maps account]

+* A [subscription key]

+> [!NOTE]

+> For more information on authentication in Azure Maps, see [manage authentication in Azure Maps].

+ // Add your Azure Maps subscription key. https://aka.ms/am-primaryKey

+[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+[free account]: https://azure.microsoft.com/free/

+[manage authentication in Azure Maps]: how-to-manage-authentication.md

+If you don't have an Azure subscription, create a [free account] before you begin.

+* An [Azure Maps account]

+* A [subscription key]

+> [!NOTE]

+> For more information on authentication in Azure Maps, see [manage authentication in Azure Maps].

+> [!NOTE]

+[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account

+[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

+[free account]: https://azure.microsoft.com/free/

+[manage authentication in Azure Maps]: how-to-manage-authentication.md

+Legacy table: availabilityResults

+`telemetryType` (`telemetryKind` in Application Insights 3.4.0) must be one of `request`, `dependency`, `trace` (log), or `exception`.

+ Title: Query Prometheus metrics using the API and PromQL

+description: Describes how to use the API to Query metrics in an Azure Monitor workspace using PromQL.

+# Query Prometheus metrics using the API and PromQL

+Azure Monitor managed service for Prometheus (preview), collects metrics from Azure Kubernetes Clusters and stores them in an Azure Monitor workspace. PromQL - Prometheus query language, is a functional query language that allows you to query and aggregate time series data. Use PromQL to query and aggregate metrics stored in an Azure Monitor workspace.

+This article describes how to query an Azure Monitor workspace using PromQL via the REST API.

+For more information on PromQL, see [Querying prometheus](https://prometheus.io/docs/prometheus/latest/querying/basics/).

+## Prerequisites

+To query an Azure monitor workspace using PromQL, you need the following prerequisites:

+## Authentication

+To query your Azure Monitor workspace, authenticate using Azure Active Directory.

+The API supports Azure Active Directory authentication using Client credentials. Register a client app with Azure Active Directory and request a token.

+To set up Azure Active Directory authentication, follow the steps below:

+1. Register an app with Azure Active Directory.

+1. Grant access for the app to your Azure Monitor workspace.

+1. Request a token.

+### Register an app with Azure Active Directory

+1. To register an app, follow the steps in [Register an App to request authorization tokens and work with APIs](../logs/api/register-app-for-token.md?tabs=portal)

+### Allow your app access to your workspace

+Allow your app to query data from your Azure Monitor workspace.

+1. Open your Azure Monitor workspace in the Azure portal.

+1. On the Overview page, take note of your Query endpoint for use in your REST request.

+1. Select Access control (IAM).

+1. Select **Add**, then **Add role assignment** from the Access Control (IAM) page.

+ :::image type="content" source="./media/prometheus-api-promql/access-control.png" lightbox="./media/prometheus-api-promql/access-control.png" alt-text="A screenshot showing the Azure Monitor workspace overview page.":::

+1. On the **Add role Assignment page**, search for *Monitoring*.

+1. Select **Monitoring Data Reader**, then select the Members tab.

+ :::image type="content" source="./media/prometheus-api-promql/add-role-assignment.png" lightbox="./media/prometheus-api-promql/add-role-assignment.png" alt-text="A screenshot showing the Add role assignment page.":::

+1. Select **Select members**.

+1. Search for the app that you registered and select it.

+1. Choose **Select**.

+1. Select **Review + assign**.

+ :::image type="content" source="./media/prometheus-api-promql/select-members.png" lightbox="./media/prometheus-api-promql/select-members.png" alt-text="A screenshot showing the Add role assignment, select members page.":::

+You've created your App registration and have assigned it access to query data from your Azure Monitor workspace. You can now generate a token and use it in a query.

+### Request a token

+Send the following request in the command prompt or by using a client like Postman.

+```shell

+curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \

+-H 'Content-Type: application/x-www-form-urlencoded' \

+--data-urlencode 'grant_type=client_credentials' \

+--data-urlencode 'client_id=<your apps client ID>' \

+--data-urlencode 'client_secret=<your apps client secret' \

+--data-urlencode 'resource= https://prometheus.monitor.azure.com'

+```

+Sample response body:

+```JSON

+{

+ "token_type": "Bearer",

+ "expires_in": "86399",

+ "ext_expires_in": "86399",

+ "expires_on": "1672826207",

+ "not_before": "1672739507",

+ "resource": "https:/prometheus.monitor.azure.com",

+ "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"

+}

+```

+Save the access token from the response for use in the following HTTP requests.

+## Query endpoint

+Find your workspace's query endpoint on the Azure Monitor workspace overview page.

+## Supported APIs

+The following queries are supported:

+### Instant queries

+ For more information, see [Instant queries](https://prometheus.io/docs/prometheus/latest/querying/api/#instant-queries)

+Path: `/api/v1/query`

+Examples:

+```

+POST https://k8s-02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query

+--header 'Authorization: Bearer <access token>'

+--header 'Content-Type: application/x-www-form-urlencoded'

+--data-urlencode 'query=sum( \

+ container_memory_working_set_bytes \

+ * on(namespace,pod) \

+ group_left(workload, workload_type) \

+ namespace_workload_pod:kube_pod_owner:relabel{ workload_type="deployment"}) by (pod)'

+```

+```

+GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query?query=container_memory_working_set_bytes'

+--header 'Authorization: Bearer <access token>'

+```

+### Range queries

+For more information, see [Range queries](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries)

+Path: `/api/v1/query_range`

+Examples:

+```

+GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query_range?query=container_memory_working_set_bytes&start=2023-03-01T00:00:00.000Z&end=2023-03-20T00:00:00.000Z&step=6h'

+--header 'Authorization: Bearer <access token>

+```

+```

+POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query_range'

+--header 'Authorization: Bearer <access token>'

+--header 'Content-Type: application/x-www-form-urlencoded'

+--data-urlencode 'query=up'

+--data-urlencode 'start=2023-03-01T20:10:30.781Z'

+--data-urlencode 'end=2023-03-20T20:10:30.781Z'

+--data-urlencode 'step=6h'

+```

+### Series

+For more information, see [Series](https://prometheus.io/docs/prometheus/latest/querying/api/#finding-series-by-label-matchers)

+Path: `/api/v1/series`

+Examples:

+```

+POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/series'

+--header 'Authorization: Bearer <access token>

+--header 'Content-Type: application/x-www-form-urlencoded'

+--data-urlencode 'match[]=kube_pod_info{pod="bestapp-123abc456d-4nmfm"}'

+```

+```

+GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/series?match[]=container_network_receive_bytes_total{namespace="default-1669648428598"}'

+```

+### Labels

+For more information, see [Labels](https://prometheus.io/docs/prometheus/latest/querying/api/#getting-label-names)

+Path: `/api/v1/labels`

+Examples:

+```

+GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/labels'

+```

+```

+POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/labels'

+```

+### Label values

+For more information, see [Label values](https://prometheus.io/docs/prometheus/latest/querying/api/#query.ing-label-values)

+Path: `/api/v1/label/__name__/values.`

+> [!NOTE]

+> `__name__` is the only supported version of this API and returns all metric names. No other /api/v1/label/<label_name>/values are supported.

+Example:

+```

+GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/label/__name__/values'

+```

+For the full specification of OSS prom APIs, see [Prometheus HTTP API](https://prometheus.io/docs/prometheus/latest/querying/api/#http-api )

+## API limitations

+The following limitations are in addition to those detailed in the Prometheus specification.

+ Any time series fetch queries (/series or /query or /query_range) must contain a \_\_name\_\_ label matcher. That is, each query must be scoped to a metric. There can only be one \_\_name\_\_ label matcher in a query.

+ + /query_range API supports a time range of 32 days. This is the maximum time range allowed including range selectors specified in the query itself.

+ For example, the query `rate(http_requests_total[1h]` for last 24 hours would actually mean data is being queried for 25 hours. A 24 hours range + 1 hour specified in query itself.

+ + /series API fetches data for a maximum 12-hour time range. If `endTime` isn't provided, endTime = time.now(). If the time rage is greater than 12 hours, the `startTime` is set to `endTime ΓÇô 12h`

+ Start time and end time provided with `/labels` and `/label/__name__/values` are ignored, and all retained data in the Azure Monitor Workspace is queried.

+ Experimental features such as exemplars aren't supported.

+For more information on Prometheus metrics limits, see [Prometheus metrics](../../azure-monitor/service-limits.md#prometheus-metrics)

+## Next steps

+[Azure Monitor workspace overview (preview)](./azure-monitor-workspace-overview.md)

+[Manage an Azure Monitor workspace (preview)](./azure-monitor-workspace-manage.md)

+[Overview of Azure Monitor Managed Service for Prometheus (preview)](./prometheus-metrics-overview.md)

+[Query Prometheus metrics using Azure workbooks (preview)](./prometheus-workbooks.md)

+3. Select **Configure** next to the cluster you want to enable.

+If no Azure Monitor Workspace is specified, a default Azure Monitor Workspace is created in the `DefaultRG-<cluster_region>` following the format `DefaultAzureMonitorWorkspace-<mapped_region>`.

+- `--ksm-metric-labels-allow-list` is a comma-separated list of more Kubernetes label keys that is used in the resource's labels metric. By default the metric contains only name and namespace labels. To include more labels provide a list of resource names in their plural form and Kubernetes label keys, you would like to allow for them. A single `*` can be provided per resource instead to allow any labels, but that has severe performance implications.

+- `--enable-windows-recording-rules` lets you enable the recording rule groups required for proper functioning of the windows dashboards.

+- If the Azure Managed Grafana instance is in a subscription other than the Azure Monitor Workspaces subscription, register the Azure Monitor Workspace subscription with the `Microsoft.Dashboard` resource provider following this [documentation](../../azure-resource-manager/management/resource-providers-and-types.md#register-resource-provider).

+Currently in bicep, there's no way to explicitly "scope" the Monitoring Data Reader role assignment on a string parameter "resource ID" for Azure Monitor Workspace (like in ARM template). Bicep expects a value of type "resource | tenant" and currently there's no rest api [spec](https://github.com/Azure/azure-rest-api-specs) for Azure Monitor Workspace. So, as a workaround, the default scoping for Monitoring Data Reader role is on the resource group and thus the role is applied on the same Azure monitor workspace (by inheritance) which is the expected behavior. Thus, after deploying this bicep template, the Grafana resource will get read permissions in all the Azure Monitor Workspaces under the subscription.

+5. The main bicep template creates all the required resources and uses two modules for creating the dcra and monitor metrics profile resources from the other two bicep files.

+3. Create the policy definition using a command like: `az policy definition create --name "(Preview) Prometheus Metrics addon" --display-name "(Preview) Prometheus Metrics addon" --mode Indexed --metadata version=1.0.0 category=Kubernetes --rules .\AddonPolicyMetricsProfile.rules.json --params .\AddonPolicyMetricsProfile.parameters.json`

+5. Select 'Assign' and then go to the 'Parameters' tab and fill in the details. Then select 'Review + Create'.

+In case you create a new Managed Grafana resource from Azure portal, please link it with the corresponding Azure Monitor Workspace from the 'Linked Grafana Workspaces' tab of the relevant Azure Monitor Workspace page. Assign the role 'Monitoring Data Reader' to the Grafana MSI on the Azure Monitor Workspace resource so that it can read data for displaying the charts, using the instructions below.

+7. Select **Select** and then **Review+assign**.

+- Ensure that you update the `kube-state metrics` Annotations and Labels list with proper formatting. There's a limitation in the Resource Manager template deployments that require exact values in the `kube-state` metrics pods. If the Kubernetes pod has any issues with malformed parameters and isn't running, then the feature won't work as expected.

+## Enable windows metrics collection

+As of version 6.4.0-main-02-22-2023-3ee44b9e, windows metric collection has been enabled for the AKS clusters. Onboarding to the Azure Monitor Metrics Addon will enable the windows daemonset pods to start running on your nodepools. Both Windows Server 2019 and Windows Server 2022 are supported. Follow the steps below to enable the pods to collect metrics from your windows node pools.

+1. Manually install the windows exporter on AKS nodes to access windows metrics.

+ Enable the following collectors:

+ * `[defaults]`

+ * `container`

+ * `memory`

+ * `process`

+ * `cpu_info`

+ Deploy the [windows-exporter-daemonset YAML](https://github.com/prometheus-community/windows_exporter/blob/master/kubernetes/windows-exporter-daemonset.yaml) file

+ ```

+ kubectl apply -f windows-exporter-daemonset.yaml

+ ```

+2. Apply the [ama-metrics-settings-configmap](https://github.com/Azure/prometheus-collector/blob/main/otelcollector/configmaps/ama-metrics-settings-configmap.yaml) to your cluster, setting the `windowsexporter` and `windowskubeproxy` booleans to rue`. For more information, see [Metrics addon settings configmap](./prometheus-metrics-scrape-configuration.md#metrics-addon-settings-configmap).

+3. While onboarding, enable the recording rules required for the default dashboards.

+ * For CLI include the option `--enable-windows-recording-rules`.

+ * For ARM template, Bicep, or Policy, set `enableWindowsRecordingRules` to `true` in the parameters file.

+ If the cluster is already onboarded to Azure Monitor Metrics, to enable windows recording rule groups use this [ARM template](https://github.com/Azure/prometheus-collector/blob/kaveesh/windows_recording_rules/AddonArmTemplate/WindowsRecordingRuleGroupTemplate/WindowsRecordingRules.json) and [Parameters](https://github.com/Azure/prometheus-collector/blob/kaveesh/windows_recording_rules/AddonArmTemplate/WindowsRecordingRuleGroupTemplate/WindowsRecordingRulesParameters.json) file to create the rule groups.

+Run the following command to verify that the DaemonSet was deployed properly on the linux nodepools:

+Run the following command to verify that the DaemonSet was deployed properly on the windows nodepools:

+```

+kubectl get ds ama-metrics-win-node --namespace=kube-system

+```

+The output should resemble the following:

+```

+User@aksuser:~$ kubectl get ds ama-metrics-node --namespace=kube-system

+NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE

+ama-metrics-win-node 3 3 3 3 3 <none> 10h

+```

+- HTTP Proxy is supported and will use the same settings as the HTTP Proxy settings for the AKS cluster configured with [these instructions](../../../articles/aks/http-proxy.md).

+- Azure Monitor Private Link (AMPLS) isn't currently supported.

+Install the `aks-preview` extension using the following command:

+```

+az extension add --name aks-preview

+```

+For more information on installing a CLI extension, see [Use and manage extensions with the Azure CLI](/cli/azure/azure-cli-extensions-overview).

+> [!NOTE]

+> Upgrade your az cli version to the latest version and ensure that the aks-preview version you're using is at least '0.5.132'. Find your current version using the `az version`.

+| kubelet | bool | `true` | Scrape kubelet in every node in the K8s cluster without any extra scrape config. |

+| cadvisor | bool | `true` | Scrape cadvisor in every node in the K8s cluster without any extra scrape config.<br>Linux only. |

+| kubestate | bool | `true` | Scrape kube-state-metrics in the K8s cluster (installed as a part of the addon) without any extra scrape config. |

+| coredns | bool | `false` | Scrape coredns service in the K8s cluster without any extra scrape config. |

+| kubeproxy | bool | `false` | Scrape kube-proxy in every linux node discovered in the K8s cluster without any extra scrape config.<br>Linux only. |

+| apiserver | bool | `false` | Scrape the kubernetes api server in the K8s cluster without any extra scrape config. |

+| windowsexporter | bool | `false` | Scrape the windows exporter in every node in the K8s cluster without any extra scrape config.<br>Windows only. |

+| windowskubeproxy | bool | `false` | Scrape the windows kubeproxy in every node in the K8s cluster without any extra scrape config.<br>Windows only. |

+| prometheuscollectorhealth | bool | `false` | Scrape info about the prometheus-collector container such as the amount and size of time series scraped. |

+The `ama-metrics` replicaset pod consumes the custom Prometheus config and scrapes the specified targets. For a cluster with a large number of nodes and pods and a large volume of metrics to scrape, some of the applicable custom scrape targets can be off-loaded from the single `ama-metrics` replicaset pod to the `ama-metrics` daemonset pod. The [ama-metrics-prometheus-config-node configmap](https://aka.ms/azureprometheus-addon-ds-configmap), similar to the regular configmap, can be created to have static scrape configs on each node. The scrape config should only target a single node and shouldn't use service discovery. Otherwise each node tries to scrape all targets and will make many calls to the Kubernetes API server. The `node-exporter` config below is one of the default targets for the daemonset pods. It uses the `$NODE_IP` environment variable, which is already set for every ama-metrics addon container to target a specific port on the node:

+Custom scrape targets can follow the same format using `static_configs` with targets using the `$NODE_IP` environment variable and specifying the port to scrape. Each pod of the daemonset takes the config, scrapes the metrics, and sends them for that node.

+Any other unsupported sections need to be removed from the config before applying as a configmap. Otherwise the custom configuration fails validation and won't be applied.

+- `prometheus.io/scheme`: If the metrics endpoint is secured, then you'll need to set scheme to `https` & most likely set the TLS config.

+## Targets scraped

+The following metrics are collected by default from each default target. All other metrics are dropped through relabeling rules.

+ - `container_fs_writes_bytes_total`

+ - `container_cpu_usage_seconds_total`

+## Targets scraped for windows

+There are two default jobs that can be run for windows which scrape metrics required for the dashboards specific to windows.

+> [!NOTE]

+> This requires an update in the ama-metrics-settings-configmap and installing windows exporter on all windows nodepools. Please refer to the [enablement document](./prometheus-metrics-enable.md#enable-prometheus-metric-collection) for more information

+- `windows-exporter` (`job=windows-exporter`)

+- `kube-proxy-windows` (`job=kube-proxy-windows`)

+## Metrics scraped for windows

+The following metrics are collected when windows exporter and windows kube proxy are enabled.

+**windows-exporter (job=windows-exporter)**<br>

+ - `windows_system_system_up_time`

+ - `windows_cpu_time_total`

+ - `windows_memory_available_bytes`

+ - `windows_os_visible_memory_bytes`

+ - `windows_memory_cache_bytes`

+ - `windows_memory_modified_page_list_bytes`

+ - `windows_memory_standby_cache_core_bytes`

+ - `windows_memory_standby_cache_normal_priority_bytes`

+ - `windows_memory_standby_cache_reserve_bytes`

+ - `windows_memory_swap_page_operations_total`

+ - `windows_logical_disk_read_seconds_total`

+ - `windows_logical_disk_write_seconds_total`

+ - `windows_logical_disk_size_bytes`

+ - `windows_logical_disk_free_bytes`

+ - `windows_net_bytes_total`

+ - `windows_net_packets_received_discarded_total`

+ - `windows_net_packets_outbound_discarded_total`

+ - `windows_container_available`

+ - `windows_container_cpu_usage_seconds_total`

+ - `windows_container_memory_usage_commit_bytes`

+ - `windows_container_memory_usage_private_working_set_bytes`

+ - `windows_container_network_receive_bytes_total`

+ - `windows_container_network_transmit_bytes_total`

+**kube-proxy-windows (job=kube-proxy-windows)**<br>

+ - `kubeproxy_sync_proxy_rules_duration_seconds`

+ - `kubeproxy_sync_proxy_rules_duration_seconds_bucket`

+ - `kubeproxy_sync_proxy_rules_duration_seconds_sum`

+ - `kubeproxy_sync_proxy_rules_duration_seconds_count`

+ - `rest_client_requests_total`

+ - `rest_client_request_duration_seconds`

+ - `rest_client_request_duration_seconds_bucket`

+ - `rest_client_request_duration_seconds_sum`

+ - `rest_client_request_duration_seconds_count`

+ - `process_resident_memory_bytes`

+ - `process_cpu_seconds_total`

+ - `go_goroutines`

+- Kubernetes / Compute Resources / Cluster (Windows)

+- Kubernetes / Compute Resources / Namespace (Windows)

+- Kubernetes / Compute Resources / Pod (Windows)

+- Kubernetes / USE Method / Cluster (Windows)

+- Kubernetes / USE Method / Node (Windows)

+- `node:windows_node:sum`

+- `node:windows_node_num_cpu:sum`

+- `:windows_node_cpu_utilisation:avg5m`

+- `node:windows_node_cpu_utilisation:avg5m`

+- `:windows_node_memory_utilisation:`

+- `:windows_node_memory_MemFreeCached_bytes:sum`

+- `node:windows_node_memory_totalCached_bytes:sum`

+- `:windows_node_memory_MemTotal_bytes:sum`

+- `node:windows_node_memory_bytes_available:sum`

+- `node:windows_node_memory_bytes_total:sum`

+- `node:windows_node_memory_utilisation:ratio`

+- `node:windows_node_memory_utilisation:`

+- `node:windows_node_memory_swap_io_pages:irate`

+- `:windows_node_disk_utilisation:avg_irate`

+- `node:windows_node_disk_utilisation:avg_irate`

+- `node:windows_node_filesystem_usage:`

+- `node:windows_node_filesystem_avail:`

+- `:windows_node_net_utilisation:sum_irate`

+- `node:windows_node_net_utilisation:sum_irate`

+- `:windows_node_net_saturation:sum_irate`

+- `node:windows_node_net_saturation:sum_irate`

+- `windows_pod_container_available`

+- `windows_container_total_runtime`

+- `windows_container_memory_usage`

+- `windows_container_private_working_set_usage`

+- `windows_container_network_received_bytes_total`

+- `windows_container_network_transmitted_bytes_total`

+- `kube_pod_windows_container_resource_memory_request`

+- `kube_pod_windows_container_resource_memory_limit`

+- `kube_pod_windows_container_resource_cpu_cores_request`

+- `kube_pod_windows_container_resource_cpu_cores_limit`

+- `namespace_pod_container:windows_container_cpu_usage_seconds_total:sum_rate`

+| Azure DDoS Protection | [Logging for Azure DDoS Protection](../../ddos-protection/ddos-view-diagnostic-logs.md#example-log-queries) |

+| Azure Functions | [Monitoring Azure Functions Data Reference Resource Logs](../../azure-functions/monitor-functions-reference.md#resource-logs) |

+- Review the following samples for context:

+ - [Enable Service Profiler for containerized ASP.NET Core Application (.NET 6)](https://github.com/microsoft/ApplicationInsights-Profiler-AspNetCore/tree/main/examples/EnableServiceProfilerForContainerAppNet6)

+ - [Application Insights Profiler for Worker Service Example](https://github.com/microsoft/ApplicationInsights-Profiler-AspNetCore/tree/main/examples/ServiceProfilerInWorkerNet6)

+1. In your preferred code editor, enable Application Insights and Profiler in `Program.cs`. [Add custom Profiler settings, if applicable](https://github.com/microsoft/ApplicationInsights-Profiler-AspNetCore/blob/main/Configurations.md).

+ For `WebAPI`:

+ // Add services to the container.

+ builder.Services.AddApplicationInsightsTelemetry();

+ builder.Services.AddServiceProfiler();

+ For `Worker`:

+ IHost host = Host.CreateDefaultBuilder(args)

+ .ConfigureServices(services =>

+ services.AddApplicationInsightsTelemetryWorkerService();

+ services.AddServiceProfiler();

+

+ // Assuming Worker is your background service class.

+ services.AddHostedService<Worker>();

+ })

+ .Build();

+

+ await host.RunAsync();

+## Before you begin

+- [Enable Application Insights in your web app](../app/asp-net.md).

+- Include the [Microsoft.ApplicationInsights.SnapshotCollector](https://www.nuget.org/packages/Microsoft.ApplicationInsights.SnapshotCollector) NuGet package version 1.3.5 or above in your app.

+The default Snapshot Debugger configuration is mostly empty and all settings are optional. You can customize the Snapshot Debugger configuration added to [ApplicationInsights.config](../app/configuration-with-applicationinsights-config.md).

+The following example shows a configuration equivalent to the default configuration:

+```xml

+<TelemetryProcessors>

+ <Add Type="Microsoft.ApplicationInsights.SnapshotCollector.SnapshotCollectorTelemetryProcessor, Microsoft.ApplicationInsights.SnapshotCollector">

+ <!-- The default is true, but you can disable Snapshot Debugging by setting it to false -->

+ <IsEnabled>true</IsEnabled>

+ <!-- Snapshot Debugging is usually disabled in developer mode, but you can enable it by setting this to true. -->

+ <!-- DeveloperMode is a property on the active TelemetryChannel. -->

+ <IsEnabledInDeveloperMode>false</IsEnabledInDeveloperMode>

+ <!-- How many times we need to see an exception before we ask for snapshots. -->

+ <ThresholdForSnapshotting>1</ThresholdForSnapshotting>

+ <!-- The maximum number of examples we create for a single problem. -->

+ <MaximumSnapshotsRequired>3</MaximumSnapshotsRequired>

+ <!-- The maximum number of problems that we can be tracking at any time. -->

+ <MaximumCollectionPlanSize>50</MaximumCollectionPlanSize>

+ <!-- How often we reconnect to the stamp. The default value is 15 minutes.-->

+ <ReconnectInterval>00:15:00</ReconnectInterval>

+ <!-- How often to reset problem counters. -->

+ <ProblemCounterResetInterval>1.00:00:00</ProblemCounterResetInterval>

+ <!-- The maximum number of snapshots allowed in ten minutes.The default value is 1. -->

+ <SnapshotsPerTenMinutesLimit>3</SnapshotsPerTenMinutesLimit>

+ <!-- The maximum number of snapshots allowed per day. -->

+ <SnapshotsPerDayLimit>30</SnapshotsPerDayLimit>

+ <!-- Whether or not to collect snapshot in low IO priority thread. The default value is true. -->

+ <SnapshotInLowPriorityThread>true</SnapshotInLowPriorityThread>

+ <!-- Agree to send anonymous data to Microsoft to make this product better. -->

+ <ProvideAnonymousTelemetry>true</ProvideAnonymousTelemetry>

+ <!-- The limit on the number of failed requests to request snapshots before the telemetry processor is disabled. -->

+ <FailedRequestLimit>3</FailedRequestLimit>

+ </Add>

+</TelemetryProcessors>

+```

+Snapshots are collected _only_ on exceptions reported to Application Insights. In some cases (for example, older versions of the .NET platform), you may need to [configure exception collection](../app/asp-net-exceptions.md#exceptions) to see exceptions with snapshots in the portal.

+Create a new class called `SnapshotCollectorTelemetryProcessorFactory` to add and configure the Snapshot Collector's telemetry processor.

+```csharp

+using Microsoft.ApplicationInsights.AspNetCore;

+using Microsoft.ApplicationInsights.Extensibility;

+using Microsoft.ApplicationInsights.SnapshotCollector;

+using Microsoft.Extensions.Options;

+internal class SnapshotCollectorTelemetryProcessorFactory : ITelemetryProcessorFactory

+{

+ private readonly IServiceProvider _serviceProvider;

+ public SnapshotCollectorTelemetryProcessorFactory(IServiceProvider serviceProvider) =>

+ _serviceProvider = serviceProvider;

+ public ITelemetryProcessor Create(ITelemetryProcessor next)

+ {

+ IOptions<SnapshotCollectorConfiguration> snapshotConfigurationOptions = _serviceProvider.GetRequiredService<IOptions<SnapshotCollectorConfiguration>>();

+ return new SnapshotCollectorTelemetryProcessor(next, configuration: snapshotConfigurationOptions.Value);

+ }

+}

+```

+Add the `SnapshotCollectorConfiguration` and `SnapshotCollectorTelemetryProcessorFactory` services to `Program.cs`:

+```csharp

+using Microsoft.ApplicationInsights.AspNetCore;

+using Microsoft.ApplicationInsights.SnapshotCollector;

+var builder = WebApplication.CreateBuilder(args);

+builder.Services.AddApplicationInsightsTelemetry();

+builder.Services.AddSnapshotCollector(config => builder.Configuration.Bind(nameof(SnapshotCollectorConfiguration), config));

+builder.Services.AddSingleton<ITelemetryProcessorFactory>(sp => new SnapshotCollectorTelemetryProcessorFactory(sp));

+```

+If needed, customize the Snapshot Debugger configuration by adding a `SnapshotCollectorConfiguration` section to *appsettings.json*. The following example shows a configuration equivalent to the default configuration:

+```json

+{

+ "SnapshotCollectorConfiguration": {

+ "IsEnabledInDeveloperMode": false,

+ "ThresholdForSnapshotting": 1,

+ "MaximumSnapshotsRequired": 3,

+ "MaximumCollectionPlanSize": 50,

+ "ReconnectInterval": "00:15:00",

+ "ProblemCounterResetInterval":"1.00:00:00",

+ "SnapshotsPerTenMinutesLimit": 1,

+ "SnapshotsPerDayLimit": 30,

+ "SnapshotInLowPriorityThread": true,

+ "ProvideAnonymousTelemetry": true,

+ "FailedRequestLimit": 3

+ }

+}

+```

+## Configure snapshot collection for other .NET applications

+Snapshots are collected only on exceptions that are reported to Application Insights. You may need to modify your code to report them. The exception handling code depends on the structure of your application, but an example is below:

+```csharp

+TelemetryClient _telemetryClient = new TelemetryClient();

+void ExampleRequest()

+{

+ try

+ {

+ // TODO: Handle the request.

+ }

+ catch (Exception ex)

+ // Report the exception to Application Insights.

+ _telemetryClient.TrackException(ex);

+ // TODO: Rethrow the exception if desired.

+}

+```

+# Configure Virtual WAN for Azure NetApp Files

+* [Azure Virtual WAN](configure-virtual-wan.md) is now generally available in [all regions](azure-netapp-files-network-topologies.md#supported-regions) that support standard network features

+To get started, see [Quickstart: Create and publish an Azure Managed Application definition](./publish-service-catalog-app.md).

+Upload _app.zip_ to an Azure storage account so you can use it when you deploy the managed application's definition. The storage account name must be globally unique across Azure and the length must be 3-24 characters with only lowercase letters and numbers. In the command, replace the placeholder `<demostorageaccount>` including the angle brackets (`<>`), with your unique storage account name.

+ -Name "<demostorageaccount>" `

+ --name <demostorageaccount> \

+ --account-name <demostorageaccount> \

+ --account-name <demostorageaccount> \

+This example uses a security group, and your Azure Active Directory account should be a member of the group. To get the group's object ID, replace the placeholder `<managedAppDemo>` including the angle brackets (`<>`), with your group's name. You use this variable's value when you deploy the managed application definition.

+$principalid=(Get-AzADGroup -DisplayName <managedAppDemo>).Id

+This example uses a security group, and your Azure Active Directory account should be a member of the group. To get the group's object ID, replace the placeholder `<managedAppDemo>` including the angle brackets (`<>`), with your group's name. You use this variable's value when you deploy the managed application definition.

+principalid=$(az ad group show --group <managedAppDemo> --query id --output tsv)

+In the `blob` command's `account-name` parameter, replace the placeholder `<demostorageaccount>` including the angle brackets (`<>`), with your unique storage account name. The `blob` command creates a variable to store the URL for the package _.zip_ file. That variable is used in the command that creates the managed application definition.

+ --account-name <demostorageaccount> \

+Upload _app.zip_ to an Azure storage account so you can use it when you deploy the managed application's definition. The storage account name must be globally unique across Azure and the length must be 3-24 characters with only lowercase letters and numbers. In the command, replace the placeholder `<demostorageaccount>` including the angle brackets (`<>`), with your unique storage account name.

+ -Name "<demostorageaccount>" `

+ --name <demostorageaccount> \

+ --account-name <demostorageaccount> \

+ --account-name <demostorageaccount> \

+ --account-name <demostorageaccount> \

+This example creates a new resource group named `byosDefinitionStorageGroup`. In the command, replace the placeholder `<definitionstorage>` including the angle brackets (`<>`), with your unique storage account name.

+ -Name "<definitionstorage>" `

+$storageid = (Get-AzStorageAccount -ResourceGroupName byosDefinitionStorageGroup -Name <definitionstorage>).Id

+ --name <definitionstorage> \

+storageid=$(az storage account show --resource-group byosDefinitionStorageGroup --name <definitionstorage> --query id --output tsv)

+This example uses a security group, and your Azure Active Directory account should be a member of the group. To get the group's object ID, replace the placeholder `<managedAppDemo>` including the angle brackets (`<>`), with your group's name. You use the variable's value when you deploy the managed application definition.

+$principalid=(Get-AzADGroup -DisplayName <managedAppDemo>).Id

+principalid=$(az ad group show --group <managedAppDemo> --query id --output tsv)

+Add the following to your parameter file and save it. Then, replace the `<placeholder values>` including the angle brackets (`<>`), with your values.

+ "value": "<placeholder for managed application name>"

+ "value": "<placeholder for you storage account ID>"

+ "value": "<placeholder for the packageFileUri>"

+ "value": "<placeholder for principalid value>"

+ "value": "<placeholder for roleid value>"

+To get your variable values:

+- Azure PowerShell: In PowerShell, type `$variableName` to display a variable's value.

+- Azure CLI: In Bash, type `echo $variableName` to display a variable's value.

+You can use the following commands to verify that the managed application definition files are saved in your storage account's container. In the command, replace the placeholder `<definitionstorage>` including the angle brackets (`<>`), with your unique storage account name.

+Get-AzStorageAccount -ResourceGroupName byosDefinitionStorageGroup -Name <definitionstorage> |

+ --account-name <definitionstorage> \

+* Get the URL, and replace scheme https with http, for example, `http://wa1.azurewebsites.net`, open the URL in the browser, now you can start chatting! Use F12 to open network traces, and you can see the SignalR connection is established through **_AG1_**.

+ Title: Customize a speech model in Azure Video Indexer

+description: This article gives an overview of what is a speech model in Azure Video Indexer.

+# Customize a speech model

+Through Azure Video Indexer integration with [Azure speech services](../cognitive-services/speech-service/captioning-concepts.md), a Universal Language Model is utilized as a base model that is trained with Microsoft-owned data and reflects commonly used spoken language. The base model is pretrained with dialects and phonetics representing various common domains. The base model works well in most speech recognition scenarios.

+However, sometimes the base modelΓÇÖs transcription doesn't accurately handle some content. In these situations, a customized speech model can be used to improve recognition of domain-specific vocabulary or pronunciation that is specific to your content by providing text data to train the model. Through the process of creating and adapting speech customization models, your content can be properly transcribed. There is no additional charge for using Video Indexers speech customization.

+## When to use a customized speech model?

+If your content contains industry specific terminology or when reviewing Video Indexer transcription results you notice inaccuracies, you can create and train a custom speech model to recognize the terms and improve the transcription quality. It may only be worthwhile to create a custom model if the relevant words and names are expected to appear repeatedly in the content you plan to index. Training a model is sometimes an iterative process and you might find that after the initial training, results could still use improvement and would benefit from additional training, see [How to Improve your custom model](#how-to-improve-your-custom-models) section for guidance.

+However, if you notice a few words or names transcribed incorrectly in the transcript, a custom speech model might not be needed, especially if the words or names arenΓÇÖt expected to be commonly used in content you plan on indexing in the future. You can just edit and correct the transcript in the Video Indexer website (see [View and update transcriptions in Azure Video Indexer website](edit-transcript-lines-portal.md)) and donΓÇÖt have to address it through a custom speech model.

+For a list of languages that support custom models and pronunciation, see the Customization and Pronunciation columns of the language support table in [Language support in Azure Video Indexer](language-support.md).

+## Train datasets

+When indexing a video, you can use a customized speech model to improve the transcription. Models are trained by loading them with [datasets](../cognitive-services/speech-service/how-to-custom-speech-test-and-train.md) that can include plain text data and pronunciation data.

+Text used to test and train a custom model should include samples from a diverse set of content and scenarios that you want your model to recognize. Consider the following factors when creating and training your datasets:

+- Include text that covers the kinds of verbal statements that your users make when they're interacting with your model. For example, if your content is primarily related to a sport, train the model with content containing terminology and subject matter related to the sport.

+- Include all speech variances that you want your model to recognize. Many factors can vary speech, including accents, dialects, and language-mixing.

+- Only include data that is relevant to content you're planning to transcribe. Including other data can harm recognition quality overall.

+### Dataset types

+There are two dataset types that you can use for customization. To help determine which dataset to use to address your problems, refer to the following table:

+|Use case|Data type|

+|||

+|Improve recognition accuracy on industry-specific vocabulary and grammar, such as medical terminology or IT jargon. |Plain text|

+|Define the phonetic and displayed form of a word or term that has nonstandard pronunciation, such as product names or acronyms. |Pronunciation data |

+### Plain-text data for training

+A dataset including plain text sentences of related text can be used to improve the recognition of domain-specific words and phrases. Related text sentences can reduce substitution errors related to misrecognition of common words and domain-specific words by showing them in context. Domain-specific words can be uncommon or made-up words, but their pronunciation must be straightforward to be recognized.

+### Best practices for plain text datasets

+- Provide domain-related sentences in a single text file. Instead of using full sentences, you can upload a list of words. However, while this adds them to the vocabulary, it doesn't teach the system how the words are ordinarily used. By providing full or partial utterances (sentences or phrases of things that users are likely to say), the language model can learn the new words and how they're used. The custom language model is good not only for adding new words to the system, but also for adjusting the likelihood of known words for your application. Providing full utterances helps the system learn better.

+- Use text data thatΓÇÖs close to the expected spoken utterances. Utterances don't need to be complete or grammatically correct, but they must accurately reflect the spoken input that you expect the model to recognize.

+- Try to have each sentence or keyword on a separate line.

+- To increase the weight of a term such as product names, add several sentences that include the term.

+- For common phrases that are used in your content, providing many examples is useful because it tells the system to listen for these terms.ΓÇ»

+- Avoid including uncommon symbols (~, # @ % &) as they'll get discarded. The sentences in which they appear will also get discarded.

+- Avoid putting too large inputs, such as hundreds of thousands of sentences, because doing so will dilute the effect of boosting.

+Use this table to ensure that your plain text dataset file is formatted correctly:

+|Property|Value|

+|||

+|Text encoding |UTF-8 BOM|

+|Number of utterances per line |1 |

+|Maximum file size |200 MB |

+Try to follow these guidelines in your plain text files:

+- Avoid repeating characters, words, or groups of words more than three times, such as "yeah yeah yeah yeah" as the service might drop lines with too many repetitions.

+- Don't use special characters or UTF-8 characters above U+00A1.

+- URIs is rejected.

+- For some languages such as Japanese or Korean, importing large amounts of text data can take a long time or can time out. Consider dividing the dataset into multiple text files with up to 20,000 lines in each.

+## Pronunciation data for training

+You can add to your custom speech model a custom pronunciation dataset to improve recognition of mispronounced words, phrases, or names.

+Pronunciation datasets need to include the spoken form of a word or phrase as well as the recognized displayed form. The spoken form is the phonetic sequence spelled out, such as ΓÇ£Triple AΓÇ¥. It can be composed of letters, words, syllables, or a combination of all three. The recognized displayed form is how you would like the word or phrase to appear in the transcription. This table includes some examples:

+|Recognized displayed form |Spoken form |

+|||

+|3CPO |three c p o |

+|CNTK |c n t k |

+|AAA |Triple A |

+You provide pronunciation datasets in a single text file. Include the spoken utterance and a custom pronunciation for each. Each row in the file should begin with the recognized form, then a tab character, and then the space-delimited phonetic sequence.

+```

+3CPO three c p o

+CNTK c n t k

+IEEE i triple e

+```

+Consider the following when creating and training pronunciation datasets:

+ItΓÇÖs not recommended to use custom pronunciation files to alter the pronunciation of common words.

+If there are a few variations of how a word or name is incorrectly transcribed, consider using some or all of them when training the pronunciation dataset. For example, if Robert is mentioned five times in the video and transcribed as Robort, Ropert, and robbers. You can try including all variations in the file as in the following example but be cautious when training with actual words like robbers as if robbers is mentioned in the video, it is transcribed as Robert.

+`Robert Roport`

+`Robert Ropert`

+`Robert Robbers`

+Pronunciation model isn't meant to address acronyms. For example, if you want Doctor to be transcribed as Dr., this can't be achieved through a pronunciation model.

+Refer to the following table to ensure that your pronunciation dataset files are valid and correctly formatted.

+|Property |Value |

+|||

+|Text encoding |UTF-8 BOM (ANSI is also supported for English) |

+|Number of pronunciations per line |1 |

+|Maximum file size |1 MB (1 KB for free tier) |

+## How to improve your custom models

+Training a pronunciation model can be an iterative process, as you might gain more knowledge on the pronunciation of the subject after initial training and evaluation of your modelΓÇÖs results. Since existing models can't be edited or modified, training a model iteratively requires the creation and uploading of datasets with additional information as well as training new custom models based on the new datasets. You would then reindex the media files with the new custom speech model.

+Example:

+Let's say you plan on indexing sports content and anticipate transcript accuracy issues with specific sports terminology as well as in the names of players and coaches. Before indexing, you've created a speech model with a plain text dataset with content containing relevant sports terminology and a pronunciation dataset with some of the player and coachesΓÇÖ names. You index a few videos using the custom speech model and when reviewing the generated transcript, find that while the terminology is transcribed correctly, many names aren't. You can take the following steps to improve performance in the future:

+1. Review the transcript and note all the incorrectly transcribed names. They could fall into two groups:

+ - Names not in the pronunciation file.

+ - Names in the pronunciation file but they're still incorrectly transcribed.

+2. Create a new dataset file. Either download the pronunciation dataset file or modify your locally saved original. For group A, add the new names to the file with how they were incorrectly transcribed (MichaelΓÇâMikel). For group B, add additional lines with each line having the correct name and a unique example of how it was incorrectly transcribed. For example:

+ `StephenΓÇâSteven`

+ `StephenΓÇâSteafan`

+ `StephenΓÇâSteevan`

+3. Upload this file as a new dataset file.

+4. Create a new speech model and add the original plain text dataset and the new pronunciation dataset file.

+5. Reindex the video with the new speech model.

+6. If needed, repeat steps 1-5 until the results are satisfactory.

+## Next steps

+To get started with speech customization, see:

+- [Customize a speech model using the API](customize-speech-model-with-api.md)

+- [Customize a speech model using the website](customize-speech-model-with-website.md)

+ Title: Customize a speech model with the Azure Video Indexer API

+description: Learn how to customize a speech model with the Azure Video Indexer API.

+# Customize a speech model with the API

+Azure Video Indexer lets you create custom language models to customize speech recognition by uploading adaptation text, namely text from the domain whose vocabulary you'd like the engine to adapt to or aligning word or name pronunciation with how it should be written.

+For a detailed overview and best practices for custom speech models, seeΓÇ»[Customize a speech model with Azure Video Indexer](customize-speech-model-overview.md).

+You can use the Azure Video Indexer APIs to create and edit custom language models in your account. You can also use the website, as described inΓÇ»[Customize speech model using the Azure Video Indexer website](customize-speech-model-with-website.md).

+The following are descriptions of some of the parameters:

+|NameΓÇâΓÇâΓÇâ|ΓÇâTypeΓÇâ|ΓÇâΓÇâDescriptionΓÇâ|ΓÇâ

+||||

+|`displayName`ΓÇâ |stringΓÇâ|The desired name of the dataset/model.|

+|`locale`ΓÇâ ΓÇâ|stringΓÇâ|The language code of the dataset/model. For full list, see [Language support](language-support.md).|

+|`kind` ΓÇâ|integer|0 for a plain text dataset, 1 for a pronunciation dataset.|

+|`description`ΓÇâΓÇâ |stringΓÇâ|Optional description of the dataset/model.|

+|`contentUrl`ΓÇâΓÇâ |uriΓÇâ |URL of source file used in creation of dataset.|

+|`customProperties`ΓÇâ|objectΓÇâ|Optional properties of dataset/model.|

+## Create a speech dataset

+The [create speech dataset](https://api-portal.videoindexer.ai/api-details#api=Operations&operation=Create-Speech-Dataset) API creates a dataset for training a speech model. You upload a file that is used to create a dataset with this call. The content of a dataset can't be modified after it's created.

+To upload a file to a dataset, you must update parameters in the Body, including a URL to the text file to be uploaded. The description and custom properties fields are optional. The following is a sample of the body:

+```json

+{

+ "displayName": "Pronunciation Dataset",

+ "locale": "en-US",

+ "kind": "Pronunciation",

+ "description": "This is a pronunciation dataset.",

+ "contentUrl": https://contoso.com/location,

+ "customProperties": {

+ "tag": "Pronunciation Dataset Example"

+ }

+}

+```

+### Response

+The response provides metadata on the newly created dataset following the format of this example JSON output:

+```json

+{

+ "id": "000000-0000-0000-0000-f58ac7002ae9",

+ "properties": {

+ "acceptedLineCount": 0,

+ "rejectedLineCount": 0,

+ "duration": null,

+ "error": null

+ },

+ "displayName": "Contoso plain text",

+ "description": "AVI dataset",

+ "locale": "en-US",

+ "kind": "Language",

+ "status": "Waiting",

+ "lastActionDateTime": "2023-02-28T13:24:27Z",

+ "createdDateTime": "2023-02-28T13:24:27Z",

+ "customProperties": null

+}

+```

+## Create a speech model

+The [create a speech model](https://api-portal.videoindexer.ai/api-details#api=Operations&operation=Create-Speech-Model) API creates and trains a custom speech model that could then be used to improve the transcription accuracy of your videos. It must contain at least one plain text dataset and can optionally have pronunciation datasets. Create it with all of the relevant dataset files as a model’s datasets can't be added or updated after its creation.

+When creating a speech model, you must update parameters in the Body, including a list of strings where the strings are the dataset/s the model will include. The description and custom properties fiels are optional. The following is a sample of the body:

+```json

+{

+ "displayName": "Contoso Speech Model",

+ "locale": "en-US",

+ "datasets": ["ff3d2bc4-ab5a-4522-b599-b3d5ba768c75", "87c8962d-1d3c-44e5-a2b2-c696fddb9bae"],

+ "description": "Contoso ads example model",

+ "customProperties": {

+ "tag": "Example Model"

+ }

+}

+```

+### Response

+The response provides metadata on the newly created model following the format of this example JSON output:

+```json{

+ "id": "00000000-0000-0000-0000-85be4454cf",

+ "properties": {

+ "deprecationDates": {

+ "adaptationDateTime": null,

+ "transcriptionDateTime": "2025-04-15T00:00:00Z"

+ },

+ "error": null

+ },

+ "displayName": "Contoso speech model",

+ "description": "Contoso speech model for video indexer",

+ "locale": "en-US",

+ "datasets": ["00000000-0000-0000-0000-f58ac7002ae9"],

+ "status": "Processing",

+ "lastActionDateTime": "2023-02-28T13:36:28Z",

+ "createdDateTime": "2023-02-28T13:36:28Z",

+ "customProperties": null

+}

+```

+## Get speech dataset

+TheΓÇ»[get speech dataset](https://api-portal.videoindexer.ai/api-details#api=Operations&operation=Get-Speech-Dataset) API returns information on the specified dataset.

+### Response

+The response provides metadata on the specified dataset following the format of this example JSON output:

+```json

+{

+ "id": "00000000-0000-0000-0000-f58002ae9",

+ "properties": {

+ "acceptedLineCount": 41,

+ "rejectedLineCount": 0,

+ "duration": null,

+ "error": null

+ },

+ "displayName": "Contoso plain text",

+ "description": "AVI dataset",

+ "locale": "en-US",

+ "kind": "Language",

+ "status": "Complete",

+ "lastActionDateTime": "2023-02-28T13:24:43Z",

+ "createdDateTime": "2023-02-28T13:24:27Z",

+ "customProperties": null

+}

+```

+## Get speech datasets files

+TheΓÇ»[get speech dataset files](https://api-portal.videoindexer.ai/api-details#api=Operations&operation=Get-Speech-Dataset-Files) API returns the files and metadata of the specified dataset.

+### Response

+The response provides a URL with the dataset files and metadata following the format of this example JSON output:

+```json

+[{

+ "datasetId": "00000000-0000-0000-0000-f58ac72a",

+ "fileId": "00000000-0000-0000-0000-cb190769c",

+ "name": "languagedata",

+ "contentUrl": "",

+ "kind": "LanguageData",

+ "createdDateTime": "2023-02-28T13:24:43Z",

+ "properties": {

+ "size": 1517

+ }

+}, {

+ "datasetId": "00000000-0000-0000-0000-f58ac72ΓÇ¥

+ "fileId": "00000000-0000-0000-0000-2369192e",

+ "name": "normalized.txt",

+ "contentUrl": "",

+ "kind": "LanguageData",

+ "createdDateTime": "2023-02-28T13:24:43Z",

+ "properties": {

+ "size": 1517

+ }

+}, {

+ "datasetId": "00000000-0000-0000-0000-f58ac7",

+ "fileId": "00000000-0000-0000-0000-05f1e306",

+ "name": "report.json",

+ "contentUrl": "",

+ "kind": "DatasetReport",

+ "createdDateTime": "2023-02-28T13:24:43Z",

+ "properties": {

+ "size": 78

+ }

+}]

+```

+## Get the specified account datasets

+TheΓÇ»[get speech datasets](https://api-portal.videoindexer.ai/api-details#api=Operations&operation=Get-Speech-Datasets) API returns information on all of the specified accounts datasets.

+### Response

+The response provides metadata on the datasets in the specified account following the format of this example JSON output:

+```json

+[{

+ "id": "00000000-0000-0000-abf5-4dad0f",

+ "properties": {

+ "acceptedLineCount": 41,

+ "rejectedLineCount": 0,

+ "duration": null,

+ "error": null

+ },

+ "displayName": "test",

+ "description": "string",

+ "locale": "en-US",

+ "kind": "Language",

+ "status": "Complete",

+ "lastActionDateTime": "2023-02-27T08:42:02Z",

+ "createdDateTime": "2023-02-27T08:41:39Z",

+ "customProperties": null

+}]

+```

+## Get the specified speech model

+TheΓÇ»[get speech model](https://api-portal.videoindexer.ai/api-details#api=Operations&operation=Get-Speech-Model) API returns information on the specified model.

+### Response

+The response provides metadata on the specified model following the format of this example JSON output:

+```json

+{

+ "id": "00000000-0000-0000-0000-5685be445",

+ "properties": {

+ "deprecationDates": {

+ "adaptationDateTime": null,

+ "transcriptionDateTime": "2025-04-15T00:00:00Z"

+ },

+ "error": null

+ },

+ "displayName": "Contoso speech model",

+ "description": "Contoso speech model for video indexer",

+ "locale": "en-US",

+ "datasets": ["00000000-0000-0000-0000-f58ac7002"],

+ "status": "Complete",

+ "lastActionDateTime": "2023-02-28T13:36:38Z",

+ "createdDateTime": "2023-02-28T13:36:28Z",

+ "customProperties": null

+}

+```

+## Get the specified account speech models

+TheΓÇ»[get speech models](https://api-portal.videoindexer.ai/api-details#api=Operations&operation=Get-Speech-Models) API returns information on all of the models in the specified account.

+### Response

+The response provides metadata on all of the speech models in the specified account following the format of this example JSON output:

+```json

+[{

+ "id": "00000000-0000-0000-0000-5685be445",

+ "properties": {

+ "deprecationDates": {

+ "adaptationDateTime": null,

+ "transcriptionDateTime": "2025-04-15T00:00:00Z"

+ },

+ "error": null

+ },

+ "displayName": "Contoso speech model",

+ "description": "Contoso speech model for video indexer",

+ "locale": "en-US",

+ "datasets": ["00000000-0000-0000-0000-f58ac7002a"],

+ "status": "Complete",

+ "lastActionDateTime": "2023-02-28T13:36:38Z",

+ "createdDateTime": "2023-02-28T13:36:28Z",

+ "customProperties": null

+}]

+```

+## Delete speech dataset

+The [delete speech dataset](https://api-portal.videoindexer.ai/api-details#api=Operations&operation=Delete-Speech-Dataset) API deletes the specified dataset. Any model that was trained with the deleted dataset continues to be available until the model is deleted. You cannot delete a dataset while it is in use for indexing or training.

+### Response

+There's no returned content when the dataset is deleted successfully.

+## Delete a speech model

+The [delete speech model](https://api-portal.videoindexer.ai/api-details#api=Operations&operation=Delete-Speech-Model) API deletes the specified speech model. You cannot delete a model while it is in use for indexing or training.

+### Response

+There's no returned content when the speech model is deleted successfully.

+## Next steps

+[Customize a speech model using the website](customize-speech-model-with-website.md)

+ Title: Customize a speech model with Azure Video Indexer website

+description: Learn how to customize a speech model with the Azure Video Indexer website.

+# Customize a speech model in the website

+

+Azure Video Indexer lets you create custom speech models to customize speech recognition by uploading datasets that are used to create a speech model. This article goes through the steps to do so through the Video Indexer website. You can also use the API, as described inΓÇ»[Customize speech model using API](customize-speech-model-with-api.md).

+For a detailed overview and best practices for custom speech models, seeΓÇ»[Customize a speech model with Azure Video Indexer](customize-speech-model-overview.md).

+## Create a dataset

+As all custom models must contain a dataset, we'll start with the process of how to create and manage datasets.

+1. Go to the [Azure Video Indexer website](https://www.videoindexer.ai/) and sign in.

+1. Select the Model customization button on the left of the page.

+1. Select the Speech (new) tab. Here you'll begin the process of uploading datasets that are used to train the speech models.

+ > [!div class="mx-imgBorder"]

+ > :::image type="content" source="./media/customize-speech-model/speech-model.png" alt-text="Screenshot of uploading datasets which are used to train the speech models.":::

+1. Select Upload dataset.

+1. Select either Plain text or Pronunciation from the Dataset type dropdown menu. Every speech model must have a plain text dataset and can optionally have a pronunciation dataset. To learn more about each type, see Customize a speech model with Azure Video Indexer.

+1. Select Browse which will open the File Explorer. You can only use one file in each dataset. Choose the relevant text file.

+1. Select a Language for the model. Choose the language that is spoken in the media files you plan on indexing with this model.

+1. The Dataset name is pre-populated with the name of the file but you can modify the name.

+1. You can optionally add a description of the dataset. This could be helpful to distinguish each dataset if you expect to have multiple datasets.

+ > [!div class="mx-imgBorder"]

+ > :::image type="content" source="./media/customize-speech-model/dataset-type.png" alt-text="Screenshot of multiple datasets.":::

+1. Once you're ready, select Upload. You'll then see a list of all of your datasets and their properties, including the type, language, status, number of lines, and creation date. Once the status is complete, it can be used in the training and creation or new models.

+ > [!div class="mx-imgBorder"]

+ > :::image type="content" source="./media/customize-speech-model/datasets.png" alt-text="Screenshot of a new model.":::

+## Review and update a dataset

+Once a Dataset has been uploaded, you might need to review it or perform any number of updates to it. This section covers how to view, download, troubleshoot, and delete a dataset.

+**View dataset**: You can view a dataset and its properties by either clicking on the dataset name or when hovering over the dataset or clicking on the ellipsis and selecting **View Dataset**.

+> [!div class="mx-imgBorder"]

+> :::image type="content" source="./media/customize-speech-model/view-dataset.png" alt-text="Screenshot of how to view dataset.":::

+You'll then view the name, description, language and status of the dataset plus the following properties:

+**Number of lines**: indicates the number of lines successfully loaded out of the total number of lines in the file. If the entire file is loaded successfully the numbers will match (for example, 10 of 10 normalized). If the numbers don't match (for example, 7 of 10 normalized), this means that only some of the lines successfully loaded and the rest had errors. Common causes of errors are formatting issues with a line, such as not spacing a tab between each word in a pronunciation file. Reviewing the plain text and pronunciation data for training articles should be helpful in finding the issue. To troubleshoot the cause, review the error details, which are contained in the report. Select **View report** to view the error details regarding the lines that didn't load successfully (errorKind). This can also be viewed by selecting the **Report** tab.

+> [!div class="mx-imgBorder"]

+> :::image type="content" source="./media/customize-speech-model/report-tab.png" alt-text="Screenshot of how to view by selecting report tab.":::

+**Dataset ID**: Each dataset has a unique GUID, which is needed when using the API for operations that reference the dataset.

+**Plain text (normalized)**: This contains the normalized text of the loaded dataset file. Normalized text is the recognized text in plain form without formatting.

+**Edit Details**: To edit a dataset's name or description, when hovering over the dataset, click on the ellipsis and then select Edit details. You're then able to edit the dataset name and description.

+> [!Note]

+> The data in a dataset can't be edited or updated once the dataset has been uploaded. If you need to edit or update the data in a dataset, download the dataset, perform the edits, save the file, and upload the new dataset file.

+**Download**: To download a dataset file, when hovering over the dataset, click on the ellipsis and then select Download. Alternatively, when viewing the dataset, you can select Download and then have the option of downloading the dataset file or the upload report in JSON form.

+**Delete**: To delete a dataset, when hovering over the dataset, click on the ellipsis and then select Delete.

+## Create a custom speech model

+Datasets are used in the creation and training of models. Once you have created a plain text dataset, you are now able to create and start using a custom speech model.

+Keep in mind the following when creating and using custom speech models:

+* A new model must include at least one plain text dataset and can have multiple plain text datasets.

+* It's optional to include a pronunciation dataset and no more than one can be included.

+* Once a model is created, you can't add additional datasets to it or perform any modifications to its datasets. If you need to add or modify datasets, create a new model.

+* If you have indexed a video using a custom speech model and then delete the model, the transcript is not impacted unless you perform a re-index.

+* If you deleted a dataset that was used to train a custom model, as the speech model was already trained by the dataset, it continues to use it until the speech model is deleted.

+* If you delete a custom model, it has no impact of the transcription of videos that were already indexed using the model.

+**The following are instructions to create and manage custom speech models. There are two ways to train a model ΓÇô through the dataset tab and through the model tab.**

+## Train a model through the Datasets tab

+1. When viewing the list of datasets, if you select a plain text dataset by clicking on the circle to the left of a plain text datasetΓÇÖs name, the Train new model icon above the datasets will now turn from greyed out to blue and can be selected. Select Train new model.

+ > [!div class="mx-imgBorder"]

+ > :::image type="content" source="./media/customize-speech-model/train-model.png" alt-text="Screenshot of how to train new model.":::

+1. In the Train a new model popup, enter a name for the model, a language, and optionally add a description. A model can only contain datasets of the same language.

+1. Select the Datasets tab and then select from the list of your datasets the datasets you would like to be included in the model. Once a model is created, datasets can't be added.

+1. Select Create ad train.

+## Train a model through the Models tab

+1. Select the Models tab and then the Train new model icon. If no plain text datasets have been uploaded, the icon is greyed out. Select all the datasets that you want to be part of the model by clicking on the circle to the left of a plain text datasetΓÇÖs name.

+1. In the Train a new model pop-up, enter a name for the model, a language, and optionally add a description. A model can only contain datasets of the same language.

+1. Select the Datasets tab and then select from the list of your datasets the datasets you would like to be included in the model. Once a model is created, datasets can't be added.

+1. Select Create and train.

+## Model review and update

+Once a Model has been created, you might need to review its datasets, edits its name, or delete it.

+**View Model**: You can view a model and its properties by either clicking on the modelΓÇÖs name or when hovering over the model, clicking on the ellipsis and then selecting View Model.

+> [!div class="mx-imgBorder"]

+> :::image type="content" source="./media/customize-speech-model/view-model.png" alt-text="Screenshot of how to review and update a model.":::

+

+You'll then see in the Details tab the name, description, language and status of the model plus the following properties:

+**Model ID**: Each model has a unique GUID, which is needed when using the API for operations that reference the model.

+**Created on**: The date the model was created.

+**Edit Details**: To edit a modelΓÇÖs name or description, when hovering over the model, click on the ellipsis and then select Edit details. You're then able to edit the modelΓÇÖs name and description.

+> [!div class="mx-imgBorder"]

+> :::image type="content" source="./media/customize-speech-model/create-model.png" alt-text="Screenshot of how to hover over the model.":::

+> [!Note]

+> Only the modelΓÇÖs name and description can be edited. If you want to make any changes to its datasets or add datasets, a new model must be created.

+**Delete**: To delete a model, when hovering over the dataset, click on the ellipsis and then select Delete.

+**Included datasets**: Click on the Included datasets tab to view the modelΓÇÖs datasets.

+> [!div class="mx-imgBorder"]

+> :::image type="content" source="./media/customize-speech-model/included-datasets.png" alt-text="Screenshot of how to delete the model.":::

+## How to use a custom language model when indexing a video

+A custom language model isn't used by default for indexing jobs and must be selected during the index upload process. To learn how to index a video, see Upload and index videos with Azure Video Indexer - Azure Video Indexer | Microsoft Learn.

+During the upload process, you can select the source language of the video. In the Video source language drop-down menu, you'll see your custom model among the language list. The naming of the model is the language of your Language model and the name that you gave it in parentheses. For example:

+> [!div class="mx-imgBorder"]

+> :::image type="content" source="./media/customize-speech-model/contoso-model.png" alt-text="Screenshot of indexing a video.":::

+Select the Upload option in the bottom of the page, and your new video will be indexed using your Language model. The same steps apply when you want to re-index a video with a custom model.

+## Next steps

+[Customize a speech model using the API](customize-speech-model-with-api.md)

+- **Language identification** - Whether the language can be automatically detected by Video Indexer when language identification is used for indexing. To learn more, see [Use Azure Video Indexer to auto identify spoken languages](language-identification-model.md) and the **Language Identification** section.

+- **Customization (language model)** - Whether the language can be used when customizing language models in Video Indexer. To learn more, see [Customize a language model in Azure Video Indexer](customize-language-model-overview.md).

+- **Pronunciation (language model)** - Whether the language can be used to create a pronunciation dataset as part of a custom speech model. To learn more, see [Customize a speech model with Azure Video Indexer](customize-speech-model-overview.md).

+ :::image type="content" source="media/language-support/website-translation.png" alt-text="Screenshot showing a menu with download, English and views as menu items. A tooltip is shown as mouseover on the English item and says Translation is set to English." lightbox="media/language-support/website-translation.png":::

+ :::image type="content" source="media/language-support/website-language.jpg" alt-text="Screenshot showing a menu with user settings show them all toggled to on." lightbox="media/language-support/website-language.jpg":::

+| **Language** | **Code** | **Supported<br/>source language** | **Language<br/>identification** | **Customization<br/>(language model)** | **Pronunciation<br>(language model)** | **Website<br/>Translation** | **Website<br/>Language** |

+|||||||||

+| Afrikaans | af-ZA | | | | | Γ£ö | |

+| Arabic (Israel) | ar-IL | Γ£ö | | Γ£ö | | | |

+| Arabic (Iraq) | ar-IQ | Γ£ö | Γ£ö | | | | |

+| Arabic (Jordan) | ar-JO | Γ£ö | Γ£ö | Γ£ö | | | |

+| Arabic (Kuwait) | ar-KW | Γ£ö | Γ£ö | Γ£ö | | | |

+| Arabic (Lebanon) | ar-LB | Γ£ö | | Γ£ö | | | |

+| Arabic (Oman) | ar-OM | Γ£ö | Γ£ö | Γ£ö | | | |

+| Arabic (Palestinian Authority) | ar-PS | Γ£ö | | Γ£ö | | | |

+| Arabic (Qatar) | ar-QA | Γ£ö | Γ£ö | Γ£ö | | | |

+| Arabic (Saudi Arabia) | ar-SA | Γ£ö | Γ£ö | Γ£ö | | | |

+| Arabic (United Arab Emirates) | ar-AE | Γ£ö | Γ£ö | Γ£ö | | | |

+| Arabic Egypt | ar-EG | Γ£ö | Γ£ö | Γ£ö | | Γ£ö | |

+| Arabic Modern Standard (Bahrain) | ar-BH | Γ£ö | Γ£ö | Γ£ö | | | |

+| Arabic Syrian Arab Republic | ar-SY | Γ£ö | Γ£ö | Γ£ö | | | |

+| Armenian | hy-AM | Γ£ö | | | | | |

+| Bangla | bn-BD | | | | | Γ£ö | |

+| Bosnian | bs-Latn | | | | | Γ£ö | |

+| Bulgarian | bg-BG | Γ£ö | Γ£ö | | | Γ£ö | |

+| Catalan | ca-ES | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | |

+| Chinese (Cantonese Traditional) | zh-HK | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | |

+| Chinese (Simplified) | zh-Hans | Γ£ö | Γ£ö | | | Γ£ö | Γ£ö |

+| Chinese (Simplified) | zh-CK | Γ£ö | Γ£ö | | | Γ£ö | Γ£ö |

+| Chinese (Traditional) | zh-Hant | | | | | Γ£ö | |

+| Croatian | hr-HR | Γ£ö | Γ£ö | | Γ£ö | Γ£ö | |

+| Czech | cs-CZ | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö |

+| Danish | da-DK | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | |

+| Dutch | nl-NL | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö |

+| English Australia | en-AU | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | |

+| English United Kingdom | en-GB | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | |

+| English United States | en-US | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö |

+| Estonian | et-EE | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | |

+| Fijian | en-FJ | | | | | Γ£ö | |

+| Filipino | fil-PH | | | | | Γ£ö | |

+| Finnish | fi-FI | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | |

+| French | fr-FR | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | |

+| French (Canada) | fr-CA | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö |

+| German | de-DE | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö |

+| Greek | el-GR | Γ£ö | Γ£ö | | | Γ£ö | |

+| Gujarati | gu-IN | Γ£ö | Γ£ö | | | Γ£ö | |

+| Haitian | fr-HT | | | | | Γ£ö | |

+| Hebrew | he-IL | Γ£ö | Γ£ö | Γ£ö | | Γ£ö | |

+| Hindi | hi-IN | Γ£ö | Γ£ö | Γ£ö | | Γ£ö | Γ£ö |

+| Hungarian | hu-HU | | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö |

+| Icelandic | is-IS | Γ£ö | | | | | |

+| Indonesian | id-ID | | | Γ£ö | Γ£ö | Γ£ö | |

+| Irish | ga-IE | Γ£ö | Γ£ö | Γ£ö | Γ£ö | | |

+| Italian | it-IT | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö |

+| Japanese | ja-JP | Γ£ö | Γ£ö | Γ£ö | | Γ£ö | Γ£ö |

+| Kannada | kn-IN | Γ£ö | Γ£ö | | | | |

+| Kiswahili | sw-KE | | | | | Γ£ö | |

+| Korean | ko-KR | Γ£ö | Γ£ö | Γ£ö | | Γ£ö | Γ£ö |

+| Latvian | lv-LV | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | |

+| Lithuanian | lt-LT | | | Γ£ö | Γ£ö | Γ£ö | |

+| Malagasy | mg-MG | | | | | Γ£ö | |

+| Malay | ms-MY | Γ£ö | | | | Γ£ö | |

+| Malayalam | ml-IN | Γ£ö | Γ£ö | | | | |

+| Maltese | mt-MT | | | | | Γ£ö | |

+| Norwegian | nb-NO | Γ£ö | Γ£ö | Γ£ö | | Γ£ö | |

+| Persian | fa-IR | Γ£ö | | Γ£ö | | Γ£ö | |

+| Polish | pl-PL | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö |

+| Portuguese | pt-BR | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö |

+| Portuguese (Portugal) | pt-PT | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | |

+| Romanian | ro-RO | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | |

+| Russian | ru-RU | Γ£ö | Γ£ö | Γ£ö | | Γ£ö | Γ£ö |

+| Samoan | en-WS | | | | | | |

+| Serbian (Cyrillic) | sr-Cyrl-RS | | | | | Γ£ö | |

+| Serbian (Latin) | sr-Latn-RS | | | | | Γ£ö | |

+| Slovak | sk-SK | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | |

+| Slovenian | sl-SI | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | |

+| Spanish | es-ES | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö |

+| Spanish (Mexico) | es-MX | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | |

+| Swedish | sv-SE | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö | Γ£ö |

+| Tamil | ta-IN | Γ£ö | Γ£ö | | | Γ£ö | |

+| Telugu | te-IN | Γ£ö | Γ£ö | | | | |

+| Thai | th-TH | Γ£ö | Γ£ö | Γ£ö | | Γ£ö | |

+| Tongan | to-TO | | | | | Γ£ö | |

+| Turkish | tr-TR | Γ£ö | Γ£ö | Γ£ö | | Γ£ö | Γ£ö |

+| Ukrainian | uk-UA | Γ£ö | Γ£ö | | | Γ£ö | |

+| Urdu | ur-PK | | | | | Γ£ö | |

+| Vietnamese | vi-VN | Γ£ö | Γ£ö | | | Γ£ö |

+## March 2023

+### Support for storage behind firewall

+It is good practice to lock storage accounts and disable public access to enhance or comply with enterprise security policy. Video Indexer can now access non-public accessible storage accounts using the [Azure Trusted Service](https://learn.microsoft.com/azure/storage/common/storage-network-security?tabs=azure-portal#trusted-access-based-on-a-managed-identity) exception using Managed Identities. You can read more how to set it up in our [how-to](storage-behind-firewall.md).

+### New custom speech and pronunciation training

+Azure Video Indexer has added a new custom speech model experience. The experience includes ability to use custom pronunciation datasets to improve recognition of mispronounced words, phrases, or names. The custom models can be used to improve the transcription quality of content with industry specific terminology. To learn more, see [Customize speech model overview](customize-speech-model-overview.md).

+### Observed people quality improvements

+Observed people now supports people who are sitting. This is in addition to existing support of people who are standing or walking. This improvement makes observed people model more versatile and suitable for a wider range of use cases. We have also improved the model re-identification and grouping algorithms by 50%. The model can now more accurately track and group people across multiple camera views.

+### Observed people indexing duration optimization

+We have optimized the memory usage of the observed people model, resulting in a 60% reduction in indexing duration when using the advanced video analysis preset. You can now process your video footage more efficiently and get results faster.

+|**Charge** | **Basic Audio Analysis** | **Standard Audio Analysis** | **Advanced Audio Analysis** | **Standard Video Analysis** | **Advanced Video Analysis** |

+| | | - | | | |

+| Per input minute | $0.0126 | $0.024 | $0.04 | $0.09 | $0.15 |

+> [!IMPORTANT]

+> When you lock your storage accounts without public access be aware that the client device you're using to download the video source file using the Video Indexer portal will be the source ip that the storage account will see and allow/deny depending on the network configuration of your storage account. For instance, if I'm accessing the Video Indexer portal from my home network and I want to download the video source file a sas url to the storage account is created, my device will initiate the request and as a consequence the storage account will see my home ip as source ip. If you did not add exception for this ip you will not be able to access the SAS url to the source video. Work with your network/storage administrator on a network strategy i.e. use your corporate network, VPN or Private Link.

+- Ensure the storage accounts that need to be backed up have cross-tenant replication enabled. You can check this by navigating to the storage account > Object replication > Advanced settings. Once here, ensure that the check-box is enabled.

+When you configure protection, Azure Backup allocates a destination storage account (Backup vault's storage account managed by Azure Backup) and enables object replication policy at container level on both destination and source storage account. When a backup job is triggered, the Azure Backup service creates a recovery point marker on the source storage account and polls the destination account for the recovery point marker replication. Once the replication point marker is present on the destination, a recovery point is created.

+- [Configure and manage Azure Blobs backup](blob-backup-configure-manage.md)

+ > * `205478c0-bd83-4e1b-a9d6-db63a3e1e1c8` is the service principal for `Microsoft.AzureFrontDoor-Cdn`.

+ > * The service principal name was changed from `Microsoft.Azure.Cdn` to `Microsoft.AzureFrontDoor-Cdn`.

+> [!IMPORTANT]

+> The Vision Studio experience is limited to 500 images. To use a larger image set, create your own search application using the APIs in this guide.

+1. In the request body, set `"annotationKind"` to either `"imageClassification"` or `"imageObjectDetection"`, depending on your project.

+'annotationKind':'imageClassification',

+A successful call to import a project results in an `Operation-Location` header being returned, which can be used to check the status of the import job. In many of our examples, we haven't needed to look at the response headers and thus haven't been displaying them. To retrieve the response headers our curl command uses `-i`. Without this additional parameter prior to the endpoint address, the response to this command would appear empty as if no response occurred.

+```

+ Title: Azure Communication Services BYOS overview

+description: Learn about the Azure Communication Services BYOS.

+# Bring your own storage (BYOS) overview

+Bring Your Own Storage (BYOS) for Call Recording allows you to specify an Azure blob storage account for storing call recording files. BYOS enables businesses to store their data in a way that meets their compliance requirements and business needs. For example, end-users could customize their own rules and access to the data, enabling them to store or delete content whenever they need it. BYOS provides a simple and straightforward solution that eliminates the need for developers to invest time and resources in downloading and exporting files.

+The same Azure Communication Services Call Recording APIs are used to export recordings to your Azure Blob Storage Container. While starting recording for a call, specify the container path where the recording needs to be exported. Upon recording completion, Azure Communication Services automatically fetches and uploads your recording to your storage.

+

+## Azure Managed Identities

+BYOS uses [Azure Managed Identities](../../../../active-directory/managed-identities-azure-resources/overview.md) to access user-owned resources securely. Azure Managed Identities provides an identity for the application to use when it needs to access Azure resources, eliminating the need for developers to manage credentials.

+## Known issues

+- Azure Communication Services will also store your files in a built-in storage for 48 hours even if the exporting with BYOS is successful.

+- Randomly, recording files are duplicated during the exporting process when using BYOS. Make sure you delete the duplicated file to avoid extra storage costs in your storage account.

+## Next steps

+For more information, see the following articles:

+- Learn more about BYOS, check out the [BYOS Quickstart](../../../quickstarts/call-automation/call-recording/bring-your-own-storage.md).

+- Learn more about Call recording, check out the [Call Recording Quickstart](../../../quickstarts/voice-video-calling/get-started-call-recording.md).

+- Learn more about [Call Automation](../../../quickstarts/call-automation/callflows-for-customer-interactions.md).

+| Canada | Toll-Free | General Availability | General Availability | General Availability | General Availability\* |

+| Canada | Local | - | - | General Availability | General Availability\* |

+| UK | Toll-Free | - | - | General Availability | General Availability\* |

+| UK | Local | - | - | General Availability | General Availability\* |

+| USA & Puerto Rico | Toll-Free | General Availability | General Availability | General Availability | General Availability\* |

+| USA & Puerto Rico | Local | - | - | General Availability | General Availability\* |

+| Canada | Toll-Free | General Availability | General Availability | General Availability | General Availability\* |

+| Canada | Local | - | - | General Availability | General Availability\* |

+| UK | Toll-Free | - | - | General Availability | General Availability\* |

+| UK | Local | - | - | General Availability | General Availability\* |

+| Germany | Toll-Free | - | - | Public Preview | Public Preview\* |

+|Toll-Free |USD 6.00/mo |

+|Toll-free |Starting at USD 0.0150/min | USD 0.1750/min |

+User may find Call ID via the action bar on the bottom of the call screen. See more [Troubleshooting guide](../../concepts/ui-library/ui-library-use-cases.md?&pivots=platform-mobile#troubleshooting-guide)

+ Title: Azure Communication Services Call Recording Bring Your Own Storage

+description: Private Preview quickstart for Bring your own storage

+zone_pivot_groups: acs-csharp-java

+# Call recording: Bring your own storage quickstart

+This quickstart gets you started with BYOS (Bring your own storage) for Call Recording. To start using BYOS, make sure you're familiar with the [Call Recording APIs](../../voice-video-calling/get-started-call-recording.md).

+## Pre-requisite: Setting up Managed Identity and RBAC role assignments

+### 1. Enable system assigned managed identity for Azure Communication Services

+

+1. Open your Azure Communication Services resource. Navigate to *Identity* on the left.

+2. System Assigned Managed Identity is disabled by default. Enable it and click of *Save*

+3. Once completed, you're able to see the Object principal ID of the newly created identity.

+

+4. Now that identity has been successfully created, click on *Azure role assignments* to start adding role assignments.

+### 2. Add role assignment

+1. Click on *"Add role assignment"*

+

+2. On the *"Add role assignment"* panel, select the following values

+ 1. Scope: **Storage**

+ 2. Subscription: **Choose your subscription**

+ 3. Resource: **Choose your storage account**

+ 4. Role: **Azure Communication Services needs *"Storage Blob Data Contributor"* to be able to write to your storage account.**

+

+

+3. Click on *"Save"*.

+4. Once completed, you see the newly added role assignment in the *"Azure role assignment"* window.

+

+## Start recording session with external storage specified

+Use the server call ID received during initiation of the call.

+### Notification on successful export

+Use an [Azure Event Grid](../../../../event-grid/overview.md) web hook, or other triggered action, to notify your services when the recorded media is ready and have been exported to the external storage location.

+Refer to this example of the event schema.

+```JSON

+{

+ "id": "string", // Unique guid for event

+ "topic": "string", // /subscriptions/{subscription-id}/resourceGroups/{group-name}/providers/Microsoft.Communication/communicationServices/{communication-services-resource-name}

+ "subject": "string", // /recording/call/{call-id}/serverCallId/{serverCallId}

+ "data": {

+ "storageType": "string", // acsstorage, blobstorage etc.

+ "recordingId": "string", // unique id for recording

+ "recordingStorageInfo": {

+ "recordingChunks": [

+ {

+ "documentId": "string", // Document id for for the recording chunk

+ "contentLocation": "string", //Azure Communication Services URL where the content is located

+ "metadataLocation": "string", // Azure Communication Services URL where the metadata for this chunk is located

+ "deleteLocation": "string", // Azure Communication Services URL to use to delete all content, including recording and metadata.

+ "index": "int", // Index providing ordering for this chunk in the entire recording

+ "endReason": "string", // Reason for chunk ending: "SessionEnded",ΓÇ»"ChunkMaximumSizeExceededΓÇ¥, etc.

+ }

+ ]

+ },

+ "recordingStartTime": "string", // ISO 8601 date time for the start of the recording

+ "recordingDurationMs": "int", // Duration of recording in milliseconds

+ "sessionEndReason": "string" // Reason for call ending: "CallEnded",ΓÇ»"InitiatorLeftΓÇ¥, etc.

+ },

+ "eventType": "string", // "Microsoft.Communication.RecordingFileStatusUpdated"

+ "dataVersion": "string", // "1.0"

+ "metadataVersion": "string", // "1"

+ "eventTime": "string" // ISO 8601 date time for when the event was created

+}

+```

+## Next steps

+For more information, see the following articles:

+- Download our [Java](https://github.com/Azure-Samples/communication-services-java-quickstarts/tree/main/ServerRecording) and [.NET](https://github.com/Azure-Samples/communication-services-dotnet-quickstarts/tree/main/ServerRecording) call recording sample apps

+- Learn more about [Call Recording](../../../concepts/voice-video-calling/call-recording.md)

+- Learn more about [Call Automation](../../../concepts/call-automation/call-automation.md)

+Use the following script to retrieve a token from the local endpoint by specifying a resource URI of an Azure service. Replace the placeholder with the resource URI to obtain the token.

+Obtain the token endpoint URL from the `IDENTITY_ENDPOINT` environment variable. `x-identity-header` contains the GUID that is stored in the `IDENTITY_HEADER` environment variable.

+x-identity-header: 853b9a84-5bfa-4b22-a3f3-0b9a43d9ad8a

+- `IDENTITY_ENDPOINT` - local URL from which your container app can request tokens.

+- `IDENTITY_HEADER` - a header used to help mitigate server-side request forgery (SSRF) attacks. The value is rotated by the platform.

+> [!NOTE]

+> If you change your database account from First Party to System or User Assigned Identy, and enable Azure Synapse Link in your database account, you won't be able to return to First Party identity since you can't disable Synapse Link from your database account.

+ --capabilities EnableMongo DisableRateLimitingResponses

+

+ > [!IMPORTANT]

+ > The list of capabilities must always specify all capabilities you wish to enable, inclusively. This includes capabilities already enabled for the account. In this example, the `EnableMongo` capability was already enabled, so both the `EnableMongo` and `DisableRateLimitingResponses` capabilities must be specified.

+ Title: LINQ to SQL translation

+# LINQ to SQL translation in Azure Cosmos DB for NoSQL

+The Azure Cosmos DB query provider performs a best effort mapping from a LINQ query into an Azure Cosmos DB SQL query. If you want to get the SQL query that is translated from LINQ, use the `ToString()` method on the generated `IQueryable` object. The following description assumes a basic familiarity with [LINQ](/dotnet/csharp/programming-guide/concepts/linq/introduction-to-linq-queries). In addition to LINQ, Azure Cosmos DB also supports [Entity Framework Core](/ef/core/providers/cosmos/?tabs=dotnet-core-cli), which works with API for NoSQL.

+> We recommend using the latest [.NET SDK (`Microsoft.Azure.Cosmos`) version](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/)

+The query provider type system supports only the JSON primitive types: `numeric`, `Boolean`, `string`, and `null`.

+ ```csharp

+ ```

+ ```csharp

+ int n = 1;

+ family.children[n].grade;

+ ```

+ ```csharp

+ ```

+ ```csharp

+ mother.familyName.StringEquals("Wakefield");

+ ```

+ ```csharp

+ string s = "Rob";

+ string e = "in";

+ string c = "obi";

+

+ child.givenName.StartsWith(s);

+ child.givenName.EndsWith(e);

+ child.givenName.Contains(c);

+ ```

+ ```csharp

+ ```

+using FeedIterator<Book> setIterator = container.GetItemLinqQueryable<Book>()

+ .Where(b => b.Title == "War and Peace")

+ .ToFeedIterator<Book>());

+//Asynchronous query execution

+while (setIterator.HasMoreResults)

+{

+ foreach(var item in await setIterator.ReadNextAsync()){

+ {

+ Console.WriteLine(item.cost);

+ }

+}

+## Supported LINQ operators

+- **CompareTo**: Translates to range comparisons. This operator is commonly used for strings, since they're not comparable in .NET.

+ ```csharp

+ input.Select(family => family.parents[0].familyName);

+ ```

+ ```sql

+ SELECT VALUE f.parents[0].familyName

+ FROM Families f

+ ```csharp

+ input.Select(family => family.children[0].grade + c); // c is an int variable

+ ```

+ ```sql

+ SELECT VALUE f.children[0].grade + c

+ FROM Families f

+ ```

+ ```csharp

+ ```

+ ```sql

+ SELECT VALUE {

+ "name":f.children[0].familyName,

+ "grade": f.children[0].grade + 3

+ }

+ FROM Families f

+ ```

+ ```csharp

+ input.SelectMany(family => family.children);

+ ```

+ ```sql

+ SELECT VALUE child

+ FROM child IN Families.children

+ ```

+ ```csharp

+ input.Where(family=> family.parents[0].familyName == "Wakefield");

+ ```

+ ```sql

+ SELECT *

+ FROM Families f

+ WHERE f.parents[0].familyName = "Wakefield"

+ ```

+ ```csharp

+ input.Where(

+ family => family.parents[0].familyName == "Wakefield" &&

+ family.children[0].grade < 3);

+ ```

+ ```sql

+ SELECT *

+ FROM Families f

+ WHERE f.parents[0].familyName = "Wakefield"

+ AND f.children[0].grade < 3

+ ```

+ ```csharp

+ input.Select(family => family.parents[0])

+ .Where(parent => parent.familyName == "Wakefield");

+ ```

+ ```sql

+ SELECT *

+ FROM Families f

+ WHERE f.parents[0].familyName = "Wakefield"

+ ```

+ ```csharp

+ input.Where(family => family.children[0].grade > 3)

+ .Select(family => family.parents[0].familyName);

+ ```

+ ```sql

+ SELECT VALUE f.parents[0].familyName

+ FROM Families f

+ WHERE f.children[0].grade > 3

+ ```

+ ```csharp

+ input.Select(family => new { grade=family.children[0].grade}).

+ Where(anon=> anon.grade < 3);

+ ```

+ ```sql

+ SELECT *

+ FROM Families f

+ WHERE ({grade: f.children[0].grade}.grade > 3)

+ ```

+ ```csharp

+ input.SelectMany(family => family.parents)

+ .Where(parent => parents.familyName == "Wakefield");

+ ```

+ ```sql

+ SELECT *

+ FROM p IN Families.parents

+ WHERE p.familyName = "Wakefield"

+ ```

+ ```csharp

+ input.SelectMany(family=>

+ family.parents.Select(p => p.familyName));

+ ```

+ ```sql

+ SELECT VALUE p.familyName

+ FROM Families f

+ JOIN p IN f.parents

+ ```

+ ```csharp

+ input.SelectMany(family =>

+ family.children.Where(child => child.familyName == "Jeff"));

+ ```

+ ```sql

+ SELECT *

+ FROM Families f

+ JOIN c IN f.children

+ WHERE c.familyName = "Jeff"

+ ```

+ ```csharp

+ input.SelectMany(family => family.children.Where(

+ child => child.familyName == family.parents[0].familyName));

+ ```

+ ```sql

+ SELECT *

+ FROM Families f

+ JOIN c IN f.children

+ WHERE c.familyName = f.parents[0].familyName

+ ```

+- [Azure Cosmos DB for NoSQL .NET SDK developer guide](../how-to-dotnet-get-started.md)

+ Title: |

+ Tutorial: Add a transformation for workspace data

+description: In this tutorial, add a custom transformation to data flowing through Azure Monitor Logs from Azure Cosmos DB by using the Azure portal.

+# Tutorial: Add a transformation for Azure Cosmos DB workspace data by using the Azure portal

+This tutorial walks you through configuration of a sample [transformation in a workspace data collection rule (DCR)](../azure-monitor/essentials/data-collection-transformations.md) by using the Azure portal.

+> [!NOTE]

+> To help improve costs for enabling Log Analytics, we now support adding Data Collection Rules and transformations on your Log Analytics resources to filter out columns, reduce number of results returned, and create new columns before the data is sent to the destination.

+Workspace transformations are stored together in a single [DCR](../azure-monitor/essentials/data-collection-rule-overview.md) for the workspace, which is called the workspace DCR. Each transformation is associated with a particular table. The transformation is applied to all data sent to this table from any workflow not using a DCR.

+> [!NOTE]

+> This tutorial uses the Azure portal to configure a workspace transformation. For the same tutorial using Azure Resource Manager templates and REST API, see [Tutorial: Add transformation in workspace data collection rule to Azure Monitor using resource manager templates](../azure-monitor/logs/tutorial-workspace-transformations-api.md).

+In this tutorial, you learn how to:

+> [!div class="checklist"]

+>

+> - Configure a [workspace transformation](../azure-monitor/essentials/data-collection-transformations.md#workspace-transformation-dcr) for a table in a Log Analytics workspace.

+> - Write a log query for a workspace transformation.

+>

+## Prerequisites

+To complete this tutorial, you need:

+- A Log Analytics workspace where you have at least [contributor rights](../azure-monitor/logs/manage-access.md#azure-rbac).

+- [Permissions to create DCR objects](../azure-monitor/essentials/data-collection-rule-overview.md#permissions) in the workspace.

+- A table that already has some data.

+- The table can't be linked to the [workspace transformation DCR](../azure-monitor/essentials/data-collection-transformations.md#workspace-transformation-dcr).

+## Overview of the tutorial

+In this tutorial, you reduce the storage requirement for the `CDBDataPlaneRequests` table by filtering out certain records. You also remove the contents of a column while parsing the column data to store a piece of data in a custom column. The [CDBDataPlaneRequests table](monitor-resource-logs.md) is created when you enable [log analytics](monitor-resource-logs.md) in a workspace.

+This tutorial uses the Azure portal, which provides a wizard to walk you through the process of creating an ingestion-time transformation. After you finish the steps, you'll see that the wizard:

+- Updates the table schema with any other columns from the query.

+- Creates a `WorkspaceTransformation` DCR and links it to the workspace if a default DCR isn't already linked to the workspace.

+- Creates an ingestion-time transformation and adds it to the DCR.

+## Enable query audit logs

+You need to enable [log analytics](monitor-resource-logs.md) for your workspace to create the `CDBDataPlaneRequests` table that you're working with. This step isn't required for all ingestion time transformations. It's just to generate the sample data that we're working with.

+## Add a transformation to the table

+Now that the table's created, you can create the transformation for it.

+1. On the **Log Analytics workspaces** menu in the Azure portal, select **Tables**. Locate the `CDBDataPlaneRequests` table and select **Create transformation**.

+ :::image type="content" source="media/tutorial-log-transformation/create-transformation.png" lightbox="media/tutorial-log-transformation/create-transformation.png" alt-text="Screenshot that shows creating a new transformation.":::

+1. Because this transformation is the first one in the workspace, you must create a [workspace transformation DCR](../azure-monitor/essentials/data-collection-transformations.md#workspace-transformation-dcr). If you create transformations for other tables in the same workspace, they're stored in this same DCR. Select **Create a new data collection rule**. The **Subscription** and **Resource group** are already populated for the workspace. Enter a name for the DCR and select **Done**.

+1. Select **Next** to view sample data from the table. As you define the transformation, the result is applied to the sample data. For this reason, you can evaluate the results before you apply it to actual data. Select **Transformation editor** to define the transformation.

+ :::image type="content" source="media/tutorial-log-transformation/transformation-query-results.png" lightbox="media/tutorial-log-transformation/transformation-query-results.png" alt-text="Screenshot that shows sample data from the log table.":::

+1. In the transformation editor, you can see the transformation that is applied to the data prior to its ingestion into the table. A virtual table named `source` represents the incoming data, which has the same set of columns as the destination table itself. The transformation initially contains a simple query that returns the `source` table with no changes.

+1. Modify the query to the following example:

+ ``` kusto

+ source

+ | where StatusCode != 200 // searching for requests that are not successful

+ | project-away Type, TenantId

+ ```

+ The modification makes the following changes:

+ - Rows related to querying the `CDBDataPlaneRequests` table itself were dropped to save space because these log entries aren't useful.

+ - Data from the `TenantId` and `Type` columns were removed to save space.

+ - Transformations also support adding columns using the `extend` operator in your query.

+ > [!Note]

+ > Using the Azure portal, the output of the transformation will initiate changes to the table schema if required. Columns will be added to match the transformation output if they don't already exist. Make sure that your output doesn't contain any columns that you don't want added to the table. If the output doesn't include columns that are already in the table, those columns won't be removed, but data won't be added.

+ >

+ > Any custom columns added to a built-in table must end in `_CF`. Columns added to a custom table don't need to have this suffix. A custom table has a name that ends in `_CL`.

+1. Copy the query into the transformation editor and select **Run** to view results from the sample data. You can verify that the new `Workspace_CF` column is in the query.

+ :::image type="content" source="media/tutorial-log-transformation/select-transformation-editor.png" lightbox="media/tutorial-log-transformation/select-transformation-editor.png" alt-text="Screenshot that shows the transformation editor.":::

+1. Select **Apply** to save the transformation and then select **Next** to review the configuration. Select **Create** to update the DCR with the new transformation.

+ :::image type="content" source="media/tutorial-log-transformation/transformation-configuration-created.png" lightbox="media/tutorial-log-transformation/transformation-configuration-created.png" alt-text="Screenshot that shows saving the transformation.":::

+## Test the transformation

+Allow about 30 minutes for the transformation to take effect and then test it by running a query against the table. This transformation affects only data sent to the table after the transformation was applied.

+For this tutorial, run some sample queries to send data to the `CDBDataPlaneRequests` table. Include some queries against `CDBDataPlaneRequests` so that you can verify that the transformation filters these records.

+## Troubleshooting

+This section describes different error conditions you might receive and how to correct them.

+### IntelliSense in Log Analytics not recognizing new columns in the table

+The cache that drives IntelliSense might take up to 24 hours to update.

+### Transformation on a dynamic column isn't working

+A known issue currently affects dynamic columns. A temporary workaround is to explicitly parse dynamic column data by using `parse_json()` prior to performing any operations against them.

+## Next steps

+> [!div class="nextstepaction"]

+> [Data collection transformations](../azure-monitor/essentials/data-collection-transformations.md)

+ - *If you have difficulty finding a new subscription* after you create it, you might need to change the global subscription filter. For more information about changing the global subscription filter, see [Can't view subscription](create-subscription.md#cant-view-subscription).

+>[!TIP]

+>If your data factory instance is Git-enabled, a linked service without key authentication will not be immediately published, which means you cannot save the integration runtime that depends on the linked service in your feature-branch. Authenticating with account key or SAS URI will immediately publish the linked service.

+ Title: 'View Azure DDoS Protection logs in Log Analytics workspace'

+description: Learn how to view DDoS protection diagnostic logs in Log Analytics workspace.

+# View Azure DDoS Protection logs in Log Analytics workspace

+In this guide, you'll learn how to view Azure DDoS Protection diagnostic logs, including notifications, mitigation reports and mitigation flow logs.

+## Prerequisites

+- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+- [DDoS Network Protection](manage-ddos-protection.md) must be enabled on a virtual network or [DDoS IP Protection](manage-ddos-protection-powershell-ip.md) must be enabled on a public IP address.

+- Configure DDoS Protection diagnostic logs. To learn more, see [Configure diagnostic logs](diagnostic-logging.md).

+- Simulate an attack using one of our simulation partners. To learn more, see [Test with simulation partners](test-through-simulations.md).

+### View in log analytics workspace

+1. Sign in to the [Azure portal](https://portal.azure.com/).

+1. In the search box at the top of the portal, enter **Log Analytics workspace**. Select **Log Analytics workspace** in the search results.

+1. Under the **Log Analytics workspaces** blade, select your workspace.

+1. On the left-side tab, select **Logs**. Here you'll see the query explorer. Exit out the *Queries* pane to utilize the *Logs* page.

+ :::image type="content" source="./media/ddos-view-diagnostic-logs/ddos-select-logs-in-workspace.png" alt-text="Screenshot of viewing a log analytics workspace.":::

+1. In the *Logs* page, type in your query then hit *Run* to view results.

+ :::image type="content" source="./media/ddos-view-diagnostic-logs/ddos-notification-logs.png" alt-text="Screenshot of viewing DDoS Protection notification logs in log analytics workspace.":::

+## Example log queries

+### DDoS Protection Notifications

+Notifications will notify you anytime a public IP resource is under attack, and when attack mitigation is over.

+```kusto

+ AzureDiagnostics

+ | where Category == "DDoSProtectionNotifications"

+```

+The following table lists the field names and descriptions:

+| Field name | Description |

+| | |

+| **TimeGenerated** | The date and time in UTC when the notification was created. |

+| **ResourceId** | The resource ID of your public IP address. |

+| **Category** | For notifications, this will be `DDoSProtectionNotifications`.|

+| **ResourceGroup** | The resource group that contains your public IP address and virtual network. |

+| **SubscriptionId** | Your DDoS protection plan subscription ID. |

+| **Resource** | The name of your public IP address. |

+| **ResourceType** | This will always be `PUBLICIPADDRESS`. |

+| **OperationName** | For notifications, this will be `DDoSProtectionNotifications`. |

+| **Message** | Details of the attack. |

+| **Type** | Type of notification. Possible values include `MitigationStarted`. `MitigationStopped`. |

+| **PublicIpAddress** | Your public IP address. |

+### DDoS Mitigation FlowLogs

+Attack mitigation flow logs allow you to review the dropped traffic, forwarded traffic and other interesting data-points during an active DDoS attack in near-real time. You can ingest the constant stream of this data into Microsoft Sentinel or to your third-party SIEM systems via event hub for near-real time monitoring, take potential actions and address the need of your defense operations.

+```kusto

+ AzureDiagnostics

+ | where Category == "DDoSMitigationFlowLogs"

+```

+| Field name | Description |

+| | |

+| **TimeGenerated** | The date and time in UTC when the flow log was created. |

+| **ResourceId** | The resource ID of your public IP address. |

+| **Category** | For flow logs, this will be `DDoSMitigationFlowLogs`.|

+| **ResourceGroup** | The resource group that contains your public IP address and virtual network. |

+| **SubscriptionId** | Your DDoS protection plan subscription ID. |

+| **Resource** | The name of your public IP address. |

+| **ResourceType** | This will always be `PUBLICIPADDRESS`. |

+| **OperationName** | For flow logs, this will be `DDoSMitigationFlowLogs`. |

+| **Message** | Details of the attack. |

+| **SourcePublicIpAddress** | The public IP address of the client generating traffic to your public IP address. |

+| **SourcePort** | Port number ranging from 0 to 65535. |

+| **DestPublicIpAddress** | Your public IP address. |

+| **DestPort** | Port number ranging from 0 to 65535. |

+| **Protocol** | Type of protocol. Possible values include `tcp`, `udp`, `other`.|

+### DDoS Mitigation FlowLogs

+Attack mitigation reports use the Netflow protocol data, which is aggregated to provide detailed information about the attack on your resource. Anytime a public IP resource is under attack, the report generation will start as soon as the mitigation starts. There will be an incremental report generated every 5 mins and a post-mitigation report for the whole mitigation period. This is to ensure that in an event the DDoS attack continues for a longer duration of time, you'll be able to view the most current snapshot of mitigation report every 5 minutes and a complete summary once the attack mitigation is over.

+```kusto

+ AzureDiagnostics

+ | where Category == "DDoSMitigationReports"

+```

+| Field name | Description |

+| | |

+| **TimeGenerated** | The date and time in UTC when the notification was created. |

+| **ResourceId** | The resource ID of your public IP address. |

+| **Category** | For notifications, this will be `DDoSProtectionNotifications`.|

+| **ResourceGroup** | The resource group that contains your public IP address and virtual network. |

+| **SubscriptionId** | Your DDoS protection plan subscription ID. |

+| **Resource** | The name of your public IP address. |

+| **ResourceType** | This will always be `PUBLICIPADDRESS`. |

+| **OperationName** | For notifications, this will be `DDoSProtectionNotifications`. |

+| **Message** | Details of the attack. |

+| **Type** | Type of notification. Possible values include `MitigationStarted`. `MitigationStopped`. |

+| **PublicIpAddress** | Your public IP address. |

+## Next steps

+*[Engage DDoS Rapid Response](ddos-rapid-response.md)

+For more information on log schemas, see [View diagnostic logs](ddos-view-diagnostic-logs.md#example-log-queries).

+The following section outlines the metrics of the Azure DDoS Protection service.

+* [Configure DDoS Alerts](alerts.md)

+* [View alerts in Microsoft Defender for Cloud](ddos-view-alerts-defender-for-cloud.md)

+* [Test with simulation partners](test-through-simulations.md)

+- [Some regulatory compliance standards are now available in government clouds](#some-regulatory-compliance-standards-are-now-available-in-government-clouds)

+### Some regulatory compliance standards are now available in government clouds

+We are announcing that the following regulatory standards are being updated with latest version and are available for customers in Azure Government and Azure China 21Vianet.

+**Azure Government**:

+- [PCI DSS v4](/azure/compliance/offerings/offering-pci-dss)

+- [SOC 2 Type 2](/azure/compliance/offerings/offering-soc-2)

+- [ISO 27001:2013](/azure/compliance/offerings/offering-iso-27001)

+**Azure China 21Vianet**:

+- [SOC 2 Type 2](/azure/compliance/offerings/offering-soc-2)

+- [ISO 27001:2013](/azure/compliance/offerings/offering-iso-27001)

+Learn how to [Customize the set of standards in your regulatory compliance dashboard](update-regulatory-compliance-packages.md).

+| [Three alerts in the Defender for Azure Resource Manager plan will be deprecated](#three-alerts-in-the-defender-for-resource-manager-plan-will-be-deprecated) | March 2023 |

+| [Deprecation of legacy compliance standards across cloud environments](#deprecation-of-legacy-compliance-standards-across-cloud-environments) | April 2023 |

+| [Multiple changes to identity recommendations](#multiple-changes-to-identity-recommendations) | April 2023 |

+### Deprecation of legacy compliance standards across cloud environments

+**Estimated date for change: April 2023**

+We are announcing the full deprecation of support of [`PCI DSS`](/azure/compliance/offerings/offering-pci-dss) standard/initiative in Azure China 21Vianet.

+Legacy PCI DSS v3.2.1 and legacy SOC TSP are set to be fully deprecated and replaced by [SOC 2 Type 2](/azure/compliance/offerings/offering-soc-2) initiative and [PCI DSS v4](/azure/compliance/offerings/offering-pci-dss) initiative.

+Learn how to [Customize the set of standards in your regulatory compliance dashboard](update-regulatory-compliance-packages.md).

+### Deprecation of legacy compliance standards across cloud environments

+**Estimated date for change: April 2023**

+We are announcing the full deprecation of support of [`PCI DSS`](/azure/compliance/offerings/offering-pci-dss) standard/initiative in Azure China 21Vianet.

+Legacy PCI DSS v3.2.1 and legacy SOC TSP are set to be fully deprecated and replaced by [SOC 2 Type 2](/azure/compliance/offerings/offering-soc-2) initiative and [`PCI DSS v4`](/azure/compliance/offerings/offering-pci-dss) initiative.

+Learn how to [Customize the set of standards in your regulatory compliance dashboard](update-regulatory-compliance-packages.md).

+Microsoft tracks the regulatory standards themselves and automatically improves its coverage in some of the packages over time. When Microsoft releases new content for the initiative, it appears automatically in your dashboard as new policies mapped to controls in the standard.

+**Available regulatory standards**:

+- PCI-DSS v3.2.1 **(deprecated)**

+- SOC 2 Type 2

+**Available AWS regulatory standards**:

+**GCP**: When users onboard, every GCP project has the "GCP Default" standard assigned.

+**Available GCP regulatory standards**:

+1. Select **Yes**.

+ The trial for OT networks is free of charge for the first 30 days. Any usage beyond 30 days incurs a charge based on the monthly plan for 1,000 devices. For more information, see [the Microsoft Defender for IoT pricing page](https://azure.microsoft.com/pricing/details/iot-defender/).

+[Configure Windows Endpoint monitoring](configure-windows-endpoint-monitoring.md)

+[Configure DNS servers for reverse lookup resolution for OT monitoring](configure-reverse-dns-lookup.md)

+

+ Microsoft Defender for IoT provides a 30-day free trial for the first 1,000 committed devices for evaluation purposes. Any usage beyond 30 days incurs a charge based on the monthly plan for 1,000 devices. For more information, see [the Microsoft Defender for IoT pricing page](https://azure.microsoft.com/pricing/details/iot-defender/).

+ Microsoft Defender for IoT provides a 30-day free trial for the first 1,000 committed devices for evaluation purposes. Any usage beyond 30 days incurs a charge based on the monthly plan for 1,000 devices. For more information, see [the Microsoft Defender for IoT pricing page](https://azure.microsoft.com/pricing/details/iot-defender/).

+## Compliance scope

+Defender for IoT cloud services (formerly *Azure Defender for IoT* or *Azure Security for IoT*) are based on Microsoft AzureΓÇÖs infrastructure, which meets demanding US government and international compliance requirements that produce formal authorizations.

+

+Specifically:

+- Defender for IoT is in scope for the following provisional authorizations in Azure and Azure Government: [FedRAMP High](/azure/compliance/offerings/offering-fedramp) and [DoD IL2](/azure/compliance/offerings/offering-dod-il2). Moreover, Defender for IoT maintains extra [DoD IL4](/azure/compliance/offerings/offering-dod-il4) and [DoD IL5](/azure/compliance/offerings/offering-dod-il5) provisional authorizations in Azure Government. For more information, see [Azure and other Microsoft cloud services compliance scope](/azure/azure-government/compliance/azure-services-in-fedramp-auditscope#azure-public-services-by-audit-scope).

+- Defender for IoT is committed to developing technology that empowers everyone, including people with disabilities, and helps customers address global accessibility requirements. For more information, search for *Azure Security for IoT* in [Accessibility Conformance Reports | Microsoft Accessibility](https://www.microsoft.com/accessibility/conformance-reports?rtc=1).

+- Defender for IoT helps customers meet their compliance obligations across regulated industries and markets worldwide. For more information, see [Azure and other Microsoft cloud services compliance offerings](/azure/compliance/offerings/).

+You'll need to set two environment variables in your function app. One is your [Azure Maps primary subscription key](../azure-maps/quick-demo-map-app.md#get-the-subscription-key-for-your-account), and one is your [Azure Maps stateset ID](../azure-maps/tutorial-creator-feature-stateset.md).

+You can also complete a basic walkthrough in the blog post [Simplify building automated workflows and apps powered by Azure Digital Twins](https://techcommunity.microsoft.com/t5/internet-of-things-blog/simplify-building-automated-workflows-and-apps-powered-by-azure/ba-p/3763051). For more information about the connector, including a complete list of the connector's actions and their parameters, see the [Azure Digital Twins connector reference documentation](/connectors/azuredigitaltwins).

+| SQL Server | Azure SQL DB | [MAP Toolkit](/previous-versions//bb977556(v=technet.10))<br/>[Azure Migrate](https://azure.microsoft.com/services/azure-migrate/)<br/>[Cloudamize*](https://www.cloudamize.com/) | [Azure SQL Migration extension](./migration-using-azure-data-studio.md)<br/> [DMA](/sql/dma/dma-overview)<br/>[Cloud Atlas*](https://www.unifycloud.com/cloud-migration-tool/)<br/>[Cloudamize*](https://www.cloudamize.com/) | [TCO Calculator](https://azure.microsoft.com/pricing/tco/calculator/) |

+ SQL Server | Azure SQL MI | [MAP Toolkit](/previous-versions//bb977556(v=technet.10))<br/>[Azure Migrate](https://azure.microsoft.com/services/azure-migrate/)<br/>[Cloudamize*](https://www.cloudamize.com/) | [Azure SQL Migration extension](./migration-using-azure-data-studio.md)<br/> [DMA](/sql/dma/dma-overview)<br/>[Cloud Atlas*](https://www.unifycloud.com/cloud-migration-tool/)<br/>[Cloudamize*](https://www.cloudamize.com/) | [TCO Calculator](https://azure.microsoft.com/pricing/tco/calculator/) |

+| SQL Server | Azure SQL VM | [MAP Toolkit](/previous-versions//bb977556(v=technet.10))<br/>[Azure Migrate](https://azure.microsoft.com/services/azure-migrate/)<br/>[Cloudamize*](https://www.cloudamize.com/) | [Azure SQL Migration extension](./migration-using-azure-data-studio.md)<br/> [DMA](/sql/dma/dma-overview)<br/>[Cloud Atlas*](https://www.unifycloud.com/cloud-migration-tool/)<br/>[Cloudamize*](https://www.cloudamize.com/) | [TCO Calculator](https://azure.microsoft.com/pricing/tco/calculator/) |

+| Amazon RDS for SQL Server | Azure SQL DB, MI, VM | | [Azure SQL Migration extension](./migration-using-azure-data-studio.md)<br/> [DMA](/sql/dma/dma-overview) | [TCO Calculator](https://azure.microsoft.com/pricing/tco/calculator/) |

+| Amazon RDS for MySQL | Azure DB for MySQL | | | [TCO Calculator](https://azure.microsoft.com/pricing/tco/calculator/) |

+| Amazon RDS for PostgreSQL | Azure DB for PostgreSQL -<br/>Single server | | | [TCO Calculator](https://azure.microsoft.com/pricing/tco/calculator/) |

+| SQL Server | Azure SQL MI | [DAMT](https://marketplace.visualstudio.com/items?itemName=ms-databasemigration.data-access-migration-toolkit) / [DMA](/sql/dm)<br/>[DMA](/sql/dma/dma-overview)<br/>[Cloud Atlas*](https://www.unifycloud.com/cloud-migration-tool/)<br/>[Cloudamize*](https://www.cloudamize.com/) | [DEA](https://www.microsoft.com/download/details.aspx?id=54090)<br/>[Cloudamize*](https://www.cloudamize.com/) |

+| Amazon RDS for SQL | Azure SQL DB, MI, VM | [DAMT](https://marketplace.visualstudio.com/items?itemName=ms-databasemigration.data-access-migration-toolkit) / [DMA](/sql/dm)<br/>[DMA](/sql/dma/dma-overview) | [DEA](https://www.microsoft.com/download/details.aspx?id=54090) |

+| Amazon RDS for MySQL | Azure DB for MySQL | | | |

+| Amazon RDS for PostgreSQL | Azure DB for PostgreSQL -<br/>Single server | | | |

+| SQL Server | Azure SQL DB | [SQL Database Projects extension](/sql/azure-data-studio/extensions/sql-database-project-extension)<br/>[DMA](/sql/dm)<br/>[DMA](/sql/dma/dma-overview)<br/>[Cloudamize*](https://www.cloudamize.com/) | [Cloudamize*](https://www.cloudamize.com/)<br/>[Attunity*](https://www.attunity.com/products/replicate/)<br/>[Striim*](https://www.striim.com/partners/striim-for-microsoft-azure/) |

+| SQL Server | Azure SQL MI | [Azure SQL Migration extension](./migration-using-azure-data-studio.md)<br/>[Cloudamize*](https://www.cloudamize.com/) | [Azure SQL Migration extension](./migration-using-azure-data-studio.md)<br/>[Cloudamize*](https://www.cloudamize.com/) | [Azure SQL Migration extension](./migration-using-azure-data-studio.md)<br/>[Cloudamize*](https://www.cloudamize.com/)<br/>[Attunity*](https://www.attunity.com/products/replicate/)<br/>[Striim*](https://www.striim.com/partners/striim-for-microsoft-azure/) |

+| SQL Server | Azure SQL VM | [Azure SQL Migration extension](./migration-using-azure-data-studio.md)<br/>[DMA](/sql/dm)<br/>[Cloudamize*](https://www.cloudamize.com/)<br/>[Attunity*](https://www.attunity.com/products/replicate/)<br/>[Striim*](https://www.striim.com/partners/striim-for-microsoft-azure/) |

+| Amazon RDS for SQL Server| Azure SQL DB | [SQL Database Projects extension](/sql/azure-data-studio/extensions/sql-database-project-extension)<br/>[DMA](/sql/dm)<br/>[DMA](/sql/dma/dma-overview)| [Attunity*](https://www.attunity.com/products/replicate/)<br/>[Striim*](https://www.striim.com/partners/striim-for-microsoft-azure/) |

+| Amazon RDS for SQL | Azure SQL MI |[Azure SQL Migration extension](./migration-using-azure-data-studio.md) | [Azure SQL Migration extension](./migration-using-azure-data-studio.md) | [Azure SQL Migration extension](./migration-using-azure-data-studio.md)<br/>[Attunity*](https://www.attunity.com/products/replicate/)<br/>[Striim*](https://www.striim.com/partners/striim-for-microsoft-azure/) |

+| Amazon RDS for SQL Server | Azure SQL VM | [Azure SQL Migration extension](./migration-using-azure-data-studio.md)<br/>[DMA](/sql/dm)<br/>[Attunity*](https://www.attunity.com/products/replicate/)<br/>[Striim*](https://www.striim.com/partners/striim-for-microsoft-azure/) |

+| Oracle | Azure SQL DB, MI, VM | [SSMA](/sql/ssma/sql-server-migration-assistant)<br/>[SharePlex*](https://www.quest.com/products/shareplex/)<br/>[Ispirer*](https://www.ispirer.com/blog/migration-to-the-microsoft-technology-stack) | [SSMA](/sql/ssma/sql-server-migration-assistant)<br/>[SharePlex*](https://www.quest.com/products/shareplex/)<br/>[Ispirer*](https://www.ispirer.com/blog/migration-to-the-microsoft-technology-stack) | [SharePlex*](https://www.quest.com/products/shareplex/)<br/>[Attunity*](https://www.attunity.com/products/replicate/)<br/>[Striim*](https://www.striim.com/partners/striim-for-microsoft-azure/) |

+| Oracle | Azure Synapse Analytics | [SSMA](/sql/ssma/sql-server-migration-assistant)<br/>[Ispirer*](https://www.ispirer.com/blog/migration-to-the-microsoft-technology-stack) | [SSMA](/sql/ssma/sql-server-migration-assistant)<br/>[Ispirer*](https://www.ispirer.com/blog/migration-to-the-microsoft-technology-stack) | [SharePlex*](https://www.quest.com/products/shareplex/)<br/>[Attunity*](https://www.attunity.com/products/replicate/)<br/>[Striim*](https://www.striim.com/partners/striim-for-microsoft-azure/) |

+| Oracle | Azure DB for PostgreSQL -<br/>Single server | [Ora2Pg*](http://ora2pg.darold.net/start.html)<br/>[Ispirer*](https://www.ispirer.com/blog/migration-to-the-microsoft-technology-stack) | [Ora2Pg*](http://ora2pg.darold.net/start.html)<br/>[Ispirer*](https://www.ispirer.com/blog/migration-to-the-microsoft-technology-stack) | <br/>[Striim*](https://www.striim.com/partners/striim-for-microsoft-azure/) |

+| Oracle | Azure DB for PostgreSQL -<br/>Flexible server | [Ora2Pg*](http://ora2pg.darold.net/start.html)<br/>[Ispirer*](https://www.ispirer.com/blog/migration-to-the-microsoft-technology-stack) | [Ora2Pg*](http://ora2pg.darold.net/start.html)<br/>[Ispirer*](https://www.ispirer.com/blog/migration-to-the-microsoft-technology-stack) | <br/>[Striim*](https://www.striim.com/partners/striim-for-microsoft-azure/) |

+| MySQL | Azure SQL DB, MI, VM | [SSMA](/sql/ssma/sql-server-migration-assistant)<br/>[Ispirer*](https://www.ispirer.com/blog/migration-to-the-microsoft-technology-stack) | [SSMA](/sql/ssma/sql-server-migration-assistant)<br/>[Ispirer*](https://www.ispirer.com/blog/migration-to-the-microsoft-technology-stack) | [Attunity*](https://www.attunity.com/products/replicate/)<br/>[Striim*](https://www.striim.com/partners/striim-for-microsoft-azure/) |

+| Amazon RDS for MySQL | Azure DB for MySQL | [MySQL dump*](https://dev.mysql.com/doc/refman/5.7/en/mysqldump.html) | [DMS](https://azure.microsoft.com/services/database-migration/) | [MyDumper/MyLoader*](https://centminmod.com/mydumper.html) with [data-in replication](../mysql/concepts-data-in-replication.md)<br/>[Attunity*](https://www.attunity.com/products/replicate/)<br/>[Striim*](https://www.striim.com/partners/striim-for-microsoft-azure/) |

+| Amazon RDS for PostgreSQL | Azure DB for PostgreSQL -<br/>Single server | [PG dump*](https://www.postgresql.org/docs/current/static/app-pgdump.html) | [PG dump*](https://www.postgresql.org/docs/current/static/app-pgdump.html) | [DMS](https://azure.microsoft.com/services/database-migration/)<br/>[Attunity*](https://www.attunity.com/products/replicate/)<br/>[Striim*](https://www.striim.com/partners/striim-for-microsoft-azure/) |

+| DB2 | Azure SQL DB, MI, VM | [SSMA](/sql/ssma/sql-server-migration-assistant)<br/>[Ispirer*](https://www.ispirer.com/blog/migration-to-the-microsoft-technology-stack) | [SSMA](/sql/ssma/sql-server-migration-assistant)<br/>[Ispirer*](https://www.ispirer.com/blog/migration-to-the-microsoft-technology-stack) | [Attunity*](https://www.attunity.com/products/replicate/)<br/>[Striim*](https://www.striim.com/partners/striim-for-microsoft-azure/) |

+| Sybase - SAP ASE | Azure SQL DB, MI, VM | [SSMA](/sql/ssma/sql-server-migration-assistant)<br/>[Ispirer*](https://www.ispirer.com/blog/migration-to-the-microsoft-technology-stack) | [SSMA](/sql/ssma/sql-server-migration-assistant)<br/>[Ispirer*](https://www.ispirer.com/blog/migration-to-the-microsoft-technology-stack) | [Attunity*](https://www.attunity.com/products/replicate/)<br/>[Striim*](https://www.striim.com/partners/striim-for-microsoft-azure/) |

+| Sybase - SAP IQ | Azure SQL DB, MI, VM | [Ispirer*](https://www.ispirer.com/blog/migration-to-the-microsoft-technology-stack) | [Ispirer*](https://www.ispirer.com/blog/migration-to-the-microsoft-technology-stack) | |

+| SQL Server | Azure SQL MI | [Cloud Atlas*](https://www.unifycloud.com/cloud-migration-tool/)<br/>[Cloudamize*](https://www.cloudamize.com/) |

+| Amazon RDS for MySQL | Azure DB for MySQL | |

+| Amazon RDS for PostgreSQL | Azure DB for PostgreSQL -<br/>Single server | |

+- **Cause**: Before migrating data, you need to migrate the certificate of the source SQL Server instance from a database that is protected by Transparent Data Encryption (TDE) to the target Azure SQL Managed Instance or SQL Server on Azure Virtual Machine.

+- **Recommendation**: Migrate the TDE certificate to the target instance and retry the process. For more information about migrating TDE-enabled databases, see [Tutorial: Migrate TDE-enabled databases (preview) to Azure SQL in Azure Data Studio](/azure/dms/tutorial-transparent-data-encryption-migration-ads).

+- **Message**: `Migration for Database <Database Name> failed with error 'Non retriable error occurred while restoring backup with index 1 - 12824 The sp_configure value 'contained database authentication' must be set to 1 in order to restore a contained database. You may need to use RECONFIGURE to set the value_in_use.

+RESTORE DATABASE is terminating abnormally.`

+- **Cause**: The source database is a contained database. A specific configuration is needed to enable restoring a contained database. For more information about contained databases, see [Contained Database Users](/sql/relational-databases/security/contained-database-users-making-your-database-portable).

+- **Recommendation**: Run the following query connected to the source SQL Server in the context of the specific database before starting the migration. Then, attempt the migration of the contained database again.

+```sql

+-- Enable "contained database authentication"

+EXEC sp_configure 'contained', 1;

+RECONFIGURE;

+```

+> [!NOTE]

+> For more information on general troubleshooting steps for Azure SQL Managed Instance errors, see [Known issues with Azure SQL Managed Instance](/azure/azure-sql/managed-instance/doc-changes-updates-known-issues)

+- **Cause**: Your network settings in the firewall are causing the Self-Hosted Integration Runtime to be unable to connect to the service back end.

+```sql

+```sql

+- **Message**: Unable to read blobs in storage container, exception: The remote server returned an error: (403) Forbidden.;The remote server returned an error: (403) Forbidden

+- **Cause**: The Azure SQL target is unable to connect to blob storage.

+- **Recommendation**: Confirm that target network settings allow access to blob storage. For example, if you're migrating to a SQL Server on Azure VM target, ensure that outbound connections on the Virtual Machine aren't being blocked.

+- **Message**: Failed to create restore job. Unable to read blobs in storage container, exception: The remote name couldn't be resolved.

+- **Cause**: The Azure SQL target is unable to connect to blob storage.

+- **Recommendation**: Confirm that target network settings allow access to blob storage. For example, if migrating to SQL VM, ensure that outbound connections on VM aren't being blocked.

+- **Cause**: The most recent backup wasn't specified in the backup settings.

+- **Recommendation**: Specify the most recent backup file name in backup settings and retry the operation.

+- **Message**: `Operation failed: errorCode: Ext_RestoreSettingsError, message: RestoreId: 1111111-aaaa-bbbb-cccc-dddddddd, OperationId: 2222222-aaaa-bbbb-cccc-dddddddd, Detail: Unable to read blobs in storage container, exception: Unable to connect to the remote server;Unable to connect to the remote server;A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond 11.111.11.111:443.`

+- **Cause**: The error is possible to occur for both storage accounts with public network and private endpoint configuration. It's also possible that you have an on-premises DNS server that controls a hybrid network routing and DHCP. Unless you allow the Azure IP addresses configured in your DNS server, your SQL Server on Azure VM target has no chance to resolve the remote storage blob endpoint.

+- **Recommendation**: To debug this issue, you can try pinging your Azure Blob Storage URL from your SQL Server on Azure VM target and confirm if you have a connectivity problem. To solve this issue, you have to allow the Azure IP addresses configured in your DNS server. For more information, see [Troubleshoot Azure Private Endpoint connectivity problems](/azure/private-link/troubleshoot-private-endpoint-connectivity)

+> [!NOTE]

+> Make sure to migrate the database schema from source to target by using the [SQL Server dacpac extension](/sql/azure-data-studio/extensions/sql-server-dacpac-extension) or the [SQL Database Projects extension](/sql/azure-data-studio/extensions/sql-database-project-extension) in Azure Data Studio before selecting the list of tables to migrate.

+>

+> If no tables exists on the Azure SQL Database target, or no tables are selected before starting the migration. The **Next** button isn't available to select to initiate the migration task.

+>

+>

+> Make sure to migrate the database schema from source to target by using the [SQL Server dacpac extension](/sql/azure-data-studio/extensions/sql-server-dacpac-extension) or the [SQL Database Projects extension](/sql/azure-data-studio/extensions/sql-database-project-extension) in Azure Data Studio before selecting the list of tables to migrate.

+- If produce request's delay exceeds request timeout(*request.timeout.ms*), Event Hubs returns **Policy Violation** error code.

+6. Run the following commands to change the peering state to disabled.

+ The peering should be in a disabled state you set.

+7. Run the following commands to change the peering state back to enabled.

+ ```azurepowershell-interactive

+ $ckt.Peerings[0].State = "Enabled"

+ Set-AzExpressRouteCircuit -ExpressRouteCircuit $ckt

+ ```

+ The peering should be in a enabled state you set.

+

+ | Request message | Custom message to see while approving the Private Endpoint. |

+The IoT Edge hub provides two main functionalities: a proxy to IoT Hub and local communications.

+IoT Hub sees a module instance as similar to a device. A module instance can:

+* Send [device-to-cloud messages](../iot-hub/iot-hub-devguide-messaging.md)

+* Receive [direct methods](../iot-hub/iot-hub-devguide-direct-methods.md) targeted specifically at its identity

+* Have a module twin that's distinct and isolated from the [device twin](../iot-hub/iot-hub-devguide-device-twins.md) and the other module twins of that device

+When writing a module, you can connect to the IoT Edge hub and use IoT Hub primitives as you would when using IoT Hub with a device application. The only difference between IoT Edge modules and IoT device applications is that with modules you have to refer to the module identity instead of the device identity.

+An IoT Edge module can send messages to the cloud via the IoT Edge hub that acts as a local broker and propagates messages to the cloud. To enable complex processing of device-to-cloud messages, an IoT Edge module can intercept and process messages sent by other modules or devices to its local IoT Edge hub. The IoT Edge module will then send new messages with processed data. Chains of IoT Edge modules can thus be created to build local processing pipelines.

+To send device-to-cloud telemetry messages using routes:

+* Use the Module Client class of the [Azure IoT SDK](https://github.com/Azure/azure-iot-sdks). Each module has *input* and *output* endpoints.

+* Use a send message method from your Module Client class to send messages on the output endpoint of your module.

+* Set up a route in the edgeHub module of your device to send this output endpoint to IoT Hub.

+To process messages using routes:

+* Set up a route to send messages coming from another endpoint (module or device) to the input endpoint of your module.

+* Listen for messages on the input endpoint of your module. Each time a new message comes back, a callback function is triggered by the Azure IoT SDK.

+* Process your message with this callback function and (optionally) send new messages in your module endpoint queue.

+>[!NOTE]

+> To learn more about declaring a route, see [Learn how to deploy modules and establish routes in IoT Edge](module-composition.md#declare-routes)

+* To get a module twin with the [Azure IoT SDK](https://github.com/Azure/azure-iot-sdks), call the `ModuleClient.getTwin` method.

+* To receive a module twin patch with the Azure IoT SDK, implement a callback function and register it with the `ModuleClient.moduleTwinCallback` method from the Azure IoT SDK so that your callback function is triggered each time a twin patch comes in.

+To receive a direct method with the [Azure IoT SDK](https://github.com/Azure/azure-iot-sdks), implement a callback function and register it with the `ModuleClient.methodCallback` method from the Azure IoT SDK so that your callback function is triggered each time that a direct method comes in.

+IoT Edge supports multiple operating systems, device architectures, and development languages so you can build the scenario that matches your needs. Use this section to understand your options for developing custom IoT Edge modules. You can learn more about tooling support and requirements for each language in [Prepare your development and test environment for IoT Edge](development-environment.md).

+For all languages in the following table, IoT Edge [supports](support.md) development for AMD64 and most ARM64 Linux containers. There is support for Debian 11 ARM32 containers, as well.

+| C | Visual Studio Code<br>Visual Studio 2019/2022 |

+| C# | Visual Studio Code<br>Visual Studio 2019/2022 |

+>For cross-platform compilation, like compiling an ARM32 IoT Edge module on an AMD64 development machine, you need to configure the development machine to compile code on target device architecture matching the IoT Edge module. For more information, see [Use Visual Studio Code to develop and debug modules for Azure IoT Edge](how-to-vs-code-develop-module.md).

+> For more information about ARM64 Linux containers, see [Use Visual Studio Code to develop and debug modules for Azure IoT Edge](how-to-vs-code-develop-module.md).

+We no longer support Windows containers. [IoT Edge for Linux on Windows](iot-edge-for-linux-on-windows.md) is the recommended way to run IoT Edge on Windows devices.

+In the config file on an IoT Edge device, there's a parameter called `allow_elevated_docker_permissions`. When set to **true**, this flag allows the `--privileged` flag and any additional capabilities that you define in the `CapAdd` field of the Docker HostConfig in the [container create options](how-to-use-create-options.md).

+> [!NOTE]

+> Currently, this flag is true by default, which allows deployments to grant privileged permissions to modules. We recommend that you set this flag to false to improve device security.

+We no longer support Windows containers. [IoT Edge for Linux on Windows](iot-edge-for-linux-on-windows.md) is the recommended way to run IoT Edge on Windows devices.

+**Description**: Recommended environment for Deep Learning with PyTorch on Azure containing the Azure Machine Learning SDK with the latest compatible versions of Ubuntu, Python, PyTorch, CUDA\RocM,NebulaML combined with optimizers like ORT Training,+DeepSpeed+MSCCL+ORT MoE, and checkpointing using NebulaML and more.

+* Unified alerting is enabled by default for all instances created after December 2022. For instances created before this date, unified alerting must be enabled manually by the Azure Managed Grafana team. For activation, [contact us](mailto:ad4g@microsoft.com)

+ Title: Connection troubleshoot overview

+description: Learn about Azure Network Watcher connection troubleshoot capability.

+# Connection troubleshoot overview

+With the increase of sophisticated and high-performance workloads in Azure, there's a critical need for increased visibility and control over the operational state of complex networks running these workloads. Such complex networks are implemented using network security groups, firewalls, user-defined routes, and resources provided by Azure. Complex configurations make troubleshooting connectivity issues challenging.

+The connection troubleshoot feature of Azure Network Watcher helps reduce the amount of time to diagnose and troubleshoot network connectivity issues. The results returned can provide insights about the root cause of the connectivity problem and whether it's due to a platform or user configuration issue.

+Connection troubleshoot reduces the Mean Time To Resolution (MTTR) by providing a comprehensive method of performing all connection major checks to detect issues pertaining to network security groups, user-defined routes, and blocked ports. It provides the following results with actionable insights where a step-by-step guide or corresponding documentation is provided for faster resolution:

+- Connectivity test with different destination types (VM, URI, FQDN, or IP Address)

+- Configuration issues that impact reachability

+- All possible hop by hop paths from the source to destination

+- Hop by hop latency

+- Latency (minimum, maximum, and average between source and destination)

+- Graphical topology view from source to destination

+- Number of probes failed during the connection troubleshoot check

+## Supported source and destination types

+Connection troubleshoot provides the capability to check TCP or ICMP connections from any of these Azure resources:

+- Virtual machines

+- Azure Bastion instances

+- Application gateways (except v1)

+> Connection troubleshoot requires that the virtual machine you troubleshoot from has the `AzureNetworkWatcherExtension` extension installed. The extension is not required on the destination virtual machine.

+> - To install the extension on a Windows VM, see [Azure Network Watcher Agent virtual machine extension for Windows](../virtual-machines/extensions/network-watcher-windows.md?toc=%2fazure%2fnetwork-watcher%2ftoc.json).

+> - To install the extension on a Linux VM, see [Azure Network Watcher Agent virtual machine extension for Linux](../virtual-machines/extensions/network-watcher-linux.md?toc=%2fazure%2fnetwork-watcher%2ftoc.json).

+Connection troubleshoot can test connections to any of these destinations:

+- Virtual machines

+- Fully qualified domain names (FQDNs)

+- Uniform resource identifiers (URIs)

+- IP addresses

+## Issues detected by connection troubleshoot

+Connection troubleshoot can detect the following types of issues that can impact connectivity:

+- High VM CPU utilization

+- High VM memory utilization

+- Virtual machine (guest) firewall rules blocking traffic

+- DNS resolution failures

+- Misconfigured or missing routes

+- Network security group (NSG) rules that are blocking traffic

+- Inability to open a socket at the specified source port

+- Missing address resolution protocol entries for Azure ExpressRoute circuits

+- Servers not listening on designated destination ports

+The following table shows the properties returned after running connection troubleshoot.

+|GuestFirewall | Traffic is blocked due to a virtual machine firewall configuration. <br><br> A TCP ping is a unique use case in which, if there's no allowed rule, the firewall itself responds to the client's TCP ping request even though the TCP ping doesn't reach the target IP address/FQDN. This event isn't logged. If there's a network rule that allows access to the target IP address/FQDN, the ping request reaches the target server and its response is relayed back to the client. This event is logged in the Network rules log. |

+|NetworkSecurityRule | Traffic is blocked by a network security group rule (security rule is returned) |

+- To learn how to use connection troubleshoot to test and troubleshoot connections, see [Troubleshoot connections with Azure Network Watcher using the Azure portal](network-watcher-connectivity-portal.md).

+- To learn more about Network Watcher and its other capabilities, see [What is Azure Network Watcher?](network-watcher-monitoring-overview.md).

+In this article, you learn how to use [Azure Network Watcher connection troubleshoot](network-watcher-connectivity-overview.md) to diagnose and troubleshoot connectivity issues.

+## Prerequisites

+- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+- Virtual machines (VMs) to troubleshoot connections with.

+> [!IMPORTANT]

+> Connection troubleshoot requires that the virtual machine you troubleshoot from has the `AzureNetworkWatcherExtension` extension installed. The extension is not required on the destination virtual machine.

+> - To install the extension on a Windows VM, see [Azure Network Watcher Agent virtual machine extension for Windows](../virtual-machines/extensions/network-watcher-windows.md?toc=%2fazure%2fnetwork-watcher%2ftoc.json).

+> - To install the extension on a Linux VM, see [Azure Network Watcher Agent virtual machine extension for Linux](../virtual-machines/extensions/network-watcher-linux.md?toc=%2fazure%2fnetwork-watcher%2ftoc.json).

+## Test connectivity between two connected virtual machines

+In this section, you test connectivity between two connected virtual machines.

+1. Sign in to the [Azure portal](https://portal.azure.com).

+1. In the search box at the top of the portal, enter *network watcher*. Select **Network Watcher** in the search results.

+1. Under **Network diagnostic tools**, select **Connection troubleshoot**. Enter or select the following information:

+ | Setting | Value |

+ | - | |

+ | **Source** | |

+ | Subscription | Select your Azure subscription. |

+ | Resource group | Select **myResourceGroup**. |

+ | Source type | Select **Virtual machine**. |

+ | Virtual machine | Select **VM1**. |

+ | **Destination** | |

+ | Destination type | Select **Select a virtual machine**. |

+ | Resource group | Select **myResourceGroup**. |

+ | Virtual machine | Select **VM2**. |

+ | **Probe Settings** | |

+ | Preferred IP version | Select **IPv4**. |

+ | Protocol | Select **TCP**. |

+ | Destination port | Enter *80*. |

+ | **Connection Diagnostics** | |

+ | Diagnostics tests | Select **Select all**. |

+ :::image type="content" source="./media/network-watcher-connectivity-portal/test-virtual-machines-connected.png" alt-text="Screenshot of Network Watcher connection troubleshoot in Azure portal to test the connection between two connected virtual machines.":::

+1. Select **Test connection**.

+ The test results show that the two virtual machines are communicating with no issues:

+ - Network security group rules allow traffic between the two virtual machines.

+ - The two virtual machines are directly connected (VM2 is the next hop of VM1).

+ - Azure default system route is used to route traffic between the two virtual machines (Route table ID: System route).

+ - 66 probes were successfully sent with average latency of 2 ms.

+ :::image type="content" source="./media/network-watcher-connectivity-portal/virtual-machine-connected-test-result.png" alt-text="Screenshot of connection troubleshoot results after testing the connection between two connected virtual machines.":::

+## Troubleshoot connectivity issue between two virtual machines

+In this section, you test connectivity between two virtual machines that have connectivity issue.

+1. Sign in to the [Azure portal](https://portal.azure.com).

+1. In the search box at the top of the portal, enter *network watcher*. Select **Network Watcher** in the search results.

+1. Under **Network diagnostic tools**, select **Connection troubleshoot**. Enter or select the following information:

+ | Setting | Value |

+ | - | |

+ | **Source** | |

+ | Subscription | Select your Azure subscription. |

+ | Resource group | Select **myResourceGroup**. |

+ | Source type | Select **Virtual machine**. |

+ | Virtual machine | Select **VM1**. |

+ | **Destination** | |

+ | Destination type | Select **Select a virtual machine**. |

+ | Resource group | Select **myResourceGroup**. |

+ | Virtual machine | Select **VM3**. |

+ | **Probe Settings** | |

+ | Preferred IP version | Select **IPv4**. |

+ | Protocol | Select **TCP**. |

+ | Destination port | Enter *80*. |

+ | **Connection Diagnostics** | |

+ | Diagnostics tests | Select **Select all**. |

+ :::image type="content" source="./media/network-watcher-connectivity-portal/test-two-virtual-machines.png" alt-text="Screenshot of Network Watcher connection troubleshoot in Azure portal to test the connection between two virtual machines.":::

+1. Select **Test connection**.

+ The test results show that the two virtual machines aren't communicating:

+ - The two virtual machines aren't connected (no probes were sent from VM1 to VM3).

+ - There's no route between the two virtual machines (Next hop type: None).

+ - Azure default system route is the route table used (Route table ID: System route).

+ - Network security group rules allow traffic between the two virtual machines.

+ :::image type="content" source="./media/network-watcher-connectivity-portal/virtual-machines-test-result.png" alt-text="Screenshot of connection troubleshoot results after testing the connection between two virtual machines that aren't communicating.":::

+## Test connectivity with `www.bing.com`

+In this section, you test connectivity between a virtual machines and `www.bing.com`.

+1. Sign in to the [Azure portal](https://portal.azure.com).

+1. In the search box at the top of the portal, enter *network watcher*. Select **Network Watcher** in the search results.

+1. Under **Network diagnostic tools**, select **Connection troubleshoot**. Enter or select the following information:

+ | Setting | Value |

+ | - | |

+ | **Source** | |

+ | Subscription | Select your Azure subscription. |

+ | Resource group | Select **myResourceGroup**. |

+ | Source type | Select **Virtual machine**. |

+ | Virtual machine | Select **VM1**. |

+ | **Destination** | |

+ | Destination type | Select **Specify manually**. |

+ | Resource group | Enter *www\.bing.com*. |

+ | **Probe Settings** | |

+ | Preferred IP version | Select **IPv4**. |

+ | Protocol | Select **TCP**. |

+ | Destination port | Enter *443*. |

+ | **Connection Diagnostics** | |

+ | Diagnostics tests | Select **Connectivity**. |

+ :::image type="content" source="./media/network-watcher-connectivity-portal/test-bing.png" alt-text="Screenshot of Network Watcher connection troubleshoot in Azure portal to test the connection between a virtual machines and Microsoft Bing search engine.":::

+1. Select **Test connection**.

+ The test results show that `www.bing.com` is reachable from **VM1** virtual machine:

+ - Connectivity test is successful with 66 probes sent with an average latency of 3 ms.

+ :::image type="content" source="./media/network-watcher-connectivity-portal/bing-test-result.png" alt-text="Screenshot of connection troubleshoot results after testing the connection with Microsoft Bing search engine.":::

+## Next steps

+Learn how to [automate virtual machines packet captures](network-watcher-alert-triggered-packet-capture.md)

+ Title: Packet capture overview

+description: Learn about Azure Network Watcher packet capture capability.

+# Packet capture overview

+Azure Network Watcher packet capture allows you to create packet capture sessions to track traffic to and from a virtual machine (VM) or a scale set. Packet capture helps to diagnose network anomalies both reactively and proactively. Other uses include gathering network statistics, gaining information on network intrusions, to debug client-server communications and much more.

+Packet capture is an extension that is remotely started through Network Watcher. This capability eases the burden of running a packet capture manually on the desired virtual machine or virtual machine scale set instance(s), which saves valuable time. Packet capture can be triggered through the portal, PowerShell, Azure CLI, or REST API. One example of how packet capture can be triggered is with virtual machine alerts. Filters are provided for the capture session to ensure you capture traffic you want to monitor. Filters are based on 5-tuple (protocol, local IP address, remote IP address, local port, and remote port) information. The captured data can be stored in the local disk or a storage blob.

+> Packet capture requires a virtual machine extension `AzureNetworkWatcherExtension`.

+> - To install the extension on a Windows virtual machine, see [Network Watcher Agent VM extension for Windows](../virtual-machines/extensions/network-watcher-windows.md).

+> - To install the extension on a Linux virtual machine, see [Network Watcher Agent VM extension for Linux](../virtual-machines/extensions/network-watcher-linux.md).

+To control the size of captured data and only capture required information, use the following options:

+#### Capture configuration

+|**Maximum bytes per packet (bytes)** | The number of bytes from each packet. All bytes are captured if left blank. Enter 34 if you only need to capture IPv4 header.|

+|**Time limit (seconds)** | Packet capture session time limit, once the value is reached the session ends. The default value is 18000 seconds (5 hours).|

+#### Filtering (optional)

+## Next steps

+- To learn how to manage packet captures using the Azure portal, see [Manage packet captures in virtual machines using the Azure portal](network-watcher-packet-capture-manage-portal.md) and [Manage packet captures in Virtual Machine Scale Sets using the Azure portal](network-watcher-packet-capture-manage-portal-vmss.md).

+- To learn how to manage packet captures using Azure PowerShell, see [Manage packet captures in virtual machines using PowerShell](network-watcher-packet-capture-manage-powershell.md) and [Manage packet captures in Virtual Machine Scale Sets using PowerShell](network-watcher-packet-capture-manage-powershell-vmss.md).

+- To learn how to create proactive packet captures based on virtual machine alerts, see [Create an alert triggered packet capture](network-watcher-alert-triggered-packet-capture.md).

+description: Learn about the meaning of various provisioning states and how to troubleshoot Azure Microsoft.Network failed Provisioning State.

+This article helps you understand the meaning of various provisioning states for Microsoft.Network resources. You can effectively troubleshoot situations when the state is **Failed**.

+The provisioning state is the status of a user-initiated, control-plane operation on an Azure Resource Manager resource.

+| Failed | Last operation on the resource wasn't successful. |

+| Succeeded | Last operation on the resource was successful. |

+| Deleting | Resource is being deleted. |

+| Migrating | Seen when migrating from Azure Service Manager to Azure Resource Manager. |

+These states are metadata properties of the resource. They're independent from the functionality of the resource itself. Being in the failed state doesn't necessarily mean that the resource isn't functional. In most cases, it can continue operating and serving traffic without issues.

+In several scenarios, if the resource is in the failed state, further operations on the resource or on other resources that depend on it might fail. You need to revert the state back to succeeded before running other operations.

+For example, you can't run an operation on a `VirtualNetworkGateway` if it has a dependent `VirtualNetworkGatewayConnection` object in failed state.

+To restore succeeded state, run another write (`PUT`) operation on the resource.

+The issue that caused the previous operation might no longer be current. The newer write operation should be successful and restore the provisioning state.

+The easiest way to achieve this task is to use Azure PowerShell. Issue a resource-specific *Get* command that fetches all the current configuration for the resource. Next, run a *Set* command, or equivalent, to commit to Azure a write operation that contains all the resource properties as currently configured.

+>

+> - Running a `Set` command on the resource without first running a `Get` results in overwriting the resource with default settings. Those settings might be different from the ones you currently have configured. Don't just run a `Set` command unless you intend to reset to default.

+> - Running a `Get` and `Set` operation using third party software or any tool using older API version might also result in loss of some settings. Those settings might not be present in the API version with which you run the command.

+1. Install the latest version of the Azure Resource Manager PowerShell cmdlets. For more information, see [Install the Azure Az PowerShell module](/powershell/azure/install-az-ps).

+5. Run the resource-specific commands in the following sections to reset the provisioning state.

+> Every sample command in this article uses `your_resource_name` for the name of the resource and `your_resource_group_name` for the name of the resource group. Make sure to replace these strings with the appropriate resource and resource group names for your deployment.

+> `Microsoft.Network/expressRouteGateways` are deployed within a Virtual WAN. If you have a standalone ExpressRoute gateway in your virtual network, run the commands related to [Microsoft.Network/virtualNetworkGateways](#microsoftnetworkvirtualnetworkgateways).

+> Most Virtual WAN related resources, such as networkVirtualAppliances, use the `Update` cmdlet, not the `Set`, for write operations.

+> Most Virtual WAN related resources, such as virtualHubs, use the `Update` cmdlet, not the `Set`, for write operations.

+> Most Virtual WAN related resources, such as virtualWans, use the `Update` cmdlet, not the `Set`, for write operations.

+>

+> - `Microsoft.Network/vpnGateways` are deployed within a Virtual WAN. If you have a standalone VPN gateway in your virtual network, run the commands related to [Microsoft.Network/virtualNetworkGateways](#microsoftnetworkvirtualnetworkgateways).

+> - Most Virtual WAN related resources, such as vpnGateways, use the `Update` cmdlet, not the `Set` for write operations.

+> [!NOTE]

+> Most Virtual WAN related resources, such as vpnSites, use the `Update` cmdlet, not the `Set`, for write operations.

+If the command that you ran didn't resolve the failed state, it should return an error code.

+If you're still experiencing issues, open a support ticket with [Microsoft support](https://portal.azure.com/?#blade/Microsoft_Azure_Support/HelpAndSupportBlade). Specify to the support agent both the error code that you received in the latest operation and the timestamp when you ran the operation.

+ Title: Handle transient connectivity errors - Azure Database for PostgreSQL - Flexible Server

+description: Learn how to handle transient connectivity errors for Azure Database for PostgreSQL - Flexible Server.

+# Handling transient connectivity errors for Azure Database for PostgreSQL - Flexible Server

+This article describes how to handle transient errors connecting to Azure Database for PostgreSQL.

+## Transient errors

+A transient error, also known as a transient fault, is an error that will resolve itself. Most typically these errors manifest as a connection to the database server being dropped. Also new connections to a server can't be opened. Transient errors can occur for example when hardware or network failure happens. Another reason could be a new version of a PaaS service that is being rolled out. Most of these events are automatically mitigated by the system in less than 60 seconds. A best practice for designing and developing applications in the cloud is to expect transient errors. Assume they can happen in any component at any time and to have the appropriate logic in place to handle these situations.

+## Handling transient errors

+Transient errors should be handled using retry logic. Situations that must be considered:

+* An error occurs when you try to open a connection

+* An idle connection is dropped on the server side. When you try to issue a command, it can't be executed

+* An active connection that currently is executing a command is dropped.

+The first and second cases are fairly straight forward to handle. Try to open the connection again. When you succeed, the transient error has been mitigated by the system. You can use your Azure Database for PostgreSQL again. We recommend having waits before retrying the connection. Back off if the initial retries fail. This way the system can use all resources available to overcome the error situation. A good pattern to follow is:

+* Wait for 5 seconds before your first retry.

+* For each following retry, increase the wait exponentially, up to 60 seconds.

+* Set a max number of retries at which point your application considers the operation failed.

+When a connection with an active transaction fails, it is more difficult to handle the recovery correctly. There are two cases: If the transaction was read-only in nature, it is safe to reopen the connection and to retry the transaction. If however if the transaction was also writing to the database, you must determine if the transaction was rolled back, or if it succeeded before the transient error happened. In that case, you might just not have received the commit acknowledgment from the database server.

+One way of doing this, is to generate a unique ID on the client that is used for all the retries. You pass this unique ID as part of the transaction to the server and to store it in a column with a unique constraint. This way you can safely retry the transaction. It will succeed if the previous transaction was rolled back and the client generated unique ID does not yet exist in the system. It will fail indicating a duplicate key violation if the unique ID was previously stored because the previous transaction completed successfully.

+When your program communicates with Azure Database for PostgreSQL through third-party middleware, ask the vendor whether the middleware contains retry logic for transient errors.

+Make sure to test your retry logic. For example, try to execute your code while scaling up or down the compute resources of your Azure Database for PostgreSQL server. Your application should handle the brief downtime that is encountered during this operation without any problems.

+## Using Data Encryption with Customer Managed Key (CMK) and Geo-redundant Business Continuity features, such as Replicas and Geo-redundant backup

+Azure Database for PostgreSQL - Flexible Server supports advanced [Data Recovery (DR)](../flexible-server/concepts-business-continuity.md) features, such as [Replicas](../../postgresql/flexible-server/concepts-read-replicas.md) and [geo-redundant backup](../flexible-server/concepts-backup-restore.md). Following are requirements for setting up data encryption with CMK and these features, additional to [basic requirements for data encryption with CMK](#requirements-for-configuring-data-encryption-for-azure-database-for-postgresql-flexible-server):

+* The Geo-redundant backup encryption key needs to be the created in an Azure Key Vault (AKV) in the region where the Geo-redundant backup is stored

+* The [Azure Resource Manager (ARM) REST API](../../azure-resource-manager/management/overview.md) version for supporting Geo-redundant backup enabled CMK servers is '2022-11-01-preview'. Therefore, using [ARM templates](../../azure-resource-manager/templates/overview.md) for automation of creation of servers utilizing both encryption with CMK and geo-redundant backup features, please use this ARM API version.

+* Same [user managed identity](../../active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities.md)can't be used to authenticate for primary database Azure Key Vault (AKV) and Azure Key Vault (AKV) holding encryption key for Geo-redundant backup. To make sure that we maintain regional resiliency we recommend creating user managed identity in the same region as the geo-backups.

+* As support for Geo-redundant backup with data encryption using CMK is currently in preview, there is currently no Azure CLI support for server creation with both of these features enabled.

+* If [Read replica database](../flexible-server/concepts-read-replicas.md) is setup to be encrypted with CMK during creation, its encryption key needs to be resident in an Azure Key Vault (AKV) in the region where Read replica database resides. [User assigned identity](../../active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities.md) to authenticate against this Azure Key Vault (AKV) needs to be created in the same region.

+- **serverName**: enter a unique name that identifies your Azure Database for PostgreSQL server. For example, `mydemoserver-pg`. The domain name `postgres.database.azure.com` is appended to the server name you provide. The server can contain only lowercase letters, numbers, and the hyphen (-) character. It must contain at least 3 through 63 characters.

+- **administratorLogin**: enter your own login account to use when you connect to the server. For example, `myadmin`. The admin login name can't be `azure_superuser`, `azure_pg_admin`, `admin`, `administrator`, `root`, `guest`, or `public`. It can't start with `pg_`.

+- **administratorLoginPassword**: enter a new password for the server admin account. It must contain between 8 and 128 characters. Your password must contain characters from three of the following categories: English uppercase letters, English lowercase letters, numbers (0 through 9), and non-alphanumeric characters (!, $, #, %, etc.).

+1. Select **Databases** > **Azure Database for PostgreSQL**.

+1. Select the **Flexible server** deployment option.

+1. Fill out the **Basics** form with the following information:

+ :::image type="content" source="./media/quickstart-create-database-portal/3-create-basics.png" alt-text="Create a server.":::

+ :::image type="content" source="./media/quickstart-create-database-portal/4-pricing-tier-geo-backup.png" alt-text="The Pricing tier pane.":::

+1. Configure Networking options

+1. On the **Networking** tab, you can choose how your server is reachable. Azure Database for PostgreSQL Flexible Server provides two ways to connect to your server:

+ :::image type="content" source="./media/quickstart-create-database-portal/5-networking.png" alt-text="The Networking pane.":::

+1. Select **Review + create** to review your selections. Select **Create** to provision the server. This operation may take a few minutes.

+1. On the toolbar, select the **Notifications** icon (a bell) to monitor the deployment process. Once the deployment is done, you can select **Pin to dashboard**, which creates a tile for this server on your Azure portal dashboard as a shortcut to the server's **Overview** page. Selecting **Go to resource** opens the server's **Overview** page.

+ :::image type="content" source="./media/quickstart-create-database-portal/7-notifications.png" alt-text="The Notifications pane.":::

+ :::image type="content" source="./media/quickstart-create-database-portal/8-server-name.png" alt-text="The server Overview page.":::

+1. Create a blank database called "mypgsqldb" at the prompt by typing the following command:

+1. At the prompt, execute the following command to switch connections to the newly created database **mypgsqldb**:

+1. Type `\q`, and then select the Enter key to quit psql.

+1. On your resource group page, select **Delete**. Enter the name of your resource group, such as the example, **myresourcegroup**, in the text box to confirm deletion. Select **Delete**.

+1. On the **Overview** page, select **Delete**.

+1. Confirm the name of the server you want to delete, and view the databases under it that are affected. Enter your server name in the text box, such as the example, **mydemoserver**. Select **Delete**.

+- Make a note of the resource group that contains your private mobile network that was collected in [Collect the required information to deploy a private mobile network](collect-required-information-for-private-mobile-network.md). We recommend that the mobile network site resource you create in this procedure belongs to the same resource group.

+ |The packet core in which to create the mobile network site resource. |**Instance details: Packet core name**|

+ |The billing plan for the site that you are creating. The available plans have the following throughput, activated SIMs and radio access network (RAN) allowances:</br></br>G0 - 100 Mbps per site, 20 activated SIMs per network and 2 RAN connections. </br> G1 - 1 Gbps per site, 100 activated SIMs per network and 5 RAN connections. </br> G2 - 2 Gbps per site, 200 activated SIMs per network and 10 RAN connections. </br> G5 - 5 Gbps per site, 500 activated SIMs per network and unlimited RAN connections. </br> G10 - 10 Gbps per site, 1000 activated SIMs per network and unlimited RAN connections.|**Instance details: Service plan**|

+ |The Azure resource group to use to deploy the mobile network resource. You should use a new resource group for this resource. It's useful to include the purpose of this resource group in its name for future identification (for example, *contoso-pmn-rg*). </br></br> Note: We recommend that this resource group is also used when [Collecting the required information for a site](collect-required-information-for-a-site.md). |**Project details: Resource group**|

+ > [!NOTE]

+ > Make a note of the Azure Stack Edge's resource group. The AKS cluster and custom location, created in this procedure, must belong to this resource group.

+ > [!NOTE]

+ > If a warning appears about an incompatibility between the selected packet core version and the current Azure Stack Edge version, you'll need to update ASE first. Select **Upgrade ASE** from the warning prompt and follow the instructions in [Update your Azure Stack Edge Pro GPU](../databox-online/azure-stack-edge-gpu-install-update.md). Once you've finished updating your ASE, go back to the beginning of this step to create the site resource.

+1. Use the information you collected in [Collect access network values](collect-required-information-for-a-site.md#collect-access-network-values) to fill out the fields in the **Access network** section.

+ > [!NOTE]

+ > **ASE N2 virtual subnet** and **ASE N3 virtual subnet** (if this site will support 5G UEs) or **ASE S1-MME virtual subnet** and **ASE S1-U virtual subnet** (if this site will support 4G UEs) must match the corresponding virtual network names on port 5 on your Azure Stack Edge Pro device.

+ - Under **Provide custom HTTPS certificate?**, select **Yes** or **No** based on whether you decided to provide a custom HTTPS certificate in [Collect local monitoring values](collect-required-information-for-a-site.md#collect-local-monitoring-values). If you selected **Yes**, use the information you collected in [Collect local monitoring values](collect-required-information-for-a-site.md#collect-local-monitoring-values) to select a certificate.

+1. If you want to assign additional packet cores to the site, for each new packet core resource see LINK

+ Title: Create additional Packet Core instances for a site - Azure portal

+description: This how-to guide shows how to create additional packet core instances for a site in your private mobile network.

+# Create additional Packet Core instances for a site using the Azure portal

+Azure Private 5G Core private mobile networks include one or more sites. Once deployed, each site can have multiple packet core instances for redundancy. In this how-to guide, you'll learn how to add additional packet core instances to a site in your private mobile network using the Azure portal.

+## Prerequisites

+- You must already have a site deployed in your private mobile network.

+- Collect all of the information in [Collect required information for a site](collect-required-information-for-a-site.md) that you used for the site.

+- Ensure you can sign in to the Azure portal using an account with access to the active subscription you used to create your private mobile network. This account must have the built-in Contributor or Owner role at the subscription scope.

+## Create the packet core instance

+In this step, you'll create an additional packet core instance for a site in your private mobile network.

+1. Sign in to the [Azure portal](https://portal.azure.com/).

+1. Search for and select the **Mobile Network** resource representing the private mobile network containing the site that you want to add a packet core instance to.

+1. Select the **Sites** blade on the resource menu.

+1. Select the **Site** resource that you want to add a packet core instance to.

+1. Select **Add packet core**.

+1. Specify a **Packet core name** and select **Next : Packet core >**.

+1. You'll now see the **Packet core** configuration tab.

+1. In the **Packet core** section, set the fields as follows:

+ - Use the information you collected in [Collect packet core configuration values](collect-required-information-for-a-site.md#collect-packet-core-configuration-values) to fill out the **Technology type**, **Azure Stack Edge device**, and **Custom location** fields.

+ - Select the recommended packet core version in the **Version** field.

+ > [!NOTE]

+ > If a warning appears about an incompatibility between the selected packet core version and the current Azure Stack Edge version, you'll need to update ASE first. Select **Upgrade ASE** from the warning prompt and follow the instructions in [Update your Azure Stack Edge Pro GPU](../databox-online/azure-stack-edge-gpu-install-update.md). Once you've finished updating your ASE, go back to the beginning of this step to create the packet core resource.

+ - Ensure **AKS-HCI** is selected in the **Platform** field.

+1. Use the information you collected in [Collect access network values](collect-required-information-for-a-site.md#collect-access-network-values) for the site to fill out the fields in the **Access network** section.

+ > [!NOTE]

+ > **ASE N2 virtual subnet** and **ASE N3 virtual subnet** (if this site supports 5G UEs) or **ASE S1-MME virtual subnet** and **ASE S1-U virtual subnet** (if this site supports 4G UEs) must match the corresponding virtual network names on port 5 on your Azure Stack Edge Pro device.

+1. In the **Attached data networks** section, select **Attach data network**. Select the existing data network you used for the site then use the information you collected in [Collect data network values](collect-required-information-for-a-site.md#collect-data-network-values) to fill out the fields. Note the following:

+ - **ASE N6 virtual subnet** (if this site supports 5G UEs) or **ASE SGi virtual subnet** (if this site supports 4G UEs) must match the corresponding virtual network name on port 6 on your Azure Stack Edge Pro device.

+ - If you decided not to configure a DNS server, clear the **Specify DNS addresses for UEs?** checkbox.

+ - If you decided to keep NAPT disabled, ensure you configure your data network router with static routes to the UE IP pools via the appropriate user plane data IP address for the corresponding attached data network.

+ Once you've finished filling out the fields, select **Attach**.

+1. Repeat the previous step for each additional data network configured on the site.

+1. If you decided to configure diagnostics packet collection or use a user assigned managed identity for HTTPS certificate for this site, select **Next : Identity >**.

+If you decided not to configure diagnostics packet collection or use a user assigned managed identity for HTTPS certificates for this site, you can skip this step.

+ 1. Select **+ Add** to configure a user assigned managed identity.

+ 1. In the **Select Managed Identity** side panel:

+ - Select the **Subscription** from the dropdown.

+ - Select the **Managed identity** from the dropdown.

+1. If you decided you want to provide a custom HTTPS certificate in [Collect local monitoring values](collect-required-information-for-a-site.md#collect-local-monitoring-values), select **Next : Local access >**. If you decided not to provide a custom HTTPS certificate for monitoring this site, you can skip this step.

+ 1. Under **Provide custom HTTPS certificate?**, select **Yes**.

+ 1. Use the information you collected in [Collect local monitoring values](collect-required-information-for-a-site.md#collect-local-monitoring-values) to select a certificate.

+1. In the **Local access** section, set the fields as follows:

+ - Under **Authentication type**, select the authentication method you decided to use in [Choose the authentication method for local monitoring tools](collect-required-information-for-a-site.md#choose-the-authentication-method-for-local-monitoring-tools).

+ - Under **Provide custom HTTPS certificate?**, select **Yes** or **No** based on whether you decided to provide a custom HTTPS certificate in [Collect local monitoring values](collect-required-information-for-a-site.md#collect-local-monitoring-values). If you selected **Yes**, use the information you collected in [Collect local monitoring values](collect-required-information-for-a-site.md#collect-local-monitoring-values) to select a certificate.

+1. Select **Review + create**.

+1. Azure will now validate the configuration values you've entered. You should see a message indicating that your values have passed validation.

+ If the validation fails, you'll see an error message and the **Configuration** tab(s) containing the invalid configuration will be flagged with red dots. Select the flagged tab(s) and use the error messages to correct invalid configuration before returning to the **Review + create** tab.

+1. Once your configuration has been validated, you can select **Create** to create the packet core instance. The Azure portal will display a confirmation screen when the packet core instance has been created.

+1. Return to the **Site** overview, and confirm that it contains the new packet core instance.

+## Next steps

+If you decided to set up Azure AD for local monitoring access, follow the steps in [Enable Azure Active Directory (Azure AD) for local monitoring tools](enable-azure-active-directory.md).

+If you haven't already done so, you should now design the policy control configuration for your private mobile network. This allows you to customize how your packet core instances apply quality of service (QoS) characteristics to traffic. You can also block or limit certain flows. See [Policy control](policy-control.md) to learn more about designing the policy control configuration for your private mobile network.

+ 1. Copy the contents of the **Blob SAS URL** field and share the URL with your support representative via a [support request ticket](/azure/azure-portal/supportability/how-to-create-azure-support-request).

+ > [!IMPORTANT]

+ > You must always set **Service type** to **Azure Private 5G Core** when raising a support request for any issues related to AP5GC.

+- If this does not resolve the issue, share the correlation ID of the failed request with AP5GC support for investigation via a [support request ticket](/azure/azure-portal/supportability/how-to-create-azure-support-request).

+ > [!IMPORTANT]

+ > You must always set **Service type** to **Azure Private 5G Core** when raising a support request for any issues related to AP5GC.

+ Title: Modify a service plan

+description: In this how-to guide, you'll learn how to modify a service plan using the Azure portal.

+# Modify a service plan

+The *service plan* determines an allowance for the throughput and the number of radio access network (RAN) connections for each site, as well as the number of devices that each network supports. The plan you selected when creating the site can be updated to support your deployment requirements as they change. In this how-to guide, you'll learn how to modify a service plan using the Azure portal.

+## Prerequisites

+- Ensure you can sign in to the Azure portal using an account with access to the active subscription you used to create your private mobile network. This account must have the built-in Contributor or Owner role at the subscription scope.

+- Verify pricing and charges associated with the service plan to which you want to move. See the [Azure Private 5G Core Pricing page](https://azure.microsoft.com/pricing/details/private-5g-core/) for pricing information.

+## Choose the new service plan

+Use the following table to choose the new service plan that will best fit your requirements.

+| Service Plan | Licensed Throughput | Licensed Activated SIMs | Licensed RANs |

+|||||

+| G0 | 100 Mbps | 20 | 2 |

+| G1 | 1 Gbps | 100 | 5 |

+| G2 | 2 Gbps | 200 | 10 |

+| G5 | 5 Gbps | 500 | Unlimited |

+| G10 | 10 Gbps | 1000 | Unlimited |

+## View the current service plan

+You can view your current service plan in the Azure portal.

+1. Sign in to the [Azure portal](https://portal.azure.com/).

+1. Search for and select the **Mobile Network** resource representing the private mobile network.

+ :::image type="content" source="media/mobile-network-search.png" alt-text="Screenshot of the Azure portal. It shows the results of a search for a Mobile Network resource.":::

+1. Select the **Sites** page, then select the site you're interested in.

+ :::image type="content" source="media/mobile-network-sites.png" alt-text="Screenshot of the Azure portal showing the Sites view in the Mobile Network resource.":::

+1. Under the **Network Functions** group, select the **Packet Core** resource.

+ :::image type="content" source="media/modify-service-plan/select-packet-core.png" alt-text="Screenshot of the Azure portal. It shows a Mobile Network Site with a Packet Core resource highlighted.":::

+1. Check the **Service Plan** field under the **Essentials** heading to view the current service plan.

+ :::image type="content" source="media/modify-service-plan/service-plan.png" alt-text="Screenshot of the Azure portal showing a packet core control plane resource. The Service Plan field is highlighted.":::

+## Modify the service plan

+To modify your service plan:

+1. If you haven't already, navigate to the service plan that you're interested in modifying as described in [View the current service plan](#view-the-current-service-plan).

+2. Select **Change plan**.

+ :::image type="content" source="media/modify-service-plan/service-plan.png" alt-text="Screenshot of the Azure portal showing a packet core control plane resource. The Service Plan field is highlighted.":::

+3. In **Service Plan** on the right, select the new service plan you collected in [Choose the new service plan](#choose-the-new-service-plan). Save your change with **Select**.

+ :::image type="content" source="media/modify-service-plan/service-plan-selection-tab.png" alt-text="Screenshot of the Azure portal showing the Service Plan screen.":::

+4. Wait while the Azure portal applies the new service plan configuration to your site. You'll see a confirmation screen when the deployment is complete.

+5. Navigate to the **Mobile Network Site** resource as described in [View the current service plan](#view-the-current-service-plan). Check that the field under **Service Plan** contains the updated information.

+## Next steps

+Use [Azure Monitor](monitor-private-5g-core-with-log-analytics.md) or the [packet core dashboards](packet-core-dashboards.md) to confirm your packet core instance is operating normally after you modify the service plan.

+| AT&T | ATT Detroit A | attdetroit1 | Central US |

+- AT&T: Atlanta, Dallas, Detroit

+| **Multicasting.io** | [Multicasting](https://multicasting.io/) | |

+| **Palo Alto Networks** | [VM-Series](https://docs.paloaltonetworks.com/vm-series/9-1/vm-series-performance-capacity/vm-series-performance-capacity/vm-series-on-azure-models-and-vms) | [VM-Series Next-Generation Firewall](https://ms.portal.azure.com/#view/Microsoft_Azure_Marketplace/GalleryItemDetailsBladeNopdl/id/paloaltonetworks.vmseries-ngfw/product/%7B%22displayName%22%3A%22VM-Series%20Next-Generation%20Firewall%20from%20Palo%20Alto%20Networks%22%2C%22itemDisplayName%22%3A%22VM-Series%20Next-Generation%20Firewall%20from%20Palo%20Alto%20Networks%22%2C%22id%22%3A%22paloaltonetworks.vmseries-ngfw%22%2C%22bigId%22%3A%22DZH318Z0BP7N%22%2C%22legacyId%22%3A%22paloaltonetworks.vmseries-ngfw%22%2C%22offerId%22%3A%22vmseries-ngfw%22%2C%22publisherId%22%3A%22paloaltonetworks%22%2C%22publisherDisplayName%22%3A%22Palo%20Alto%20Networks%2C%20Inc.%22%2C%22summary%22%3A%22Looking%20to%20secure%20your%20applications%20in%20Azure%2C%20protect%20against%20threats%20and%20prevent%20data%20exfiltration%3F%22%2C%22longSummary%22%3A%22VM-Series%20next-generation%20firewall%20is%20for%20developers%2C%20architects%2C%20and%20security%20teams.%20Enable%20firewall%2C%20inline%20threat%2C%20and%20data%20theft%20preventions%20into%20your%20application%20development%20workflows%20using%20native%20Azure%20services%20and%20VM-Series%20automation%20features.%22%2C%22description%22%3A%22%3Cp%3EThe%20VM-Series%20virtualized%20next-generation%20firewall%20allows%20developers%2C%20and%20cloud%20security%20architects%20to%20automate%20and%20deploy%20inline%20firewall%20and%20threat%20prevention%20along%20with%20their%20application%20deployment%20workflows.%20Users%20can%20achieve%20%E2%80%98touchless%E2%80%99%20deployment%20of%20advanced%20firewall%2C%20threat%20prevention%20capabilities%20using%20ARM%20templates%2C%20native%20Azure%20services%2C%20and%20VM-Series%20firewall%20automation%20features%20such%20as%20bootstrapping.%20Auto-scaling%20using%20Azure%20VMSS%20and%20tag-based%20dynamic%20security%20policies%20are%20supported%20using%20the%20Panorama%20Plugin%20for%20Azure.%3C%2Fp%3E%20%5Cn%5Cn%3Cp%3EProtect%20your%20applications%20and%20data%20with%20whitelisting%20and%20segmentation%20policies.%20Policies%20update%20dynamically%20based%20on%20Azure%20tags%20assigned%20to%20application%20VMs%2C%20allowing%20you%20to%20re) |

+| AT&T Detroit | attdetroit1 |

+For each entity (folder/table), there will be three selection states: fully selected, partially selected and not selected. In the example below, if you select ΓÇ£Department 1ΓÇ¥ on the folder hierarchy, ΓÇ£Department 1ΓÇ¥ is considered as fully selected. The parent entities for ΓÇ£Department 1ΓÇ¥ like ΓÇ£CompanyΓÇ¥ and ΓÇ£exampleΓÇ¥ are considered as partially selected as thereΓÇÖre other entities under the same parent not having been selected, for example ΓÇ£Department 2ΓÇ¥. Different icons will be used on UI for entities with different selection states.

+After you run the scan itΓÇÖs likely that there will be new assets added in the source system. By default the future assets under a certain parent will be automatically selected if the parent is fully or partially selected when you run the scan again. In the example above, after you select ΓÇ£Department 1ΓÇ¥ and run the scan, any new assets under folder ΓÇ£Department 1ΓÇ¥ or under ΓÇ£CompanyΓÇ¥ and ΓÇ£exampleΓÇ¥ will be included when you run the scan again.

+A toggle button will be introduced for users to control the automatic inclusion for new assets under partially selected parent. By default the toggle will be turned off and the automatic inclusion behavior for partially selected parent is disabled. In the same example with the toggle turned off, any new assets under partially selected parents like ΓÇ£CompanyΓÇ¥ and ΓÇ£exampleΓÇ¥ will not be included when you run the scan again, only new assets under ΓÇ£Department 1ΓÇ¥ will be included in future scan.

+If the toggle button is turned on, the new assets under a certain parent will be automatically selected if the parent is fully or partially selected when you run the scan again. The inclusion behavior will be the same as before the toggle button is introduced.

+> [!NOTE]

+> * The availability of the toggle button will depend on the data source type. It will be available in public preview for sources including Azure Blob Storage, Azure Data Lake Storage Gen 1, Azure Data Lake Storage Gen 2, Azure Files and Azure Dedicated SQL pool (formerly SQL DW).

+> * For any scans created or scheduled before the toggle button is introduced, the toggle state is set as on and canΓÇÖt be changed. For any scans created or scheduled after the toggle button is introduced, the toggle state canΓÇÖt be changed after the scan is saved. You need to create a new scan to change the toggle state.

+> * When the toggle button is turned off, for sources of storage type like Azure Data Lake Storage Gen 2 it may take up to 4 hours before the [browse by source type](how-to-browse-catalog.md#browse-by-source-type) experience becomes fully available after your scan job is completed.

+### Known limitations

+When the toggle button is turned off:

+* The file entities under a partially selected parent will not be scanned.

+* If all existing entities under a parent are explicitly selected, the parent will be considered as fully selected and any new assets under the parent will be included when you run the scan again.

+If your Azure Subscription moves tenants while you have a Microsoft Purview account, you will need to create a new Microsoft Purview account and re-register and scan your sources.

+Moving tenants is not currently supported for Microsoft Purview.

+> [!NOTE]

+> If Unity displays a warning dialog after importing the OpenXR package asking whether to enable the native platform backends for the new input system, click **No** for now. You will enable it in a later step.

+## Custom ASIM parser development process

+- Develop both a filtering parser and a parameter-less parser.

+- Create a YAML file for the parser as described in [Deploying Parsers](#deploy-parsers) above.

+- Make sure that your parsers pass all [testings](#test-parsers) with no errors. If any warnings are left, [document them](#documenting-accepted-warnings) in the parser YAML file.

+- Create a pull request against the [Microsoft Sentinel GitHub repository](https://github.com/Azure/Azure-Sentinel), including:

+ - Your parsers YAML files in the ASIM parser folders (`/Parsers/ASim<schema>/Parsers`)

+ - Representative sample data according to the [samples submission guidelines](#samples-submission-guidelines).

+ - Test results according to the [test results submission guidelines](#test-results-submission-guidelines).

+### Samples submission guidelines

+Sample data is needed when troubleshooting parser issues and for ensuring future updates to the parser conform to older samples. The samples you submit should include any event variant that the parser supports. Make sure that the sample events include all possible event types, event formats and variations such as events representing successful and failed activity. Also make sure that variations in value formats are represented. For example, if a hostname can be represented as an FQDN or a simple hostname, the sample events should include both formats.

+To submit the event samples, use the following steps:

+- In the `Logs` screen, run a query that will extract from the source table only the events selected by the parser. For example, for the [Infoblox DNS parser](https://github.com/Azure/Azure-Sentinel/blob/master/Parsers/ASimDns/Parsers/ASimDnsInfobloxNIOS.yaml), use the following query:

+``` KQL

+ Syslog

+ | where ProcessName == "named"

+```

+- Export the results using the **Export to CSV** option to a file named `<EventVendor>_<EventProduct>_<EventSchema>_IngestedLogs.csv`, Where `EventProduct`, `EventProduct`, and `EventSchema` are the values assigned by the parser to those fields.

+- In the `Logs` screen, run a query that will output the schema or the parser input table. For example, for the same Infoblox DNS parser, the query is:

+``` KQL

+ Syslog

+ | getschema

+```

+- Export the results using the **Export to CSV** option to a file named `<TableName>_schema.csv`, where `TableName` is the name of source table the parser uses.

+- Include both files in your PR in the folder `/Sample Data/ASIM`. If the file already exists, add your GitHub handle to the name, for example: `<EventVendor>_<EventProduct>_<EventSchema>_SchemaTest_<GitHubHanlde>.csv`

+### Test results submission guidelines

+Test results are important to verify the correctness of the parser and understand any reported exception.

+To submit your test results, use the following steps:

+- Run the parser tests and described in the [testings](#test-parsers) section.

+- and export the tests results using the **Export to CSV** option to files named `<EventVendor>_<EventProduct>_<EventSchema>_SchemaTest.csv` and `<EventVendor>_<EventProduct>_<EventSchema>_DataTest.csv` respectively.

+- Include both files in your PR in the folder `/Parsers/ASim<schema>/Tests`.

+ - `su`, `sudu`, and `sshd` activity reported using Syslog.

+| **Palo Alto PanOS threat logs** | Collected using CEF. | `_Im_WebSession_PaloAltoCEF` |

+| **Zscaler ZIA** | Collected using CEF. | `_Im_WebSessionZscalerZIAVxx` |

+| <a name="url"></a>**Url** | Mandatory | String | The HTTP request URL, including parameters. For `HTTPSession` events, the URL may include the schema and should include the server name. For `WebServerSession` and for `ApiRequest` the URL would typically not include the schema and server, which can be found in the `NetworkApplicationProtocol` and `DstFQDN` fields respectively. <br><br>Example: `https://contoso.com/fo/?k=v&amp;q=u#f` |

+| <a name="servers"></a>**SAP - FTP Servers** | FTP Servers for identification of unauthorized connections. <br><br>- **Client**:such as 100. <br>- **FTP_Server_Name**: FTP server name, such as `http://contoso.com/` <br>-**FTP_Server_Port**:FTP server port, such as 22. <br>- **Description**A meaningful FTP Server description |

+> - This feature is currently available only in the East US, North Europe and West Europe regions, with other regions being added during the public preview.

+> When sessions are enabled on a queue or a subscription, the client applications can ***no longer*** send/receive regular messages. All messages must be sent as part of a session (by setting the session id) and received by accepting the session. Clients may still peek a queue or subscription that has sessions enabled. See [Message browsing](message-browsing.md).