-## Identity verification tools

-|  is a tool that saves time during authentication deployment. It supports multiple languages without the need to write code. It also has a no code debugger for user journeys.|

-(Contains([alternativeSecurityId],"x509:\<SKI>")>0,[alternativeSecurityId],Error("No altSecurityIdentities SKI match found."))

-& IIF(Contains([alternativeSecurityId],"x509:\<SHA1-PUKEY>")>0,[alternativeSecurityId],Error("No altSecurityIdentities SHA1-PUKEY match found."))

-# When to use an Azure Multi-Factor Authentication Provider

-Two-step verification is available by default for global administrators who have Azure Active Directory, and Microsoft 365 users. However, if you wish to take advantage of [advanced features](howto-mfa-mfasettings.md) then you should purchase the full version of Azure Multi-Factor Authentication (MFA).

-An Azure Multi-Factor Auth Provider is used to take advantage of features provided by Azure Multi-Factor Authentication for users who **do not have licenses**.

-## What is an MFA Provider?

-There are two types of Auth providers, and the distinction is around how your Azure subscription is charged. The per-authentication option calculates the number of authentications performed against your tenant in a month. This option is best if you have a number of users authenticating only occasionally. The per-user option calculates the number of individuals in your tenant who perform two-step verification in a month. This option is best if you have some users with licenses but need to extend MFA to more users beyond your licensing limits.

-## Manage your MFA Provider

-You cannot change the usage model (per enabled user or per authentication) after an MFA provider is created.

-If your MFA provider is not linked to an Azure AD tenant, or you link the new MFA provider to a different Azure AD tenant, user settings and configuration options are not transferred. Also, existing Azure MFA Servers need to be reactivated using activation credentials generated through the MFA Provider.

-When you have confirmed that all settings have been migrated, you can browse to the **Azure portal** > **Azure Active Directory** > **Security** > **MFA** > **Providers** and select the ellipses **...** and select **Delete**.

