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

+You must start the onboarding process with Zoom to become a Zoom Phone Cloud Peering provider. For more information on Cloud Peering, see [Zoom's Cloud Peering information](https://partner.zoom.us/partner-type/cloud-peering/).

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

+You must allocate "service verification" test numbers for Zoom. Zoom use these numbers 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). You need six numbers for the US and Canada or two numbers for the rest of the world.

+You must also allocate at least one test number for each service for your own integration testing.

+You must know which Zoom Phone Cloud Peering region you need to connect to.

+## Enable Zoom Phone Cloud Peering support

+> [!NOTE]

+> If you selected Zoom Phone Cloud Peering when you [deployed Azure Communications Gateway](deploy.md), skip this step and go to [Ask your onboarding team for the FQDNs and IP addresses for Azure Communications Gateway](#ask-your-onboarding-team-for-the-fqdns-and-ip-addresses-for-azure-communications-gateway).

+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 **Zoom Phone Cloud Peering** to open a page for the service.

+1. On the service's page, select **Zoom Phone Cloud Peering settings**.

+1. Fill in the fields, selecting **Review + create** and **Create**.

+ > [!IMPORTANT]

+ > Do not add the numbers for your own integration testing when you configure test numbers. You will configure numbers for integration testing when you [configure test numbers](configure-test-numbers-zoom.md).

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

+|A name for the test line. We recommend names of the form OC1 and OC2 (for Operator Connect) and TPM1 and TPM2 (for Teams Phone Mobile). |**Name**|

+Wait for your resource to be provisioned. 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.

+- You must [deploy Azure Communications Gateway](deploy.md) using the Microsoft Azure portal and [connect it to Operator Connect or Teams Phone Mobile](connect-operator-connect.md).

+- You must know the test numbers to use for integration testing and for service verification (continuous call testing). These numbers can't be the same. You chose them as part of [deploying Azure Communications Gateway](deploy.md#prerequisites) or [connecting it to Operator Connect or Teams Phone Mobile](connect-operator-connect.md#prerequisites).

+ - Integration testing allows you to confirm that Azure Communications Gateway and Microsoft Phone System are interoperating correctly with your network.

+ - Service verification is set up by the Operator Connect and Teams Phone Mobile programs and ensures that your deployment is able to handle calls from Microsoft Phone System throughout the lifetime of your deployment.

+- You must have a tenant you can use for integration testing (representing an enterprise customer), and some users in that tenant to whom you can assign the numbers for integration testing.

+ - If you don't already have a suitable test tenant, you can use the [Microsoft 365 Developer Program](https://developer.microsoft.com/microsoft-365/dev-program), which provides E5 licenses.

+## Set up your test tenant

+Integration testing requires setting up your test tenant for Operator Connect or Teams Phone Mobile and configuring users in this tenant with the numbers you chose for integration testing.

+> [!IMPORTANT]

+> Do not assign the service verification numbers to test users. Your onboarding team arranges configuration of your service verification numbers.

+## Update your network's routing configuration

+Your network must route calls for service verification testing and for integration testing to Azure Communications Gateway.

+1. Route all calls from any service verification number to any other service verification number back to Microsoft Phone System through Azure Communications Gateway.

+2. Route calls involving the test numbers for integration testing in the same way that you expect to route customer calls.

+|Google Container Registry|Supports both authenticated pulls and unauthenticated pulls.|Azure CLI|

+[docker-rate-limit]:https://aka.ms/docker-rate-limit

+|Google Container Registry|Supports both authenticated pulls and unauthenticated pulls.|Azure CLI|

+[az-keyvault-set-policy]: ../key-vault/general/assign-access-policy.md#assign-an-access-policy

+Microsoft Copilot for Azure (preview) requires registration and is currently only available to approved enterprise customers and partners. Customers who wish to use Microsoft Copilot for Azure (preview) are required to submit a [registration form](https://aka.ms/MSCopilotforAzurePreview).

+In this example, Microsoft Copilot for Azure (preview) responds to the prompt, "Any code performance optimizations?" The response notes that there are 6 recommendations, providing the option to view either the top recommendation or all recommendations at once.

+* Adopt new features that are supported only for new containers, e.g. [Hierarchical partition keys](hierarchical-partition-keys.md).

+| South Central US | UK South | East Asia |

+| West Central US | UK West | Malaysia South |

+| West US | West Europe | Japan West |

+| West US 2 | Israel Central | Australia Southeast |

+| Not supported | South Africa North | Not supported |

+ --dest-account $destinationAccount `

+ --src-account $sourceAccount `

+ --dest-account $destinationAccount `

+ --src-account $sourceAccount `

+ --dest-account $destinationAccount `

+ --src-account $sourceAccount `

+ --dest-account $destinationAccount `

+ --src-account $sourceAccount `

+ --account-name $destinationAccount `

+ --account-name $destinationAccount

+ --account-name $destinationAccount `

+ --account-name $destinationAccount `

+ --account-name $destinationAccount `

+ "properties": {

+ }

+### Steps to enable CMK on your existing Azure Cosmos DB account with Continuous backup or Analytical store account

+ az cosmosdb updateΓÇ»--resource-group $resourceGroupNameΓÇ» --name $accountNameΓÇ» --default-identity "SystemAssignedIdentity=subscriptions/00000000-0000-0000-0000-00000000/resourcegroups/MyRG/providers/Microsoft.ManagedIdentity/ systemAssignedIdentities/MyID"

+Enabling CMK doesn't pose any threat of data loss.

+**What is the behavior on existing accounts that are enabled for Continuous backup?**

+When CMK is turned on, the encryption is turned on for continuous backups as well. Once CMK is turned on, all restored accounts going forward will be CMK enabled.

+- This behavior is in line with the current design of restore of CMK enabled account with periodic backup

+A container's indexing policy can be updated at any time [by using the Azure portal or one of the supported SDKs](how-to-manage-indexing-policy.md). An update to the indexing policy triggers a transformation from the old index to the new one, which is performed online and in-place (so no additional storage space is consumed during the operation). The old indexing policy is efficiently transformed to the new policy without affecting the write availability, read availability, or the throughput provisioned on the container. Index transformation is an asynchronous operation, and the time it takes to complete depends on the provisioned throughput, the number of items and their size. If multiple indexing policy updates have to be made, it is recommended to do all the changes as a single operation in order to have the index transformation complete as quickly as possible.

+<tr><td>Vector Index (only available in Cosmos DB)</td><td><img src="medi>vector search</a></td></tr>

+for all of your learning & evaluation needs. Users can provision a single free DB server per supported Azure region for a given subscription. This feature is currently available for our users in the East US, and Southeast Asia regions.

+* Free tier is currently available in East US, and Southeast Asia regions only.

+description: Release notes, new features, and features in preview

+* General availability: [The latest minor PostgreSQL version updates](reference-versions.md#postgresql-versions) (11.22, 12.17, 13.13, 14.10, 15.5, and 16.1) are now available in all supported regions.

+> | [tdigest](https://github.com/tvondra/tdigest) | Data type for on-line accumulation of rank-based statistics such as quantiles and trimmed means. | 1.4.1 | 1.4.1 | 1.4.1 | 1.4.1 | 1.4.1 | 1.4.1 |

+> | [pg\_partman](https://pgxn.org/dist/pg_partman/doc/pg_partman.html) | Manages partitioned tables by time or ID. | 4.7.4 | 4.7.4 | 4.7.4 | 5.0.0 | 5.0.0 | 5.0.0 |

+> | [old\_snapshot](https://www.postgresql.org/docs/current/oldsnapshot.html) | Allows inspection of the server state that is used to implement old_snapshot_threshold. | | | | 1.0 | 1.0 | |

+> [pgvector](https://github.com/pgvector/pgvector#installation-notes) | Open-source vector similarity search for Postgres | 0.5.1 | 0.5.1 | 0.5.1 | 0.5.1 | 0.5.1 | 0.5.1 |

+The current minor release is 16.1. Refer to the [PostgreSQL

+documentation](https://www.postgresql.org/docs/release/16.1/) to

+The current minor release is 15.5. Refer to the [PostgreSQL

+documentation](https://www.postgresql.org/docs/release/15.5/) to

+The current minor release is 14.10. Refer to the [PostgreSQL

+documentation](https://www.postgresql.org/docs/release/14.10/) to

+The current minor release is 13.13. Refer to the [PostgreSQL

+documentation](https://www.postgresql.org/docs/release/13.13/) to

+The current minor release is 12.17. Refer to the [PostgreSQL

+documentation](https://www.postgresql.org/docs/release/12.17/) to

+The *final* minor release is 11.22. Refer to the [PostgreSQL

+documentation](https://www.postgresql.org/docs/release/11.22/) to

+description: Vector database extension and retrieval augmented generation (RAG) implementation.

+# Vector database

+You have likely considered augmenting your applications with large language models (LLMs) and vector databases that can access your own data through retrieval-augmented generation (RAG). This approach allows you to

+Some RAG implementation tutorials demonstrate integrating vector databases that are distinct from traditional relational and non-relational databases. Instead of adding a separate vector database to your existing tech stack, you can achieve the same outcome using the vector database extensions for Azure Cosmos DB when working with multi-modal data. By doing so, you can keep your vector embeddings and original data together to achieve data consistency, scale, and performance while avoiding the extra cost of moving data to a separate vector database.

+Here is how:

+| **[Azure Cosmos DB for Mongo DB vCore](#implement-vector-database-functionalities-using-our-api-for-mongodb-vcore)** | Store your application data and vector embeddings together in a single MongoDB-compatible service featuring native support for vector search. |

+| **[Azure Cosmos DB for PostgreSQL](#implement-vector-database-functionalities-using-our-api-for-postgresql)** | Store your data and vectors together in a scalable PostgreSQL offering with native support for vector search. |

+| **[Azure Cosmos DB for NoSQL with Azure AI Search](#implement-vector-database-functionalities-using-our-nosql-api-and-ai-search)** | Augment your Azure Cosmos DB data with semantic and vector search capabilities of Azure AI Search. |

+## What does a vector database do?

+The vector search feature in a vector database enables retrieval-augmented generation to harness LLMs and custom data or domain-specific information. This process involves extracting pertinent information from a custom data source and integrating it into the model request through prompt engineering.

+A robust mechanism is necessary to identify the most relevant data from the custom source that can be passed to the LLM. Our vector search features convert the data in your database into embeddings and store them as vectors for future use, thus capturing the semantic meaning of the text and going beyond mere keywords to comprehend the context. Moreover, this mechanism allows you to optimize for the LLMΓÇÖs limit on the number of tokens per request.

+Here are multiple ways to implement RAG on your data by using our vector database functionalities.

+## Implement vector database functionalities using our API for MongoDB vCore

+### Vector database implementation code samples

+## Implement vector database functionalities using our API for PostgreSQL

+Use the native vector search feature in Azure Cosmos DB for PostgreSQL, which offers an efficient way to store, index, and search high-dimensional vector data directly alongside other application data. This approach removes the necessity of migrating your data to costlier alternative vector databases and provides a seamless integration of your AI-driven applications.

+### Vector database implementation code samples

+## Implement vector database functionalities using our NoSQL API and AI Search

+Implement RAG patterns with Azure Cosmos DB for NoSQL and Azure AI Search. This approach enables powerful integration of your data residing in the NoSQL API into your AI-oriented applications. Azure AI Search empowers you to efficiently index and query high-dimensional vector data, thereby meeting your vector database needs.

+### Vector database implementation code samples

+- [.NET RAG Pattern retail reference solution for NoSQL](https://github.com/Azure/Vector-Search-AI-Assistant-MongoDBvCore)

+- [.NET tutorial - recipe chatbot](https://github.com/microsoft/AzureDataRetrievalAugmentedGenerationSamples/tree/main/C%23/CosmosDB-NoSQL_CognitiveSearch)

+- [.NET tutorial - recipe chatbot w/ Semantic Kernel](https://github.com/microsoft/AzureDataRetrievalAugmentedGenerationSamples/tree/main/C%23/CosmosDB-NoSQL_CognitiveSearch_SemanticKernel)

+- [Python notebook tutorial - Azure product chatbot](https://github.com/microsoft/AzureDataRetrievalAugmentedGenerationSamples/tree/main/Python/CosmosDB-NoSQL_CognitiveSearch)

+- You've incurred overage charges that haven't been paid and are within 3 months of the invoice bill date.

+- Similar to the authentication process used in the standard Azure REST API, acquiring an access token from Azure AD is required before making a call to the Airflow REST API. A guide on how to obtain the token from Azure AD can be found at [https://learn.microsoft.com/rest/api/azure](/rest/api/azure).

+- [How to change the password for Managed Airflow environments](password-change-airflow.md)

+### Region expansion

+| | <ul><li>At least one 1-GbE RJ-45 network cable for Port 1 </li><li>At least one 25/10-GbE SFP+ copper cable for Port 3, Port 4, Port 5, or Port 6</li></ul>| Customer needs to procure these cables.<br>For a full list of supported network cables, switches, and transceivers for device network cards from Cavium, see [Cavium FastlinQ 41000 Series Interoperability Matrix](https://www.marvell.com/documents/xalflardzafh32cfvi0z/).|

+| | <ul><li>At least two 1-GbE RJ-45 network cables for Port 1 on the two device nodes </li><li>You would need two 1-GbE RJ-45 network cables to connect Port 2 on each device node to the internet. Depending on the network topology you wish to deploy, you also need SFP+ copper cables to connect Port 3 and Port 4 across the device nodes and also from device nodes to the switches. See the [Supported network topologies](azure-stack-edge-gpu-clustering-overview.md#supported-networking-topologies).</li></ul> | Customer needs to procure these cables.<br>For a full list of supported network cables, switches, and transceivers for device network cards from Cavium, see [Cavium FastlinQ 41000 Series Interoperability Matrix](https://www.marvell.com/documents/xalflardzafh32cfvi0z/).|

+ See [Cavium FastlinQ 41000 Series Interoperability Matrix](https://www.marvell.com/documents/xalflardzafh32cfvi0z/) to get compatible network cables and switches.

+| | <ul><li>At least 1 X 1-GbE RJ-45 network cable for Port 1 </li><li>At least 1 X 25-GbE SFP+ copper cable for Port 3, Port 4, Port 5, or Port 6</li></ul>| Customer needs to procure these cables.<br>For a full list of supported network cables, switches, and transceivers for device network cards, see [Cavium FastlinQ 41000 Series Interoperability Matrix](https://www.marvell.com/documents/xalflardzafh32cfvi0z/).|

+| | - At least one X 1-GbE RJ-45 network cable for Port 1. <br> - At least 100-GbE QSFP28 Passive Direct Attached Cable (tested in-house) for each data network interface Port 3 and Port 4 to be configured. <br> - At least one 100-GbE network switch to connect a 1 GbE or a 100-GbE network interface to the Internet for data.| Customer needs to procure these cables.|

+| | <br> - At least two 1-GbE RJ-45 network cables for Port 1 on the two device nodes <br> - You would need two 1-GbE network cables to connect Port 2 on each device node to the internet. Depending on the network topology you wish to deploy, you may also need at least one 100-GbE QSFP28 Passive Direct Attached Cable (tested in-house) to connect Port 3 and Port 4 across the device nodes. <br> - You would also need at least one 10/1-GbE network switch to connect Port 1 and Port 2. You would need a 100/10-GbE switch to connect Port 3 or Port 4 network interface to the Internet for data.| Customer needs to procure these cables and switches. Exact number of cables and switches would depend on the network topology that you deploy.|

+ - **Mellanox dual port 100 GbE ConnectX-6 Dx network adapter** - Port 3, Port 4.

+| | <ul><li>At least 1 X 1-GbE RJ-45 network cable for Port 1 </li><li> At least 1 X 25-GbE SFP+ copper cable for Port 3, Port 4</li><ul>| Customer needs to procure these cables.<br>For a full list of supported network cables, switches, and transceivers for device network cards, see [Cavium FastlinQ 41000 Series Interoperability Matrix](https://www.marvell.com/documents/xalflardzafh32cfvi0z/).|

+<!--

+# Doc scores:

+# 11/18/22: 75 (2456/62)

+# 09/01/23: 100 (2159/0)

+-->

+<!--

+-->

+This tutorial describes how to copy data from your host computer and generate checksums to verify data integrity.

+- The client computer used to copy data to the disks is running a [Supported operating system](data-box-disk-system-requirements.md#supported-operating-systems-for-clients).

+- The intended storage type for your data matches [Supported storage types](data-box-disk-system-requirements.md#supported-storage-types-for-upload).

+- You've reviewed [Managed disk limits in Azure object size limits](data-box-disk-limits.md#azure-object-size-limits).

+- It is your responsibility to ensure that you copy your local data to the folders that correspond to the appropriate data format. For instance, copy block blob data to the *BlockBlob* folder. Block blobs being archived should be copied to the *BlockBlob_Archive* folder. If the local data format doesn't match the appropriate folder for the chosen storage type, the data upload to Azure fails in a later step.

+- While copying data, ensure that the data size conforms to the size limits described within in the [Azure storage and Data Box Disk limits](data-box-disk-limits.md) article.

+- To preserve metadata such as ACLs, timestamps, and file attributes when transferring data to Azure Files, follow the guidance within the [Preserving file ACLs, attributes, and timestamps with Azure Data Box Disk](data-box-disk-file-acls-preservation.md) article.

+- If you use both Data Box Disk and other applications to upload data simultaneously, you may experience upload job failures and data corruption.

+ > [!IMPORTANT]

+ > Data uploaded to the archive tier remains offline and needs to be rehydrated before reading or modifying. Data copied to the archive tier must remain for at least 180 days or be subject to an early deletion charge. Archive tier is not supported for ZRS, GZRS, or RA-GZRS accounts.

+- Ensure that virtual hard disks (VHDs) uploaded to the precreated folders have unique names within resource groups. Managed disks must have unique names within a resource group across all the precreated folders on the Data Box Disk. If you're using multiple Data Box Disks, managed disk names must be unique across all folder and disks. When VHDs with duplicate names are found, only one is converted to a managed disk with that name. The remaining VHDs are uploaded as page blobs into the staging storage account.

+- Always copy the VHDs to one of the precreated folders. VHDs placed outside of these folders or in a folder that you created are uploaded to Azure Storage accounts as page blobs instead of managed disks.

+- Only fixed VHDs can be uploaded to create managed disks. Dynamic VHDs, differencing VHDs and VHDX files aren't supported.

+- The Data Box Disk Split Copy and Validation tools, `DataBoxDiskSplitCopy.exe` and `DataBoxDiskValidation.cmd`, report failures when long paths are processed. These failures are common when long paths aren't enabled on the client, and your data copy's paths and file names exceed 256 characters. To avoid these failures, follow the guidance within the [enable long paths on your Windows client](/windows/win32/fileio/maximum-file-path-limitation?tabs=cmd#enable-long-paths-in-windows-10-version-1607-and-later) article.

+1. View the contents of the unlocked drive. The list of the precreated folders and subfolders in the drive varies according to the options you select when placing the Data Box Disk order. The creation of extra folders isn't permitted, as copying data to a user-created folder causes upload failures.

+ |Selected storage destination |Storage account type|Staging storage account type |Folders and subfolders |

+ ||--|--||

+ |Storage account |GPv1 or GPv2 | NA | BlockBlob<br>BlockBlob_Archive<br>PageBlob<br>AzureFile |

+ |Storage account |Blob storage account| NA | BlockBlob<br>BlockBlob_Archive |

+ |Managed disks |NA | GPv1 or GPv2 | ManagedDisk<ul><li>PremiumSSD</li><li>StandardSSD</li><li>StandardHDD</li></ul> |

+ |Storage account<br>Managed disks |GPv1 or GPv2 | GPv1 or GPv2 | BlockBlob<br/>BlockBlob_Archive<br/>PageBlob<br/>AzureFile<br/>ManagedDisk<ul><li>PremiumSSD</li><li>StandardSSD</li><li>StandardHDD</li></ul>|

+ |Storage account <br> Managed disks |Blob storage account | GPv1 or GPv2 |BlockBlob<br>BlockBlob_Archive<br>ManagedDisk<ul> <li>PremiumSSD</li><li>StandardSSD</li><li>StandardHDD</li></ul> |

+ The following screenshot shows an order where a GPv2 storage account and archive tier were specified:

+ :::image type="content" source="media/data-box-disk-deploy-copy-data/content-sml.png" alt-text="Screenshot of the contents of the disk drive." lightbox="media/data-box-disk-deploy-copy-data/content.png":::

+1. Copy data to be imported as block blobs into the *BlockBlob* folder. Copy data to be stored as block blobs with the archive tier into the *BlockBlob_Archive* folder. Similarly, copy VHD or VHDX data to the *PageBlob* folder, and file share data into *AzureFile* folder.

+ A container is created in the Azure storage account for each subfolder within the *BlockBlob* and *PageBlob* folders. All files copied to the *BlockBlob* and *PageBlob* folders are copied into a default `$root` container within the Azure Storage account. Any files in the `$root` container are always uploaded as block blobs.

+ Copy data to be placed in Azure file shares to a subfolder within the *AzureFile* folder. All files copied to the *AzureFile* folder are copied as files to a default container of type `databox-format-[GUID]`, for example, `databox-azurefile-7ee19cfb3304122d940461783e97bf7b4290a1d7`.

+ Before you begin to copy data, you need to move any files and folders that exist in the root directory to a different folder.

+1. When copying files, ensure that files don't exceed 4.7 TiB for block blobs, 8 TiB for page blobs, and 1 TiB for Azure Files.

+1. You can use File Explorer's drag and drop functionality to copy the data. You can also use any SMB compatible file copy tool such as Robocopy to copy your data.

+ One benefit of using a file copy tool is the ability to initiate multiple copy jobs, as in the following example using the Robocopy tool:

+ `Robocopy <source> <destination> * /MT:64 /E /R:1 /W:1 /NFL /NDL /FFT /Log:c:\RobocopyLog.txt`

+ >[!NOTE]

+ > The parameters used in this example are based on the environment used during in-house testing. Your paramters and values are likely different.

+ The parameters and options for the command are used as follows:

+ |Parameters/Options |Description |

+ |-||

+ |Source | Specifies the path to the source directory. |

+ |Destination | Specifies the path to the destination directory. |

+ |/E | Copies subdirectories including empty directories. |

+ |/MT[:n] | Creates multi-threaded copies with *n* threads where *n* is an integer between 1 and 128.<br>The default value for *n* is 8. |

+ |/R: \<n> | Specifies the number of retries on failed copies.<br>The default value of *n* is 1,000,000 retries. |

+ |/W: \<n> | Specifies the wait time between retries, in seconds.<br>The default value of *n* is 30 and is equivalent to a wait time 30 seconds. |

+ |/NFL | Specifies that file names aren't logged. |

+ |/NDL | Specifies that directory names aren't to be logged. |

+ |/FFT | Assumes FAT file times with a resolution precision of two seconds. |

+ |/Log:\<Log File> | Writes the status output to the log file.<br>Any existing log file is overwritten. |

+ Multiple disks can be used in parallel with multiple jobs running on each disk. Keep in mind that duplicate filenames are either overwritten or result in a copy error.

+1. Check the copy status when the job is in progress. The following sample shows the output of the robocopy command to copy files to the Data Box Disk.

+ ```Sample output

+

+ C:\Users>robocopy

+ -

+ ROBOCOPY :: Robust File Copy for Windows

+ -

+

+ Simple Usage :: ROBOCOPY source destination /MIR

+ source :: Source Directory (drive:\path or \\server\share\path).

+ destination :: Destination Dir (drive:\path or \\server\share\path).

+ /MIR :: Mirror a complete directory tree.

+ For more usage information run ROBOCOPY /?

+ **** /MIR can DELETE files as well as copy them !

+ C:\Users>Robocopy C:\Repository\guides \\10.126.76.172\AzFileUL\templates /MT:64 /E /R:1 /W:1 /FFT

+ -

+ ROBOCOPY :: Robust File Copy for Windows

+ -

+ Source : C:\Repository\guides\

+ 100% New File 206 C:\Repository\guides\article-metadata.md

+ 100% New File 209 C:\Repository\guides\content-channel-guidance.md

+ 100% New File 732 C:\Repository\guides\index.md

+ 100% New File 199 C:\Repository\guides\pr-criteria.md

+ 100% New File 178 C:\Repository\guides\pull-request-co.md

+ 100% New File 250 C:\Repository\guides\pull-request-ete.md

+ 100% New File 174 C:\Repository\guides\create-images-markdown.md

+ 100% New File 197 C:\Repository\guides\create-links-markdown.md

+ 100% New File 184 C:\Repository\guides\create-tables-markdown.md

+ 100% New File 208 C:\Repository\guides\custom-markdown-extensions.md

+ 100% New File 210 C:\Repository\guides\file-names-and-locations.md

+ 100% New File 234 C:\Repository\guides\git-commands-for-master.md

+ 100% New File 186 C:\Repository\guides\release-branches.md

+ 100% New File 240 C:\Repository\guides\retire-or-rename-an-article.md

+ 100% New File 215 C:\Repository\guides\style-and-voice.md

+ 100% New File 212 C:\Repository\guides\syntax-highlighting-markdown.md

+ 100% New File 207 C:\Repository\guides\tools-and-setup.md

+ Ended : Thursday, August 31, 2023 2:34:59 PM

+ | Platform | Mostly small files < 512 KB | Mostly medium files 512 KB-1 MB | Mostly large files > 1 MB |

+ ||--|-||

+ | Data Box Disk | 4 Robocopy sessions*<br>16 threads per session | 2 Robocopy session*<br>16 threads per session | 2 Robocopy session*<br>16 threads per session |

+ For more information on the Robocopy command, read the [Robocopy and a few examples](https://social.technet.microsoft.com/wiki/contents/articles/1073.robocopy-and-a-few-examples.aspx) article.

+1. Open the target folder, then view and verify the copied files. If you have any errors during the copy process, download the log files for troubleshooting. The robocopy command's output specifies the location of the log files.

+The Data Box Split Copy tool helps split and copy data across two or more Azure Data Box Disks. The tool is only available for use on a Windows computer. This optional procedure is helpful when you have a large dataset that needs to be split and copied across several disks.

+> The Data Box Split Copy tool can also validate your data. If you use Data Box Split Copy tool to copy data, you can skip the [validation step](#validate-data).

+> The Split Copy tool is not supported with managed disks.

+1. On your Windows computer, ensure that you have the Data Box Split Copy tool downloaded and extracted in a local folder. This tool is included within the Data Box Disk toolset for Windows.

+1. Open File Explorer. Make a note of the data source drive and drive letters assigned to Data Box Disk.

+ :::image type="content" source="media/data-box-disk-deploy-copy-data/split-copy-1-sml.png" alt-text="Screenshot of the data source drive and drive letters assigned to Data Box Disk." lightbox="media/data-box-disk-deploy-copy-data/split-copy-1.png":::

+1. Identify the source data to copy. For instance, in this case:

+ - The following block blob data was identified.

+ :::image type="content" source="media/data-box-disk-deploy-copy-data/split-copy-2-sml.png" alt-text="Screenshot of block blob data identified for the copy process." lightbox="media/data-box-disk-deploy-copy-data/split-copy-2.png":::

+ - The following page blob data was identified.

+ :::image type="content" source="media/data-box-disk-deploy-copy-data/split-copy-3-sml.png" alt-text="Screenshot of page blob data identified for the copy process." lightbox="media/data-box-disk-deploy-copy-data/split-copy-3.png":::

+1. Navigate to the folder where the software is extracted and locate the `SampleConfig.json` file. This file is a read-only file that you can modify and save.

+ :::image type="content" source="media/data-box-disk-deploy-copy-data/split-copy-4-sml.png" alt-text="Screenshot showing the location of the sample configuration file." lightbox="media/data-box-disk-deploy-copy-data/split-copy-4.png":::

+1. Modify the `SampleConfig.json` file.

+ - Provide a job name. A folder with this name is created on the Data Box Disk. It's also used to create a container in the Azure storage account associated with these disks. The job name must follow the [Azure container naming conventions](/rest/api/storageservices/naming-and-referencing-containers--blobs--and-metadata).

+ - Supply a source path, making note of the path format in the `SampleConfigFile.json`.

+ - Enter the drive letters corresponding to the target disks. Data is taken from the source path and copied across multiple disks.

+ - Provide a path for the log files. By default, log files are sent to the directory where the `.exe` file is located.

+ - To validate the file format, go to `JSONlint`.

+ :::image type="content" source="media/data-box-disk-deploy-copy-data/split-copy-5.png" alt-text="Screenshot showing the contents of the sample configuration file.":::

+ - Save the file as `ConfigFile.json`.

+ :::image type="content" source="media/data-box-disk-deploy-copy-data/split-copy-6-sml.png" alt-text="Screenshot showing the location of the replacement configuration file." lightbox="media/data-box-disk-deploy-copy-data/split-copy-6.png":::

+1. Open a Command Prompt window with elevated privileges and run the `DataBoxDiskSplitCopy.exe` using the following command.

+ ```Command prompt

+ DataBoxDiskSplitCopy.exe PrepImport /config:ConfigFile.json

+ ```

+1. When prompted, press any key to continue running the tool.

+ :::image type="content" source="media/data-box-disk-deploy-copy-data/split-copy-8-sml.png" alt-text="Screenshot showing the command prompt window executing the Split Copy tool." lightbox="media/data-box-disk-deploy-copy-data/split-copy-8.png":::

+1. After the dataset is split and copied, the summary of the Split Copy tool for the copy session is presented as shown in the following sample output.

+ :::image type="content" source="media/data-box-disk-deploy-copy-data/split-copy-9-sml.png" alt-text="Screenshot showing the summary presented after successful execution of the Split Copy tool." lightbox="media/data-box-disk-deploy-copy-data/split-copy-9.png":::

+1. Verify that the data is split properly across the target disks.

+ :::image type="content" source="media/data-box-disk-deploy-copy-data/split-copy-10-sml.png" alt-text="Screenshot indicating resulting data split properly across the first of two target disks." lightbox="media/data-box-disk-deploy-copy-data/split-copy-10.png":::

+ :::image type="content" source="media/data-box-disk-deploy-copy-data/split-copy-11-sml.png" alt-text="Screenshot indicating resulting data split properly across the second of two target disks." lightbox="media/data-box-disk-deploy-copy-data/split-copy-11.png":::

+ Examine the `H:` drive contents and ensure that two subfolders are created that correspond to block blob and page blob format data.

+ :::image type="content" source="media/data-box-disk-deploy-copy-data/split-copy-12-sml.png" alt-text="Screenshot showing two subfolders created which correspond to block blob and page blob format data." lightbox="media/data-box-disk-deploy-copy-data/split-copy-12.png":::

+1. If the copy session fails, use the following command to recover and resume:

+ `DataBoxDiskSplitCopy.exe PrepImport /config:ConfigFile.json /ResumeSession`

+If you encounter errors while using the Split Copy tool, follow the steps within the [troubleshoot Split Copy tool errors](data-box-disk-troubleshoot-data-copy.md) article.

+>[!IMPORTANT]

+> The Data Box Split Copy tool also validates your data. If you use Data Box Split Copy tool to copy data, you can skip the [validation step](#validate-data).

+> The Split Copy tool is not supported with managed disks.

+## Validate data

+If you didn't use the Data Box Split Copy tool to copy data, you need to validate your data. Perform the following steps on each of your Data Box Disks to verify the data. If you encounter errors during validation, follow the steps within the [troubleshoot validation errors](data-box-disk-troubleshoot.md) article.

+1. Run `DataBoxDiskValidation.cmd` for checksum validation in the *DataBoxDiskImport* folder of your drive. This tool is only available for the Windows environment. Linux users need to validate that the source data copied to the disk meets [Azure Data Box prerequisites](./data-box-disk-limits.md).

+ :::image type="content" source="media/data-box-disk-deploy-copy-data/validation-tool-output-sml.png" alt-text="Screenshot showing Data Box Disk validation tool output." lightbox="media/data-box-disk-deploy-copy-data/validation-tool-output.png":::

+1. Choose the appropriate validation option when prompted. **We recommend that you always validate the files and generate checksums by selecting option 2**. After the script has completed, exit out of the command window. The time required for validation to complete depends upon the size of your data. The tool notifies you of any errors encountered during validation and checksum generation, and provides you with a link to the error logs.

+ :::image type="content" source="media/data-box-disk-deploy-copy-data/checksum-output-sml.png" alt-text="Screenshot showing a failed execution attempt and indicating the location of the corresponding log file." lightbox="media/data-box-disk-deploy-copy-data/checksum-output.png":::

+ > [!TIP]

+ > - Reset the tool between two runs.

+ > - The checksum process may take more time if you have a large data set containing many files that take up relatively little storage capacity. If you validate files and skip checksum creation, you should independently verify data integrity on the Data Box Disk prior to deleting any copies. This verification ideally includes generating checksums.

+In this tutorial, you learned how to complete the following tasks with Azure Data Box Disk:

+<!--

+-->

+<!--

+-->

+# Doc scores:

+# 10/21/22: 75 (1921/15)

+# 09/24/23: 100 (1996/0)

+Azure Data Box Disk is a hybrid cloud solution that allows you to import your on-premises data into Azure in a quick, easy, and reliable way. You transfer your data to solid-state disks (SSDs) supplied by Microsoft and ship the disks back. This data is then uploaded to Azure.

+> * Cancel the order

+ * Have other [required software](data-box-disk-system-requirements.md#other-required-software-for-windows-clients) installed if it's a Windows client.

+ :::image type="content" source="media/data-box-disk-deploy-ordered/search-data-box11-sml.png" alt-text="Search Azure Data Box 1" lightbox="media/data-box-disk-deploy-ordered/search-data-box11.png":::

+1. Click **Create**.

+1. Check if Data Box service is available in your region. Enter or select the following information and click **Apply**.

+ :::image type="content" source="media/data-box-disk-deploy-ordered/select-data-box-sku-1-sml.png" alt-text="Select Data Box Disk option" lightbox="media/data-box-disk-deploy-ordered/select-data-box-sku-1.png":::

+ |Subscription|Select the subscription for which Data Box service is enabled.<br /> The subscription is linked to your billing account. |

+ |Resource group| Select the resource group you want to use to order a Data Box. <br /> A resource group is a logical container for the resources that can be managed or deployed together.|

+1. Select **Data Box Disk**. The maximum capacity of the solution for a single order of five disks is 35 TB. You could create multiple orders for larger data sizes.

+ :::image type="content" alt-text="Select Data Box Disk option 2" source="media/data-box-disk-deploy-ordered/select-data-box-sku-zoom.png":::

+1. In **Order**, specify the **Order details** in the **Basics** tab. Enter or select the following information.

+ |Import order name|Provide a friendly name to track the order.<br /> The name can have between 3 and 24 characters that can be letters, numbers, and hyphens. <br /> The name must start and end with a letter or a number. |

+ |Number of disks per order| Enter the number of disks you would like to order. <br /> There can be a maximum of five disks per order (1 disk = 7TB). |

+ |Disk passkey| Supply the disk passkey if you check **Use custom key instead of Azure generated passkey**. <br /> Provide a 12-character to 32-character alphanumeric key that has at least one numeric and one special character. The allowed special characters are `@?_+`. <br /> You can choose to skip this option and use the Azure generated passkey to unlock your disks.|

+ :::image type="content" alt-text="Screenshot of order details" source="media/data-box-disk-deploy-ordered/data-box-disk-order-sml.png" lightbox="media/data-box-disk-deploy-ordered/data-box-disk-order.png":::

+1. On the **Data destination** screen, select the **Data destination** - either storage accounts or managed disks (or both).

+ > [!CAUTION]

+ > Blob data can be uploaded to the archive tier, but will need to be rehydrated before reading or modifying. Data copied to the archive tier must remain for at least 180 days or be subject to an early deletion charge. Archive tier is not supported for ZRS, GZRS, or RA-GZRS accounts.

+ |Data destination |Choose from storage account or managed disks or both.<br /> Based on the specified Azure region, select a storage account from the filtered list of an existing storage account. Data Box Disk can be linked with only one storage account.<br /> You can also create a new General-purpose v1, General-purpose v2, or Blob storage account.<br /> Storage accounts with virtual networks are supported. To allow Data Box service to work with secured storage accounts, enable the trusted services within the storage account network firewall settings. For more information, see how to Add Azure Data Box as a trusted service. <br /> To enable support for large file shares, select **Enable large file shares**. To enable the ability to move blob data to the archive tier, select **Enable copy to archive**. |

+ |Destination Azure region| Select a region for your storage account. <br /> Currently, storage accounts in all regions in US, West and North Europe, Canada, and Australia are supported. |

+ |Resource group| If using Data Box Disk to create managed disks from the on-premises VHDs, you need to provide the resource group.<br /> Create a new resource group if you intend to create managed disks from on-premises VHDs. Use an existing resource group only if it was created for Data Box Disk order for managed disk by Data Box service.<br /> Only one resource group is supported.|

+ :::image type="content" alt-text="Screenshot of Data Box Disk data destination." source="media/data-box-disk-deploy-ordered/data-box-disk-order-destination-sml.png" lightbox="media/data-box-disk-deploy-ordered/data-box-disk-order-destination.png":::

+1. Select **Next: Security>** to continue.

+1. If you want to use your own customer-managed key to protect the unlock passkey for your new resource, expand **Encryption type**.

+ :::image type="content" alt-text="Screenshot of Data Box Disk encryption type." source="media/data-box-disk-deploy-ordered/data-box-disk-encryption-sml.png" lightbox="media/data-box-disk-deploy-ordered/data-box-disk-encryption.png":::

+ :::image type="content" alt-text="Screenshot of Customer managed key selection." source="media/data-box-disk-deploy-ordered/data-box-disk-customer-key-sml.png" lightbox="media/data-box-disk-deploy-ordered/data-box-disk-customer-key.png":::

+ * The **Subscription** is automatically populated.

+ * For **Key vault**, you can select an existing key vault from the dropdown list.

+ :::image type="content" alt-text="Screenshot of existing key vault." source="media/data-box-disk-deploy-ordered/data-box-disk-select-key-vault.png":::

+ :::image type="content" alt-text="Screenshot of new key vault." source="media/data-box-disk-deploy-ordered/data-box-disk-create-new-key-vault-sml.png" lightbox="media/data-box-disk-deploy-ordered/data-box-disk-create-new-key-vault.png":::

+ :::image type="content" alt-text="Screenshot of Create key vault blade." source="media/data-box-disk-deploy-ordered/data-box-disk-key-vault-blade-sml.png" lightbox="media/data-box-disk-deploy-ordered/data-box-disk-key-vault-blade.png":::

+ :::image type="content" alt-text="Screenshot of Review + create." source="media/data-box-disk-deploy-ordered/data-box-disk-create-key-vault-sml.png" lightbox="media/data-box-disk-deploy-ordered/data-box-disk-create-key-vault.png":::

+ :::image type="content" alt-text="Screenshot of new key vault 2." source="media/data-box-disk-deploy-ordered/data-box-disk-new-key-vault-sml.png" lightbox="media/data-box-disk-deploy-ordered/data-box-disk-new-key-vault.png":::

+ :::image type="content" alt-text="Screenshot of Create new key." source="media/data-box-disk-deploy-ordered/data-box-disk-new-key-sml.png" lightbox="media/data-box-disk-deploy-ordered/data-box-disk-new-key.png":::

+ You're notified when the key has been created in your key vault. Your new key is selected on the **Select a key** blade.

+ :::image type="content" alt-text="Screenshot of key version." source="media/data-box-disk-deploy-ordered/data-box-disk-key-version-sml.png" lightbox="media/data-box-disk-deploy-ordered/data-box-disk-key-version.png":::

+ :::image type="content" alt-text="Screenshot of new key version." source="media/data-box-disk-deploy-ordered/data-box-disk-new-key-version-sml.png" lightbox="media/data-box-disk-deploy-ordered/data-box-disk-new-key-version.png":::

+ :::image type="content" alt-text="Screenshot of new key version settings." source="media/data-box-disk-deploy-ordered/data-box-disk-new-key-settings-sml.png" lightbox="media/data-box-disk-deploy-ordered/data-box-disk-new-key-settings.png":::

+ :::image type="content" alt-text="Screenshot of encryption type settings." source="media/data-box-disk-deploy-ordered/data-box-disk-encryption-settings-sml.png" lightbox="media/data-box-disk-deploy-ordered/data-box-disk-encryption-settings.png":::

+1. Select a user identity that you use to manage access to this resource. Choose **Select a user identity**. In the panel on the right, select the subscription and the managed identity to use. Then choose **Select**.

+ :::image type="content" alt-text="Screenshot of user identity." source="media/data-box-disk-deploy-ordered/data-box-disk-user-identity-sml.png" lightbox="media/data-box-disk-deploy-ordered/data-box-disk-user-identity.png":::

+ :::image type="content" alt-text="Screenshot of user identity 2." source="media/data-box-disk-deploy-ordered/data-box-disk-user-identity-2-sml.png" lightbox="media/data-box-disk-deploy-ordered/data-box-disk-user-identity-2.png":::

+1. In the **Contact details** tab, select **Add address** and enter the address details. Click Validate address. The service validates the shipping address for service availability. If the service is available for the specified shipping address, you receive a notification to that effect.

+ :::image type="content" alt-text="Screenshot of Data Box Disk contact details." source="media/data-box-disk-deploy-ordered/data-box-disk-contact-details-sml.png" lightbox="media/data-box-disk-deploy-ordered/data-box-disk-contact-details.png":::

+1. Review the information in the **Review + Order** tab related to the order, contact, notification, and privacy terms. Check the box corresponding to the agreement to privacy terms.

+1. Click **Order**. The order takes a few minutes to be created.

+If the disks aren't available, you receive a notification. If the disks are available, Microsoft identifies the disks for shipment and prepares the disk package. During disk preparation, following actions occur:

+> [Set up your Azure Data Box Disk](./data-box-disk-deploy-set-up.md)

+> If there are any files or directories that exceed the Azure Storage service limits, or don't conform to Azure Files/Blob naming conventions, then these files or directories are not ingested into the Azure Storage via the Data Box service.

+- Don't copy data directly into the disks. Copy data to pre-created *BlockBlob*, *PageBlob*, and *AzureFile* folders.

+- Any empty directory hierarchy (without any files) created under *BlockBlob* and *PageBlob* folders isn't uploaded.

+- If there are any errors when uploading data to Azure, an error log is created in the target storage account. The path to this error log is available in the portal when the upload is complete and you can review the log to take corrective action. Don't delete data from the source without verifying the uploaded data.

+- File metadata and NTFS permissions aren't preserved when the data is uploaded to Azure Files. For example, the *Last modified* attribute of the files won't be kept when the data is copied.

+ - You can only have one managed disk with a given name in a resource group across all the precreated folders and across all the Data Box Disk. This implies that the VHDs uploaded to the precreated folders should have unique names. Make sure that the given name doesn't match an already existing managed disk in a resource group. If VHDs have same names, then only one VHD is converted to managed disk with that name. The other VHDs are uploaded as page blobs into the staging storage account.

+ - Only the fixed VHDs can be uploaded to create managed disks. Dynamic VHDs, differencing VHDs or VHDX files aren't supported.

+ - Non VHD files copied to the precreated managed disk folders won't be converted to a managed disk.

+| Block blob | 7 TiB |

+| Page blob | 4 TiB <br> Every file uploaded in page blob format must be 512 bytes aligned (an integral multiple), else the upload fails. <br> VHD and VHDX are 512 bytes aligned. |

+| Azure Files | 1 TiB |

+| Managed disks | 4 TiB <br> For more information on size and limits, see: <li>[Scalability targets of Standard SSDs](../virtual-machines/disks-types.md#standard-ssds)</li><li>[Scalability targets of Premium SSDs](../virtual-machines/disks-types.md#standard-hdds)</li><li>[Scalability targets of Standard HDDs](../virtual-machines/disks-types.md#premium-ssds)</li><li>[Pricing and billing of managed disks](../virtual-machines/disks-types.md#billing)</li>

+<!--| Entity | Conventions |

+| Blob names for block blob and page blob | Blob names are case-sensitive and can contain any combination of characters. <br> A blob name must be between 1 to 1,024 characters long. <br> Reserved URL characters must be properly escaped. <br>The number of path segments comprising the blob name cannot exceed 254. A path segment is the string between consecutive delimiter characters (for example, the forward slash '/') that correspond to the name of a virtual directory. | -->

+| Managed disk names | <li> The name must be 1 to 80 characters long. </li><li> The name must begin with a letter or number, end with a letter, number or underscore. </li><li> The name may contain only letters, numbers, underscores, periods, or hyphens. </li><li> The name shouldn't have spaces or `/`. |

+|What AWS data resources can I discover? | **Object storage:**<br /><br />AWS S3 buckets<br/><br/> Defender for Cloud can discover KMS-encrypted data, but not data encrypted with a customer-managed key.<br /><br />**Databases**<br /><br />Any flavor of RDS instances <br /><br />Unsupported scenarios: <br />- You can't share a DB snapshot that uses an option group with permanent or persistent options, except for Oracle DB instances that have the **Timezone** or **OLS** option (or both). [Learn more](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ShareSnapshot.html) |

+ServiceNow is now integrated with Microsoft Defender for Cloud, which enables customers to connect ServiceNow to their Defender for Cloud environment to prioritize remediation of recommendations that impact your business. Microsoft Defender for Cloud integrates with the ITSM module (incident management). As part of this connection, customers can create/view ServiceNow tickets (linked to recommendations) from Microsoft Defender for Cloud.

+As part of the integration, you can create and monitor tickets in ServiceNow directly from Microsoft Defender for Cloud:

+- **Incident**: An incident is an unplanned interruption of reduction in the quality of an IT service. It can be reported by a user or monitoring system. ServiceNow’s incident management module helps IT teams track and manage incidents, from initial reporting to resolution.

+- **Problem**: A problem is the underlying cause of one or more incidents. ItΓÇÖs often a recurring or persistent issue that needs to be addressed to prevent future incidents.

+- **Change**: A change is a planned alternation or addition to an IT service or its supporting infrastructure. A change management module helps IT teams plan, approve, and execute changes in a controlled and systematic manner. It minimizes the risk of service disruptions and maintains service quality.

+To onboard ServiceNow to Defender for Cloud, you need a Client ID and Client Secret for the ServiceNow instance. If you don't have a Client ID and Client Secret, follow these steps to create them:

+1. Browse to **System OAuth**, and select **Application Registry**.

+1. In the upper right corner, select **New**.

+1. Complete the OAuth Client application details to create a Client ID and Client

+ - **Refresh Token Lifespan**: Time in seconds that the refresh token is valid.

+1. Select **Submit** to save the API Client ID and Client Secret.

+1. Sign in to [the Azure portal](https://aka.ms/integrations) as at least a Security Admin and navigate to **Microsoft Defender for Cloud** > **Environment settings**.

+1. Select **Integrations** to connect your environment to a third-party ticketing system, which is ServiceNow in this scenario.

+ Based on your permissions, you can create an **Integration** by using:

+ - Connector

+ For simplicity, We recommend creating the integration on the higher scope based on the user permissions. For example, if you have permission for a management group, you could create a single integration of a management group rather than create integrations in each one of the subscriptions.

+ If you select the drop-down menu, you see **Assigned to**, **Caller**, and **Short description** are grayed out because those are necessary fields. You can choose other fields such as **Assignment group**, **Description**, **Impact**, or **Urgency**.

+1. A notice appears after successful creation of integration.

+You can review the integrations in ARG both on the individual integration or on all integrations.

+You can review an integration, or all integrations, in [Azure Resource Graph (ARG)](/azure/governance/resource-graph), an Azure service that gives you the ability to query across multiple subscriptions. On the Integrations page, select **Open in ARG** to explore the details in ARG.

+1. Navigate to **Microsoft Defender for Cloud** > **Recommendations** and select any recommendation with unhealthy resources that you want to create a ServiceNow ticket for and assign an owner to.

+1. Select the resource from the unhealthy resources and select **Create assignment**.

+ >In ServiceNow, there are several types of tickets that can be used to manage and track different types of incidents, requests, and tasks. Only incident, change request, and problem are supported with this integration.

+ - **Assigned to**: Choose the owner whom you would like to assign the affected recommendation to.

+ - **Caller**: Represents the user defining the assignment.

+ - **Description and Short Description**: If you chose a default integration earlier, description, and short description are automatically completed.

+ - **Remediation timeframe**: Choose the remediation timeframe to desired deadline for the recommendation to be remediated.

+ Select the Ticket ID to go to the newly created incident in the ServiceNow portal.

+ >When integration is deleted, all the assignments will be deleted. It could take up to 24 hrs.

+- A verification that a ticket state is still **In progress**. If the ticket state is changed to **Resolved**, **Canceled**, or **Closed** in ServiceNow, the change is synchronized to Microsoft Defender for Cloud and delete the assignment.

+- When the ticket owner is changed in ServiceNow, the assignment owner is updated in Microsoft Defender for Cloud.

+| November 22 | [Enable permissions management with Defender for Cloud (Preview)](#enable-permissions-management-with-defender-for-cloud-preview) |

+| November 22 | [Defender for Cloud integration with ServiceNow](#defender-for-cloud-integration-with-servicenow) |

+| November 20| [General Availability of the autoprovisioning process for SQL Servers on machines plan](#general-availability-of-the-autoprovisioning-process-for-sql-servers-on-machines-plan)|

+### Enable permissions management with Defender for Cloud (Preview)

+November 22, 2023

+Microsoft now offers both Cloud-Native Application Protection Platforms (CNAPP) and Cloud Infrastructure Entitlement Management (CIEM) solutions with [Microsoft Defender for Cloud (CNAPP)](defender-for-cloud-introduction.md) and [Microsoft Entra Permissions Management](/entra/permissions-management/) (CIEM).

+Security administrators can get a centralized view of their unused or excessive access permissions within Defender for Cloud.

+Security teams can drive the least privilege access controls for cloud resources and receive actionable recommendations for resolving permissions risks across Azure, AWS, and GCP cloud environments as part of their Defender Cloud Security Posture Management (CSPM), without any extra licensing requirements.

+Learn how to [Enable Permissions Management in Microsoft Defender for Cloud (Preview)](enable-permissions-management.md).

+### Defender for Cloud integration with ServiceNow

+November 22, 2023

+ServiceNow is now integrated with Microsoft Defender for Cloud, which enables customers to connect ServiceNow to their Defender for Cloud environment to prioritize remediation of recommendations that affect your business. Microsoft Defender for Cloud integrates with the ITSM module (incident management). As part of this connection, customers are able to create/view ServiceNow tickets (linked to recommendations) from Microsoft Defender for Cloud.

+You can learn more about [Defender for Cloud's integration with ServiceNow](integration-servicenow.md).

+### General Availability of the autoprovisioning process for SQL Servers on machines plan

+This article explains how to add a resource group to your Microsoft Defender for IoT solution. To learn more about resource groups, see [Manage Azure resource groups by using the Azure portal](../../azure-resource-manager/management/manage-resource-groups-portal.md).

+After [onboarding](onboard-sensors.md) a new OT network sensor to Microsoft Defender for IoT, you might want to define several settings directly on the OT sensor console, such as [adding local users](manage-users-sensor.md) or [connecting to an on-premises management console](ot-deploy/connect-sensors-to-management.md).

+The OT sensor settings listed in this article are also available directly from the Azure portal. Use the Azure portal to apply these settings in bulk across multiple cloud-connected OT sensors at a time, or across all cloud-connected OT sensors in a specific site or zone. This article describes how to view and configure view OT network sensor settings from the Azure portal.

+Define a new setting whenever you want to define a specific configuration for one or more OT network sensors. For example, if you want to define bandwidth caps for all OT sensors in a specific site or zone, or define them for a single OT sensor at a specific location in your network.

+ |**Setting** | Define the values for your selected setting type.<br>For details about the options available for each setting type, find your selected setting type in the [Sensor setting reference](#sensor-setting-reference) below. |

+ |**Review and create** | Check the selections made for your setting. <br><br>If your new setting replaces an existing setting, a :::image type="icon" source="media/how-to-manage-individual-sensors/warning-icon.png" border="false"::: warning is shown to indicate the existing setting.<br><br>When you're satisfied with the setting's configuration, select **Create**. |

+By default, if you configure any settings from the Azure portal, all settings that are configurable from both the Azure portal and the OT sensor are set to read-only on the OT sensor itself. For example, if you configure a VLAN from the Azure portal, then bandwidth cap, subnet, and VLAN settings are *all* set to read-only, and blocked from modifications on the OT sensor.

+If you're in a situation where the OT sensor is disconnected from Azure, and you need to modify one of these settings, you must first gain write access to those settings.

+|**Active Directory Groups** | Select **+ Add** to add an Active Directory group to each permission level listed, as needed. <br><br> When you enter a group name, make sure that you enter the group name exactly as defined in your Active Directory configuration on the LDAP server. You use these group names when adding new sensor users with Active Directory.<br><br> Supported permission levels include **Read-only**, **Security Analyst**, **Admin**, and **Trusted Domains**. |

+**Minimum required for a stable connection to Azure**: 350 Kbps. At this minimum setting, connections to the sensor console might be slower than usual.

+To focus the Azure device inventory on devices that are in your IoT/OT scope, you need to manually edit the subnet list to include only the locally monitored subnets that are in your IoT/OT scope. Once the subnets are configured, the network location of the devices is shown in the *Network location* (Public preview) column in the Azure device inventory. All of the devices associated with the listed subnets are displayed as *local*, while devices associated with detected subnets not included in the list are displayed as *routed*.

+1. Under **Subnets**, review the configured subnets. To focus the device inventory and view local devices in the inventory, delete any subnets that are not in your IoT/OT scope by selecting the options menu (...) on any subnet you want to delete.

+> Make sure to [assign your licenses to specific users](/microsoft-365/admin/manage/assign-licenses-to-users) to start using them.

+- [How to configure Dev Box Hibernation (preview)](how-to-configure-dev-box-hibernation.md)

+- **Message**: Deployed failure: Index cannot be created on computed column '{0}' of table '{1}' because the underlying object '{2}' has a different owner. Object element: {3}.

+

+ ` Sample Generated Script:: IF NOT EXISTS (SELECT * FROM sys.indexes WHERE object_id = OBJECT_ID(N'[Sales].[Customer]') AND name = N'AK_Customer_AccountNumber') CREATE UNIQUE NONCLUSTERED INDEX [AK_Customer_AccountNumber] ON [Sales].[Customer] ( [AccountNumber] ASC )WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, SORT_IN_TEMPDB = OFF, IGNORE_DUP_KEY = OFF, DROP_EXISTING = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) `

+- **Cause**: All function references in the computed column must have the same owner as the table.

+- **Recommendation**: Check the doc [Ownership Requirement](https://learn.microsoft.com/sql/relational-databases/indexes/indexes-on-computed-columns?view=sql-server-ver16#ownership-requirements).

+ Title: 'Quickstart: Create a public DNS zone and record - Azure portal'

+description: Use this step-by-step quickstart guide to learn how to create an Azure public DNS zone and record using the Azure portal.

+#Customer intent: As an administrator or developer, I want to learn how to configure Azure DNS using the Azure portal so I can use Azure DNS for my public zone.

+In this quickstart, you create a test domain, and then create an address record to resolve *www* to the IP address *10.10.10.10*.

+> [!IMPORTANT]

+> The names and IP addresses in this quickstart are examples that do not represent real-world scenarios. The private IP address 10.10.10.10 is used here with a public DNS zone for testing purposes.

+An Azure account with an active subscription is required. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+1. At the upper left, select **Create a resource**, enter **DNS zone** into **Search services and marketplace** and then select **DNS zone**.

+2. On the **DNS zone** page, select **Create**.

+ 

+3. On the **Create DNS zone** page, type or select the following values:

+ - **Name**: Type *contoso.xyz* for this quickstart example. The DNS zone name can be any value that isn't already configured on the Azure DNS servers. A real-world value would be a domain that you bought from a domain name registrar.

+ - **Resource group location**: Select a location for the new resource group. In this example, the location selected is **West US**.

+4. Select **Review create** and then select **Create**.

+ 

+Next, DNS records are created for your domain inside the DNS zone. A new address record, known as an '**A**' record, is created to resolve a host name to an IPv4 address.

+2. At the top of the **contoso.xyz** DNS zone page, select **+ Record set**.

+3. In the **Add a record set** window, enter or select the following values:

+ - **Name**: Type *www*. This record name is the host name that you want to resolve to the specified IP address.

+ - **TTL unit**: Select **Hours**. The time unit for the **TTL** entry is specified here.

+ - **IP address**: For this quickstart example, type *10.10.10.10*. This value is the IP address that the record name resolves to. In a real-world scenario, you would enter the public IP address for your web server.

+4. Select **OK** to create the A record.

+Since this quickstart is just for quick testing purposes, there's no need to configure the Azure DNS name servers at a domain name registrar. In a real production domain, you must enable users on the Internet to resolve the host name and connect to your web server or app. To accomplish this task, visit your domain name registrar and replace the name server records with the Azure DNS name servers. For more information, see [Tutorial: Host your domain in Azure DNS](dns-delegate-domain-azure-dns.md#delegate-the-domain).

+1. On the **contoso.xyz** DNS zone page, copy one of the name server names from the name server list. For example: ns1-32.azure-dns.com.

+ [  ](./media/dns-getstarted-portal/view-zone.png#lightbox)

+ nslookup www.contoso.xyz ns1-32.azure-dns.com.

+ 

+> [!NOTE]

+> Azure DNS doesn't currently support the use of a dot (**.**) before the '**@**' in the SOA hostmaster mailbox entry. For example: `john.smith@contoso.xyz` (converted to john.smith.contoso.xyz) and `john\.smith@contoso.xyz` are not allowed.

+ Title: Authentication concepts in Microsoft Azure Data Manager for Energy

+description: This article describes the various concepts regarding the authentication in Azure Data Manager for Energy.

+# Authentication concepts in Azure Data Manager for Energy

+## Service Principals

+In the Azure Data Manager for Energy instance,

+1. No Service Principals are created.

+2. The app-id is used for API access. The same app-id is used to provision ADME instance.

+3. The app-id doesn't have access to infrastructure resources.

+4. The app-id also gets added as OWNER to all OSDU groups by default.

+5. For service-to-service (S2S) communication, ADME uses MSI (msft service identity).

+In the OSDU instance,

+1. Terraform scripts create two Service Principals:

+2. The first Service Principal is used for API access. It can also manage infrastructure resources.

+3. The second Service Principal is used for service-to-service (S2S) communications.

+Access management is a critical function for any service or resource. The entitlement service lets you control who can use your Azure Data Manager for Energy, what they can see or change, and which services or data they can use.

+All group identifiers (emails) are of form {groupType}.{serviceName|resourceName}.{permission}@{partition}.{domain}.com. A group naming convention is adopted by OSDU such that the group's name starts with

+1. the word "data." for data groups;

+2. the word "service." for service groups;

+3. the word "users." for user groups. There's one exception for "users" group created when a new data partition is provisioned. For example, for data partition `opendes`, the group `users@opendes.dataservices.energy` is created.

+For each OSDU group, you can either add a user as an OWNER or a MEMBER.

+1. If you're an OWNER of an OSDU group, then you can add or remove the members of that group or delete the group.

+2. If you're a MEMBER of an OSDU group, you can view, edit, or delete the service or data depending on the scope of the OSDU group. For example, if you're a MEMBER of service.legal.editor OSDU group, you can call the APIs to change the legal service.

+A full list of entitlements API endpoints can be found in [OSDU entitlement service](https://community.opengroup.org/osdu/platform/security-and-compliance/entitlements/-/blob/release/0.15/docs/tutorial/Entitlements-Service.md#entitlement-service-api). A few illustrations of how to use Entitlement APIs are available in the [How to manage users](how-to-manage-users.md).

+In this article, you'll learn how to manage users and their memberships in OSDU groups in Azure Data Manager for Energy. [Entitlements APIs](https://community.opengroup.org/osdu/platform/security-and-compliance/entitlements/-/tree/master/) are used to add or remove users to OSDU groups and to check the entitlements when the user tries to access the OSDU services or data. For more information about OSDU groups, see [entitlement services](concepts-entitlements.md).

+1. Create an Azure Data Manager for Energy instance using the tutorial at [How to create Azure Data Manager for Energy instance](quickstart-create-microsoft-energy-data-services-instance.md).

+2. Generate the access token needed to call the Entitlements APIs.

+3. Get various parameters of your instance such as client-id, client-secret, etc.

+4. Keep all these parameter values handy as they will be needed for executing different user management requests via the Entitlements API.

+## Fetch Parameters

+1. Navigate to the Microsoft Entra account for your organization. You can search for "Microsoft Entra ID" in the Azure portal's search bar.

+2. Locate `tenant-id` under the basic information section in the *Overview* tab.

+3. Copy the `tenant-id` and paste it into an editor to be used later.

+It's the same value that you used to register your application during the provisioning of your [Azure Data Manager for Energy instance](quickstart-create-microsoft-energy-data-services-instance.md). It is often referred to as `app-id`.

+1. Find the `client-id` in the *Essentials* pane of Azure Data Manager for Energy *Overview* page.

+2. Copy the `client-id` and paste it into an editor to be used later.

+3. Currently, one Azure Data Manager for Energy instance allows one app-id to be as associated with one instance.

+> The 'client-id' that is passed as values in the entitlement API calls needs to be the same that was used for provisioning your Azure Data Manager for the Energy instance.

+A `client-secret` is a string value your app can use in place of a certificate to identify itself. It is sometimes referred to as an application password.

+1. Navigate to *App Registrations*.

+2. Open 'Certificates & secrets' under the *Manage* section.

+3. Create a `client-secret` for the `client-id` that you used to create your Azure Data Manager for Energy instance.

+4. Add one now by clicking on *New Client Secret*.

+5. Record the secret's `value` for later use in your client application code.

+6. The Service Principal [SPN] of the app id and client secret has the Infra Admin access to the instance.

+> Don't forget to record the secret's value. This secret value is never displayed again after you leave this page of 'client secret' creation.

+#### Find the `URL` for your Azure Data Manager for Energy instance

+1. Navigate to your Azure Data Manager for Energy *Overview* page on the Azure portal.

+2. Copy the URI from the essentials pane.

+#### Find the `data-partition-id`

+1. You have two ways to get the list of data partitions in your Azure Data Manager for Energy instance. '

+2. One option is to navigate the *Data Partitions* menu item under the Advanced section of your Azure Data Manager for Energy UI.

+3. Another option is to click on the *view* below the *data partitions* field in the essentials pane of your Azure Data Manager for Energy *Overview* page.

+1. Run the below curl command in Azure Cloud Bash after replacing the placeholder values with the corresponding values found earlier in the above steps.

+2. Copy the `access_token` value from the response. You'll need it to pass as one of the headers in all calls to the Entitlements APIs.

+## Fetch OID

+`object-id` (OID) is the Microsoft Entra user Object ID.

+1. Find the 'object-id' (OID) of the user(s) first. If you are managing an application's access, you must find and use the application ID (or client ID) instead of the OID.

+2. Input the `object-id` (OID) of the users (or the application or client ID if managing access for an application) as parameters in the calls to the Entitlements API of your Azure Data Manager for Energy Instance.

+## Get the list of all available groups

+Run the below curl command in Azure Cloud Bash to get all the groups that are available for your Azure Data Manager for the Energy instance and its data partitions.

+## Add user(s) to a OSDU group

+1. Run the below curl command in Azure Cloud Bash to add the user(s) to the "Users" group using the Entitlement service.

+2. The value to be sent for the param **"email"** is the **Object_ID (OID)** of the user and not the user's email.

+> [!IMPORTANT]

+> The app-id is the default OWNER of all the groups.

+## Add user(s) to an entitlements group

+1. Run the below curl command in Azure Cloud Bash to add the user(s) to an entitlement group using the Entitlement service.

+2. The value to be sent for the param **"email"** is the **Object_ID (OID)** of the user and not the user's email.

+Consider an Azure Data Manager for Energy instance named "medstest" with a data partition named "dp1".

+## Get entitlements groups for a given user

+1. Run the below curl command in Azure Cloud Bash to get all the groups associated with the user.

+## Delete entitlement groups of a given user

+1. Run the below curl command in Azure Cloud Bash to delete a given user from a given data partition.

+2. As stated above, **DO NOT** delete the OWNER of a group unless you have another OWNER who can manage users in that group.

+Create a legal tag for your data partition.

+> - Authenticating and authorizing users or applications using Microsoft Entra identities provides superior security and ease of use over key-based and shared access signatures (SAS) authentication. With Microsoft Entra ID, there is no need to store secrets used for authentication in your code and risk potential security vulnerabilities. We strongly recommend you use Microsoft Entra ID with your Azure Event Grid event publishing applications. For more information, see [Authenticate publishing clients using Microsoft Entra ID](authenticate-with-microsoft-entra-id.md).

+The [Microsoft Identity](/entra/identity-platform/v2-overview) platform provides an integrated authentication and access control management for resources and applications that use Microsoft Entra ID as their identity provider. Use the Microsoft Identity platform to provide authentication and authorization support in your applications. It's based on open standards such as OAuth 2.0 and OpenID Connect and offers tools and open-source libraries that support many authentication scenarios. It provides advanced features such as [Conditional Access](/entra/identity/conditional-access/overview) that allows you to set policies that require multifactor authentication or allow access from specific locations, for example.

+An advantage that improves your security stance when using Microsoft Entra ID is that you don't need to store credentials, such as authentication keys, in the code or repositories. Instead, you rely on the acquisition of OAuth 2.0 access tokens from the Microsoft Identity platform that your application presents when authenticating to a protected resource. You can register your event publishing application with Microsoft Entra ID and obtain a service principal associated with your app that you manage and use. Instead, you can use [Managed Identities](/entra/identity/managed-identities-azure-resources/overview), either system assigned or user assigned, for an even simpler identity management model as some aspects of the identity lifecycle are managed for you.

+[Role-based access control (RBAC)](/entra/identity-platform/custom-rbac-for-developers) allows you to configure authorization in a way that certain security principals (identities for users, groups, or apps) have specific permissions to execute operations over Azure resources. This way, the security principal used by a client application that sends events to Event Grid must have the RBAC role **EventGrid Data Sender** associated with it.

+Regardless of the security principal used, a managed identity or an application security principal, your client uses that identity to authenticate before Microsoft Entra ID and obtain an [OAuth 2.0 access token](/entra/identity-platform/access-tokens) that's sent with requests when sending events to Event Grid. That token is cryptographically signed and once Event Grid receives it, the token is validated. For example, the audience (the intended recipient of the token) is confirmed to be Event Grid (`https://eventgrid.azure.net`), among other things. The token contains information about the client identity. Event Grid takes that identity and validates that the client has the role **EventGrid Data Sender** assigned to it. More precisely, Event Grid validates that the identity has the ``Microsoft.EventGrid/events/send/action`` permission in an RBAC role associated to the identity before allowing the event publishing request to complete.

+To authenticate your event publishing client using managed identities, first decide on the hosting Azure service for your client application and then enable system assigned or user assigned managed identities on that Azure service instance. For example, you can enable managed identities on a [VM](/entr?tabs=dotnet).

+Besides managed identities, another identity option is to create a security principal for your client application. To that end, you need to register your application with Microsoft Entra ID. Registering your application is a gesture through which you delegate identity and access management control to Microsoft Entra ID. Follow the steps in section [Register an application](/entra/identity-platform/quickstart-register-app#register-an-application) and in section [Add a client secret](/entra/identity-platform/quickstart-register-app#add-a-client-secret). Make sure to review the [prerequisites](/entra/identity-platform/quickstart-register-app#prerequisites) before starting.

+> When you register an application in the portal, an [application object](/entra/identity-platform/app-objects-and-service-principals?tabs=browser#application-object) and a [service principal](/entra/identity-platform/app-objects-and-service-principals?tabs=browser#service-principal-object) are created automatically in your home tenant. Alternatively, you can use Microsot Graph to register your application. However, if you register or create an application using the Microsoft Graph APIs, creating the service principal object is a separate step.

+To send events to a topic, domain, or partner namespace, you can build the client in the following way. The API version that first provided support for Microsoft Entra authentication is ``2018-01-01``. Use that API version or a more recent version in your application.

+Microsoft Entra authentication provides a superior authentication support than that's offered by access key or Shared Access Signature (SAS) token authentication. With Microsoft Entra authentication, the identity is validated against Microsoft Entra identity provider. As a developer, you won't have to handle keys in your code if you use Microsoft Entra authentication. You'll also benefit from all security features built into the Microsoft Identity platform, such as [Conditional Access](/entra/identity/conditional-access/overview) that can help you improve your application's security stance.

+ :::image type="content" source="./media/authenticate-with-microsoft-entra-id/existing-topic-local-auth.png" alt-text="Screenshot showing the Overview page of an existing topic.":::

+ :::image type="content" source="./media/authenticate-with-microsoft-entra-id/local-auth-popup.png" alt-text="Screenshot showing the Local Authentication window.":::

+- Learn about [managed identities](/entra/identity/managed-identities-azure-resources/overview)

+- Learn about [applications and service principals](/entra/identity-platform/app-objects-and-service-principals)

+- Learn about [registering an application with the Microsoft Identity platform](/entra/identity-platform/quickstart-register-app).

+- Learn about [application and service principal objects in Microsoft Entra ID](/entra/identity-platform/app-objects-and-service-principals).

+- Learn about [Microsoft Identity Platform access tokens](/entra/identity-platform/access-tokens).

+- Learn about [OAuth 2.0 authentication code flow and Microsoft Identity Platform](/entra/identity-platform/v2-oauth2-auth-code-flow)