+# Customer intent: As a developer who is building a web app, I want to learn more about the OAuth 2.0 authorization code flow in Azure AD B2C, so that I can add sign-up, sign-in, and other identity management tasks to my app.

+You can use the OAuth 2.0 authorization code grant in apps installed on a device to gain access to protected resources, such as web APIs. By using the Azure Active Directory B2C (Azure AD B2C) implementation of OAuth 2.0, you can add sign-up, sign-in, and other identity management tasks to your single-page, mobile, and desktop apps. In this article, we describe how to send and receive HTTP messages without using any open-source libraries. This article is language-independent. When possible, we recommend you use the supported Microsoft Authentication Libraries (MSAL). Take a look at the [sample apps that use MSAL](integrate-with-app-code-samples.md).

+The authorization code flow begins with the client directing the user to the `/authorize` endpoint. This is the interactive part of the flow, where the user takes action. In this request, the client indicates in the `scope` parameter the permissions that it needs to acquire from the user. The following examples (with line breaks for readability) show how to acquire an authorization code. If you're testing this GET HTTP request, use your browser.

+| scope |Required |A space-separated list of scopes. The `openid` scope indicates a permission to sign in the user and get data about the user in the form of ID tokens. The `offline_access` scope is optional for web applications. It indicates that your application will need a *refresh token* for extended access to resources. The client-id indicates the token issued are intended for use by Azure AD B2C registered client. The `https://{tenant-name}/{app-id-uri}/{scope}` indicates a permission to protected resources, such as a web API. For more information, see [Request an access token](access-tokens.md#scopes). |

+| scope |Recommended |A space-separated list of scopes. A single scope value indicates to Azure AD B2C both of the permissions that are being requested. Using the client ID as the scope indicates that your app needs an access token that can be used against your own service or web API, represented by the same client ID. The `offline_access` scope indicates that your app needs a refresh token for long-lived access to resources. You also can use the `openid` scope to request an ID token from Azure AD B2C. |

+#Customer intent: As a developer, I want to use my own domain name for the sign-in and sign-up experience, so that my users have a seamless experience.

+This article describes how to enable custom domains in your redirect URLs for Azure Active Directory B2C (Azure AD B2C). Using a verified custom domain has a number of benefits such as:

+- By staying in the same domain for your application during sign-in, you mitigate the impact of [third-party cookie blocking](/entra/identity-platform/reference-third-party-cookies-spas).

+ :::image type="content" source="./media/custom-domain/custom-domain-user-experience.png" alt-text="Screenshot of a browser window with the domain name highlighted in the address bar to show the custom domain experience.":::

+- You can set up multiple custom domains. For the maximum number of supported custom domains, see [Microsoft Entra service limits and restrictions](/entra/identity/users/directory-service-limits-restrictions) for Azure AD B2C and [Azure subscription and service limits, quotas, and constraints](/azure/azure-resource-manager/management/azure-subscription-service-limits#azure-front-door-classic-limits) for Azure Front Door.

+When you create an Azure AD B2C tenant it comes with an initial domain name, <domainname>.onmicrosoft.com. You can't change or delete the initial domain name, but you can add your own custom domain.

+1. [Add your custom domain name to Microsoft Entra ID](/entra/fundamentals/add-custom-domain#add-your-custom-domain-name).

+1. [Add your DNS information to the domain registrar](/entra/fundamentals/add-custom-domain#add-your-dns-information-to-the-domain-registrar). After you add your custom domain name to Microsoft Entra ID, create a DNS `TXT`, or `MX` record for your domain. Creating this DNS record for your domain verifies ownership of your domain name.

+1. [Verify your custom domain name](/entra/fundamentals/add-custom-domain#verify-your-custom-domain-name). Verify each subdomain, or hostname you plan to use. For example, to be able to sign in with *login.contoso.com* and *account.contoso.com*, you need to verify both subdomains and not just the top-level domain *contoso.com*.

+ |Tier| Select either Standard or Premium tier. Standard tier is content delivery optimized. Premium tier builds on Standard tier and is focused on security. See [Tier Comparison](../frontdoor/front-door-cdn-comparison.md).|

+ |Origin host name| Enter `<tenant-name>.b2clogin.com`. Replace `<tenant-name>` with the [name of your Azure AD B2C tenant](tenant-management-read-tenant-name.md#get-your-tenant-name) such as `contoso.b2clogin.com`.|

+1. Once the Azure Front Door resource is created, select **Overview**, and copy the **Endpoint hostname**. You will need this later on. It will look something like `b2cazurefrontdoor-ab123e.z01.azurefd.net`.

+ :::image type="content" source="./media/custom-domain/azure-front-door-custom-domain-origins.png" alt-text="Screenshot of the Origin groups menu from the Azure portal with Host name and Origin host header text boxes highlighted.":::

+ :::image type="content" source="./media/custom-domain/enable-the-route.png" alt-text="Screenshot of the Front Door manager page from the Azure portal with the default route highlighted.":::

+If you are using a custom HTML template to [customize the Azure AD B2C user interface](customize-ui-with-html.md), you need to [Configure CORS](customize-ui-with-html.md?pivots=b2c-user-flow.md#3-configure-cors) with your custom domain.

+ :::image type="content" source="./media/custom-domain/user-flow-run-now.png" alt-text="Screenshot of the Run user flow page from the Azure portal with the copy button for the Run userflow endpoint text box highlighted.":::

+1. To simulate a sign in with your custom domain, open a web browser and use the URL you just copied. Replace the Azure AD B2C domain (_&lt;tenant-name&gt;_.b2clogin.com) with your custom domain.

+- **policy-name** with your policy name.

+to `https://account.contosobank.co.uk/<tenant ID GUID>/`

+If you choose to use tenant ID instead of tenant name, be sure to update the identity provider **OAuth redirect URIs** accordingly. When using your tenant ID instead of tenant name, a valid OAuth redirect URI would look like the following sample:

+```http

+https://login.contoso.com/11111111-1111-1111-1111-111111111111/oauth2/authresp

+```

+For more information, see [Configure your identity provider](#configure-your-identity-provider).

+After you add the custom domain and configure your application, users will still be able to access the &lt;tenant-name&gt;.b2clogin.com domain. If you want to prevent access, you can configure the policy to check the authorization request "host name" against an allowed list of domains. The host name is the domain name that appears in the URL. The host name is available through `{Context:HostName}` [claim resolvers](claim-resolver-overview.md). Then you can present a custom error message.

+ :::image type="content" source="./media/custom-domain/azure-front-door-route-status.png" alt-text="Screenshot of the Front Door manager page from the Azure portal with the default route, Status and Provisioning state items highlighted.":::

+### Identity provider returns an error

+## See also

+* Learn about [OAuth authorization requests](protocols-overview.md).

+* Learn about [OpenID Connect authorization requests](openid-connect.md).

+* Learn about [authorization code flow](authorization-code-flow.md).

+- How to [Create and read a user account by using Azure Active Directory B2C custom policy](custom-policies-series-store-user.md)

+ Title: Set up sign-in for multitenant Microsoft Entra ID using custom policies

+description: Add a multitenant Microsoft Entra identity provider using custom policies in Azure Active Directory B2C.

+#Customer intent: As a developer, I want to enable sign-in for users using the multitenant endpoint for Microsoft Entra ID. Allowing users from multiple Microsoft Entra tenants to sign in using Azure AD B2C, without me having to configure an identity provider for each tenant.

+# Set up sign-in for multitenant Microsoft Entra ID using custom policies in Azure Active Directory B2C

+This article shows you how to enable sign-in for users using the multitenant endpoint for Microsoft Entra ID, allowing users from multiple Microsoft Entra tenants to sign in using Azure AD B2C, without you having to configure an identity provider for each tenant. However, guest members in any of these tenants **will not** be able to sign in. For that, you need to [individually configure each tenant](identity-provider-azure-ad-single-tenant.md).

+To enable users to sign in to Azure AD B2C with a Microsoft Entra account, you first need to create an application in the Microsoft Entra tenant from the [Azure portal](https://portal.azure.com). For more information, see [Register an application with the Microsoft identity platform](/entra/identity-platform/quickstart-register-app).

+1. If you have access to multiple tenants, select the **Settings** icon in the top menu to switch to your Microsoft Entra tenant from the **Directories + subscriptions** menu.

+> [!NOTE]

+> The client secret will not be shown again after this point. If you do not make a record of it, you will have to create a new one.

+### [Optional] Configuring optional claims

+[Publisher verification](/entra/identity-platform/publisher-verification-overview) helps your users understand the authenticity of the app you registered. A verified app means that the publisher of the app has [verified](/partner-center/verification-responses) their identity using their Microsoft Partner Network (MPN). Learn how to [mark your app as publisher verified](/entra/identity-platform/mark-app-as-publisher-verified).

+You now need to store the application key that you created in your Azure AD B2C tenant.

+1. Set **client_id** to the application ID of the Microsoft Entra multitenant application that you registered earlier.

+1. Under **CryptographicKeys**, update the value of **StorageReferenceId** to the name of the policy key that you created earlier. For example, `B2C_1A_AADAppSecret`.

+To test the multitenant sign-in capability, perform the last two steps using the credentials for a user that exists with another Microsoft Entra tenant. Copy the **Run now endpoint** and open it in a private browser window, for example, Incognito Mode in Google Chrome or an InPrivate window in Microsoft Edge. Opening in a private browser window allows you to test the full user journey by not using any currently cached Microsoft Entra credentials.

+## See also

+- Check out the Microsoft Entra multitenant federation [Live demo](https://github.com/azure-ad-b2c/unit-tests/tree/main/Identity-providers#azure-active-directory), and how to pass Microsoft Entra access token [Live demo](https://github.com/azure-ad-b2c/unit-tests/tree/main/Identity-providers#azure-active-directory-with-access-token)

+#Customer intent: As a developer, I want to manage resources in my Azure AD B2C tenant by calling the Microsoft Graph API and using an application identity to automate the process.

+### User migration

+Watch this video to learn how user migration to Azure AD B2C can be managed using Microsoft Graph API.

+>[!Video https://www.youtube.com/embed/9BRXBtkBzL4]

+Choose a mechanism for letting users register via local accounts. A Local account is one where Azure AD B2C completes the identity assertion. For more information, see [b2cAuthenticationMethodsPolicy resource type](/graph/api/resources/b2cauthenticationmethodspolicy).

+You can manage Microsoft Graph in two ways:

+* **Delegated permissions** either the user or an administrator consents to the permissions that the app requests. The app is delegated with the permission to act as a signed-in user when it makes calls to the target resource.

+* **Application permissions** are used by apps that do not require a signed in user present. Because of this, only administrators can consent to application permissions.

+## See also

+#Customer intent: As a developer, I want to learn how to enable multifactor authentication in consumer-facing applications secured by Azure Active Directory B2C.

+Azure Active Directory B2C (Azure AD B2C) integrates directly with [Microsoft Entra multifactor authentication](/entra/identity/authentication/concept-mfa-howitworks) so that you can add a second layer of security to sign-up and sign-in experiences in your applications. If you already created sign-up and sign-in user flows, you can still enable multifactor authentication.

+Using this feature applications can handle multiple scenarios such as:

+- Requiring multifactor authentication to access one application, but not requiring it to access another. For example, a customer can sign into an auto insurance application with a social or local account, but must verify the phone number before accessing the home insurance application registered in the same directory.

+- Requiring multifactor authentication to access an application in general, but not requiring it to access the sensitive portions within it. For example, a customer can sign in to a banking application with a social or local account and check the account balance, but must verify the phone number before attempting a wire transfer.

+- **Email** - During sign-in, a verification email containing a one-time password (OTP) is sent to the user. The user provides the OTP code that was sent in the email to the application.

+- **SMS or phone call** - During the first sign-up or sign-in, the user is asked to provide and verify a phone number. During subsequent sign-ins, the user is prompted to select either the **Send Code** or **Call Me** option. Depending on the user's choice, a text message is sent or a phone call is made to the verified phone number to identify the user. The user either provides the OTP code sent via text message or approves the phone call.

+When an Azure AD B2C application uses the TOTP option for MFA, end users need to use an authenticator app to generate TOTP codes. Users can use the [Microsoft Authenticator app](https://www.microsoft.com/security/mobile-authenticator-app) or any other authenticator app that supports TOTP verification. If using the Microsoft Authenticator app an Azure AD B2C system admin needs to advise end users to set up the Microsoft Authenticator app using the following steps:

+1. Open the Azure AD B2C application requiring you to use TOTP for MFA, for example *Contoso webapp*, and then sign in or sign up by entering the required information.

+1. If you're asked to enroll your account by scanning a QR code using an authenticator app, open the Microsoft Authenticator app in your phone, and in the upper right corner, select the **3-dotted** menu icon (for Android) or **+** menu icon (for iOS).

+1. Select **Other account (Google, Facebook, etc.)**, and then scan the QR code shown in the Azure AD B2C application to enroll your account. If you're unable to scan the QR code, you can add the account manually:

+ 1. In the Azure AD B2C application, select **Still having trouble?**. This displays **Account Name** and **Secret**.

+1. In the Azure AD B2C application, select **Continue**.

+Learn about [OATH software tokens](/entra/identity/authentication/concept-authentication-oath-tokens)

+In Azure AD B2C, you can delete a user's TOTP authenticator app enrollment. The user will then be forced to re-enroll their account to use TOTP authentication again. To delete a user's TOTP enrollment, you can use either the [Azure portal](https://portal.azure.com) or the [Microsoft Graph API](/graph/api/softwareoathauthenticationmethod-delete).

+> - Deleting a user's TOTP authenticator app enrollment from Azure AD B2C doesn't remove the user's account in the TOTP authenticator app on their device. The system admin needs to direct the user to manually delete their account from the TOTP authenticator app on their device before trying to enroll again.

+# Customer intent: As a technical or non-technical customer, I need to understand at a high level what Azure AD B2C is and how it can help me build a customer-facing application.

+Azure Active Directory B2C provides business-to-customer identity as a service. Your customers can use their preferred social, enterprise, or local account identities to get single sign-on access to your applications and APIs.

+Azure AD B2C is built on the same technology as [Microsoft Entra ID](../active-directory/fundamentals/whatis.md) but for a different purpose and is a separate service. It allows businesses to build customer facing applications, and then allow anyone to sign up and sign in to those applications with no restrictions on user account.

+Any business or individual who wishes to authenticate end users to their web or mobile applications using a white-label authentication solution. Apart from authentication, Azure AD B2C service is used for authorization such as access to API resources by authenticated users. Azure AD B2C is designed to be used by **IT administrators** and **developers**.

+Azure AD B2C is a white-label authentication solution which means you can customize the entire user experience with your brand so that it blends seamlessly with your web and mobile applications.

+Customize every page displayed by Azure AD B2C when your users sign up, sign in, and modify their profile information. Customize the HTML, CSS, and JavaScript in your user journeys so that the Azure AD B2C experience looks and feels like it's a native part of your application.

+Azure AD B2C can facilitate collecting information from a user during registration or profile editing, then hand that data off to an external system via API. Then, during future authentications, Azure AD B2C can retrieve that data from the external system and, if needed, include it as a part of the authentication token response it sends to your application.

+#Customer intent: As an IT admin or developer, I need to understand in more detail the technical aspects and features of Azure AD B2C and how it can help me build a customer-facing application.

+This article is a companion to [About Azure Active Directory B2C](overview.md) and provides a more in-depth introduction to the service. We will discuss here the primary resources you work with in the service, its features and learn how they enable you to provide a fully custom identity experience for customers in your applications.

+In Azure Active Directory B2C (Azure AD B2C), a *tenant* represents your organization and is a directory of users. Each Azure AD B2C tenant is distinct and separate from other Azure AD B2C tenants. An Azure AD B2C tenant is also different from a Microsoft Entra tenant, which you may already have.

+* **Directory** - This is where Azure AD B2C stores your users' credentials, profile data, and your application registrations.

+* **Application registrations** - You can register your web, mobile, and native applications with Azure AD B2C to enable identity management. You can also register any APIs you want to protect with Azure AD B2C.

+* **User flows** and **custom policies** - These are used to create identity experiences for your applications with built-in user flows and fully configurable custom policies:

+ * **Username, email, and phone sign-in** - You can configure your Azure AD B2C local accounts to allow sign up and sign in with a username, email address, phone number, or a combination of methods.

+ * **Social identity providers** - You can federate with social providers like Facebook, LinkedIn, or Twitter.

+ * **External identity providers** - You can also federate with standard identity protocols like OAuth 2.0, OpenID Connect, and more.

+* **Guest account** - These are external users you invite to your tenant as guests. A typical scenario for inviting a guest user to your Azure AD B2C tenant is to share administration responsibilities.

+* **Consumer account** - These are accounts that are managed by Azure AD B2C user flows and custom policies.

+Azure AD B2C provides various ways in which you can authenticate a user. Users can sign-in to a local account, by using username and password, phone verification (also known as passwordless authentication). Email sign-up is enabled by default in your local account identity provider settings.

+You can also extend the underlying Microsoft Entra ID schema to store additional information about your users. For example, their country/region of residency, preferred language, and preferences like whether they want to subscribe to a newsletter or enable multifactor authentication. For more information, see:

+You can configure Azure AD B2C to allow users to sign in to your application with credentials from social and enterprise identity providers. Azure AD B2C can federate with identity providers that support OAuth 1.0, OAuth 2.0, OpenID Connect, and SAML protocols. For example, Facebook, Microsoft account, Google, Twitter, and Active Directory Federation Service (AD FS).

+To learn more about identity providers, see [Add identity providers to your applications in Azure Active Directory B2C](add-identity-provider.md).

+In Azure AD B2C, you can define the business logic that users follow to gain access to your application. For example, you can determine the sequence of steps users follow when they sign in, sign up, edit their profile, or reset a password. After completing the sequence, the user acquires a token and gains access to your application.

+* **User flows** - These are predefined, built-in, configurable policies that we provide so you can create sign-up, sign-in, and policy editing experiences in minutes.

+* **Custom policies** - These enable you to create your own user journeys for complex identity experience scenarios.

+To learn more about user flows and custom policies, and help you decide which method will work best for your business needs, see [User flows and custom policies overview](user-flow-overview.md).

+You can customize your Azure AD B2C domain in the redirect URIs for your application. Custom domain allows you to create a seamless experience so that the pages that are shown blend seamlessly with the domain name of your application. From the user's perspective, they remain in your domain during the sign-in process rather than redirecting to the Azure AD B2C default domain *.b2clogin.com*.

+Language customization in Azure AD B2C allows you to accommodate different languages to suit your customer needs. Microsoft provides localizations for 36 languages, but you can also provide your own localizations for any language.

+Azure AD B2C ensures valid email addresses by requiring customers to verify them during the sign-up, and password reset flows. This also prevents malicious actors from using automated processes to generate fraudulent accounts in your applications.

+You can customize the email sent to users that sign up to use your applications. By using a third-party email provider, you can use your own email template and From: address and subject, as well as support localization and custom one-time password (OTP) settings. For more information, see:

+For more information, see [About API connectors in Azure AD B2C](api-connectors-overview.md).

+Azure AD B2C Multifactor Authentication (MFA) helps safeguard access to data and applications while maintaining simplicity for your users. It provides extra security by requiring a second form of authentication, and delivers strong authentication by offering a range of easy-to-use authentication methods.

+Azure AD B2C evaluates each sign-in event and ensures that all policy requirements are met before granting the user access. Risky users or risky sign-ins may be blocked, or challenged with a specific remediation like multifactor authentication (MFA). For more information, see [Identity Protection and Conditional Access](conditional-access-identity-protection-overview.md).

+As an Azure AD B2C tenant administrator, you can [reset a user's password](manage-users-portal.md#reset-a-users-password) if the user forgets their password. Or you can set a policy to force users to reset their password periodically. For more information, see [Set up a force password reset flow](force-password-reset.md).

+Azure AD B2C complies with the security, privacy, and other commitments described in the [Microsoft Azure Trust Center](https://www.microsoft.com//trust-center).

+Sessions are modeled as encrypted data, with the decryption key known only to the Azure AD B2C Security Token Service (STS). A strong encryption algorithm, AES-192, is used. All communication paths are protected with TLS for confidentiality and integrity. Our Security Token Service uses an Extended Validation (EV) certificate for TLS. In general, the Security Token Service mitigates cross-site scripting (XSS) attacks by not rendering untrusted input.

+For more information about Microsoft Entra roles, including Azure AD B2C administration role support, see [Administrator role permissions in Microsoft Entra ID](/entra/identity/role-based-access-control/permissions-reference).

+Azure AD B2C creates audit logs containing activity information about its resources, issued tokens, and administrator access. You can use the audit logs to understand platform activity and diagnose issues. Audit log entries are available soon after the activity that generated the event occurs.

+Use MS graph API to manage your Azure AD B2C directory. You can also create the Azure AD B2C directory itself. You can manage users, identity providers, user flows, custom policies and more.

+#Customer intent: As a developer, I want to learn how to create user flows and custom policies in the Azure portal to enable sign up, sign in, and user profile editing for my applications in Azure Active Directory B2C.

+The sign-up and sign-in user flow handles both experiences with a single configuration. Users of your application are led down the right path depending on the context. To create a sign-up and sign-in user flow:

+ 

+ 

+ 

+1. Select **Create** to add the user flow. A prefix of *B2C_1_* is automatically prepended to the name you entered earlier. For example, *B2C_1_signupsignin1*.

+1. From the **User flows** page, select the user flow you just created to open its overview page.

+1. At the top of the user flow overview page, select **Run user flow**. A pane will open at the right side of the page.

+ 

+1. Select your country and region, enter the name that you want displayed, enter a postal code, and then select **Create**. The token is returned to `https://jwt.ms` and should be displayed to you in your browser.

+1. You can now run the user flow again and you should be able to sign in with the account that you just created. The returned token includes the claims that you selected of country/region, name, and postal code.

+> The "Run user flow" experience is not currently compatible with the SPA reply URL type using authorization code flow. To use the "Run user flow" experience with these kinds of apps, [register a reply URL of type "Web" and enable the implicit flow.](tutorial-register-spa.md).

+1. From the **User flows** page, select the sign-up or sign-in user flow you just created.

+1. From the **User flows** page, select the user flow you just created to open its overview page, then select **Run user flow**.

+1. You now have the opportunity to change the password for the user. Change the password and select **Continue**. The token is returned to `https://jwt.ms` and should be displayed in your browser.

+1. At the top of the user flow overview page, select **Run user flow**. A pane will open at the right side of the page.

+1. You now have the opportunity to change the display name and job title for the user. Select **Continue**. The token is returned to `https://jwt.ms` and should be displayed in your browser.

+Azure AD B2C requires you to register two applications that it uses to sign up and sign in users with local accounts: *IdentityExperienceFramework*, a web API, and *ProxyIdentityExperienceFramework*, a native app with delegated permission to the IdentityExperienceFramework app. Your users can sign up with an email address or username and a password to access applications registered to your tenant, which creates a "local account." Local accounts exist only in your Azure AD B2C tenant.

+You will need to register these two applications in your Azure AD B2C tenant only once.

+1. Select the **APIs my organization uses** tab, then select the **IdentityExperienceFramework** application.

+Custom policies are a set of XML files you upload to your Azure AD B2C tenant to define technical profiles and user journeys. We provide starter packs with several pre-built policies to get you going quickly. Each of these starter packs contains the smallest number of technical profiles and user journeys needed to achieve the scenarios described. For a more in-depth guide to Azure AD B2C custom policies, follow our [custom policies how-to guide series](custom-policies-series-overview.md).

+- **SocialAndLocalAccountsWithMFA** - Enables social, local, and multifactor authentication options.

+Get the custom policy starter packs from GitHub, then update the XML files in the **SocialAndLocalAccounts** starter pack with your Azure AD B2C tenant name.

+The **SocialAndLocalAccounts** starter pack includes Facebook social sign in. Facebook isn't required for using custom policies, but we use it here to demonstrate how you can enable federated social login in a custom policy. If you don't need to enable federated social login, use the **LocalAccounts** starter pack instead, and skip to the [Upload the policies](tutorial-create-user-flows.md?pivots=b2c-custom-policy#upload-the-policies) section.

+ Title: "Tutorial - Register a web application in Azure Active Directory B2C"

+#Customer intent: As a developer or IT admin, I want to register my web application in Azure AD B2C so that I can enable my users to sign up, sign in, and manage their profiles.

+A "web application" refers to a traditional web application that performs most of the application logic on the server. They may be built using frameworks like ASP.NET Core, Spring (Java), Flask (Python), or Express (Node.js).

+To register a web application in your Azure AD B2C tenant, you can use our new unified **App registrations**. [Learn more about the new experience](./app-registrations-training-guide.md).

+#### App registrations

+#### App registrations

+# Customer intent: As a developer, I want to understand the difference between user flows and custom policies, so that I can choose the best method for my business needs. I want to understand the scenarios that can be enabled with each method, and how to integrate them with my applications.

+* Attributes to be collected from the consumer, such as first name, last name, postal code, or country/region of residency

+* Multifactor authentication

+A custom policy is fully configurable and policy-driven. It orchestrates trust between entities in standard protocols such as OpenID Connect, OAuth, SAML. As well as a few non-standard ones, for example REST API-based system-to-system claims exchanges. The framework creates user-friendly, white-labeled experiences.

+* [`ocrHighResolution`](#high-resolution-extraction)

+* [`formulas`](#formula-extraction)

+* [`styleFont`](#font-property-extraction)

+* [`barcodes`](#barcode-property-extraction)

+* [`languages`](#language-detection)

+> Not all add-on capabilities are supported by all models. For more information, *see* [model data extraction](concept-model-overview.md#model-data-extraction).

+* [`keyValuePairs`](#key-value-pairs)

+## Language detection

+It predicts the detected primary language for each text line along with the `confidence` in the `languages` collection under `analyzeResult`.

+```json

+"languages": [

+ {

+ "spans": [

+ {

+ "offset": 0,

+ "length": 131

+ }

+ ],

+ "locale": "en",

+ "confidence": 0.7

+ },

+]

+```

+## Key-value Pairs

+Key-value pairs are specific spans within the document that identify a label or key and its associated response or value. In a structured form, these pairs could be the label and the value the user entered for that field. In an unstructured document, they could be the date a contract was executed on based on the text in a paragraph. The AI model is trained to extract identifiable keys and values based on a wide variety of document types, formats, and structures.

+Keys can also exist in isolation when the model detects that a key exists, with no associated value or when processing optional fields. For example, a middle name field can be left blank on a form in some instances. Key-value pairs are spans of text contained in the document. For documents where the same value is described in different ways, for example, customer/user, the associated key is either customer or user (based on context).

+* You can pass a list of field labels like `Party1`, `Party2`, `TermsOfUse`, `PaymentTerms`, `PaymentDate`, and `TermEndDate`" as part of the `analyze document` request.

+|**Business card model**| &bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=businessCard)<br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)<br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)<br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)<br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)<br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)|**prebuilt-businessCard**|

+|_**Custom model**_| &bullet; [Document Intelligence Studio](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects)</br>&bullet; [REST API](/rest/api/aiservices/document-models/build-model?view=rest-aiservices-2023-10-31-preview&preserve-view=true&tabs=HTTP)</br>&bullet; [C# SDK](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [Java SDK](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [JavaScript SDK](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [Python SDK](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)|

+| _**Composed model**_| &bullet; [Document Intelligence Studio](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects)</br>&bullet; [REST API](/rest/api/aiservices/document-models/compose-model?view=rest-aiservices-2023-10-31-preview&preserve-view=true&tabs=HTTP)</br>&bullet; [C# SDK](/dotnet/api/azure.ai.formrecognizer.training.formtrainingclient.startcreatecomposedmodel)</br>&bullet; [Java SDK](/java/api/com.azure.ai.formrecognizer.training.formtrainingclient.begincreatecomposedmodel)</br>&bullet; [JavaScript SDK](/javascript/api/@azure/ai-form-recognizer/documentmodeladministrationclient?view=azure-node-latest#@azure-ai-form-recognizer-documentmodeladministrationclient-begincomposemodel&preserve-view=true)</br>&bullet; [Python SDK](/python/api/azure-ai-formrecognizer/azure.ai.formrecognizer.formtrainingclient?view=azure-python#azure-ai-formrecognizer-formtrainingclient-begin-create-composed-model&preserve-view=true)|

+|_**Custom model**_| &bullet; [Document Intelligence Studio](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects)</br>&bullet; [REST API](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br>&bullet; [C# SDK](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [Java SDK](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [JavaScript SDK](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [Python SDK](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)|

+| _**Composed model**_| &bullet; [Document Intelligence Studio](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects)</br>&bullet; [REST API](/rest/api/aiservices/document-models/compose-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br>&bullet; [C# SDK](/dotnet/api/azure.ai.formrecognizer.training.formtrainingclient.startcreatecomposedmodel)</br>&bullet; [Java SDK](/java/api/com.azure.ai.formrecognizer.training.formtrainingclient.begincreatecomposedmodel)</br>&bullet; [JavaScript SDK](/javascript/api/@azure/ai-form-recognizer/documentmodeladministrationclient?view=azure-node-latest#@azure-ai-form-recognizer-documentmodeladministrationclient-begincomposemodel&preserve-view=true)</br>&bullet; [Python SDK](/python/api/azure-ai-formrecognizer/azure.ai.formrecognizer.formtrainingclient?view=azure-python#azure-ai-formrecognizer-formtrainingclient-begin-create-composed-model&preserve-view=true)|

+Automated contract processing is the process of extracting key contract fields from documents. Historically, the contract analysis process is achieved manually and, hence, very time consuming. Accurate extraction of key data from contracts is typically the first and one of the most critical steps in the contract automation process.

+|**Contract model**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-10-31-preview&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)|**prebuilt-contract**|

+|**Contract model**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)|**prebuilt-contract**|

+ > [Document Intelligence API v4.0:2023-10-31-preview](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-10-31-preview&preserve-view=true&tabs=HTTP)

+ > [Document Intelligence API v3.1:2023-07-31 (GA)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)

+> Use the [**REST API**](/rest/api/aiservices/document-models/copy-model-to?view=rest-aiservices-2023-10-31-preview&preserve-view=true

+&tabs=HTTP) or [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects) to copy a model to another region.

+> Use the [**REST API**](/rest/api/aiservices/document-models/copy-model-to?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP) or [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects) to copy a model to another region.

+| Custom document | [Document Intelligence 3.1](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)| [Document Intelligence SDK](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)| [Document Intelligence Studio](https://formrecognizer.appliedai.azure.com/studio)

+Custom template models are generally available with the [v4.0 API](/rest/api/aiservices/document-models/build-model?view=rest-aiservices-2023-10-31-preview&preserve-view=true&tabs=HTTP). If you're starting with a new project or have an existing labeled dataset, use the v3.1 or v3.0 API with Document Intelligence Studio to train a custom template model.

+| Custom template | [v3.1 API](/rest/api/aiservices/document-models/build-model?view=rest-aiservices-2023-10-31-preview&preserve-view=true&tabs=HTTP)| [Document Intelligence SDK](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)| [Document Intelligence Studio](https://formrecognizer.appliedai.azure.com/studio)|

+Custom template models are generally available with the [v3.1 API](/rest/api/aiservices/document-models/build-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP). If you're starting with a new project or have an existing labeled dataset, use the v3.1 or v3.0 API with Document Intelligence Studio to train a custom template model.

+| Custom template | [v3.1 API](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)| [Document Intelligence SDK](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)| [Document Intelligence Studio](https://formrecognizer.appliedai.azure.com/studio)|

+If the language of your documents and extraction scenarios supports custom neural models, we recommend that you use custom neural models over template models for higher accuracy.

+The build custom model operation adds support for the *template* and *neural* custom models. Previous versions of the REST API and SDKs only supported a single build mode that is now known as the *template* mode.

+|Custom model| &bullet; [Document Intelligence Studio](https://formrecognizer.appliedai.azure.com/studio/customform/projects)</br>&bullet; [REST API](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br>&bullet; [C# SDK](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [Python SDK](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)|***custom-model-id***|

+| Custom template v 4.0 v3.1 v3.0 | [Document Intelligence 3.1](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)| [Document Intelligence SDK](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)| [Document Intelligence Studio](https://formrecognizer.appliedai.azure.com/studio)|

+| Custom neural v4.0 v3.1 v3.0 | [Document Intelligence 3.1](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)| [Document Intelligence SDK](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)| [Document Intelligence Studio](https://formrecognizer.appliedai.azure.com/studio)

+* [REST API](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP): This API shows you more about the v3.0 version and new capabilities.

+|`Layout` model with the optional query string parameter **`features=keyValuePairs`** enabled.|&bullet; v4:2023-10-31-preview</br>&bullet; v3.1:2023-07-31 (GA) |**`prebuilt-layout`**|

+|**General document model**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)|**prebuilt-document**|

+* Explore our [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP).

+|**Health insurance card model**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-10-31-preview&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)|**prebuilt-healthInsuranceCard.us**|

+|**Health insurance card model**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)|**prebuilt-healthInsuranceCard.us**|

+* Explore our [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP) to learn more about the v3.1 version and new capabilities.

+|**ID document model**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-10-31-preview&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)|**prebuilt-idDocument**|

+|**ID document model**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)|**prebuilt-idDocument**|

+|**Invoice model**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-10-31-preview&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)|**prebuilt-invoice**|

+|**Invoice model**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)|**prebuilt-invoice**|

+|**Layout model**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-10-31-preview&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)|**prebuilt-layout**|

+|**Layout model**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)|**prebuilt-layout**|

+1. Select **Run Layout**. The Document Intelligence Sample Labeling tool calls the `Analyze Layout` API and analyze the document.

+The second step is to call the [Get Analyze Layout Result](https://westcentralus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/GetAnalyzeLayoutResult) operation. This operation takes as input the Result ID the `Analyze Layout` operation created. It returns a JSON response that contains a **status** field with the following possible values.

+|Model|[2023-10-31-preview](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-10-31-preview&preserve-view=true&tabs=HTTP)|[2023-07-31 (GA)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)|[2022-08-31 (GA)](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)|[v2.1 (GA)](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/AnalyzeBusinessCardAsync)|

+For all models, except Business card model, Document Intelligence now supports add-on capabilities to allow for more sophisticated analysis. These optional capabilities can be enabled and disabled depending on the scenario of the document extraction. There are seven add-on capabilities available for the `2023-07-31` (GA) and later API version:

+* [`ocrHighResolution`](concept-add-on-capabilities.md#high-resolution-extraction)

+* [`formulas`](concept-add-on-capabilities.md#formula-extraction)

+* [`styleFont`](concept-add-on-capabilities.md#font-property-extraction)

+* [`barcodes`](concept-add-on-capabilities.md#barcode-property-extraction)

+* [`languages`](concept-add-on-capabilities.md#language-detection)

+* [`keyValuePairs`](concept-add-on-capabilities.md#key-value-pairs) (2023-10-31-preview)

+* [`queryFields`](concept-add-on-capabilities.md#query-fields) (2023-31-preview)

+|**Read OCR model**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-10-31-preview&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)|**prebuilt-read**|

+|**Read OCR model**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)|**prebuilt-read**|

+> [Document Intelligence API v3.1](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)

+|**Receipt model**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-10-31-preview&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)|**prebuilt-receipt**|

+|**Receipt model**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)|**prebuilt-receipt**|

+|**US tax form models**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-10-31-preview&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)|**&bullet; prebuilt-tax.us.W-2</br>&bullet; prebuilt-tax.us.1098</br>&bullet; prebuilt-tax.us.1098E</br>&bullet; prebuilt-tax.us.1098T</br>&bullet; prebuilt-tax.us.1099(Variations)**|

+|**US tax form models**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.1.0&preserve-view=true)|**&bullet; prebuilt-tax.us.W-2</br>&bullet; prebuilt-tax.us.1098</br>&bullet; prebuilt-tax.us.1098E</br>&bullet; prebuilt-tax.us.1098T**|

+| `TaxYear` | String | Tax Year extracted from Form 1099-NEC.| 2021 |

+| `Payer` | Object | An object that contains the payer's TIN, Name, Address, and PhoneNumber | |

+| `Recipient` | Object | An object that contains the recipient's TIN, Name, Address, and AccountNumber| |

+| `Box1` |number|Box 1 extracted from Form 1099-NEC.| 123456 |

+| `Box2` |boolean|Box 2 extracted from Form 1099-NEC.| true |

+| `Box4` |number|Box 4 extracted from Form 1099-NEC.| 123456 |

+| `StateTaxesWithheld` |array| State Taxes Withheld extracted from Form 1099-NEC (boxes 5, 6, and 7)| |

+To use your SAS URL with the [REST API](/rest/api/aiservices/document-models/build-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP), add the SAS URL to the request body:

+You can also use the **[Get model](/rest/api/aiservices/document-models/get-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)** API to track the status of the operation by querying the target model. Call the API using the target model ID that you copied down from the [Generate Copy authorization request](#generate-copy-authorization-request) response.

+You can use the [**Get operation**](/rest/api/aiservices/miscellaneous/get-operation?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP) API to list all document model operations (succeeded, in-progress, or failed) associated with your Document Intelligence resource. Operation information only persists for 24 hours. Here's a list of the operations (operationId) that can be returned:

+If the operation was successful, the document model can be accessed using the [**getModel**](/rest/api/aiservices/document-models/get-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP) (get a single model), or [**GetModels**](/rest/api/aiservices/document-models/get-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTPs) (get a list of models) APIs.

+* [REST API reference documentation](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)

+Document Intelligence uses the [prebuilt-layout model](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP) API to learn the expected sizes and positions of typeface and handwritten text elements and extract tables. Then it uses user-specified labels to learn the key/value associations and tables in the documents. We recommend that you use five manually labeled forms of the same type (same structure) to get started with training a new model. Then, add more labeled data, as needed, to improve the model accuracy. Document Intelligence enables training a model to extract key-value pairs and tables using supervised learning capabilities.

+With the [**create compose model**](/rest/api/aiservices/document-models/compose-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP) operation, you can assign up to 100 trained custom models to a single model ID. When analyze documents with a composed model, Document Intelligence first classifies the form you submitted, then chooses the best matching assigned model, and returns results for that model. This operation is useful when incoming forms may belong to one of several templates.

+The [compose model API](/rest/api/aiservices/document-models/compose-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP) accepts a list of model IDs to be composed.

+To make an [**Analyze document**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP) request, use a unique model name in the request parameters.

+You can manage custom models throughout your development needs including [**copying**](/rest/api/aiservices/document-models/copy-model-to?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP), [**listing**](/rest/api/aiservices/document-models/get-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTPs), and [**deleting**](/rest/api/aiservices/document-models/delete-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP) your models.

+Using the **REST API**, you can make a [**Compose Custom Model**](/rest/api/aiservices/document-models/compose-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP) request to create a single composed model from existing models. The request body requires a string array of your `modelIds` to compose and you can optionally define the `modelName`.

+Using the REST API, you can make an [Analyze Document](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP) request to analyze a document and extract key-value pairs and table data.

+You can [manage your custom models](../how-to-guides/use-sdk-rest-api.md?view=doc-intel-2.1.0&preserve-view=true) throughout their lifecycle by viewing a [list of all custom models](/rest/api/aiservices/document-models/get-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTPs) under your subscription, retrieving information about [a specific custom model](/rest/api/aiservices/document-models/get-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP), and [deleting custom models](/rest/api/aiservices/document-models/delete-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP) from your account.

+> [Document Intelligence API reference](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)

+> [Explore the Document Intelligence REST API](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)

+|**prebuilt-contract**|Extract contract agreement and party details.|&#9679; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=contract)</br>&#9679; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)

+|**prebuilt-tax.us.1098**|Extract mortgage interest information and details.|&#9679; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=tax.us.1098)</br>&#9679; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)

+|**prebuilt-tax.us.1098E**|Extract student loan information and details.|&#9679; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=tax.us.1098E)</br>&#9679; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)

+|**prebuilt-tax.us.1098T**|Extract tuition information and details.|&#9679; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=tax.us.1098T)</br>&#9679; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)

+|[**Custom model**](concept-custom.md) | Extracts information from forms and documents into structured data based on a model created from a set of representative training document sets.|Extract distinct data from forms and documents specific to your business and use cases.|&#9679; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects)</br>&#9679; [**REST API**](/rest/api/aiservices/document-models/build-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br>&#9679; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&#9679; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&#9679; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&#9679; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)|

+|[**Custom Template model**](concept-custom-template.md) | The custom template model extracts labeled values and fields from structured and semi-structured documents.</br> | Extract key data from highly structured documents with defined visual templates or common visual layouts, forms.| &#9679; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects)</br>&#9679; [**REST API**](/rest/api/aiservices/document-models/build-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br>&#9679; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&#9679; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&#9679; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&#9679; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)

+ |[**Custom Neural model**](concept-custom-neural.md)| The custom neural model is used to extract labeled data from structured (surveys, questionnaires), semi-structured (invoices, purchase orders), and unstructured documents (contracts, letters).|Extract text data, checkboxes, and tabular fields from structured and unstructured documents.|[**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects)</br>&#9679; [**REST API**](/rest/api/aiservices/document-models/build-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br>&#9679; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&#9679; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&#9679; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&#9679; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)

+|[**Composed custom models**](concept-composed-models.md)| A composed model is created by taking a collection of custom models and assigning them to a single model built from your form types.| Useful when you train several models and want to group them to analyze similar form types like purchase orders.|&#9679; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects)</br>&#9679; [**REST API**](/rest/api/aiservices/document-models/compose-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br>&#9679; [**C# SDK**](/dotnet/api/azure.ai.formrecognizer.training.formtrainingclient.startcreatecomposedmodel)</br>&#9679; [**Java SDK**](/jav?view=doc-intel-3.0.0&preserve-view=true)

+|[**Composed classification model**](concept-custom-classifier.md)| Custom classification models combine layout and language features to detect, identify, and classify documents within an input file.|&#9679; A loan application packaged containing application form, payslip, and, bank statement.</br>&#9679; A collection of scanned invoices. |&#9679; [Document Intelligence Studio](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects)</br>&#9679; [REST API](/rest/api/aiservices/document-classifiers/build-classifier?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br>

+| [.NET/C# → 4.0.0 (GA)](https://azuresdkdocs.blob.core.windows.net/$web/dotnet/Azure.AI.FormRecognizer/4.0.0/https://docsupdatetracker.net/index.html)|[NuGet](https://www.nuget.org/packages/Azure.AI.FormRecognizer)|[v3.0](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br> [v2.1](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/AnalyzeBusinessCardAsync)</br>[v2.0](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2/operations/AnalyzeLayoutAsync) |[Windows, macOS, Linux, Docker](https://dotnet.microsoft.com/download)|

+|[Java → 4.0.6 (GA)](https://azuresdkdocs.blob.core.windows.net/$web/java/azure-ai-formrecognizer/4.0.0/https://docsupdatetracker.net/index.html) |[MVN repository](https://mvnrepository.com/artifact/com.azure/azure-ai-formrecognizer/4.0.0-beta.6) |[v3.0](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br> [v2.1](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/AnalyzeBusinessCardAsync)</br>[v2.0](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2/operations/AnalyzeLayoutAsync) |[Windows, macOS, Linux](/java/openjdk/install)|

+|[JavaScript → 4.0.0 (GA)](https://azuresdkdocs.blob.core.windows.net/$web/javascript/azure-ai-form-recognizer/4.0.0/https://docsupdatetracker.net/index.html)| [npm](https://www.npmjs.com/package/@azure/ai-form-recognizer)| [v3.0](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br> [v2.1](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/AnalyzeBusinessCardAsync)</br>[v2.0](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2/operations/AnalyzeLayoutAsync) | [Browser, Windows, macOS, Linux](https://nodejs.org/en/download/) |

+|[Python → 3.2.0 (GA)](https://azuresdkdocs.blob.core.windows.net/$web/python/azure-ai-formrecognizer/3.2.0/https://docsupdatetracker.net/index.html) | [PyPI](https://pypi.org/project/azure-ai-formrecognizer/3.2.0/)| [v3.0](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br> [v2.1](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/AnalyzeBusinessCardAsync)</br>[v2.0](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2/operations/AnalyzeLayoutAsync) |[Windows, macOS, Linux](/azure/developer/python/configure-local-development-environment?tabs=windows%2Capt%2Ccmd#use-the-azure-cli)

+> [**Explore Document Intelligence REST API v3.0**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)

+| [**.NET/C# → latest (GA)**](/dotnet/api/overview/azure/ai.formrecognizer-readme?view=azure-dotnet&preserve-view=true)|[NuGet](https://www.nuget.org/packages/Azure.AI.FormRecognizer/4.1.0)|[&bullet; 2023-07-31 (GA)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br> [&bullet; 2022-08-31 (GA)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br> [&bullet; v2.1](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/AnalyzeBusinessCardAsync)</br>[&bullet; v2.0](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2/operations/AnalyzeLayoutAsync) |[Windows, macOS, Linux, Docker](https://dotnet.microsoft.com/download)|

+|[**Java → latest (GA)**](https://azuresdkdocs.blob.core.windows.net/$web/java/azure-ai-formrecognizer/4.1.0/https://docsupdatetracker.net/index.html) |[MVN repository](https://mvnrepository.com/artifact/com.azure/azure-ai-formrecognizer/4.1.0) |[&bullet; 2023-07-31 (GA)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br> [&bullet; 2022-08-31 (GA)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br> [&bullet; v2.1](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/AnalyzeBusinessCardAsync)</br>[&bullet; v2.0](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2/operations/AnalyzeLayoutAsync) |[Windows, macOS, Linux](/java/openjdk/install)|

+|[**JavaScript → latest (GA)**](https://azuresdkdocs.blob.core.windows.net/$web/javascript/azure-ai-form-recognizer/5.0.0/https://docsupdatetracker.net/index.html)| [npm](https://www.npmjs.com/package/@azure/ai-form-recognizer)| [&bullet; 2023-07-31 (GA)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br> &bullet; [2022-08-31 (GA)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br> [&bullet; v2.1](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/AnalyzeBusinessCardAsync)</br>[&bullet; v2.0](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2/operations/AnalyzeLayoutAsync) | [Browser, Windows, macOS, Linux](https://nodejs.org/en/download/) |

+|[**Python → latest (GA)**](https://azuresdkdocs.blob.core.windows.net/$web/python/azure-ai-formrecognizer/3.3.0/https://docsupdatetracker.net/index.html) | [PyPI](https://pypi.org/project/azure-ai-formrecognizer/3.3.0/)| [&bullet; 2023-07-31 (GA)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br> &bullet; [2022-08-31 (GA)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br> [&bullet; v2.1](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/AnalyzeBusinessCardAsync)</br>[&bullet; v2.0](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2/operations/AnalyzeLayoutAsync) |[Windows, macOS, Linux](/azure/developer/python/configure-local-development-environment?tabs=windows%2Capt%2Ccmd#use-the-azure-cli)

+>Explore [**Document Intelligence REST API 2023-07-31**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP) operations.

+* [Review the new REST API](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)

+> All January 2023 updates are available with [REST API version **2022-08-31 (GA)**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP).

+ * **Document Intelligence REST API v3.0 is now generally available and ready for use in production applications!** Update your applications with [**REST API version 2022-08-31**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP).

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

+**¹** GPT-4 Turbo Preview = `gpt-4` (1106-preview). To deploy this model, under **Deployments** select model **gpt-4**. For **Model version** select **1106-preview**. We don't recommend using this model in production. We will upgrade all deployments of this model to a future stable version. Models designated preview do not follow the standard Azure OpenAI model lifecycle.

+> All customers have the ability to modify the content filters to be stricter (for example, to filter content at lower severity levels than the default). Approval is required for turning the content filters partially or fully off. Managed customers only may apply for full content filtering control via this form: [Azure OpenAI Limited Access Review: Modified Content Filters and Abuse Monitoring (microsoft.com)](https://customervoice.microsoft.com/Pages/ResponsePage.aspx?id=v4j5cvGGr0GRqy180BHbR7en2Ais5pxKtso_Pz4b1_xURE01NDY1OUhBRzQ3MkQxMUhZSE1ZUlJKTiQlQCN0PWcu).

+The content filtering system integrated into Azure OpenAI Service runs alongside the core models and uses an ensemble of multi-class classification models to detect four categories of harmful content (violence, hate, sexual, and self-harm) at four severity levels respectively (safe, low, medium, and high), and optional binary classifiers for detecting jailbreak risk, existing text, and code in public repositories. The default content filtering configuration is set to filter at the medium severity threshold for all four content harms categories for both prompts and completions. That means that content that is detected at severity level medium or high is filtered, while content detected at severity level low or safe is not filtered by the content filters. Learn more about content categories, severity levels, and the behavior of the content filtering system [here](../concepts/content-filter.md). Jailbreak risk detection and protected text and code models are optional and off by default. For jailbreak and protected material text and code models, the configurability feature allows all customers to turn the models on and off. The models are by default off and can be turned on per your scenario. Note that some models are required to be on for certain scenarios to retain coverage under the [Customer Copyright Commitment](/legal/cognitive-services/openai/customer-copyright-commitment?context=%2Fazure%2Fai-services%2Fopenai%2Fcontext%2Fcontext).

+EmbeddingsOptions embeddingOptions = new()

+{

+ DeploymentName = "text-embedding-ada-002",

+ Input = { "Your text string goes here" },

+};

+var returnValue = openAIClient.GetEmbeddings(embeddingOptions);

+foreach (float item in returnValue.Value.Data[0].Embedding.ToArray())

+ Title: Azure OpenAI Service performance & latency

+description: Learn about performance and latency with Azure OpenAI

+recommendations: false

+# Performance and latency

+This article will provide you with background around how latency works with Azure OpenAI and how to optimize your environment to improve performance.

+## What is latency?

+The high level definition of latency in this context is the amount of time it takes to get a response back from the model. For completion and chat completion requests, latency is largely dependent on model type as well as the number of tokens generated and returned. The number of tokens sent to the model as part of the input token limit, has a much smaller overall impact on latency.

+## Improve performance

+### Model selection

+Latency varies based on what model you are using. For an identical request, it is expected that different models will have a different latency. If your use case requires the lowest latency models with the fastest response times we recommend the latest models in the [GPT-3.5 Turbo model series](../concepts/models.md#gpt-35-models).

+### Max tokens

+When you send a completion request to the Azure OpenAI endpoint your input text is converted to tokens which are then sent to your deployed model. The model receives the input tokens and then begins generating a response. It's an iterative sequential process, one token at a time. Another way to think of it is like a for loop with `n tokens = n iterations`.

+So another important factor when evaluating latency is how many tokens are being generated. This is controlled largely via the `max_tokens` parameter. Reducing the number of tokens generated per request will reduce the latency of each request.

+### Streaming

+**Examples of when to use streaming**:

+Chat bots and conversational interfaces.

+Streaming impacts perceived latency. If you have streaming enabled you'll receive tokens back in chunks as soon as they're available. From a user perspective, this often feels like the model is responding faster even though the overall time to complete the request remains the same.

+**Examples of when streaming is less important**:

+Sentiment analysis, language translation, content generation.

+There are many use cases where you are performing some bulk task where you only care about the finished result, not the real-time response. If streaming is disabled, you won't receive any tokens until the model has finished the entire response.

+### Content filtering

+Azure OpenAI includes a [content filtering system](./content-filters.md) that works alongside the core models. This system works by running both the prompt and completion through an ensemble of classification models aimed at detecting and preventing the output of harmful content.

+The content filtering system detects and takes action on specific categories of potentially harmful content in both input prompts and output completions.

+The addition of content filtering comes with an increase in safety, but also latency. There are many applications where this tradeoff in performance is necessary, however there are certain lower risk use cases where disabling the content filters to improve performance might be worth exploring.

+Learn more about requesting modifications to the default, [content filtering policies](./content-filters.md).

+## Summary

+* **Model latency**: If model latency is important to you we recommend trying out our latest models in the [GPT-3.5 Turbo model series](../concepts/models.md).

+* **Lower max tokens**: OpenAI has found that even in cases where the total number of tokens generated is similar the request with the higher value set for the max token parameter will have more latency.

+* **Lower total tokens generated**: The fewer tokens generated the faster the overall response will be. Remember this is like having a for loop with `n tokens = n iterations`. Lower the number of tokens generated and overall response time will improve accordingly.

+* **Streaming**: Enabling streaming can be useful in managing user expectations in certain situations by allowing the user to see the model response as it is being generated rather than having to wait until the last token is ready.

+* **Content Filtering** improves safety, but it also impacts latency. Evaluate if any of your workloads would benefit from [modified content filtering policies](./content-filters.md).

+- `openai.File.find_matching_files()`

+This article only shows examples with the new OpenAI Python 1.x API library. For information on migrating from `0.28.1` to `1.x` refer to our [migration guide](./migration.md).

+from openai import OpenAI

+client = OpenAI(

+ api_key=os.environ['OPENAI_API_KEY']

+)

+import os

+from openai import AzureOpenAI

+

+client = AzureOpenAI(

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

+ api_version="2023-10-01-preview",

+ azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")

+ )

+from openai import OpenAI

+client = OpenAI(

+ api_key=os.environ['OPENAI_API_KEY']

+)

+from azure.identity import DefaultAzureCredential, get_bearer_token_provider

+from openai import AzureOpenAI

+token_provider = get_bearer_token_provider(DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default")

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

+endpoint = "https://my-resource.openai.azure.com"

+client = AzureOpenAI(

+ api_version=api_version,

+ azure_endpoint=endpoint,

+ azure_ad_token_provider=token_provider,

+)

+completion = client.completions.create(

+ model='gpt-3.5-turbo-instruct',

+ prompt="<prompt>)

+chat_completion = client.chat.completions.create(

+ model="gpt-4",

+ messages="<messages>"

+embedding = client.embeddings.create(

+ input="<input>",

+ model="text-embedding-ada-002"

+)

+completion = client.completions.create(

+ model=gpt-35-turbo-instruct, # This must match the custom deployment name you chose for your model.

+ prompt=<"prompt">

+chat_completion = client.chat.completions.create(

+ model="gpt-35-turbo", # model = "deployment_name".

+ messages=<"messages">

+embedding = client.embeddings.create(

+ input = "<input>",

+ model= "text-embedding-ada-002" # model = "deployment_name".

+embedding = client.embeddings.create(

+embedding = client.embeddings.create(

+ model="text-embedding-ada-002" # This must match the custom deployment name you chose for your model.

+| Default DALL-E 3 quota limits| 2 capacity units (6 requests per minute)|

+### Responsible AI

+- **Expanded customer configurability**: All Azure OpenAI customers can now configure all severity levels (low, medium, high) for the categories hate, violence, sexual and self-harm, including filtering only high severity content. [Configure content filters](./how-to/content-filters.md)

+- **Content Credentials in all DALL-E models**: AI-generated images from all DALL-E models now include a digital credential that discloses the content as AI-generated. Applications that display image assets can leverage the open source [Content Authenticity Initiative SDK](https://opensource.contentauthenticity.org/docs/js-sdk/getting-started/quick-start/) to display credentials in their AI generated images. [Content Credentials in Azure OpenAI](/azure/ai-services/openai/concepts/content-credentials)

+- **New RAI models**

+

+ - **Jailbreak risk detection**: Jailbreak attacks are user prompts designed to provoke the Generative AI model into exhibiting behaviors it was trained to avoid or to break the rules set in the System Message. The jailbreak risk detection model is optional (default off), and available in annotate and filter model. It runs on user prompts.

+ - **Protected material text**: Protected material text describes known text content (for example, song lyrics, articles, recipes, and selected web content) that can be outputted by large language models. The protected material text model is optional (default off), and available in annotate and filter model. It runs on LLM completions.

+ - **Protected material code**: Protected material code describes source code that matches a set of source code from public repositories, which can be outputted by large language models without proper citation of source repositories. The protected material code model is optional (default off), and available in annotate and filter model. It runs on LLM completions.

+ [Configure content filters](./how-to/content-filters.md)

+- **Blocklists**: Customers can now quickly customize content filter behavior for prompts and completions further by creating a custom blocklist in their filters. The custom blocklist allows the filter to take action on a customized list of patterns, such as specific terms or regex patterns. In addition to custom blocklists, we provide a Microsoft profanity blocklist (English). [Use blocklists](./how-to/use-blocklists.md)

+ Title: Recover or purge deleted Azure AI services resources

+description: This article provides instructions on how to recover or purge an already-deleted Azure AI services resource.

+# Recover or purge deleted Azure AI services resources

+This article provides instructions on how to recover or purge an Azure AI services resource that is already deleted.

+Once you delete a resource, you won't be able to create another one with the same name for 48 hours. To create a resource with the same name, you need to purge the deleted resource.

+> [!NOTE]

+> The instructions in this article are applicable to both a multi-service resource and a single-service resource. A multi-service resource enables access to multiple Azure AI services using a single key and endpoint. On the other hand, a single-service resource enables access to just that specific Azure AI service for which the resource was created.

+## Recover a deleted resource

+The following prerequisites must be met before you can recover a deleted resource:

+* The resource to be recovered must have been deleted within the past 48 hours.

+* The resource to be recovered must not have been purged already. A purged resource can't be recovered.

+* Before you attempt to recover a deleted resource, make sure that the resource group for that account exists. If the resource group was deleted, you must recreate it. Recovering a resource group isn't possible. For more information, seeΓÇ»[Manage resource groups](../azure-resource-manager/management/manage-resource-groups-portal.md).

+* If the deleted resource used customer-managed keys with Azure Key Vault and the key vault have also been deleted, then you must restore the key vault before you restore the Azure AI services resource. For more information, see [Azure Key Vault recovery management](../key-vault/general/key-vault-recovery.md).

+* If the deleted resource used a customer-managed storage and storage account has also been deleted, you must restore the storage account before you restore the Azure AI services resource. For instructions, see [Recover a deleted storage account](../storage/common/storage-account-recover.md).

+To recover a deleted Azure AI services resource, use the following commands. Where applicable, replace:

+* `{subscriptionID}` with your Azure subscription ID

+* `{resourceGroup}` with your resource group

+* `{resourceName}` with your resource name

+* `{location}` with the location of your resource

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

+If you need to recover a deleted resource, navigate to the hub of the Azure AI services API type and select "Manage deleted resources" from the menu. For example, if you would like to recover an "Anomaly detector" resource, search for "Anomaly detector" in the search bar and select the service. Then select **Manage deleted resources**.

+Select the subscription in the dropdown list to locate the deleted resource you would like to recover. Select one or more of the deleted resources and select **Recover**.

+> [!NOTE]

+> It can take a couple of minutes for your deleted resource(s) to recover and show up in the list of the resources. Select the **Refresh** button in the menu to update the list of resources.

+# [Rest API](#tab/rest-api)

+Use the following `PUT` command:

+```rest-api

+https://management.azure.com/subscriptions/{subscriptionID}/resourceGroups/{resourceGroup}/providers/Microsoft.CognitiveServices/accounts/{resourceName}?Api-Version=2021-04-30

+```

+In the request body, use the following JSON format:

+```json

+{

+ "location": "{location}",

+ "properties": {

+ "restore": true

+ }

+}

+```

+# [PowerShell](#tab/powershell)

+Use the following command to restore the resource:

+```powershell

+New-AzResource -Location {location} -Properties @{restore=$true} -ResourceId /subscriptions/{subscriptionID}/resourceGroups/{resourceGroup}/providers/Microsoft.CognitiveServices/accounts/{resourceName} -ApiVersion 2021-04-30

+```

+If you need to find the name of your deleted resources, you can get a list of deleted resource names with the following command:

+```powershell

+Get-AzResource -ResourceId /subscriptions/{subscriptionId}/providers/Microsoft.CognitiveServices/deletedAccounts -ApiVersion 2021-04-30

+```

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

+```azurecli-interactive

+az resource create --subscription {subscriptionID} -g {resourceGroup} -n {resourceName} --location {location} --namespace Microsoft.CognitiveServices --resource-type accounts --properties "{\"restore\": true}"

+```

+## Purge a deleted resource

+Your subscription must have `Microsoft.CognitiveServices/locations/resourceGroups/deletedAccounts/delete` permissions to purge resources, such as [Cognitive Services Contributor](../role-based-access-control/built-in-roles.md#cognitive-services-contributor) or [Contributor](../role-based-access-control/built-in-roles.md#contributor).

+When using `Contributor` to purge a resource the role must be assigned at the subscription level. If the role assignment is only present at the resource or resource group level, you can't access the purge functionality.

+To purge a deleted Azure AI services resource, use the following commands. Where applicable, replace:

+* `{subscriptionID}` with your Azure subscription ID

+* `{resourceGroup}` with your resource group

+* `{resourceName}` with your resource name

+* `{location}` with the location of your resource

+> [!NOTE]

+> Once a resource is purged, it is permanently deleted and cannot be restored. You will lose all data and keys associated with the resource.

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

+If you need to purge a deleted resource, the steps are similar to recovering a deleted resource.

+1. Navigate to the hub of the Azure AI services API type of your deleted resource. For example, if you would like to purge an "Anomaly detector" resource, search for "Anomaly detector" in the search bar and select the service. Then select **Manage deleted resources** from the menu.

+1. Select the subscription in the dropdown list to locate the deleted resource you would like to purge.

+1. Select one or more deleted resources and select **Purge**. Purging permanently deletes an Azure AI services resource.

+ :::image type="content" source="media/managing-deleted-resource.png" alt-text="A screenshot showing a list of resources that can be purged." lightbox="media/managing-deleted-resource.png":::

+# [Rest API](#tab/rest-api)

+Use the following `DELETE` command:

+```rest-api

+https://management.azure.com/subscriptions/{subscriptionID}/providers/Microsoft.CognitiveServices/locations/{location}/resourceGroups/{resourceGroup}/deletedAccounts/{resourceName}?Api-Version=2021-04-30`

+```

+# [PowerShell](#tab/powershell)

+```powershell

+Remove-AzResource -ResourceId /subscriptions/{subscriptionID}/providers/Microsoft.CognitiveServices/locations/{location}/resourceGroups/{resourceGroup}/deletedAccounts/{resourceName} -ApiVersion 2021-04-30

+```

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

+```azurecli-interactive

+az resource delete --ids /subscriptions/{subscriptionId}/providers/Microsoft.CognitiveServices/locations/{location}/resourceGroups/{resourceGroup}/deletedAccounts/{resourceName}

+```

+## See also

+* [Create a multi-service resource](multi-service-resource.md)

+* [Create a new resource using an ARM template](create-account-resource-manager-template.md)

+pronunciationAssessmentConfig.enableProsodyAssessment();

+pronunciationAssessmentConfig.enableContentAssessmentWithTopic("greeting");

+| File size (lexicon file)² | 30KB per file | 100KB per file|

+² The characters of lexicon file aren't charged. Only the lexicon elements in SSML are counted as billable characters. Refer to [billable characters](text-to-speech.md#billable-characters) to learn more.

+> [!NOTE]

+> For an Azure AI resource using a managed virtual network, a private endpoint is automatically created for a connection if the target resource is an Azure Private Link supported resource (Key Vault, Storage Account, Container Registry, Azure AI, Azure OpenAI, Azure Cognitive Search). For more on connections, see [How to add a new connection in Azure AI Studio](connections-add.md).

+ :::image type="content" source="../media/how-to/projects-create-details.png" alt-text="Screenshot of the project details page within the create project dialog." lightbox="../media/how-to/projects-create-details.png":::

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

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

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

+1. You're taken to the index details page where you can see the status of your index creation.

+**Question:** I deployed a model but I don't see it in the playground.

+**Answer:** Playground only supports a few select models, such as Azure OpenAI models and Llama-2. If playground support is available, you see the **Open in playground** button on the model deployment's **Details** page.

+1. On the deployment details page from the previous step, select **Open in playground**.

+ Title: Build and deploy a question and answer copilot with prompt flow in Azure AI Studio

+description: Use this article to build and deploy a question and answer copilot with prompt flow in Azure AI Studio

+# Tutorial: Build and deploy a question and answer copilot with prompt flow in Azure AI Studio

+In this [Azure AI Studio](https://ai.azure.com) tutorial, you use generative AI and prompt flow to build, configure, and deploy a copilot for your retail company called Contoso. Your retail company specializes in outdoor camping gear and clothing.

+The copilot should answer questions about your products and services. It should also answer questions about your customers. For example, the copilot can answer questions such as "How much do the TrailWalker hiking shoes cost?" and "How many TrailWalker hiking shoes did Daniel Wilson buy?".

+The steps in this tutorial are:

+1. Create an Azure AI Studio project.

+1. Deploy an Azure OpenAI model and chat with your data.

+1. Create a prompt flow from the playground.

+1. Customize prompt flow with multiple data sources.

+1. Evaluate the flow using a question and answer evaluation dataset.

+1. Deploy the flow for consumption.

+## Prerequisites

+- An Azure subscription - <a href="https://azure.microsoft.com/free/cognitive-services" target="_blank">Create one for free</a>.

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

+ Currently, access to this service is granted only by application. You can apply for access to Azure OpenAI by completing the form at <a href="https://aka.ms/oai/access" target="_blank">https://aka.ms/oai/access</a>. Open an issue on this repo to contact us if you have an issue.

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

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

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

+- Your subscription needs to be below your [quota limit](../how-to/quota.md) to [deploy a new model in this tutorial](#deploy-a-chat-model). Otherwise you already need to have a [deployed chat model](../how-to/deploy-models.md).

+- You need a local copy of product and customer data. The [Azure/aistudio-copilot-sample repository on GitHub](https://github.com/Azure/aistudio-copilot-sample/tree/main/data) contains sample retail customer and product information that's relevant for this tutorial scenario. Clone the repository or copy the files from [1-customer-info](https://github.com/Azure/aistudio-copilot-sample/tree/main/data/1-customer-info) and [3-product-info](https://github.com/Azure/aistudio-copilot-sample/tree/main/data/3-product-info).

+## Create an Azure AI project in Azure AI Studio

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

+To create an Azure AI project in Azure AI Studio, follow these steps:

+1. Sign in to [Azure AI Studio](https://ai.azure.com) and go to the **Build** page from the top menu.

+1. Select **+ New project**.

+1. Enter a name for the project.

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

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/create-project-details.png" alt-text="Screenshot of the project details page within the create project dialog." lightbox="../media/tutorials/copilot-deploy-flow/create-project-details.png":::

+ > [!NOTE]

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

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

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/create-project-resource.png" alt-text="Screenshot of the create resource page within the create project dialog." lightbox="../media/tutorials/copilot-deploy-flow/create-project-resource.png":::

+1. Select your **Azure subscription** from the dropdown. Choose a specific Azure subscription for your project for billing, access, or administrative reasons. For example, this grants users and service principals with subscription-level access to your project.

+1. Leave the **Resource group** as the default to create a new resource group. Alternatively, you can select an existing resource group from the dropdown.

+ > [!TIP]

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

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

+ > [!NOTE]

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

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

+Once a project is created, you can access the **Tools**, **Components**, and **Settings** assets in the left navigation panel.

+## Deploy a chat model

+Follow these steps to deploy an Azure OpenAI chat model for your copilot.

+1. Sign in to [Azure AI Studio](https://ai.azure.com) with credentials that have access to your Azure OpenAI resource. During or after the sign-in workflow, select the appropriate directory, Azure subscription, and Azure OpenAI resource. You should be on the Azure AI Studio **Home** page.

+1. Select **Build** from the top menu and then select **Deployments** > **Create**.

+

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/deploy-create.png" alt-text="Screenshot of the deployments page with a button to create a new project." lightbox="../media/tutorials/copilot-deploy-flow/deploy-create.png":::

+1. On the **Select a model** page, select the model you want to deploy from the **Model** dropdown. For example, select **gpt-35-turbo-16k**. Then select **Confirm**.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/deploy-gpt-35-turbo-16k.png" alt-text="Screenshot of the model selection page." lightbox="../media/tutorials/copilot-deploy-flow/deploy-gpt-35-turbo-16k.png":::

+1. On the **Deploy model** page, enter a name for your deployment, and then select **Deploy**. After the deployment is created, you see the deployment details page. Details include the date you created the deployment and the created date and version of the model you deployed.

+1. On the deployment details page from the previous step, select **Open in playground**.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/deploy-gpt-35-turbo-16k-details.png" alt-text="Screenshot of the GPT chat deployment details." lightbox="../media/tutorials/copilot-deploy-flow/deploy-gpt-35-turbo-16k-details.png":::

+For more information about deploying models, see [how to deploy models](../how-to/deploy-models.md).

+## Chat in the playground without your data

+In the [Azure AI Studio](https://ai.azure.com) playground you can observe how your model responds with and without your data. In this section, you test your model without your data. In the next section, you add your data to the model to help it better answer questions about your products.

+1. In the playground, make sure that **Chat** is selected from the **Mode** dropdown. Select your deployed GPT chat model from the **Deployment** dropdown.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/playground-chat.png" alt-text="Screenshot of the chat playground with the chat mode and model selected." lightbox="../media/tutorials/copilot-deploy-flow/playground-chat.png":::

+1. In the **System message** text box on the **Assistant setup** pane, provide this prompt to guide the assistant: "You're an AI assistant that helps people find information." You can tailor the prompt for your scenario. For more information, see [prompt samples](../how-to/models-foundation-azure-ai.md#prompt-samples).

+1. Select **Apply changes** to save your changes, and when prompted to see if you want to update the system message, select **Continue**.

+1. In the chat session pane, enter the following question: "How much do the TrailWalker hiking shoes cost", and then select the right arrow icon to send.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/chat-without-data.png" alt-text="Screenshot of the first chat question without grounding data." lightbox="../media/tutorials/copilot-deploy-flow/chat-without-data.png":::

+1. The assistant replies that it doesn't know the answer. The model doesn't have access to product information about the TrailWalker hiking shoes.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/assistant-reply-not-grounded.png" alt-text="Screenshot of the assistant's reply without grounding data." lightbox="../media/tutorials/copilot-deploy-flow/assistant-reply-not-grounded.png":::

+In the next section, you'll add your data to the model to help it answer questions about your products.

+## Add your data and try the chat model again

+You need a local copy of example product information. For more information and links to example data, see the [prerequisites](#prerequisites).

+You upload your local data files to Azure Blob storage and create an Azure AI Search index. Your data source is used to help ground the model with specific data. Grounding means that the model uses your data to help it understand the context of your question. You're not changing the deployed model itself. Your data is stored separately and securely in your Azure subscription. For more information, see [Azure OpenAI on your data](/azure/ai-services/openai/concepts/use-your-data).

+Follow these steps to add your data to the playground to help the assistant answer questions about your products.

+1. If you aren't already in the [Azure AI Studio](https://ai.azure.com) playground, select **Build** from the top menu and then select **Playground** from the collapsible left menu.

+1. On the **Assistant setup** pane, select **Add your data (preview)** > **+ Add a data source**.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/add-your-data.png" alt-text="Screenshot of the chat playground with the option to add a data source visible." lightbox="../media/tutorials/copilot-deploy-flow/add-your-data.png":::

+1. In the **Data source** page that appears, select **Upload files** from the **Select data source** dropdown.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/add-your-data-source.png" alt-text="Screenshot of the product data source selection options." lightbox="../media/tutorials/copilot-deploy-flow/add-your-data-source.png":::

+ > [!TIP]

+ > For data source options and supported file types and formats, see [Azure OpenAI on your data](/azure/ai-services/openai/concepts/use-your-data).

+1. Enter *product-info* as the name of your product information index.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/add-your-data-source-details.png" alt-text="Screenshot of the resources and information required to upload files." lightbox="../media/tutorials/copilot-deploy-flow/add-your-data-source-details.png":::

+1. Select or create an Azure AI Search resource named *contoso-outdoor-search* and select the acknowledgment that connecting it incurs usage on your account.

+ > [!NOTE]

+ > You use the *product-info* index and the *contoso-outdoor-search* Azure AI Search resource in prompt flow later in this tutorial. If the names you enter differ from what's specified here, make sure to use the names you entered in the rest of the tutorial.

+1. Select the Azure subscription that contains the Azure OpenAI resource you want to use. Then select **Next**.

+1. On the **Upload files** page, select **Browse for a file** and select the files you want to upload. Select the product info files that you downloaded or created earlier. See the [prerequisites](#prerequisites). If you want to upload more than one file, do so now. You can't add more files later in the same playground session.

+1. Select **Upload** to upload the file to your Azure Blob storage account. Then select **Next** from the bottom of the page.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/add-your-data-uploaded-product-info.png" alt-text="Screenshot of the dialog to select and upload files." lightbox="../media/tutorials/copilot-deploy-flow/add-your-data-uploaded-product-info.png":::

+1. On the **Data management** page under **Search type**, select **Keyword**. This setting helps determine how the model responds to requests. Then select **Next**.

+

+ > [!NOTE]

+ > If you had added vector search on the **Select or add data source** page, then more options would be available here for an additional cost. For more information, see [Azure OpenAI on your data](/azure/ai-services/openai/concepts/use-your-data).

+

+1. Review the details you entered, and select **Save and close**. You can now chat with the model and it uses information from your data to construct the response.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/add-your-data-review-finish.png" alt-text="Screenshot of the review and finish page for adding data." lightbox="../media/tutorials/copilot-deploy-flow/add-your-data-review-finish.png":::

+1. Now on the **Assistant setup** pane, you can see that your data ingestion is in progress. Before proceeding, wait until you see the data source and index name in place of the status.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/add-your-data-ingestion-in-progress.png" alt-text="Screenshot of the chat playground with the status of data ingestion in view." lightbox="../media/tutorials/copilot-deploy-flow/add-your-data-ingestion-in-progress.png":::

+1. You can now chat with the model asking the same question as before ("How much do the TrailWalker hiking shoes cost"), and this time it uses information from your data to construct the response. You can expand the **references** button to see the data that was used.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/chat-with-data.png" alt-text="Screenshot of the assistant's reply with grounding data." lightbox="../media/tutorials/copilot-deploy-flow/chat-with-data.png":::

+## Create compute and runtime that are needed for prompt flow

+You use prompt flow to optimize the messages that are sent to the copilot's chat model. Prompt flow requires a compute instance and a runtime. If you already have a compute instance and a runtime, you can skip this section and remain in the playground.

+To create a compute instance and a runtime, follow these steps:

+1. If you don't have a compute instance, you can [create one in Azure AI Studio](../how-to/create-manage-compute.md).

+1. Then create a runtime by following the steps in [how to create a runtime](../how-to/create-manage-runtime.md).

+To complete the rest of the tutorial, make sure that your runtime is in the **Running** status. You might need to select **Refresh** to see the updated status.

+> [!IMPORTANT]

+> You're charged for compute instances while they are running. To avoid incurring unnecessary Azure costs, pause the compute instance when you're not actively working in prompt flow. For more information, see [how to start and stop compute](../how-to/create-manage-compute.md#start-or-stop-a-compute-instance).

+## Create a prompt flow from the playground

+Now that your [deployed chat model](#deploy-a-chat-model) is working in the playground [with your data](#add-your-data-and-try-the-chat-model-again), you could [deploy your copilot as a web app](deploy-chat-web-app.md#deploy-your-web-app) from the playground.

+But you might ask "How can I further customize this copilot?" You might want to add multiple data sources, compare different prompts or the performance of multiple models. A [prompt flow](../how-to/prompt-flow.md) serves as an executable workflow that streamlines the development of your LLM-based AI application. It provides a comprehensive framework for managing data flow and processing within your application.

+In this section, you learn how to transition to prompt flow from the playground. You export the playground chat environment including connections to the data that you added. Later in this tutorial, you [evaluate the flow](#evaluate-the-flow-using-a-question-and-answer-evaluation-dataset) and then [deploy the flow](#deploy-the-flow) for [consumption](#use-the-deployed-flow).

+> [!NOTE]

+> The changes made in prompt flow aren't applied backwards to update the playground environment.

+You can create a prompt flow from the playground by following these steps:

+1. If you aren't already in the [Azure AI Studio](https://ai.azure.com) playground, select **Build** from the top menu and then select **Playground** from the collapsible left menu.

+1. Select **Open in prompt flow** from the menu above the **Chat session** pane.

+1. Enter a folder name for your prompt flow. Then select **Open**. Azure AI Studio exports the playground chat environment including connections to your data to prompt flow.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/prompt-flow-from-playground.png" alt-text="Screenshot of the open in prompt flow dialog." lightbox="../media/tutorials/copilot-deploy-flow/prompt-flow-from-playground.png":::

+Within a flow, nodes take center stage, representing specific tools with unique capabilities. These nodes handle data processing, task execution, and algorithmic operations, with inputs and outputs. By connecting nodes, you establish a seamless chain of operations that guides the flow of data through your application. For more information, see [prompt flow tools](../how-to/prompt-flow.md#prompt-flow-tools).

+To facilitate node configuration and fine-tuning, a visual representation of the workflow structure is provided through a DAG (Directed Acyclic Graph) graph. This graph showcases the connectivity and dependencies between nodes, providing a clear overview of the entire workflow. The nodes in the graph shown here are representative of the playground chat experience that you exported to prompt flow.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/prompt-flow-overview-graph.png" alt-text="Screenshot of the default graph exported from the playground to prompt flow." lightbox="../media/tutorials/copilot-deploy-flow/prompt-flow-overview-graph.png":::

+Nodes can be added, updated, rearranged, or removed. The nodes in your flow at this point include:

+- **DetermineIntent**: This node determines the intent of the user's query. It uses the system prompt to determine the intent. You can edit the system prompt to provide scenario-specific few-shot examples.

+- **ExtractIntent**: This node formats the output of the **DetermineIntent** node and sends it to the **RetrieveDocuments** node.

+- **RetrieveDocuments**: This node searches for top documents related to the query. This node uses the search type and any parameters you pre-configured in playground.

+- **FormatRetrievedDocuments**: This node formats the output of the **RetrieveDocuments** node and sends it to the **DetermineReply** node.

+- **DetermineReply**: This node contains an extensive system prompt, which asks the LLM to respond using the retrieved documents only. There are two inputs:

+ - The **RetrieveDocuments** node provides the top retrieved documents.

+ - The **FormatConversation** node provides the formatted conversation history including the latest query.

+The **FormatReply** node formats the output of the **DetermineReply** node.

+In prompt flow, you should also see:

+- **Save**: You can save your prompt flow at any time by selecting **Save** from the top menu. Be sure to save your prompt flow periodically as you make changes in this tutorial.

+- **Runtime**: The runtime that you created [earlier in this tutorial](#create-compute-and-runtime-that-are-needed-for-prompt-flow). You can start and stop runtimes and compute instances via **Settings** in the left menu. To work in prompt flow, make sure that your runtime is in the **Running** status.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/prompt-flow-overview.png" alt-text="Screenshot of the prompt flow editor and surrounding menus." lightbox="../media/tutorials/copilot-deploy-flow/prompt-flow-overview.png":::

+- **Tools**: You can return to the prompt flow anytime by selecting **Prompt flow** from **Tools** in the left menu. Then select the prompt flow folder that you created earlier (not the sample flow).

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/prompt-flow-return.png" alt-text="Screenshot of the list of your prompt flows." lightbox="../media/tutorials/copilot-deploy-flow/prompt-flow-return.png":::

+## Customize prompt flow with multiple data sources

+Earlier in the [Azure AI Studio](https://ai.azure.com) playground, you [added your data](#add-your-data-and-try-the-chat-model-again) to create one search index that contained product data for the Contoso copilot. So far, users can only inquire about products with questions such as "How much do the TrailWalker hiking shoes cost?". But they can't get answers to questions such as "How many TrailWalker hiking shoes did Daniel Wilson buy?" To enable this scenario, we add another index with customer information to the flow.

+### Create the customer info index

+You need a local copy of example customer information. For more information and links to example data, see the [prerequisites](#prerequisites).

+Follow these instructions on how to create a new index:

+1. Select **Index** from the left menu. Then select **+ New index**.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/add-index-new.png" alt-text="Screenshot of the indexes page with the button to create a new index." lightbox="../media/tutorials/copilot-deploy-flow/add-index-new.png":::

+ You're taken to the **Create an index** wizard.

+1. On the Source data page, select **Upload folder** from the **Upload** dropdown. Select the customer info files that you downloaded or created earlier. See the [prerequisites](#prerequisites).

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/add-index-dataset-upload-folder.png" alt-text="Screenshot of the customer data source selection options." lightbox="../media/tutorials/copilot-deploy-flow/add-index-dataset-upload-folder.png":::

+1. Select **Next** at the bottom of the page.

+1. Select the same Azure AI Search resource (*contoso-outdoor-search*) that you used for your product info index (*product-info*). Then select **Next**.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/add-index-storage.png" alt-text="Screenshot of the selected Azure AI Search resource." lightbox="../media/tutorials/copilot-deploy-flow/add-index-storage.png":::

+1. Select **Hybrid + Semantic (Recommended)** for the **Search type**. This type should be selected by default.

+1. Select *Default_AzureOpenAI* from the **Azure OpenAI resource** dropdown. Select the checkbox to acknowledge that an Azure OpenAI embedding model will be deployed if it's not already. Then select **Next**.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/add-index-search-settings.png" alt-text="Screenshot of index search type options." lightbox="../media/tutorials/copilot-deploy-flow/add-index-search-settings.png":::

+ > [!NOTE]

+ > The embedding model is listed with other model deployments in the **Deployments** page.

+1. Enter **customer-info** for the index name. Then select **Next**.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/add-index-settings.png" alt-text="Screenshot of the index name and virtual machine options." lightbox="../media/tutorials/copilot-deploy-flow/add-index-settings.png":::

+1. Review the details you entered, and select **Create**.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/add-index-review.png" alt-text="Screenshot of the review and finish index creation page." lightbox="../media/tutorials/copilot-deploy-flow/add-index-review.png":::

+ > [!NOTE]

+ > You use the *customer-info* index and the *contoso-outdoor-search* Azure AI Search resource in prompt flow later in this tutorial. If the names you enter differ from what's specified here, make sure to use the names you entered in the rest of the tutorial.

+1. You're taken to the index details page where you can see the status of your index creation

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/add-index-created-details.png" alt-text="Screenshot of the customer info index details." lightbox="../media/tutorials/copilot-deploy-flow/add-index-created-details.png":::

+For more information on how to create an index, see [Create an index](../how-to/index-add.md).

+### Add customer information to the flow

+After you're done creating your index, return to your prompt flow and follow these steps to add the customer info to the flow:

+1. Select the **RetrieveDocuments** node from the graph and rename it **RetrieveProductInfo**. Now the retrieve product info node can be distinguished from the retrieve customer info node that you add to the flow.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/node-rename-retrieve-product-info.png" alt-text="Screenshot of the prompt flow node for retrieving product info." lightbox="../media/tutorials/copilot-deploy-flow/node-rename-retrieve-product-info.png":::

+1. Select **+ Python** from the top menu to create a new [Python node](../how-to/prompt-flow-tools/python-tool.md) that's used to retrieve customer information.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/node-new-retrieve-customer-info.png" alt-text="Screenshot of the prompt flow node for retrieving customer info." lightbox="../media/tutorials/copilot-deploy-flow/node-new-retrieve-customer-info.png":::

+1. Name the node **RetrieveCustomerInfo** and select **Add**.

+1. Copy and paste the Python code from the **RetrieveProductInfo** node into the **RetrieveCustomerInfo** node to replace all of the default code.

+1. Select the **Validate and parse input** button to validate the inputs for the **RetrieveCustomerInfo** node. If the inputs are valid, prompt flow parses the inputs and creates the necessary variables for you to use in your code.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/customer-info-validate-parse.png" alt-text="Screenshot of the validate and parse input button." lightbox="../media/tutorials/copilot-deploy-flow/customer-info-validate-parse.png":::

+1. Edit the **RetrieveCustomerInfo** inputs that prompt flow parsed for you so that it can connect to your *customer-info* index.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/customer-info-edit-inputs.png" alt-text="Screenshot of inputs to edit in the retrieve customer info node." lightbox="../media/tutorials/copilot-deploy-flow/customer-info-edit-inputs.png":::

+ > [!NOTE]

+ > The graph is updated immediately after you set the **queries** input value to **ExtractIntent.output.search_intents**. In the graph you can see that **RetrieveCustomerInfo** gets inputs from **ExtractIntent**.

+ The inputs are case sensitive, so be sure they match these values exactly:

+

+ | Name | Type | Value |

+ |-|-|--|

+ | **embeddingModelConnection** | Azure OpenAI | *Default_AzureOpenAI* |

+ | **embeddingModelName** | string | *None* |

+ | **indexName** | string | *customer-info* |

+ | **queries** | string | *${ExtractIntent.output.search_intents}* |

+ | **queryType** | string | *simple* |

+ | **searchConnection** | Cognitive search | *contoso-outdoor-search* |

+ | **semanticConfiguration** | string | *None* |

+ | **topK** | int | *5* |

+1. Select **Save** from the top menu to save your changes.

+### Format the retrieved documents to output

+Now that you have both the product and customer info in your prompt flow, you format the retrieved documents so that the large language model can use them.

+1. Select the **FormatRetrievedDocuments** node from the graph.

+1. Copy and paste the following Python code to replace all contents in the **FormatRetrievedDocuments** code block.

+ ```python

+ from promptflow import tool

+

+ @tool

+ def format_retrieved_documents(docs1: object, docs2: object, maxTokens: int) -> str:

+ formattedDocs = []

+ strResult = ""

+ docs = [val for pair in zip(docs1, docs2) for val in pair]

+ for index, doc in enumerate(docs):

+ formattedDocs.append({

+ f"[doc{index}]": {

+ "title": doc['title'],

+ "content": doc['content']

+ }

+ })

+ formattedResult = { "retrieved_documents": formattedDocs }

+ nextStrResult = str(formattedResult)

+ if (estimate_tokens(nextStrResult) > maxTokens):

+ break

+ strResult = nextStrResult

+

+ return {

+ "combined_docs": docs,

+ "strResult": strResult

+ }

+

+ def estimate_tokens(text: str) -> int:

+ return (len(text) + 2) / 3

+ ```

+1. Select the **Validate and parse input** button to validate the inputs for the **FormatRetrievedDocuments** node. If the inputs are valid, prompt flow parses the inputs and creates the necessary variables for you to use in your code.

+1. Edit the **FormatRetrievedDocuments** inputs that prompt flow parsed for you so that it can extract product and customer info from the **RetrieveProductInfo** and **RetrieveCustomerInfo** nodes.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/format-retrieved-documents-edit-inputs.png" alt-text="Screenshot of inputs to edit in the format retrieved documents node." lightbox="../media/tutorials/copilot-deploy-flow/format-retrieved-documents-edit-inputs.png":::

+ The inputs are case sensitive, so be sure they match these values exactly:

+

+ | Name | Type | Value |

+ |-|-|--|

+ | **docs1** | object | *${RetrieveProductInfo.output}* |

+ | **docs2** | object | *${RetrieveCustomerInfo.output}* |

+ | **maxTokens** | int | *5000* |

+1. Select the **DetermineReply** node from the graph.

+1. Set the **documentation** input to *${FormatRetrievedDocuments.output.strResult}*.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/determine-reply-edit-inputs.png" alt-text="Screenshot of editing the documentation input value in the determine reply node." lightbox="../media/tutorials/copilot-deploy-flow/determine-reply-edit-inputs.png":::

+1. Select the **outputs** node from the graph.

+1. Set the **fetched_docs** input to *${FormatRetrievedDocuments.output.combined_docs}*.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/outputs-edit.png" alt-text="Screenshot of editing the fetched_docs input value in the outputs node." lightbox="../media/tutorials/copilot-deploy-flow/outputs-edit.png":::

+1. Select **Save** from the top menu to save your changes.

+### Chat in prompt flow with product and customer info

+By now you have both the product and customer info in prompt flow. You can chat with the model in prompt flow and get answers to questions such as "How many TrailWalker hiking shoes did Daniel Wilson buy?" Before proceeding to a more formal evaluation, you can optionally chat with the model to see how it responds to your questions.

+1. Select **Chat** from the top menu in prompt flow to try chat.

+1. Enter "How many TrailWalker hiking shoes did Daniel Wilson buy?" and then select the right arrow icon to send.

+1. The response is what you expect. The model uses the customer info to answer the question.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/chat-with-data-customer.png" alt-text="Screenshot of the assistant's reply with product and customer grounding data." lightbox="../media/tutorials/copilot-deploy-flow/chat-with-data-customer.png":::

+## Evaluate the flow using a question and answer evaluation dataset

+In [Azure AI Studio](https://ai.azure.com), you want to evaluate the flow before you [deploy the flow](#deploy-the-flow) for [consumption](#use-the-deployed-flow).

+In this section, you use the built-in evaluation to evaluate your flow with a question and answer evaluation dataset. The built-in evaluation uses AI-assisted metrics to evaluate your flow: groundedness, relevance, and retrieval score. For more information, see [built-in evaluation metrics](../concepts/evaluation-metrics-built-in.md).

+### Create an evaluation

+You need a question and answer evaluation dataset that contains questions and answers that are relevant to your scenario. Create a new file locally named **qa-evaluation.jsonl**. Copy and paste the following questions and answers (`"truth"`) into the file.

+```json

+{"question": "What color is the CozyNights Sleeping Bag?", "truth": "Red"}

+{"question": "When did Daniel Wilson order the BaseCamp Folding Table?", "truth": "May 7th, 2023"}

+{"question": "How much do TrailWalker Hiking Shoes cost? ", "truth": "$110"}

+{"question": "What kind of tent did Sarah Lee buy?", "truth": "SkyView 2 person tent"}

+{"question": "What is Melissa Davis's phone number?", "truth": "555-333-4444"}

+{"question": "What is the proper care for trailwalker hiking shoes?", "truth": "After each use, remove any dirt or debris by brushing or wiping the shoes with a damp cloth."}

+{"question": "Does TrailMaster Tent come with a warranty?", "truth": "2 years"}

+{"question": "How much did David Kim spend on the TrailLite Daypack?", "truth": "$240"}

+{"question": "What items did Amanda Perez purchase?", "truth": "TrailMaster X4 Tent, TrekReady Hiking Boots (quantity 3), CozyNights Sleeping Bag, TrailBlaze Hiking Pants, RainGuard Hiking Jacket, and CompactCook Camping Stove"}

+{"question": "What is the Brand for TrekReady Hiking Boots", "truth": "TrekReady"}

+{"question": "How many items did Karen Williams buy?", "truth": "three items of the Summit Breeze Jacket"}

+{"question": "France is in Europe", "truth": "Sorry, I can only truth questions related to outdoor/camping gear and equipment"}

+```

+Now that you have your evaluation dataset, you can evaluate your flow by following these steps:

+1. Select **Evaluate** > **Built-in evaluation** from the top menu in prompt flow.

+

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/evaluate-built-in-evaluation.png" alt-text="Screenshot of the option to create a built-in evaluation from prompt flow." lightbox="../media/tutorials/copilot-deploy-flow/evaluate-built-in-evaluation.png":::

+ You're taken to the **Create a new evaluation** wizard.

+1. Enter a name for your evaluation and select a runtime.

+1. Select **Question and answer pairs with retrieval-augmented generation** from the scenario options.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/evaluate-basic-scenario.png" alt-text="Screenshot of selecting an evaluation scenario." lightbox="../media/tutorials/copilot-deploy-flow/evaluate-basic-scenario.png":::

+1. Select the flow to evaluate. In this example, select *Contoso outdoor flow* or whatever you named your flow. Then select **Next**.

+1. Select the metrics you want to use to evaluate your flow. In this example, select **Groundedness**, **Relevance**, and **Retrieval score**.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/evaluate-metrics.png" alt-text="Screenshot of selecting evaluation metrics." lightbox="../media/tutorials/copilot-deploy-flow/evaluate-metrics.png":::

+1. Select a model to use for evaluation. In this example, select **gpt-35-turbo-16k**. Then select **Next**.

+ > [!NOTE]

+ > Evaluation with AI-assisted metrics needs to call another GPT model to do the calculation. For best performance, use a GPT-4 or gpt-35-turbo-16k model. If you didn't previously deploy a GPT-4 or gpt-35-turbo-16k model, you can deploy another model by following the steps in [Deploy a chat model](#deploy-a-chat-model). Then return to this step and select the model you deployed.

+1. Select **Add new dataset**. Then select **Next**.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/evaluate-add-dataset.png" alt-text="Screenshot of the option to use a new or existing dataset." lightbox="../media/tutorials/copilot-deploy-flow/evaluate-add-dataset.png":::

+1. Select **Upload files**, browse files, and select the **qa-evaluation.jsonl** file that you created earlier.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/evaluate-upload-files.png" alt-text="Screenshot of the dataset upload files button." lightbox="../media/tutorials/copilot-deploy-flow/evaluate-upload-files.png":::

+1. After the file is uploaded, you need to map the properties from the file (data source) to the evaluation properties. Enter the following values for each data source property:

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/evaluate-map-data-source.png" alt-text="Screenshot of the evaluation dataset mapping." lightbox="../media/tutorials/copilot-deploy-flow/evaluate-map-data-source.png":::

+ | Name | Description | Type | Data source |

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

+ | **chat_history** | The chat history | list | *${data.chat_history}* |

+ | **query** | The query | string | *${data.question}* |

+ | **question** | A query seeking specific information | string | *${data.question}* |

+ | **answer** | The response to question generated by the model as answer | string | ${run.outputs.reply} |

+ | **documents** | String with context from retrieved documents | string | ${run.outputs.fetched_docs} |

+1. Select **Next**.

+1. Review the evaluation details and then select **Submit**.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/evaluate-review-finish.png" alt-text="Screenshot of the review and finish page within the create evaluation dialog." lightbox="../media/tutorials/copilot-deploy-flow/evaluate-review-finish.png":::

+ You're taken to the **Metric evaluations** page.

+### View the evaluation status and results

+Now you can view the evaluation status and results by following these steps:

+1. After you [create an evaluation](#create-an-evaluation), if you aren't there already go to **Build** > **Evaluation**. On the **Metric evaluations** page, you can see the evaluation status and the metrics that you selected. You might need to select **Refresh** after a couple of minutes to see the **Completed** status.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/evaluate-status-completed.png" alt-text="Screenshot of the metric evaluations page." lightbox="../media/tutorials/copilot-deploy-flow/evaluate-status-completed.png":::

+ > [!TIP]

+ > Once the evaluation is in **Completed** status, you don't need runtime or compute to complete the rest of this tutorial. You can stop your compute instance to avoid incurring unnecessary Azure costs. For more information, see [how to start and stop compute](../how-to/create-manage-compute.md#start-or-stop-a-compute-instance).

+1. Select the name of the evaluation that completed first (*contoso-evaluate-from-flow_variant_0*) to see the evaluation details with the columns that you mapped earlier.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/evaluate-view-results-detailed.png" alt-text="Screenshot of the detailed metrics results page." lightbox="../media/tutorials/copilot-deploy-flow/evaluate-view-results-detailed.png":::

+1. Select the name of the evaluation that completed second (*evaluation_contoso-evaluate-from-flow_variant_0*) to see the evaluation metrics: **Groundedness**, **Relevance**, and **Retrieval score**.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/evaluate-view-results-metrics.png" alt-text="Screenshot of the average metrics scores." lightbox="../media/tutorials/copilot-deploy-flow/evaluate-view-results-metrics.png":::

+For more information, see [view evaluation results](../how-to/evaluate-flow-results.md).

+## Deploy the flow

+Now that you [built a flow](#create-a-prompt-flow-from-the-playground) and completed a metrics-based [evaluation](#evaluate-the-flow-using-a-question-and-answer-evaluation-dataset), it's time to create your online endpoint for real-time inference. That means you can use the deployed flow to answer questions in real time.

+Follow these steps to deploy a prompt flow as an online endpoint from [Azure AI Studio](https://ai.azure.com).

+1. Have a prompt flow ready for deployment. If you don't have one, see [how to build a prompt flow](../how-to/flow-develop.md).

+1. Optional: Select **Chat** to test if the flow is working correctly. Testing your flow before deployment is recommended best practice.

+1. Select **Deploy** on the flow editor.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/deploy-from-flow.png" alt-text="Screenshot of the deploy button from a prompt flow editor." lightbox = "../media/tutorials/copilot-deploy-flow/deploy-from-flow.png":::

+1. Provide the requested information on the **Basic Settings** page in the deployment wizard.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/deploy-basic-settings.png" alt-text="Screenshot of the basic settings page in the deployment wizard." lightbox = "../media/tutorials/copilot-deploy-flow/deploy-basic-settings.png":::

+1. Select **Next** to proceed to the advanced settings pages.

+1. On the **Advanced settings - Endpoint** page, leave the default settings and select **Next**.

+1. On the **Advanced settings - Deployment** page, leave the default settings and select **Next**.

+1. On the **Advanced settings - Outputs & connections** page, make sure all outputs are selected under **Included in endpoint response**.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/deploy-advanced-outputs-connections.png" alt-text="Screenshot of the advanced settings page in the deployment wizard." lightbox = "../media/tutorials/copilot-deploy-flow/deploy-advanced-outputs-connections.png":::

+1. Select **Review + Create** to review the settings and create the deployment.

+1. Select **Create** to deploy the prompt flow.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/deploy-review-create.png" alt-text="Screenshot of the review prompt flow deployment settings page." lightbox = "../media/tutorials/copilot-deploy-flow/deploy-review-create.png":::

+For more information, see [how to deploy a flow](../how-to/flow-deploy.md).

+## Use the deployed flow

+Your copilot application can use the deployed prompt flow to answer questions in real time. You can use the REST endpoint or the SDK to use the deployed flow.

+1. To view the status of your deployment in [Azure AI Studio](https://ai.azure.com), select **Deployments** from the left navigation. Once the deployment is created successfully, you can select the deployment to view the details.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/deployments-state-updating.png" alt-text="Screenshot of the prompt flow deployment state in progress." lightbox = "../media/tutorials/copilot-deploy-flow/deployments-state-updating.png":::

+ > [!NOTE]

+ > If you see a message that says "Currently this endpoint has no deployments" or the **State** is still *Updating*, you might need to select **Refresh** after a couple of minutes to see the deployment.

+1. Optionally, the details page is where you can change the authentication type or enable monitoring.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/deploy-authentication-monitoring.png" alt-text="Screenshot of the prompt flow deployment details page." lightbox = "../media/tutorials/copilot-deploy-flow/deploy-authentication-monitoring.png":::

+1. Select the **Consume** tab. You can see code samples and the REST endpoint for your copilot application to use the deployed flow.

+ :::image type="content" source="../media/tutorials/copilot-deploy-flow/deployments-score-url-samples.png" alt-text="Screenshot of the prompt flow deployment endpoint and code samples." lightbox = "../media/tutorials/copilot-deploy-flow/deployments-score-url-samples.png":::

+## Clean up resources

+To avoid incurring unnecessary Azure costs, you should delete the resources you created in this quickstart if they're no longer needed. To manage resources, you can use the [Azure portal](https://portal.azure.com?azure-portal=true).

+You can also [stop or delete your compute instance](../how-to/create-manage-compute.md#start-or-stop-a-compute-instance) in [Azure AI Studio](https://ai.azure.com).

+## Next steps

+* Learn more about [prompt flow](../how-to/prompt-flow.md).

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

+* [Get started building a sample copilot application with the SDK](https://github.com/azure/aistudio-copilot-sample)

+An important practice that you should include as part of your migration process is remembering to follow commonly used deployment and testing patterns. Testing your application before deployment is an important step to ensure its quality, functionality, and compatibility with the target environment. It can help you identify and fix any errors, bugs, or issues that might affect the performance, security, or usability of the application or underlying infrastructure.

+ Title: Set up advanced Ingress configurations on Azure Kubernetes Service

+description: Understand the advanced configuration options that are supported with the application routing add-on for Azure Kubernetes Service.

+# Set up advanced Ingress configurations with the application routing add-on

+This article shows you how to set up an advanced Ingress configuration to encrypt the traffic with SSL/TLS certificates stored in an Azure Key Vault, and use Azure DNS to manage DNS zones.

+* [Configure custom ingress configurations][custom-ingress-configurations] shows how to create an advanced Ingress configuration to encrypt the traffic and use Azure DNS to manage DNS zones.

+ Title: Auto-upgrade Node OS Images

+description: Learn how to choose an upgrade channel that best supports your needs for cluster's node OS security and maintenance.

+# Auto-upgrade node OS images

+AKS provides multiple auto-upgrade channels dedicated to timely node-level OS security updates. This channel is different from cluster-level Kubernetes version upgrades and supersedes it.

+## Interactions between node OS auto-upgrade and cluster auto-upgrade

+Node-level OS security updates are released at a faster rate than Kubernetes patch or minor version updates. The node OS auto-upgrade channel grants you flexibility and enables a customized strategy for node-level OS security updates. Then, you can choose a separate plan for cluster-level Kubernetes version [auto-upgrades][Autoupgrade].

+It's best to use both cluster-level [auto-upgrades][Autoupgrade] and the node OS auto-upgrade channel together. Scheduling can be fine-tuned by applying two separate sets of [maintenance windows][planned-maintenance] - `aksManagedAutoUpgradeSchedule` for the cluster [auto-upgrade][Autoupgrade] channel and `aksManagedNodeOSUpgradeSchedule` for the node OS auto-upgrade channel.

+## Channels for node OS image upgrades

+The selected channel determines the timing of upgrades. When making changes to node OS auto-upgrade channels, allow up to 24 hours for the changes to take effect.

+> [!NOTE]

+> Node OS image auto-upgrade won't affect the cluster's Kubernetes version. It only works for a cluster in a [supported version][supported].

+The following upgrade channels are available. You're allowed to choose one of these options:

+|Channel|Description|OS-specific behavior|

+|||

+| `None`| Your nodes don't have security updates applied automatically. This means you're solely responsible for your security updates.|N/A|

+| `Unmanaged`|OS updates are applied automatically through the OS built-in patching infrastructure. Newly allocated machines are unpatched initially. The OS's infrastructure patches them at some point.|Ubuntu and Azure Linux (CPU node pools) apply security patches through unattended upgrade/dnf-automatic roughly once per day around 06:00 UTC. Windows doesn't automatically apply security patches, so this option behaves equivalently to `None`.|

+| `SecurityPatch`|This channel is in preview and requires enabling the feature flag `NodeOsUpgradeChannelPreview`. Refer to the prerequisites section for details. AKS regularly updates the node's virtual hard disk (VHD) with patches from the image maintainer labeled "security only." There might be disruptions when the security patches are applied to the nodes. When the patches are applied, the VHD is updated and existing machines are upgraded to that VHD, honoring maintenance windows and surge settings. This option incurs the extra cost of hosting the VHDs in your node resource group. If you use this channel, Linux [unattended upgrades][unattended-upgrades] are disabled by default.|Azure Linux doesn't support this channel on GPU-enabled VMs. `SecurityPatch` works on patch versions that are deprecated, so long as the minor Kubernetes version is still supported.|

+| `NodeImage`|AKS updates the nodes with a newly patched VHD containing security fixes and bug fixes on a weekly cadence. The update to the new VHD is disruptive, following maintenance windows and surge settings. No extra VHD cost is incurred when choosing this option. If you use this channel, Linux [unattended upgrades][unattended-upgrades] are disabled by default. Node image upgrades support patch versions that are deprecated, so long as the minor Kubernetes version is still supported.|

+To set the node OS auto-upgrade channel when creating a cluster, use the *node-os-upgrade-channel* parameter, similar to the following example.

+```azurecli-interactive

+az aks create --resource-group myResourceGroup --name myAKSCluster --node-os-upgrade-channel SecurityPatch

+```

+To set the node os auto-upgrade channel on existing cluster, update the *node-os-upgrade-channel* parameter, similar to the following example.

+```azurecli-interactive

+az aks update --resource-group myResourceGroup --name myAKSCluster --node-os-upgrade-channel SecurityPatch

+```

+## Update ownership and schedule

+The default cadence means there's no planned maintenance window applied.

+|Channel|Updates Ownership|Default cadence|

+|||

+| `Unmanaged`|OS driven security updates. AKS has no control over these updates.|Nightly around 6AM UTC for Ubuntu and Azure Linux. Monthly for Windows.|

+| `SecurityPatch`|AKS|Weekly.|

+| `NodeImage`|AKS|Weekly.|

+## SecurityPatch channel requirements

+To use the `SecurityPatch` channel, your cluster must support these requirements.

+- Must be using API version `11-02-preview` or later

+- If using Azure CLI, the `aks-preview` CLI extension version `0.5.127` or later must be installed

+- The `NodeOsUpgradeChannelPreview` feature flag must be enabled on your subscription

+### Register NodeOsUpgradeChannelPreview

+Register the `NodeOsUpgradeChannelPreview` feature flag by using the [az feature register][az-feature-register] command, as shown in the following example:

+```azurecli-interactive

+az feature register --namespace "Microsoft.ContainerService" --name "NodeOsUpgradeChannelPreview"

+```

+It takes a few minutes for the status to show *Registered*. Verify the registration status by using the [az feature show][az-feature-show] command:

+```azurecli-interactive

+az feature show --namespace "Microsoft.ContainerService" --name "NodeOsUpgradeChannelPreview"

+```

+When the status reflects *Registered*, refresh the registration of the *Microsoft.ContainerService* resource provider by using the [az provider register][az-provider-register] command:

+```azurecli-interactive

+az provider register --namespace Microsoft.ContainerService

+```

+## Node channel known bugs

+- Currently, when you set the [cluster auto-upgrade channel][Autoupgrade] to `node-image`, it also automatically sets the node OS auto-upgrade channel to `NodeImage`. You can't change node OS auto-upgrade channel value if your cluster auto-upgrade channel is `node-image`. In order to set the node OS auto-upgrade channel value, check the [cluster auto-upgrade channel][Autoupgrade] value isn't `node-image`.

+- The `SecurityPatch` channel isn't supported on Windows OS node pools.

+

+ > [!NOTE]

+ > By default, any new cluster created with an API version of `06-01-2022` or later will set the node OS auto-upgrade channel value to `NodeImage`. Any existing clusters created with an API version earlier than `06-01-2022` will have the node OS auto-upgrade channel value set to `None` by default.

+## Node OS planned maintenance windows

+Planned maintenance for the node OS auto-upgrade starts at your specified maintenance window.

+> [!NOTE]

+> To ensure proper functionality, use a maintenance window of four hours or more.

+For more information on Planned Maintenance, see [Use Planned Maintenance to schedule maintenance windows for your Azure Kubernetes Service (AKS) cluster][planned-maintenance].

+## Node OS auto-upgrades FAQ

+* How can I check the current nodeOsUpgradeChannel value on a cluster?

+Run the `az aks show` command and check the "autoUpgradeProfile" to determine what value the `nodeOsUpgradeChannel` is set to:

+```azurecli-interactive

+az aks show --resource-group myResourceGroup --name myAKSCluster --query "autoUpgradeProfile"

+```

+* How can I monitor the status of node OS auto-upgrades?

+To view the status of your node OS auto upgrades, look up [activity logs][monitor-aks] on your cluster. You can also look up specific upgrade-related events as mentioned in [Upgrade an AKS cluster][aks-upgrade]. AKS also emits upgrade-related Event Grid events. To learn more, see [AKS as an Event Grid source][aks-eventgrid].

+* Can I change the node OS auto-upgrade channel value if my cluster auto-upgrade channel is set to `node-image` ?

+ No. Currently, when you set the [cluster auto-upgrade channel][Autoupgrade] to `node-image`, it also automatically sets the node OS auto-upgrade channel to `NodeImage`. You can't change the node OS auto-upgrade channel value if your cluster auto-upgrade channel is `node-image`. In order to be able to change the node OS auto-upgrade channel values, make sure the [cluster auto-upgrade channel][Autoupgrade] isn't `node-image`.

+<!-- LINKS -->

+[planned-maintenance]: planned-maintenance.md

+[release-tracker]: release-tracker.md

+[az-provider-register]: /cli/azure/provider#az-provider-register

+[az-feature-register]: /cli/azure/feature#az-feature-register

+[az-feature-show]: /cli/azure/feature#az-feature-show

+[upgrade-aks-cluster]: upgrade-cluster.md

+[unattended-upgrades]: https://help.ubuntu.com/community/AutomaticSecurityUpdates

+[Autoupgrade]: auto-upgrade-cluster.md

+[kured]: node-updates-kured.md

+[supported]: ./support-policies.md

+[monitor-aks]: ./monitor-aks-reference.md

+[aks-eventgrid]: ./quickstart-event-grid.md

+[aks-upgrade]: ./upgrade-cluster.md

+## Regional availability for ARM64 node pools

+Azure CNI Overlay is currently unavailable for ARM64 node pools in the following regions:

+- East US 2

+- France Central

+- Southeast Asia

+- South Central US

+- West Europe

+- West US 3

+> [!NOTE]

+> Because Routing domain is not yet supported for ARM, CNI Overlay is not yet supported on ARM-based (ARM64) processor nodes.

+>

+The AKS product group, engineering teams, and field teams (including global black belts (GBBs)) contributed to, wrote, and grouped the following best practices and conceptual articles. Their purpose is to help cluster operators and developers better understand the concepts above and implement the appropriate features.

+An important practice that you should include as part of your application development and deployment process is remembering to follow commonly used deployment and testing patterns. Testing your application before deployment is an important step to ensure its quality, functionality, and compatibility with the target environment. It can help you identify and fix any errors, bugs, or issues that might affect the performance, security, or usability of the application or underlying infrastructure.

+* Ephemeral containers and other troubleshooting methods like `exec` into a container,

+log outputs from containers, and `stdio` (ReadStreamRequest and WriteStreamRequest) require a policy modification and redeployment.

+* Due to container image layer measurements being encoded in the security policy, we don't recommend using the `latest` tag when specifying containers.

+* Memory: The Kata-CC handler uses 2 GB memory for the UVM OS and X MB additional memory where X is the resource `limits` if specified in the YAML manifest (resulting in a 2-GB VM when no limit is given, without implicit memory for containers). The [Kata][kata-technical-documentation] handler uses 256 MB base memory for the UVM OS and X MB additional memory when resource `limits` are specified in the YAML manifest. If limits are unspecified, an implicit limit of 1,792 MB is added resulting in a 2 GB VM and 1,792 MB implicit memory for containers.

+[confidential-containers-security-policy]: ../confidential-computing/confidential-containers-aks-security-policy.md

+> [!IMPORTANT]

+> A minimum of 2 CoreDNS pod replicas per cluster is recommended. Configuring a minimum of 1 CoreDNS pod replica may result in failures during operations which require node draining, such as cluster upgrade operations.

+ Title: Enable managed identity authentication on Azure Kubernetes Service

+description: Learn how to enable Microsoft Entra ID on Azure Kubernetes Service with kubelogin and authenticate Azure users with credentials or managed roles.

+# Enable Azure managed identity authentication for Kubernetes clusters with kubelogin

+## Limitations

+The following are constraints integrating Azure managed identity authentication on AKS.

+* Integration can't be disabled once added.

+The following requirements need to be met in order to properly install the AKS addon for managed identity.

+> The step described in this section suggests an alternative authentication method compared to the normal Microsoft Entra group authentication. Use this option only in an emergency.

+If you lack administrative access to a valid Microsoft Entra group, you can follow this workaround. Sign in with an account that is a member of the [Azure Kubernetes Service Cluster Admin](../role-based-access-control/built-in-roles.md#azure-kubernetes-service-cluster-admin-role) role and grant your group or tenant admin credentials to access your cluster.

+ Also, please ensure your cluster is started when the planned maintenance window is starting. If the cluster is stopped, then its control plane is deallocated and no operations can be performed.

+ 

+* Once the previous command has succeeded, you can retry the upgrade operation.

+ ```azurecli-interactive

+ az aks upgrade --name myAKSCluster --resource-group myResourceGroup --kubernetes-version <KUBERNETES_VERSION>

+ ```

+* [Stop AKS cluster upgrades automatically on API breaking changes](./stop-cluster-upgrade-api-breaking-changes.md)

+An important practice that you should include as part of your upgrade process is remembering to follow commonly used deployment and testing patterns. Testing an upgrade in a development or test environment before deployment in production is an important step to ensure application functionality and compatibility with the target environment. It can help you identify and fix any errors, bugs, or issues that might affect the performance, security, or usability of the application or underlying infrastructure.

+You'll use the [Azure Web App task (`AzureWebApp`)](/azure/devops/pipelines/tasks/deploy/azure-rm-web-app) to deploy to Azure App Service in your pipeline. For more complicated scenarios such as needing to use XML parameters in your deploy, you can use the [Azure App Service deploy task (AzureRmWebAppDeployment)](/azure/devops/pipelines/tasks/deploy/azure-rm-web-app-deployment).

+## 1. Create a pipeline for your stack

+Learn more about [Azure Pipelines ecosystem support](/azure/devops/pipelines/ecosystems/ecosystems).

+# [Classic](#tab/classic/)

+To get started:

+1. Create a pipeline and select the **ASP.NET Core** template. This selection automatically adds the tasks required to build the code in the sample repository.

+2. Save the pipeline and queue a build to see it in action.

+ The **ASP.NET Core** pipeline template publishes the deployment ZIP file as an Azure artifact for the deployment task later.

+--

+## 2. Add the deployment task

+# [YAML](#tab/yaml/)

+1. Click the end of the YAML file, then select **Show assistant**.'

+ Alternatively, you can add the [Azure App Service deploy (AzureRmWebAppDeployment)](/azure/devops/pipelines/tasks/deploy/azure-rm-web-app-deployment) task.

+1. Choose your **Azure subscription**. Make sure to **Authorize** your connection. The authorization creates the required service connection.

+1. Select the **App type**, **App name**, and **Runtime stack** based on your App Service app. Your complete YAML should look similar to the following code.

+ azureSubscription: '<service-connection-name>'

+ appName: '<app-name>'

+ * **azureSubscription**: Name of the authorized service connection to your Azure subscription.

+ * **appName**: Name of your existing app.

+ * **package**: Fike path to the package or a folder containing your app service contents. Wildcards are supported.

+1. Create a [release pipeline](/azure/devops/pipelines/release/) by selecting **Releases** from the left menu and select **New pipeline**.

+1. Select the **Azure App Service deployment** template for your stage. This automatically adds the necessary tasks.

+ > [!NOTE]

+ > If you're deploying a Node.js app to App Service on Windows, select the **Deploy Node.js App to Azure App Service** template. The only difference between these templates is that Node.js template configures the task to generate a **web.config** file containing a parameter that starts the **iisnode** service.

+1. To link this release pipeline to the Azure artifact from the previous step, select **Add an artifact** > **Build**.

+1. In **Source (build pipeline)**, select the build pipeline you created in the previous section, then select **Add**.

+1. Save the release pipeline and create a release to see it in action.

+### Example: Deploy a .NET app

+# [YAML](#tab/yaml/)

+To deploy a .zip web package (for example, from an ASP.NET web app) to an Azure Web App, use the following snippet to deploy the build to an app.

+ azureSubscription: '<service-connection-name>'

+ appName: '<app-name>'

+For classic pipelines, it's the easiest to define build and release stages in separate pages (**Pipelines** and **Releases**, respectively). In general, you:

+- In the **Pipelines** page, build and test your app by using the template of your choice, such as **ASP.NET Core**, **Node.js with Grunt**, **Maven**, or others, and publish an artifact.

+- In the **Release** page, use the generic **Azure App Service deployment** template to deploy the artifact.

+There may be templates for specific programming languages to choose from.

+## Example: deploy to a virtual application

+By default, your deployment happens to the root application in the Azure Web App. You can deploy to a specific virtual application by using the `VirtualApplication` property of the Azure App Service deploy (`AzureRmWebAppDeployment`) task:

+* **VirtualApplication**: the name of the Virtual Application that's configured in the Azure portal. For more information, see [Configure an App Service app in the Azure portal

+By default, your deployment happens to the root application in the Azure Web App. If you want to deploy to a specific virtual application, enter its name in the **Virtual Application** property of the **Azure App Service deploy** task.

+## Example: Deploy to a slot

+ azureSubscription: '<service-connection-name>'

+ appName: '<app-name>'

+ azureSubscription: '<service-connection-name>'

+ WebAppName: '<app-name>'

+Use the option **Deploy to Slot or App Service Environment** in the **Azure Web App** task to specify the slot to deploy to. To swap the slots, use the **Azure App Service manage** task.

+## Example: Deploy to multiple web apps

+You can use [jobs](/azure/devops/pipelines/process/phases) in your YAML file to set up a pipeline of deployments. By using jobs, you can control the order of deployment to multiple web apps.

+ azureSubscription: '<service-connection-name>'

+ appName: '<staging-app-name>'

+ resourceGroupName: <group-name>

+ azureSubscription: '<service-connection-name>'

+ appName: '<production-app-name>'

+ resourceGroupName: <group-name>

+If you want to deploy to multiple web apps, add stages to your release pipeline. You can control the order of deployment. To learn more, see [Stages](/azure/devops/pipelines/process/stages).

+## Example: Make variable substitutions

+For most language stacks, [app settings](./configure-common.md?toc=%2fazure%2fapp-service%2fcontainers%2ftoc.json#configure-app-settings) and [connection strings](./configure-common.md?toc=%2fazure%2fapp-service%2fcontainers%2ftoc.json#configure-connection-strings) can be set as environment variables at runtime.

+But there are other reasons you would want to make variable substitutions to your *Web.config*. In this example, your Web.config file contains a connection string named `connectionString`. You can change its value before deploying to each web app. You can do this either by applying a Web.config transformation or by substituting variables in your Web.config file.

+The following snippet shows an example of variable substitution by using the Azure App Service Deploy (`AzureRmWebAppDeployment`) task:

+## Example: Deploy conditionally

+To do this in YAML, you can use one of the following techniques:

+ azureSubscription: '<service-connection-name>'

+ appName: '<app-name>'

+## Example: deploy using Web Deploy

+The Azure App Service deploy (`AzureRmWebAppDeployment`) task can deploy to App Service using Web Deploy.

+# [YAML](#tab/yaml/)

+```yml

+trigger:

+- main

+pool:

+ vmImage: windows-latest

+variables:

+ buildConfiguration: 'Release'

+steps:

+- script: dotnet build --configuration $(buildConfiguration)

+ displayName: 'dotnet build $(buildConfiguration)'

+- task: DotNetCoreCLI@2

+ inputs:

+ command: 'publish'

+ publishWebProjects: true

+ arguments: '--configuration $(buildConfiguration)'

+ zipAfterPublish: true

+- task: AzureRmWebAppDeployment@4

+ inputs:

+ ConnectionType: 'AzureRM'

+ azureSubscription: '<service-connection-name>'

+ appType: 'webApp'

+ WebAppName: '<app-name>'

+ packageForLinux: '$(System.DefaultWorkingDirectory)/**/*.zip'

+ enableCustomDeployment: true

+ DeploymentType: 'webDeploy'

+```

+# [Classic](#tab/classic/)

+In the release pipeline, assuming you're using the **Azure App Service deployment** template:

+1. Select the **Tasks** tab, then select **Deploy Azure App Service**. This is the `AzureRmWebAppDeployment` task.

+1. In the dialog, make sure that **Connection type** is set to **Azure Resource Manager**.

+1. In the dialog, expand **Additional Deployment Options** and select **Select deployment method**. Make sure that **Web Deploy** is selected as the deployment method.

+1. Save the release pipeline.

+> [!NOTE]

+> With the [`AzureRmWebAppDeployment@3`](/azure/devops/pipelines/tasks/reference/azure-rm-web-app-deployment-v3) and [`AzureRmWebAppDeployment@4`](/azure/devops/pipelines/tasks/reference/azure-rm-web-app-deployment-v4) tasks, you should use the **Azure Resource Manager** connection type, or `AzureRM`, when deploying with Web Deploy. It uses publishing profiles for deployment when basic authentication is enabled for your app, but it uses the more secure Entra ID authentication when [basic authentication is disabled](configure-basic-auth-disable.md).

+## Frequently asked questions

+#### What's the difference between the `AzureWebApp` and `AzureRmWebAppDeployment` tasks?

+The Azure Web App task (`AzureWebApp`) is the simplest way to deploy to an Azure Web App. By default, your deployment happens to the root application in the Azure Web App.

+The [Azure App Service Deploy task (`AzureRmWebAppDeployment`)](/azure/devops/pipelines/tasks/deploy/azure-rm-web-app-deployment) can handle more custom scenarios, such as:

+- [Modify configuration settings](#example-make-variable-substitutions) inside web packages and XML parameters files.

+- [Deploy with Web Deploy](#example-deploy-using-web-deploy), if you're used to the IIS deployment process.

+- [Deploy to virtual applications](#example-deploy-to-a-virtual-application).

+- Deploy to other app types, like Container apps, Function apps, WebJobs, or API and Mobile apps.

+> [!NOTE]

+> File transforms and variable substitution are also supported by the separate [File Transform task](/azure/devops/pipelines/tasks/utility/file-transform) for use in Azure Pipelines. You can use the File Transform task to apply file transformations and variable substitutions on any configuration and parameters files.

+#### I get the message "Invalid App Service package or folder path provided."

+In YAML pipelines, depending on your pipeline, there may be a mismatch between where your built web package is saved and where the deploy task is looking for it. For example, the `AzureWebApp` task picks up the web package for deployment. For example, the AzureWebApp task looks in `$(System.DefaultWorkingDirectory)/**/*.zip`. If the web package is deposited elsewhere, modify the value of `package`.

+#### I get the message "Publish using webdeploy options are supported only when using Windows agent."

+This error occurs in the **AzureRmWebAppDeployment** task when you configure the task to deploy using Web Deploy, but your agent isn't running Windows. Verify that your YAML has something similar to the following code:

+```yml

+pool:

+ vmImage: windows-latest

+```

+#### Web Deploy doesn't work when I disable basic authentication

+For troubleshooting information on getting Microsoft Entra ID authentication to work with the `AzureRmWebAppDeployment` task, see [I can't Web Deploy to my Azure App Service using Microsoft Entra ID authentication from my Windows agent](/azure/devops/pipelines/tasks/reference/azure-rm-web-app-deployment-v4#i-cant-web-deploy-to-my-azure-app-service-using-microsoft-entra-id-authentication-from-my-windows-agent)

+4. [GitHub Actions](#how-does-the-github-actions-build-provider-work) is the default build provider. To change the provider, select **Change provider** > **App Service Build Service** (Kudu) > **OK**.

+ If you canΓÇÖt find an organization or repository, you might need to enable more permissions on GitHub. For more information, see [Managing access to your organization's repositories](https://docs.github.com/organizations/managing-access-to-your-organizations-repositories).

+1. (Preview) Under **Authentication type**, select **User-assigned identity** for better security. For more information, see [frequently asked questions]().

+1. When **GitHub Actions** is selected as the build provider, you can select the workflow file you want by using the **Runtime stack** and **Version** dropdown lists. Azure commits this workflow file into your selected GitHub repository to handle build and deploy tasks. To see the file before saving your changes, select **Preview file**.

+ > App Service detects the [language stack setting](configure-common.md#configure-language-stack-settings) of your app and selects the most appropriate workflow template. If you choose a different template, it might deploy an app that doesn't run properly. For more information, see [How the GitHub Actions build provider works](#how-does-the-github-actions-build-provider-work).

+1. By default, the GitHub Actions workflow file is preserved in your repository, but it continues to trigger deployment to your app. To delete the file from your repository, select **Delete workflow file**.

+## Frequently asked questions

+- [How does the GitHub Actions build provider work?](#how-does-the-github-actions-build-provider-work)

+- [How do I configure continuous deployment without basic authentication?](#how-do-i-configure-continuous-deployment-without-basic-authentication)

+- [What does the user-assigned identity option do for GitHub Actions?](#what-does-the-user-assigned-identity-option-do-for-github-actions)

+- [I see "You do not have sufficient permissions on this app to assign role-based access to a managed identity and configure federated credentials." when I select the user-assigned identity option with GitHub Actions.](#i-see-you-do-not-have-sufficient-permissions-on-this-app-to-assign-role-based-access-to-a-managed-identity-and-configure-federated-credentials-when-i-select-the-user-assigned-identity-option-with-github-actions)

+- [How do I deploy from other repositories](#how-do-i-deploy-from-other-repositories)

+#### How does the GitHub Actions build provider work?

+- Instead of using a user-assigned managed identity or the publishing profile, you can also deploy by using a [service principal](deploy-github-actions.md?tabs=userlevel) in Microsoft Entra ID.

+#### How do I configure continuous deployment without basic authentication?

+To configure continuous deployment [without basic authentication](configure-basic-auth-disable.md), try using GitHub Actions with the **user-assigned identity** option.

+#### What does the user-assigned identity option do for GitHub Actions?

+When you select **user-assigned identity** under the **GitHub Actions** source, Azure creates a [user-managed identity](/en-us/entra/identity/managed-identities-azure-resources/overview#managed-identity-types) for you and [federates it with GitHub as an authorized client](/entra/workload-id/workload-identity-federation-create-trust-user-assigned-managed-identity?pivots=identity-wif-mi-methods-azp). This user-managed identity isn't shown in the **Identities** page for your app.

+This automatically created user-managed identity should be used only for the GitHub Actions deployment. Using it for other configurations isn't supported.

+#### I see "You do not have sufficient permissions on this app to assign role-based access to a managed identity and configure federated credentials." when I select the user-assigned identity option with GitHub Actions.

+To use the **user-assigned identity** option for your GitHub Actions deployment, you need the `Microsoft.Authorization/roleAssignments/write` permission on your app. By default, the **User Access Administrator** role and **Owner** role have this permission already, but the **Contributor** role doesn't.

+#### How do I deploy from other repositories

+You can quickly get started with GitHub Actions by using the App Service Deployment Center. This turn-key method automatically generates a workflow file based on your application stack and commits it to your GitHub repository in the correct directory. For more information, see [Continuous deployment to Azure App Service](deploy-continuous-deployment.md).

+You can also deploy a workflow without using the Deployment Center. To do so, you need to first generate deployment credentials.

+The recommended way to authenticate with Azure App Services for GitHub Actions is with a user-defined managed identity, and the easiest way for that is by [configuring GitHub Actions deployment directly in the portal](deploy-continuous-deployment.md) instead and selecting **User-assigned managed identity**.

+> [!NOTE]

+> Authentication using a user-assigned managed identity is currently in preview.

+Alternatively, you can authenticate with a service principal, OpenID Connect, or a publish profile.

+> [!NOTE]

+> Publish profile requires [basic authentication](configure-basic-auth-disable.md) to be enabled.

+> As of October 2020, Linux web apps needs the app setting `WEBSITE_WEBDEPLOY_USE_SCM` set to `true` **before downloading the publish profile**. This requirement will be removed in the future.

+In the previous example, replace the placeholders with your subscription ID, resource group name, and app name. The output is a JSON object with the role assignment credentials that provide access to your App Service app similar to the following JSON snippet. Copy this JSON object for later.

+1. If you don't have an existing application, register a [new Active Directory application and service principal that can access resources](../active-directory/develop/howto-create-service-principal-portal.md). Create the Active Directory application.

+ This command outputs a JSON with an `appId` that is your `client-id`. Save the value to use as the `AZURE_CLIENT_ID` GitHub secret later.

+1. Create a new role assignment by subscription and object. By default, the role assignment is tied to your default subscription. Replace `$subscriptionId` with your subscription ID, `$resourceGroupName` with your resource group name, and `$assigneeObjectId` with the generated `assignee-object-id`. Learn [how to manage Azure subscriptions with the Azure CLI](/cli/azure/manage-azure-subscriptions-azure-cli).

+ * Set the `subject`. Its value is defined by GitHub depending on your workflow:

+Check out references on Azure GitHub Actions and workflows:

+- [Actions workflows to deploy to Azure](https://github.com/Azure/actions-workflow-samples)

+- [Events that trigger workflows](https://docs.github.com/en/actions/reference/events-that-trigger-workflows)

+Retrieve and initialize [the ASP.NET Core web app template](https://github.com/Azure-Samples/quickstart-deploy-aspnet-core-app-service) for this quickstart using the following steps:

+ For instance, if an HTTPRoute has two backends specified with equal weights, and one is invalid 50 percent of the traffic must receive a 500.

+> Executing child scripts using `.\child-runbook.ps1` is not supported in PowerShell 7.1 and PowerShell 7.2

+>- PowerShell 5.1, PowerShell 7.1(preview), Python 2.7, and Python 3.8 runbooks are supported on both extension-based and agent-based Windows Hybrid Runbook Workers. For agent based workers, ensure the Windows Hybrid worker version is 7.3.12960 or above.

+>- PowerShell 7.2 and Python 3.10 (preview) runbooks are supported on extension-based Windows Hybrid Workers only. Ensure the Windows Hybrid worker extension version is 1.1.11 or above.

+>- PowerShell 5.1, PowerShell 7.1(preview), Python 2.7, Python 3.8 runbooks are supported on both extension-based and agent-based Linux Hybrid Runbook Workers. For agent-based workers, ensure the Linux Hybrid Runbook worker version is 1.7.5.0 or above.

+>- PowerShell 7.2 and Python 3.10 (preview) runbooks are supported on extension-based Linux Hybrid Workers only. Ensure the Linux Hybrid worker extension version is 1.1.11 or above.

+| [PowerShell](#powershell-runbooks) |Textual runbook based on Windows PowerShell scripting. The currently supported versions are: PowerShell 5.1 (GA), PowerShell 7.1 (preview), and PowerShell 7.2 (GA).|

+The PowerShell version is determined by the **Runtime version** specified (that is version 7.2, 7.1 (preview) or 5.1). The Azure Automation service supports the latest PowerShell runtime.

+The same Azure sandbox and Hybrid Runbook Worker can execute multiple **PowerShell** runbooks targeting different runtime versions side by side.

+> - Currently, PowerShell 7.2 runtime version is supported for both Cloud and Hybrid jobs in all Public regions except Central India, UAE Central, Israel Central, Italy North, Germany North and Gov clouds.

+> - At the time of runbook execution, if you select **Runtime Version** as **7.2**, PowerShell modules targeting 7.2 runtime version are used and if you select **Runtime Version** as **5.1**, PowerShell modules targeting 5.1 runtime version are used. This applies for PowerShell 7.1 (preview) modules and runbooks.

+> Currently, PowerShell 5.1, PowerShell 7.1 (preview) and PowerShell 7.2 are supported.

+# [PowerShell 7.2](#tab/lps72)

+> Currently, PowerShell 7.2 runtime version is supported for both Cloud and Hybrid jobs in all Public regions except Central India, UAE Central, Israel Central, Italy North, Germany North and Gov clouds.

+- For the PowerShell 7.2 runtime version, the module activities aren't extracted for the imported modules.

+- Source control integration doesn't support PowerShell 7.2. Also, PowerShell 7.2 runbooks in source control get created in Automation account as Runtime 5.1.

+- Az module 8.3.0 is installed by default. The complete list of component modules of selected Az module version is shown once Az version is configured again using Azure portal or API.

+- The imported PowerShell 7.2 module would be validated during job execution. Ensure that all dependencies for the selected module are also imported for successful job execution.

+> PowerShell 7.1 (preview) and PowerShell 7.2 do not support Workflow runbooks.

+1. Create an Azure VM or Arc-enabled server and add it to the above created Hybrid Worker Group. Use the below command to add an existing Azure VM or Arc-enabled Server to the Hybrid Worker Group. Generate a new GUID and pass it as the name of the Hybrid Worker. To fetch `vmResourceId`, go to the **Properties** tab of the VM on Azure portal.

+> This article is applicable for PowerShell 5.1; PowerShell 7.1 (preview) and PowerShell 7.2 don't support workflows.

+> [Tutorial: Create a Python 3 runbook](automation-tutorial-runbook-textual-python-3.md)

+> Snapshot support is available if you use version **7.0.0** or later of any of the following packages.

+|Solution and version |Kubernetes version |Azure Arc-enabled data services version |SQL engine version |PostgreSQL server version|

+|Red Hat OCP 4.12.30|1.25.11|1.25.0_2023-11-14|16.0.5100.7246|Not validated|

+|Hitachi Virtual Storage Software Block software-defined storage (VSSB)|1.24.12 |1.20.0_2023-06-13 |16.0.5100.7242 |14.5 (Ubuntu 20.04)|

+|Hitachi Virtual Storage Platform (VSP) |1.24.12 |1.19.0_2023-05-09 |16.0.937.6221 |14.5 (Ubuntu 20.04)|

+|[Hitachi UCP with RedHat OpenShift](https://www.hitachivantara.com/en-us/solutions/modernize-digital-core/infrastructure-modernization/hybrid-cloud-infrastructure.html) |1.23.12 |1.16.0_2023-02-14 |16.0.937.6221 |14.5 (Ubuntu 20.04)|

+Ensure that both the licensing package and SSU are downloaded for the Azure Arc-enabled server as documented at [KB5031043: Procedure to continue receiving security updates after extended support has ended on October 10, 2023](https://support.microsoft.com/topic/kb5031043-procedure-to-continue-receiving-security-updates-after-extended-support-has-ended-on-october-10-2023-c1a20132-e34c-402d-96ca-1e785ed51d45). Ensure you are following all of the networking prerequisites as recorded at [Prepare to deliver Extended Security Updates for Windows Server 2012](prepare-extended-security-updates.md?tabs=azure-cloud#networking).

+If installing the Extended Security Update enabled by Azure Arc fails with errors such as "ESU: Trying to Check IMDS Again LastError=HRESULT_FROM_WIN32(12029)" or "ESU: Trying to Check IMDS Again LastError=HRESULT_FROM_WIN32(12002)", there is a known remediation approach:

+1. Download this [intermediate CA published by Microsoft](https://www.microsoft.com/pkiops/certs/Microsoft%20Azure%20TLS%20Issuing%20CA%2001%20-%20xsign.crt).

+1. Install the downloaded certificate as Local Computer under `Intermediate Certificate Authorities\Certificates`. Use the following command to install the certificate correctly:

+ `certutil -addstore CA 'Microsoft Azure TLS Issuing CA 01 - xsign.crt'`

+1. Install security updates. If it fails, reboot the machine and install security updates again.

+If you're working with Azure Government Cloud, use the following instructions instead of those above:

+1. Download this [intermediate CA published by Microsoft](https://www.microsoft.com/pkiops/certs/Microsoft%20Azure%20TLS%20Issuing%20CA%2002%20-%20xsign.crt).

+1. Install the downloaded certificate as Local Computer under `Intermediate Certificate Authorities\Certificates`. Use the following command to install the certificate correctly:

+ `certutil -addstore CA 'Microsoft Azure TLS Issuing CA 02 - xsign.crt'`

+1. Install security updates. If it fails, reboot the machine and install security updates again.

+If you encounter the error "ESU: not eligible HRESULT_FROM_WIN32(1633)", follow these steps:

+`Remove-Item ΓÇ£$env:ProgramData\AzureConnectedMachineAgent\Certs\license.jsonΓÇ¥ -Force`

+`Restart-Service himds`

+If you have other issues receiving ESUs after successfully enrolling the server through Arc-enabled servers, or you need additional information related to issues affecting ESU deployment, see [Troubleshoot issues in ESU](/troubleshoot/windows-client/windows-7-eos-faq/troubleshoot-extended-security-updates-issues).

+When using .NET isolated functions, you have access to the start-up of your function app, which is usually in `Program.cs`. You're responsible for creating and starting your own host instance. As such, you also have direct access to the configuration pipeline for your app. With .NET Functions isolated worker process, you can much more easily add configurations, inject dependencies, and run your own middleware.

+This code requires `using Microsoft.Extensions.DependencyInjection;`.

+Before calling `Build()` on the `HostBuilder`, you should:

+- Call either `ConfigureFunctionsWebApplication()` if using [ASP.NET Core integration](#aspnet-core-integration) or `ConfigureFunctionsWorkerDefaults()` otherwise. See [HTTP trigger](#http-trigger) for details on these options.

+ - If you're writing your application using F#, some trigger and binding extensions require extra configuration here. See the setup documentation for the [Blobs extension][fsharp-blobs], the [Tables extension][fsharp-tables], and the [Cosmos DB extension][fsharp-cosmos] if you plan to use this in your app.

+- Configure any services or app configuration your project requires. See [Configuration] for details.

+ - If you are planning to use Application Insights, you need to call `AddApplicationInsightsTelemetryWorkerService()` and `ConfigureFunctionsApplicationInsights()` in the `ConfigureServices()` delegate. See [Application Insights](#application-insights) for details.

+If your project targets .NET Framework 4.8, you also need to add `FunctionsDebugger.Enable();` before creating the HostBuilder. It should be the first line of your `Main()` method. For more information, see [Debugging when targeting .NET Framework](#debugging-when-targeting-net-framework).

+The [HostBuilder] is used to build and return a fully initialized [`IHost`][IHost] instance, which you run asynchronously to start your function app.

+[fsharp-blobs]: ./functions-bindings-storage-blob.md#install-extension

+[fsharp-tables]: ./functions-bindings-storage-table.md#install-extension

+[fsharp-cosmos]: ./functions-bindings-cosmosdb-v2.md#install-extension

+| **`GetOutputBindings`** | Gets the output binding entries for the current function execution. Each entry in the result of this method is of type `OutputBindingData`. You can use the `Value` property to get or set the value as needed. |

+| **`BindInputAsync`** | Binds an input binding item for the requested `BindingMetadata` instance. For example, you can use this method when you have a function with a `BlobInput` input binding that needs to be accessed or updated by your middleware. |

+To write to an output binding, you must apply an output binding attribute to the function method, which define how to write to the bound service. The value returned by the method is written to the output binding. For example, the following example writes a string value to a message queue named `output-queue` by using an output binding:

+> [!NOTE]

+> Refer to the [Azure Functions Python developer guide](../functions-reference-python.md) for more details about how the V2 model works.

+If you're writing your application using F#, you must also configure this extension as part of the app's [startup configuration](./dotnet-isolated-process-guide.md#start-up-and-configuration). In the call to `ConfigureFunctionsWorkerDefaults()` or `ConfigureFunctionsWebApplication()`, add a delegate that takes an `IFunctionsWorkerApplication` parameter. Then within the body of that delegate, call `ConfigureCosmosDBExtension()` on the object:

+```fsharp

+let hostBuilder = new HostBuilder()

+hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->

+ appBuilder.ConfigureCosmosDBExtension() |> ignore

+) |> ignore

+```

+Add the extension to your project by installing the [Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs NuGet package], version 5.x or later.

+dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs

+If you're writing your application using F#, you must also configure this extension as part of the app's [startup configuration](./dotnet-isolated-process-guide.md#start-up-and-configuration). In the call to `ConfigureFunctionsWorkerDefaults()` or `ConfigureFunctionsWebApplication()`, add a delegate that takes an `IFunctionsWorkerApplication` parameter. Then within the body of that delegate, call `ConfigureBlobStorageExtension()` on the object:

+```fsharp

+let hostBuilder = new HostBuilder()

+hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->

+ appBuilder.ConfigureBlobStorageExtension() |> ignore

+) |> ignore

+```

+If you're writing your application using F#, you must also configure this extension as part of the app's [startup configuration](./dotnet-isolated-process-guide.md#start-up-and-configuration). In the call to `ConfigureFunctionsWorkerDefaults()` or `ConfigureFunctionsWebApplication()`, add a delegate that takes an `IFunctionsWorkerApplication` parameter. Then within the body of that delegate, call `ConfigureTablesExtension()` on the object:

+```fsharp

+let hostBuilder = new HostBuilder()

+hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->

+ appBuilder.ConfigureTablesExtension() |> ignore

+) |> ignore

+```

+In the current preview, you must deploy your functions code in a Linux container that you create. Functions maintains a set of [language-specific base images](https://mcr.microsoft.com/catalog?search=functions) that you can use to generate your containerized function apps. When you create a Functions project using [Azure Functions Core Tools](./functions-run-local.md) and include the [`--docker` option](./functions-core-tools-reference.md#func-init), Core Tools also generates a Dockerfile that you can use to create your container from the correct base image.

+ Title: 'Quickstart: Deploy an Azure Linux Container Host for an AKS cluster using Azure PowerShell'

+description: Learn how to quickly create an Azure Linux Container Host for an AKS cluster using Azure PowerShell.

+# Quickstart: Deploy an Azure Linux Container Host for an AKS cluster using Azure PowerShell

+Get started with the Azure Linux Container Host by using Azure PowerShell to deploy an Azure Linux Container Host for an AKS cluster. After installing the prerequisites, you create a resource group, create an AKS cluster, connect to the cluster, and run a sample multi-container application in the cluster.

+## Prerequisites

+- [!INCLUDE [quickstarts-free-trial-note](../../includes/quickstarts-free-trial-note.md)]

+- Use the PowerShell environment in [Azure Cloud Shell](/azure/cloud-shell/overview). For more information, see [Azure Cloud Shell Quickstart](/azure/cloud-shell/quickstart).

+ [](https://shell.azure.com)

+- If you're running PowerShell locally, install the `Az PowerShell` module and connect to your Azure account using the [`Connect-AzAccount`](/powershell/module/az.accounts/Connect-AzAccount) cmdlet. For more information about installing the Az PowerShell module, see [Install Azure PowerShell][install-azure-powershell].

+- The identity you use to create your cluster has the appropriate minimum permissions. For more details on access and identity for AKS, see [Access and identity options for Azure Kubernetes Service (AKS)](../aks/concepts-identity.md).

+## Create a resource group

+An [Azure resource group][azure-resource-group] is a logical group in which Azure resources are deployed and managed. When creating a resource group, you need to specify a location. This location is the storage location of your resource group metadata and where your resources run in Azure if you don't specify another region during resource creation.

+The following example creates resource group named *testAzureLinuxResourceGroup* in the *eastus* region.

+- Create a resource group using the [`New-AzResourceGroup`][new-azresourcegroup] cmdlet.

+ ```azurepowershell-interactive

+ New-AzResourceGroup -Name testAzureLinuxResourceGroup -Location eastus

+ ```

+ The following example output resembles successful creation of the resource group:

+ ```output

+ ResourceGroupName : testAzureLinuxResourceGroup

+ Location : eastus

+ ProvisioningState : Succeeded

+ Tags :

+ ResourceId : /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/testAzureLinuxResourceGroup

+ ```

+ > [!NOTE]

+ > The above example uses *eastus*, but Azure Linux Container Host clusters are available in all regions.

+## Create an Azure Linux Container Host cluster

+The following example creates a cluster named *testAzureLinuxCluster* with one node.

+- Create an AKS cluster using the [`New-AzAksCluster`][new-azakscluster] cmdlet with the `-NodeOsSKU` flag set to *AzureLinux*.

+ ```azurepowershell-interactive

+ New-AzAksCluster -ResourceGroupName testAzureLinuxResourceGroup -Name testAzureLinuxCluster -NodeOsSKU AzureLinux

+ ```

+ After a few minutes, the command completes and returns JSON-formatted information about the cluster.

+## Connect to the cluster

+To manage a Kubernetes cluster, use the Kubernetes command-line client, [kubectl](https://kubernetes.io/docs/reference/kubectl/kubectl/). `kubectl` is already installed if you use Azure Cloud Shell.

+1. Install `kubectl` locally using the `Install-AzAksCliTool` cmdlet.

+ ```azurepowershell-interactive

+ Install-AzAksCliTool

+ ```

+2. Configure `kubectl` to connect to your Kubernetes cluster using the [`Import-AzAksCredential`][import-azakscredential] cmdlet. This command downloads credentials and configures the Kubernetes CLI to use them.

+ ```azurepowershell-interactive

+ Import-AzAksCredential -ResourceGroupName testAzureLinuxResourceGroup -Name testAzureLinuxCluster

+ ```

+3. Verify the connection to your cluster using the [`kubectl get`][kubectl-get] command. This command returns a list of the cluster pods.

+ ```azurepowershell-interactive

+ kubectl get pods --all-namespaces

+ ```

+## Deploy the application

+A [Kubernetes manifest file](../../articles/aks/concepts-clusters-workloads.md#deployments-and-yaml-manifests) defines a cluster's desired state, such as which container images to run.

+In this quickstart, you use a manifest to create all objects needed to run the [Azure Vote application](https://github.com/Azure-Samples/azure-voting-app-redis). This manifest includes two Kubernetes deployments:

+- The sample Azure Vote Python applications.

+- A Redis instance.

+This manifest also creates two [Kubernetes Services](../../articles/aks/concepts-network.md#services):

+- An internal service for the Redis instance.

+- An external service to access the Azure Vote application from the internet.

+1. Create a file named `azure-vote.yaml` and copy in the following manifest.

+ - If you use the Azure Cloud Shell, you can create the file using `code`, `vi`, or `nano`.

+ ```yaml

+ apiVersion: apps/v1

+ kind: Deployment

+ metadata:

+ name: azure-vote-back

+ spec:

+ replicas: 1

+ selector:

+ matchLabels:

+ app: azure-vote-back

+ template:

+ metadata:

+ labels:

+ app: azure-vote-back

+ spec:

+ nodeSelector:

+ "kubernetes.io/os": linux

+ containers:

+ - name: azure-vote-back

+ image: mcr.microsoft.com/oss/bitnami/redis:6.0.8

+ env:

+ - name: ALLOW_EMPTY_PASSWORD

+ value: "yes"

+ resources:

+ requests:

+ cpu: 100m

+ memory: 128Mi

+ limits:

+ cpu: 250m

+ memory: 256Mi

+ ports:

+ - containerPort: 6379

+ name: redis

+

+ apiVersion: v1

+ kind: Service

+ metadata:

+ name: azure-vote-back

+ spec:

+ ports:

+ - port: 6379

+ selector:

+ app: azure-vote-back

+

+ apiVersion: apps/v1

+ kind: Deployment

+ metadata:

+ name: azure-vote-front

+ spec:

+ replicas: 1

+ selector:

+ matchLabels:

+ app: azure-vote-front

+ template:

+ metadata:

+ labels:

+ app: azure-vote-front

+ spec:

+ nodeSelector:

+ "kubernetes.io/os": linux

+ containers:

+ - name: azure-vote-front

+ image: mcr.microsoft.com/azuredocs/azure-vote-front:v1

+ resources:

+ requests:

+ cpu: 100m

+ memory: 128Mi

+ limits:

+ cpu: 250m

+ memory: 256Mi

+ ports:

+ - containerPort: 80

+ env:

+ - name: REDIS

+ value: "azure-vote-back"

+

+ apiVersion: v1

+ kind: Service

+ metadata:

+ name: azure-vote-front

+ spec:

+ type: LoadBalancer

+ ports:

+ - port: 80

+ selector:

+ app: azure-vote-front

+ ```

+ For a breakdown of YAML manifest files, see [Deployments and YAML manifests](../../articles/aks/concepts-clusters-workloads.md#deployments-and-yaml-manifests).

+2. Deploy the application using the [`kubectl apply`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#apply) command and specify the name of your YAML manifest:

+ ```azurepowershell-interactive

+ kubectl apply -f azure-vote.yaml

+ ```

+ The following example resembles output showing the successfully created deployments and

+ ```output

+ deployment "azure-vote-back" created

+ service "azure-vote-back" created

+ deployment "azure-vote-front" created

+ service "azure-vote-front" created

+ ```

+## Test the application

+When the application runs, a Kubernetes service exposes the application frontend to the internet. This process can take a few minutes to complete.

+1. Monitor progress using the [`kubectl get service`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#get) command with the `--watch` argument.

+ ```azurepowershell-interactive

+ kubectl get service azure-vote-front --watch

+ ```

+ The **EXTERNAL-IP** output for the `azure-vote-front` service initially shows as *pending*.

+ ```output

+ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE

+ azure-vote-front LoadBalancer 10.0.37.27 <pending> 80:30572/TCP 6s

+ ```

+2. Once the **EXTERNAL-IP** address changes from *pending* to an actual public IP address, use `CTRL-C` to stop the `kubectl` watch process. The following example output shows a valid public IP address assigned to the service:

+ ```output

+ azure-vote-front LoadBalancer 10.0.37.27 52.179.23.131 80:30572/TCP 2m

+ ```

+3. Open a web browser to the external IP address of your service to see the application in action.

+ :::image type="content" source="./media/azure-voting-application.png" alt-text="Screenshot of browsing to Azure Vote sample application.":::

+## Delete the cluster

+If you don't plan on continuing through the following tutorials, remove the created resources to avoid incurring Azure charges.

+- Remove the resource group and all related resources using the [`RemoveAzResourceGroup`][remove-azresourcegroup] cmdlet.

+ ```azurepowershell-interactive

+ Remove-AzResourceGroup -Name testAzureLinuxResourceGroup

+ ```

+## Next steps

+In this quickstart, you deployed an Azure Linux Container Host AKS cluster. To learn more about the Azure Linux Container Host and walk through a complete cluster deployment and management example, continue to the Azure Linux Container Host tutorial.

+> [!div class="nextstepaction"]

+> [Azure Linux Container Host tutorial](./tutorial-azure-linux-create-cluster.md)

+<!-- LINKS - internal -->

+[install-azure-powershell]: /powershell/azure/install-az-ps

+[azure-resource-group]: ../azure-resource-manager/management/overview.md

+[new-azresourcegroup]: /powershell/module/az.resources/new-azresourcegroup

+[new-azakscluster]: /powershell/module/az.aks/new-azakscluster

+[import-azakscredential]: /powershell/module/az.aks/import-azakscredential

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

+[remove-azresourcegroup]: /powershell/module/az.resources/remove-azresourcegroup

+> [!NOTE]

+>

+> For Azure Maps pricing information and free offering details, see [Azure Maps Pricing].

+| [Container Monitoring Solution](../containers/containers.md) | Migrate to new service called Container Insights with Azure Monitor Agent | Generally Available | [Enable Container Insights](../containers/container-insights-transition-solution.md) |

+ :::image type="content" source="media/alerts-create-new-alert-rule/alerts-rule-actions-tab.png" alt-text="Screenshot that shows the Actions tab when creating a new alert rule.":::

+ |Automatically resolve alerts (preview) |Select to make the alert stateful. When an alert is stateful, the alert is resolved when the condition is no longer met.<br> If you don't select this checkbox, metric alerts are stateless. Stateless alerts fire each time the condition is met, even if alert already fired.<br> The frequency of notifications for stateless metric alerts differs based on the alert rule's configured frequency:<br>**Alert frequency of less than 5 minutes**: While the condition continues to be met, a notification is sent somewhere between one and six minutes.<br>**Alert frequency of more than 5 minutes**: While the condition continues to be met, a notification is sent between the configured frequency and doubles the value of the frequency. For example, for an alert rule with a frequency of 15 minutes, a notification is sent somewhere between 15 to 30 minutes.|

+ - If you are querying an ADX or ARG cluster you must add **Reader role** for all data sources accessed by the query. For example, if the query is resource centric, it needs a reader role on that resources.

+1. <a name="custom-props"></a>(Optional) In the **Custom properties** section, if you've configured action groups for this alert rule, you can add your own properties to include in the alert notification payload. You can use these properties in the actions called by the action group, such as webhook, Azure function or logic app actions.

+ :::image type="content" source="media/alerts-create-new-alert-rule/alerts-rule-custom-props.png" alt-text="Screenshot that shows the custom properties section of creating a new alert rule.":::

+You can configure [System.Diagnostics.DiagnosticSource](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md) events to be sent to Application Insights as traces. First, install the [`Microsoft.ApplicationInsights.DiagnosticSourceListener`](https://www.nuget.org/packages/Microsoft.ApplicationInsights.DiagnosticSourceListener) NuGet package. Then edit the "TelemetryModules" section of the [ApplicationInsights.config](./configuration-with-applicationinsights-config.md) file.

+> [!WARNING]

+> We have recently enabled TLS 1.3 in Availability Tests. If you are seeing new error messages as a result, please ensure that clients running on Windows Server 2022 with TLS 1.3 enabled can connect to your endpoint. If you are unable to do this, you may consider temporarily disabling TLS 1.3 on your endpoint so that Availability Tests will fall back to older TLS versions.

+> For additional information, please check the [troubleshooting article](/troubleshoot/azure/azure-monitor/app-insights/troubleshoot-availability).

+Connection string and role name are the most common settings you need to get started:

+```json

+{

+ "connectionString": "...",

+ "role": {

+ "name": "my cloud role name"

+ }

+}

+```

+Connection string is required. Role name is important anytime you're sending data from different applications to the same Application Insights resource.

+If you specify a relative path, it resolves relative to the directory where `applicationinsights-agent-3.4.18.jar` is located.

+If you specify a relative path, it resolves relative to the directory where `applicationinsights-agent-3.4.18.jar` is located.

+Sampling only applies to logs inside of a request. Logs that aren't inside of a request (for example, startup logs) are always collected by default.

+If no sampling is configured, the default is now rate-limited sampling configured to capture at most

+* `objectName` is the [Object Name](https://docs.oracle.com/javase/8/docs/api/javax/management/ObjectName.html) of the `JMX MBean` that you want to collect.

+* `attribute` is the attribute name inside of the `JMX MBean` that you want to collect.

+Starting with version 3.2.0, you can set a custom dimension programmatically on your request telemetry. It ensures inheritance by dependency and log telemetry. All are captured in the context of that request.

+It automatically modifies to return:

+* Meets the configured level for the logging framework.

+* Also meets the configured level for Application Insights.

+> Don't use both a connection string and an instrumentation key. The latter one set supersedes the other, and could result in telemetry not appearing on the portal. See [missing data](#missing-data).

+To set the connection string, see [Connection string](java-standalone-config.md#connection-string).

+The connection string contains an ikey, which is a unique identifier used by the ingestion service to associate telemetry to a specific Application Insights resource. These ikey unique identifiers aren't security tokens or security keys. If you want to protect your AI resource from misuse, the ingestion endpoint provides authenticated telemetry ingestion options based on [Microsoft Entra ID](azure-ad-authentication.md#microsoft-entra-authentication-for-application-insights).

+> The Application Insights JavaScript SDK requires the connection string to be passed in during initialization and configuration. It's viewable in plain text in client browsers. There's no easy way to use the [Microsoft Entra ID-based authentication](azure-ad-authentication.md#microsoft-entra-authentication-for-application-insights) for browser telemetry. We recommend that you consider creating a separate Application Insights resource for browser telemetry if you need to secure the service telemetry.

+# example: kubectl logs prometheus-prometheus-kube-prometheus-prometheus-0 prom-remotewrite --namespace <namespace>

+Watch this video to learn how to build a hive cluster.

+> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RE5ah5O]

+The gallery lists all the saved workbooks and templates in your current environment. Select **Browse across galleries** to see the workbooks for all your resources.

+[Get started with Azure Workbooks](workbooks-getting-started.md)

+- *Throughput limit reached*

+

+ Throughput limit reached is a boolean metric that denotes the volume is hitting its QoS limits. The value 1 means that the volume has reached its maximum throughput, and throughput for this volume will be throttled. The value 0 means this limit has not yet been reached.

+

+ If the volume is hitting the throughput limit, it's not sized appropriately for the application's demands. To resolve throughput issues:

+ - Resize the volume:

+ Increase the volume size to allocate more throughput to the volume so it's not throttled.

+ - Modify the service level:

+

+ The Premium and Ultra service levels in Azure NetApp Files cater to workloads with higher throughput requirements. [Moving the volume to a capacity pool in a higher service level](dynamic-change-volume-service-level.md) automatically increases these limits for the volume.

+ - Change the workloads/application:

+ Consider repurposing the volume and delegating a different volume with a larger size and/or in a higher service level to meet your application requirements. If it's an NFS volume, consider changing mount options to reduce data flow if your application supports those changes.

+ :::image type="content" source="../media/azure-netapp-files/throughput-limit-reached.png" alt-text="Screenshot that shows Azure NetApp Files metrics a line graph demonstrating throughput limit reached." lightbox="../media/azure-netapp-files/throughput-limit-reached.png":::

+* US Gov Arizona

+* US Gov Texas

+* US Gov Virginia

+Azure NetApp Files supports three [service levels](azure-netapp-files-service-levels.md) that can be configured at capacity pool level (Standard, Premium and Ultra). Cool access is an additional service only on the Standard service level. Standard storage with cool access is supported only on capacity pools of the **auto** QoS type.

+ * 1-TiB capacity at the hot tier rate

+ * 3-TiB capacity at the cool tier rate

+ * 0.5-TiB capacity at the hot tier rate

+ * 1.5-TiB capacity at the cool tier rate

+ * 0.25-TiB capacity at the hot tier rate

+ * 0.75-TiB capacity at the cool tier rate

+| Storage cost for Day 1~7 (seven days) | 4 TiB of active data (hot tier) | `4 TiB x 1024 x 7 days x 730/30 hrs. x $0.000202/GiB/hr. = $140.93` |

+| Storage cost for Day 1~5 (five days) | 4 TiB of active data (hot tier) | `4 TiB x 1024 x 5 days x 730/30 hrs. x $0.000202/GiB/hr. = $100.67` |

+| Storage cost for Day 1~3 (three days) | 4 TiB of active data (hot tier) | `4 TiB x 1024 x 3 days x 730/30 hrs. x $0.000202/GiB/hr. = $60.40` |

+ * An auto QoS capacity pool enabled for standard storage with cool access cannot be converted to a capacity pool using manual QoS.

+* Considerations for using cool access with [cross-region replication](cross-region-replication-requirements-considerations.md) (CRR) and [cross-zone replication](cross-zone-replication-introduction.md):

+* [Standard network features is US Gov regions](azure-netapp-files-network-topologies.md#supported-regions) is now generally available (GA)

+

+ Azure NetApp Files now supports Standard network features for new volumes in US Gov Arizona, US Gov Texas, and US Gov Virginia. Standard network features provide an enhanced virtual networking experience through various features for a seamless and consistent experience with security posture of all their workloads including Azure NetApp Files.

+ Title: Azure Relay Hybrid Connections - HTTP requests in Java

+description: Write a Java console application for Azure Relay Hybrid Connections HTTP requests.

+# Get started with Relay Hybrid Connections HTTP requests in Java

+In this quickstart, you create Java sender and receiver applications that send and receive messages by using the HTTP protocol. The applications use Hybrid Connections feature of Azure Relay. To learn about Azure Relay in general, see [Azure Relay](relay-what-is-it.md).

+In this quickstart, you take the following steps:

+1. Create a Relay namespace by using the Azure portal.

+2. Create a hybrid connection in that namespace by using the Azure portal.

+3. Write a server (listener) console application to receive messages.

+4. Write a client (sender) console application to send messages.

+5. Run applications.

+## Prerequisites

+- [Java](https://www.java.com/en/). Please ensure that you are running JDK 1.8+

+- [Maven](https://maven.apache.org/install.html). Please ensure that you have Maven installed

+- [Azure Relay SDK](https://github.com/Azure/azure-relay-java). Review Java SDK

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

+## Create a namespace using the Azure portal

+## Create a hybrid connection using the Azure portal

+## Create a server application (listener)

+To listen and receive messages from the Relay, write a Java console application.

+## Create a client application (sender)

+To send messages to the Relay, you can use any HTTP client, or write a Java console application.

+## Run the applications

+1. Run the server application: from a Java command prompt or application type `java -cp <jar_dependency_path> com.example.listener.Listener.java`.

+2. Run the client application: from a Java command prompt or application type `java -cp <jar_dependency_path> com.example.sender.Sender.java`, and enter some text.

+3. Ensure that the server application console outputs the text that was entered in the client application.

+Congratulations, you have created an end-to-end Hybrid Connections application using Java!

+## Next steps

+In this quickstart, you created Java client and server applications that used HTTP to send and receive messages. The Hybrid Connections feature of Azure Relay also supports using WebSockets to send and receive messages. To learn how to use WebSockets with Azure Relay Hybrid Connections, see the [WebSockets quickstart](relay-hybrid-connections-node-get-started.md).

+In this quickstart, you used Java to create client and server applications. To learn how to write client and server applications using .NET Framework, see the [.NET WebSockets quickstart](relay-hybrid-connections-dotnet-get-started.md) or the [.NET HTTP quickstart](relay-hybrid-connections-http-requests-dotnet-get-started.md).

+- [Hybrid Connections - Java HTTP](relay-hybrid-connections-java-get-started.md)

+ If a resource group's region is temporarily unavailable, you may not be able to update resources in the resource group because the metadata is unavailable. The resources in other regions will still function as expected, but you may not be able to update them. This condition may also apply to global resources like Azure DNS, Azure DNS Private Zones, Azure Traffic Manager, and Azure Front Door. You can view which types have their metadata managed by Azure Resource Manager via the [list of types for the Azure Resource Graph resources table](../../governance/resource-graph/reference/supported-tables-resources.md#resources).

+### Resource group location alignment

+To reduce the likelihood of being impacted by region outages, if they occur, it's recommended to co-locate your resources with their resource group in the same region together.

+The resource group location is used to determine the location where Azure Resource Manager will store metadata related to all the resources within the resource group, which is then used for routing and caching. For instance, when you list your resources at the subscription or resource group scopes, Azure Resource Manager responds based off this cache.

+When the resource group's region is unavailable, Azure Resource Manager may be unable to update your resource's metadata and may block your write calls. By co-locating your resource and resource group region, you can reduce your chance of being affected by region unavailability since your resource and resource management metadata will all be stored in one region instead of multiple.

+> | workspaces | resource group | 3-33 | Alphanumerics and hyphens |

+> | workspaces / datastores | workspace | Maximum 255 characters for datastore name| Datastore name consists only of lowercase letters, digits, and underscores |

+> If you are using unit 50 or unit 100 **and** your scenario is mainly sending to small groups (group size <20) or single connection, you need to check [sending to small group](#small-group) or [sending to connection](#send-to-connection) for reference. In those scenarios there is large routing cost which is not included in the Server Load.

+>

+> The group count, group member count listed in the table are **not hard limits**. These parameter values are selected to establish a stable benchmark scenario. For example, it is OK to assign each conneciton to a distinct group. Under this configuration, the performance is close to [send to connection](#send-to-connection).

+ 1. Open [New Notebook](/azure-data-studio/notebooks/notebooks-python-kernel) connected to the Python 3 Kernel.

+> If you are using unit 50 or unit 100 **and** your scenario is mainly sending to small groups (group size <20), you need to check [sending to small group](#small-group) for reference. In those scenarios there is large routing cost which is not included in the Server Load.

+> [!NOTE]

+> The group count, group member count listed in the table are **not hard limits**. These parameter values are selected to establish a stable benchmark scenario.

+ dotnet add package Azure.Identity

+ dotnet add package Azure.Messaging.WebPubSub

+- If using DependencyInjection, install [Microsoft.Extensions.Azure](https://www.nuget.org/packages/Microsoft.Extensions.Azure) from nuget.org

+ ```bash

+ dotnet add package Microsoft.Extensions.Azure

+ ```

+

+- Immutable vault is available in all Azure public and US Government regions.

+### UserErrorContainerNotFoundForPointInTimeRestore

+**Error code**: `UserErrorContainerNotFoundForPointInTimeRestore`

+**Error message**: A container selected for the restore was not found in the storage account for the selected point in time.

+**Recommendation**: Use specific container restore or prefix match restore for containers that are present in the account. We also recommend enabling vaulted backup for your storage account to get comprehensive protection against deletion of containers. If you already have it configured, you can use a recovery point for performing recovery of deleted containers.

+Back up daily via the Azure VM extension | Four backups per day: one scheduled backup as set up in the backup policy, and three on-demand backups. <br><br> To allow user retries in case of failed attempts, the hard limit for on-demand backups is set to nine attempts in a 24 hour UTC period.

+<a name="tvm-backup">Back up trusted launch VMs</a> | Backup is supported. <br><br> Backup of trusted launch VMs is supported through [Enhanced policy](backup-azure-vms-enhanced-policy.md). You can enable backup through a [Recovery Services vault](./backup-azure-arm-vms-prepare.md), the [pane for managing a VM](./backup-during-vm-creation.md#start-a-backup-after-creating-the-vm), and the [pane for creating a VM](backup-during-vm-creation.md#create-a-vm-with-backup-configured). <br><br> **Feature details** <br><br> - Backup is supported in all regions where trusted launch VMs are available. <br><br> - Configuration of backups, alerts, and monitoring for trusted launch VMs is currently not supported through the backup center. <br><br> - Migration of an existing [Gen2 VM](../virtual-machines/generation-2.md) (protected with Azure Backup) to a trusted launch VM is currently not supported. [Learn how to create a trusted launch VM](../virtual-machines/trusted-launch-portal.md?tabs=portal#deploy-a-trusted-launch-vm). <br><br> - Item-level restore is supported for the scenarios mentioned [here](backup-support-matrix-iaas.md#support-for-file-level-restore).

+<a name="ultra-disk-backup">Ultra disks</a> | Supported with [Enhanced policy](backup-azure-vms-enhanced-policy.md). The support is currently in preview. <br><br> [Supported regions](../virtual-machines/disks-types.md#ultra-disk-limitations). <br><br> To enroll your subscription for this feature, [fill this form](https://forms.office.com/r/1GLRnNCntU). <br><br> - Configuration of Ultra disk protection is supported via Recovery Services vault only. This configuration is currently not supported via virtual machine blade. <br><br> - Cross-region restore is currently not supported for machines using Ultra disks. <br><br> - GRS type vaults cannot be used for enabling backup.

+<a name="premium-ssd-v2-backup">Premium SSD v2</a> | Supported with [Enhanced policy](backup-azure-vms-enhanced-policy.md). The support is currently in preview. <br><br> [Supported regions](../virtual-machines/disks-types.md#regional-availability). <br><br> To enroll your subscription for this feature, [fill this form](https://forms.office.com/r/h56TpTc773). <br><br> - Configuration of Premium v2 disk protection is supported via Recovery Services vault only. This configuration is currently not supported via virtual machine blade. <br><br> - Cross-region restore is currently not supported for machines using Premium v2 disks. <br><br> - GRS type vaults cannot be used for enabling backup.

+### Retention limits

+The following are the retention durations that can be set for the different recovery points:

+|Recovery point |Minimum | Maximum

+|||

+|Daily recovery point | 7 days | 9999 days

+|Weekly recovery point | 4 weeks | 5163 weeks

+|Monthly recovery point | 3 months | 1188 months

+|Yearly recovery point | 1 year | 99 years

+>- The role/access level required to perform restore operation in cross-regions are _Backup Operator_ role in the subscription and _Contributor(write)_ access on the source and target virtual machines. To view backup jobs, _Backup reader_ is the minimum permission required in the subscription.

+- [Troubleshoot common issues with SAP HANA database backups](backup-azure-sap-hana-database-troubleshoot.md).

+> Currently calling and chat push notifications are supported for both Android and iOS.

+| | Get associated Mobile Network Code, if available (two or three decimal digits used to identify network operator within a country) | ✔️ | ✔️ | ✔️ | ✔️ |

+| | Get associated Mobile Country Code, if available (three decimal digits used to identify the country of a mobile operator) | ✔️ | ✔️ | ✔️ | ✔️ |

+For customers that use Virtual appointments, refer to our Teams Interoperability [user privacy](interop/guest/privacy.md#chat-storage) for storage of chat messages in Teams meetings.

+let worker = await client.path("/routing/workers/{workerId}", "worker-1").patch({

+worker = await client.UpdateWorkerAsync(worker);

+worker = await client.path("/routing/workers/{workerId}", worker.body.id).patch({

+worker = client.upsert_worker(worker_id = worker.id, available_for_offers = False)

+worker = client.updateWorkerWithResponse(worker.getId(), worker.setAvailableForOffers(false));

+This article focuses on *inbound* engagement, where the consumer initiates communication. Developers interested in scheduled business-to-consumer interactions should read our [Virtual Visits](/azure/communication-services/tutorials/virtual-visits) tutorial.

+After you deploy Azure Communications Gateway and connect it to your core network, you need to connect it to Microsoft Phone System. You also need to onboard to the Operator Connect or Teams Phone Mobile environments.

+This article describes how to set up Azure Communications Gateway for Operator Connect and Teams Phone Mobile. After you finish the steps in this article, you can [prepare for live traffic](prepare-for-live-traffic-operator-connect.md) with Operator Connect, Teams Phone Mobile and Azure Communications Gateway.

+You must [deploy Azure Communications Gateway](deploy.md).

+You must allocate six "service verification" test numbers for each of Operator Connect and Teams Phone Mobile. These numbers are used by the Operator Connect and Teams Phone Mobile programs for continuous call testing.

+- If you selected the service you're setting up as part of deploying Azure Communications Gateway, you've allocated numbers for the service already.

+- Otherwise, choose the phone numbers now (in E.164 format and including the country code) and names to identify them. We recommend names of the form OC1 and OC2 (for Operator Connect) and TPM1 and TPM2 (for Teams Phone Mobile).

+You must also allocate at least one test number for each service for integration testing.

+If you want to set up Teams Phone Mobile and you didn't select it when you deployed Azure Communications Gateway, choose:

+- The number used in Teams Phone Mobile to access the Voicemail Interactive Voice Response (IVR) from native dialers.

+- How you plan to route Teams Phone Mobile calls to Microsoft Phone System. Choose from:

+ - Integrated MCP (MCP in Azure Communications Gateway).

+ - On-premises MCP.

+ - Another method to route calls.

+## Enable Operator Connect or Teams Phone Mobile support

+> [!NOTE]

+> If you selected Operator Connect or Teams Phone Mobile when you [deployed Azure Communications Gateway](deploy.md), skip this step and go to [Add the Project Synergy application to your Azure tenancy](#add-the-project-synergy-application-to-your-azure-tenancy).

+1. Sign in to the [Azure portal](https://azure.microsoft.com/).

+1. In the search bar at the top of the page, search for your Communications Gateway resource and select it.

+1. In the side menu bar, find **Communications services** and select **Operator Connect** or **Teams Phone Mobile** (as appropriate) to open a page for the service.

+1. On the service's page, select **Operator Connect settings** or **Teams Phone Mobile settings**.

+1. Fill in the fields, selecting **Review + create** and **Create**.

+1. Select the **Overview** page for your resource.

+1. Select **Add test lines** and add the service verification lines you chose in [Prerequisites](#prerequisites). Set the **Testing purpose** to **Automated**.

+ > [!IMPORTANT]

+ > Do not add the numbers for integration testing. You will configure numbers for integration testing when you [carry out integration testing and prepare for live traffic](prepare-for-live-traffic-operator-connect.md).

+1. Wait for your resource to be updated. When your resource is ready, the **Provisioning Status** field on the resource overview changes to "Complete." We recommend that you check in periodically to see if the Provisioning Status field is "Complete." This step might take up to two weeks.

+Before starting this step, check that the **Provisioning Status** field for your resource is "Complete".

+After you deploy Azure Communications Gateway and connect it to your core network, you need to connect it to Microsoft Phone System.

+This article describes how to start connecting Azure Communications Gateway to Microsoft Teams Direct Routing. After you finish the steps in this article, you can set up test users for test calls and prepare for live traffic.

+You must [deploy Azure Communications Gateway](deploy.md).

+Your organization must [integrate with Azure Communications Gateway's Provisioning API](integrate-with-provisioning-api.md). If you didn't configure the Provisioning API in the Azure portal as part of deploying, you also need to know:

+- The IP addresses or address ranges (in CIDR format) in your network that should be allowed to connect to the Provisioning API, as a comma-separated list.

+- (Optional) The name of any custom SIP header that Azure Communications Gateway should add to messages entering your network.

+## Enable Microsoft Teams Direct Routing support

+> [!NOTE]

+> If you selected Microsoft Teams Direct Routing when you [deployed Azure Communications Gateway](deploy.md), skip this step and go to [Find your Azure Communication Gateway's domain names](#find-your-azure-communication-gateways-domain-names).

+1. Sign in to the [Azure portal](https://azure.microsoft.com/).

+1. In the search bar at the top of the page, search for your Communications Gateway resource and select it.

+1. In the side menu bar, find **Communications services** and select **Teams Direct Routing** to open a page for the service.

+1. On the service's page, select **Teams Direct Routing settings**.

+1. Fill in the fields, selecting **Review + create** and **Create**.

+1. Select the **Overview** page for your resource.

+1. Wait for your resource to be updated. When your resource is ready, the **Provisioning Status** field on the resource overview changes to "Complete." We recommend that you check in periodically to see if the Provisioning Status field is "Complete." This step might take up to two weeks.

+Before starting this step, check that the **Provisioning Status** field for your resource is "Complete".

+After you deploy Azure Communications Gateway and connect it to your core network, you need to connect it to Zoom.

+This article describes how to start connecting Azure Communications Gateway to Zoom Phone Cloud Peering. After you finish the steps in this article, you can set up test users for test calls and prepare for live traffic.