-Self-service password reset (SSPR) gives users in Azure Active Directory (Azure AD) the ability to change or reset their password, with no administrator or help desk involvement. Typically, users open a web browser on another device to access the [SSPR portal](https://aka.ms/sspr). To improve the experience on computers that run Windows 7, 8, 8.1, and 10, you can enable users to reset their password at the Windows sign-in screen.

-

- - If Ctrl+Alt+Del is required by policy in Windows 10, **Reset password** won't work.

-## Windows 10 password reset

-To configure a Windows 10 device for SSPR at the sign-in screen, review the following prerequisites and configuration steps.

-### Windows 10 prerequisites

-### Enable for Windows 10 using Microsoft Endpoint Manager

- - For **Platform** choose *Windows 10 and later*

-1. Select **Create**, then provide a meaningful name for the profile, such as *Windows 10 sign-in screen SSPR*

-### Enable for Windows 10 using the Registry

-### Troubleshooting Windows 10 password reset

-When users reset their password from the sign-in screen of a Windows 10 device, a low-privilege temporary account called `defaultuser1` is created. This account is used to keep the password reset process secure.

-| deviceOwnership | Equals, NotEquals | Supported values are "Personal" for bring your own devices and "Company" for corprate owned devices | (device.deviceOwnership -eq "Company") |

-The OAuth 2.0 On-Behalf-Of flow (OBO) serves the use case where an application invokes a service/web API, which in turn needs to call another service/web API. The idea is to propagate the delegated user identity and permissions through the request chain. For the middle-tier service to make authenticated requests to the downstream service, it needs to secure an access token from the Microsoft identity platform, on behalf of the user.

-The OBO flow only works for user principals at this time. A service principal cannot request an app-only token, send it to an API, and have that API exchange that for another token that represents that original service principal. Additionally, the OBO flow is focused on acting on another party's behalf, known as a delegated scenario - this means that it uses only delegated *scopes*, and not application *roles*, for reasoning about permissions. *Roles* remain attached to the principal (the user) in the flow, never the application operating on the users behalf.

-This article describes how to program directly against the protocol in your application. When possible, we recommend you use the supported Microsoft Authentication Libraries (MSAL) instead to [acquire tokens and call secured web APIs](authentication-flows-app-scenarios.md#scenarios-and-supported-authentication-flows). Also take a look at the [sample apps that use MSAL](sample-v2-code.md).

-As of May 2018, some implicit-flow derived `id_token` can't be used for OBO flow. Single-page apps (SPAs) should pass an **access** token to a middle-tier confidential client to perform OBO flows instead.

-If a client uses the implicit flow to get an id_token, and that client also has wildcards in a reply URL, the id_token can't be used for an OBO flow. However, access tokens acquired through the implicit grant flow can still be redeemed by a confidential client even if the initiating client has a wildcard reply URL registered.

-Additionally, applications with custom signing keys cannot be used as middle-tier API's in the OBO flow (this includes enterprise applications configured for single sign-on). This will result in an error because tokens signed with a key controlled by the client cannot be safely accepted.

-Assume that the user has been authenticated on an application using the [OAuth 2.0 authorization code grant flow](v2-oauth2-auth-code-flow.md) or another login flow. At this point, the application has an access token *for API A* (token A) with the user's claims and consent to access the middle-tier web API (API A). Now, API A needs to make an authenticated request to the downstream web API (API B).

-In this scenario, the middle-tier service has no user interaction to get the user's consent to access the downstream API. Therefore, the option to grant access to the downstream API is presented upfront as a part of the consent step during authentication. To learn how to set this up for your app, see [Gaining consent for the middle-tier application](#gaining-consent-for-the-middle-tier-application).

-| `assertion` | Required | The access token that was sent to the middle-tier API. This token must have an audience (`aud`) claim of the app making this OBO request (the app denoted by the `client-id` field). Applications cannot redeem a token for a different app (so e.g. if a client sends an API a token meant for MS Graph, the API cannot redeem it using OBO. It should instead reject the token). |

-The following HTTP POST requests an access token and refresh token with `user.read` scope for the https://graph.microsoft.com web API.

-A service-to-service access token request with a certificate contains the following parameters:

-| `assertion` | Required | The access token that was sent to the middle-tier API. This token must have an audience (`aud`) claim of the app making this OBO request (the app denoted by the `client-id` field). Applications cannot redeem a token for a different app (so e.g. if a client sends an API a token meant for MS Graph, the API cannot redeem it using OBO. It should instead reject the token). |

-Notice that the parameters are almost the same as in the case of the request by shared secret except that the `client_secret` parameter is replaced by two parameters: a `client_assertion_type` and `client_assertion`.

-The following HTTP POST requests an access token with `user.read` scope for the https://graph.microsoft.com web API with a certificate.

-The following example shows a success response to a request for an access token for the https://graph.microsoft.com web API.

-The above access token is a v1.0-formatted token for Microsoft Graph. This is because the token format is based on the **resource** being accessed and unrelated to the endpoints used to request it. The Microsoft Graph is setup to accept v1.0 tokens, so the Microsoft identity platform produces v1.0 access tokens when a client requests tokens for Microsoft Graph. Other apps may indicate that they want v2.0-format tokens, v1.0-format tokens, or even proprietary or encrypted token formats. Both the v1.0 and v2.0 endpoints can emit either format of token - this way the resource can always get the right format of token regardless of how or where the token was requested by the client.

-| scope |required | A space-separated list of scopes for the token request. For more information, see [scopes](v2-permissions-and-consent.md). SAML itself doesn't have a concept of scopes, but here it is used to identify the target SAML application for which you want to receive a token. For this OBO flow, the scope value must always be the SAML Entity ID with `/.default` appended. For example, in case the SAML application's Entity ID is `https://testapp.contoso.com`, then the requested scope should be `https://testapp.contoso.com/.default`. In case the Entity ID doesn't start with a URI scheme such as `https:`, Azure AD prefixes the Entity ID with `spn:`. In that case you must request the scope `spn:<EntityID>/.default`, for example `spn:testapp/.default` in case the Entity ID is `testapp`. Note that the scope value you request here determines the resulting `Audience` element in the SAML token, which may be important to the SAML application receiving the token. |

-Depending on the architecture or usage of your application, you may consider different strategies for ensuring that the OBO flow is successful. In all cases, the ultimate goal is to ensure proper consent is given so that the client app can call the middle-tier app, and the middle tier app has permission to call the back-end resource.

-> [!NOTE]

-> Previously the Microsoft account system (personal accounts) did not support the "known client applications" field, nor could it show combined consent. This has been added and all apps in the Microsoft identity platform can use the known client application approach for getting consent for OBO calls.

-The middle tier application adds the client to the [known client applications list](reference-app-manifest.md#knownclientapplications-attribute) (`knownClientApplications`) in its manifest. If a consent prompt is triggered by the client, the consent flow will be both for itself and the middle tier application. On the Microsoft identity platform, this is done using the [`.default` scope](v2-permissions-and-consent.md#the-default-scope). When triggering a consent screen using known client applications and `.default`, the consent screen will show permissions for **both** the client to the middle tier API, and also request whatever permissions are required by the middle-tier API. The user provides consent for both applications, and then the OBO flow works.

-The resource service (API) identified in the request should be the API for which the client application is requesting an access token as a result of the user's sign-in. For example, `scope=openid https://middle-tier-api.example.com/.default` (to request an access token for the middle tier API), or `scope=openid offline_access .default` (when a resource is not identified, it defaults to Microsoft Graph).

-Regardless of which API is identified in the authorization request, the consent prompt will be a combined consent prompt including all required permissions configured for the client app, as well as all required permissions configured for each middle tier API listed in the client's required permissions list, and which have identified the client as a known client application.

-Resources can indicate that a given application always has permission to receive certain scopes. This is primarily useful to make connections between a front-end client and a back-end resource more seamless. A resource can [declare multiple pre-authorized applications](reference-app-manifest.md#preauthorizedapplications-attribute) (`preAuthorizedApplications`) in its manifest - any such application can request these permissions in an OBO flow and receive them without the user providing consent.

-After you send the invitation, the user account is automatically added to the directory as a guest.

-After a guest user has been added to the directory in Azure AD, an application owner can send the guest user a direct link to the app they want to share. Azure AD admins can also set up self-service management for gallery or SAML-based apps in their Azure AD tenant. This way, application owners can manage their own guest users, even if the guest users havenΓÇÖt been added to the directory yet. When an app is configured for self-service, the application owner uses their Access Panel to invite a guest user to an app or add a guest user to a group that has access to the app. Self-service app management for gallery and SAML-based apps requires some initial setup by an admin. The following is a summary of the setup steps (for more detailed instructions, see [Prerequisites](#prerequisites) later on this page):

-> * Users are only able to invite guests if they have the **Guest inviter** role.

-

- 

-

-3. At the top of the users list, select **+** on the right-hand side.

- 

- 

- 

- 

- 

-B2B collaboration user accounts are the result of inviting guest users to collaborate by using the guest users' own credentials. When the invitation is initially sent to the guest user, an account is created in your tenant. This account doesnΓÇÖt have any credentials associated with it because authentication is performed by the guest user's identity provider. The **Issuer** property for the guest user account in your directory is set to the host's organization domain until the guest redeems their invitation. In the portal, the **Invitation accepted** property in the invited userΓÇÖs Azure AD portal profile will be set to **No** and querying for `externalUserState` using the Microsoft Graph API will return `Pending Acceptance`.

-After the B2B collaboration user accepts the invitation, the **Issuer** property is updated based on the userΓÇÖs identity provider.

-If the B2B collaboration user is using credentials from another Azure AD organization, the **Issuer** is **External Azure AD**.

-

-If the B2B collaboration user is using a Microsoft account or credentials from another external identity provider, the **Issuer** reflects the identity provider, for example **Microsoft Account**, **google.com**, or **facebook.com**.

-

-For external users who are using internal credentials, the **Issuer** property is set to the hostΓÇÖs organization domain. The **Directory synced** property is **Yes** if the account is homed in the organizationΓÇÖs on-premises Active Directory and synced with Azure AD, or **No** if the account is a cloud-only Azure AD account. The directory sync information is also available via the `onPremisesSyncEnabled` property in Microsoft Graph.

-### Issuer

-This property indicates the userΓÇÖs primary identity provider. A user can have several identity providers, which can be viewed by selecting issuer in the userΓÇÖs profile or by querying the `onPremisesSyncEnabled` property via the Microsoft Graph API.

-> Issuer and UserType are independent properties. A value of issuer does not imply a particular value for UserType

-Issuer property value | Sign-in state

-{issuer URI} | This user is homed in an external organization that doesn't use Azure Active Directory as their identity provider, but instead uses a SAML/WS-Fed-based identity provider. The issuer URI is shown when the issuer field is clicked.

-## September 2022

->[NOTE]

->The Group writeback functionality is currently in Public Preview as we are collecting customer feedback and telemetry. Please refer to [the limitations](https://learn.microsoft.com/azure/active-directory/hybrid/how-to-connect-group-writeback-v2#understand-limitations-of-public-preview) before you enable this functionality.

- New-ADSyncRule `

- -Name 'In from AAD - Group SOAinAAD Delete WriteBackOutOfScope and SoftDelete' `

- -Identifier 'cb871f2d-0f01-4c32-a333-ff809145b947' `

- -Description 'Delete AD groups that fall out of scope of Group Writeback or get Soft Deleted in Azure AD' `

- -Direction 'Inbound' `

- -Precedence $precedenceValue `

- -PrecedenceAfter '00000000-0000-0000-0000-000000000000' `

- -PrecedenceBefore '00000000-0000-0000-0000-000000000000' `

- -SourceObjectType 'group' `

- -TargetObjectType 'group' `

- -Connector 'b891884f-051e-4a83-95af-2544101c9083' `

- -LinkType 'Join' `

- -SoftDeleteExpiryInterval 0 `

- -ImmutableTag '' `

- -OutVariable syncRule

- Add-ADSyncAttributeFlowMapping `

- -SynchronizationRule $syncRule[0] `

- -Destination 'reasonFiltered' `

- -FlowType 'Expression' `

- -ValueMergeType 'Update' `

- -Expression 'IIF((IsPresent([reasonFiltered]) = True) && (InStr([reasonFiltered], "WriteBackOutOfScope") > 0 || InStr([reasonFiltered], "SoftDelete") > 0), "DeleteThisGroupInAD", [reasonFiltered])' `

- -OutVariable syncRule

- New-Object `

- -TypeName 'Microsoft.IdentityManagement.PowerShell.ObjectModel.ScopeCondition' `

- -ArgumentList 'cloudMastered','true','EQUAL' `

- -OutVariable condition0

- Add-ADSyncScopeConditionGroup `

- -SynchronizationRule $syncRule[0] `

- -ScopeConditions @($condition0[0]) `

- -OutVariable syncRule

- New-Object `

- -TypeName 'Microsoft.IdentityManagement.PowerShell.ObjectModel.JoinCondition' `

- -ArgumentList 'cloudAnchor','cloudAnchor',$false `

- -OutVariable condition0

- Add-ADSyncJoinConditionGroup `

- -SynchronizationRule $syncRule[0] `

- -JoinConditions @($condition0[0]) `

- -OutVariable syncRule

- Add-ADSyncRule `

- -SynchronizationRule $syncRule[0]

- Get-ADSyncRule `

- -Identifier 'cb871f2d-0f01-4c32-a333-ff809145b947'

- ```

-1. From the navigation menu, select **Configuration > Global Settings**, and then expand the **VPN Settings** section.

- 

-1. Expand the **SCIM Provisioning** section and enable SCIM provisioning by clicking on **Enable SCIM Provisioning**.

- 

-1. Copy the Base URL and Bearer Token from the Cato Management Application to the SCIM app in the Azure portal:

- 1. In the Cato Management Application (from the **SCIM Provisioning** section), copy the Base URL.

- 1. In the Cato Networks SCIM app in the Azure portal, in the **Provisioning** tab, paste the base URL in the **Tenant URL** field.

- 

- 1. In the Cato Management Application (from the **SCIM Provisioning** section), click **Generate Token** and copy the bearer token.

- 1. In the Cato Networks SCIM app in the Azure portal, paste the bearer token in the **Secret Token** field.

- 

-1. In the Cato Management Application (from the **SCIM Provisioning** section), click **Save**. SCIM Provisioning between your Cato account and Azure AD is configured.

- 

-1. Test the connection between the Azure SCIM app and the Cato Cloud. In the Cato Networks SCIM apps in the Azure portal, in the **Provisioning** tab, click **Test Connection**.

- 

- 

- 

- 

- 

- 

- 

- 

- 

-This tutorial describes the steps you need to perform in both Code42 and Azure Active Directory (Azure AD) to configure automatic user provisioning. When configured, Azure AD automatically provisions and de-provisions users and groups to [Code42](https://www.crashplan.com/) using the Azure AD Provisioning service. For important details on what this service does, how it works, and frequently asked questions, see [Automate user provisioning and deprovisioning to SaaS applications with Azure Active Directory](../app-provisioning/user-provisioning.md).

- 1. **Enable Use of Application Proxy** checkbox, if you have configured your on-premise atlassian application in an App Proxy setup. For App proxy setup , follow the steps on the [Azure AD App Proxy Documentation](/articles/active-directory/app-proxy/what-is-application-proxy.md).

-* [Learn how to review logs and get reports on provisioning activity](../app-provisioning/check-status-user-account-provisioning.md)

- * For App proxy setup , follow the steps on the [Azure AD App Proxy Documentation](/articles/active-directory/app-proxy/what-is-application-proxy.md).

-description: Learn how to configure single sign-on between Azure Active Directory and Lesson.ly.

-# Tutorial: Azure Active Directory single sign-on (SSO) integration with Lesson.ly

-In this tutorial, you'll learn how to integrate Lesson.ly with Azure Active Directory (Azure AD). When you integrate Lesson.ly with Azure AD, you can:

-* Control in Azure AD who has access to Lesson.ly.

-* Enable your users to be automatically signed-in to Lesson.ly with their Azure AD accounts.

-* Lesson.ly single sign-on (SSO) enabled subscription.

-* Lesson.ly supports **SP** initiated SSO.

-* Lesson.ly supports **Just In Time** user provisioning.

-## Add Lesson.ly from the gallery

-To configure the integration of Lesson.ly into Azure AD, you need to add Lesson.ly from the gallery to your list of managed SaaS apps.

-1. In the **Add from the gallery** section, type **Lesson.ly** in the search box.

-1. Select **Lesson.ly** from results panel and then add the app. Wait a few seconds while the app is added to your tenant.

- Alternatively, you can also use the [Enterprise App Configuration Wizard](https://portal.office.com/AdminPortal/home?Q=Docs#/azureadappintegration). In this wizard, you can add an application to your tenant, add users/groups to the app, assign roles, as well as walk through the SSO configuration as well. [Learn more about Microsoft 365 wizards.](/microsoft-365/admin/misc/azure-ad-setup-guides)

-## Configure and test Azure AD SSO for Lesson.ly

-Configure and test Azure AD SSO with Lesson.ly using a test user called **B.Simon**. For SSO to work, you need to establish a link relationship between an Azure AD user and the related user in Lesson.ly.

-To configure and test Azure AD SSO with Lesson.ly, perform the following steps:

-1. **[Configure Lesson.ly SSO](#configure-lessonly-sso)** - to configure the single sign-on settings on application side.

- 1. **[Create Lesson.ly test user](#create-lessonly-test-user)** - to have a counterpart of B.Simon in Lesson.ly that is linked to the Azure AD representation of user.

-1. In the Azure portal, on the **Lesson.ly** application integration page, find the **Manage** section and select **single sign-on**.

-1. Lesson.ly application expects the SAML assertions in a specific format, which requires you to add custom attribute mappings to your SAML token attributes configuration. The following screenshot shows the list of default attributes.

-1. In addition to above, Lesson.ly application expects few more attributes to be passed back in SAML response which are shown below. These attributes are also pre populated but you can review them as per your requirements.

-1. On the **Set up Lesson.ly** section, copy the appropriate URL(s) based on your requirement.

-In this section, you'll enable B.Simon to use Azure single sign-on by granting access to Lesson.ly.

-1. In the applications list, select **Lesson.ly**.

-## Configure Lesson.ly SSO

-To configure single sign-on on **Lesson.ly** side, you need to send the downloaded **Certificate (Base64)** and appropriate copied URLs from Azure portal to [Lesson.ly support team](mailto:support@lessonly.com). They set this setting to have the SAML SSO connection set properly on both sides.

-### Create Lesson.ly test user

-* Click on **Test this application** in Azure portal. This will redirect to Lesson.ly Sign-on URL where you can initiate the login flow.

-* Go to Lesson.ly Sign-on URL directly and initiate the login flow from there.

-* You can use Microsoft My Apps. When you click the Lesson.ly tile in the My Apps, this will redirect to Lesson.ly Sign-on URL. For more information about the My Apps, see [Introduction to the My Apps](https://support.microsoft.com/account-billing/sign-in-and-start-apps-from-the-my-apps-portal-2f3b1bae-0e5a-4a86-a33e-876fbd2a4510).

-Once you configure Lesson.ly you can enforce session control, which protects exfiltration and infiltration of your organizationΓÇÖs sensitive data in real time. Session control extends from Conditional Access. [Learn how to enforce session control with Microsoft Defender for Cloud Apps](/cloud-app-security/proxy-deployment-any-app).

- > The SuccessFactors Writeback provisioning app does not support "group assignment". Only "user assignment" is supported.

-* [Learn how to export and import your provisioning configurations](../app-provisioning/export-import-provisioning-configuration.md)

-description: Learn how to configure Azure Active Directory to automatically provision and deprovision user accounts to Zendesk.

-writer: zhchia

-This tutorial demonstrates the steps to perform in Zendesk and Azure Active Directory (Azure AD) to configure Azure AD to automatically provision and deprovision users and groups to Zendesk.

-> [!NOTE]

-> This tutorial describes a connector that's built on top of the Azure AD user provisioning service. For information on what this service does, how it works, and frequently asked questions, see [Automate user provisioning and deprovisioning to software-as-a-service (SaaS) applications with Azure Active Directory](../app-provisioning/user-provisioning.md).

-The scenario outlined in this tutorial assumes that you have:

-* An Azure AD tenant.

-* A user account in Zendesk with admin permissions.

-## Add Zendesk from the Azure Marketplace

-Before you configure Zendesk for automatic user provisioning with Azure AD, add Zendesk from the Azure Marketplace to your list of managed SaaS applications.

-To add Zendesk from the Marketplace, follow these steps.

- 

-2. Go to **Enterprise applications**, and then select **All applications**.

- 

-3. To add a new application, select **New application** at the top of the dialog box.

- 

-4. In the search box, enter **Zendesk** and select **Zendesk** from the result panel. To add the application, select **Add**.

- 

-## Assign users to Zendesk

-Azure Active Directory uses a concept called *assignments* to determine which users should receive access to selected apps. In the context of automatic user provisioning, only the users or groups that were assigned to an application in Azure AD are synchronized.

-Before you configure and enable automatic user provisioning, decide which users or groups in Azure AD need access to Zendesk. To assign these users or groups to Zendesk, follow the instructions in [Assign a user or group to an enterprise app](../manage-apps/assign-user-or-group-access-portal.md).

-## Configure automatic user provisioning to Zendesk

-This section guides you through the steps to configure the Azure AD provisioning service. Use it to create, update, and disable users or groups in Zendesk based on user or group assignments in Azure AD.

-> [!TIP]

-> You also can enable SAML-based single sign-on for Zendesk. Follow the instructions in the [Zendesk single sign-on tutorial](zendesk-tutorial.md). Single sign-on can be configured independently of automatic user provisioning, although these two features complement each other.

-1. Sign in to the [Azure portal](https://portal.azure.com). Select **Enterprise applications** > **All applications** > **Zendesk**.

- 

-2. In the applications list, select **Zendesk**.

- 

-3. Select the **Provisioning** tab.

- 

-4. Set the **Provisioning Mode** to **Automatic**.

- 

-5. Under the **Admin Credentials** section, input the admin username, secret token, and domain of your Zendesk account. Examples of these values are:

-6. The secret token for your Zendesk account is located in **Admin** > **API** > **Settings**. Make sure that **Token Access** is set to **Enabled**.

- 

- 

-7. After you fill in the boxes shown in Step 5, select **Test Connection** to make sure that Azure AD can connect to Zendesk. If the connection fails, make sure your Zendesk account has admin permissions and try again.

- 

- 

- 

- 

- 

- 

- 

- 

- 

-## Additional resources

-* [Manage user account provisioning for enterprise apps](../app-provisioning/configure-automatic-user-provisioning-portal.md)

-<!--Image references-->

-[1]: ./media/zendesk-tutorial/tutorial_general_01.png

-[2]: ./media/zendesk-tutorial/tutorial_general_02.png

-[3]: ./media/zendesk-tutorial/tutorial_general_03.png

-The Secrets Store CSI Driver on Azure Kubernetes Service (AKS) provides a variety of methods of identity-based access to your Azure key vault. This article outlines these methods and how to use them to access your key vault and its contents from your AKS cluster. For more information, see [Use the Secrets Store CSI Driver][csi-secrets-store-driver].

-An Azure AD workload identity (preview) is an identity used by an application running on a pod that can authenticate itself against other Azure services that support it, such as Storage or SQL. It integrates with the capabilities native to Kubernetes to federate with external identity providers. In this security model, the AKS cluster acts as token issuer, Azure Active Directory uses OpenID Connect to discover public signing keys and verify the authenticity of the service account token before exchanging it for an Azure AD token. Your workload can exchange a service account token projected to its volume for an Azure AD token using the Azure Identity client library using the Azure SDK or the Microsoft Authentication Library (MSAL).

-1. Use the Azure CLI [az account set][az-account-set] command to set a specific subscription to be the current active subscription.

- az account set --subscription "subscriptionID"

-2. Use the Azure CLI [az account set][az-account-set] command to set a specific subscription to be the current active subscription. Then use the [az identity create][az-identity-create] command to create a managed identity.

- az account set --subscription "subscriptionID"

- ```azurecli

- az identity create --name "userAssignedIdentityName" --resource-group "resourceGroupName" --location "location" --subscription "subscriptionID"

- ```

-3. You need to set an access policy that grants the workload identity permission to access the Key Vault secrets, access keys, and certificates. The rights are assigned using the [az keyvault set-policy][az-keyvault-set-policy] command as shown below.

- ```azurecli

- az keyvault set-policy -n $KEYVAULT_NAME --key-permissions get --spn $APPLICATION_CLIENT_ID

- az keyvault set-policy -n $KEYVAULT_NAME --secret-permissions get --spn $APPLICATION_CLIENT_ID

- az keyvault set-policy -n $KEYVAULT_NAME --certificate-permissions get --spn $APPLICATION_CLIENT_ID

- ```

-4. Run the [az aks show][az-aks-show] command to get the AKS cluster OIDC issuer URL, and replace the default value for the cluster name and the resource group name.

- ```azurecli

- az aks show --resource-group resourceGroupName --name clusterName --query "oidcIssuerProfile.issuerUrl" -otsv

-5. Establish a federated identity credential between the Azure AD application and the service account issuer and subject. Get the object ID of the Azure AD application. Update the values for `serviceAccountName` and `serviceAccountNamespace` with the Kubernetes service account name and its namespace.

- export APPLICATION_OBJECT_ID="$(az ad app show --id ${APPLICATION_CLIENT_ID} --query id -otsv)"

- export SERVICE_ACCOUNT_NAME=serviceAccountName

- export SERVICE_ACCOUNT_NAMESPACE=serviceAccountNamespace

- Then add the federated identity credential by first copying and pasting the following multi-line input in the Azure CLI.

- ```azurecli

- cat <<EOF > body.json

- {

- "name": "kubernetes-federated-credential",

- "issuer": "${SERVICE_ACCOUNT_ISSUER}",

- "subject": "system:serviceaccount:${SERVICE_ACCOUNT_NAMESPACE}:${SERVICE_ACCOUNT_NAME}",

- "description": "Kubernetes service account federated credential",

- "audiences": [

- "api://AzureADTokenExchange"

- ]

- }

- EOF

- Next, use the [az identity federated-credential create][az-identity-federated-credential-create] command to create the federated identity credential between the Managed Identity, the service account issuer, and the subject. Replace the values `resourceGroupName`, `userAssignedIdentityName`, and `federatedIdentityName`.

- ```azurecli

- az identity federated-credential create --name federatedIdentityName --identity-name userAssignedIdentityName --resource-group resourceGroupName --issuer ${AKS_OIDC_ISSUER} --subject ${SERVICE_ACCOUNT_NAMESPACE}:${SERVICE_ACCOUNT_NAME}"

-6. Deploy your secretproviderclass and application by setting the `clientID` in the `SecretProviderClass` to the client ID of the Azure AD application.

- clientID: "${APPLICATION_CLIENT_ID}"

-1. Verify that your virtual machine scale set or availability set nodes have their own system-assigned identity:

-description: Learn more about using Dapr on your Azure Kubernetes Service (AKS) cluster to develop applications.

-# Dapr

-Distributed Application Runtime (Dapr) offers APIs that simplify microservice development and implementation. Running as a sidecar process in tandem with your applications, Dapr APIs abstract away common complexities developers regularly encounter when building distributed applications, such as service discovery, message broker integration, encryption, observability, and secret management. Whether your inter-application communication is direct service-to-service, or pub/sub messaging, Dapr helps you write simple, portable, resilient, and secured microservices.

-Dapr is incrementally adoptable ΓÇô the API building blocks can be used as the need arises. Use one, several, or all to develop your application faster.

-## Capabilities and features

-Dapr provides the following set of capabilities to help with your microservice development on AKS:

-* Easy provisioning of Dapr on AKS through [cluster extensions][cluster-extensions].

-* Portability enabled through HTTP and gRPC APIs which abstract underlying technologies choices

-* Reliable, secure, and resilient service-to-service calls through HTTP and gRPC APIs

-* Publish and subscribe messaging made easy with support for CloudEvent filtering and ΓÇ£at-least-onceΓÇ¥ semantics for message delivery

-* Pluggable observability and monitoring through Open Telemetry API collector

-* Works independent of language, while also offering language specific SDKs

-* Integration with VS Code through the Dapr extension

-* [More APIs for solving distributed application challenges][dapr-blocks]

-## Frequently asked questions

-### How do Dapr and Service meshes compare?

-A: Where a service mesh is defined as a networking service mesh, Dapr is not a service mesh. While Dapr and service meshes do offer some overlapping capabilities, a service mesh is focused on networking concerns, whereas Dapr is focused on providing building blocks that make it easier for developers to build applications as microservices. Dapr is developer-centric, while service meshes are infrastructure-centric.

-Some common capabilities that Dapr shares with service meshes include:

-* Secure service-to-service communication with mTLS encryption

-* Service-to-service metric collection

-* Service-to-service distributed tracing

-* Resiliency through retries

-In addition, Dapr provides other application-level building blocks for state management, pub/sub messaging, actors, and more. However, Dapr does not provide capabilities for traffic behavior such as routing or traffic splitting. If your solution would benefit from the traffic splitting a service mesh provides, consider using [Open Service Mesh][osm-docs].

-For more information on Dapr and service meshes, and how they can be used together, visit the [Dapr documentation][dapr-docs].

-### How does the Dapr secrets API compare to the Secrets Store CSI driver?

-Both the Dapr secrets API and the managed Secrets Store CSI driver allow for the integration of secrets held in an external store, abstracting secret store technology from application code. The Secrets Store CSI driver mounts secrets held in Azure Key Vault as a CSI volume for consumption by an application. Dapr exposes secrets via a RESTful API that can be called by application code and can be configured with assorted secret stores. The following table lists the capabilities of each offering:

-| | Dapr secrets API | Secrets Store CSI driver |

-| | | |

-| **Supported secrets stores** | Local environment variables (for Development); Local file (for Development); Kubernetes Secrets; AWS Secrets Manager; Azure Key Vault secret store; Azure Key Vault with Managed Identities on Kubernetes; GCP Secret Manager; HashiCorp Vault | Azure Key Vault secret store|

-| **Accessing secrets in application code** | Call the Dapr secrets API | Access the mounted volume or sync mounted content as a Kubernetes secret and set an environment variable |

-| **Secret rotation** | New API calls obtain the updated secrets | Polls for secrets and updates the mount at a configurable interval |

-| **Logging and metrics** | The Dapr sidecar generates logs, which can be configured with collectors such as Azure Monitor, emits metrics via Prometheus, and exposes an HTTP endpoint for health checks | Emits driver and Azure Key Vault provider metrics via Prometheus |

-For more information on the secret management in Dapr, see the [secrets management building block overview][dapr-secrets-block].

-For more information on the Secrets Store CSI driver and Azure Key Vault provider, see the [Secrets Store CSI driver overview][csi-secrets-store].

-### How does the managed Dapr cluster extension compare to the open source Dapr offering?

-The managed Dapr cluster extension is the easiest method to provision Dapr on an AKS cluster. With the extension, you're able to offload management of the Dapr runtime version by opting into automatic upgrades. Additionally, the extension installs Dapr with smart defaults (for example, provisioning the Dapr control plane in high availability mode).

-When installing Dapr OSS via helm or the Dapr CLI, runtime versions and configuration options are the responsibility of developers and cluster maintainers.

-Lastly, the Dapr extension is an extension of AKS, therefore you can expect the same support policy as other AKS features.

-[Learn more about migrating from Dapr OSS to the Dapr extension for AKS][dapr-migration].

-### How can I switch to using the Dapr extension if IΓÇÖve already installed Dapr via a method, such as Helm?

-Recommended guidance is to completely uninstall Dapr from the AKS cluster and reinstall it via the cluster extension.

-If you install Dapr through the AKS extension, our recommendation is to continue using the extension for future management of Dapr instead of the Dapr CLI. Combining the two tools can cause conflicts and result in undesired behavior.

-## Next Steps

-After learning about Dapr and some of the challenges it solves, try [installing the dapr extension][dapr-extension].

-<!-- Links Internal -->

-[csi-secrets-store]: ./csi-secrets-store-driver.md

-[osm-docs]: ./open-service-mesh-about.md

-[cluster-extensions]: ./cluster-extensions.md

-[dapr-quickstart]: ./quickstart-dapr.md

-[dapr-migration]: ./dapr-migration.md

-[dapr-extension]: ./dapr.md

-<!-- Links External -->

-[dapr-docs]: https://docs.dapr.io/

-[dapr-blocks]: https://docs.dapr.io/concepts/building-blocks-concept/

-[dapr-secrets-block]: https://docs.dapr.io/developing-applications/building-blocks/secrets/secrets-overview/

-| 1.20 | Dec-08-20 | Jan 2021 | Mar 2021 | 1.23 GA |

-The `validate-jwt` policy enforces existence and validity of a JSON web token (JWT) extracted from a specified HTTP header, extracted from a specified query parameter, or matching a specific value.

-description: Learn how to manage protocols (TLS) and ciphers (DES) in Azure API Management.

-Azure API Management supports multiple versions of Transport Layer Security (TLS) protocol for:

-* The 3DES cipher

-This guide shows you how to manage protocols and ciphers configuration for an Azure API Management instance.

-

-## How to manage TLS protocols and 3DES cipher

-1. Navigate to your **API Management instance** in the Azure portal.

-1. Scroll to the **Security** section in the side menu.

-1. Under the Security section, select **Protocols + ciphers**.

-1. Click **Save**. Changes will be applied within an hour.

-> Some protocols or cipher suites (like backend-side TLS 1.2) can't be enabled or disabled from the Azure portal. Instead, you'll need to apply the REST call. Use the `properties.customProperties` structure in the [Create/Update API Management Service REST API](/rest/api/apimanagement/current-ga/api-management-service/create-or-update) article.

-For additional settings that customize build automation, see [Oryx configuration](https://github.com/microsoft/Oryx/blob/master/doc/configuration.md).

-1. **Database**: If your app depends on a database, provision the necessary resources on Azure as well. See [Tutorial: Deploy a Django web app with PostgreSQL - create a database](tutorial-python-postgresql-app.md#3create-the-postgresql-database-in-azure) for an example.

-1. **App service resources**: Create a resource group, App Service Plan, and App Service web app to host your application. You can most easily do this by doing an initial deployment of your code through the Azure CLI command [`az webapp up`](/cli/azure/webapp?az-webapp-up). Or, you can create and deploy resources as shown in [Tutorial: Deploy a Django web app with PostgreSQL](tutorial-python-postgresql-app.md). Replace the names of the resource group, App Service Plan, and the web app to be more suitable for your application.

- - Database connections, for example, are often managed through such settings, as shown in [Tutorial: Deploy a Django web app with PostgreSQL - configure variables to connect the database](tutorial-python-postgresql-app.md#5connect-the-web-app-to-the-database).

-1. **Custom actions**: To perform actions within the App Service container that hosts your app, such as Django database migrations, you can [connect to the container through SSH](configure-linux-open-ssh-session.md). For an example of running Django database migrations, see [Tutorial: Deploy a Django web app with PostgreSQL - run database migrations](tutorial-python-postgresql-app.md#7migrate-app-database).

-1. Add `whitenoise` to your *requirements.txt* file. [Whitenoise](http://whitenoise.evans.io/en/stable/) (whitenoise.evans.io) is a Python package that makes it simple for a production Django app to serve it's own static files. Whitenoise specifically serves those files that are found in the folder specified by the Django `STATIC_ROOT` variable.

-If your Flask web app includes static front-end files, first follow the instructions on [managing static files](https://flask.palletsprojects.com/en/2.1.x/tutorial/static/) in the Flask documentation. For an example of serving static files in a Flask application, see the [quickstart sample Flask application](https://github.com/Azure-Samples/msdocs-python-flask-webapp-quickstart) on Github.

-The following sections provide additional details for each option.

-If you want more specific control over the startup command, use a [custom startup command](#customize-startup-command), replace `<module>` with the name of folder that contains *wsgi.py*, and add a `--chdir` argument if that module is not in the project root. For example, if your *wsgi.py* is located under *knboard/backend/config* from your project root, use the arguments `--chdir knboard/backend config.wsgi`.

-If your main app module is contained in a different file, use a different name for the app object, or you want to provide additional arguments to Gunicorn, use a [custom startup command](#customize-startup-command).

-App Service ignores any errors that occur when processing a custom startup command or file, then continues its startup process by looking for Django and Flask apps. If you don't see the behavior you expect, check that your startup command or file is error-free and that a startup command file is deployed to App Service along with your app code. You can also check the [Diagnostic logs](#access-diagnostic-logs) for additional information. Also check the app's **Diagnose and solve problems** page on the [Azure portal](https://portal.azure.com).

- For more information, see [Running Gunicorn](https://docs.gunicorn.org/en/stable/run.html) (docs.gunicorn.org). If you are using auto-scale rules to scale your web app up and down, you should also dynamically set the number of gunicorn workers using the `NUM_CORES` environment variable in your startup command, for example: `--workers $((($NUM_CORES*2)+1))`. For more information on setting the recommended number of gunicorn workers, see [the Gunicorn FAQ](https://docs.gunicorn.org/en/stable/design.html#how-many-workers)

-Build issues such as incorrect dependencies in *requirements.txt* and errors in pre- or post-build scripts will appear in these logs. Errors also appear if your requirements file is not exactly named *requirements.txt* or does not appear in the root folder of your project.

-The following sections provide additional guidance for specific issues.

-If you see an error like `ModuleNotFoundError: No module named 'example'`, this means that Python could not find one or more of your modules when the application started. This most often occurs if you deploy your virtual environment with your code. Virtual environments are not portable, so a virtual environment should not be deployed with your application code. Instead, let Oryx create a virtual environment and install your packages on the web app by creating an app setting, `SCM_DO_BUILD_DURING_DEPLOYMENT`, and setting it to `1`. This will force Oryx to install your packages whenever you deploy to App Service. For more information, please see [this article on virtual environment portability](https://azure.github.io/AppService/2020/12/11/cicd-for-python-apps.html).

-If you're encountering this error with the sample in [Tutorial: Deploy a Django web app with PostgreSQL](tutorial-python-postgresql-app.md), check that you completed the steps in [Configure environment variables to connect the database](tutorial-python-postgresql-app.md#5connect-the-web-app-to-the-database).

-> [HTML (on Windows or Linux)](quickstart-html.md)

-In this tutorial, you'll deploy a data-driven Python web app (**[Django](https://www.djangoproject.com/)** or **[Flask](https://flask.palletsprojects.com/)**) with the **[Azure Database for PostgreSQL](../postgresql/index.yml)** relational database service. The Python app is hosted in a fully managed **[Azure App Service](./overview.md#app-service-on-linux)** which supports [Python 3.7 or higher](https://www.python.org/downloads/) in a Linux server environment. You can start with a basic pricing tier that can be scaled up at any later time.

-* [Python 3.7 or higher](https://www.python.org/downloads/) installed locally.

-* [PostgreSQL](https://www.postgresql.org/download/) installed locally.

-## 1 - Sample application

-Sample Python applications using the Flask and Django framework are provided to help you follow along with this tutorial. Download or clone one of the sample applications to your local workstation.

-To run the application locally, navigate into the application folder:

-### [Flask](#tab/flask)

-```bash

-cd msdocs-flask-postgresql-sample-app

-```

-### [Django](#tab/django)

-```bash

-cd msdocs-django-postgresql-sample-app

-```

-Create a virtual environment for the app:

-Install the dependencies:

-```Console

-pip install -r requirements.txt

-```

-> [!NOTE]

-> If you are following along with this tutorial with your own app, look at the *requirements.txt* file description in each project's *README.md* file ([Flask](https://github.com/Azure-Samples/msdocs-flask-postgresql-sample-app/blob/main/README.md), [Django](https://github.com/Azure-Samples/msdocs-django-postgresql-sample-app/blob/main/README.md)) to see what packages you'll need.

-This sample application requires an *.env* file describing how to connect to your local PostgreSQL instance. Create an *.env* file as shown below using the *.env.sample* file as a guide. Set the value of `DBNAME` to the name of an existing database in your local PostgreSQL instance. This tutorial assumes the database name is *restaurant*. Set the values of `DBHOST`, `DBUSER`, and `DBPASS` as appropriate for your local PostgreSQL instance.

-For Django, you can use SQLite locally instead of PostgreSQL by following the instructions in the comments of the [*settings.py*](https://github.com/Azure-Samples/msdocs-django-postgresql-sample-app/blob/main/azureproject/settings.py) file.

-Create the `restaurant` and `review` database tables:

-### [Flask](#tab/flask)

-```Console

-flask db init

-flask db migrate -m "initial migration"

-```

-### [Django](#tab/django)

-```Console

-python manage.py migrate

-```

-Run the app:

-```Console

-```Console

-### [Flask](#tab/flask)

-In a web browser, go to the sample application at `http://127.0.0.1:5000` and add some restaurants and restaurant reviews to see how the app works.

-### [Django](#tab/django)

-In a web browser, go to the sample application at `http://127.0.0.1:8000` and add some restaurants and restaurant reviews to see how the app works.

-> [!TIP]

-> With Django, you can create users with the `python manage.py createsuperuser` command like you would with a typical Django app. For more information, see the documentation for [django django-admin and manage.py](https://docs.djangoproject.com/en/1.8/ref/django-admin/). Use the superuser account to access the `/admin` portion of the web site. For Flask, use an extension such as [Flask-admin](https://github.com/flask-admin/flask-admin) to provide the same functionality.

-Having issues? [Let us know](https://aka.ms/DjangoCLITutorialHelp).

-## 2 - Create a web app in Azure

-To host your application in Azure, you need to create Azure App Service web app.

-### [Azure portal](#tab/azure-portal)

-Sign in to the [Azure portal](https://portal.azure.com/) and follow these steps to create your Azure App Service resource.

-| Instructions | Screenshot |

-|:-|--:|

-| [!INCLUDE [A screenshot showing how to use the search box in the top tool bar to find App Services in Azure](<./includes/tutorial-python-postgresql-app/create-app-service-azure-portal-1.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-app-service-azure-portal-1-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-app-service-azure-portal-1.png" alt-text="A screenshot showing how to use the search box in the top tool bar to find App Services in Azure portal." ::: |

-| [!INCLUDE [A screenshot showing the location of the Create button on the App Services page in the Azure portal](<./includes/tutorial-python-postgresql-app/create-app-service-azure-portal-2.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-app-service-azure-portal-2-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-app-service-azure-portal-2.png" alt-text="A screenshot showing the location of the Create button on the App Services page in the Azure portal." ::: |

-| [!INCLUDE [A screenshot showing how to fill out the form to create a new App Service in the Azure portal](<./includes/tutorial-python-postgresql-app/create-app-service-azure-portal-3.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-app-service-azure-portal-3-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-app-service-azure-portal-3.png" alt-text="A screenshot showing how to fill out the form to create a new App Service in the Azure portal." ::: |

-| [!INCLUDE [A screenshot showing how to select the basic App Service plan in the Azure portal](<./includes/tutorial-python-postgresql-app/create-app-service-azure-portal-4.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-app-service-azure-portal-4-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-app-service-azure-portal-4.png" alt-text="A screenshot showing how to select the basic App Service plan in the Azure portal." ::: |

-| [!INCLUDE [A screenshot showing the location of the Review plus Create button in the Azure portal](<./includes/tutorial-python-postgresql-app/create-app-service-azure-portal-5.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-app-service-azure-portal-5-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-app-service-azure-portal-5.png" alt-text="A screenshot showing the location of the Review plus Create button in the Azure portal." ::: |

-### [VS Code](#tab/vscode-aztools)

-To create Azure resources in VS Code, you must have the [Azure Tools extension pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-node-azure-pack) installed and be signed into Azure from VS Code.

-> [!div class="nextstepaction"]

-> [Download Azure Tools extension pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-node-azure-pack)

-| Instructions | Screenshot |

-|:-|--:|

-| [!INCLUDE [A screenshot showing how to use the search box in the top tool bar to find App Services in Azure](<./includes/tutorial-python-postgresql-app/create-app-service-visual-studio-code-1.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-1-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-1.png" alt-text="A screenshot showing how to find the VS Code Azure extension in VS Code." ::: |

-| [!INCLUDE [A screenshot showing how to use the search box in the top tool bar to find App Services in Azure](<./includes/tutorial-python-postgresql-app/create-app-service-visual-studio-code-2.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-2-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-2.png" alt-text="A screenshot showing how to create a new web app in VS Code." ::: |

-| [!INCLUDE [A screenshot showing how to use the search box in the top tool bar to find App Services in Azure](<./includes/tutorial-python-postgresql-app/create-app-service-visual-studio-code-3.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-3-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-3.png" alt-text="A screenshot showing how to use the search box in the top tool bar of VS Code to name a new web app." ::: |

-| [!INCLUDE [A screenshot showing how to use the search box in the top tool bar to find App Services in Azure](<./includes/tutorial-python-postgresql-app/create-app-service-visual-studio-code-4.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-4a-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-4a.png" alt-text="A screenshot showing how to use the search box in the top tool bar of VS Code to create a new resource group." ::: :::image type="content" source="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-4b-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-4b.png" alt-text="A screenshot showing how to use the search box in the top tool bar of VS Code to name a new resource group." ::: |

-| [!INCLUDE [A screenshot showing how to use the search box in the top tool bar to find App Services in Azure](<./includes/tutorial-python-postgresql-app/create-app-service-visual-studio-code-5.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-5-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-5.png" alt-text="A screenshot showing how to use the search box in the top tool bar of VS Code to set the runtime stack of a web app in Azure." ::: |

-| [!INCLUDE [A screenshot showing how to use the search box in the top tool bar to find App Services in Azure](<./includes/tutorial-python-postgresql-app/create-app-service-visual-studio-code-6.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-6-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-6.png" alt-text="A screenshot showing how to use the search box in the top tool bar of VS Code to set location for new web app resource in Azure." ::: |

-| [!INCLUDE [A screenshot showing how to use the search box in the top tool bar to find App Services in Azure](<./includes/tutorial-python-postgresql-app/create-app-service-visual-studio-code-7.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-7a-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-7a.png" alt-text="A screenshot showing how to use the search box in the top tool bar of VS Code to create a new App Service plan in Azure." ::: :::image type="content" source="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-7b-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-7b.png" alt-text="A screenshot showing how to use the search box in the top tool bar in VS Code to name a new App Service plan in Azure." ::: |

-| [!INCLUDE [A screenshot showing how to use the search box in the top tool bar to find App Services in Azure](<./includes/tutorial-python-postgresql-app/create-app-service-visual-studio-code-8.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-8-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-8.png" alt-text="A screenshot showing how to use the search box in the top tool bar in VS Code to select a pricing tier for a web app in Azure." ::: |

-| [!INCLUDE [A screenshot showing how to use the search box in the top tool bar to find App Services in Azure](<./includes/tutorial-python-postgresql-app/create-app-service-visual-studio-code-9.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-9-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-9.png" alt-text="A screenshot showing how to use the search box in the top tool bar of VS Code to skip configuring Application Insights for a web app in Azure." ::: |

-| [!INCLUDE [A screenshot showing how to use the search box in the top tool bar to find App Services in Azure](<./includes/tutorial-python-postgresql-app/create-app-service-visual-studio-code-10.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-10a-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-10a.png" alt-text="A screenshot showing deployment with Visual Studio Code and View Output Button." ::: :::image type="content" source="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-10b-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-10b.png" alt-text="A screenshot showing deployment with Visual Studio Code and how to view App Service in Azure portal." ::: :::image type="content" source="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-10c-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-app-service-visual-studio-code-10c.png" alt-text="A screenshot showing the default App Service web page when no app has been deployed." ::: |

-### [Azure CLI](#tab/azure-cli)

-Azure CLI commands can be run in the [Azure Cloud Shell](https://shell.azure.com) or on a workstation with the [Azure CLI installed](/cli/azure/install-azure-cli).

-Having issues? Refer first to the [Troubleshooting guide](configure-language-python.md#troubleshooting), otherwise, [let us know](https://aka.ms/DjangoCLITutorialHelp).

-## 3 - Create the PostgreSQL database in Azure

-You can create a PostgreSQL database in Azure using the [Azure portal](https://portal.azure.com/), Visual Studio Code, or the Azure CLI.

-### [Azure portal](#tab/azure-portal)

-Sign in to the [Azure portal](https://portal.azure.com/) and follow these steps to create your Azure Database for PostgreSQL resource.

-| Instructions | Screenshot |

-|:-|--:|

-| [!INCLUDE [A screenshot showing how to use the search box in the top tool bar to find Postgres Services in Azure](<./includes/tutorial-python-postgresql-app/create-postgres-service-azure-portal-1.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-postgres-service-azure-portal-1-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-postgres-service-azure-portal-1.png" alt-text="A screenshot showing how to use the search box in the top tool bar to find Postgres Services in the Azure portal." ::: |

-| [!INCLUDE [A screenshot showing the location of the Create button on the Azure Database for PostgreSQL servers page in the Azure portal](<./includes/tutorial-python-postgresql-app/create-postgres-service-azure-portal-2.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-postgres-service-azure-portal-2-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-postgres-service-azure-portal-2.png" alt-text="A screenshot showing the location of the Create button on the Azure Database for PostgreSQL servers page in the Azure portal." ::: |

-| [!INCLUDE [A screenshot showing the location of the Create button on the Azure Database for PostgreSQL Flexible server deployment option page in the Azure portal](<./includes/tutorial-python-postgresql-app/create-postgres-service-azure-portal-3.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-postgres-service-azure-portal-3-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-postgres-service-azure-portal-3.png" alt-text="A screenshot showing the location of the Create Flexible Server button on the Azure Database for PostgreSQL deployment option page in the Azure portal." ::: |

-| [!INCLUDE [A screenshot showing how to fill out the form to create a new Azure Database for PostgreSQL Flexible server in the Azure portal](<./includes/tutorial-python-postgresql-app/create-postgres-service-azure-portal-4.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-postgres-service-azure-portal-4-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-postgres-service-azure-portal-4.png" alt-text="A screenshot showing how to fill out the form to create a new Azure Database for PostgreSQL in the Azure portal." ::: |

-| [!INCLUDE [A screenshot showing how to select and configure the compute and storage for PostgreSQL Flexible server in the Azure portal](<./includes/tutorial-python-postgresql-app/create-postgres-service-azure-portal-5.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-postgres-service-azure-portal-5-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-postgres-service-azure-portal-5.png" alt-text="A screenshot showing how to select and configure the basic database service plan in the Azure portal." ::: |

-| [!INCLUDE [A screenshot showing creating administrator account information for the PostgreSQL Flexible server in in the Azure portal](<./includes/tutorial-python-postgresql-app/create-postgres-service-azure-portal-6.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-postgres-service-azure-portal-6-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-postgres-service-azure-portal-6.png" alt-text="Creating administrator account information for the PostgreSQL Flexible server in the Azure portal." ::: |

-| [!INCLUDE [A screenshot showing adding current IP as a firewall rule for the PostgreSQL Flexible server in the Azure portal](<./includes/tutorial-python-postgresql-app/create-postgres-service-azure-portal-7.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-postgres-service-azure-portal-7-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-postgres-service-azure-portal-7.png" alt-text="A screenshot showing adding current IP as a firewall rule for the PostgreSQL Flexible server in the Azure portal." ::: |

-### [VS Code](#tab/vscode-aztools)

-Follow these steps to create your Azure Database for PostgreSQL resource using the [Azure Tools extension pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-node-azure-pack) in Visual Studio Code.

-| Instructions | Screenshot |

-|:-|--:|

-| [!INCLUDE [Open Azure Extension - Database in VS Code](<./includes/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-1.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-1-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-1.png" alt-text="A screenshot showing how to open Azure Extension for Database in VS Code." ::: |

-| [!INCLUDE [Create database server in VS Code](<./includes/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-2.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-2-240px.png" alt-text="A screenshot showing how create a database server in VSCode." lightbox="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-2.png"::: |

-| [!INCLUDE [Azure portal - create new resource](<./includes/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-3.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-3-240px.png" alt-text="A screenshot how to create a new resource in VS Code." lightbox="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-3.png"::: |

-| [!INCLUDE [Azure portal - create new resource](<./includes/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-4.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-4a-240px.png" alt-text="A screenshot showing how to create a new resource in the VS Code - server name." lightbox="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-4a.png"::: :::image type="content" source="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-4b-240px.png" alt-text="A screenshot showing how to create a new resource in VS Code - SKU." lightbox="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-4b.png"::: :::image type="content" source="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-4c-240px.png" alt-text="A screenshot showing how to create a new resource in VS Code - admin account name." lightbox="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-4c.png"::: :::image type="content" source="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-4d-240px.png" alt-text="A screenshot showing how to create a new resource in VS Code - admin account password." lightbox="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-4d.png"::: :::image type="content" source="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-4e-240px.png" alt-text="A screenshot showing how to create a new resource in VS Code - resource group." lightbox="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-4e.png"::: :::image type="content" source="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-4f-240px.png" alt-text="A screenshot showing how to create a new resource in VS Code - location." lightbox="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-4f.png":::|

-| [!INCLUDE [Configure access for the database in the Azure portal](<./includes/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-5.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-5a-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-5a.png" alt-text="A screenshot showing how to configure access for a database by configuring a firewall rule in VS Code." ::: :::image type="content" source="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-5b-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-5b.png" alt-text="A screenshot showing how to select the correct PostgreSQL server to add a firewall rule in VS Code." ::: :::image type="content" source="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-5c-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-5c.png" alt-text="A screenshot showing a dialog box asking to add firewall rule for local IP address in VS Code." :::|

-| [!INCLUDE [Create a new Azure resource in the Azure portal](<./includes/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-6.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-6-240px.png" lightbox="./media/tutorial-python-postgresql-app/create-postgres-service-visual-studio-code-6.png" alt-text="A screenshot showing how to create a PostgreSQL database server in VS Code." ::: |

-### [Azure CLI](#tab/azure-cli)

-Run `az login` to sign in to and follow these steps to create your Azure Database for PostgreSQL resource.

-## 4 - Allow web app to access the database

-After the Azure Database for PostgreSQL server is created, configure access to the server from the web app by adding a firewall rule. This can be done through the Azure portal or the Azure CLI.

-If you're working in VS Code, right-click the database server and select **Open in Portal** to go to the Azure portal. Or, go to the [Azure Cloud Shell](https://shell.azure.com) and run the Azure CLI commands.

-### [Azure portal](#tab/azure-portal-access)

-| Instructions | Screenshot |

-|:-|--:|

-| [!INCLUDE [A screenshot showing the location and adding a firewall rule in the Azure portal](<./includes/tutorial-python-postgresql-app/add-access-to-postgres-from-web-app-portal-1.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/add-access-to-postgres-from-web-app-portal-1-240px.png" lightbox="./media/tutorial-python-postgresql-app/add-access-to-postgres-from-web-app-portal-1.png" alt-text="A screenshot showing how to add access from other Azure services to a PostgreSQL database in the Azure portal." ::: |

-### [Azure CLI](#tab/azure-cli-access)

-## 5 - Connect the web app to the database

-With the web app and PostgreSQL database created, the next step is to connect the web app to the PostgreSQL database in Azure.

-The web app code uses database information in four environment variables named `DBHOST`, `DBNAME`, `DBUSER`, and `DBPASS` to connect to the PostgresSQL server.

-### [Azure portal](#tab/azure-portal)

-| Instructions | Screenshot |

-|:-|--:|

-| [!INCLUDE [Azure portal connect app to postgres step 1](<./includes/tutorial-python-postgresql-app/connect-postgres-to-app-azure-portal-1.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/connect-postgres-to-app-azure-portal-1-240px.png" lightbox="./media/tutorial-python-postgresql-app/connect-postgres-to-app-azure-portal-1.png" alt-text="A screenshot showing how to navigate to App Settings in the Azure portal." ::: |

-| [!INCLUDE [Azure portal connect app to postgres step 2](<./includes/tutorial-python-postgresql-app/connect-postgres-to-app-azure-portal-2.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/connect-postgres-to-app-azure-portal-2-240px.png" lightbox="./media/tutorial-python-postgresql-app/connect-postgres-to-app-azure-portal-2.png" alt-text="A screenshot showing how to configure the App Settings in the Azure portal." ::: |

-### [VS Code](#tab/vscode-aztools)

-To configure environment variables for the web app from VS Code, you must have the [Azure Tools extension pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-node-azure-pack) installed and be signed into Azure from VS Code.

-| Instructions | Screenshot |

-|:-|--:|

-| [!INCLUDE [VS Code connect app to postgres step 1](<./includes/tutorial-python-postgresql-app/connect-postgres-to-app-visual-studio-code-1.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/connect-app-to-database-azure-extension-240px.png" lightbox="./media/tutorial-python-postgresql-app/connect-app-to-database-azure-extension.png" alt-text="A screenshot showing how to locate the Azure Tools extension in VS Code." ::: |

-| [!INCLUDE [VS Code connect app to postgres step 2](<./includes/tutorial-python-postgresql-app/connect-postgres-to-app-visual-studio-code-2.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/connect-app-to-database-create-setting-240px.png" lightbox="./media/tutorial-python-postgresql-app/connect-app-to-database-create-setting.png" alt-text="A screenshot showing how to add a setting to the App Service in VS Code." ::: |

-| [!INCLUDE [VS Code connect app to postgres step 3](<./includes/tutorial-python-postgresql-app/connect-postgres-to-app-visual-studio-code-3.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/connect-app-to-database-settings-example-a-240px.png" lightbox="./media/tutorial-python-postgresql-app/connect-app-to-database-settings-example-a.png" alt-text="A screenshot showing adding setting name for app service to connect to PostgreSQL database in VS Code." ::: :::image type="content" source="./media/tutorial-python-postgresql-app/connect-app-to-database-settings-example-b-240px.png" lightbox="./media/tutorial-python-postgresql-app/connect-app-to-database-settings-example-b.png" alt-text="A screenshot showing adding setting value for app service to connect to PostgreSQL database in VS Code." ::: |

-### [Azure CLI](#tab/azure-cli)

-Having issues? Refer first to the [Troubleshooting guide](configure-language-python.md#troubleshooting), otherwise, [let us know](https://aka.ms/DjangoCLITutorialHelp).

-## 6 - Deploy your application code to Azure

-Azure App service supports multiple methods to deploy your application code to Azure including support for GitHub Actions and all major CI/CD tools. This article focuses on how to deploy your code from your local workstation to Azure.

-### [Deploy using VS Code](#tab/vscode-aztools-deploy)

-To deploy a web app from VS Code, you must have the [Azure Tools extension pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-node-azure-pack) installed and be signed into Azure from VS Code.

-| Instructions | Screenshot |

-|:-|--:|

-| [!INCLUDE [VS Code deploy step 1](<./includes/tutorial-python-postgresql-app/deploy-visual-studio-code-1.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/connect-app-to-database-azure-extension-240px.png" lightbox="./media/tutorial-python-postgresql-app/connect-app-to-database-azure-extension.png" alt-text="A screenshot showing how to locate the Azure Tools extension in VS Code." ::: |

-| [!INCLUDE [VS Code deploy step 2](<./includes/tutorial-python-postgresql-app/deploy-visual-studio-code-2.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/deploy-web-app-visual-studio-code-1-240px.png" lightbox="./media/tutorial-python-postgresql-app/deploy-web-app-visual-studio-code-1.png" alt-text="A screenshot showing how to deploy a web app in VS Code." ::: |

-| [!INCLUDE [VS Code deploy step 3](<./includes/tutorial-python-postgresql-app/deploy-visual-studio-code-3.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/deploy-web-app-visual-studio-code-2-240px.png" lightbox="./media/tutorial-python-postgresql-app/deploy-web-app-visual-studio-code-2.png" alt-text="A screenshot showing how to deploy a web app in VS Code: selecting the code to deploy." ::: :::image type="content" source="./media/tutorial-python-postgresql-app/deploy-web-app-visual-studio-code-3-240px.png" lightbox="./media/tutorial-python-postgresql-app/deploy-web-app-visual-studio-code-3.png" alt-text="A screenshot showing how to deploy a web app in VS Code: a dialog box to confirm deployment." ::: |

-| [!INCLUDE [VS Code deploy step 4](<./includes/tutorial-python-postgresql-app/deploy-visual-studio-code-4.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/deploy-web-app-visual-studio-code-4-240px.png" lightbox="./media/tutorial-python-postgresql-app/deploy-web-app-visual-studio-code-4.png" alt-text="A screenshot showing how to deploy a web app in VS Code: a dialog box to choose to always deploy to the app service." ::: |

-| [!INCLUDE [VS Code deploy step 5](<./includes/tutorial-python-postgresql-app/deploy-visual-studio-code-5.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/deploy-web-app-visual-studio-code-5-240px.png" lightbox="./media/tutorial-python-postgresql-app/deploy-web-app-visual-studio-code-5.png" alt-text="A screenshot showing how to deploy a web app in VS Code: a dialog box with choice to browse to website." ::: :::image type="content" source="./media/tutorial-python-postgresql-app/deploy-web-app-visual-studio-code-6-240px.png" lightbox="./media/tutorial-python-postgresql-app/deploy-web-app-visual-studio-code-6.png" alt-text="A screenshot showing how to deploy a web app in VS Code: a dialog box with choice to view deployment details." ::: |

-### [Deploy using Local Git](#tab/local-git-deploy)

-### [Deploy using a ZIP file](#tab/zip-deploy)

-## 7 - Migrate app database

-With the code deployed and the database in place, the app is almost ready to use. First, you need to establish the necessary schema in the database itself. You do this by "migrating" the data models in the Django app to the database.

-**Step 1.** Create SSH session and connect to web app server.

-### [Azure portal](#tab/azure-portal)

-Navigate to page for the App Service instance in the Azure portal.

-1. Select **SSH**, under **Development Tools** on the left side

-2. Then **Go** to open an SSH console on the web app server. (It may take a minute to connect for the first time as the web app container needs to start.)

-### [VS Code](#tab/vscode-aztools)

-In VS Code, you can use the [Azure Tools extension pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-node-azure-pack), which must be installed and be signed into Azure from VS Code.

-In the **App Service** section of the Azure Tools extension:

-1. Locate your web app and right-click to bring up the context menu.

-2. Select **SSH into Web App** to open an SSH terminal window.

-### [Azure CLI](#tab/azure-cli)

-> [!NOTE]

-> If you cannot connect to the SSH session, then the app itself has failed to start. **Check the diagnostic logs** for details. For example, if you haven't created the necessary app settings in the previous section, the logs will indicate `KeyError: 'DBNAME'`.

-**Step 2.** In the SSH session, run the following command to migrate the models into the database schema (you can paste commands using **Ctrl**+**Shift**+**V**):

-When you deploy the Flask sample app to Azure App Service, the database tables are created automatically in Azure PostgreSQL. If the tables aren't created, try the following command:

-```bash

-# Create database tables

-flask db init

-```

-```bash

-# Create database tables

-python manage.py migrate

-```

-If you encounter any errors related to connecting to the database, check the values of the application settings of the App Service created in the previous section, namely `DBHOST`, `DBNAME`, `DBUSER`, and `DBPASS`. Without those settings, the migrate command can't communicate with the database.

-## 8 - Browse to the app

-Browse to the deployed application in your web browser at the URL `http://<app-name>.azurewebsites.net`. It can take a minute or two for the app to start, so if you see a default app page, wait a minute and refresh the browser.

-When you see your sample web app, it's running in a Linux container in App Service using a built-in image **Congratulations!** You've deployed your Python app to App Service.

-## 9 - Stream diagnostic logs

-Azure App Service captures all messages output to the console to help you diagnose issues with your application. The sample app includes `print()` statements to demonstrate this capability as shown below.

-### [Flask](#tab/flask)

-### [Django](#tab/django)

-You can access the console logs generated from inside the container that hosts the app on Azure.

-### [Azure portal](#tab/azure-portal)

-| Instructions | Screenshot |

-|:-|--:|

-| [!INCLUDE [Stream logs from Azure portal 1](<./includes/tutorial-python-postgresql-app/stream-logs-azure-portal-1.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/stream-logs-azure-portal-1-240px.png" lightbox="./media/tutorial-python-postgresql-app/stream-logs-azure-portal-1.png" alt-text="A screenshot showing how to set application logging in the Azure portal." ::: |

-| [!INCLUDE [Stream logs from Azure portal 2](<./includes/tutorial-python-postgresql-app/stream-logs-azure-portal-2.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/stream-logs-azure-portal-2-240px.png" lightbox="./media/tutorial-python-postgresql-app/stream-logs-azure-portal-2.png" alt-text="A screenshot showing how to stream logs in the Azure portal." ::: |

-### [VS Code](#tab/vscode-aztools)

-| Instructions | Screenshot |

-|:-|--:|

-| [!INCLUDE [Stream logs from VS Code 1](<./includes/tutorial-python-postgresql-app/stream-logs-visual-studio-code-1.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/stream-logs-visual-studio-code-1-240px.png" lightbox="./media/tutorial-python-postgresql-app/stream-logs-visual-studio-code-1.png" alt-text="A screenshot showing how to set application logging in VS Code." ::: |

-| [!INCLUDE [Stream logs from VS Code 2](<./includes/tutorial-python-postgresql-app/stream-logs-visual-studio-code-2.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/stream-logs-visual-studio-code-2-240px.png" lightbox="./media/tutorial-python-postgresql-app/stream-logs-visual-studio-code-2.png" alt-text="A screenshot showing VS Code output window." ::: |

-### [Azure CLI](#tab/azure-cli)

-Having issues? [Let us know](https://aka.ms/DjangoCLITutorialHelp).

-## Clean up resources

-You can leave the app and database running as long as you want for further development work and skip ahead to [Next steps](#next-steps).

-However, when you're finished with the sample app, you can remove all of the resources for the app from Azure to ensure you don't incur other charges and keep your Azure subscription uncluttered. Removing the resource group also removes all resources in the resource group and is the fastest way to remove all Azure resources for your app.

-### [Azure portal](#tab/azure-portal)

-Follow these steps while signed-in to the Azure portal to delete a resource group.

-| Instructions | Screenshot |

-|:-|--:|

-| [!INCLUDE [Remove resource group Azure portal 1](<./includes/tutorial-python-postgresql-app/remove-resource-group-azure-portal-1.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/remove-resource-group-azure-portal-1-240px.png" lightbox="./media/tutorial-python-postgresql-app/remove-resource-group-azure-portal-1.png" alt-text="A screenshot showing how to find resource group in the Azure portal." ::: |

-| [!INCLUDE [Remove resource group Azure portal 2](<./includes/tutorial-python-postgresql-app/remove-resource-group-azure-portal-2.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/remove-resource-group-azure-portal-2-240px.png" lightbox="./media/tutorial-python-postgresql-app/remove-resource-group-azure-portal-2.png" alt-text="A screenshot showing how to delete a resource group in the Azure portal." ::: |

-| [!INCLUDE [Remove resource group Azure portal 3](<./includes/tutorial-python-postgresql-app/remove-resource-group-azure-portal-3.md>)] | |

-### [VS Code](#tab/vscode-aztools)

-| Instructions | Screenshot |

-|:-|--:|

-| [!INCLUDE [Remove resource group VS Code 1](<./includes/tutorial-python-postgresql-app/remove-resource-group-visual-studio-code-1.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/remove-resource-group-visual-studio-code-1-240px.png" lightbox="./media/tutorial-python-postgresql-app/remove-resource-group-visual-studio-code-1.png" alt-text="A screenshot showing how to delete a resource group in VS Code." ::: |

-| [!INCLUDE [Remove resource group VS Code 2](<./includes/tutorial-python-postgresql-app/remove-resource-group-visual-studio-code-2.md>)] | :::image type="content" source="./media/tutorial-python-postgresql-app/remove-resource-group-visual-studio-code-2-240px.png" lightbox="./media/tutorial-python-postgresql-app/remove-resource-group-visual-studio-code-2.png" alt-text="A screenshot showing how to finish deleting a resource in VS Code." ::: |

-### [Azure CLI](#tab/azure-cli)

-Having issues? [Let us know](https://aka.ms/DjangoCLITutorialHelp).

-1. Within your **Application Gateways** properties blade, obtain and make a note of the **Resource ID**, you will require this if setting up a Private Endpoint within a diffrerent Azure AD tenant

-> If you are setting up the **Private Endpoint** from within another tenant, you will need to utilise the Azure Application Gateway Resource ID, along with sub-resource as either _appGwPublicFrontendIp_ or _appGwPrivateFrontendIp_, depending upon your Azure Application Gateway Private Link Frontend IP Configuration.

-description: Azure Form Recognizer service that analyzes and extracts text, table and data, maps field relationships as key-value pairs, and returns a structured JSON output from your forms and documents.

-recommendations: false

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

-<!-- markdownlint-disable MD024 -->

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

-# Overview: What is Azure Form Recognizer?

-Azure Form Recognizer is a cloud-based [Azure Applied AI Service](../../applied-ai-services/index.yml) that analyzes forms and documents, extracts text and data, and maps field relationships as key-value pairs. To learn more about each model, *see* Concepts articles:

-| Model type | Model name |

-||--|

-|**Document analysis models**| &#9679; [**Read model**](concept-read.md)</br> &#9679; [**General document model**](concept-general-document.md)</br> &#9679; [**Layout model**](concept-layout.md) </br> |

-| **Prebuilt models** | &#9679; [**W-2 form model**](concept-w2.md) </br>&#9679; [**Invoice model**](concept-invoice.md)</br>&#9679; [**Receipt model**](concept-receipt.md) </br>&#9679; [**ID document model**](concept-id-document.md) </br>&#9679; [**Business card model**](concept-business-card.md) </br>

-| **Custom models** | &#9679; [**Custom model**](concept-custom.md) </br>&#9679; [**Composed model**](concept-model-overview.md)|

-## Which Form Recognizer model should I use?

-This section will help you decide which Form Recognizer v3.0 supported model you should use for your application:

-| Type of document | Data to extract |Document format | Your best solution |

-| --|-| -|-|

-|**A text-based document** like a contract or letter.|You want to extract primarily text lines, words, locations, and detected languages.|</li></ul>The document is written or printed in a [supported language](language-support.md#read-layout-and-custom-form-template-model).| [**Read model**](concept-read.md)|

-|**A document that includes structural information** like a report or study.|In addition to text, you need to extract structural information like tables, selection marks, paragraphs, titles, headings, and subheadings.|The document is written or printed in a [supported language](language-support.md#read-layout-and-custom-form-template-model)| [**Layout model**](concept-layout.md)

-|**A structured or semi-structured document that includes content formatted as fields and values**, like a credit application or survey form.|You want to extract fields and values including ones not covered by the scenario-specific prebuilt models **without having to train a custom model**.| The form or document is a standardized format commonly used in your business or industry and printed in a [supported language](language-support.md#read-layout-and-custom-form-template-model).|[**General document model**](concept-general-document.md)

-|**U.S. W-2 form**|You want to extract key information such as salary, wages, and taxes withheld from US W2 tax forms.</li></ul> |The W-2 document is in United States English (en-US) text.|[**W-2 model**](concept-w2.md)

-|**Invoice**|You want to extract key information such as customer name, billing address, and amount due from invoices.</li></ul> |The invoice document is written or printed in a [supported language](language-support.md#invoice-model).|[**Invoice model**](concept-invoice.md)

- |**Receipt**|You want to extract key information such as merchant name, transaction date, and transaction total from a sales or single-page hotel receipt.</li></ul> |The receipt is written or printed in a [supported language](language-support.md#receipt-model). |[**Receipt model**](concept-receipt.md)|

-|**ID document** like a passport or driver's license. |You want to extract key information such as first name, last name, and date of birth from US drivers' licenses or international passports. |Your ID document is a US driver's license or the biographical page from an international passport (not a visa).| [**ID document model**](concept-id-document.md)|

-|**Business card**|You want to extract key information such as first name, last name, company name, email address, and phone number from business cards.</li></ul>|The business card document is in English or Japanese text. | [**Business card model**](concept-business-card.md)|

-|**Mixed-type document(s)**| You want to extract key-value pairs, selection marks, tables, signature fields, and selected regions not extracted by prebuilt or general document models.| You have various documents with structured, semi-structured, and/or unstructured elements.| [**Custom model**](concept-custom.md)|

->[!Tip]

->

-> * If you're still unsure which model to use, try the General Document model.

-> * The General Document model is powered by the Read OCR model to detect lines, words, locations, and languages.

-> * General document extracts all the same fields as Layout model (pages, tables, styles) and also extracts key-value pairs.

-## Form Recognizer models and development options

-> [!NOTE]

-> The following models and development options are supported by the Form Recognizer service v3.0. You can Use Form Recognizer to automate your data processing in applications and workflows, enhance data-driven strategies, and enrich document search capabilities. Use the links in the table to learn more about each model and browse the API references.

-| Model | Description |Automation use cases | Development options |

-|-|--|-|--|

-|[ **Read**](concept-read.md)|Extract text lines, words, detected languages, and handwritten style if detected.| <ul><li>Contract processing. </li><li>Financial or medical report processing.</li></ul>|<ul ><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/read)</li><li>[**REST API**](how-to-guides/use-sdk-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li><li>[**C# SDK**](how-to-guides/use-sdk-rest-api.md?view=form-recog-3.0.0&preserve-view=true?pivots=programming-language-csharp)</li><li>[**Python SDK**](how-to-guides/use-sdk-rest-api.md?view=form-recog-3.0.0&preserve-view=true?pivots=programming-language-python)</li><li>[**Java SDK**](how-to-guides/use-sdk-rest-api.md?view=form-recog-3.0.0&preserve-view=true?pivots=programming-language-java)</li><li>[**JavaScript**](how-to-guides/use-sdk-rest-api.md?view=form-recog-3.0.0&preserve-view=true?pivots=programming-language-javascript)</li></ul> |

-|[**General document model**](concept-general-document.md)|Extract text, tables, structure, and key-value pairs.|<ul><li>Key-value pair extraction.</li><li>Form processing.</li><li>Survey data collection and analysis.</li></ul>|<ul ><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/document)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li><li>[**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#general-document-model)</li><li>[**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#general-document-model)</li><li>[**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#general-document-model)</li><li>[**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#general-document-model)</li></ul> |

-|[**Layout model**](concept-layout.md) | Extract text, selection marks, and tables structures, along with their bounding box coordinates, from forms and documents.</br></br> Layout API has been updated to a prebuilt model. |<ul><li>Document indexing and retrieval by structure.</li><li>Preprocessing prior to OCR analysis.</li></ul> |<ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/layout)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li><li>[**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#layout-model)</li><li>[**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#layout-model)</li><li>[**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#layout-model)</li><li>[**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#layout-model)</li></ul>|

-|[**Custom model (updated)**](concept-custom.md) | Extraction and analysis of data from forms and documents specific to distinct business data and use cases.</br></br>Custom model API v3.0 supports **signature detection for custom template (custom form) models**.</br></br>Custom model API v3.0 now supports two model types:<ul><li>[**Custom Template model**](concept-custom-template.md) (custom form) is used to analyze structured and semi-structured documents.</li><li> [**Custom Neural model**](concept-custom-neural.md) (custom document) is used to analyze unstructured documents.</li></ul>|<ul><li>Identification and compilation of data, unique to your business, impacted by a regulatory change or market event.</li><li>Identification and analysis of previously overlooked unique data.</li></ul> |[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li><li>[**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li><li>[**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li><li>[**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li><li>[**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li></ul>|

-|[ **W-2 Form**](concept-w2.md) | Extract information reported in each box on a W-2 form.|<ul><li>Automated tax document management.</li><li>Mortgage loan application processing.</li></ul> |<ul ><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=tax.us.w2)<li>[**REST API**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v3-0-preview-2/operations/AnalyzeDocument)</li><li>[**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li></ul> |

-|[**Invoice model**](concept-invoice.md) | Automated data processing and extraction of key information from sales invoices. |<ul><li>Accounts payable processing.</li><li>Automated tax recording and reporting.</li></ul> |<ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=invoice)</li><li>[**REST API**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)</li><li>[**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li></ul>|

-|[**Receipt model (updated)**](concept-receipt.md) | Automated data processing and extraction of key information from sales receipts.</br></br>Receipt model v3.0 supports processing of **single-page hotel receipts**.|<ul><li>Expense management.</li><li>Consumer behavior data analysis.</li><li>Customer loyalty program.</li><li>Merchandise return processing.</li><li>Automated tax recording and reporting.</li></ul> |<ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=receipt)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li><li>[**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li></ul>|

-|[**ID document model (updated)**](concept-id-document.md) |Automated data processing and extraction of key information from US driver's licenses and international passports.</br></br>Prebuilt ID document API supports the **extraction of endorsements, restrictions, and vehicle classifications from US driver's licenses**. |<ul><li>Know your customer (KYC) financial services guidelines compliance.</li><li>Medical account management.</li><li>Identity checkpoints and gateways.</li><li>Hotel registration.</li></ul> |<ul><li> [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=idDocument)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li><li>[**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li></ul>|

-|[**Business card model**](concept-business-card.md) |Automated data processing and extraction of key information from business cards.|<ul><li>Sales lead and marketing management.</li></ul> |<ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=businessCard)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li><li>[**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li></ul>|

- >[!TIP]

- >

- > * For an enhanced experience and advanced model quality, try the [Form Recognizer v3.0 Studio ](https://formrecognizer.appliedai.azure.com/studio).

- > * The v3.0 Studio supports any model trained with v2.1 labeled data.

- > * You can refer to the API migration guide for detailed information about migrating from v2.1 to v3.0.

-The following models are supported by Form Recognizer v2.1. Use the links in the table to learn more about each model and browse the API references.

-| Model| Description | Development options |

-|-|--|-|

-|[**Layout API**](concept-layout.md) | Extraction and analysis of text, selection marks, tables, and bounding box coordinates, from forms and documents. | <ul><li>[**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-layout)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-2.1.0&preserve-view=true)</li><li>[**Client-library SDK**](quickstarts/try-sdk-rest-api.md)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?branch=main&tabs=layout#run-the-container-with-the-docker-compose-up-command)</li></ul>|

-|[**Custom model**](concept-custom.md) | Extraction and analysis of data from forms and documents specific to distinct business data and use cases.| <ul><li>[**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#train-a-custom-form-model)</li><li>[**REST API**](quickstarts/try-sdk-rest-api.md)</li><li>[**Client-library SDK**](how-to-guides/try-sdk-rest-api.md)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=custom#run-the-container-with-the-docker-compose-up-command)</li></ul>|

-|[**Invoice model**](concept-invoice.md) | Automated data processing and extraction of key information from sales invoices. | <ul><li>[**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-using-a-prebuilt-model)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-2.1.0&preserve-view=true)</li><li>[**Client-library SDK**](quickstarts/try-sdk-rest-api.md)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=invoice#run-the-container-with-the-docker-compose-up-command)</li></ul>|

-|[**Receipt model**](concept-receipt.md) | Automated data processing and extraction of key information from sales receipts.| <ul><li>[**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-using-a-prebuilt-model)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-2.1.0&preserve-view=true)</li><li>[**Client-library SDK**](how-to-guides/try-sdk-rest-api.md)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=receipt#run-the-container-with-the-docker-compose-up-command)</li></ul>|

-|[**ID document model**](concept-id-document.md) | Automated data processing and extraction of key information from US driver's licenses and international passports.| <ul><li>[**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-using-a-prebuilt-model)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-2.1.0&preserve-view=true)</li><li>[**Client-library SDK**](how-to-guides/try-sdk-rest-api.md)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=id-document#run-the-container-with-the-docker-compose-up-command)</li></ul>|

-|[**Business card model**](concept-business-card.md) | Automated data processing and extraction of key information from business cards.| <ul><li>[**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-using-a-prebuilt-model)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-2.1.0&preserve-view=true)</li><li>[**Client-library SDK**](how-to-guides/try-sdk-rest-api.md)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=business-card#run-the-container-with-the-docker-compose-up-command)</li></ul>|

-## How to use Form Recognizer documentation

-This documentation contains the following article types:

-* [**Concepts**](concept-layout.md) provide in-depth explanations of the service functionality and features.

-* [**Quickstarts**](quickstarts/try-sdk-rest-api.md) are getting-started instructions to guide you through making requests to the service.

-* [**How-to guides**](how-to-guides/try-sdk-rest-api.md) contain instructions for using the service in more specific or customized ways.

-* [**Tutorials**](tutorial-ai-builder.md) are longer guides that show you how to use the service as a component in broader business solutions.

-## Data privacy and security

- As with all the cognitive services, developers using the Form Recognizer service should be aware of Microsoft policies on customer data. See our [Data, privacy, and security for Form Recognizer](/legal/cognitive-services/form-recognizer/fr-data-privacy-security) page.

-## Next steps

-> [!div class="checklist"]

->

-> * Try our [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com)

-> * Explore the [**REST API reference documentation**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument) to learn more.

-> * If you're familiar with a previous version of the API, see the [**What's new**](./whats-new.md) article to learn of recent changes.

-> [!div class="checklist"]

->

-> * Try our [**Sample Labeling online tool**](https://aka.ms/fott-2.1-ga/)

-> * Follow our [**client library / REST API quickstart**](./quickstarts/try-sdk-rest-api.md) to get started extracting data from your documents. We recommend that you use the free service when you're learning the technology. Remember that the number of free pages is limited to 500 per month.

-> * Explore the [**REST API reference documentation**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/AnalyzeWithCustomForm) to learn more.

-> * If you're familiar with a previous version of the API, see the [**What's new**](./whats-new.md) article to learn of recent changes.

-description: The Azure Form Recognizer service allows you to identify and extract key/value pairs and table data from your form documents, as well as extract major information from sales receipts and business cards.

-adobe-target: true

-adobe-target-activity: DocsExpΓÇô463504ΓÇôA/BΓÇôDocs/FormRecognizerΓÇôDecisionTreeΓÇôFY23Q1

-adobe-target-experience: Experience B

-adobe-target-content: ./overview-experiment

-#Customer intent: As a developer of form-processing software, I want to learn what the Form Recognizer service does so I can determine if I should use it.

-Azure Form Recognizer is a cloud-based [Azure Applied AI Service](../../applied-ai-services/index.yml) that analyzes forms and documents, extracts text and data, and maps field relationships as key-value pairs. To learn more about each model, *see* Concepts articles:

-This section will help you decide which Form Recognizer v3.0 supported model you should use for your application:

-> The following models and development options are supported by the Form Recognizer service v3.0. You can Use Form Recognizer to automate your data processing in applications and workflows, enhance data-driven strategies, and enrich document search capabilities. Use the links in the table to learn more about each model and browse the API references.

-|[ **Read**](concept-read.md)|Extract text lines, words, detected languages, and handwritten style if detected.| <ul><li>Contract processing. </li><li>Financial or medical report processing.</li></ul>|<ul ><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/read)</li><li>[**REST API**](how-to-guides/use-sdk-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li><li>[**C# SDK**](how-to-guides/use-sdk-rest-api.md?view=form-recog-3.0.0&preserve-view=true?pivots=programming-language-csharp)</li><li>[**Python SDK**](how-to-guides/use-sdk-rest-api.md?view=form-recog-3.0.0&preserve-view=true?pivots=programming-language-python)</li><li>[**Java SDK**](how-to-guides/use-sdk-rest-api.md?view=form-recog-3.0.0&preserve-view=true?pivots=programming-language-java)</li><li>[**JavaScript**](how-to-guides/use-sdk-rest-api.md?view=form-recog-3.0.0&preserve-view=true?pivots=programming-language-javascript)</li></ul> |

-|[**General document model**](concept-general-document.md)|Extract text, tables, structure, and key-value pairs.|<ul><li>Key-value pair extraction.</li><li>Form processing.</li><li>Survey data collection and analysis.</li></ul>|<ul ><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/document)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li><li>[**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#general-document-model)</li><li>[**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#general-document-model)</li><li>[**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#general-document-model)</li><li>[**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#general-document-model)</li></ul> |

-|[**Layout model**](concept-layout.md) | Extract text, selection marks, and tables structures, along with their bounding box coordinates, from forms and documents.</br></br> Layout API has been updated to a prebuilt model. |<ul><li>Document indexing and retrieval by structure.</li><li>Preprocessing prior to OCR analysis.</li></ul> |<ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/layout)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li><li>[**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#layout-model)</li><li>[**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#layout-model)</li><li>[**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#layout-model)</li><li>[**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#layout-model)</li></ul>|

-|[**Custom model (updated)**](concept-custom.md) | Extraction and analysis of data from forms and documents specific to distinct business data and use cases.</br></br>Custom model API v3.0 supports **signature detection for custom template (custom form) models**.</br></br>Custom model API v3.0 now supports two model types:<ul><li>[**Custom Template model**](concept-custom-template.md) (custom form) is used to analyze structured and semi-structured documents.</li><li> [**Custom Neural model**](concept-custom-neural.md) (custom document) is used to analyze unstructured documents.</li></ul>|<ul><li>Identification and compilation of data, unique to your business, impacted by a regulatory change or market event.</li><li>Identification and analysis of previously overlooked unique data.</li></ul> |[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li><li>[**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li><li>[**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li><li>[**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li><li>[**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li></ul>|

-|[ **W-2 Form**](concept-w2.md) | Extract information reported in each box on a W-2 form.|<ul><li>Automated tax document management.</li><li>Mortgage loan application processing.</li></ul> |<ul ><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=tax.us.w2)<li>[**REST API**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v3-0-preview-2/operations/AnalyzeDocument)</li><li>[**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li></ul> |

-|[**Invoice model**](concept-invoice.md) | Automated data processing and extraction of key information from sales invoices. |<ul><li>Accounts payable processing.</li><li>Automated tax recording and reporting.</li></ul> |<ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=invoice)</li><li>[**REST API**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)</li><li>[**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li></ul>|

-|[**Receipt model (updated)**](concept-receipt.md) | Automated data processing and extraction of key information from sales receipts.</br></br>Receipt model v3.0 supports processing of **single-page hotel receipts**.|<ul><li>Expense management.</li><li>Consumer behavior data analysis.</li><li>Customer loyalty program.</li><li>Merchandise return processing.</li><li>Automated tax recording and reporting.</li></ul> |<ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=receipt)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li><li>[**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li></ul>|

-|[**ID document model (updated)**](concept-id-document.md) |Automated data processing and extraction of key information from US driver's licenses and international passports.</br></br>Prebuilt ID document API supports the **extraction of endorsements, restrictions, and vehicle classifications from US driver's licenses**. |<ul><li>Know your customer (KYC) financial services guidelines compliance.</li><li>Medical account management.</li><li>Identity checkpoints and gateways.</li><li>Hotel registration.</li></ul> |<ul><li> [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=idDocument)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li><li>[**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li></ul>|

-|[**Business card model**](concept-business-card.md) |Automated data processing and extraction of key information from business cards.|<ul><li>Sales lead and marketing management.</li></ul> |<ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=businessCard)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true)</li><li>[**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li><li>[**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-3.0.0&preserve-view=true#prebuilt-model)</li></ul>|

- > * For an enhanced experience and advanced model quality, try the [Form Recognizer v3.0 Studio ](https://formrecognizer.appliedai.azure.com/studio).

-The following models are supported by Form Recognizer v2.1. Use the links in the table to learn more about each model and browse the API references.

-|[**Layout API**](concept-layout.md) | Extraction and analysis of text, selection marks, tables, and bounding box coordinates, from forms and documents. | <ul><li>[**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-layout)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-2.1.0&preserve-view=true)</li><li>[**Client-library SDK**](quickstarts/try-sdk-rest-api.md)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?branch=main&tabs=layout#run-the-container-with-the-docker-compose-up-command)</li></ul>|

-|[**Invoice model**](concept-invoice.md) | Automated data processing and extraction of key information from sales invoices. | <ul><li>[**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-using-a-prebuilt-model)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-2.1.0&preserve-view=true)</li><li>[**Client-library SDK**](quickstarts/try-sdk-rest-api.md)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=invoice#run-the-container-with-the-docker-compose-up-command)</li></ul>|

-|[**Receipt model**](concept-receipt.md) | Automated data processing and extraction of key information from sales receipts.| <ul><li>[**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-using-a-prebuilt-model)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-2.1.0&preserve-view=true)</li><li>[**Client-library SDK**](how-to-guides/try-sdk-rest-api.md)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=receipt#run-the-container-with-the-docker-compose-up-command)</li></ul>|

-|[**ID document model**](concept-id-document.md) | Automated data processing and extraction of key information from US driver's licenses and international passports.| <ul><li>[**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-using-a-prebuilt-model)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-2.1.0&preserve-view=true)</li><li>[**Client-library SDK**](how-to-guides/try-sdk-rest-api.md)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=id-document#run-the-container-with-the-docker-compose-up-command)</li></ul>|

-|[**Business card model**](concept-business-card.md) | Automated data processing and extraction of key information from business cards.| <ul><li>[**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-using-a-prebuilt-model)</li><li>[**REST API**](quickstarts/get-started-sdks-rest-api.md?view=form-recog-2.1.0&preserve-view=true)</li><li>[**Client-library SDK**](how-to-guides/try-sdk-rest-api.md)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=business-card#run-the-container-with-the-docker-compose-up-command)</li></ul>|

-## How to use Form Recognizer documentation

-This documentation contains the following article types:

-* [**Concepts**](concept-layout.md) provide in-depth explanations of the service functionality and features.

-* [**Quickstarts**](quickstarts/try-sdk-rest-api.md) are getting-started instructions to guide you through making requests to the service.

-* [**How-to guides**](how-to-guides/try-sdk-rest-api.md) contain instructions for using the service in more specific or customized ways.

-* [**Tutorials**](tutorial-ai-builder.md) are longer guides that show you how to use the service as a component in broader business solutions.

-To configure disaster recovery in Azure Arc-enabled SQL Managed Instance, set up failover groups.

-The distributed availability groups used in Azure Arc-enabled SQL Managed Instance is the same technology that is in SQL Server. Because Azure Arc-enabled SQL Managed Instance runs on Kubernetes, there's no Windows failover cluster involved. For more information, see [Distributed availability groups](/sql/database-engine/availability-groups/windows/distributed-availability-groups).

-To configure disaster recovery:

-1. Copy the mirroring certificates

-### Configure distributed availability groups

-2. Provision the managed instance in the secondary site and configure as a disaster recovery instance. At this point, the system databases are not part of the contained availability group.

-3. Copy the mirroring certificates from each site to a location that's accessible to both the geo-primary and geo-secondary instances.

- ```azurecli

- az sql mi-arc get-mirroring-cert --name <primaryinstance> --cert-file $HOME/sqlcerts/<name>.pemΓÇï --k8s-namespace <namespace> --use-k8s

- az sql mi-arc get-mirroring-cert --name <secondaryinstance> --cert-file $HOME/sqlcerts/<name>.pem --k8s-namespace <namespace> --use-k8s

- ```

- Example:

- ```azurecli

- az sql mi-arc get-mirroring-cert --name sqlprimary --cert-file $HOME/sqlcerts/sqlprimary.pemΓÇï --k8s-namespace my-namespace --use-k8s

- az sql mi-arc get-mirroring-cert --name sqlsecondary --cert-file $HOME/sqlcerts/sqlsecondary.pem --k8s-namespace my-namespace --use-k8s

- ```

- az sql instance-failover-group-arc create --shared-name myfog --name primarycr --mi sqlinstance1 --role primary --partner-mi sqlinstance2 --partner-mirroring-url tcp://10.20.5.20:970 --partner-mirroring-cert-file $HOME/sqlcerts/sqlinstance2.pem --k8s-namespace my-namespace --use-k8s

-Benefits of the Azure Key Vault Secrets Provider extension include the folllowing:

- - AKS Engine

-> `Azure Repos PAT token` should have `Build: Read & execute` and `Code: Read` permissions.

-If `az arcappliance deploy` was not completed, then the kubeconfig file may exist but may be empty or missing data, so it can't be used for logs collection. In this case, the Appliance VM IP address can be used to collect logs instead. The Appliance VM IP is assigned when the `az arcappliance deploy` command is run, after Control Plane Endpoint reconciliation. For example, if the message displayed in the command window reads "Appliance IP is 10.97.176.27", the command to use for logs collection would be:

-If outbound connectivity is restricted by your firewall or proxy server, make sure the URLs listed below are not blocked.

-URLS:

-| Agent resource | Description |

-|||

-|`https://mcr.microsoft.com`|Microsoft container registry|

-|`https://*.his.arc.azure.com`|Azure Arc Identity service|

-|`https://*.dp.kubernetesconfiguration.azure.com`|Azure Arc configuration service|

-|`https://*.servicebus.windows.net`|Cluster connect|

-|`https://guestnotificationservice.azure.com` |Guest notification service|

-|`https://*.dp.prod.appliances.azure.com`|Resource bridge data plane service|

-|`https://ecpacr.azurecr.io` |Resource bridge container image download |

-|`.blob.core.windows.net`<br> `*.dl.delivery.mp.microsoft.com`<br> `*.do.dsp.mp.microsoft.com` |Resource bridge image download |

-|`https://azurearcfork8sdev.azurecr.io` |Azure Arc for Kubernetes container image download |

-|`adhs.events.data.microsoft.com ` |Required diagnostic data sent to Microsoft from control plane nodes|

-|`v20.events.data.microsoft.com` |Required diagnostic data sent to Microsoft from the Azure Stack HCI or Windows Server host|

-URLs used by other Arc agents:

-|Agent resource | Description |

-|||

-|`https://management.azure.com` |Azure Resource Manager|

-|`https://login.microsoftonline.com` |Azure Active Directory|

-* Get answers from Azure experts through [Microsoft Q&A](/answers/topics/azure-arc.html).

-* Connect with [@AzureSupport](https://twitter.com/azuresupport), the official Microsoft Azure account for improving customer experience. Azure Support connects the Azure community to answers, support, and experts.

-* [Open an Azure support request](../../azure-portal/supportability/how-to-create-azure-support-request.md).

-| AZCM0001 | An unknown error occurred | Contact Microsoft Support for further assistance |

-| AZCM0011 | The user canceled the action (CTRL+C) | Retry the previous command |

-| AZCM0012 | The access token provided is invalid | Obtain a new access token and try again |

-| AZCM0013 | The tags provided are invalid | Check that the tags are enclosed in double quotes, separated by commas, and that any names or values with spaces are enclosed in single quotes: `--tags "SingleName='Value with spaces',Location=Redmond"`

-| AZCM0014 | The cloud is invalid | Specify a supported cloud: `AzureCloud` or `AzureUSGovernment` |

-| AZCM0015 | The correlation ID specified isn't a valid GUID | Provide a valid GUID for `--correlation-id` |

-| AZCM0016 | Missing a mandatory parameter | Review the output to identify which parameters are missing |

-| AZCM0017 | The resource name is invalid | Specify a name that only uses alphanumeric characters, hyphens and/or underscores. The name cannot end with a hyphen or underscore. |

-| AZCM0018 | The command was executed without administrative privileges | Retry the command with administrator or root privileges in an elevated command prompt or console session. |

-| AZCM0041 | The credentials supplied are invalid | For device logins, verify the user account specified has access to the tenant and subscription where the server resource will be created. For service principal logins, check the client ID and secret for correctness, the expiration date of the secret, and that the service principal is from the same tenant where the server resource will be created. |

-| AZCM0042 | Creation of the Azure Arc-enabled server resource failed | Verify that the user/service principal specified has access to create Azure Arc-enabled server resources in the specified resource group. |

-| AZCM0043 | Deletion of the Azure Arc-enabled server resource failed | Verify that the user/service principal specified has access to delete Azure Arc-enabled server resources in the specified resource group. If the resource no longer exists in Azure, use the `--force-local-only` flag to proceed. |

-| AZCM0061 | Unable to reach the agent service | Verify you're running the command in an elevated user context (administrator/root) and that the HIMDS service is running on your server. |

-| AZCM0062 | An error occurred while connecting the server | Review other error codes in the output for more specific information. If the error occurred after the Azure resource was created, you need to delete the Arc server from your resource group before retrying. |

-| AZCM0063 | An error occurred while disconnecting the server | Review other error codes in the output for more specific information. If you continue to encounter this error, you can delete the resource in Azure, and then run `azcmagent disconnect --force-local-only` on the server to disconnect the agent. |

-| AZCM0064 | The agent service is not responding | Check the status of the `himds` service to ensure it is running. Start the service if it is not running. If it is running, wait a minute then try again. |

-| AZCM0065 | An internal agent communication error occurred | Contact Microsoft Support for assistance |

-| AZCM0066 | The agent web service is not responding or unavailable | Contact Microsoft Support for assistance |

-| AZCM0067 | The agent is already connected to Azure | Run `azcmagent disconnect` to remove the current connection, then try again. |

-| AZCM0068 | An internal error occurred while disconnecting the server from Azure | Contact Microsoft Support for assistance |

-| AZCM0070 | Unable to obtain local config | The Hybrid Instance Metadata service (HIMDS) might not be running. Check the status of your HIMDS service (for Windows) or the HIMDS daemon (for Linux). |

-| AZCM0101 | The command was not parsed successfully | Run `azcmagent <command> --help` to review the correct command syntax |

-| AZCM0102 | Unable to retrieve the computer hostname | Run `hostname` to check for any system-level error messages, then contact Microsoft Support. |

-| AZCM0103 | An error occurred while generating RSA keys | Contact Microsoft Support for assistance |

-| AZCM0104 | Failed to read system information | Verify the identity used to run `azcmagent` has administrator/root privileges on the system and try again. |

-The following is an example of the command to enable verbose logging with the Connected Machine agent for Windows when performing an interactive installation.

-The following is an example of the command to enable verbose logging with the Connected Machine agent for Windows when performing an at-scale installation using a service principal.

-The following is an example of the command to enable verbose logging with the Connected Machine agent for Linux when performing an interactive installation.

-The following is an example of the command to enable verbose logging with the Connected Machine agent for Linux when performing an at-scale installation using a service principal.

-| **Data center selection** | Select the name of the datacenter (as shown in the vSphere client) where the Azure Arc resource bridge's VM should be deployed. |

-| **Network selection** | Select the name of the virtual network or segment to which the VM must be connected. This network should allow the appliance to communicate with vCenter Server and the Azure endpoints (or internet). |

-| **Static IP / DHCP** | If you have DHCP server in your network and want to use it, enter **y**. Otherwise, enter **n**. If you are using a DHCP server, reserve the IP address assigned to the Azure Arc Resource Bridge VM (Appliance VM IP). </br>When you choose a static IP configuration, you're asked for the following information: </br> 1. **Static IP address prefix**: Network address in CIDR notation. For example: **192.168.0.0/24**. </br> 2. **Static gateway**: Gateway address. For example: **192.168.0.0**. </br> 3. **DNS servers**: IP address(es) of DNS server(s) used by Azure Arc Resource Bridge VM for DNS resolution. VM must be able to resolve external sites, like mcr.microsoft.com and the vCenter server. </br> 4. **Start range IP**: Minimum size of two available IP addresses is required. One IP address is for the VM, and the other is reserved for upgrade scenarios. Provide the starting IP address of that range. Ensure the Start range IP has internet access. </br> 5. **End range IP**: Last IP address of the IP range requested in the previous field. Ensure the End range IP has internet access. </br> 6. **VLAN ID** (optional) |

-| **Resource pool** | Select the name of the resource pool to which the Azure Arc resource bridge's VM will be deployed. |

-| **Data store** | Select the name of the datastore to be used for the Azure Arc resource bridge's VM. |

-This article is an introduction to using C# to develop .NET isolated process functions, which run out-of-process in Azure Functions. Running out-of-process lets you decouple your function code from the Azure Functions runtime. Isolated process C# functions run on .NET 6.0, .NET 7.0, and .NET Framework 4.8 (preview support). [In-process C# class library functions](functions-dotnet-class-library.md) aren't supported on .NET 7.0.

-The [ConfigureFunctionsWorkerDefaults] method is used to add the settings required for the function app to run out-of-process, which includes the following functionality:

-<!-- Insert example here -->

-<script src="https://unpkg.com/three@0.102.0/build/three.min.js"></script>

-<script src="https://unpkg.com/three@0.102.0/examples/js/loaders/GLTFLoader.js"></script>

-<!-- Insert example here -->

-<script src="https://unpkg.com/deck.gl@8.8.9/dist.min.js"></script>

-This sample renders an arc-layer from the [deck.gl][deckgl] library.

-| AlmaLinux 8.5 | X³ | | |

-| AlmaLinux 8 | X | X | |

-| CentOS Linux 6.5+ | | X | X |

-| CBL-Mariner 2.0 | X | | |

-| Debian 7 | | | X |

-| OpenSUSE 13.1+ | | | X |

-This guide will walk you through migrating a classic Application Insights resource to a workspace-based resource. Workspace-based resources support full integration between Application Insights and Log Analytics. Workspace-based resources send Application Insights telemetry to a common Log Analytics workspace. This behavior allows you to access [the latest features of Azure Monitor](#new-capabilities) while keeping application, infrastructure, and platform logs in a consolidated location.

-Workspace-based resources enable common Azure role-based access control (Azure RBAC) across your resources, and eliminate the need for cross-app/workspace queries.

-**Workspace-based resources are currently available in all commercial regions and Azure US Government.**

-Workspace-based Application Insights allows you to take advantage of all the latest capabilities of Azure Monitor and Log Analytics, including:

-* [Customer-Managed Keys (CMK)](../logs/customer-managed-keys.md) provides encryption at rest for your data with encryption keys that only you have access to.

-* [Azure Private Link](../logs/private-link-security.md) allows you to securely link Azure PaaS services to your virtual network using private endpoints.

-* [Bring Your Own Storage (BYOS) for Profiler and Snapshot Debugger](./profiler-bring-your-own-storage.md) gives you full control over:

- - Encryption-at-rest policy

- - Lifetime management policy

- - Network access for all data associated with Application Insights Profiler and Snapshot Debugger

-* [Commitment Tiers](../logs/cost-logs.md#commitment-tiers) enable you to save as much as 30% compared to the Pay-As-You-Go price. Otherwise, Pay-as-you-go data ingestion and data retention are billed similarly in Log Analytics as they are in Application Insights.

-* Faster data ingestion via Log Analytics streaming ingestion.

-> After migrating to a workspace-based Application Insights resource, telemetry from multiple Application Insights resources may be stored in a common Log Analytics workspace. You will still be able to pull data from a specific Application Insights resource, as described under [Understanding log queries](#understanding-log-queries).

-The migration process is **permanent, and cannot be reversed**. Once you migrate a resource to workspace-based Application Insights, it will always be a workspace-based resource. However, once you migrate you're able to change the target workspace as often as needed.

-If you don't need to migrate an existing resource, and instead want to create a new workspace-based Application Insights resource, use the [workspace-based resource creation guide](create-workspace-resource.md).

-## Pre-requisites

- - Workspace-based Application Insights resources aren't compatible with workspaces set to the dedicated **`workspace based permissions`** setting. To learn more about Log Analytics workspace access control, consult the [access control mode guidance](../logs/manage-access.md#access-control-mode)

- - If you don't already have an existing Log Analytics Workspace, [consult the Log Analytics workspace creation documentation](../logs/quick-create-workspace.md).

-Once the migration is complete, you can use [diagnostic settings](../essentials/diagnostic-settings.md) to configure data archiving to a storage account or streaming to Azure Event Hubs.

- > * Diagnostics settings uses a different export format/schema than continuous export, migrating will break any existing integrations with Stream Analytics.

- > * Diagnostic settings export may increase costs. ([more information](export-telemetry.md#diagnostic-settings-based-export))

- > - If you currently store Application Insights data for longer than the default 90 days and want to retain this larger retention period after migration, you will need to adjust your [workspace retention settings](/azure/azure-monitor/logs/data-retention-archive?tabs=portal-1%2Cportal-2#set-retention-and-archive-policy-by-table) from the default 90 days to the desired longer retention period.

- > - If youΓÇÖve selected data retention greater than 90 days on data ingested into the Classic Application Insights resource prior to migration, data retention will continue to be billed to through that Application Insights resource until that data exceeds the retention period.

- > - If the retention setting for your Application Insights instance under **Configure** > **Usage and estimated costs** > **Data Retention** is enabled, then use that setting to control the retention days for the telemetry data still saved in your classic resource's storage.

-This section walks through migrating a classic Application Insights resource to a workspace-based resource.

-1. From your Application Insights resource, select **Properties** under the **Configure** heading in the left-hand menu bar.

-

-2. Select **`Migrate to Workspace-based`**.

-

-

-3. Choose the Log Analytics workspace where you want all future ingested Application Insights telemetry to be stored. It can either be a Log Analytics workspace in the same subscription, or in a different subscription that shares the same Azure AD tenant. The Log Analytics workspace doesn't have to be in the same resource group as the Application Insights resource.

-> [!NOTE]

-> Migrating to a workspace-based resource can take up to 24 hours, but is usually faster than that. Please rely on accessing data through your Application Insights resource while waiting for the migration process to complete. Once completed, you will start seeing new data stored in the Log Analytics workspace tables.

-

-

-Once your resource is migrated, you'll see the corresponding workspace info in the **Overview** pane:

-

-Clicking the blue link text will take you to the associated Log Analytics workspace where you can take advantage of the new unified workspace query environment.

-> After migrating to a workspace-based Application Insights resource, we recommend using the [workspace's daily cap](../logs/daily-cap.md) to limit ingestion and costs instead of the cap in Application Insights.

-## Understanding log queries

-We still provide full backwards compatibility for your Application Insights classic resource queries, workbooks, and log-based alerts within the Application Insights experience.

-To write queries against the [new workspace-based table structure/schema](#workspace-based-resource-changes), you must first navigate to your Log Analytics workspace.

-If you have multiple Application Insights resources store telemetry in one Log Analytics workspace, but you only want to query data from one specific Application Insights resource, you have two options:

-Notice that if you query directly from the Log Analytics workspace, you'll only see data that is ingested post migration. To see both your classic Application Insights data and the new data ingested after migration in a unified query experience, use the **Logs** tab from within your migrated Application Insights resource.

-> If you rename your Application Insights resource after migrating to workspace-based model, the Application Insights Logs tab will no longer show the telemetry collected before renaming. You will be able to see all data (old and new) on the Logs tab of the associated Log Analytics resource.

-If you don't run the `az extension add` command, you'll see an error message that states: `az : ERROR: az monitor: 'app-insights' is not in the 'az monitor' command group. See 'az monitor --help'.`

-Now you can run the following to create your Application Insights resource:

-For the full Azure CLI documentation for this command, consult the [Azure CLI documentation](/cli/azure/monitor/app-insights/component#az-monitor-app-insights-component-update).

-The `Update-AzApplicationInsights` PowerShell command doesn't currently support migrating a classic Application Insights resource to workspace-based. To create a workspace-based resource with PowerShell, you can use the Azure Resource Manager templates below and deploy with PowerShell.

-## Modifying the associated workspace

-Once a workspace-based Application Insights resource has been created, you can modify the associated Log Analytics Workspace.

-There's usually no difference, with a couple of exceptions.

-There's no strict (billing-wise) capping available.

-### Will my old logs queries continue to work?

-### Will migration impact AppInsights API accessing data?

-No, migration won't impact existing API access to data. After migration, you'll be able to access data directly from a workspace using a [slightly different schema](#workspace-based-resource-changes).

-No, there's no impact to [Live Metrics](live-stream.md#live-metrics-monitor--diagnose-with-1-second-latency) or other monitoring experiences.

-### What happens with Continuous export after migration?

-You'll need to switch to [Diagnostic Settings](../essentials/diagnostic-settings.md#diagnostic-settings-in-azure-monitor).

-**Error message:** *The selected workspace is configured with workspace-based access mode. Some APM features may be impacted. Select another workspace or allow resource-based access in the workspace settings. You can override this error by using CLI.*

-In order for your workspace-based Application Insights resource to operate properly you need to change the access control mode of your target Log Analytics workspace to the **resource or workspace permissions** setting. This setting is located in the Log Analytics workspace UI under **Properties** > **Access control mode**. For detailed instructions, consult the [Log Analytics configure access control mode guidance](../logs/manage-access.md#access-control-mode). If your access control mode is set to the exclusive **Require workspace permissions** setting, migration via the portal migration experience will remain blocked.

-If you canΓÇÖt change the access control mode for security reasons for your current target workspace, we recommend creating a new Log Analytics workspace to use for the migration.

-**Error message:** *Continuous Export needs to be disabled before continuing. After migration, use Diagnostic Settings for export.*

-The legacy continuous export functionality isn't supported for workspace-based resources. Prior to migrating you need to disable continuous export.

-1. From your Application Insights resource view, under the **Configure** heading select **Continuous Export**.

- 

-2. Select **Disable**.

- 

-**Warning Message:** *Your customized Application Insights retention settings won't apply to data sent to the workspace. You'll need to reconfigure these separately.*

-You don't have to make any changes prior to migrating. This message alerts you that your current Application Insights retention settings aren't set to the default 90-day retention period. This warning message means you may want to modify the retention settings for your Log Analytics workspace prior to migrating and starting to ingest new data.

-You can check your current retention settings for Log Analytics under **General** > **Usage and estimated costs** > **Data Retention** from within the Log Analytics UI. This setting will affect how long any new ingested data is stored once you migrate your Application Insights resource.

-Prior to the introduction of [workspace-based Application Insights resources](create-workspace-resource.md), Application Insights data was stored separate from other log data in Azure Monitor. Both are based on Azure Data Explorer and use the same Kusto Query Language (KQL). Workspace-based Application Insights resources data is stored in a Log Analytics workspace, together with other monitoring data and application data. This simplifies your configuration by allowing you to analyze data across multiple solutions more easily, and to use the capabilities of workspaces.

-The structure of a Log Analytics workspace is described in [Log Analytics workspace overview](../logs/log-analytics-workspace-overview.md). For a classic application, the data isn't stored in a Log Analytics workspace. It uses the same query language, and you create and run queries by using the same Log Analytics tool in the Azure portal. Data items for classic applications are stored separately from each other. The general structure is the same as for workspace-based applications, although the table and column names are different.

-| dependencies | AppDependencies | Calls from the application to other components (including external components) recorded via TrackDependency() ΓÇô for example, calls to REST API, database or a file system. |

-| performanceCounters | AppPerformanceCounters | Performance measurements from the compute resources supporting the application, for example, Windows performance counters. |

-| exceptions | AppExceptions | Exceptions thrown by the application runtime, captures both server side and client-side (browsers) exceptions. |

-| traces | AppTraces | Detailed logs (traces) emitted through application code/logging frameworks recorded via TrackTrace(). |

-> Do not take a production dependency on the Log Analytics tables, until you see new telemetry records show up directly in Log Analytics. This might take up to 24 hours after the migration process started.

-The following sections show the mapping between the classic property names and the new workspace-based Application Insights property names. Use this information to convert any queries using legacy tables.

-Most of the columns have the same name with different capitalization. Since KQL is case-sensitive, you'll need to change each column name along with the table names in existing queries. Columns with changes in addition to capitalization are highlighted. You can still use your classic Application Insights queries within the **Logs** pane of your Application Insights resource, even if it's a workspace-based resource. The new property names are required for when querying from within the context of the Log Analytics workspace experience.

-> Older versions of Application Insights SDKs used to report standard deviation (valueStdDev) in the metrics pre-aggregation. Due to little adoption in metrics analysis, the field was removed and is no longer aggregated by the SDKs. If the value is received by the Application Insights data collection end point, it gets dropped during ingestion and is not sent to the Log Analytics workspace. If you are interested in using standard deviation in your analysis, we recommend using queries against Application Insights raw events.

-* [Write Analytics queries](../logs/log-query-overview.md)

-description: Provides instructions to wire up OpenCensus Python with Azure Monitor

-Microsoft's supported solution for tracking and exporting data for your Python applications is through the [Opencensus Python SDK](#introducing-opencensus-python-sdk) via the [Azure Monitor exporters](#instrument-with-opencensus-python-sdk-with-azure-monitor-exporters).

-Any other telemetry SDKs for Python are UNSUPPORTED and are NOT recommended by Microsoft to use as a telemetry solution.

-You may have noted that OpenCensus is converging into [OpenTelemetry](https://opentelemetry.io/). However, we continue to recommend OpenCensus while OpenTelemetry gradually matures.

-> A preview [OpenTelemetry-based Python offering](opentelemetry-enable.md?tabs=python) is available. [Learn more](opentelemetry-overview.md).

-## Introducing Opencensus Python SDK

-[OpenCensus](https://opencensus.io) is a set of open source libraries to allow collection of distributed tracing, metrics and logging telemetry. Through the use of [Azure Monitor exporters](https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-azure), you will be able to send this collected telemetry to Application insights. This article walks you through the process of setting up OpenCensus and Azure Monitor Exporters for Python to send your monitoring data to Azure Monitor.

-The SDK uses three Azure Monitor exporters to send different types of telemetry to Azure Monitor. They are `trace`, `metrics`, and `logs`. For more information on these telemetry types, see [the data platform overview](../data-platform.md). Use the following instructions to send these telemetry types via the three exporters.

-Here are the exporters that OpenCensus provides mapped to the types of telemetry that you see in Azure Monitor.

-1. Although entering values is helpful for demonstration purposes, ultimately we want to emit the log data to Azure Monitor. Pass your connection string directly into the exporter. Or, you can specify it in an environment variable, `APPLICATIONINSIGHTS_CONNECTION_STRING`. We recommend using the connection string to instantiate the exporters that are used to send telemetry to Application Insights. Modify your code from the previous step based on the following code sample:

- > [!NOTE]

- > In this context, `traces` isn't the same as `tracing`. Here, `traces` refers to the type of telemetry that you'll see in Azure Monitor when you utilize `AzureLogHandler`. But `tracing` refers to a concept in OpenCensus and relates to [distributed tracing](./distributed-tracing.md).

- > The root logger is configured with the level of WARNING. That means any logs that you send that have less of a severity are ignored, and in turn, won't be sent to Azure Monitor. For more information, see [documentation](https://docs.python.org/3/library/logging.html#logging.Logger.setLevel).

-1. You can also add custom properties to your log messages in the *extra* keyword argument by using the custom_dimensions field. These properties appear as key-value pairs in `customDimensions` in Azure Monitor.

- > For this feature to work, you need to pass a dictionary to the custom_dimensions field. If you pass arguments of any other type, the logger ignores them.

-> As part of using Application Insights instrumentation, we collect and send diagnostic data to Microsoft. This data helps us run and improve Application Insights. You have the option to disable non-essential data collection. [Learn More](./statsbeat.md).

-You can configure logging explicitly in your application code like above for your Django applications, or you can specify it in Django's logging configuration. This code can go into whatever file you use for Django settings configuration. For how to configure Django settings, see [Django settings](https://docs.djangoproject.com/en/4.0/topics/settings/). For more information on configuring logging, see [Django logging](https://docs.djangoproject.com/en/4.0/topics/logging/).

-OpenCensus Python doesn't automatically track and send `exception` telemetry. They're sent through `AzureLogHandler` by using exceptions through the Python logging library. You can add custom properties just like with normal logging.

-Because you must log exceptions explicitly, it's up to the user how they want to log unhandled exceptions. OpenCensus doesn't place restrictions on how a user wants to do this, as long as they explicitly log an exception telemetry.

-You can send `customEvent` telemetry in exactly the same way that you send `trace` telemetry except by using `AzureEventHandler` instead.

-For information on sampling in OpenCensus, take a look at [sampling in OpenCensus](sampling.md#configuring-fixed-rate-sampling-for-opencensus-python-applications).

-For details on how to enrich your logs with trace context data, see OpenCensus Python [logs integration](./correlation.md#log-correlation).

-For details on how to modify tracked telemetry before it's sent to Azure Monitor, see OpenCensus Python [telemetry processors](./api-filtering-sampling.md#opencensus-python-telemetry-processors).

-OpenCensus.stats supports 4 aggregation methods but provides partial support for Azure Monitor:

-### Count Aggregation example

-1. First, let's generate some local metric data. We'll create a simple metric to track the number of times the user selects the **Enter** key.

-1. Although entering values is helpful for demonstration purposes, ultimately we want to emit the metric data to Azure Monitor. Pass your connection string directly into the exporter. Or, you can specify it in an environment variable, `APPLICATIONINSIGHTS_CONNECTION_STRING`. We recommend using the connection string to instantiate the exporters that are used to send telemetry to Application Insights. Modify your code from the previous step based on the following code sample:

-1. The exporter sends metric data to Azure Monitor at a fixed interval. The default is every 15 seconds. To modify the export interval, pass in `export_interval` as a parameter in seconds to `new_metrics_exporter()`. We're tracking a single metric, so this metric data, with whatever value and time stamp it contains, is sent every interval. The value is cumulative, can only increase and resets to 0 on restart. You can find the data under `customMetrics`, but `customMetrics` properties valueCount, valueSum, valueMin, valueMax, and valueStdDev are not effectively used.

-### Setting custom dimensions in metrics

-Opencensus Python SDK allows adding custom dimensions to your metrics telemetry by the way of `tags`, which are essentially a dictionary of key/value pairs.

-1. For a specific `View`, specify the tags you want to use when recording metrics with that view via the tag key.

-1. Be sure to use the tag map when recording in the measurement map. The tag keys that are specified in the `View` must be found in the tag map used to record.

-1. Under the `customMetrics` table, all metrics records emitted using the `prompt_view` will have custom dimensions `{"url":"http://example.com"}`.

-1. To produce tags with different values using the same keys, create new tag maps for them.

-By default, the metrics exporter sends a set of performance counters to Azure Monitor. You can disable this by setting the `enable_standard_metrics` flag to `False` in the constructor of the metrics exporter.

-These performance counters are currently sent:

-You should be able to see these metrics in `performanceCounters`. For more information, see [performance counters](./performance-counters.md).

-> In OpenCensus, `tracing` refers to [distributed tracing](./distributed-tracing.md). The `AzureExporter` sends `requests` and `dependency` telemetry to Azure Monitor.

-1. Running the code repeatedly prompts you to enter a value. With each entry, the value is printed to the shell. The OpenCensus Python Module generates a corresponding piece of `SpanData`. The OpenCensus project defines a [trace as a tree of spans](https://opencensus.io/core-concepts/tracing/).

-1. Although entering values is helpful for demonstration purposes, ultimately we want to emit `SpanData` to Azure Monitor. Pass your connection string directly into the exporter. Or, you can specify it in an environment variable, `APPLICATIONINSIGHTS_CONNECTION_STRING`. We recommend using the connection string to instantiate the exporters that are used to send telemetry to Application Insights. Modify your code from the previous step based on the following code sample:

-1. Now when you run the Python script, you should still be prompted to enter values, but only the value is being printed in the shell. The created `SpanData` is sent to Azure Monitor. You can find the emitted span data under `dependencies`. For more information about outgoing requests, see OpenCensus Python [dependencies](./opencensus-python-dependency.md).

-For more information on incoming requests, see OpenCensus Python [requests](./opencensus-python-request.md).

-For information on sampling in OpenCensus, take a look at [sampling in OpenCensus](sampling.md#configuring-fixed-rate-sampling-for-opencensus-python-applications).

-For more information on telemetry correlation in your trace data, take a look at OpenCensus Python [telemetry correlation](./correlation.md#telemetry-correlation-in-opencensus-python).

-As shown, there are three different Azure Monitor exporters that support OpenCensus. Each one sends different types of telemetry to Azure Monitor. To see what types of telemetry each exporter sends, see the following list.

-Each exporter accepts the same arguments for configuration, passed through the constructors. You can see details about each one here:

-Users who want to capture custom telemetry in Azure Functions environments are encouraged to used the OpenCensus Python Azure Functions [extension](https://github.com/census-ecosystem/opencensus-python-extensions-azure/tree/main/extensions/functions#opencensus-python-azure-functions-extension). More details can be found in this [document](../../azure-functions/functions-reference-python.md#log-custom-telemetry).

-> Authentication feature is available starting from `opencensus-ext-azure` v1.1b0

-Each of the Azure Monitor exporters supports configuration of securely sending telemetry payloads via OAuth authentication with Azure Active Directory (AAD).

-For more information, check out the [Authentication](./azure-ad-authentication.md) documentation.

-

-For more detailed information about how to use queries and logs, see [Logs in Azure Monitor](../logs/data-platform-logs.md).

-* [Azure Monitor Exporters on GitHub](https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-azure)

-* [OpenCensus Integrations](https://github.com/census-instrumentation/opencensus-python#extensions)

-* [Azure Monitor Sample Applications](https://github.com/Azure-Samples/azure-monitor-opencensus-python/tree/master/azure_monitor)

-* [Tracking out-going requests](./opencensus-python-request.md)

-description: Provides an overview of how to use OpenTelemetry with Azure Monitor.

-Microsoft is excited to embrace [OpenTelemetry](https://opentelemetry.io/) as the future of telemetry instrumentation. You, our customers, have asked for vendor-neutral instrumentation, and we're delighted to partner with the OpenTelemetry community to create consistent APIs/SDKs across languages.

-Microsoft worked together with project stakeholders from two previously popular open-source telemetry projects, [OpenCensus](https://opencensus.io/) and [OpenTracing](https://opentracing.io/), to help create a single project--OpenTelemetry. OpenTelemetry includes contributions from all major cloud and Application Performance Management (APM) vendors and lives within the [Cloud Native Computing Foundation (CNCF)](https://www.cncf.io/) of which Microsoft is a Platinum Member.

-1. Distributed Tracing

-2. Metrics

-3. Logs

-Initially the OpenTelemetry community took on Distributed Tracing. Metrics and Logs are still in progress. A complete observability story includes all three pillars, but currently our [Azure Monitor OpenTelemetry-based exporter **preview** offerings for .NET, Python, and JavaScript](opentelemetry-enable.md) **only include Distributed Tracing**.

-There are several sources that explain the three pillars in detail including the [OpenTelemetry community website](https://opentelemetry.io/docs/concepts/data-collection/), [OpenTelemetry Specifications](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/overview.md), and [Distributed Systems Observability](https://www.oreilly.com/library/view/distributed-systems-observability/9781492033431/ch04.html) by Cindy Sridharan.

-### Instrumenting your application

-At a basic level, "instrumentingΓÇ¥ is simply enabling an application to capture telemetry.

-1. Manual Instrumentation

-2. Automatic Instrumentation (Auto-Instrumentation)

-Manual instrumentation is coding against the OpenTelemetry API. In the context of an end user, it typically refers to installing a language-specific SDK in an application. Manual instrumentation packages consist of our [Azure Monitor OpenTelemetry-based exporter **preview** offerings for .NET, Python, and JavaScript](opentelemetry-enable.md).

-> ΓÇ£ManualΓÇ¥ does **NOT** mean youΓÇÖll be required to write complex code to define spans for distributed traces (though it remains an option). A rich and growing set of instrumentation libraries maintained by OpenTelemetry contributors will enable you to effortlessly capture telemetry signals across common frameworks and libraries. A subset of OpenTelemetry Instrumentation Libraries will be supported by Azure Monitor, informed by customer feedback. Additionally, we are working to [instrument the most popular Azure Service SDKs using OpenTelemetry](https://devblogs.microsoft.com/azure-sdk/introducing-experimental-opentelemetry-support-in-the-azure-sdk-for-net/).

-On the other hand, auto-instrumentation is enabling telemetry collection through configuration without touching the application's code. While more convenient, it tends to be less configurable and itΓÇÖs not available in all languages. Azure MonitorΓÇÖs OpenTelemetry-based auto-instrumentation offering consists of the [Java 3.X OpenTelemetry-based GA offering](java-in-process-agent.md), and we continue to invest in it informed by customer feedback. The OpenTelemetry community is also experimenting with C# and Python auto-instrumentation, but Azure Monitor is focused on creating a simple and effective manual instrumentation story in the near-term.

-### Sending your telemetry

-There are also two ways to send your data to Azure Monitor (or any vendor).

-1. Direct Exporter

-2. Via an Agent

-A direct exporter sends telemetry in-process (from the applicationΓÇÖs code) directly to Azure MonitorΓÇÖs ingestion endpoint. The main advantage of this approach is onboarding simplicity.

-**All Azure MonitorΓÇÖs currently supported OpenTelemetry-based offerings use a direct exporter**.

-Alternatively, sending telemetry via an agent will provide a path for any OpenTelemetry supported language to send to Azure Monitor via [OTLP](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/README.md). Receiving OTLP will enable customers to observe applications written in languages beyond our [supported languages](platforms.md).

-> Some customers have begun to use the [OpenTelemetry-Collector](https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/design.md) as an agent alternative even though Microsoft doesnΓÇÖt officially support ΓÇ£Via an AgentΓÇ¥ approach for application monitoring yet. In the meantime, the open source community has contributed an OpenTelemetry-Collector Azure Monitor Exporter that some customers are using to send data to Azure Monitor Application Insights.

-See [glossary](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md) in the OpenTelemetry specifications.

-Some legacy terms in Application Insights are confusing given the industry convergence on OpenTelemetry. The table below highlights these differences. Eventually Application Insights terms will be replaced by OpenTelemetry terms.

-Auto-Collectors | Instrumentation Libraries

-Channel | Exporter

-Codeless / Agent-based | Auto-Instrumentation

-## Next step

-The following pages consist of language-by-language guidance to enable and configure MicrosoftΓÇÖs OpenTelemetry-based offerings. Importantly, we share the available functionality and limitations of each offering so you can determine whether OpenTelemetry is right for your project.

-description: Monitor applications with Azure Application Insights and Overview Dashboard functionality.

-Application Insights has always provided a summary overview pane to allow quick, at-a-glance assessment of your application's health and performance. The new overview dashboard provides a faster more flexible experience.

-The new overview dashboard now launches by default:

-

-

-Overall performance has been greatly increased. You have one-click access to popular features like **Search** and **Analytics**. Each default dynamically updating KPI tile provides insight into corresponding Application Insights features. To learn more about failed requests select **Failures** under the **Investigate** header:

-

-Application dashboard leverages the existing dashboard technology within Azure to provide a fully customizable single pane view of your application health and performance.

-To access the default dashboard select _Application Dashboard_ in the upper left corner.

-

-If this is your first time accessing the dashboard, it will launch a default view:

-

-You can keep the default view if you like it. Or you can also add, and delete from the dashboard to best fit the needs of your team.

-> All users with access to the Application Insights resource share the same Application dashboard experience. Changes made by one user will modify the view for all users.

-To navigate back to the overview experience just select:

-

-There is currently a limit of 30 days of data for data displayed in a dashboard.If you select a time filter beyond 30 days, or if you select **Configure tile settings** and set a custom time range in excess of 30 days your dashboard will not display beyond 30 days of data, even with the default data retention of 90 days. There is currently no workaround for this behavior.

-The default Application Dashboard is created during Application Insights resource creation. If you move or rename your Application Insights instance, then queries on the dashboard will fail with Resource not found errors as the dashboard queries rely on the original resource URI. Delete the default dashboard, then from the Application Insights Overview resource menu select Application Dashboard again and the default dashboard will be re-created with the new resource name. Make other custom edits to the dashboard as needed.

-description: Tutorial to send alerts in response to errors in your application using Azure Application Insights.

-# Monitor and alert on application health with Azure Application Insights

-Azure Application Insights allows you to monitor your application and send you alerts when it is either unavailable, experiencing failures, or suffering from performance issues. This tutorial takes you through the process of creating tests to continuously check the availability of your application.

-You learn how to:

-> * Create availability test to continuously check the response of the application

-> * Send mail to administrators when a problem occurs

-To complete this tutorial:

-Create an [Application Insights resource](../app/create-new-resource.md).

-Sign in to the Azure portal at [https://portal.azure.com](https://portal.azure.com).

-Availability tests in Application Insights allow you to automatically test your application from various locations around the world. In this tutorial, you will perform a url test to ensure that your web application is available. You could also create a complete walkthrough to test its detailed operation.

-1. Select **Application Insights** and then select your subscription.

-2. Select **Availability** under the **Investigate** menu and then click **Create test**.

- 

-3. Type in a name for the test and leave the other defaults. This selection will trigger requests for the application url every 5 minutes from five different geographic locations.

-4. Select **Alerts** to open the **Alerts** dropdown where you can define details for how to respond if the test fails. Choose **Near-realtime** and set the status to **Enabled.**

- Type in an email address to send when the alert criteria is met. You could optionally type in the address of a webhook to call when the alert criteria is met.

- 

-5. Return to the test panel, select the ellipses and edit alert to enter the configuration for your near-realtime alert.

- 

-6. Set failed locations to greater than or equal to 3. Create an [action group](../alerts/action-groups.md) to configure who gets notified when your alert threshold is breached.

- 

-7. Once you have configured your alert, click on the test name to view details from each location. Tests can be viewed in both line graph and scatter plot format to visualize the success/failures for a given time range.

- 

-8. You can drill down into the details of any test by clicking on its dot in the scatter chart. This will launch the end-to-end transaction details view. The example below shows the details for a failed request.

- 

-

-> Entries in the activity log are system generated and can't be changed or deleted.

-If a log profile already exists, you first must remove the existing log profile and then create a new one.

-If a log profile already exists, you first must remove the existing log profile and then create a log profile.

-The primary method for visualizing Prometheus metrics is [Azure Managed Grafana](../../managed-grafan). Connect your Azure Monitor workspace to a Grafana workspace so that it can be used as a data source in a Grafana dashboard. You then have access to multiple prebuilt dashboards that use Prometheus metrics and the ability to create any number of custom dashboards.

-> Queries against Application Insights table except `SystemEvents` will work for both a workspace-based and classic Application Insights resource, since [backwards compatibility](../app/convert-classic-resource.md#understanding-log-queries) allows you to continue to use [legacy table names](../app/apm-tables.md). For a workspace-based resource, open **Logs** from the **Log Analytics workspace** menu. For a classic resource, open **Logs** from the **Application Insights** menu.

-## August 2022

-### Application-insights

-### Change-analysis

-| Microsoft.MachineLearningServices/workspaces/computes | [listKeys](/rest/api/azureml/2022-05-01/compute/list-keys) |

-| Microsoft.MachineLearningServices/workspaces/computes | [listNodes](/rest/api/azureml/2022-05-01/compute/list-nodes) |

-| Microsoft.MachineLearningServices/workspaces | [listKeys](/rest/api/azureml/2022-05-01/workspaces/list-keys) |

-| Microsoft.MachineLearningServices/workspaces/computes | [listKeys](/rest/api/azureml/2022-05-01/compute/list-keys) |

-| Microsoft.MachineLearningServices/workspaces/computes | [listNodes](/rest/api/azureml/2022-05-01/compute/list-nodes) |

-| Microsoft.MachineLearningServices/workspaces | [listKeys](/rest/api/azureml/2022-05-01/workspaces/list-keys) |

-The vSAN datastore capacity can be expanded by connecting Azure storage resources such as [Azure NetApp Files volumes as datastores](/azure/azure-vmware/attach-azure-netapp-files-to-azure-vmware-solution-hosts). Virtual machines can be migrated between vSAN and Azure NetApp Files datastores using storage vMotion. Azure NetApp Files datastores can be replicated to other regions using storage based [Cross-region replication](/azure/azure-netapp-files/cross-region-replication-introduction) for testing, development and failover purposes.

-Multi-user authorization (MUA) for Azure Backup allows you to add an additional layer of protection to critical operations on your Recovery Services vaults. For MUA, Azure Backup uses another Azure resource called the Resource Guard to ensure critical operations are performed only with applicable authorization.

-Azure Backup uses the Resource Guard as an authorization service for a Recovery Services vault. Therefore, to perform a critical operation (described below) successfully, you must have sufficient permissions on the associated Resource Guard as well.

-> To function as intended, the Resource Guard must be owned by a different user, and the vault admin must not have Contributor permissions. You can place Resource Guard in a subscription or tenant different from the one containing the Recovery Services vault to provide better protection.

-The following table lists the operations defined as critical operations and can be protected by a Resource Guard. You can choose to exclude certain operations from being protected using the Resource Guard when associating vaults with it. Note that operations denoted as Mandatory cannot be excluded from being protected using the Resource Guard for vaults associated with it. Also, the excluded critical operations would apply to all vaults associated with a Resource Guard.

-**Operation** | **Mandatory/Optional**

-Modify backup policy (reduced retention) | Optional: Can be excluded

-Modify protection (reduced retention) | Optional: Can be excluded

-Stop protection with delete data | Optional: Can be excluded

-Change MARS security PIN | Optional: Can be excluded

-The concepts and the processes involved when using MUA for Backup are explained below.

-**Backup admin**: Owner of the Recovery Services vault and performs management operations on the vault. To begin with, the Backup admin must not have any permissions on the Resource Guard.

-Here is the flow of events in a typical scenario:

-1. The Backup admin creates the Recovery Services vault.

-1. The Security admin creates the Resource Guard. The Resource Guard can be in a different subscription or a different tenant with respect to the Recovery Services vault. It must be ensured that the Backup admin does not have Contributor permissions on the Resource Guard.

-1. The Backup admin now configures the Recovery Services vault to be protected by MUA via the Resource Guard.

- - If the Backup admin did not have the required permissions/roles, the request would have failed.

->- MUA provides protection on the above listed operations performed on the Recovery Services vaults only. Any operations performed directly on the data source (i.e., the Azure resource/workload that is protected) are beyond the scope of the Resource Guard.

->- This feature is currently available via the Azure portal only.

->- This feature is currently supported for Recovery Services vaults only and not available for Backup vaults.

-The following table depicts scenarios for creating your Resource Guard and Recovery Services vault (RS vault), along with the relative protection offered by each.

-RS vault and Resource Guard are **in the same subscription.** </br> The Backup admin does not have access to the Resource Guard. | Least isolation between the Backup admin and the Security admin. | Relatively easy to implement since only one subscription is required. | Resource level permissions/ roles need to be ensured are correctly assigned.

-RS vault and Resource Guard are **in different subscriptions but the same tenant.** </br> The Backup admin does not have access to the Resource Guard or the corresponding subscription. | Medium isolation between the Backup admin and the Security admin. | Relatively medium ease of implementation since two subscriptions (but a single tenant) are required. | Ensure that that permissions/ roles are correctly assigned for the resource or the subscription.

-RS vault and Resource Guard are **in different tenants.** </br> The Backup admin does not have access to the Resource Guard, the corresponding subscription, or the corresponding tenant.| Maximum isolation between the Backup admin and the Security admin, hence, maximum security. | Relatively difficult to test since requires two tenants or directories to test. | Ensure that permissions/ roles are correctly assigned for the resource, the subscription or the directory.

- >[!NOTE]

- > For this article, we will demonstrate creation of the Resource Guard in a different tenant that offers maximum protection. In terms of requesting and approving requests for performing critical operations, this article demonstrates the same using [Azure Active Directory Privileged Identity Management](../active-directory/privileged-identity-management/pim-configure.md) in the tenant housing the Resource Guard. You can optionally use other mechanisms to manage JIT permissions on the Resource Guard as per your setup.

-[Configure Multi-user authorization using Resource Guard](multi-user-authorization.md)

-2. Select **Disable** for operations that you wish to exclude from being authorized using the Resource Guard. Note that the operations **Disable soft delete** and **Remove MUA protection** cannot be disabled.

-1. Click **Save**.

-This article describes how to configure Multi-user authorization (MUA) for Azure Backup to add an additional layer of protection to critical operations on your Recovery Services vaults

-This document includes the following:

->- Protect against unauthorized operations on a vault

-Learn about various [MUA usage scenarios](multi-user-authorization-concept.md#usage-scenarios).

-1. In the Azure portal, go to the directory under which you wish to create the Resource Guard.

-1. Search for **Resource Guards** in the search bar and select the corresponding item from the drop-down.

- - Click **Create** to start creating a Resource Guard.

- - Also, it is helpful to add a description of how to get or request access to perform actions on associated vaults when needed. This description would also appear in the associated vaults to guide the backup admin on getting the required permissions. You can edit the description later if needed, but having a well-defined description at all times is encouraged.

- You can also [select the operations to be protected after creating the resource guard](#select-operations-to-protect-using-resource-guard).

-1. Click **Review + Create**.

-1. Follow notifications for status and successful creation of the Resource Guard.

-2. Select **Disable** for operations that you wish to exclude from being authorized using the Resource Guard. Note that the operations **Disable soft delete** and **Remove MUA protection** cannot be disabled.

-3. Optionally, you can also update the description for the Resource Guard using this blade.

-4. Click **Save**.

-1. In the Resource Guard created above, go to the Access Control (IAM) blade, and then go to **Add role assignment**.

-1. Select **Reader** from the list of built-in roles and click **Next** on the bottom of the screen.

-1. Click **Select members** and add the Backup adminΓÇÖs email ID to add them as the **Reader**. Since the Backup admin is in another tenant in this case, they will be added as guests to the tenant containing the Resource Guard.

-1. Now you are presented with the option to enable MUA and choose a Resource Guard using one of the following ways:

- 1. Or you can select the Resource Guard from the list of Resource Guards you have **Reader** access to, and those available in the region.

-1. Click **Save** once done to enable MUA

-## Protect against unauthorized (protected) operations

-Once you have enabled MUA, the operations in scope will be restricted on the vault, if the Backup admin tries to perform them without having the required role (i.e., Contributor role) on the Resource Guard.

- >It is highly recommended that you test your setup after enabling MUA to ensure that protected operations are blocked as expected and to ensure that MUA is correctly configured.

-1. To disable soft delete, go to the Recovery Services Vault > Properties > Security Settings and click **Update**, which brings up the Security Settings.

-1. Disable the soft delete using the slider. You are informed that this is a protected operation, and you need to verify their access to the Resource Guard.

-1. Proceed to click **Save**. The request fails with an error informing them about not having sufficient permissions on the Resource Guard to let you perform this operation.

-The following sub-sections discuss authorizing these requests using PIM. There are cases where you may need to perform critical operations on your backups and MUA can help you ensure that these are performed only when the right approvals or permissions exist. As discussed earlier, the Backup admin needs to have a Contributor role on the Resource Guard to perform critical operations that are in the Resource Guard scope. One of the ways to allow just-in-time for such operations is through the use of [Azure Active Directory (Azure AD) Privileged Identity Management](../active-directory/privileged-identity-management/pim-configure.md).

-> Though using Azure AD PIM is the recommended approach, you can use manual or custom methods to manage access for the Backup admin on the Resource Guard. For managing access to the Resource Guard manually, use the ΓÇÿAccess control (IAM)ΓÇÖ setting on the left navigation bar of the Resource Guard and grant the **Contributor** role to the Backup admin.

- 1. If you donΓÇÖt see the corresponding resource in the list of resources, ensure you add the containing subscription to be managed by PIM.

-1. In the Add assignments

- 1. Go to Select members and add the username (or email IDs) of the Backup admin

- 1. Click Next

-1. In the next screen

- 1. Click **Assign** to finish creating the eligible assignment.

-Note if this is not configured, any requests will be automatically approved without going through the security admins or a designated approverΓÇÖs review. More details on this can be found [here](../active-directory/privileged-identity-management/pim-resource-roles-configure-role-settings.md)

-1. If the setting named **Approvers** shows None or displays incorrect approvers, click **Edit** to add the reviewers who would need to review and approve the activation request for the Contributor role.

-1. In the **Activation** tab, select **Require approval to activate** and add the approver(s) who need to approve each request. You can also select other security options like using MFA and mandating ticket options to activate the Contributor role. Optionally, select relevant settings in the **Assignment** and **Notification** tabs as per your requirements.

-1. Click **Update** once done.

-1. Go to My roles > Azure resources on the left menu.

-1. The Backup admin can see an Eligible assignment for the contributor role. Click **Activate** to activate it.

-1. Review the request. If genuine, select the request and click **Approve** to approve it.

-1. The Backup admin goes to the vault -> **Properties** -> **Multi-user Authorization**.

-1. Click **Update**

- 1. Uncheck the Protect with Resource Guard check box

- 1. After **authentication**, click **Save**. With the right access, the request should be successfully completed.

- - [Multi-user authorization using Resource Guard is now generally available](#multi-user-authorization-using-resource-guard-is-now-generally-available)

- - [Multi-user authorization using Resource Guard (in preview)](#multi-user-authorization-using-resource-guard-in-preview)

-## Multi-user authorization using Resource Guard is now generally available

-## Multi-user authorization using Resource Guard (in preview)

-## Alternative: Use Azure Key Vault VM Extension with Pool User-assigned Managed Identity

- No. `CloudServiceConfiguration` pools will be [retired](https://azure.microsoft.com/updates/azure-batch-cloudserviceconfiguration-pools-will-be-retired-on-29-february-2024/) on the same date as Azure Batch account certificate retirement on February 29, 2024. We recommend that you migrate to `VirtualMachinceConfiguration` pools before that date where you'll be able to use these solutions.

-To support security best practices and remain in compliance with industry standards, Azure Batch will retire Transport Layer Security (TLS) 1.0 and TLS 1.1 in Azure Batch on *March 31, 2023*. Learn how to migrate to TLS 1.2 in the client code you manage by using Batch.

-Most customers have already migrated to TLS 1.2. Customers who continue to use TLS 1.0 or TLS 1.1 can be identified via existing BatchOperation data. If you're using TLS 1.0 or TLS 1.1, to avoid disruption to your Batch workflows, update existing workflows to use TLS 1.2.

- TLS 1.0 and TLS 1.1 have security issues that are fixed in TLS 1.2. TLS 1.2 has been available since 2008. TLS 1.2 is the current default version in most development frameworks.

- After the feature retirement from Azure Batch, your client application won't work until you upgrade the code to use TLS 1.2.

- Upgrading to TLS 1.2 won't affect your application's performance.

- To determine the TLS version you're using, check the audit log for your Batch deployment.

-> You can either use a pronunciation data file on its own, or you can add pronunciation within a structured text data file. The Speech service doesn't support training a model where you select both of those datasets as input.

-* Speech SDK 1.23.0 and Speech CLI 1.23.0 were released in July 2022. See details below.

-The intensity of speaking style can be adjusted to better fit your use case. You specify a stronger or softer style with the `styledegree` attribute to make the speech more expressive or subdued.

-Apart from adjusting the speaking styles and style degree, you can also adjust the `role` parameter so that the voice imitates a different age and gender. For example, a male voice can raise the pitch and change the intonation to imitate a female voice, but the voice name won't be changed.

-> The `lexeme` element is case sensitive in the custom lexicon. For example, if you only provide a phoneme for the `lexeme` "Hello," it won't work for the `lexeme` "hello."

->

-> Currently, `redlips_front` only supports neural voices in `en-US` locale, and `FacialExpression` supports neural voices in `en-US` and `zh-CN` locales.

-* [Conversation summarization](../summarization/language-support.md?tabs=conversation-summarization)|

-Language service features utilize AI models that are versioned. We update the language service with new model versions to improve accuracy, support, and quality. As models become older, they are retired. Use this article for information on that process, and what you can expect for your applications.

-As new models and functionalities become available, older less accurate models are deprecated. To ensure you are using the latest model version and avoid interruptions to your applications, we highly recommend using the default model-version parameter (`latest`) in your API calls. After their deprecation date, pre-built model versions will no longer be functional and your implementation may be broken.

-| Named Entity Recognition (NER) | `2021-06-01*` | `2019-10-01`, `2020-02-01`, `2020-04-01`, `2021-01-15` |

-New configs are being released every few months. So, training configs expiration of any publicly available config is **six months** after its release. If you have assigned a trained model to a deployment, this deployment expires after **twelve months** from the training config expiration.

-After training config version expires, API calls will return an error when called or used if called with an expired config version. By default, training requests will use the latest available training config version. To change the config version, use `trainingConfigVersion` when submitting a training job and assign the version you want.

-| Custom text classification | `2022-05-01` | `10/28/2022` | `10/28/2023` |

-| Custom named entity recognition | `2022-05-01` | `10/28/2022` | `10/28/2023` |

-If you are using the [Language Studio](https://aka.ms/languageStudio) for building your project you will be using the latest API version available. If you need to use another API version this is only available directly through APIs.

-| Custom text classification | `2022-05-01` | `2022-05-01` | |

-| Conversational language understanding | `2022-05-01` | `2022-05-01` | |

-| Custom named entity recognition | `2022-05-01` | `2022-05-01` | |

-| Orchestration workflow | `2022-05-01` | `2022-05-01` | |

-An entity component determines a way you can extract the entity. An entity can simply contain one component, which would determine the only method that would be used to extract the entity, or multiple components to expand the ways in which the entity is defined and extracted.

-> [!NOTE]

-> During public preview of the service, there were 4 available options: **Longest overlap**, **Exact overlap**, **Union overlap**, and **Return all separately**. **Longest overlap** and **exact overlap** are deprecated and will only be supported for projects that previously had those options selected. **Union overlap** has been renamed to **Combine components**, while **Return all separately** has been renamed to **Do not combine components**.

-When you do not combine components, you simply allow every component to act as an independent entity extractor. One way of using this option is to separate the entities extracted from a list to the ones extracted through the learned or prebuilt components to handle and treat them differently.

- |F0|Free tier|You are only allowed **One** Language resource **per subscription**.|

-Conversational language understanding is only available in some Azure regions. To use conversational language understanding, you must choose a Language resource in one of following regions:

-* Australia East

-* Central India

-* East US

-* East US 2

-* North Europe

-* South Central US

-* Switzerland North

-* UK South

-* West Europe

-* West US 2

-* West US 3

-| Project name | You can only use letters `(a-z, A-Z)`, and numbers `(0-9)` ,symbols `_ . -`,with no spaces. Maximum allowed length is 50 characters. |

-| Language | Language code | Starting with model version: | Notes |

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

-| Arabic* | `ar` | 2019-10-01 | |

-| Chinese-Simplified | `zh-hans` | 2021-01-15 | `zh` also accepted |

-| Chinese-Traditional* | `zh-hant` | 2019-10-01 | |

-| Czech* | `cs` | 2019-10-01 | |

-| Danish* | `da` | 2019-10-01 | |

-| Dutch* | `nl` | 2019-10-01 | |

-| English | `en` | 2019-10-01 | |

-| Finnish* | `fi` | 2019-10-01 | |

-| French | `fr` | 2021-01-15 | |

-| German | `de` | 2021-01-15 | |

-| Hebrew | `he` | 2022-10-01 | |

-| Hindi | `hi` | 2022-10-01 | |

-| Hungarian* | `hu` | 2019-10-01 | |

-| Italian | `it` | 2021-01-15 | |

-| Japanese | `ja` | 2021-01-15 | |

-| Korean | `ko` | 2021-01-15 | |

-| Norwegian (Bokmål)* | `no` | 2019-10-01 | `nb` also accepted |

-| Polish* | `pl` | 2019-10-01 | |

-| Portuguese (Brazil) | `pt-BR` | 2021-01-15 | |

-| Portuguese (Portugal) | `pt-PT` | 2021-01-15 | `pt` also accepted |

-| Russian* | `ru` | 2019-10-01 | |

-| Spanish | `es` | 2020-04-01 | |

-| Swedish* | `sv` | 2019-10-01 | |

-| Turkish* | `tr` | 2019-10-01 | |

-[PII feature overview](overview.md)

-* Your Language resource has to be created in one of the [supported regions](#regional-support).

-## Regional support

-Orchestration workflow is only available in some Azure regions. To use orchestration workflow, you must choose a Language resource in one of following regions:

-* West US 2

-* East US

-* East US 2

-* West US 3

-* South Central US

-* West Europe

-* North Europe

-* UK south

-* Australia East

-| Project name | You can only use letters `(a-z, A-Z)`, and numbers `(0-9)` ,symbols `_ . -`,with no spaces. Maximum allowed length is 50 characters. |

-Within your Communications Resource, we have provided an **Insights Preview** feature that displays a number of data visualizations conveying insights from the Azure Monitor logs and metrics monitored for your Communications Services. The visualizations within Insights is made possible via [Azure Monitor Workbooks](../../../azure-monitor/visualize/workbooks-overview.md). In order to take advantage of Workbooks, follow the instructions outlined in [Enable Azure Monitor in Diagnostic Settings](enable-logging.md), and to enable Workbooks, you will need to send your logs to a [Log Analytics workspace](../../../azure-monitor/logs/log-analytics-overview.md) destination.

-For an in-depth description of workbooks, please refer to the [Azure Monitor Workbooks](../../../azure-monitor/visualize/workbooks-overview.md) documentation.

-In this article, you will learn about Azure AD permissions available for communication as a Teams user in Azure Communication Services.

-| Mixed audio+video | Mp4 | Single file, single channel | Keeping records and meeting notes Coaching and Training | Public Preview |

-| Mixed audio | Mp3 (lossy)/ wav (lossless) | Single file, single channel | Compliance & Adherence Coaching and Training | Public Preview |

-| **Unmixed audio** | wav | Single file, up to 5 wav channels | Quality Assurance Analytics | **Private Preview** |

-Run-time control APIs can be used to manage recording via internal business logic triggers, such as an application creating a group call and recording the conversation. Also, recordings can be triggered by a user action that tells the server application to start recording. Call Recording APIs are [Out-of-Call APIs](./call-automation-apis.md#out-of-call-apis), using the `serverCallId` to initiate recording. Once a call is created, a `serverCallId` is returned via the `Microsoft.Communication.CallLegStateChanged` event after a call has been established. The `serverCallId` can be found in the `data.serverCallId` field. See our [Call Recording Quickstart Sample](../../quickstarts/voice-video-calling/call-recording-sample.md) to learn about retrieving the `serverCallId` from the Calling Client SDK. A `recordingOperationId` is returned when recording is started, which is then used for follow-on operations like pause and resume.

- "topic": string, // Azure Communication Services resource id

- "subject": string, // /recording/call/{call-id}

- docker push $ACR_NAME.azurecr.io/albumapp-ui

- docker push $ACR_NAME.azurecr.io/albumapp-ui

-When you deploy an internal or an external environment into your own network, a new resource group prefixed with `MC_` is created in the Azure subscription where your environment is hosted. This resource group contains infrastructure components managed by the Azure Container Apps platform, and shouldn't be modified. The resource group contains Public IP addresses used specifically for outbound connectivity from your environment and a load balancer. In addition to the [Azure Container Apps billing](./billing.md), you will be billed for the following:

-No. Materialized Views can't be created on a table that existed before the account was onboarded to support materialized views. Create new table after account is onboarded on which materialized views can be defined. MV on existing table is planned for the future.

-* Hierarchical partition keys can currently only be enabled on new containers. The desired partition key paths must be specified at the time of container creation and can't be changed later.

-* Move data from one Azure Cosmos DB container to another container in the same database or a different databases.

-* Moving data between dedicated containers to shared database containers.

-* Move data from an Azure Cosmos DB account located in region1 to another Azure Cosmos DB account in the same or a different region.

-## Azure Cosmos DB's API for MongoDB updates

-You can now use the free and lightweight tool feature to manage and query your MongoDB resources using mongo shell. Azure Data Studio MongoDB extension for Azure Cosmos DB allows you to manage multiple accounts all in one view by

-1. Connecting your Mongo resources

-2. Configuring the database settings

-3. Performing create, read, update, and delete (CRUD) across Windows, macOS, and Linux.

-### Linux emulator with Azure Cosmos DB for MongoDB

-The Azure Cosmos DB Linux emulator with API for MongoDB support provides a local environment that emulates the Azure Cosmos DB service for development purposes on Linux and macOS. Using the emulator, you can develop and test your MongoDB applications locally, without creating an Azure subscription or incurring any costs.

-### 16-MB limit per document in API for MongoDB (Preview)

-The 16-MB document limit in the Azure Cosmos DB for MongoDB provides developers the flexibility to store more data per document. This ease-of-use feature will speed up your development process in these cases.

-The API for MongoDB now offers a built-in role-based access control (RBAC) that allows you to authorize your data requests with a fine-grained, role-based permission model. Using this role-based access control (RBAC) allows you access with more options for control, security, and auditability of your database account data.

-`$expr` allows the use of [aggregation expressions](https://www.mongodb.com/docs/manual/meta/aggregation-quick-reference/#std-label-aggregation-expressions) within the query language.

-### Role-Based Access Control for $merge stage

-* Added Role-Based Access Control(RBAC) for `$merge` stage.

-* `$merge` writes the results of aggregation pipeline to specified collection. The `$merge` operator must be the last stage in the pipeline

- - If all you know is the number of vCores and servers in your existing database cluster, read about [estimating request units using vCores or vCPUs](../convert-vcore-to-request-unit.md).

- - If you know typical request rates for your current database workload, read about [estimating request units using Azure Cosmos DB capacity planner](estimate-ru-capacity-planner.md).

-description: Learn about Azure Cosmos DB's API for MongoDB (3.2 version) supported features and syntax.

-# Azure Cosmos DB's API for MongoDB (3.2 version): supported features and syntax

-Azure Cosmos DB is Microsoft's globally distributed multi-model database service. You can communicate with the Azure Cosmos DB's API for MongoDB using any of the open-source MongoDB client [drivers](https://docs.mongodb.org/ecosystem/drivers). The Azure Cosmos DB's API for MongoDB enables the use of existing client drivers by adhering to the MongoDB [wire protocol](https://docs.mongodb.org/manual/reference/mongodb-wire-protocol).

-By using the Azure Cosmos DB's API for MongoDB, you can enjoy the benefits of the MongoDB you're used to, with all of the enterprise capabilities that Azure Cosmos DB provides: [global distribution](../distribute-data-globally.md), [automatic sharding](../partitioning-overview.md), availability and latency guarantees, automatic indexing of every field, encryption at rest, backups, and much more.

-All new accounts for Azure Cosmos DB's API for MongoDB are compatible with MongoDB server version **3.6**. This article covers MongoDB version 3.2. The supported operators and any limitations or exceptions are listed below. Any client driver that understands these protocols should be able to connect to Azure Cosmos DB's API for MongoDB.

-Azure Cosmos DB's API for MongoDB also offers a seamless upgrade experience for qualifying accounts. Learn more on the [MongoDB version upgrade guide](upgrade-version.md).

-Azure Cosmos DB's API for MongoDB provides comprehensive support for MongoDB query language constructs. Below you can find the detailed list of currently supported operations, operators, stages, commands, and options.

-Azure Cosmos DB's API for MongoDB supports the following database commands:

-> This article only lists the supported server commands and excludes client-side wrapper functions. Client-side wrapper functions such as `deleteMany()` and `updateMany()` internally utilize the `delete()` and `update()` server commands. Functions utilizing supported server commands are compatible with Azure Cosmos DB's API for MongoDB.

-| $eq | `{ "Volcano Name": { $eq: "Rainier" } }` |

-| $gt | `{ "Elevation": { $gt: 4000 } }` |

-| $gte | `{ "Elevation": { $gte: 4392 } }` |

-| $lt | `{ "Elevation": { $lt: 5000 } }` |

-| $lte | `{ "Elevation": { $lte: 5000 } }` |

-| $ne | `{ "Elevation": { $ne: 1 } }` |

-| $in | `{ "Volcano Name": { $in: ["St. Helens", "Rainier", "Glacier Peak"] } }` |

-| $nin | `{ "Volcano Name": { $nin: ["Lassen Peak", "Hood", "Baker"] } }` |

-| $or | `{ $or: [ { Elevation: { $lt: 4000 } }, { "Volcano Name": "Rainier" } ] }` |

-| $and | `{ $and: [ { Elevation: { $gt: 4000 } }, { "Volcano Name": "Rainier" } ] }` |

-| $not | `{ "Elevation": { $not: { $gt: 5000 } } }`|

-| $nor | `{ $nor: [ { "Elevation": { $lt: 4000 } }, { "Volcano Name": "Baker" } ] }` |

-| $exists | `{ "Status": { $exists: true } }`|

-| $type | `{ "Status": { $type: "string" } }`|

-| $mod | `{ "Elevation": { $mod: [ 4, 0 ] } }` |

-| $regex | `{ "Volcano Name": { $regex: "^Rain"} }`|

-When there's a need to include '$' or '|', it is best to create two (or more) regex queries.

-For example, given the following original query: ```find({x:{$regex: /^abc$/})```, it has to be modified as follows:

-```find({x:{$regex: /^abc/, x:{$regex:/^abc$/}})```.

-The bar operator '|' acts as an "or" function - the query ```find({x:{$regex: /^abc|^def/})``` matches the documents in which field 'x' has values that begin with "abc" or "def". To utilize the index, it's recommended to break the query into two different queries joined by the $or operator: ```find( {$or : [{x: $regex: /^abc/}, {$regex: /^def/}] })```.

-Operator | Example | Supported |

- | | |

-$geoWithin | ```{ "Location.coordinates": { $geoWithin: { $centerSphere: [ [ -121, 46 ], 5 ] } } }``` | Yes |

-$geoIntersects | ```{ "Location.coordinates": { $geoIntersects: { $geometry: { type: "Polygon", coordinates: [ [ [ -121.9, 46.7 ], [ -121.5, 46.7 ], [ -121.5, 46.9 ], [ -121.9, 46.9 ], [ -121.9, 46.7 ] ] ] } } } }``` | Yes |

-$near | ```{ "Location.coordinates": { $near: { $geometry: { type: "Polygon", coordinates: [ [ [ -121.9, 46.7 ], [ -121.5, 46.7 ], [ -121.5, 46.9 ], [ -121.9, 46.9 ], [ -121.9, 46.7 ] ] ] } } } }``` | Yes |

-$nearSphere | ```{ "Location.coordinates": { $nearSphere : [ -121, 46 ], $maxDistance: 0.50 } }``` | Yes |

-$geometry | ```{ "Location.coordinates": { $geoWithin: { $geometry: { type: "Polygon", coordinates: [ [ [ -121.9, 46.7 ], [ -121.5, 46.7 ], [ -121.5, 46.9 ], [ -121.9, 46.9 ], [ -121.9, 46.7 ] ] ] } } } }``` | Yes |

-$minDistance | ```{ "Location.coordinates": { $nearSphere : { $geometry: {type: "Point", coordinates: [ -121, 46 ]}, $minDistance: 1000, $maxDistance: 1000000 } } }``` | Yes |

-$maxDistance | ```{ "Location.coordinates": { $nearSphere : [ -121, 46 ], $maxDistance: 0.50 } }``` | Yes |

-$center | ```{ "Location.coordinates": { $geoWithin: { $center: [ [-121, 46], 1 ] } } }``` | Yes |

-$centerSphere | ```{ "Location.coordinates": { $geoWithin: { $centerSphere: [ [ -121, 46 ], 5 ] } } }``` | Yes |

-$box | ```{ "Location.coordinates": { $geoWithin: { $box: [ [ 0, 0 ], [ -122, 47 ] ] } } }``` | Yes |

-$polygon | ```{ "Location.coordinates": { $near: { $geometry: { type: "Polygon", coordinates: [ [ [ -121.9, 46.7 ], [ -121.5, 46.7 ], [ -121.5, 46.9 ], [ -121.9, 46.9 ], [ -121.9, 46.7 ] ] ] } } } }``` | Yes |

-When using the `findOneAndUpdate` operation, sort operations on a single field are supported but sort operations on multiple fields are not supported.

-Operator | Example | Notes

- | | |

-$all | ```{ "Location.coordinates": { $all: [-121.758, 46.87] } }``` |

-$elemMatch | ```{ "Location.coordinates": { $elemMatch: { $lt: 0 } } }``` |

-$size | ```{ "Location.coordinates": { $size: 2 } }``` |

-$comment | ```{ "Location.coordinates": { $elemMatch: { $lt: 0 } }, $comment: "Negative values"}``` |

-$text | | Not supported. Use $regex instead.

-The ```$where``` and the ```$eval``` operators are not supported by Azure Cosmos DB.

-Method | Example | Notes

- | | |

-cursor.sort() | ```cursor.sort({ "Elevation": -1 })``` | Documents without sort key do not get returned

-Unique indexes are available for all Azure Cosmos DB accounts using Azure Cosmos DB's API for MongoDB.

-Azure Cosmos DB does not yet support users and roles. However, Azure Cosmos DB supports Azure role-based access control (Azure RBAC) and read-write and read-only passwords/keys that can be obtained through the [Azure portal](https://portal.azure.com) (Connection String page).

-Azure Cosmos DB supports automatic, native replication at the lowest layers. This logic is extended out to achieve low-latency, global replication as well. Azure Cosmos DB does not support manual replication commands.

-Some applications rely on a [Write Concern](https://docs.mongodb.com/manual/reference/write-concern/) that specifies the number of responses required during a write operation. Due to how Azure Cosmos DB handles replication in the background all writes are all automatically Quorum by default. Any write concern specified by the client code is ignored. Learn more in [Using consistency levels to maximize availability and performance](../consistency-levels.md).

-Azure Cosmos DB supports automatic, server-side sharding. It manages shard creation, placement, and balancing automatically. Azure Cosmos DB does not support manual sharding commands, which means you don't have to invoke commands such as shardCollection, addShard, balancerStart, moveChunk etc. You only need to specify the shard key while creating the containers or querying the data.

-description: Learn about Azure Cosmos DB's API for MongoDB (3.6 version) supported features and syntax.

-# Azure Cosmos DB's API for MongoDB (3.6 version): supported features and syntax

-Azure Cosmos DB is Microsoft's globally distributed multi-model database service. You can communicate with the Azure Cosmos DB's API for MongoDB using any of the open-source MongoDB client [drivers](https://docs.mongodb.org/ecosystem/drivers). The Azure Cosmos DB's API for MongoDB enables the use of existing client drivers by adhering to the MongoDB [wire protocol](https://docs.mongodb.org/manual/reference/mongodb-wire-protocol).

-By using the Azure Cosmos DB's API for MongoDB, you can enjoy the benefits of the MongoDB you're used to, with all of the enterprise capabilities that Azure Cosmos DB provides: [global distribution](../distribute-data-globally.md), [automatic sharding](../partitioning-overview.md), availability and latency guarantees, encryption at rest, backups, and much more.

-The Azure Cosmos DB's API for MongoDB is compatible with MongoDB server version **3.6** by default for new accounts. The supported operators and any limitations or exceptions are listed below. Any client driver that understands these protocols should be able to connect to Azure Cosmos DB's API for MongoDB. Note that when using Azure Cosmos DB's API for MongoDB accounts, the 3.6 version of account has the endpoint in the format `*.mongo.cosmos.azure.com` whereas the 3.2 version of account has the endpoint in the format `*.documents.azure.com`.

-Azure Cosmos DB's API for MongoDB provides comprehensive support for MongoDB query language constructs. The following sections show the detailed list of server operations, operators, stages, commands, and options currently supported by Azure Cosmos DB.

-> This article only lists the supported server commands and excludes client-side wrapper functions. Client-side wrapper functions such as `deleteMany()` and `updateMany()` internally utilize the `delete()` and `update()` server commands. Functions utilizing supported server commands are compatible with Azure Cosmos DB's API for MongoDB.

-Azure Cosmos DB's API for MongoDB supports the following database commands:

-| [change streams](change-streams.md) | Yes |

-| delete | Yes |

-| eval | No |

-| find | Yes |

-| findAndModify | Yes |

-| getLastError | Yes |

-| getMore | Yes |

-| getPrevError | No |

-| insert | Yes |

-| parallelCollectionScan | No |

-| resetError | No |

-| update | Yes |

-| authenticate | Yes |

-| getnonce | Yes |

-| logout | Yes |

-| cloneCollectionAsCapped | No |

-| collMod | No |

-| connectionStatus | No |

-| convertToCapped | No |

-| copydb | No |

-| create | Yes |

-| createIndexes | Yes |

-| currentOp | Yes |

-| drop | Yes |

-| dropDatabase | Yes |

-| dropIndexes | Yes |

-| filemd5 | Yes |

-| killCursors | Yes |

-| killOp | No |

-| listCollections | Yes |

-| listDatabases | Yes |

-| listIndexes | Yes |

-| reIndex | Yes |

-| renameCollection | No |

-| buildInfo | Yes |

-| collStats | Yes |

-| connPoolStats | No |

-| connectionStatus | No |

-| dataSize | No |

-| dbHash | No |

-| dbStats | Yes |

-| explain | Yes |

-| features | No |

-| hostInfo | Yes |

-| listDatabases | Yes |

-| listCommands | No |

-| profiler | No |

-| serverStatus | No |

-| top | No |

-| whatsmyuri | Yes |

-| aggregate | Yes |

-| count | Yes |

-| distinct | Yes |

-| mapReduce | No |

-| $addFields | Yes |

-| $bucket | No |

-| $bucketAuto | No |

-| $changeStream | Yes |

-| $collStats | No |

-| $count | Yes |

-| $currentOp | No |

-| $facet | Yes |

-| $geoNear | Yes |

-| $graphLookup | Yes |

-| $group | Yes |

-| $indexStats | No |

-| $limit | Yes |

-| $listLocalSessions | No |

-| $listSessions | No |

-| $lookup | Partial |

-| $match | Yes |

-| $out | Yes |

-| $project | Yes |

-| $redact | Yes |

-| $replaceRoot | Yes |

-| $replaceWith | No |

-| $sample | Yes |

-| $skip | Yes |

-| $sort | Yes |

-| $sortByCount | Yes |

-| $unwind | Yes |

-| $and | Yes |

-| $not | Yes |

-| $or | Yes |

-| $setEquals | Yes |

-| $setIntersection | Yes |

-| $setUnion | Yes |

-| $setDifference | Yes |

-| $setIsSubset | Yes |

-| $anyElementTrue | Yes |

-| $allElementsTrue | Yes |

-| $cmp | Yes |

-| $eq | Yes |

-| $gt | Yes |

-| $gte | Yes |

-| $lt | Yes |

-| $lte | Yes |

-| $ne | Yes |

-| $in | Yes |

-| $nin | Yes |

-| $abs | Yes |

-| $add | Yes |

-| $ceil | Yes |

-| $divide | Yes |

-| $exp | Yes |

-| $floor | Yes |

-| $ln | Yes |

-| $log | Yes |

-| $log10 | Yes |

-| $mod | Yes |

-| $multiply | Yes |

-| $pow | Yes |

-| $sqrt | Yes |

-| $subtract | Yes |

-| $trunc | Yes |

-| $concat | Yes |

-| $indexOfBytes | Yes |

-| $indexOfCP | Yes |

-| $split | Yes |

-| $strLenBytes | Yes |

-| $strLenCP | Yes |

-| $strcasecmp | Yes |

-| $substr | Yes |

-| $substrBytes | Yes |

-| $substrCP | Yes |

-| $toLower | Yes |

-| $toUpper | Yes |

-| $meta | No |

-| $arrayElemAt | Yes |

-| $arrayToObject | Yes |

-| $concatArrays | Yes |

-| $filter | Yes |

-| $indexOfArray | Yes |

-| $isArray | Yes |

-| $objectToArray | Yes |

-| $range | Yes |

-| $reverseArray | Yes |

-| $reduce | Yes |

-| $size | Yes |

-| $slice | Yes |

-| $zip | Yes |

-| $in | Yes |

-| $map | Yes |

-| $let | Yes |

-| $$CURRENT | Yes |

-| $$DESCEND | Yes |

-| $$KEEP | Yes |

-| $$PRUNE | Yes |

-| $$REMOVE | Yes |

-| $$ROOT | Yes |

-| $literal | Yes |

-| $dayOfYear | Yes |

-| $dayOfMonth | Yes |

-| $dayOfWeek | Yes |

-| $year | Yes |

-| $month | Yes |

-| $week | Yes |

-| $hour | Yes |

-| $minute | Yes |

-| $second | Yes |

-| $millisecond | Yes |

-| $dateToString | Yes |

-| $isoDayOfWeek | Yes |

-| $isoWeek | Yes |

-| $dateFromParts | Yes |

-| $dateToParts | Yes |

-| $dateFromString | Yes |

-| $isoWeekYear | Yes |

-| $cond | Yes |

-| $ifNull | Yes |

-| $switch | Yes |

-| $type | Yes |

-| $sum | Yes |

-| $avg | Yes |

-| $first | Yes |

-| $last | Yes |

-| $max | Yes |

-| $min | Yes |

-| $push | Yes |

-| $addToSet | Yes |

-| $stdDevPop | Yes |

-| $stdDevSamp | Yes |

-| $mergeObjects | Yes |

-| Double | Yes |

-| String | Yes |

-| Object | Yes |

-| Array | Yes |

-| Binary Data | Yes |

-| ObjectId | Yes |

-| Boolean | Yes |

-| Date | Yes |

-| Null | Yes |

-| 32-bit Integer (int) | Yes |

-| Timestamp | Yes |

-| 64-bit Integer (long) | Yes |

-| MinKey | Yes |

-| MaxKey | Yes |

-| Decimal128 | Yes |

-| Regular Expression | Yes |

-| JavaScript | Yes |

-| JavaScript (with scope)| Yes |

-| Undefined | Yes |

-| Single Field Index | Yes |

-| Compound Index | Yes |

-| Multikey Index | Yes |

-| Text Index | No |

-| 2dsphere | Yes |

-| 2d Index | No |

-| Hashed Index | Yes |

-| TTL | Yes |

-| Unique | Yes |

-| Partial | No |

-| Case Insensitive | No |

-| Sparse | No |

-| Background | Yes |

-| $or | Yes |

-| $and | Yes |

-| $not | Yes |

-| $nor | Yes |

-| $exists | Yes |

-| $type | Yes |

-| $expr | Yes |

-| $jsonSchema | No |

-| $mod | Yes |

-| $regex | Yes |

-| $text | No (Not supported. Use $regex instead.)|

-| $where | No |

-When there's a need to include '$' or '|', it is best to create two (or more) regex queries. For example, given the following original query: ```find({x:{$regex: /^abc$/})```, it has to be modified as follows:

-The first part will use the index to restrict the search to those documents beginning with ^abc and the second part will match the exact entries. The bar operator '|' acts as an "or" function - the query ```find({x:{$regex: /^abc |^def/})``` matches the documents in which field 'x' has values that begin with "abc" or "def". To utilize the index, it's recommended to break the query into two different queries joined by the $or operator: ```find( {$or : [{x: $regex: /^abc/}, {$regex: /^def/}] })```.

-| Command | Supported |

-| $all | Yes |

-| $elemMatch | Yes |

-| $size | Yes |

-| Command | Supported |

-| $comment | Yes |

-| $elemMatch | Yes |

-| $meta | No |

-| $slice | Yes |

-| $inc | Yes |

-| $mul | Yes |

-| $rename | Yes |

-| $setOnInsert | Yes |

-| $set | Yes |

-| $unset | Yes |

-| $min | Yes |

-| $max | Yes |

-| $currentDate | Yes |

-| $ | Yes |

-| $[]| Yes |

-| $[\<identifier\>]| Yes |

-| $addToSet | Yes |

-| $pop | Yes |

-| $pullAll | Yes |

-| $pull | Yes |

-| $push | Yes |

-| $pushAll | Yes |

-| $each | Yes |

-| $slice | Yes |

-| $sort | Yes |

-| $position | Yes |

-| $bit | Yes |

-| $bitsAllSet | No |

-| $bitsAnySet | No |

-| $bitsAllClear | No |

-| $bitsAnyClear | No |

-Operator | Supported |

- | |

-$geoWithin | Yes |

-$geoIntersects | Yes |

-$near | Yes |

-$nearSphere | Yes |

-$geometry | Yes |

-$minDistance | Yes |

-$maxDistance | Yes |

-$center | No |

-$centerSphere | No |

-$box | No |

-$polygon | No |

-When using the `findOneAndUpdate` operation, sort operations on a single field are supported but sort operations on multiple fields are not supported.

-The API for MongoDB [supports a variety of indexes](indexing.md) to enable sorting on multiple fields, improve query performance, and enforce uniqueness.

-Azure Cosmos DB supports automatic, native replication at the lowest layers. This logic is extended out to achieve low-latency, global replication as well. Azure Cosmos DB does not support manual replication commands.

-Azure Cosmos DB does not yet support retryable writes. Client drivers must add `retryWrites=false` to their connection string.

-Azure Cosmos DB supports automatic, server-side sharding. It manages shard creation, placement, and balancing automatically. Azure Cosmos DB does not support manual sharding commands, which means you don't have to invoke commands such as addShard, balancerStart, moveChunk etc. You only need to specify the shard key while creating the containers or querying the data.

-Azure Cosmos DB does not yet support server-side sessions commands.

-Azure Cosmos DB does not yet support users and roles. However, it supports Azure role-based access control (Azure RBAC) and read-write and read-only passwords or keys that can be obtained through the connection string pane in the [Azure portal](https://portal.azure.com).

-Some applications rely on a [Write Concern](https://docs.mongodb.com/manual/reference/write-concern/) which specifies the number of responses required during a write operation. Due to how Azure Cosmos DB handles replication, all writes are automatically majority quorum by default when using strong consistency. Any write concern specified by the client code is ignored. To learn more, see [Using consistency levels to maximize availability and performance](../consistency-levels.md) article.

-description: Learn about Azure Cosmos DB's API for MongoDB 4.0 server version supported features and syntax. Learn about the database commands, query language support, datatypes, aggregation pipeline commands, and operators supported.

-# Azure Cosmos DB's API for MongoDB (4.0 server version): supported features and syntax

-Azure Cosmos DB is Microsoft's globally distributed multi-model database service. You can communicate with the Azure Cosmos DB's API for MongoDB using any of the open-source MongoDB client [drivers](https://docs.mongodb.org/ecosystem/drivers). The Azure Cosmos DB's API for MongoDB enables the use of existing client drivers by adhering to the MongoDB [wire protocol](https://docs.mongodb.org/manual/reference/mongodb-wire-protocol).

-By using the Azure Cosmos DB's API for MongoDB, you can enjoy the benefits of the MongoDB you're used to, with all of the enterprise capabilities that Azure Cosmos DB provides: [global distribution](../distribute-data-globally.md), [automatic sharding](../partitioning-overview.md), availability and latency guarantees, encryption at rest, backups, and much more.

-The supported operators and any limitations or exceptions are listed below. Any client driver that understands these protocols should be able to connect to Azure Cosmos DB's API for MongoDB. When using Azure Cosmos DB's API for MongoDB accounts, the 3.6+ versions of accounts have the endpoint in the format `*.mongo.cosmos.azure.com` whereas the 3.2 version of accounts has the endpoint in the format `*.documents.azure.com`.

-> This article only lists the supported server commands and excludes client-side wrapper functions. Client-side wrapper functions such as `deleteMany()` and `updateMany()` internally utilize the `delete()` and `update()` server commands. Functions utilizing supported server commands are compatible with Azure Cosmos DB's API for MongoDB.

-Azure Cosmos DB's API for MongoDB provides comprehensive support for MongoDB query language constructs. Below you can find the detailed list of currently supported operations, operators, stages, commands, and options.

-Azure Cosmos DB's API for MongoDB supports the following database commands:

-| [change streams](change-streams.md) | Yes |

-| delete | Yes |

-| eval | No |

-| find | Yes |

-| findAndModify | Yes |

-| getLastError | Yes |

-| getMore | Yes |

-| getPrevError | No |

-| insert | Yes |

-| parallelCollectionScan | No |

-| resetError | No |

-| update | Yes |

-| abortTransaction | Yes |

-| commitTransaction | Yes |

-| authenticate | Yes |

-| getnonce | Yes |

-| logout | Yes |

-| cloneCollectionAsCapped | No |

-| collMod | No |

-| connectionStatus | No |

-| convertToCapped | No |

-| copydb | No |

-| create | Yes |

-| createIndexes | Yes |

-| currentOp | Yes |

-| drop | Yes |

-| dropDatabase | Yes |

-| dropIndexes | Yes |

-| filemd5 | Yes |

-| killCursors | Yes |

-| killOp | No |

-| listCollections | Yes |

-| listDatabases | Yes |

-| listIndexes | Yes |

-| reIndex | Yes |

-| renameCollection | No |

-| buildInfo | Yes |

-| collStats | Yes |

-| connPoolStats | No |

-| connectionStatus | No |

-| dataSize | No |

-| dbHash | No |

-| dbStats | Yes |

-| explain | Yes |

-| features | No |

-| hostInfo | Yes |

-| listDatabases | Yes |

-| listCommands | No |

-| profiler | No |

-| serverStatus | No |

-| top | No |

-| whatsmyuri | Yes |

-| aggregate | Yes |

-| count | Yes |

-| distinct | Yes |

-| mapReduce | No |

-| $addFields | Yes |

-| $bucket | No |

-| $bucketAuto | No |

-| $changeStream | Yes |

-| $collStats | No |

-| $count | Yes |

-| $currentOp | No |

-| $facet | Yes |

-| $geoNear | Yes |

-| $graphLookup | Yes |

-| $group | Yes |

-| $indexStats | No |

-| $limit | Yes |

-| $listLocalSessions | No |

-| $listSessions | No |

-| $lookup | Partial |

-| $match | Yes |

-| $out | Yes |

-| $project | Yes |

-| $redact | Yes |

-| $replaceRoot | Yes |

-| $replaceWith | No |

-| $sample | Yes |

-| $skip | Yes |

-| $sort | Yes |

-| $sortByCount | Yes |

-| $unwind | Yes |

-| $and | Yes |

-| $not | Yes |

-| $or | Yes |

-| $convert | Yes |

-| $toBool | Yes |

-| $toDate | Yes |

-| $toDecimal | Yes |

-| $toDouble | Yes |

-| $toInt | Yes |

-| $toLong | Yes |

-| $toObjectId | Yes |

-| $toString | Yes |

-| $setEquals | Yes |

-| $setIntersection | Yes |

-| $setUnion | Yes |

-| $setDifference | Yes |

-| $setIsSubset | Yes |

-| $anyElementTrue | Yes |

-| $allElementsTrue | Yes |

-| $cmp | Yes |

-| $eq | Yes |

-| $gt | Yes |

-| $gte | Yes |

-| $lt | Yes |

-| $lte | Yes |

-| $ne | Yes |

-| $in | Yes |

-| $nin | Yes |

-| $abs | Yes |

-| $add | Yes |

-| $ceil | Yes |

-| $divide | Yes |

-| $exp | Yes |

-| $floor | Yes |

-| $ln | Yes |

-| $log | Yes |

-| $log10 | Yes |

-| $mod | Yes |

-| $multiply | Yes |

-| $pow | Yes |

-| $sqrt | Yes |

-| $subtract | Yes |

-| $trunc | Yes |

-| $concat | Yes |

-| $indexOfBytes | Yes |

-| $indexOfCP | Yes |

-| $ltrim | Yes |

-| $rtrim | Yes |

-| $trim | Yes |

-| $split | Yes |

-| $strLenBytes | Yes |

-| $strLenCP | Yes |

-| $strcasecmp | Yes |

-| $substr | Yes |

-| $substrBytes | Yes |

-| $substrCP | Yes |

-| $toLower | Yes |

-| $toUpper | Yes |

-| $meta | No |

-| $arrayElemAt | Yes |

-| $arrayToObject | Yes |

-| $concatArrays | Yes |

-| $filter | Yes |

-| $indexOfArray | Yes |

-| $isArray | Yes |

-| $objectToArray | Yes |

-| $range | Yes |

-| $reverseArray | Yes |

-| $reduce | Yes |

-| $size | Yes |

-| $slice | Yes |

-| $zip | Yes |

-| $in | Yes |

-| $map | Yes |

-| $let | Yes |

-| $$CURRENT | Yes |

-| $$DESCEND | Yes |

-| $$KEEP | Yes |

-| $$PRUNE | Yes |

-| $$REMOVE | Yes |

-| $$ROOT | Yes |

-| $literal | Yes |

-| $dayOfYear | Yes |

-| $dayOfMonth | Yes |

-| $dayOfWeek | Yes |

-| $year | Yes |

-| $month | Yes |

-| $week | Yes |

-| $hour | Yes |

-| $minute | Yes |

-| $second | Yes |

-| $millisecond | Yes |

-| $dateToString | Yes |

-| $isoDayOfWeek | Yes |

-| $isoWeek | Yes |

-| $dateFromParts | Yes |

-| $dateToParts | Yes |

-| $dateFromString | Yes |

-| $isoWeekYear | Yes |

-| $cond | Yes |

-| $ifNull | Yes |

-| $switch | Yes |

-| $type | Yes |

-| $sum | Yes |

-| $avg | Yes |

-| $first | Yes |

-| $last | Yes |

-| $max | Yes |

-| $min | Yes |

-| $push | Yes |

-| $addToSet | Yes |

-| $stdDevPop | Yes |

-| $stdDevSamp | Yes |

-| $mergeObjects | Yes |

-Azure Cosmos DB for MongoDB supports documents encoded in MongoDB BSON format. The 4.0 API version enhances the internal usage of this format to improve performance and reduce costs. Documents written or updated through an endpoint running 4.0+ benefit from this.

-

-In an [upgrade scenario](upgrade-version.md), documents written prior to the upgrade to version 4.0+ will not benefit from the enhanced performance until they are updated via a write operation through the 4.0+ endpoint.

-16MB document support raises the size limit for your documents from 2MB to 16MB. This limit only applies to collections created after this feature has been enabled. Once this feature is enabled for your database account, it cannot be disabled. This feature is not compatible with the Azure Synapse Link feature and/or Continuous Backup.

-Enabling 16MB can be done in the features tab in the Azure portal or programmatically by [adding the "EnableMongo16MBDocumentSupport" capability](how-to-configure-capabilities.md).

-We recommend enabling Server Side Retry to ensure requests with larger documents succeed. If necessary, raising your DB/Collection RUs may also help performance.

-| Double | Yes |

-| String | Yes |

-| Object | Yes |

-| Array | Yes |

-| Binary Data | Yes |

-| ObjectId | Yes |

-| Boolean | Yes |

-| Date | Yes |

-| Null | Yes |

-| 32-bit Integer (int) | Yes |

-| Timestamp | Yes |

-| 64-bit Integer (long) | Yes |

-| MinKey | Yes |

-| MaxKey | Yes |

-| Decimal128 | Yes |

-| Regular Expression | Yes |

-| JavaScript | Yes |

-| JavaScript (with scope)| Yes |

-| Undefined | Yes |

-| Single Field Index | Yes |

-| Compound Index | Yes |

-| Multikey Index | Yes |

-| Text Index | No |

-| 2dsphere | Yes |

-| 2d Index | No |

-| Hashed Index | Yes |

-| TTL | Yes |

-| Unique | Yes |

-| Partial | No |

-| Case Insensitive | No |

-| Sparse | No |

-| Background | Yes |

-| $or | Yes |

-| $and | Yes |

-| $not | Yes |

-| $nor | Yes |

-| $exists | Yes |

-| $type | Yes |

-| $expr | Yes |

-| $jsonSchema | No |

-| $mod | Yes |

-| $regex | Yes |

-| $text | No (Not supported. Use $regex instead.)|

-| $where | No |

-When there's a need to include '$' or '|', it is best to create two (or more) regex queries. For example, given the following original query: `find({x:{$regex: /^abc$/})`, it has to be modified as follows:

-| Command | Supported |

-| $all | Yes |

-| $elemMatch | Yes |

-| $size | Yes |

-| Command | Supported |

-| $comment | Yes |

-| $elemMatch | Yes |

-| $meta | No |

-| $slice | Yes |

-| $inc | Yes |

-| $mul | Yes |

-| $rename | Yes |

-| $setOnInsert | Yes |

-| $set | Yes |

-| $unset | Yes |

-| $min | Yes |

-| $max | Yes |

-| $currentDate | Yes |

-| $ | Yes |

-| $[]| Yes |

-| $[\<identifier\>]| Yes |

-| $addToSet | Yes |

-| $pop | Yes |

-| $pullAll | Yes |

-| $pull | Yes |

-| $push | Yes |

-| $pushAll | Yes |

-| $each | Yes |

-| $slice | Yes |

-| $sort | Yes |

-| $position | Yes |

-| $bit | Yes |

-| $bitsAllSet | No |

-| $bitsAnySet | No |

-| $bitsAllClear | No |

-| $bitsAnyClear | No |

-Operator | Supported |

- | |

-$geoWithin | Yes |

-$geoIntersects | Yes |

-$near | Yes |

-$nearSphere | Yes |

-$geometry | Yes |

-$minDistance | Yes |

-$maxDistance | Yes |

-$center | No |

-$centerSphere | No |

-$box | No |

-$polygon | No |

-When using the `findOneAndUpdate` operation with API for MongoDB version 4.0, sort operations on a single field and multiple fields are supported. Sort operations on multiple fields was a limitation of previous wire protocols.

-The API for MongoDB [supports a variety of indexes](indexing.md) to enable sorting on multiple fields, improve query performance, and enforce uniqueness.

-Azure Cosmos DB supports automatic, native replication at the lowest layers. This logic is extended out to achieve low-latency, global replication as well. Azure Cosmos DB does not support manual replication commands.

-Retryable writes enables MongoDB drivers to automatically retry certain write operations in case of failure, but results in more stringent requirements for certain operations, which match MongoDB protocol requirements. With this feature enabled, update operations, including deletes, in sharded collections will require the shard key to be included in the query filter or update statement.

-For example, with a sharded collection, sharded on key ΓÇ£countryΓÇ¥: To delete all the documents with the field city = "NYC", the application will need to execute the operation for all shard key (country) values if Retryable writes is enabled.

-To enable the feature, [add the EnableMongoRetryableWrites capability](how-to-configure-capabilities.md) to your database account. This feature can also be enabled in the features tab in the Azure portal.

-Azure Cosmos DB supports automatic, server-side sharding. It manages shard creation, placement, and balancing automatically. Azure Cosmos DB does not support manual sharding commands, which means you don't have to invoke commands such as addShard, balancerStart, moveChunk etc. You only need to specify the shard key while creating the containers or querying the data.

-Azure Cosmos DB does not yet support server-side sessions commands.

-Multi-document transactions are supported within an unsharded collection. Multi-document transactions are not supported across collections or in sharded collections. The timeout for transactions is a fixed 5 seconds.

-Azure Cosmos DB does not yet support users and roles. However, Azure Cosmos DB supports Azure role-based access control (Azure RBAC) and read-write and read-only passwords/keys that can be obtained through the [Azure portal](https://portal.azure.com) (Connection String page).

-Some applications rely on a [Write Concern](https://docs.mongodb.com/manual/reference/write-concern/), which specifies the number of responses required during a write operation. Due to how Azure Cosmos DB handles replication in the background all writes are all automatically Quorum by default. Any write concern specified by the client code is ignored. Learn more in [Using consistency levels to maximize availability and performance](../consistency-levels.md).

- - If all you know is the number of vCores and servers in your existing database cluster, read about [estimating request units using vCores or vCPUs](../convert-vcore-to-request-unit.md)

- - If you know typical request rates for your current database workload, read about [estimating request units using Azure Cosmos DB capacity planner](estimate-ru-capacity-planner.md)

-The supported operators and any limitations or exceptions are listed below. Any client driver that understands these protocols should be able to connect to Azure Cosmos DB for MongoDB. When using Azure Cosmos DB for MongoDB accounts, the 3.6+ versions of accounts have the endpoint in the format `*.mongo.cosmos.azure.com` whereas the 3.2 version of accounts has the endpoint in the format `*.documents.azure.com`.