+|`APP_CLIENT_SECRET`|The client secret value for the web app you created in [step 2.2](#step-22-create-a-web-app-client-secret) |

+|`APP_CLIENT_SECRET`|The client secret value for the web app you created in [step 2.4](#step-24-create-a-client-secret) |

+|`CLIENT_SECRET`| The client secret value you created in [step 2.2](#step-22-create-a-web-app-client-secret). To help increase security, consider storing it instead in an environment variable, as recommended in the comments. |

+1. For **Response type**, select **id_token**. So, the **Client secret** value isn't needed. Learn more about use of [Client ID and secret](identity-provider-generic-openid-connect.md#client-id-and-secret) when adding a generic OpenID Connect identity provider.

+1. For **Client secret**, enter the client secret value that you previously recorded.

+1. In **Secret**, enter your client secret value that you recorded earlier.

+ Title: Configure TheAccessHub Admin Tool by using Azure Active Directory B2C

+description: In this tutorial, configure TheAccessHub Admin Tool by using Azure Active Directory B2C to address customer account migration and customer service request (CSR) administration.

+# Configure TheAccessHub Admin Tool by using Azure Active Directory B2C

+In this tutorial, we provide guidance on how to integrate Azure Active Directory B2C (Azure AD B2C) with [TheAccessHub Admin Tool](https://n8id.com/products/theaccesshub-admintool/) from N8 Identity. This solution addresses customer account migration and customer service request (CSR) administration.

+This solution is suited for you if you have one or more of the following needs:

+- You have an existing site and you want to migrate to Azure AD B2C. However, you're struggling with migration of your customer accounts, including passwords.

+- You need a tool for your CSR to administer Azure AD B2C accounts.

+## Prerequisites

+- An [Azure AD B2C tenant](./tutorial-create-tenant.md). The tenant must be linked to your Azure subscription.

+- A TheAccessHub Admin Tool environment. Contact [N8 Identity](https://n8id.com/contact/) to provision a new environment.

+- (Optional:) Connection and credential information for any databases or Lightweight Directory Access Protocols (LDAPs) that you want to migrate customer data from.

+- (Optional:) A configured Azure AD B2C environment for using [custom policies](./tutorial-create-user-flows.md?pivots=b2c-custom-policy), if you want to integrate TheAccessHub Admin Tool into your sign-up policy flow.

+The TheAccessHub Admin Tool runs like any other application in Azure. It can run in either N8 Identity's Azure subscription or the customer's subscription. The following architecture diagram shows the implementation.

+

+| 1. | Each user arrives at a login page. The user creates a new account and enters information on the page. Azure AD B2C collects the user attributes.

+| 2. | Azure AD B2C calls the TheAccessHub Admin Tool and passes on the user attributes.

+| 4. | User records are synced from the database to TheAccessHub Admin Tool.

+| 7. |Based on the success/failure response from the TheAccessHub Admin Tool, Azure AD B2C sends a customized welcome email to users.

+## Create a Global Administrator in your Azure AD B2C tenant

+The TheAccessHub Admin Tool requires permissions to act on behalf of a Global Administrator to read user information and conduct changes in your Azure AD B2C tenant. Changes to your regular administrators won't affect TheAccessHub Admin Tool's ability to interact with the tenant.

+To create a Global Administrator:

+1. In the Azure portal, sign in to your Azure AD B2C tenant as an administrator. Go to **Azure Active Directory** > **Users**.

+2. Select **New User**.

+3. Choose **Create User** to create a regular directory user and not a customer.

+4. Complete the identity information form:

+ a. Enter the username, such as **theaccesshub**.

+ b. Enter the account name, such as **TheAccessHub Service Account**.

+5. Select **Show Password** and copy the initial password for later use.

+6. Assign the Global Administrator role:

+ a. For **User**, select the user's current role to change it.

+ b. Select the **Global Administrator** record.

+ c. Select **Create**.

+TheAccessHub Admin Tool uses the Microsoft Graph API to read and make changes to your directory. It acts as a Global Administrator in your tenant. TheAccessHub Admin Tool needs additional permission, which you can grant from within the tool.

+To authorize TheAccessHub Admin Tool to access your directory:

+1. Log in to TheAccessHub Admin Tool by using the credentials that N8 Identity has provided.

+2. Go to **System Admin** > **Azure AD B2C Config**.

+3. Select **Authorize Connection**.

+4. In the new window, sign in with your Global Administrator account. You might be asked to reset your password if you're signing in for the first time with the new service account.

+## Configure a new CSR user by using your enterprise identity

+Create a CSR/Helpdesk user who accesses TheAccessHub Admin Tool by using their existing enterprise Azure Active Directory credentials.

+To configure a CSR/Helpdesk user with single sign-on (SSO), we recommend the following steps:

+1. Log in to TheAccessHub Admin Tool by using the credentials that N8 Identity has provided.

+2. Go to **Manager Tools** > **Manage Colleagues**.

+3. Select **Add Colleague**.

+4. For **Colleague Type**, select **Azure Administrator**.

+5. Enter the colleague's profile information:

+ a. Choose a home organization to control who has permission to manage this user.

+ b. For **Login ID/Azure AD User Name**, supply the user principal name from the user's Azure Active Directory account.

+ c. On the **TheAccessHub Roles** tab, select the managed role **Helpdesk**. It will allow the user to access the **Manage Colleagues** view. The user will still need to be placed into a group or be made an organization owner to act on customers.

+## Configure a new CSR user by using a new identity

+Create a CSR/Helpdesk user who will access TheAccessHub Admin Tool by using a new local credential that's unique to the tool. This user will be used mainly by organizations that don't use Azure Active Directory.

+To [set up a CSR/Helpdesk user](https://youtu.be/iOpOI2OpnLI) without SSO:

+1. Log in to TheAccessHub Admin Tool by using the credentials that N8 Identity has provided.

+2. Go to **Manager Tools** > **Manage Colleagues**.

+3. Select **Add Colleague**.

+4. For **Colleague Type**, select **Local Administrator**.

+5. Enter the colleague's profile information:

+ a. Choose a home organization to control who has permission to manage this user.

+ b. On the **TheAccessHub Roles** tab, select the managed role **Helpdesk**. It will allow the user to access the **Manage Colleagues** view. The user will still need to be placed into a group or be made an organization owner to act on customers.

+6. Copy the **Login ID/Email** and **One Time Password** attributes. Provide them to the new user. The user will use these credentials to log in to TheAccessHub Admin Tool. The user will be prompted to enter a new password on first login.

+7. Select **Submit**.

+Permissions to manage customer and CSR/Helpdesk users in TheAccessHub Admin Tool are managed through an organization hierarchy. All colleagues and customers have a home organization where they reside. You can assign specific colleagues or groups of colleagues as owners of organizations.

+Organization owners can manage (make changes to) colleagues and customers in organizations or suborganizations that they own. To allow multiple colleagues to manage a set of users, you can create a group that has many members. You can then assign the group as an organization owner. All of the group's members can then manage colleagues and customers in the organization.

+1. Log in to TheAccessHub Admin Tool by using the credentials that N8 Identity has provided.

+2. Go to **Organization > Manage Groups**.

+3. Select **Add Group**.

+4. Enter values for **Group name**, **Group description**, and **Group owner**.

+5. Search for and select the boxes on the colleagues you want to be members of the group, and then select **Add**.

+ If necessary, you can remove members by selecting the **x** at the end of the row.

+7. Select **Submit**.

+1. Log in to TheAccessHub Admin Tool by using the credentials that N8 Identity has provided.

+2. Go to **Organization** > **Manage Organizations**.

+3. Select **Add Organization**.

+4. Supply values for **Organization name**, **Organization owner**, and **Parent organization**:

+ a. The organization name is ideally a value that corresponds to your customer data. When you're loading colleague and customer data, if you supply the name of the organization in the load, the colleague can be automatically placed into the organization.

+ b. The owner represents the person or group that will manage the customers and colleagues in this organization and any suborganization within it.

+ c. The parent organization indicates which other organization is also responsible for this organization.

+1. Log in to TheAccessHub Admin Tool by using the credentials that N8 Identity has provided.

+2. Go to **Manager Tools** > **Tree View**.

+3. In this representation, you can visualize which colleagues and groups can manage which organizations. Modify the hierarchy by dragging organizations into parent organizations.

+## Customize the welcome notification

+While you're using TheAccessHub Admin Tool to migrate users from a previous authentication solution into Azure AD B2C, you might want to customize the user welcome notification. TheAccessHub Admin Tool sends this notification to users during migration. This message normally includes a link for users to set a new password in the Azure AD B2C directory.

+1. Log in to TheAccessHub Admin Tool by using the credentials that N8 Identity has provided.

+2. Go to **System Admin** > **Notifications**.

+3. Select the **Create Colleague** template.

+4. Select **Edit**.

+5. Alter the **Message** and **Template** fields as necessary. The **Template** field is HTML aware and can send HTML-formatted email notifications to customers.

+6. Select **Save** when you're finished.

+By using TheAccessHub Admin Tool, you can import data from various databases, LDAPs, and .csv files and then push that data to your Azure AD B2C tenant. You migrate the data by loading it into the Azure AD B2C user colleague type within TheAccessHub Admin Tool.

+If the source of data isn't Azure itself, the data will be placed into both TheAccessHub Admin Tool and Azure AD B2C. If the source of your external data isn't a simple .csv file on your machine, set up a data source before doing the data load. The following steps describe creating a data source and loading the data.

+1. Log in to TheAccessHub Admin Tool by using the credentials that N8 Identity has provided.

+2. Go to **System Admin** > **Data Sources**.

+3. Select **Add Data Source**.

+4. Supply **Name** and **Type** values for this data source.

+5. Fill in the form data, depending on your data source type.

+ For databases:

+ a. For **Type**, enter **Database**.

+ b. For **Database type**, select a database from one of the supported database types.

+ c. For **Connection URL**, enter a well-formatted JDBC connection string, such as `jdbc:postgresql://myhost.com:5432/databasename`.

+ d. For **Username**, enter the username for accessing the database.

+ e. For **Password**, enter the password for accessing the database.

+ f. For **Query**, enter the SQL query to extract the customer details, such as `SELECT * FROM mytable;`.

+ g. Select **Test Connection**. You'll see a sample of your data to ensure that the connection is working.

+ For LDAPs:

+ a. For **Type**, enter **LDAP**.

+ b. For **Host**, enter the host name or IP address for the machine in which the LDAP server is running, such as `mysite.com`.

+ c. For **Port**, enter the port number in which the LDAP server is listening.

+ d. For **SSL**, select the box if TheAccessHub Admin Tool should communicate to the LDAP securely by using SSL. We highly recommend using SSL.

+ e. For **Login DN**, enter the distinguished name (DN) of the user account to log in and do the LDAP search.

+ f. For **Password**, enter the password for the user.

+ g. For **Base DN**, enter the DN at the top of the hierarchy in which you want to do the search.

+ h. For **Filter**, enter the LDAP filter string, which will obtain your customer records.

+ i. For **Attributes**, enter a comma-separated list of attributes from your customer records to pass to TheAccessHub Admin Tool.

+ j. Select the **Test Connection**. You'll see a sample of your data to ensure that the connection is working.

+ For OneDrive:

+ a. For **Type**, select **OneDrive for Business**.

+ b. Select **Authorize Connection**.

+ c. A new window prompts you to sign in to OneDrive. Sign in with a user that has read access to your OneDrive account. TheAccessHub Admin Tool will act for this user to read .csv load files.

+6. Select **Save** when you're finished.

+1. Log in to TheAccessHub Admin Tool by using the credentials that N8 Identity has provided.

+2. Go to **System Admin** > **Data Synchronization**.

+3. Select **New Load**.

+4. For **Colleague Type**, select **Azure AD B2C User**.

+5. Select **Source**. In the pop-up dialog, select your data source. If you created a OneDrive data source, also select the file.

+6. If you don't want to create new customer accounts with this load, change the first policy (**IF colleague not found in TheAccessHub THEN**) to **Do Nothing**.

+7. If you don't want to update existing customer accounts with this load, change the second policy (**IF source and TheAccessHub data mismatch THEN**) to **Do Nothing**.

+8. Select **Next**.

+9. In **Search-Mapping configuration**, you identify how to correlate load records with customers already loaded into TheAccessHub Admin Tool.

+ Choose one or more identifying attributes in the source. Match the attributes with an attribute in TheAccessHub Admin Tool that holds the same values. If a match is found, the existing record will be overridden. Otherwise, a new customer will be created.

+

+ You can sequence a number of these checks. For example, you could check email first, and then check first and last name.

+10. On the left-side menu, select **Data Mapping**.

+11. In **Data-Mapping configuration**, assign the TheAccessHub Admin Tool attributes that should be populated from your source attributes. There's no need to map all the attributes. Unmapped attributes will remain unchanged for existing customers.

+12. If you map to the attribute `org_name` with a value that is the name of an existing organization, newly created customers will be placed in that organization.

+13. Select **Next**.

+14. If you want this load to be recurring, specify a **Daily/Weekly** or **Monthly** schedule. Otherwise, keep the default of **Now**.

+15. Select **Submit**.

+16. If you selected the **Now** schedule, a new record will be added to the **Data Synchronizations** screen immediately. After the validation phase has reached 100 percent, select the new record to see the expected outcome for the load. For scheduled loads, these records will appear only after the scheduled time.

+17. If there are no errors, select **Run** to commit the changes. Otherwise, select **Remove** from the **More** menu to remove the load. You can then correct the source data or load mappings and try again.

+ Instead, if the number of errors is small, you can manually update the records and select **Update** on each record to make corrections. Another option is to continue with any errors and resolve them later as **Support Interventions** in TheAccessHub Admin Tool.

+18. When the **Data Synchronization** record becomes 100 percent on the load phase, all the changes resulting from the load have been initiated. Customers should begin appearing or receiving changes in Azure AD B2C.

+As a one-time or ongoing operation, TheAccessHub Admin Tool can synchronize all the customer information from Azure AD B2C into TheAccessHub Admin Tool. This operation ensures that CSR/Helpdesk administrators see up-to-date customer information.

+1. Log in to TheAccessHub Admin Tool by using the credentials that N8 Identity has provided.

+2. Go to **System Admin** > **Data Synchronization**.

+3. Select **New Load**.

+4. For **Colleague Type**, select **Azure AD B2C User**.

+6. Select **Next**.

+7. For the **Data Mapping & Search** step, leave the defaults. Exception: if you map to the attribute `org_name` with a value that is the name of an existing organization, newly created customers will be placed in that organization.

+8. Select **Next**.

+9. If you want this load to be recurring, specify a **Daily/Weekly** or **Monthly** schedule. Otherwise, keep the default of **Now**. We recommend syncing from Azure AD B2C on a regular basis.

+10. Select **Submit**.

+11. If you selected the **Now** schedule, a new record will be added to the **Data Synchronizations** screen immediately. After the validation phase has reached 100 percent, select the new record to see the expected outcome for the load. For scheduled loads, these records will appear only after the scheduled time.

+12. If there are no errors, select **Run** to commit the changes. Otherwise, select **Remove** from the **More** menu to remove the load. You can then correct the source data or load mappings and try again.

+ Instead, if the number of errors is small, you can manually update the records and select **Update** on each record to make corrections. Another option is to continue with any errors and resolve them later as **Support Interventions** in TheAccessHub Admin Tool.

+13. When the **Data Synchronization** record becomes 100 percent on the load phase, all the changes resulting from the load have been initiated.

+Occasional syncing of TheAccessHub Admin Tool limits the tool's ability to keep its state up to date with Azure AD B2C. You can use TheAccessHub Admin Tool's API and Azure AD B2C policies to inform TheAccessHub Admin Tool of changes as they happen. This solution requires technical knowledge of [Azure AD B2C custom policies](./user-flow-overview.md).

+The following procedures give you example policy steps and a secure certificate to notify TheAccessHub Admin Tool of new accounts in your sign-up custom policies.

+### Create a secure credential to invoke TheAccessHub Admin Tool's API

+1. Log in to TheAccessHub Admin Tool by using the credentials that N8 Identity has provided.

+2. Go to **System Admin** > **Admin Tools** > **API Security**.

+3. Select **Generate**.

+4. Copy the **Certificate Password**.

+6. Follow [this tutorial](./secure-rest-api.md#https-client-certificate-authentication ) to add the client certificate into Azure AD B2C.

+1. Log in to TheAccessHub Admin Tool by using the credentials that N8 Identity has provided.

+2. Go to **System Admin** > **Admin Tools** > **Azure B2C Policies**.

+3. Supply your Azure AD B2C tenant domain and the two Identity Experience Framework IDs from your Identity Experience Framework configuration.

+4. Select **Save**.

+5. Select **Download** to get a .zip file with basic policies that add customers into TheAccessHub Admin Tool as customers sign up.

+6. Follow [this tutorial](./tutorial-create-user-flows.md?pivots=b2c-custom-policy) to get started with designing custom policies in Azure AD B2C.

+For more information, review the following articles:

+> At this time, Azure AD B2C supports only one HTTP header for authentication. If your RESTful call requires multiple headers, such as a client ID and client secret value, you will need to proxy the request in some manner.

+| SamlAssertionDecryption |No* | The X509 certificate (RSA key set). A SAML identity provider uses the public portion of the certificate to encrypt the assertion of the SAML response. Azure AD B2C uses the private portion of the certificate to decrypt the assertion. <br/><br/> * Required if the external IDP Encryts SAML assertions.|

+You need to store the client ID and the client secret value that you previously recorded in your Azure AD B2C tenant.

+$ClientSecret = "your-client-application-secret-here" # Insert your application's client secret value

+ Title: Evolution of Microsoft identity platform

+With the unified Microsoft identity platform (v2.0), you can write code once and authenticate any Microsoft identity into your application. For several platforms, the fully supported open-source Microsoft Authentication Library (MSAL) is recommended for use against the identity platform endpoints. MSAL is simple to use, provides great single sign-on (SSO) experiences for your users, helps you achieve high reliability and performance, and is developed using Microsoft Secure Development Lifecycle (SDL). When calling APIs, you can configure your application to take advantage of incremental consent, which allows you to delay the request for consent for more invasive scopes until the application's usage warrants this at runtime. MSAL also supports Azure Active Directory B2C, so your customers use their preferred social, enterprise, or local account identities to get single sign-on access to your applications and APIs.

+The Azure portal **[App registrations](https://go.microsoft.com/fwlink/?linkid=2083908)** experience is the one portal experience for managing all applications you've integrated with Microsoft identity platform. If you have been using the Application Registration Portal, start using the Azure portal app registration experience instead.

+For integration with Azure AD B2C (when authenticating social or local identities), you'll need to register your application in an Azure AD B2C tenant. This experience is also part of the Azure portal.

+ Title: ADAL client app error handling best practices

+ Title: Application types in v1.0

+ Title: Why update to Microsoft identity platform (v2.0)

+ Title: Azure AD for developers (v1.0)

+ Title: Azure ADAL to MSAL migration videos

+ Title: Tutorial - Web app accesses Microsoft Graph as the app

+ Title: Request custom claims (MSAL iOS/macOS)

+ Title: Microsoft identity platform overview

+For developers, the Microsoft identity platform offers integration of modern innovations in the identity and security space like passwordless authentication, step-up authentication, and Conditional Access. You don't need to implement such functionality yourself: applications integrated with the Microsoft identity platform natively take advantage of such innovations.

+ Title: Manage users excluded from Conditional Access policies

+ Title: Change signature hash algorithm for Microsoft 365 relying party trust

+ Title: Federating multiple Azure AD with single AD FS

+While developers can securely store the secrets in [Azure Key Vault](../../key-vault/general/overview.md), services need a way to access Azure Key Vault. Managed identities provide an automatically managed identity in Azure Active Directory for applications to use when connecting to resources that support Azure Active Directory (Azure AD) authentication. Applications can use managed identities to obtain Azure AD tokens without having manage any credentials.

+ Title: "Tutorial: Use a managed identity to access Azure Key Vault - Linux"

+ Title: Use managed identities from a virtual machine to access Cosmos DB

+ "identityName": "my-user-assigned"

+

+ },

+ --enable-custom-ca-trust \

+ --os-type Linux

+The AKS cluster identity needs permission to manage network resources if you use an existing subnet or resource group. For information, see [Use kubenet networking with your own IP address ranges in Azure Kubernetes Service (AKS)][use-kubenet] or [Configure Azure CNI networking in Azure Kubernetes Service (AKS)][advanced-networking]. If you are configuring your load balancer to use an [IP address in a different subnet][different-subnet], ensure the AKS cluster identity also has read access to that subnet.

+## Connect Azure Private Link service to internal load balancer (Preview)

+To attach an Azure Private Link Service to an internal load balancer, create a service manifest named `internal-lb-pls.yaml` with the service type *LoadBalancer* and the *azure-load-balancer-internal* and *azure-pls-create* annotation as shown in the example below. For more options, refer to the [Azure Private Link Service Integration](https://kubernetes-sigs.github.io/cloud-provider-azure/development/design-docs/pls-integration/) design document

+```yaml

+apiVersion: v1

+kind: Service

+metadata:

+ name: internal-app

+ annotations:

+ service.beta.kubernetes.io/azure-load-balancer-internal: "true"

+ service.beta.kubernetes.io/azure-pls-create: "true"

+spec:

+ type: LoadBalancer

+ ports:

+ - port: 80

+ selector:

+ app: internal-app

+```

+Deploy the internal load balancer using the [kubectl apply][kubectl-apply] and specify the name of your YAML manifest:

+```console

+kubectl apply -f internal-lb-pls.yaml

+```

+An Azure load balancer is created in the node resource group and connected to the same virtual network as the AKS cluster.

+When you view the service details, the IP address of the internal load balancer is shown in the *EXTERNAL-IP* column. In this context, *External* is in relation to the external interface of the load balancer, not that it receives a public, external IP address. It may take a minute or two for the IP address to change from *\<pending\>* to an actual internal IP address, as shown in the following example:

+```

+$ kubectl get service internal-app

+NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE

+internal-app LoadBalancer 10.125.17.53 10.125.0.66 80:30430/TCP 64m

+```

+Additionally, a Private Link Service object will also be created that connects to the Frontend IP configuration of the Load Balancer associated with the Kubernetes service. Details of the Private Link Service object can be retrieved as shown in the following example:

+```

+$ AKS_MC_RG=$(az aks show -g myResourceGroup --name myAKSCluster --query nodeResourceGroup -o tsv)

+$ az network private-link-service list -g ${AKS_MC_RG} --query "[].{Name:name,Alias:alias}" -o table

+Name Alias

+-- -

+pls-xyz pls-xyz.abc123-defg-4hij-56kl-789mnop.eastus2.azure.privatelinkservice

+```

+### Create a Private Endpoint to the Private Link Service

+A Private Endpoint allows you to privately connect to your Kubernetes service object via the Private Link Service created above. To do so, follow the example shown below:

+```azurecli

+$ AKS_PLS_ID=$(az network private-link-service list -g ${AKS_MC_RG} --query "[].id" -o tsv)

+$ az network private-endpoint create \

+ -g myOtherResourceGroup \

+ --name myAKSServicePE \

+ --vnet-name myOtherVNET \

+ --subnet pe-subnet \

+ --private-connection-resource-id ${AKS_PLS_ID} \

+ --connection-name connectToMyK8sService

+```

+The following image shows the process flow for creating an authorization in API Management using the grant type authorization code. For public preview no API documentation is available.

+After creating a policy fragment, you can view and update the properties of a policy fragment, or delete the policy fragment at any time.

+**To view properties of a policy fragment:**

+## Release notes

+### June 2022

+- Deprecation of policy "API App should only be accessible over HTTPS"

+- Rename of policy "Web Application should only be accessible over HTTPS" to "App Service apps should only be accessible over HTTPS"

+- Update scope of policy "App Service apps should only be accessible over HTTPS" to include all app types except Function apps

+- Update scope of policy "App Service apps should only be accessible over HTTPS" to include slots

+- Update scope of policy "Function apps should only be accessible over HTTPS" to include slots

+- Update logic of policy "App Service apps should use a SKU that supports private link" to include checks on App Service plan tier or name so that the policy supports Terraform deployments

+- Update list of supported SKUs of policy "App Service apps should use a SKU that supports private link" to include the Basic and Standard tiers

+Application Gateway enables customers to securely store TLS certificates in Azure Key Vault. When using a key vault resource, it is important that the gateway always has access to the linked key vault. If your Application Gateway is unable to fetch the certificate, the associated HTTPS listeners will be placed in a disabled state. [Learn more](../application-gateway/disabled-listeners.md).

+This article helps you understand the details of the error codes and the steps to resolve such key vault misconfigurations.

+The following sections describe the various errors you might encounter. You can verify if your gateway has any such problem by visting [**Azure Advisor**](./key-vault-certs.md#investigating-and-resolving-key-vault-errors) for your account, and use this troubleshooting article to fix the problem. We recommend configuring Azure Advisor alerts to stay informed when a key vault problem is detected for your gateway.

+**Description:** The associated user-assigned managed identity doesn't have the required permission.

+**Resolution:** Configure the access policies of your key vault to grant the user-assigned managed identity permission on secrets. You may do so in any of the following ways:

+ **Vault access policy**

+ 1. Go to the linked key vault in the Azure portal.

+ 1. Open the **Access policies** blade.

+ 1. For **Permission model**, select **Vault access policy**.

+ 1. Under **Secret Management Operations**, select the **Get** permission.

+ 1. Select **Save**.

+ **Azure role-based access control**

+ 1. Go to the linked key vault in the Azure portal.

+ 1. Open the **Access policies** blade.

+ 1. For **Permission model**, select **Azure role-based access control**.

+ 1. After this, navigate to **Access Control (IAM)** blade to configure permissions.

+ 1. **Add role assignment** for your managed identity by choosing the following<br>

+ a. **Role**: Key Vault Secrets User<br>

+ b. **Assign access to**: Managed identity<br>

+ c. **Members**: select the user-assigned managed identity which you've associated with your application gateway.<br>

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

+For more information, see [Azure role-based access control in Key Vault](../key-vault/general/rbac-guide.md).

+> [!NOTE]

+> Portal support for adding a new key vault-based certificate is currently not available when using **Azure role-based access control**. You can accomplish it by using ARM template, CLI, or PowerShell. Visit [this page](./key-vault-certs.md#key-vault-azure-role-based-access-control-permission-model) for guidance.

+**Resolution:** Create a new managed identity and use it with the key vault.

+1. Re-create a managed identity with the same name that was previously used, and under the same resource group. (**TIP**: Refer to resource Activity Logs for naming details).

+1. Go to the desired key vault resource, and set its access policies to grant this new managed identity the required permission. You can follow the same steps as mentioned under [UserAssignedIdentityDoesNotHaveGetPermissionOnKeyVault](./application-gateway-key-vault-common-errors.md#error-code-userassignedidentitydoesnothavegetpermissiononkeyvault).

+- [Understanding and fixing disabled listeners](disabled-listeners.md)

+description: Learn concepts related to the Layout API with Form Recognizer REST API usage and limits.

+The paragraph roles are best used with unstructured documents, structured documents and forms. Roles help analyze the structure of the extracted content for better semantic search and analysis.

+> Currently, Form Recognizer Studio doesn't support Microsoft Word, Excel, PowerPoint, and HTML file formats in the Read preview.

+* Supported file formats: These include JPEG/JPG, PNG, BMP, TIFF, PDF (text-embedded or scanned). Additionally, the newest API version `2022-06-30-preview` supports Microsoft Word (DOCX), Excel (XLS), PowerPoint (PPT), and HTML files.

+After you've completed the prerequisites, navigate to the [Form Recognizer Studio General Documents preview](https://formrecognizer.appliedai.azure.com).

+In the following example, we use the General Documents feature. The steps to use other pre-trained features like [W2 tax form](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=tax.us.w2), [Read](https://formrecognizer.appliedai.azure.com/studio/read), [Layout](https://formrecognizer.appliedai.azure.com/studio/layout), [Invoice](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=invoice), [Receipt](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=receipt), [Business card](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=businessCard), and [ID documents](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=idDocument) models are similar.

+ :::image border="true" type="content" source="../media/quickstarts/form-recognizer-general-document-demo-preview3.gif" alt-text="Selecting the General Document API to analysis a document in the Form Recognizer Studio.":::

+1. This step is a one-time process unless you've already selected the service resource from prior use. Select your Azure subscription, resource group, and resource. (You can change the resources anytime in "Settings" in the top menu.) Review and confirm your selections.

+1. Observe the highlighted extracted content in the document view. Hover your move over the keys and values to see details.

+1. In the output section's Result tab, browse the JSON output to understand the service response format.

+1. In the Code tab, browse the sample code for integration. Copy and download to get started.

+[CORS (Cross Origin Resource Sharing)](/rest/api/storageservices/cross-origin-resource-sharing--cors--support-for-the-azure-storage-services) needs to be configured on your Azure storage account for it to be accessible from the Form Recognizer Studio. To configure CORS in the Azure portal, you'll need access to the CORS tab of your storage account.

+1. Select the CORS tab for the storage account.

+curl -v -i POST "{endpoint}/formrecognizer/documentModels/{modelID}:analyze?api-version=2022-06-30-preview" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {key}" --data-ascii "{'urlSource': '{your-document-url}'}"

+curl -v -X GET "{endpoint}/formrecognizer/documentModels/{model name}/analyzeResults/{resultId}?api-version=2022-06-30-preview" -H "Ocp-Apim-Subscription-Key: {key}"

+curl -v -X GET "{endpoint}/formrecognizer/documentModels/{modelID}/analyzeResults/{resultId}?api-version=2022-06-30-preview" -H "Ocp-Apim-Subscription-Key: {key}"

+|**Arkas Logistics** | [**Arkas Logistics**](http://www.arkaslojistik.com.tr/) is operates under the umbrella of Arkas Holding, Turkey's leading holding institution and operating in 23 countries. During the COVID-19 crisis, the company has been able to provide outstanding, complete logistical services thanks to its focus on contactless operation and digitalization steps. Form Recognizer powers a solution that maintains the continuity of the supply chain and allows for uninterrupted service. | [Customer story](https://customers.microsoft.com/story/842149-arkas-logistics-transportation-azure-en-turkey ) |

+|**Instabase**| [**Instabase**](https://instabase.com/) is a horizontal application platform that provides best-in-class machine learning processes to help retrieve, organize, identify, and understand complex masses of unorganized data. The application platform then brings this data into business workflows as organized information. This workflow provides a repository of integrative applications to orchestrate and harness that information with the means to rapidly extend and enhance them as required. The applications are fully containerized for widespread, infrastructure-agnostic deployment. | [Customer story](https://customers.microsoft.com/en-gb/story/1376278902865681018-instabase-partner-professional-services-azure)|

+|**Old Mutual**| [**Old Mutual**](https://www.oldmutual.co.za/) is Africa's leading financial services group with a comprehensive range of investment capabilities. They're the industry leader in retirement fund solutions, investments, asset management, group risk benefits, insurance, and multi-fund management. The Old Mutual team used Microsoft Natural Language Processing and Optical Character Recognition to provide the basis for automating key customer transactions received via emails. It also offered an opportunity to identify incomplete customer requests in order to nudge customers to the correct digital channels. Old Mutual's extensible solution technology was further developed as a microservice to be consumed by any enterprise application through a secure API management layer. | [Customer story](https://customers.microsoft.com/en-us/story/1507561807660098567-old-mutual-banking-capital-markets-azure-en-south-africa)|

+|**Zelros**| [**Zelros**](http://www.zelros.com/) offers AI-powered software for the insurance industry. Insurers use the platform to take in forms and seamlessly manage customer enrollment and claims filing. The company combined its technology with Form Recognizer to automatically pull key-value pairs and text out of documents. When insurers use the platform, they can quickly process paperwork, ensure high accuracy, and redirect thousands of hours previously spent on manual data extraction toward better service. | [Customer story](https://customers.microsoft.com/story/816397-zelros-insurance-azure)|

+## Azure Attestation runs in a TEE

+To keep Microsoft operationally out of trusted computing base (TCB), critical operations of Azure Attestation like quote validation, token generation, policy evaluation and token signing are moved into an SGX enclave.

+* For more information on Hybrid Runbook Worker, see [Automation Hybrid Runbook Worker](automation-hybrid-runbook-worker.md).

+description: Know about Hybrid Runbook Worker. How to install and run the runbooks on machines in your local datacenter or cloud provider.

+- New features

+- Improvements to existing features

+ ,RECOVERY;

+,RECOVERY;

+,RECOVERY;

+The **maxmemory-reserved** setting configures the amount of memory in MB per instance in a cluster that is reserved for non-cache operations, such as replication during failover. Setting this value allows you to have a more consistent Redis server experience when your load varies. This value should be set higher for workloads that write large amounts of data. When memory is reserved for such operations, it's unavailable for storage of cached data. The minimum and maximum values on the slider are 10% and 60%, shown in megabytes. You must set the value in that range.

+The **maxfragmentationmemory-reserved** setting configures the amount of memory in MB per instance in a cluster that is reserved to accommodate for memory fragmentation. When you set this value, the Redis server experience is more consistent when the cache is full or close to full and the fragmentation ratio is high. When memory is reserved for such operations, it's unavailable for storage of cached data. The minimum and maximum values on the slider are 10% and 60%, shown in megabytes. You must set the value in that range.

+Import/Export is an Azure Cache for Redis data management operation that allows you to import and export data in the cache. You can import and export an Azure Cache for Redis Database (RDB) snapshot from a premium cache to a page blob in an Azure Storage Account. Use Import/Export to migrate between different Azure Cache for Redis instances or populate the cache with data before use.

+Export allows you to export the data stored in Azure Cache for Redis to Redis compatible RDB files. You can use this feature to move data from one Azure Cache for Redis instance to another or to another Redis server. During the export process, a temporary file is created on the VM that hosts the Azure Cache for Redis server instance. The temporary file is uploaded to the designated storage account. When the export operation completes with either a status of success or failure, the temporary file is deleted.

+| `maxmemory-reserved` | 10% of `maxmemory` | The allowed range for `maxmemory-reserved` is 10% - 60% of `maxmemory`. If you try to set these values lower than 10% or higher than 60%, they're reevaluated and set to the 10% minimum and 60% maximum. The values are rendered in megabytes. |

+| `maxfragmentationmemory-reserved` | 10% of `maxmemory` | The allowed range for `maxfragmentationmemory-reserved` is 10% - 60% of `maxmemory`. If you try to set these values lower than 10% or higher than 60%, they're reevaluated and set to the 10% minimum and 60% maximum. The values are rendered in megabytes. |

+Yes, you can import data that was exported from Azure Cache for Redis instances. You can import RDB files from any Redis server running in any cloud or environment. The environments include Linux, Windows, or cloud providers such as Amazon Web Services. To do import this data, upload the RDB file from the Redis server you want into a page or block blob in an Azure Storage Account. Then, import it into your premium Azure Cache for Redis instance. For example, you might want to export the data from your production cache and import it into a cache that is used as part of a staging environment for testing or migration.

+Azure Cache for Redis persistence features are intended to be used to restore data after data loss, not importing it to a new cache. You can't import from AOF page blob backups to a new cache. To export data for importing back to a new cache, use the export RDB feature or automatic recurring RDB export. For more information on importing to a new cache, see [Import](cache-how-to-import-export-data.md#import).

+2. On the **Create a resource** page, select **Databases** and then select **Azure Cache for Redis**.

+- Azure subscription - [create one for free](https://azure.microsoft.com/free/)

+ | **Subscription** | Select your subscription. | The subscription under which to create this new Azure Cache for Redis instance. |

+ | **Resource group** | Select a resource group, or select **Create new** and enter a new resource group name. | Name for the resource group in which to create your cache and other resources. By putting all your app resources in one resource group, you can easily manage or delete them together. |

+ | **DNS name** | Enter a globally unique name. | The cache name must be a string between 1 and 63 characters that contains only numbers, letters, or hyphens. The name must start and end with a number or letter, and can't contain consecutive hyphens. Your cache instance's *host name* will be *\<DNS name>.redis.cache.windows.net*. |

+1. Select **Availability zones**.

+1. Select **Create**.

+ It takes a while for the cache to be created. You can monitor progress on the Azure Cache for Redis **Overview** page. When **Status** shows as **Running**, the cache is ready to use.

+ > Availability zones can't be changed or enabled after a cache is created.

+A Premium cache has one primary and one replica node by default. To configure zone redundancy for more than two Availability Zones, you need to add [more replicas](cache-how-to-multi-replicas.md) to the cache you're creating.

+No, this isn't supported currently.

+When using zone redundancy configured with multiple Availability Zones, data is replicated from the primary cache node in one zone to the other node(s) in another zone(s). The data transfer charge is the network egress cost of data moving across the selected Availability Zones. For more information, see [Bandwidth Pricing Details](https://azure.microsoft.com/pricing/details/bandwidth/).

+- [Azure Cache for Redis Premium service tiers](cache-overview.md#service-tiers)

+| [Cognitive

+| [Cognitive

+For more information, see [public documentation](../cognitive-services/computer-vision/index-identity.yml), and [public API documentation](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236) for Face API.

+### [Cognitive

+ Title: How to secure an Azure Maps application with a SAS token

+description: Create an Azure Maps account secured with SAS token authentication.

+# Secure an Azure Maps account with a SAS token

+This article describes how to create an Azure Maps account with a securely stored SAS token you can use to call the Azure Maps REST API.

+- An Azure subscription. If you don't already have an Azure account, [sign up for a free one](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+- **Owner** role permission on the Azure subscription. You need the **Owner** permissions to:

+ - Create a key vault in [Azure Key Vault](../key-vault/general/basic-concepts.md).

+ - Create a user-assigned managed identity.

+ - Assign the managed identity a role.

+ - Create an Azure Maps account.

+- [Azure CLI installed](/cli/azure/install-azure-cli) to deploy the resources.

+## Example scenario: SAS token secure storage

+A SAS token credential grants the access level it specifies to anyone who holds it, until the token expires or access is revoked. Applications that use SAS token authentication should store the keys securely.

+This scenario safely stores a SAS token as a secret in Key Vault, and distributes the token into a public client. Application lifecycle events can generate new SAS tokens without interrupting active connections that use existing tokens.

+For more information about configuring Key Vault, see the [Azure Key Vault developer's guide](../key-vault/general/developers-guide.md).

+The following example scenario uses two Azure Resource Manager (ARM) template deployments to do the following steps:

+1. Create a key vault.

+1. Create a user-assigned managed identity.

+1. Assign Azure role-based access control (RBAC) **Azure Maps Data Reader** role to the user-assigned managed identity.

+1. Create an Azure Maps account with a [Cross Origin Resource Sharing (CORS) configuration](azure-maps-authentication.md#cross-origin-resource-sharing-cors), and attach the user-assigned managed identity.

+1. Create and save a SAS token in the Azure key vault.

+1. Retrieve the SAS token secret from the key vault.

+1. Create an Azure Maps REST API request that uses the SAS token.

+When you finish, you should see Azure Maps `Search Address (Non-Batch)` REST API results on PowerShell with Azure CLI. The Azure resources deploy with permissions to connect to the Azure Maps account. There are controls for maximum rate limit, allowed regions, `localhost` configured CORS policy, and Azure RBAC.

+## Azure resource deployment with Azure CLI

+The following steps describe how to create and configure an Azure Maps account with SAS token authentication. In this example, Azure CLI runs in a PowerShell instance.

+1. Sign in to your Azure subscription with `az login`.

+1. Register Key Vault, Managed Identities, and Azure Maps for your subscription.

+ ```azurecli

+ az provider register --namespace Microsoft.KeyVault

+ az provider register --namespace Microsoft.ManagedIdentity

+ az provider register --namespace Microsoft.Maps

+ ```

+1. Retrieve your Azure Active Directory (Azure AD) object ID.

+1. Create a template file named *prereq.azuredeploy.json* with the following content:

+ "description": "Specifies the object ID of a user, service principal, or security group in the Azure AD tenant for the vault. The object ID must be unique for the set of access policies. Get it by using Get-AzADUser or Get-AzADServicePrincipal cmdlets."

+1. Deploy the prerequisite resources you created in the previous step. Supply your own value for `<group-name>`. Make sure to use the same `location` as the Azure Maps account.

+ ```azurecli

+ az group create --name <group-name> --location "East US"

+ $outputs = $(az deployment group create --name ExampleDeployment --resource-group <group-name> --template-file "./prereq.azuredeploy.json" --parameters objectId=$id --query "[properties.outputs.keyVaultName.value, properties.outputs.userAssignedIdentityPrincipalId.value, properties.outputs.userIdentityResourceId.value]" --output tsv)

+ ```

+1. Create a template file *azuredeploy.json* to provision the Azure Maps account, role assignment, and SAS token.

+ "description": "Input string for new GUID associated with assigning built in role types."

+ "description": "Current Universal DateTime in ISO 8601 'u' format to use as the start of the SAS token."

+ "description": "The duration of the SAS token. P1Y is maximum, ISO 8601 format is expected."

+ "description": "The specified application's web host header origins (example: https://www.azure.com) which the Azure Maps account allows for CORS."

+ "description": "The specified SAS token allowed locations where the token may be used."

+1. Deploy the template with the ID parameters from the Key Vault and managed identity resources you created in the previous step. Supply your own value for `<group-name>`. When creating the SAS token, you set the `allowedRegions` parameter to `eastus`, `westus2`, and `westcentralus`. You can then use these locations to make HTTP requests to the `us.atlas.microsoft.com` endpoint.

+ > [!IMPORTANT]

+ > You save the SAS token in the key vault to prevent its credentials from appearing in the Azure deployment logs. The SAS token secret's `tags` also contain the start, expiry, and signing key name, to show when the SAS token will expire.

+ ```azurecli

+ az deployment group create --name ExampleDeployment --resource-group <group-name> --template-file "./azuredeploy.json" --parameters keyVaultName="$($outputs[0])" userAssignedIdentityPrincipalId="$($outputs[1])" userAssignedIdentityResourceId="$($outputs[2])" allowedOrigins="['http://localhost']" allowedRegions="['eastus', 'westus2', 'westcentralus']" maxRatePerSecond="10"

+ ```

+1. Locate and save a copy of the single SAS token secret from Key Vault.

+ ```azurecli

+ $secretId = $(az keyvault secret list --vault-name $outputs[0] --query "[? contains(name,'map')].id" --output tsv)

+ $sasToken = $(az keyvault secret show --id "$secretId" --query "value" --output tsv)

+ ```

+1. Test the SAS token by making a request to an Azure Maps endpoint. This example specifies the `us.atlas.microsoft.com` to ensure your request routes to US geography. Your SAS token allows regions within the US geography.

+ az rest --method GET --url 'https://us.atlas.microsoft.com/search/address/json?api-version=1.0&query=1 Microsoft Way, Redmond, WA 98052' --headers "Authorization=jwt-sas $($sasToken)" --query "results[].address"

+## Complete script example

+To run the complete example, the following template files must be in the same directory as the current PowerShell session:

+- *prereq.azuredeploy.json* to create the key vault and managed identity.

+- *azuredeploy.json* to create the Azure Maps account, configure the role assignment and managed identity, and store the SAS token in the key vault.

+az group create --name <group-name> --location "East US"

+$outputs = $(az deployment group create --name ExampleDeployment --resource-group <group-name> --template-file "./prereq.azuredeploy.json" --parameters objectId=$id --query "[properties.outputs.keyVaultName.value, properties.outputs.userAssignedIdentityPrincipalId.value, properties.outputs.userIdentityResourceId.value]" --output tsv)

+az deployment group create --name ExampleDeployment --resource-group <group-name> --template-file "./azuredeploy.json" --parameters keyVaultName="$($outputs[0])" userAssignedIdentityPrincipalId="$($outputs[1])" userAssignedIdentityResourceId="$($outputs[2])" allowedOrigins="['http://localhost']" allowedRegions="['eastus', 'westus2', 'westcentralus']" maxRatePerSecond="10"

+az rest --method GET --url 'https://us.atlas.microsoft.com/search/address/json?api-version=1.0&query=1 Microsoft Way, Redmond, WA 98052' --headers "Authorization=jwt-sas $($sasToken)" --query "results[].address"

+```

+## Real-world example

+You can run requests to Azure Maps APIs from most clients, like C#, Java, or JavaScript. [Postman](https://learning.postman.com/docs/sending-requests/generate-code-snippets) converts an API request into a basic client code snippet in almost any programming language or framework you choose. You can use this generated code snippet in your front-end applications.

+The following small JavaScript code example shows how you could use your SAS token with the JavaScript [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#supplying_request_options) to get and return Azure Maps information. The example uses the Azure Maps [Get Search Address](/rest/api/maps/search/get-search-address) API version 1.0. Supply your own value for `<your SAS token>`.

+For this sample to work, make sure to run it from within the same origin as the `allowedOrigins` for the API call. For example, if you provide `https://contoso.com` as the `allowedOrigins` in the API call, the HTML page that hosts the JavaScript script should be `https://contoso.com`.

+```javascript

+async function getData(url = 'https://us.atlas.microsoft.com/search/address/json?api-version=1.0&query=1 Microsoft Way, Redmond, WA 98052') {

+ const response = await fetch(url, {

+ method: 'GET',

+ mode: 'cors',

+ headers: {

+ 'Content-Type': 'application/json',

+ 'Authorization': 'jwt-sas <your SAS token>',

+ }

+ });

+ return response.json(); // parses JSON response into native JavaScript objects

+}

+postData('https://us.atlas.microsoft.com/search/address/json?api-version=1.0&query=1 Microsoft Way, Redmond, WA 98052')

+ .then(data => {

+ console.log(data); // JSON data parsed by `data.json()` call

+ });

+Deploy a quickstart ARM template to create an Azure Maps account that uses a SAS token:

+> [!div class="nextstepaction"]

+> [Create an Azure Maps account](https://github.com/Azure/azure-quickstart-templates/tree/master/quickstarts/microsoft.maps/maps-use-sas)

+For more detailed examples, see:

+|XDT_MicrosoftApplicationInsights_Mode | In default mode, only essential features are enabled to ensure optimal performance. | `disabled` or `recommended`. |

+Upgrading from version 2.8.9 happens automatically, without any extra actions. The new monitoring bits are delivered in the background to the target app service, and on application restart they'll be picked up.

+ - Confirm that `IKeyExists` is `true`. If it's `false`, add `APPINSIGHTS_INSTRUMENTATIONKEY` and `APPLICATIONINSIGHTS_CONNECTION_STRING` with your ikey GUID to your application settings.

+ - If your application refers to any Application Insights packages, enabling the App Service integration may not take effect and the data may not appear in Application Insights. An example would be if you've previously instrumented, or attempted to instrument, your app with the [ASP.NET Core SDK](./asp-net-core.md). To fix the issue, in portal turn on "Interop with Application Insights SDK" and you'll start seeing the data in Application Insights.

+1. Check that `ApplicationInsightsAgent_EXTENSION_VERSION` app setting is set to a value of "~2"

+1. Browse to https:// your site name .scm.azurewebsites.net/ApplicationInsights

+1. Within this site, confirm:

+ * The status source exists and looks like: `Status source /var/log/applicationinsights/status_abcde1234567_89_0.json`

+ * `Auto-Instrumentation enabled successfully`, is displayed. If a similar value isn't present, it means the application isn't running or isn't supported. To ensure that the application is running, try manually visiting the application url/application endpoints, which will allow the runtime information to become available.

+ * `IKeyExists` is `true`. If it's `false`, add `APPINSIGHTS_INSTRUMENTATIONKEY` and `APPLICATIONINSIGHTS_CONNECTION_STRING` with your ikey GUID to your application settings.

+#### Default website deployed with web apps doesn't support automatic client-side monitoring

+When you create a web app with the `ASP.NET Core` runtimes in Azure App Services, it deploys a single static HTML page as a starter website. The static webpage also loads an ASP.NET managed web part in IIS. This behavior allows for testing codeless server-side monitoring, but doesn't support automatic client-side monitoring.

+### PHP and WordPress aren't supported

+| `AppAlreadyInstrumented:true` | This value indicates that the extension detected that some aspect of the SDK is already present in the Application, and will back-off. It can be due to a reference to `Microsoft.ApplicationInsights.AspNetCore`, or `Microsoft.ApplicationInsights` | Remove the references. Some of these references are added by default from certain Visual Studio templates, and older versions of Visual Studio reference `Microsoft.ApplicationInsights`. |

+|`IKeyExists:false`|This value indicates that the instrumentation key isn't present in the AppSetting, `APPINSIGHTS_INSTRUMENTATIONKEY`. Possible causes: The values may have been accidentally removed, forgot to set the values in automation script, etc. | Make sure the setting is present in the App Service application settings. |

+ Title: Smart Detection of Failure Anomalies in Application Insights | Microsoft Docs

+After setting up [Application Insights for your project](./app-insights-overview.md), and if your app generates a certain minimum amount of data, Smart Detection of Failure Anomalies takes 24 hours to learn the normal behavior of your app, before it is switched on and can send alerts.

+## Delete alerts

+You can disable or delete a Failure Anomalies alert rule, but once deleted you can't create another one for the same Application Insights resource.

+Notice that if you delete an Application Insights resource, the associated Failure Anomalies alert rule doesn't get deleted automatically. You can do so manually on the Alert rules page or with the following Azure CLI command:

+```azurecli

+az resource delete --ids <Resource ID of Failure Anomalies alert rule>

+```

+Smart Detection of Failure Anomalies complements other similar but distinct features of Application Insights.

+* [metric alerts](../alerts/alerts-log.md) are set by you and can monitor a wide range of metrics such as CPU occupancy, request rates, page load times, and so on. You can use them to warn you, for example, if you need to add more resources. By contrast, Smart Detection of Failure Anomalies covers a small range of critical metrics (currently only failed request rate), designed to notify you in near real-time manner once your web app's failed request rate increases compared to web app's normal behavior. Unlike metric alerts, Smart Detection automatically sets and updates thresholds in response changes in the behavior. Smart Detection also starts the diagnostic work for you, saving you time in resolving issues.

+* [Smart Detection of performance anomalies](proactive-performance-diagnostics.md) also uses machine intelligence to discover unusual patterns in your metrics, and no configuration by you is required. But unlike Smart Detection of Failure Anomalies, the purpose of Smart Detection of performance anomalies is to find segments of your usage manifold that might be badly served - for example, by specific pages on a specific type of browser. The analysis is performed daily, and if any result is found, it's likely to be much less urgent than an alert. By contrast, the analysis for Failure Anomalies is performed continuously on incoming application data, and you will be notified within minutes if server failure rates are greater than expected.

+* [Availability web tests](./monitor-web-app-availability.md)

+ms.reviwer: cawa

+ms.reviwer: cawa

+ms.reviwer: cawa

+- [Monitoring usage and estimated costs in Azure Monitor](./usage-estimated-costs.md)

+| Traffic Comparison | This workbook lets you compare network traffic trends for a single machine or a group of machines. |

+1. Go to the **Monitor** menu in the Azure portal.

+2. Select a virtual machine.

+3. On the VM insights page, select **Performance** or **Maps** tab and then select **View Workbooks** from the link on the page. From the drop-down list, select **Go to Gallery**.

+ :::image type="content" source="media/vminsights-workbooks/workbook-dropdown-gallery-01.png" lightbox="media/vminsights-workbooks/workbook-dropdown-gallery-01.png" alt-text="Screenshot of workbook drop-down list in V M insights.":::

+To extract keyframes using the Azure Video Indexer website, upload and index your video. Once the indexing job is complete, click on the **Download** button and select **Artifacts (ZIP)**. This will download the artifacts folder to your computer (make sure to view the warning regarding artifacts below). Unzip and open the folder. In the *_KeyframeThumbnail* folder, and you will find all of the keyframes that were extracted from your video.

+When indexing with an API and the response status is OK, you get a detailed JSON output as the response content. When calling the [Get Video Index](https://api-portal.videoindexer.ai/api-details#api=Operations&operation=Get-Video-Index) API, we recommend passing `&includeSummarizedInsights=false`.

+## Get the insights using the website

+1. Choose the **Insights** tab.

+2. Select which insights you want to view (under the **View** drop-down).

+3. Go to the **Timeline** tab to see timestamped transcript lines.

+4. Select **Download** > **Insights (JSON)** to get the insights output file.

+5. If you want to download artifacts, beware of the following:

+ [!INCLUDE [artifacts](./includes/artifacts.md)]

+## Get insights produced by the API

+To retrieve the JSON file (OCR, face, keyframe, etc.) or an artifact type, call the [Get Video Index API](https://api-portal.videoindexer.ai/api-details#api=Operations&operation=Get-Video-Index).

+This API returns a URL only with a link to the specific resource type you request. An additional GET request must be made to this URL for the specific artifact. The file types for each artifact type vary depending on the artifact:

+### JSON

+* OCR

+* Faces

+* VisualContentModeration

+* LanguageDetection

+* MultiLanguageDetection

+* Metadata

+* Emotions

+* TextualContentModeration

+* AudioEffects

+* ObservedPeople

+* Labels

+### Zip file containing JPG images

+* KeyframesThumbnails

+* FacesThumbnails

+|`summarizedInsights`|Contains one [summarized insight](#summary-of-the-insights).

+## Summary of the insights

+ The page shows the video's insights.

+4. View the insights of the video.

+ [!INCLUDE [insights](./includes/insights.md)]

+ Select the **Timeline** tab to see transcripts with timelines and other information that you can choose from the **View** drop-down.

+ If you want to download artifact files, beware of the following:

+

+ [!INCLUDE [artifacts](./includes/artifacts.md)]

+

+ For more information, see [Insights output](video-indexer-output-json-v2.md).

+

+# What is Azure Web PubSub service?

+ >- You don't need to back up the databases *azure_maintenance* and *azure_sys*. Additionally, you can't back up a database already backed-up to a Backup vault.

+ >- Backup of Azure PostgreSQL servers with Private endpoint enabled is currently not supported.

+- Instant Restore tier is zonally redundant using Zone-redundant storage (ZRS) resiliency. See the [pricing details for Managed Disk Snapshots](https://azure.microsoft.com/pricing/details/managed-disks/).

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

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

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

+ Title: Certify bundled or indirectly connected devices

+description: Learn how to submit a bundled or indirectly connected device for Azure Certified Device certification. See how to configure dependencies and components.

+Many devices interact with Azure indirectly. Some communicate through another device, such as a gateway. Others connect through software as a service (SaaS) or platform as a service (PaaS) offerings.

+The [submission portal](https://certify.azure.com/) and [device catalog](https://devicecatalog.azure.com) offer support for indirectly connected devices:

+- By listing dependencies in the portal, you can specify that your device needs another device or service to connect to Azure.

+- By adding components, you can indicate that your device is part of a bundle.

+This functionality gives indirectly connected devices access to the Azure Certified Device program.

+Depending on your product line and the services that you offer or use, your situation might require a combination of dependencies and bundling. The Azure Edge Certification Portal provides a way for you to list dependencies and additional components.

+Many sensors require a device to connect to Azure. In addition, you might have multiple compatible devices that work with the sensor. **To accommodate these scenarios, certify the devices before you certify the sensor that passes information through them.**

+The following matrix provides some examples of submission combinations:

+To certify a sensor that requires a separate device:

+1. Go to the [Azure Certified Device portal](https://certify.azure.com) to certify the device and publish it to the Azure Certified Device catalog. If you have multiple, compatible pass-through devices, as in the earlier example, submit them separately for certification and catalog publication.

+1. With the sensor connected through the device, submit the sensor for certification. In the **Dependencies** tab of the **Device details** section, set the following values:

+ - **Dependency type**: Select **Hardware gateway**.

+ - **Dependency URL**: Enter the URL of the device in the device catalog.

+ - **Used during testing**: Select **Yes**.

+ - **Customer-facing comments**: Enter any comments that you'd like to provide to a user who sees the product description in the device catalog. For example, you might enter **Series 100 devices are required for sensors to connect to Azure**.

+1. If you'd like to add more devices as optional for this device:

+ 1. Select **Add additional dependency**.

+ 1. Enter **Dependency type** and **Dependency URL** values.

+ 1. For **Used during testing**, select **No**.

+ 1. For **Customer-facing comments**, enter a comment that informs your customers that other devices are available as alternatives to the device that was used during testing.

+As part of your product portfolio, you might certify a device that requires services from your company or third-party companies. To add this type of dependency:

+1. Go to the [Azure Certified Device portal](https://certify.azure.com) and start the submission process for your device.

+1. In the **Dependencies** tab, enter the following values:

+ - **Dependency type**: Select **Software service**.

+ - **Service name**: Enter the name of your product.

+ - **Dependency URL**: Enter the URL of a product page that describes the service.

+ - **Customer-facing comments**: Enter any comments that you'd like to provide to a user who sees the product description in the Azure Certified Device catalog.

+1. If you have other software, services, or hardware dependencies that you'd like to add as optional for this device, select **Add additional dependency** and enter the required information.

+With bundled product listings, a device is successfully certified in the Azure Certified Device program with other components. The device and the components are then sold together under one product listing.

+The following matrix provides some examples of bundled products. You can submit a device that includes extra components such as a temperature sensor and a camera sensor, as in submission example 1. You can also submit a touch sensor that includes a pass-through device, as in submission example 2.

+Use the component feature to add multiple components to your listing. Format the product listing image to indicate that your product comes with other components. If your bundle requires additional services for certification, identify those services through service dependencies.

+For a more detailed description of how to use the component functionality in the Azure Certified Device portal, see [Add components on the portal](./how-to-using-the-components-feature.md).

+If a device is a pass-through device with a separate sensor in the same product, create one component to reflect the pass-through device, and another component to reflect the sensor. As the following screenshot shows, you can add components to your project in the **Product details** tab of the **Device details** section:

+Configure the pass-through device first. For **Component type**, select **Customer Ready Product**. Enter the other values, as relevant for your product. The following screenshot provides an example:

+For the sensor, add a second component. For **Component type**, select **Peripheral**. For **Attachment method**, select **Discrete**. The following screenshot provides an example:

+After you've created the sensor component, enter its information. Then go to the **Sensors** tab and enter detailed sensor information, as the following screenshot shows.

+Complete the rest of your project's details, and then submit your device for certification as usual.

+>[!IMPORTANT]

+> Microsoft Azure has introduced newer generations of high-performance computing (HPC), general purpose, and memory-optimized virtual machines (VMs). For this reason, we recommend that you migrate workloads from the original H-series and H-series Promo VMs to our newer offerings by August 31, 2022. Azure [HC](../virtual-machines/hc-series.md), [HBv2](../virtual-machines/hbv2-series.md), [HBv3](../virtual-machines/hbv3-series.md), [Dv4](../virtual-machines/dv4-dsv4-series.md), [Dav4](../virtual-machines/dav4-dasv4-series.md), [Ev4](../virtual-machines/ev4-esv4-series.md), and [Eav4](../virtual-machines/eav4-easv4-series.md) VMs have greater memory bandwidth, improved networking capabilities, and better cost and performance across various HPC workloads.

+>[!IMPORTANT]

+> Microsoft Azure has introduced newer generations of high-performance computing (HPC), general purpose, and memory-optimized virtual machines (VMs). For this reason, we recommend that you migrate workloads from the original H-series and H-series Promo VMs to our newer offerings by August 31, 2022. Azure [HC](../virtual-machines/hc-series.md), [HBv2](../virtual-machines/hbv2-series.md), [HBv3](../virtual-machines/hbv3-series.md), [Dv4](../virtual-machines/dv4-dsv4-series.md), [Dav4](../virtual-machines/dav4-dasv4-series.md), [Ev4](../virtual-machines/ev4-esv4-series.md), and [Eav4](../virtual-machines/eav4-easv4-series.md) VMs have greater memory bandwidth, improved networking capabilities, and better cost and performance across various HPC workloads.

+ On August 31, 2022, we're retiring the following H-series Azure VM sizes:

+- H8

+- H8m

+- H16

+- H16r

+- H16m

+- H16mr

+- H8 Promo

+- H8m Promo

+- H16 Promo

+- H16r Promo

+- H16m Promo

+- H16mr Promo

+ Title: Best practices for using the Multivariate Anomaly Detector API

+# Best practices for using the Multivariate Anomaly Detector API

+Now you're able to run your code with MVAD APIs without any error. What could be done to improve your model accuracy?

+* As the model learns normal patterns from historical data, the training data should represent the **overall normal** state of the system. It's hard for the model to learn these types of patterns if the training data is full of anomalies. An empirical threshold of abnormal rate is **1%** and below for good accuracy.

+* In general, the **missing value ratio of training data should be under 20%**. Too much missing data may end up with automatically filled values (usually linear values or constant values) being learned as normal patterns. That may result in real (not missing) data points being detected as anomalies.

+ Anything beyond that or "before" the leading sliding window won't impact the inference result at all and may only cause performance downgrade.Anything below that may lead to an `NotEnoughInput` error.

+In a group of variables (time series), each variable may be collected from an independent source. The timestamps of different variables may be inconsistent with each other and with the known frequencies. Here's a simple example.

+We have two variables collected from two sensors which send one data point every 30 seconds. However, the sensors aren't sending data points at a strict even frequency, but sometimes earlier and sometimes later. Because MVAD will take into consideration correlations between different variables, timestamps must be properly aligned so that the metrics can correctly reflect the condition of the system. In the above example, timestamps of variable 1 and variable 2 must be properly 'rounded' to their frequency before alignment.

+`nan` indicates missing values. Obviously, the merged table isn't what you might have expected. Variable 1 and variable 2 interleave, and the MVAD model can't extract information about correlations between them. If we set `alignMode` to `Inner`, the merged table will be empty as there's no common timestamp in variable 1 and variable 2.

+### Limitations

+There are some limitations in both the training and inference APIs, you should be aware of these limitations to avoid errors.

+#### General Limitations

+* Sliding window: 28-2880 timestamps, default is 300. For periodic data, set the length of 2-4 cycles as the sliding window.

+* API calls: At most 20 API calls per minute.

+* Variable numbers: For training and asynchronized inference, at most 301 variables.

+#### Training Limitations

+* Timestamps: At most 1000000. Too few timestamps may decrease model quality. Recommend having more than 15000 timestamps.

+* Granularity: The minimum granularity is `per_second`.

+#### Asynchronized inference limitations

+* Timestamps: At most 20000, at least 1 sliding window length.

+#### Synchronized inference limitations

+* Timestamps: At most 2880, at least 1 sliding window length.

+* Detecting timestamps: From 1 to 10.

+## Model quality

+### How to deal with false positive and false negative in real scenarios?

+We have provided severity which indicates the significance of anomalies. False positives may be filtered out by setting up a threshold on the severity. Sometimes too many false positives may appear when there are pattern shifts in the inference data. In such cases a model may need to be retrained on new data. If the training data contains too many anomalies, there could be false negatives in the detection results. This is because the model learns patterns from the training data and anomalies may bring bias to the model. Thus proper data cleaning may help reduce false negatives.

+

+### How to estimate which model is best to use according to training loss and validation loss?

+Generally speaking, it's hard to decide which model is the best without a labeled dataset. However, we can leverage the training and validation losses to have a rough estimation and discard those bad models. First, we need to observe whether training losses converge. Divergent losses often indicate poor quality of the model. Second, loss values may help identify whether underfitting or overfitting occurs. Models that are underfitting or overfitting may not have desired performance. Third, although the definition of the loss function doesn't reflect the detection performance directly, loss values may be an auxiliary tool to estimate model quality. Low loss value is a necessary condition for a good model, thus we may discard models with high loss values.

+| Timestamps in training data and/or inference data weren't rounded up to align with the respective data frequency of each variable. | The timestamps of the inference results aren't as expected: either too few timestamps or too many timestamps. | Please refer to [Timestamp round-up](#timestamp-round-up). |

+| Taking all data points with `isAnomaly`=`true` as anomalies | Too many false positives | You should use both `isAnomaly` and `severity` (or `score`) to sift out anomalies that aren't severe and (optionally) use grouping to check the duration of the anomalies to suppress random noises. Please refer to the [FAQ](#faq) section below for the difference between `severity` and `score`. |

+| Creating Anomaly Detector resources on Azure regions that don't support MVAD yet and calling MVAD APIs | You'll get a "resource not found" error while calling the MVAD APIs. | During preview stage, MVAD is available on limited regions only. Please bookmark [What's new in Anomaly Detector](../whats-new.md) to keep up to date with MVAD region roll-outs. You could also file a GitHub issue or contact us at AnomalyDetector@microsoft.com to request for specific regions. |

+* **Streaming scenario**: You want to predict whether the ONE data point at "2021-01-02T00:00:00Z" is anomalous. Your `startTime` and `endTime` will be the same value ("2021-01-02T00:00:00Z"). Your inference data source, however, must contain at least 1,440 + 1 timestamps. Because MVAD will take the leading data before the target data point ("2021-01-02T00:00:00Z") to decide whether the target is an anomaly. The length of the needed leading data is `slidingWindow` or 1,440 in this case. 1,440 = 60 * 24, so your input data must start from at latest "2021-01-01T00:00:00Z".

+### Why does the service only accept zip files for training and inference when sending data asynchronously?

+We use zip files because in batch scenarios, we expect the size of both training and inference data would be very large and can't be put in the HTTP request body. This allows users to perform batch inference on historical data either for model validation or data analysis.

+Normally we recommend you to use `severity` as the filter to sift out 'anomalies' that aren't so important to your business. Depending on your scenario and data pattern, those anomalies that are less important often have relatively lower `severity` values or standalone (discontinuous) high `severity` values like random spikes.

+We consider whether a data point is anomalous from both global and local perspective. If `score` at a timestamp is higher than a certain threshold, then the timestamp is marked as an anomaly. If `score` is lower than the threshold but is relatively higher in a segment, it's also marked as an anomaly.

+* [Learn about the underlying algorithms that power Anomaly Detector Multivariate](https://arxiv.org/abs/2009.02040)

+ Title: Build a React app to add users to a Face service

+description: Learn how to set up your development environment and deploy a Face app to get consent from customers.

+# Build a React app to add users to a Face service

+This guide will show you how to get started with the sample Face enrollment application. The app demonstrates best practices for obtaining meaningful consent to add users into a face recognition service and acquire high-accuracy face data. An integrated system could use an app like this to provide touchless access control, identity verification, attendance tracking, or personalization kiosk, based on their face data.

+When launched, the application shows users a detailed consent screen. If the user gives consent, the app prompts for a username and password and then captures a high-quality face image using the device's camera.

+The sample app is written using JavaScript and the React Native framework. It can currently be deployed on Android and iOS devices; more deployment options are coming in the future.

+## Prerequisites

+* An Azure subscription ΓÇô [Create one for free](https://azure.microsoft.com/free/cognitive-services/).

+* Once you have your Azure subscription, [create a Face resource](https://portal.azure.com/#create/Microsoft.CognitiveServicesFace) in the Azure portal to get your key and endpoint. After it deploys, select **Go to resource**.

+ * You'll need the key and endpoint from the resource you created to connect your application to Face API.

+ * For local development and testing only, the API key and endpoint are environment variables. For final deployment, store the API key in a secure location and never in the code or environment variables.

+### Important Security Considerations

+* For local development and initial limited testing, it is acceptable (although not best practice) to use environment variables to hold the API key and endpoint. For pilot and final deployments, the API key should be stored securely - which likely involves using an intermediate service to validate a user token generated during login.

+* Never store the API key or endpoint in code or commit them to a version control system (e.g. Git). If that happens by mistake, you should immediately generate a new API key/endpoint and revoke the previous ones.

+* As a best practice, consider having separate API keys for development and production.

+## Set up the development environment

+#### [Android](#tab/android)

+

+1. Clone the git repository for the [sample app](https://github.com/azure-samples/cognitive-services-FaceAPIEnrollmentSample).

+1. To set up your development environment, follow the <a href="https://reactnative.dev/docs/environment-setup" title="React Native documentation" target="_blank">React Native documentation <span class="docon docon-navigate-external x-hidden-focus"></span></a>. Select **React Native CLI Quickstart**. Select your development OS and **Android** as the target OS. Complete the sections **Installing dependencies** and **Android development environment**.

+1. Download your preferred text editor such as [Visual Studio Code](https://code.visualstudio.com/).

+1. Retrieve your FaceAPI endpoint and key in the Azure portal under the **Overview** tab of your resource. Don't check in your Face API key to your remote repository.

+1. Run the app using either the Android Virtual Device emulator from Android Studio, or your own Android device. To test your app on a physical device, follow the relevant <a href="https://reactnative.dev/docs/running-on-device" title="React Native documentation" target="_blank">React Native documentation <span class="docon docon-navigate-external x-hidden-focus"></span></a>.

+#### [iOS](#tab/ios)

+1. Clone the git repository for the [sample app](https://github.com/azure-samples/cognitive-services-FaceAPIEnrollmentSample).

+1. To set up your development environment, follow the <a href="https://reactnative.dev/docs/environment-setup" title="React Native documentation" target="_blank">React Native documentation <span class="docon docon-navigate-external x-hidden-focus"></span></a>. Select **React Native CLI Quickstart**. Select **macOS** as your development OS and **iOS** as the target OS. Complete the section **Installing dependencies**.

+1. Download your preferred text editor such as [Visual Studio Code](https://code.visualstudio.com/). You will also need to download Xcode.

+1. Retrieve your FaceAPI endpoint and key in the Azure portal under the **Overview** tab of your resource. Don't check in your Face API key to your remote repository.

+1. Run the app using either a simulated device from Xcode, or your own iOS device. To test your app on a physical device, follow the relevant <a href="https://reactnative.dev/docs/running-on-device" title="React Native documentation" target="_blank">React Native documentation <span class="docon docon-navigate-external x-hidden-focus"></span></a>.

+## Create a user add experience

+Now that you have set up the sample app, you can tailor it to your own needs.

+For example, you may want to add situation-specific information on your consent page:

+> [!div class="mx-imgBorder"]

+> 

+Many face recognition issues are caused by low-quality reference images. Some factors that can degrade model performance are:

+* Face size (faces that are distant from the camera)

+* Face orientation (faces turned or tilted away from camera)

+* Poor lighting conditions (either low light or backlighting) where the image may be poorly exposed or have too much noise

+* Occlusion (partially hidden or obstructed faces) including accessories like hats or thick-rimmed glasses)

+* Blur (such as by rapid face movement when the photograph was taken).

+The service provides image quality checks to help you make the choice of whether the image is of sufficient quality based on the above factors to add the customer or attempt face recognition. This app demonstrates how to access frames from the device's camera, detect quality and show user interface messages to the user to help them capture a higher quality image, select the highest-quality frames, and add the detected face into the Face API service.

+> [!div class="mx-imgBorder"]

+> 

+Notice the app also offers functionality for deleting the user's information and the option to re-add.

+> [!div class="mx-imgBorder"]

+> 

+To extend the app's functionality to cover the full experience, read the [overview](../enrollment-overview.md) for additional features to implement and best practices.

+## Deploy the app

+#### [Android](#tab/android)

+First, make sure that your app is ready for production deployment: remove any keys or secrets from the app code and make sure you have followed the [security best practices](../../cognitive-services-security.md?tabs=command-line%2ccsharp).

+When you're ready to release your app for production, you'll generate a release-ready APK file, which is the package file format for Android apps. This APK file must be signed with a private key. With this release build, you can begin distributing the app to your devices directly.

+Follow the <a href="https://developer.android.com/studio/publish/preparing#publishing-build" title="Prepare for release" target="_blank">Prepare for release <span class="docon docon-navigate-external x-hidden-focus"></span></a> documentation to learn how to generate a private key, sign your application, and generate a release APK.

+Once you've created a signed APK, see the <a href="https://developer.android.com/studio/publish" title="Publish your app" target="_blank">Publish your app <span class="docon docon-navigate-external x-hidden-focus"></span></a> documentation to learn more about how to release your app.

+#### [iOS](#tab/ios)

+First, make sure that your app is ready for production deployment: remove any keys or secrets from the app code and make sure you have followed the [security best practices](../../cognitive-services-security.md?tabs=command-line%2ccsharp). To prepare for distribution, you will need to create an app icon, a launch screen, and configure deployment info settings. Follow the [documentation from Xcode](https://developer.apple.com/documentation/Xcode/preparing_your_app_for_distribution) to prepare your app for distribution.

+When you're ready to release your app for production, you'll build an archive of your app. Follow the [Xcode documentation](https://developer.apple.com/documentation/Xcode/distributing_your_app_for_beta_testing_and_releases) on how to create an archive build and options for distributing your app.

+## Next steps

+In this guide, you learned how to set up your development environment and get started with the sample app. If you're new to React Native, you can read their [getting started docs](https://reactnative.dev/docs/getting-started) to learn more background information. It also may be helpful to familiarize yourself with [Face API](../overview-identity.md). Read the other sections on adding users before you begin development.

+The *Read* OCR container allows you to extract printed and handwritten text from images and documents with support for JPEG, PNG, BMP, PDF, and TIFF file formats. For more information, see the [Read API how-to guide](how-to/call-read-api.md).

+> This feature is also offered by the Azure [Face](./index-identity.yml) service. Use this alternative for more detailed face analysis, including face identification and head pose detection.

+ Title: "Face detection and attributes concepts"

+description: Learn more about face detection; face detection is the action of locating human faces in an image and optionally returning different kinds of face-related data.

+# Face detection and attributes

+This article explains the concepts of face detection and face attribute data. Face detection is the process of locating human faces in an image and optionally returning different kinds of face-related data.

+You use the [Face - Detect](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236) API to detect faces in an image. To get started using the REST API or a client SDK, follow a [quickstart](./quickstarts-sdk/identity-client-library.md). Or, for a more in-depth guide, see [Call the detect API](./how-to/identity-detect-faces.md).

+## Face rectangle

+Each detected face corresponds to a `faceRectangle` field in the response. This is a set of pixel coordinates for the left, top, width, and height of the detected face. Using these coordinates, you can get the location and size of the face. In the API response, faces are listed in size order from largest to smallest.

+## Face ID

+The face ID is a unique identifier string for each detected face in an image. You can request a face ID in your [Face - Detect](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236) API call.

+## Face landmarks

+Face landmarks are a set of easy-to-find points on a face, such as the pupils or the tip of the nose. By default, there are 27 predefined landmark points. The following figure shows all 27 points:

+

+The coordinates of the points are returned in units of pixels.

+The Detection_03 model currently has the most accurate landmark detection. The eye and pupil landmarks it returns are precise enough to enable gaze tracking of the face.

+## Attributes

+Attributes are a set of features that can optionally be detected by the [Face - Detect](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236) API. The following attributes can be detected:

+* **Accessories**. Whether the given face has accessories. This attribute returns possible accessories including headwear, glasses, and mask, with confidence score between zero and one for each accessory.

+* **Age**. The estimated age in years of a particular face.

+* **Blur**. The blurriness of the face in the image. This attribute returns a value between zero and one and an informal rating of low, medium, or high.

+* **Emotion**. A list of emotions with their detection confidence for the given face. Confidence scores are normalized, and the scores across all emotions add up to one. The emotions returned are happiness, sadness, neutral, anger, contempt, disgust, surprise, and fear.

+* **Exposure**. The exposure of the face in the image. This attribute returns a value between zero and one and an informal rating of underExposure, goodExposure, or overExposure.

+* **Facial hair**. The estimated facial hair presence and the length for the given face.

+* **Gender**. The estimated gender of the given face. Possible values are male, female, and genderless.

+* **Glasses**. Whether the given face has eyeglasses. Possible values are NoGlasses, ReadingGlasses, Sunglasses, and Swimming Goggles.

+* **Hair**. The hair type of the face. This attribute shows whether the hair is visible, whether baldness is detected, and what hair colors are detected.

+* **Head pose**. The face's orientation in 3D space. This attribute is described by the roll, yaw, and pitch angles in degrees, which are defined according to the [right-hand rule](https://en.wikipedia.org/wiki/Right-hand_rule). The order of three angles is roll-yaw-pitch, and each angle's value range is from -180 degrees to 180 degrees. 3D orientation of the face is estimated by the roll, yaw, and pitch angles in order. See the following diagram for angle mappings:

+ 

+ For more details on how to use these values, see the [Head pose how-to guide](./how-to/use-headpose.md).

+* **Makeup**. Whether the face has makeup. This attribute returns a Boolean value for eyeMakeup and lipMakeup.

+* **Mask**. Whether the face is wearing a mask. This attribute returns a possible mask type, and a Boolean value to indicate whether nose and mouth are covered.

+* **Noise**. The visual noise detected in the face image. This attribute returns a value between zero and one and an informal rating of low, medium, or high.

+* **Occlusion**. Whether there are objects blocking parts of the face. This attribute returns a Boolean value for eyeOccluded, foreheadOccluded, and mouthOccluded.

+* **Smile**. The smile expression of the given face. This value is between zero for no smile and one for a clear smile.

+* **QualityForRecognition** The overall image quality regarding whether the image being used in the detection is of sufficient quality to attempt face recognition on. The value is an informal rating of low, medium, or high. Only "high" quality images are recommended for person enrollment, and quality at or above "medium" is recommended for identification scenarios.

+ >[!NOTE]

+ > The availability of each attribute depends on the detection model specified. QualityForRecognition attribute also depends on the recognition model, as it is currently only available when using a combination of detection model detection_01 or detection_03, and recognition model recognition_03 or recognition_04.

+> [!IMPORTANT]

+> Face attributes are predicted through the use of statistical algorithms. They might not always be accurate. Use caution when you make decisions based on attribute data.

+## Input data

+Use the following tips to make sure that your input images give the most accurate detection results:

+* The supported input image formats are JPEG, PNG, GIF (the first frame), BMP.

+* The image file size should be no larger than 6 MB.

+* The minimum detectable face size is 36 x 36 pixels in an image that is no larger than 1920 x 1080 pixels. Images with larger than 1920 x 1080 pixels have a proportionally larger minimum face size. Reducing the face size might cause some faces not to be detected, even if they are larger than the minimum detectable face size.

+* The maximum detectable face size is 4096 x 4096 pixels.

+* Faces outside the size range of 36 x 36 to 4096 x 4096 pixels will not be detected.

+* Some faces might not be recognized because of technical challenges, such as:

+ * Images with extreme lighting, for example, severe backlighting.

+ * Obstructions that block one or both eyes.

+ * Differences in hair type or facial hair.

+ * Changes in facial appearance because of age.

+ * Extreme facial expressions.

+### Input data with orientation information:

+Some input images with JPEG format might contain orientation information in Exchangeable image file format (Exif) metadata. If Exif orientation is available, images will be automatically rotated to the correct orientation before sending for face detection. The face rectangle, landmarks, and head pose for each detected face will be estimated based on the rotated image.

+To properly display the face rectangle and landmarks, you need to make sure the image is rotated correctly. Most of image visualization tools will auto-rotate the image according to its Exif orientation by default. For other tools, you might need to apply the rotation using your own code. The following examples show a face rectangle on a rotated image (left) and a non-rotated image (right).

+

+### Video input

+If you're detecting faces from a video feed, you may be able to improve performance by adjusting certain settings on your video camera:

+* **Smoothing**: Many video cameras apply a smoothing effect. You should turn this off if you can because it creates a blur between frames and reduces clarity.

+* **Shutter Speed**: A faster shutter speed reduces the amount of motion between frames and makes each frame clearer. We recommend shutter speeds of 1/60 second or faster.

+* **Shutter Angle**: Some cameras specify shutter angle instead of shutter speed. You should use a lower shutter angle if possible. This will result in clearer video frames.

+ >[!NOTE]

+ > A camera with a lower shutter angle will receive less light in each frame, so the image will be darker. You'll need to determine the right level to use.

+## Next steps

+Now that you're familiar with face detection concepts, learn how to write a script that detects faces in a given image.

+* [Call the detect API](./how-to/identity-detect-faces.md)

+ Title: "Face recognition concepts"

+description: Learn the concept of Face recognition, its related operations, and the underlying data structures.

+# Face recognition concepts

+This article explains the concept of Face recognition, its related operations, and the underlying data structures. Broadly, Face recognition refers to the method of verifying or identifying an individual by their face.

+Verification is one-to-one matching that takes two faces and returns whether they are the same face, and identification is one-to-many matching that takes a single face as input and returns a set of matching candidates. Face recognition is important in implementing the identity verification scenario, which enterprises and apps can use to verify that a (remote) user is who they claim to be.

+## Related data structures

+The recognition operations use mainly the following data structures. These objects are stored in the cloud and can be referenced by their ID strings. ID strings are always unique within a subscription, but name fields may be duplicated.

+|Name|Description|

+|:--|:--|

+|DetectedFace| This single face representation is retrieved by the [face detection](./how-to/identity-detect-faces.md) operation. Its ID expires 24 hours after it's created.|

+|PersistedFace| When DetectedFace objects are added to a group, such as FaceList or Person, they become PersistedFace objects. They can be [retrieved](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c) at any time and don't expire.|

+|[FaceList](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) or [LargeFaceList](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc)| This data structure is an assorted list of PersistedFace objects. A FaceList has a unique ID, a name string, and optionally a user data string.|

+|[Person](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c)| This data structure is a list of PersistedFace objects that belong to the same person. It has a unique ID, a name string, and optionally a user data string.|

+|[PersonGroup](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) or [LargePersonGroup](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d)| This data structure is an assorted list of Person objects. It has a unique ID, a name string, and optionally a user data string. A PersonGroup must be [trained](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) before it can be used in recognition operations.|

+|PersonDirectory | This data structure is like **LargePersonGroup** but offers additional storage capacity and other added features. For more information, see [Use the PersonDirectory structure](./how-to/use-persondirectory.md).

+## Recognition operations

+This section details how the underlying operations use the above data structures to identify and verify a face.

+### PersonGroup creation and training

+You need to create a [PersonGroup](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) or [LargePersonGroup](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) to store the set of people to match against. PersonGroups hold [Person](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) objects, which each represent an individual person and hold a set of face data belonging to that person.

+The [Train](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) operation prepares the data set to be used in face data comparisons.

+### Identification

+The [Identify](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239) operation takes one or several source face IDs (from a DetectedFace or PersistedFace object) and a PersonGroup or LargePersonGroup. It returns a list of the Person objects that each source face might belong to. Returned Person objects are wrapped as Candidate objects, which have a prediction confidence value.

+### Verification

+The [Verify](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a) operation takes a single face ID (from a DetectedFace or PersistedFace object) and a Person object. It determines whether the face belongs to that same person. Verification is one-to-one matching and can be used as a final check on the results from the Identify API call. However, you can optionally pass in the PersonGroup to which the candidate Person belongs to improve the API performance.

+## Input data

+Use the following tips to ensure that your input images give the most accurate recognition results:

+* The supported input image formats are JPEG, PNG, GIF (the first frame), BMP.

+* Image file size should be no larger than 6 MB.

+* When you create Person objects, use photos that feature different kinds of angles and lighting.

+* Some faces might not be recognized because of technical challenges, such as:

+ * Images with extreme lighting, for example, severe backlighting.

+ * Obstructions that block one or both eyes.

+ * Differences in hair type or facial hair.

+ * Changes in facial appearance because of age.

+ * Extreme facial expressions.

+* You can utilize the qualityForRecognition attribute in the [face detection](./how-to/identity-detect-faces.md) operation when using applicable detection models as a general guideline of whether the image is likely of sufficient quality to attempt face recognition on. Only "high" quality images are recommended for person enrollment and quality at or above "medium" is recommended for identification scenarios.

+## Next steps

+Now that you're familiar with face recognition concepts, Write a script that identifies faces against a trained PersonGroup.

+* [Face client library quickstart](./quickstarts-sdk/identity-client-library.md)

+ Title: Best practices for adding users to a Face service

+description: Learn about the process of Face enrollment to register users in a face recognition service.

+# Best practices for adding users to a Face service

+In order to use the Cognitive Services Face API for face verification or identification, you need to enroll faces into a **LargePersonGroup** or similar data structure. This deep-dive demonstrates best practices for gathering meaningful consent from users and example logic to create high-quality enrollments that will optimize recognition accuracy.

+## Meaningful consent

+One of the key purposes of an enrollment application for facial recognition is to give users the opportunity to consent to the use of images of their face for specific purposes, such as access to a worksite. Because facial recognition technologies may be perceived as collecting sensitive personal data, it's especially important to ask for consent in a way that is both transparent and respectful. Consent is meaningful to users when it empowers them to make the decision that they feel is best for them.

+Based on Microsoft user research, Microsoft's Responsible AI principles, and [external research](ftp://ftp.cs.washington.edu/tr/2000/12/UW-CSE-00-12-02.pdf), we have found that consent is meaningful when it offers the following to users enrolling in the technology:

+* Awareness: Users should have no doubt when they are being asked to provide their face template or enrollment photos.

+* Understanding: Users should be able to accurately describe in their own words what they were being asked for, by whom, to what end, and with what assurances.

+* Freedom of choice: Users should not feel coerced or manipulated when choosing whether to consent and enroll in facial recognition.

+* Control: Users should be able to revoke their consent and delete their data at any time.

+This section offers guidance for developing an enrollment application for facial recognition. This guidance has been developed based on Microsoft user research in the context of enrolling individuals in facial recognition for building entry. Therefore, these recommendations might not apply to all facial recognition solutions. Responsible use for Face API depends strongly on the specific context in which it's integrated, so the prioritization and application of these recommendations should be adapted to your scenario.

+> [!NOTE]

+> It is your responsibility to align your enrollment application with applicable legal requirements in your jurisdiction and accurately reflect all of your data collection and processing practices.

+## Application development

+Before you design an enrollment flow, think about how the application you're building can uphold the promises you make to users about how their data is protected. The following recommendations can help you build an enrollment experience that includes responsible approaches to securing personal data, managing users' privacy, and ensuring that the application is accessible to all users.

+|Category | Recommendations |

+|||

+|Hardware | Consider the camera quality of the enrollment device. |

+|Recommended enrollment features | Include a log-on step with multi-factor authentication. </br></br>Link user information like an alias or identification number with their face template ID from the Face API (known as person ID). This mapping is necessary to retrieve and manage a user's enrollment. Note: person ID should be treated as a secret in the application.</br></br>Set up an automated process to delete all enrollment data, including the face templates and enrollment photos of people who are no longer users of facial recognition technology, such as former employees. </br></br>Avoid auto-enrollment, as it does not give the user the awareness, understanding, freedom of choice, or control that is recommended for obtaining consent. </br></br>Ask users for permission to save the images used for enrollment. This is useful when there is a model update since new enrollment photos will be required to re-enroll in the new model about every 10 months. If the original images aren't saved, users will need to go through the enrollment process from the beginning.</br></br>Allow users to opt out of storing photos in the system. To make the choice clearer, you can add a second consent request screen for saving the enrollment photos. </br></br>If photos are saved, create an automated process to re-enroll all users when there is a model update. Users who saved their enrollment photos will not have to enroll themselves again. </br></br>Create an app feature that allows designated administrators to override certain quality filters if a user has trouble enrolling. |

+|Security | Cognitive Services follow [best practices](../cognitive-services-virtual-networks.md?tabs=portal) for encrypting user data at rest and in transit. The following are other practices that can help uphold the security promises you make to users during the enrollment experience. </br></br>Take security measures to ensure that no one has access to the person ID at any point during enrollment. Note: PersonID should be treated as a secret in the enrollment system. </br></br>Use [role-based access control](../../role-based-access-control/overview.md) with Cognitive Services. </br></br>Use token-based authentication and/or shared access signatures (SAS) over keys and secrets to access resources like databases. By using request or SAS tokens, you can grant limited access to data without compromising your account keys, and you can specify an expiry time on the token. </br></br>Never store any secrets, keys, or passwords in your app. |

+|User privacy |Provide a range of enrollment options to address different levels of privacy concerns. Do not mandate that people use their personal devices to enroll into a facial recognition system. </br></br>Allow users to re-enroll, revoke consent, and delete data from the enrollment application at any time and for any reason. |

+|Accessibility |Follow accessibility standards (for example, [ADA](https://www.ada.gov/regs2010/2010ADAStandards/2010ADAstandards.htm) or [W3C](https://www.w3.org/TR/WCAG21/)) to ensure the application is usable by people with mobility or visual impairments. |

+## Next steps

+Follow the [Build an enrollment app](Tutorials/build-enrollment-app.md) guide to get started with a sample enrollment app. Then customize it or write your own app to suit the needs of your product.

+ Title: "Example: Add faces to a PersonGroup - Face"

+description: This guide demonstrates how to add a large number of persons and faces to a PersonGroup object with the Azure Cognitive Services Face service.

+ms.devlang: csharp

+# Add faces to a PersonGroup

+This guide demonstrates how to add a large number of persons and faces to a PersonGroup object. The same strategy also applies to LargePersonGroup, FaceList, and LargeFaceList objects. This sample is written in C# by using the Azure Cognitive Services Face .NET client library.

+## Step 1: Initialization

+The following code declares several variables and implements a helper function to schedule the face add requests:

+- `PersonCount` is the total number of persons.

+- `CallLimitPerSecond` is the maximum calls per second according to the subscription tier.

+- `_timeStampQueue` is a Queue to record the request timestamps.

+- `await WaitCallLimitPerSecondAsync()` waits until it's valid to send the next request.

+```csharp

+const int PersonCount = 10000;

+const int CallLimitPerSecond = 10;

+static Queue<DateTime> _timeStampQueue = new Queue<DateTime>(CallLimitPerSecond);

+static async Task WaitCallLimitPerSecondAsync()

+{

+ Monitor.Enter(_timeStampQueue);

+ try

+ {

+ if (_timeStampQueue.Count >= CallLimitPerSecond)

+ {

+ TimeSpan timeInterval = DateTime.UtcNow - _timeStampQueue.Peek();

+ if (timeInterval < TimeSpan.FromSeconds(1))

+ {

+ await Task.Delay(TimeSpan.FromSeconds(1) - timeInterval);

+ }

+ _timeStampQueue.Dequeue();

+ }

+ _timeStampQueue.Enqueue(DateTime.UtcNow);

+ }

+ finally

+ {

+ Monitor.Exit(_timeStampQueue);

+ }

+}

+```

+## Step 2: Authorize the API call

+When you use a client library, you must pass your key to the constructor of the **FaceClient** class. For example:

+```csharp

+private readonly IFaceClient faceClient = new FaceClient(

+ new ApiKeyServiceClientCredentials("<SubscriptionKey>"),

+ new System.Net.Http.DelegatingHandler[] { });

+```

+To get the key, go to the Azure Marketplace from the Azure portal. For more information, see [Subscriptions](https://www.microsoft.com/cognitive-services/sign-up).

+## Step 3: Create the PersonGroup

+A PersonGroup named "MyPersonGroup" is created to save the persons.

+The request time is enqueued to `_timeStampQueue` to ensure the overall validation.

+```csharp

+const string personGroupId = "mypersongroupid";

+const string personGroupName = "MyPersonGroup";

+_timeStampQueue.Enqueue(DateTime.UtcNow);

+await faceClient.LargePersonGroup.CreateAsync(personGroupId, personGroupName);

+```

+## Step 4: Create the persons for the PersonGroup

+Persons are created concurrently, and `await WaitCallLimitPerSecondAsync()` is also applied to avoid exceeding the call limit.

+```csharp

+Person[] persons = new Person[PersonCount];

+Parallel.For(0, PersonCount, async i =>

+{

+ await WaitCallLimitPerSecondAsync();

+ string personName = $"PersonName#{i}";

+ persons[i] = await faceClient.PersonGroupPerson.CreateAsync(personGroupId, personName);

+});

+```

+## Step 5: Add faces to the persons

+Faces added to different persons are processed concurrently. Faces added for one specific person are processed sequentially.

+Again, `await WaitCallLimitPerSecondAsync()` is invoked to ensure that the request frequency is within the scope of limitation.

+```csharp

+Parallel.For(0, PersonCount, async i =>

+{

+ Guid personId = persons[i].PersonId;

+ string personImageDir = @"/path/to/person/i/images";

+ foreach (string imagePath in Directory.GetFiles(personImageDir, "*.jpg"))

+ {

+ await WaitCallLimitPerSecondAsync();

+ using (Stream stream = File.OpenRead(imagePath))

+ {

+ await faceClient.PersonGroupPerson.AddFaceFromStreamAsync(personGroupId, personId, stream);

+ }

+ }

+});

+```

+## Summary

+In this guide, you learned the process of creating a PersonGroup with a massive number of persons and faces. Several reminders:

+- This strategy also applies to FaceLists and LargePersonGroups.

+- Adding or deleting faces to different FaceLists or persons in LargePersonGroups are processed concurrently.

+- Adding or deleting faces to one specific FaceList or person in a LargePersonGroup are done sequentially.

+- For simplicity, how to handle a potential exception is omitted in this guide. If you want to enhance more robustness, apply the proper retry policy.

+The following features were explained and demonstrated:

+- Create PersonGroups by using the [PersonGroup - Create](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) API.

+- Create persons by using the [PersonGroup Person - Create](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) API.

+- Add faces to persons by using the [PersonGroup Person - Add Face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523b) API.

+## Next steps

+In this guide, you learned how to add face data to a **PersonGroup**. Next, learn how to use the enhanced data structure **PersonDirectory** to do more with your face data.

+- [Use the PersonDirectory structure](use-persondirectory.md)

+ Title: Analyze videos in near real time - Computer Vision

+description: Learn how to perform near real-time analysis on frames that are taken from a live video stream by using the Computer Vision API.

+ms.devlang: csharp

+# Analyze videos in near real time

+This article demonstrates how to perform near real-time analysis on frames that are taken from a live video stream by using the Computer Vision API. The basic elements of such an analysis are:

+- Acquiring frames from a video source.

+- Selecting which frames to analyze.

+- Submitting these frames to the API.

+- Consuming each analysis result that's returned from the API call.

+The samples in this article are written in C#. To access the code, go to the [Video frame analysis sample](https://github.com/Microsoft/Cognitive-Samples-VideoFrameAnalysis/) page on GitHub.

+## Approaches to running near real-time analysis

+You can solve the problem of running near real-time analysis on video streams by using a variety of approaches. This article outlines three of them, in increasing levels of sophistication.

+### Design an infinite loop

+The simplest design for near real-time analysis is an infinite loop. In each iteration of this loop, you grab a frame, analyze it, and then consume the result:

+```csharp

+while (true)

+{

+ Frame f = GrabFrame();

+ if (ShouldAnalyze(f))

+ {

+ AnalysisResult r = await Analyze(f);

+ ConsumeResult(r);

+ }

+}

+```

+If your analysis were to consist of a lightweight, client-side algorithm, this approach would be suitable. However, when the analysis occurs in the cloud, the resulting latency means that an API call might take several seconds. During this time, you're not capturing images, and your thread is essentially doing nothing. Your maximum frame rate is limited by the latency of the API calls.

+### Allow the API calls to run in parallel

+Although a simple, single-threaded loop makes sense for a lightweight, client-side algorithm, it doesn't fit well with the latency of a cloud API call. The solution to this problem is to allow the long-running API call to run in parallel with the frame-grabbing. In C#, you could do this by using task-based parallelism. For example, you can run the following code:

+```csharp

+while (true)

+{

+ Frame f = GrabFrame();

+ if (ShouldAnalyze(f))

+ {

+ var t = Task.Run(async () =>

+ {

+ AnalysisResult r = await Analyze(f);

+ ConsumeResult(r);

+ }

+ }

+}

+```

+With this approach, you launch each analysis in a separate task. The task can run in the background while you continue grabbing new frames. The approach avoids blocking the main thread as you wait for an API call to return. However, the approach can present certain disadvantages:

+* It costs you some of the guarantees that the simple version provided. That is, multiple API calls might occur in parallel, and the results might get returned in the wrong order.

+* It could also cause multiple threads to enter the ConsumeResult() function simultaneously, which might be dangerous if the function isn't thread-safe.

+* Finally, this simple code doesn't keep track of the tasks that get created, so exceptions silently disappear. Thus, you need to add a "consumer" thread that tracks the analysis tasks, raises exceptions, kills long-running tasks, and ensures that the results get consumed in the correct order, one at a time.

+### Design a producer-consumer system

+For your final approach, designing a "producer-consumer" system, you build a producer thread that looks similar to your previously mentioned infinite loop. However, instead of consuming the analysis results as soon as they're available, the producer simply places the tasks in a queue to keep track of them.

+```csharp

+// Queue that will contain the API call tasks.

+var taskQueue = new BlockingCollection<Task<ResultWrapper>>();

+// Producer thread.

+while (true)

+{

+ // Grab a frame.

+ Frame f = GrabFrame();

+ // Decide whether to analyze the frame.

+ if (ShouldAnalyze(f))

+ {

+ // Start a task that will run in parallel with this thread.

+ var analysisTask = Task.Run(async () =>

+ {

+ // Put the frame, and the result/exception into a wrapper object.

+ var output = new ResultWrapper(f);

+ try

+ {

+ output.Analysis = await Analyze(f);

+ }

+ catch (Exception e)

+ {

+ output.Exception = e;

+ }

+ return output;

+ }

+ // Push the task onto the queue.

+ taskQueue.Add(analysisTask);

+ }

+}

+```

+You also create a consumer thread, which takes tasks off the queue, waits for them to finish, and either displays the result or raises the exception that was thrown. By using the queue, you can guarantee that the results get consumed one at a time, in the correct order, without limiting the maximum frame rate of the system.

+```csharp

+// Consumer thread.

+while (true)

+{

+ // Get the oldest task.

+ Task<ResultWrapper> analysisTask = taskQueue.Take();

+

+ // Wait until the task is completed.

+ var output = await analysisTask;

+ // Consume the exception or result.

+ if (output.Exception != null)

+ {

+ throw output.Exception;

+ }

+ else

+ {

+ ConsumeResult(output.Analysis);

+ }

+}

+```

+## Implement the solution

+### Get started quickly

+To help get your app up and running as quickly as possible, we've implemented the system that's described in the preceding section. It's intended to be flexible enough to accommodate many scenarios, while being easy to use. To access the code, go to the [Video frame analysis sample](https://github.com/Microsoft/Cognitive-Samples-VideoFrameAnalysis/) page on GitHub.

+The library contains the `FrameGrabber` class, which implements the previously discussed producer-consumer system to process video frames from a webcam. Users can specify the exact form of the API call, and the class uses events to let the calling code know when a new frame is acquired, or when a new analysis result is available.

+To illustrate some of the possibilities, we've provided two sample apps that use the library.

+The first sample app is a simple console app that grabs frames from the default webcam and then submits them to the Face service for face detection. A simplified version of the app is reproduced in the following code:

+```csharp

+using System;

+using System.Linq;

+using Microsoft.Azure.CognitiveServices.Vision.Face;

+using Microsoft.Azure.CognitiveServices.Vision.Face.Models;

+using VideoFrameAnalyzer;

+namespace BasicConsoleSample

+{

+ internal class Program

+ {

+ const string ApiKey = "<your API key>";

+ const string Endpoint = "https://<your API region>.api.cognitive.microsoft.com";

+ private static async Task Main(string[] args)

+ {

+ // Create grabber.

+ FrameGrabber<DetectedFace[]> grabber = new FrameGrabber<DetectedFace[]>();

+ // Create Face Client.

+ FaceClient faceClient = new FaceClient(new ApiKeyServiceClientCredentials(ApiKey))

+ {

+ Endpoint = Endpoint

+ };

+ // Set up a listener for when we acquire a new frame.

+ grabber.NewFrameProvided += (s, e) =>

+ {

+ Console.WriteLine($"New frame acquired at {e.Frame.Metadata.Timestamp}");

+ };

+ // Set up a Face API call.

+ grabber.AnalysisFunction = async frame =>

+ {

+ Console.WriteLine($"Submitting frame acquired at {frame.Metadata.Timestamp}");

+ // Encode image and submit to Face service.

+ return (await faceClient.Face.DetectWithStreamAsync(frame.Image.ToMemoryStream(".jpg"))).ToArray();

+ };

+ // Set up a listener for when we receive a new result from an API call.

+ grabber.NewResultAvailable += (s, e) =>

+ {

+ if (e.TimedOut)

+ Console.WriteLine("API call timed out.");

+ else if (e.Exception != null)

+ Console.WriteLine("API call threw an exception.");

+ else

+ Console.WriteLine($"New result received for frame acquired at {e.Frame.Metadata.Timestamp}. {e.Analysis.Length} faces detected");

+ };

+ // Tell grabber when to call the API.

+ // See also TriggerAnalysisOnPredicate

+ grabber.TriggerAnalysisOnInterval(TimeSpan.FromMilliseconds(3000));

+ // Start running in the background.

+ await grabber.StartProcessingCameraAsync();

+ // Wait for key press to stop.

+ Console.WriteLine("Press any key to stop...");

+ Console.ReadKey();

+ // Stop, blocking until done.

+ await grabber.StopProcessingAsync();

+ }

+ }

+}

+```

+The second sample app is a bit more interesting. It allows you to choose which API to call on the video frames. On the left side, the app shows a preview of the live video. On the right, it overlays the most recent API result on the corresponding frame.

+In most modes, there's a visible delay between the live video on the left and the visualized analysis on the right. This delay is the time that it takes to make the API call. An exception is in the "EmotionsWithClientFaceDetect" mode, which performs face detection locally on the client computer by using OpenCV before it submits any images to Azure Cognitive Services.

+By using this approach, you can visualize the detected face immediately. You can then update the emotions later, after the API call returns. This demonstrates the possibility of a "hybrid" approach. That is, some simple processing can be performed on the client, and then Cognitive Services APIs can be used to augment this processing with more advanced analysis when necessary.

+

+### Integrate the samples into your codebase

+To get started with this sample, do the following:

+1. Create an [Azure account](https://azure.microsoft.com/free/cognitive-services/). If you already have one, you can skip to the next step.

+2. Create resources for Computer Vision and Face in the Azure portal to get your key and endpoint. Make sure to select the free tier (F0) during setup.

+ - [Computer Vision](https://portal.azure.com/#create/Microsoft.CognitiveServicesComputerVision)

+ - [Face](https://portal.azure.com/#create/Microsoft.CognitiveServicesFace)

+ After the resources are deployed, click **Go to resource** to collect your key and endpoint for each resource.

+3. Clone the [Cognitive-Samples-VideoFrameAnalysis](https://github.com/Microsoft/Cognitive-Samples-VideoFrameAnalysis/) GitHub repo.

+4. Open the sample in Visual Studio 2015 or later, and then build and run the sample applications:

+ - For BasicConsoleSample, the Face key is hard-coded directly in [BasicConsoleSample/Program.cs](https://github.com/Microsoft/Cognitive-Samples-VideoFrameAnalysis/blob/master/Windows/BasicConsoleSample/Program.cs).

+ - For LiveCameraSample, enter the keys in the **Settings** pane of the app. The keys are persisted across sessions as user data.

+When you're ready to integrate the samples, reference the VideoFrameAnalyzer library from your own projects.

+The image-, voice-, video-, and text-understanding capabilities of VideoFrameAnalyzer use Azure Cognitive Services. Microsoft receives the images, audio, video, and other data that you upload (via this app) and might use them for service-improvement purposes. We ask for your help in protecting the people whose data your app sends to Azure Cognitive Services.

+## Summary

+In this article, you learned how to run near real-time analysis on live video streams by using the Face and Computer Vision services. You also learned how you can use our sample code to get started.

+Feel free to provide feedback and suggestions in the [GitHub repository](https://github.com/Microsoft/Cognitive-Samples-VideoFrameAnalysis/). To provide broader API feedback, go to our [UserVoice](https://feedback.azure.com/d365community/forum/09041fae-0b25-ec11-b6e6-000d3a4f0858) site.

+ Title: Call the Image Analysis API

+description: Learn how to call the Image Analysis API and configure its behavior.

+# Call the Image Analysis API

+This article demonstrates how to call the Image Analysis API to return information about an image's visual features. It also shows you how to parse the returned information using the client SDKs or REST API.

+This guide assumes you have already <a href="https://portal.azure.com/#create/Microsoft.CognitiveServicesComputerVision" title="created a Computer Vision resource" target="_blank">created a Computer Vision resource </a> and obtained a key and endpoint URL. If you're using a client SDK, you'll also need to authenticate a client object. If you haven't done these steps, follow the [quickstart](../quickstarts-sdk/image-analysis-client-library.md) to get started.

+

+## Submit data to the service

+The code in this guide uses remote images referenced by URL. You may want to try different images on your own to see the full capability of the Image Analysis features.

+#### [REST](#tab/rest)

+When analyzing a local image, you put the binary image data in the HTTP request body. For a remote image, you specify the image's URL by formatting the request body like this: `{"url":"http://example.com/images/test.jpg"}`.

+#### [C#](#tab/csharp)

+In your main class, save a reference to the URL of the image you want to analyze.

+[!code-csharp[](~/cognitive-services-quickstart-code/dotnet/ComputerVision/ImageAnalysisQuickstart.cs?name=snippet_analyze_url)]

+#### [Java](#tab/java)

+In your main class, save a reference to the URL of the image you want to analyze.

+[!code-java[](~/cognitive-services-quickstart-code/java/ComputerVision/src/main/java/ImageAnalysisQuickstart.java?name=snippet_urlimage)]

+#### [JavaScript](#tab/javascript)

+In your main function, save a reference to the URL of the image you want to analyze.

+[!code-javascript[](~/cognitive-services-quickstart-code/javascript/ComputerVision/ImageAnalysisQuickstart.js?name=snippet_describe_image)]

+#### [Python](#tab/python)

+Save a reference to the URL of the image you want to analyze.

+[!code-python[](~/cognitive-services-quickstart-code/python/ComputerVision/ImageAnalysisQuickstart.py?name=snippet_remoteimage)]

+## Determine how to process the data

+### Select visual features

+The Analyze API gives you access to all of the service's image analysis features. Choose which operations to do based on your own use case. See the [overview](../overview.md) for a description of each feature. The examples below add all of the available visual features, but for practical usage you'll likely only need one or two.

+#### [REST](#tab/rest)

+You can specify which features you want to use by setting the URL query parameters of the [Analyze API](https://westus.dev.cognitive.microsoft.com/docs/services/computer-vision-v3-2/operations/56f91f2e778daf14a499f21b). A parameter can have multiple values, separated by commas. Each feature you specify will require more computation time, so only specify what you need.

+|URL parameter | Value | Description|

+|||--|

+|`visualFeatures`|`Adult` | detects if the image is pornographic in nature (depicts nudity or a sex act), or is gory (depicts extreme violence or blood). Sexually suggestive content ("racy" content) is also detected.|

+|`visualFeatures`|`Brands` | detects various brands within an image, including the approximate location. The Brands argument is only available in English.|

+|`visualFeatures`|`Categories` | categorizes image content according to a taxonomy defined in documentation. This value is the default value of `visualFeatures`.|

+|`visualFeatures`|`Color` | determines the accent color, dominant color, and whether an image is black&white.|

+|`visualFeatures`|`Description` | describes the image content with a complete sentence in supported languages.|

+|`visualFeatures`|`Faces` | detects if faces are present. If present, generate coordinates, gender and age.|

+|`visualFeatures`|`ImageType` | detects if image is clip art or a line drawing.|

+|`visualFeatures`|`Objects` | detects various objects within an image, including the approximate location. The Objects argument is only available in English.|

+|`visualFeatures`|`Tags` | tags the image with a detailed list of words related to the image content.|

+|`details`| `Celebrities` | identifies celebrities if detected in the image.|

+|`details`|`Landmarks` |identifies landmarks if detected in the image.|

+A populated URL might look like this:

+`https://{endpoint}/vision/v2.1/analyze?visualFeatures=Description,Tags&details=Celebrities`

+#### [C#](#tab/csharp)

+Define your new method for image analysis. Add the code below, which specifies visual features you'd like to extract in your analysis. See the **[VisualFeatureTypes](/dotnet/api/microsoft.azure.cognitiveservices.vision.computervision.models.visualfeaturetypes)** enum for a complete list.

+[!code-csharp[](~/cognitive-services-quickstart-code/dotnet/ComputerVision/ImageAnalysisQuickstart.cs?name=snippet_visualfeatures)]

+#### [Java](#tab/java)

+Specify which visual features you'd like to extract in your analysis. See the [VisualFeatureTypes](/java/api/com.microsoft.azure.cognitiveservices.vision.computervision.models.visualfeaturetypes) enum for a complete list.

+[!code-java[](~/cognitive-services-quickstart-code/java/ComputerVision/src/main/java/ImageAnalysisQuickstart.java?name=snippet_features_remote)]

+#### [JavaScript](#tab/javascript)

+Specify which visual features you'd like to extract in your analysis. See the [VisualFeatureTypes](/javascript/api/@azure/cognitiveservices-computervision/visualfeaturetypes) enum for a complete list.

+[!code-javascript[](~/cognitive-services-quickstart-code/javascript/ComputerVision/ImageAnalysisQuickstart.js?name=snippet_features_remote)]

+#### [Python](#tab/python)

+Specify which visual features you'd like to extract in your analysis. See the [VisualFeatureTypes](/python/api/azure-cognitiveservices-vision-computervision/azure.cognitiveservices.vision.computervision.models.visualfeaturetypes) enum for a complete list.

+[!code-python[](~/cognitive-services-quickstart-code/python/ComputerVision/ImageAnalysisQuickstart.py?name=snippet_features_remote)]

+### Specify languages

+You can also specify the language of the returned data.

+#### [REST](#tab/rest)

+The following URL query parameter specifies the language. The default value is `en`.

+|URL parameter | Value | Description|

+|||--|

+|`language`|`en` | English|

+|`language`|`es` | Spanish|

+|`language`|`ja` | Japanese|

+|`language`|`pt` | Portuguese|

+|`language`|`zh` | Simplified Chinese|

+A populated URL might look like this:

+`https://{endpoint}/vision/v2.1/analyze?visualFeatures=Description,Tags&details=Celebrities&language=en`

+#### [C#](#tab/csharp)

+Use the *language* parameter of [AnalyzeImageAsync](/dotnet/api/microsoft.azure.cognitiveservices.vision.computervision.computervisionclientextensions.analyzeimageasync#microsoft-azure-cognitiveservices-vision-computervision-computervisionclientextensions-analyzeimageasync(microsoft-azure-cognitiveservices-vision-computervision-icomputervisionclient-system-string-system-collections-generic-ilist((system-nullable((microsoft-azure-cognitiveservices-vision-computervision-models-visualfeaturetypes))))-system-collections-generic-ilist((system-nullable((microsoft-azure-cognitiveservices-vision-computervision-models-details))))-system-string-system-collections-generic-ilist((system-nullable((microsoft-azure-cognitiveservices-vision-computervision-models-descriptionexclude))))-system-string-system-threading-cancellationtoken)) call to specify a language. A method call that specifies a language might look like the following.

+```csharp

+ImageAnalysis results = await client.AnalyzeImageAsync(imageUrl, visualFeatures: features, language: "en");

+```

+#### [Java](#tab/java)

+Use the [AnalyzeImageOptionalParameter](/java/api/com.microsoft.azure.cognitiveservices.vision.computervision.models.analyzeimageoptionalparameter) input in your Analyze call to specify a language. A method call that specifies a language might look like the following.

+```java

+ImageAnalysis analysis = compVisClient.computerVision().analyzeImage().withUrl(pathToRemoteImage)

+ .withVisualFeatures(featuresToExtractFromLocalImage)

+ .language("en")

+ .execute();

+```

+#### [JavaScript](#tab/javascript)

+Use the **language** property of the [ComputerVisionClientAnalyzeImageOptionalParams](/javascript/api/@azure/cognitiveservices-computervision/computervisionclientanalyzeimageoptionalparams) input in your Analyze call to specify a language. A method call that specifies a language might look like the following.

+```javascript

+const result = (await computerVisionClient.analyzeImage(imageURL,{visualFeatures: features, language: 'en'}));

+```

+#### [Python](#tab/python)

+Use the *language* parameter of your [analyze_image](/python/api/azure-cognitiveservices-vision-computervision/azure.cognitiveservices.vision.computervision.operations.computervisionclientoperationsmixin#azure-cognitiveservices-vision-computervision-operations-computervisionclientoperationsmixin-analyze-image) call to specify a language. A method call that specifies a language might look like the following.

+```python

+results_remote = computervision_client.analyze_image(remote_image_url , remote_image_features, remote_image_details, 'en')

+```

+## Get results from the service

+This section shows you how to parse the results of the API call. It includes the API call itself.

+> [!NOTE]

+> **Scoped API calls**

+>

+> Some of the features in Image Analysis can be called directly as well as through the Analyze API call. For example, you can do a scoped analysis of only image tags by making a request to `https://{endpoint}/vision/v3.2/tag` (or to the corresponding method in the SDK). See the [reference documentation](https://westus.dev.cognitive.microsoft.com/docs/services/computer-vision-v3-2/operations/56f91f2e778daf14a499f21b) for other features that can be called separately.

+#### [REST](#tab/rest)

+The service returns a `200` HTTP response, and the body contains the returned data in the form of a JSON string. The following text is an example of a JSON response.

+```json

+{

+ "tags":[

+ {

+ "name":"outdoor",

+ "score":0.976

+ },

+ {

+ "name":"bird",

+ "score":0.95

+ }

+ ],

+ "description":{

+ "tags":[

+ "outdoor",

+ "bird"

+ ],

+ "captions":[

+ {

+ "text":"partridge in a pear tree",

+ "confidence":0.96

+ }

+ ]

+ }

+}

+```

+See the following table for explanations of the fields in this example:

+Field | Type | Content

+|||

+Tags | `object` | The top-level object for an array of tags.

+tags[].Name | `string` | The keyword from the tags classifier.

+tags[].Score | `number` | The confidence score, between 0 and 1.

+description | `object` | The top-level object for an image description.

+description.tags[] | `string` | The list of tags. If there is insufficient confidence in the ability to produce a caption, the tags might be the only information available to the caller.

+description.captions[].text | `string` | A phrase describing the image.

+description.captions[].confidence | `number` | The confidence score for the phrase.

+### Error codes

+See the following list of possible errors and their causes:

+* 400

+ * `InvalidImageUrl` - Image URL is badly formatted or not accessible.

+ * `InvalidImageFormat` - Input data is not a valid image.

+ * `InvalidImageSize` - Input image is too large.

+ * `NotSupportedVisualFeature` - Specified feature type isn't valid.

+ * `NotSupportedImage` - Unsupported image, for example child pornography.

+ * `InvalidDetails` - Unsupported `detail` parameter value.

+ * `NotSupportedLanguage` - The requested operation isn't supported in the language specified.

+ * `BadArgument` - More details are provided in the error message.

+* 415 - Unsupported media type error. The Content-Type isn't in the allowed types:

+ * For an image URL, Content-Type should be `application/json`

+ * For a binary image data, Content-Type should be `application/octet-stream` or `multipart/form-data`

+* 500

+ * `FailedToProcess`

+ * `Timeout` - Image processing timed out.

+ * `InternalServerError`

+#### [C#](#tab/csharp)

+The following code calls the Image Analysis API and prints the results to the console.

+[!code-csharp[](~/cognitive-services-quickstart-code/dotnet/ComputerVision/ImageAnalysisQuickstart.cs?name=snippet_analyze)]

+#### [Java](#tab/java)

+The following code calls the Image Analysis API and prints the results to the console.

+[!code-java[](~/cognitive-services-quickstart-code/java/ComputerVision/src/main/java/ImageAnalysisQuickstart.java?name=snippet_analyze)]

+#### [JavaScript](#tab/javascript)

+The following code calls the Image Analysis API and prints the results to the console.

+[!code-javascript[](~/cognitive-services-quickstart-code/javascript/ComputerVision/ImageAnalysisQuickstart.js?name=snippet_analyze)]

+#### [Python](#tab/python)

+The following code calls the Image Analysis API and prints the results to the console.

+[!code-python[](~/cognitive-services-quickstart-code/python/ComputerVision/ImageAnalysisQuickstart.py?name=snippet_analyze)]

+> [!TIP]

+> While working with Computer Vision, you might encounter transient failures caused by [rate limits](https://azure.microsoft.com/pricing/details/cognitive-services/computer-vision/) enforced by the service, or other transient problems like network outages. For information about handling these types of failures, see [Retry pattern](/azure/architecture/patterns/retry) in the Cloud Design Patterns guide, and the related [Circuit Breaker pattern](/azure/architecture/patterns/circuit-breaker).

+## Next steps

+* Explore the [concept articles](../concept-object-detection.md) to learn more about each feature.

+* See the [API reference](https://westus.dev.cognitive.microsoft.com/docs/services/computer-vision-v3-2/operations/56f91f2e778daf14a499f21b) to learn more about the API functionality.

+ Title: How to call the Read API

+description: Learn how to call the Read API and configure its behavior in detail.

+# Call the Read API

+In this guide, you'll learn how to call the Read API to extract text from images. You'll learn the different ways you can configure the behavior of this API to meet your needs.

+This guide assumes you have already <a href="https://portal.azure.com/#create/Microsoft.CognitiveServicesComputerVision" title="created a Computer Vision resource" target="_blank">create a Computer Vision resource </a> and obtained a key and endpoint URL. If you haven't, follow a [quickstart](../quickstarts-sdk/client-library.md) to get started.

+## Determine how to process the data (optional)

+### Specify the OCR model

+By default, the service will use the latest generally available (GA) model to extract text. Starting with Read 3.2, a `model-version` parameter allows choosing between the GA and preview models for a given API version. The model you specify will be used to extract text with the Read operation.

+When using the Read operation, use the following values for the optional `model-version` parameter.

+|Value| Model used |

+|:--|:-|

+| Not provided | Latest GA model |

+| latest | Latest GA model|

+| [2022-04-30](../whats-new.md#may-2022) | Latest GA model. 164 languages for print text and 9 languages for handwritten text along with several enhancements on quality and performance |

+| [2022-01-30-preview](../whats-new.md#february-2022) | Preview model adds print text support for Hindi, Arabic and related languages. For handwriitten text, adds support for Japanese and Korean. |

+| [2021-09-30-preview](../whats-new.md#september-2021) | Preview model adds print text support for Russian and other Cyrillic languages, For handwriitten text, adds support for Chinese Simplified, French, German, Italian, Portuguese, and Spanish. |

+| 2021-04-12 | 2021 GA model |

+### Input language

+By default, the service extracts all text from your images or documents including mixed languages. The [Read operation](https://westus.dev.cognitive.microsoft.com/docs/services/computer-vision-v3-2/operations/5d986960601faab4bf452005) has an optional request parameter for language. Only provide a language code if you want to force the document to be processed as that specific language. Otherwise, the service may return incomplete and incorrect text.

+### Natural reading order output (Latin languages only)

+By default, the service outputs the text lines in the left to right order. Optionally, with the `readingOrder` request parameter, use `natural` for a more human-friendly reading order output as shown in the following example. This feature is only supported for Latin languages.

+### Select page(s) or page ranges for text extraction

+By default, the service extracts text from all pages in the documents. Optionally, use the `pages` request parameter to specify page numbers or page ranges to extract text from only those pages. The following example shows a document with 10 pages, with text extracted for both cases - all pages (1-10) and selected pages (3-6).

+## Submit data to the service

+You submit either a local image or a remote image to the Read API. For local, you put the binary image data in the HTTP request body. For remote, you specify the image's URL by formatting the request body like the following: `{"url":"http://example.com/images/test.jpg"}`.

+The Read API's [Read call](https://centraluseuap.dev.cognitive.microsoft.com/docs/services/computer-vision-v3-2/operations/5d986960601faab4bf452005) takes an image or PDF document as the input and extracts text asynchronously.

+`https://{endpoint}/vision/v3.2/read/analyze[?language][&pages][&readingOrder]`

+The call returns with a response header field called `Operation-Location`. The `Operation-Location` value is a URL that contains the Operation ID to be used in the next step.

+|Response header| Example value |

+|:--|:-|

+|Operation-Location | `https://cognitiveservice/vision/v3.2/read/analyzeResults/49a36324-fc4b-4387-aa06-090cfbf0064f` |

+> [!NOTE]

+> **Billing**

+>

+> The [Computer Vision pricing](https://azure.microsoft.com/pricing/details/cognitive-services/computer-vision/) page includes the pricing tier for Read. Each analyzed image or page is one transaction. If you call the operation with a PDF or TIFF document containing 100 pages, the Read operation will count it as 100 transactions and you will be billed for 100 transactions. If you made 50 calls to the operation and each call submitted a document with 100 pages, you will be billed for 50 X 100 = 5000 transactions.

+## Get results from the service

+The second step is to call [Get Read Results](https://centraluseuap.dev.cognitive.microsoft.com/docs/services/computer-vision-v3-2/operations/5d9869604be85dee480c8750) operation. This operation takes as input the operation ID that was created by the Read operation.

+`https://{endpoint}/vision/v3.2/read/analyzeResults/{operationId}`

+It returns a JSON response that contains a **status** field with the following possible values.

+|Value | Meaning |

+|:--|:-|

+| `notStarted`| The operation has not started. |

+| `running`| The operation is being processed. |

+| `failed`| The operation has failed. |

+| `succeeded`| The operation has succeeded. |

+You call this operation iteratively until it returns with the **succeeded** value. Use an interval of 1 to 2 seconds to avoid exceeding the requests per second (RPS) rate.

+> [!NOTE]

+> The free tier limits the request rate to 20 calls per minute. The paid tier allows 10 requests per second (RPS) that can be increased upon request. Note your Azure resource identfier and region, and open an Azure support ticket or contact your account team to request a higher request per second (RPS) rate.

+When the **status** field has the `succeeded` value, the JSON response contains the extracted text content from your image or document. The JSON response maintains the original line groupings of recognized words. It includes the extracted text lines and their bounding box coordinates. Each text line includes all extracted words with their coordinates and confidence scores.

+> [!NOTE]

+> The data submitted to the `Read` operation are temporarily encrypted and stored at rest for a short duration, and then deleted. This lets your applications retrieve the extracted text as part of the service response.

+### Sample JSON output

+See the following example of a successful JSON response:

+```json

+{

+ "status": "succeeded",

+ "createdDateTime": "2021-02-04T06:32:08.2752706+00:00",

+ "lastUpdatedDateTime": "2021-02-04T06:32:08.7706172+00:00",

+ "analyzeResult": {

+ "version": "3.2",

+ "readResults": [

+ {

+ "page": 1,

+ "angle": 2.1243,

+ "width": 502,

+ "height": 252,

+ "unit": "pixel",

+ "lines": [

+ {

+ "boundingBox": [

+ 58,

+ 42,

+ 314,

+ 59,

+ 311,

+ 123,

+ 56,

+ 121

+ ],

+ "text": "Tabs vs",

+ "appearance": {

+ "style": {

+ "name": "handwriting",

+ "confidence": 0.96

+ }

+ },

+ "words": [

+ {

+ "boundingBox": [

+ 68,

+ 44,

+ 225,

+ 59,

+ 224,

+ 122,

+ 66,

+ 123

+ ],

+ "text": "Tabs",

+ "confidence": 0.933

+ },

+ {

+ "boundingBox": [

+ 241,

+ 61,

+ 314,

+ 72,

+ 314,

+ 123,

+ 239,

+ 122

+ ],

+ "text": "vs",

+ "confidence": 0.977

+ }

+ ]

+ }

+ ]

+ }

+ ]

+ }

+}

+```

+### Handwritten classification for text lines (Latin languages only)

+The response includes classifying whether each text line is of handwriting style or not, along with a confidence score. This feature is only supported for Latin languages. The following example shows the handwritten classification for the text in the image.

+## Next steps

+- Get started with the [OCR (Read) REST API or client library quickstarts](../quickstarts-sdk/client-library.md).

+- Learn about the [Read 3.2 REST API](https://westus.dev.cognitive.microsoft.com/docs/services/computer-vision-v3-2/operations/5d986960601faab4bf452005).

+ Title: "Find similar faces"

+description: Use the Face service to find similar faces (face search by image).

+# Find similar faces

+The Find Similar operation does face matching between a target face and a set of candidate faces, finding a smaller set of faces that look similar to the target face. This is useful for doing a face search by image.

+This guide demonstrates how to use the Find Similar feature in the different language SDKs. The following sample code assumes you have already authenticated a Face client object. For details on how to do this, follow a [quickstart](../quickstarts-sdk/identity-client-library.md).

+## Set up sample URL

+This guide uses remote images that are accessed by URL. Save a reference to the following URL string. All of the images accessed in this guide are located at this URL path.

+```

+"https://csdx.blob.core.windows.net/resources/Face/media/"

+```

+## Detect faces for comparison

+You need to detect faces in images before you can compare them. In this guide, the following remote image, called *findsimilar.jpg*, will be used as the source:

+

+#### [C#](#tab/csharp)

+The following face detection method is optimized for comparison operations. It doesn't extract detailed face attributes, and it uses an optimized recognition model.

+[!code-csharp[](~/cognitive-services-quickstart-code/dotnet/Face/FaceQuickstart.cs?name=snippet_face_detect_recognize)]

+The following code uses the above method to get face data from a series of images.

+[!code-csharp[](~/cognitive-services-quickstart-code/dotnet/Face/FaceQuickstart.cs?name=snippet_loadfaces)]

+#### [JavaScript](#tab/javascript)

+The following face detection method is optimized for comparison operations. It doesn't extract detailed face attributes, and it uses an optimized recognition model.

+The following code uses the above method to get face data from a series of images.

+#### [REST API](#tab/rest)

+Copy the following cURL command and insert your key and endpoint where appropriate. Then run the command to detect one of the target faces.

+Find the `"faceId"` value in the JSON response and save it to a temporary location. Then, call the above command again for these other image URLs, and save their face IDs as well. You'll use these IDs as the target group of faces from which to find a similar face.

+Finally, detect the single source face that you'll use for matching, and save its ID. Keep this ID separate from the others.

+## Find and print matches

+In this guide, the face detected in the *Family1-Dad1.jpg* image should be returned as the face that's similar to the source image face.

+

+#### [C#](#tab/csharp)

+The following code calls the Find Similar API on the saved list of faces.

+[!code-csharp[](~/cognitive-services-quickstart-code/dotnet/Face/FaceQuickstart.cs?name=snippet_find_similar)]

+The following code prints the match details to the console:

+[!code-csharp[](~/cognitive-services-quickstart-code/dotnet/Face/FaceQuickstart.cs?name=snippet_find_similar_print)]

+#### [JavaScript](#tab/javascript)

+The following method takes a set of target faces and a single source face. Then, it compares them and finds all the target faces that are similar to the source face. Finally, it prints the match details to the console.

+#### [REST API](#tab/rest)

+Copy the following cURL command and insert your key and endpoint where appropriate.

+Paste in the following JSON content for the `body` value:

+Then, copy over the source face ID value to the `"faceId"` field. Then copy the other face IDs, separated by commas, as terms in the `"faceIds"` array.

+Run the command, and the returned JSON should show the correct face ID as a similar match.

+## Next steps

+In this guide, you learned how to call the Find Similar API to do a face search by similarity in a larger group of faces. Next, learn more about the different recognition models available for face comparison operations.

+* [Specify a face recognition model](specify-recognition-model.md)

+ Title: "Example: Real-time video analysis - Face"

+description: Use the Face service to perform near-real-time analysis on frames taken from a live video stream.

+ms.devlang: csharp

+# Example: How to Analyze Videos in Real-time

+This guide will demonstrate how to perform near-real-time analysis on frames taken from a live video stream. The basic components in such a system are:

+- Acquire frames from a video source

+- Select which frames to analyze

+- Submit these frames to the API

+- Consume each analysis result that is returned from the API call

+These samples are written in C# and the code can be found on GitHub here: [https://github.com/Microsoft/Cognitive-Samples-VideoFrameAnalysis](https://github.com/Microsoft/Cognitive-Samples-VideoFrameAnalysis/).

+## The Approach

+There are multiple ways to solve the problem of running near-real-time analysis on video streams. We will start by outlining three approaches in increasing levels of sophistication.

+### A Simple Approach

+The simplest design for a near-real-time analysis system is an infinite loop, where each iteration grabs a frame, analyzes it, and then consumes the result:

+```csharp

+while (true)

+{

+ Frame f = GrabFrame();

+ if (ShouldAnalyze(f))

+ {

+ AnalysisResult r = await Analyze(f);

+ ConsumeResult(r);

+ }

+}

+```

+If our analysis consisted of a lightweight client-side algorithm, this approach would be suitable. However, when analysis happens in the cloud, the latency involved means that an API call might take several seconds. During this time, we are not capturing images, and our thread is essentially doing nothing. Our maximum frame-rate is limited by the latency of the API calls.

+### Parallelizing API Calls

+While a simple single-threaded loop makes sense for a lightweight client-side algorithm, it doesn't fit well with the latency involved in cloud API calls. The solution to this problem is to allow the long-running API calls to execute in parallel with the frame-grabbing. In C#, we could achieve this using Task-based parallelism, for example:

+```csharp

+while (true)

+{

+ Frame f = GrabFrame();

+ if (ShouldAnalyze(f))

+ {

+ var t = Task.Run(async () =>

+ {

+ AnalysisResult r = await Analyze(f);

+ ConsumeResult(r);

+ }

+ }

+}

+```

+This code launches each analysis in a separate Task, which can run in the background while we continue grabbing new frames. With this method we avoid blocking the main thread while waiting for an API call to return, but we have lost some of the guarantees that the simple version provided. Multiple API calls might occur in parallel, and the results might get returned in the wrong order. This could also cause multiple threads to enter the ConsumeResult() function simultaneously, which could be dangerous, if the function is not thread-safe. Finally, this simple code does not keep track of the Tasks that get created, so exceptions will silently disappear. Therefore, the final step is to add a "consumer" thread that will track the analysis tasks, raise exceptions, kill long-running tasks, and ensure that the results get consumed in the correct order.

+### A Producer-Consumer Design

+In our final "producer-consumer" system, we have a producer thread that looks similar to our previous infinite loop. However, instead of consuming analysis results as soon as they are available, the producer simply puts the tasks into a queue to keep track of them.

+```csharp

+// Queue that will contain the API call tasks.

+var taskQueue = new BlockingCollection<Task<ResultWrapper>>();

+

+// Producer thread.

+while (true)

+{

+ // Grab a frame.

+ Frame f = GrabFrame();

+

+ // Decide whether to analyze the frame.

+ if (ShouldAnalyze(f))

+ {

+ // Start a task that will run in parallel with this thread.

+ var analysisTask = Task.Run(async () =>

+ {

+ // Put the frame, and the result/exception into a wrapper object.

+ var output = new ResultWrapper(f);

+ try

+ {

+ output.Analysis = await Analyze(f);

+ }

+ catch (Exception e)

+ {

+ output.Exception = e;

+ }

+ return output;

+ }

+

+ // Push the task onto the queue.

+ taskQueue.Add(analysisTask);

+ }

+}

+```

+We also have a consumer thread that takes tasks off the queue, waits for them to finish, and either displays the result or raises the exception that was thrown. By using the queue, we can guarantee that results get consumed one at a time, in the correct order, without limiting the maximum frame-rate of the system.

+```csharp

+// Consumer thread.

+while (true)

+{

+ // Get the oldest task.

+ Task<ResultWrapper> analysisTask = taskQueue.Take();

+

+ // Await until the task is completed.

+ var output = await analysisTask;

+

+ // Consume the exception or result.

+ if (output.Exception != null)

+ {

+ throw output.Exception;

+ }

+ else

+ {

+ ConsumeResult(output.Analysis);

+ }

+}

+```

+## Implementing the Solution

+### Getting Started

+To get your app up and running as quickly as possible, you will use a flexible implementation of the system described above. To access the code, go to [https://github.com/Microsoft/Cognitive-Samples-VideoFrameAnalysis](https://github.com/Microsoft/Cognitive-Samples-VideoFrameAnalysis).

+The library contains the class FrameGrabber, which implements the producer-consumer system discussed above to process video frames from a webcam. The user can specify the exact form of the API call, and the class uses events to let the calling code know when a new frame is acquired or a new analysis result is available.

+To illustrate some of the possibilities, there are two sample apps that use the library. The first is a simple console app, and a simplified version of it is reproduced below. It grabs frames from the default webcam, and submits them to the Face service for face detection.

+The second sample app is a bit more interesting, and allows you to choose which API to call on the video frames. On the left-hand side, the app shows a preview of the live video, on the right-hand side it shows the most recent API result overlaid on the corresponding frame.

+In most modes, there will be a visible delay between the live video on the left, and the visualized analysis on the right. This delay is the time taken to make the API call. One exception is the "EmotionsWithClientFaceDetect" mode, which performs face detection locally on the client computer using OpenCV, before submitting any images to Cognitive Services. This way, we can visualize the detected face immediately and then update the emotions once the API call returns. This is an example of a "hybrid" approach, where the client can perform some simple processing, and Cognitive Services APIs can augment this with more advanced analysis when necessary.

+

+### Integrating into your codebase

+To get started with this sample, follow these steps:

+1. Create an [Azure account](https://azure.microsoft.com/free/cognitive-services/). If you already have one, you can skip to the next step.

+2. Create resources for Computer Vision and Face in the Azure portal to get your key and endpoint. Make sure to select the free tier (F0) during setup.

+ - [Computer Vision](https://portal.azure.com/#create/Microsoft.CognitiveServicesComputerVision)

+ - [Face](https://portal.azure.com/#create/Microsoft.CognitiveServicesFace)

+ After the resources are deployed, click **Go to resource** to collect your key and endpoint for each resource.

+3. Clone the [Cognitive-Samples-VideoFrameAnalysis](https://github.com/Microsoft/Cognitive-Samples-VideoFrameAnalysis/) GitHub repo.

+4. Open the sample in Visual Studio, and build and run the sample applications:

+ - For BasicConsoleSample, the Face key is hard-coded directly in [BasicConsoleSample/Program.cs](https://github.com/Microsoft/Cognitive-Samples-VideoFrameAnalysis/blob/master/Windows/BasicConsoleSample/Program.cs).

+ - For LiveCameraSample, the keys should be entered into the Settings pane of the app. They will be persisted across sessions as user data.

+

+When you're ready to integrate, **reference the VideoFrameAnalyzer library from your own projects.**

+## Summary

+In this guide, you learned how to run near-real-time analysis on live video streams using the Face, Computer Vision, and Emotion APIs, and how to use our sample code to get started.

+Feel free to provide feedback and suggestions in the [GitHub repository](https://github.com/Microsoft/Cognitive-Samples-VideoFrameAnalysis/) or, for broader API feedback, on our [UserVoice](https://feedback.azure.com/d365community/forum/09041fae-0b25-ec11-b6e6-000d3a4f0858) site.

+## Related Topics

+- [Call the detect API](identity-detect-faces.md)

+ Title: "Call the Detect API - Face"

+description: This guide demonstrates how to use face detection to extract attributes like age, emotion, or head pose from a given image.

+ms.devlang: csharp

+# Call the Detect API

+This guide demonstrates how to use the face detection API to extract attributes like age, emotion, or head pose from a given image. You'll learn the different ways to configure the behavior of this API to meet your needs.

+The code snippets in this guide are written in C# by using the Azure Cognitive Services Face client library. The same functionality is available through the [REST API](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).

+## Setup

+This guide assumes that you already constructed a [FaceClient](/dotnet/api/microsoft.azure.cognitiveservices.vision.face.faceclient) object, named `faceClient`, with a Face key and endpoint URL. For instructions on how to set up this feature, follow one of the quickstarts.

+## Submit data to the service

+To find faces and get their locations in an image, call the [DetectWithUrlAsync](/dotnet/api/microsoft.azure.cognitiveservices.vision.face.faceoperationsextensions.detectwithurlasync) or [DetectWithStreamAsync](/dotnet/api/microsoft.azure.cognitiveservices.vision.face.faceoperationsextensions.detectwithstreamasync) method. **DetectWithUrlAsync** takes a URL string as input, and **DetectWithStreamAsync** takes the raw byte stream of an image as input.

+You can query the returned [DetectedFace](/dotnet/api/microsoft.azure.cognitiveservices.vision.face.models.detectedface) objects for their unique IDs and a rectangle that gives the pixel coordinates of the face. This way, you can tell which face ID maps to which face in the original image.

+For information on how to parse the location and dimensions of the face, see [FaceRectangle](/dotnet/api/microsoft.azure.cognitiveservices.vision.face.models.facerectangle). Usually, this rectangle contains the eyes, eyebrows, nose, and mouth. The top of head, ears, and chin aren't necessarily included. To use the face rectangle to crop a complete head or get a mid-shot portrait, you should expand the rectangle in each direction.

+## Determine how to process the data

+This guide focuses on the specifics of the Detect call, such as what arguments you can pass and what you can do with the returned data. We recommend that you query for only the features you need. Each operation takes more time to complete.

+### Get face landmarks

+[Face landmarks](../concept-face-detection.md#face-landmarks) are a set of easy-to-find points on a face, such as the pupils or the tip of the nose. To get face landmark data, set the _detectionModel_ parameter to `DetectionModel.Detection01` and the _returnFaceLandmarks_ parameter to `true`.

+### Get face attributes

+Besides face rectangles and landmarks, the face detection API can analyze several conceptual attributes of a face. For a full list, see the [Face attributes](../concept-face-detection.md#attributes) conceptual section.

+To analyze face attributes, set the _detectionModel_ parameter to `DetectionModel.Detection01` and the _returnFaceAttributes_ parameter to a list of [FaceAttributeType Enum](/dotnet/api/microsoft.azure.cognitiveservices.vision.face.models.faceattributetype) values.

+## Get results from the service

+### Face landmark results

+The following code demonstrates how you might retrieve the locations of the nose and pupils:

+You also can use face landmark data to accurately calculate the direction of the face. For example, you can define the rotation of the face as a vector from the center of the mouth to the center of the eyes. The following code calculates this vector:

+When you know the direction of the face, you can rotate the rectangular face frame to align it more properly. To crop faces in an image, you can programmatically rotate the image so the faces always appear upright.

+### Face attribute results

+The following code shows how you might retrieve the face attribute data that you requested in the original call.

+To learn more about each of the attributes, see the [Face detection and attributes](../concept-face-detection.md) conceptual guide.

+## Next steps

+In this guide, you learned how to use the various functionalities of face detection and analysis. Next, integrate these features into an app to add face data from users.

+- [Tutorial: Add users to a Face service](../enrollment-overview.md)

+## Related articles

+- [Reference documentation (REST)](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236)

+- [Reference documentation (.NET SDK)](/dotnet/api/overview/azure/cognitiveservices/face-readme)

+ Title: "Migrate your face data across subscriptions - Face"

+description: This guide shows you how to migrate your stored face data from one Face subscription to another.

+ms.devlang: csharp

+# Migrate your face data to a different Face subscription

+This guide shows you how to move face data, such as a saved PersonGroup object with faces, to a different Azure Cognitive Services Face subscription. To move the data, you use the Snapshot feature. This way you avoid having to repeatedly build and train a PersonGroup or FaceList object when you move or expand your operations. For example, perhaps you created a PersonGroup object with a free subscription and now want to migrate it to your paid subscription. Or you might need to sync face data across subscriptions in different regions for a large enterprise operation.

+This same migration strategy also applies to LargePersonGroup and LargeFaceList objects. If you aren't familiar with the concepts in this guide, see their definitions in the [Face recognition concepts](../concept-face-recognition.md) guide. This guide uses the Face .NET client library with C#.

+> [!WARNING]

+> The Snapshot feature might move your data outside the geographic region you originally selected. Data might move to West US, West Europe, and Southeast Asia regions.

+## Prerequisites

+You need the following items:

+- Two Face keys, one with the existing data and one to migrate to. To subscribe to the Face service and get your key, follow the instructions in [Create a Cognitive Services account](../../cognitive-services-apis-create-account.md).

+- The Face subscription ID string that corresponds to the target subscription. To find it, select **Overview** in the Azure portal.

+- Any edition of [Visual Studio 2015 or 2017](https://www.visualstudio.com/downloads/).

+## Create the Visual Studio project

+This guide uses a simple console app to run the face data migration. For a full implementation, see the [Face snapshot sample](https://github.com/Azure-Samples/cognitive-services-dotnet-sdk-samples/tree/master/app-samples/FaceApiSnapshotSample/FaceApiSnapshotSample) on GitHub.

+1. In Visual Studio, create a new Console app .NET Framework project. Name it **FaceApiSnapshotSample**.

+1. Get the required NuGet packages. Right-click your project in the Solution Explorer, and select **Manage NuGet Packages**. Select the **Browse** tab, and select **Include prerelease**. Find and install the following package:

+ - [Microsoft.Azure.CognitiveServices.Vision.Face 2.3.0-preview](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Vision.Face/2.2.0-preview)

+## Create face clients

+In the **Main** method in *Program.cs*, create two [FaceClient](/dotnet/api/microsoft.azure.cognitiveservices.vision.face.faceclient) instances for your source and target subscriptions. This example uses a Face subscription in the East Asia region as the source and a West US subscription as the target. This example demonstrates how to migrate data from one Azure region to another.

+```csharp

+var FaceClientEastAsia = new FaceClient(new ApiKeyServiceClientCredentials("<East Asia Key>"))

+ {

+ Endpoint = "https://southeastasia.api.cognitive.microsoft.com/>"

+ };

+var FaceClientWestUS = new FaceClient(new ApiKeyServiceClientCredentials("<West US Key>"))

+ {

+ Endpoint = "https://westus.api.cognitive.microsoft.com/"

+ };

+```

+Fill in the key values and endpoint URLs for your source and target subscriptions.

+## Prepare a PersonGroup for migration

+You need the ID of the PersonGroup in your source subscription to migrate it to the target subscription. Use the [PersonGroupOperationsExtensions.ListAsync](/dotnet/api/microsoft.azure.cognitiveservices.vision.face.persongroupoperationsextensions.listasync) method to retrieve a list of your PersonGroup objects. Then get the [PersonGroup.PersonGroupId](/dotnet/api/microsoft.azure.cognitiveservices.vision.face.models.persongroup.persongroupid#Microsoft_Azure_CognitiveServices_Vision_Face_Models_PersonGroup_PersonGroupId) property. This process looks different based on what PersonGroup objects you have. In this guide, the source PersonGroup ID is stored in `personGroupId`.

+> [!NOTE]

+> The [sample code](https://github.com/Azure-Samples/cognitive-services-dotnet-sdk-samples/tree/master/app-samples/FaceApiSnapshotSample/FaceApiSnapshotSample) creates and trains a new PersonGroup to migrate. In most cases, you should already have a PersonGroup to use.

+## Take a snapshot of a PersonGroup

+A snapshot is temporary remote storage for certain Face data types. It functions as a kind of clipboard to copy data from one subscription to another. First, you take a snapshot of the data in the source subscription. Then you apply it to a new data object in the target subscription.

+Use the source subscription's FaceClient instance to take a snapshot of the PersonGroup. Use [TakeAsync](/dotnet/api/microsoft.azure.cognitiveservices.vision.face.snapshotoperationsextensions.takeasync) with the PersonGroup ID and the target subscription's ID. If you have multiple target subscriptions, add them as array entries in the third parameter.

+```csharp

+var takeSnapshotResult = await FaceClientEastAsia.Snapshot.TakeAsync(

+ SnapshotObjectType.PersonGroup,

+ personGroupId,

+ new[] { "<Azure West US Subscription ID>" /* Put other IDs here, if multiple target subscriptions wanted */ });

+```

+> [!NOTE]

+> The process of taking and applying snapshots doesn't disrupt any regular calls to the source or target PersonGroups or FaceLists. Don't make simultaneous calls that change the source object, such as [FaceList management calls](/dotnet/api/microsoft.azure.cognitiveservices.vision.face.facelistoperations) or the [PersonGroup Train](/dotnet/api/microsoft.azure.cognitiveservices.vision.face.persongroupoperations) call, for example. The snapshot operation might run before or after those operations or might encounter errors.

+## Retrieve the snapshot ID

+The method used to take snapshots is asynchronous, so you must wait for its completion. Snapshot operations can't be canceled. In this code, the `WaitForOperation` method monitors the asynchronous call. It checks the status every 100 ms. After the operation finishes, retrieve an operation ID by parsing the `OperationLocation` field.

+```csharp

+var takeOperationId = Guid.Parse(takeSnapshotResult.OperationLocation.Split('/')[2]);

+var operationStatus = await WaitForOperation(FaceClientEastAsia, takeOperationId);

+```

+A typical `OperationLocation` value looks like this:

+```csharp

+"/operations/a63a3bdd-a1db-4d05-87b8-dbad6850062a"

+```

+The `WaitForOperation` helper method is here:

+```csharp

+/// <summary>

+/// Waits for the take/apply operation to complete and returns the final operation status.

+/// </summary>

+/// <returns>The final operation status.</returns>

+private static async Task<OperationStatus> WaitForOperation(IFaceClient client, Guid operationId)

+{

+ OperationStatus operationStatus = null;

+ do

+ {

+ if (operationStatus != null)

+ {

+ Thread.Sleep(TimeSpan.FromMilliseconds(100));

+ }

+ // Get the status of the operation.

+ operationStatus = await client.Snapshot.GetOperationStatusAsync(operationId);

+ Console.WriteLine($"Operation Status: {operationStatus.Status}");

+ }

+ while (operationStatus.Status != OperationStatusType.Succeeded

+ && operationStatus.Status != OperationStatusType.Failed);

+ return operationStatus;

+}

+```

+After the operation status shows `Succeeded`, get the snapshot ID by parsing the `ResourceLocation` field of the returned OperationStatus instance.

+```csharp

+var snapshotId = Guid.Parse(operationStatus.ResourceLocation.Split('/')[2]);

+```

+A typical `resourceLocation` value looks like this:

+```csharp

+"/snapshots/e58b3f08-1e8b-4165-81df-aa9858f233dc"

+```

+## Apply a snapshot to a target subscription

+Next, create the new PersonGroup in the target subscription by using a randomly generated ID. Then use the target subscription's FaceClient instance to apply the snapshot to this PersonGroup. Pass in the snapshot ID and the new PersonGroup ID.

+```csharp

+var newPersonGroupId = Guid.NewGuid().ToString();

+var applySnapshotResult = await FaceClientWestUS.Snapshot.ApplyAsync(snapshotId, newPersonGroupId);

+```

+> [!NOTE]

+> A Snapshot object is valid for only 48 hours. Only take a snapshot if you intend to use it for data migration soon after.

+A snapshot apply request returns another operation ID. To get this ID, parse the `OperationLocation` field of the returned applySnapshotResult instance.

+```csharp

+var applyOperationId = Guid.Parse(applySnapshotResult.OperationLocation.Split('/')[2]);

+```

+The snapshot application process is also asynchronous, so again use `WaitForOperation` to wait for it to finish.

+```csharp

+operationStatus = await WaitForOperation(FaceClientWestUS, applyOperationId);

+```

+## Test the data migration

+After you apply the snapshot, the new PersonGroup in the target subscription populates with the original face data. By default, training results are also copied. The new PersonGroup is ready for face identification calls without needing retraining.

+To test the data migration, run the following operations and compare the results they print to the console:

+```csharp

+await DisplayPersonGroup(FaceClientEastAsia, personGroupId);

+await IdentifyInPersonGroup(FaceClientEastAsia, personGroupId);

+await DisplayPersonGroup(FaceClientWestUS, newPersonGroupId);

+// No need to retrain the PersonGroup before identification,

+// training results are copied by snapshot as well.

+await IdentifyInPersonGroup(FaceClientWestUS, newPersonGroupId);

+```

+Use the following helper methods:

+```csharp

+private static async Task DisplayPersonGroup(IFaceClient client, string personGroupId)

+{

+ var personGroup = await client.PersonGroup.GetAsync(personGroupId);

+ Console.WriteLine("PersonGroup:");

+ Console.WriteLine(JsonConvert.SerializeObject(personGroup));

+ // List persons.

+ var persons = await client.PersonGroupPerson.ListAsync(personGroupId);

+ foreach (var person in persons)

+ {

+ Console.WriteLine(JsonConvert.SerializeObject(person));

+ }

+ Console.WriteLine();

+}

+```

+```csharp

+private static async Task IdentifyInPersonGroup(IFaceClient client, string personGroupId)

+{

+ using (var fileStream = new FileStream("data\\PersonGroup\\Daughter\\Daughter1.jpg", FileMode.Open, FileAccess.Read))

+ {

+ var detectedFaces = await client.Face.DetectWithStreamAsync(fileStream);

+ var result = await client.Face.IdentifyAsync(detectedFaces.Select(face => face.FaceId.Value).ToList(), personGroupId);

+ Console.WriteLine("Test identify against PersonGroup");

+ Console.WriteLine(JsonConvert.SerializeObject(result));

+ Console.WriteLine();

+ }

+}

+```

+Now you can use the new PersonGroup in the target subscription.

+To update the target PersonGroup again in the future, create a new PersonGroup to receive the snapshot. To do this, follow the steps in this guide. A single PersonGroup object can have a snapshot applied to it only one time.

+## Clean up resources

+After you finish migrating face data, manually delete the snapshot object.

+```csharp

+await FaceClientEastAsia.Snapshot.DeleteAsync(snapshotId);

+```

+## Next steps

+Next, see the relevant API reference documentation, explore a sample app that uses the Snapshot feature, or follow a how-to guide to start using the other API operations mentioned here:

+- [Snapshot reference documentation (.NET SDK)](/dotnet/api/microsoft.azure.cognitiveservices.vision.face.snapshotoperations)

+- [Face snapshot sample](https://github.com/Azure-Samples/cognitive-services-dotnet-sdk-samples/tree/master/app-samples/FaceApiSnapshotSample/FaceApiSnapshotSample)

+- [Add faces](add-faces.md)

+- [Call the detect API](identity-detect-faces.md)

+ Title: How to mitigate latency when using the Face service

+description: Learn how to mitigate latency when using the Face service.

+ms.devlang: csharp

+# How to: mitigate latency when using the Face service

+You may encounter latency when using the Face service. Latency refers to any kind of delay that occurs when communicating over a network. In general, possible causes of latency include:

+- The physical distance each packet must travel from source to destination.

+- Problems with the transmission medium.

+- Errors in routers or switches along the transmission path.

+- The time required by antivirus applications, firewalls, and other security mechanisms to inspect packets.

+- Malfunctions in client or server applications.

+This article talks about possible causes of latency specific to using the Azure Cognitive Services, and how you can mitigate these causes.

+> [!NOTE]

+> Azure Cognitive Services does not provide any Service Level Agreement (SLA) regarding latency.

+## Possible causes of latency

+### Slow connection between the Cognitive Service and a remote URL

+Some Azure services provide methods that obtain data from a remote URL that you provide. For example, when you call the [DetectWithUrlAsync method](/dotnet/api/microsoft.azure.cognitiveservices.vision.face.faceoperationsextensions.detectwithurlasync#Microsoft_Azure_CognitiveServices_Vision_Face_FaceOperationsExtensions_DetectWithUrlAsync_Microsoft_Azure_CognitiveServices_Vision_Face_IFaceOperations_System_String_System_Nullable_System_Boolean__System_Nullable_System_Boolean__System_Collections_Generic_IList_System_Nullable_Microsoft_Azure_CognitiveServices_Vision_Face_Models_FaceAttributeType___System_String_System_Nullable_System_Boolean__System_String_System_Threading_CancellationToken_) of the Face service, you can specify the URL of an image in which the service tries to detect faces.

+```csharp

+var faces = await client.Face.DetectWithUrlAsync("https://www.biography.com/.image/t_share/MTQ1MzAyNzYzOTgxNTE0NTEz/john-f-kennedymini-biography.jpg");

+```

+The Face service must then download the image from the remote server. If the connection from the Face service to the remote server is slow, that will affect the response time of the Detect method.

+To mitigate this situation, consider [storing the image in Azure Premium Blob Storage](../../../storage/blobs/storage-upload-process-images.md?tabs=dotnet). For example:

+``` csharp

+var faces = await client.Face.DetectWithUrlAsync("https://csdx.blob.core.windows.net/resources/Face/Images/Family1-Daughter1.jpg");

+```

+### Large upload size

+Some Azure services provide methods that obtain data from a file that you upload. For example, when you call the [DetectWithStreamAsync method](/dotnet/api/microsoft.azure.cognitiveservices.vision.face.faceoperationsextensions.detectwithstreamasync#Microsoft_Azure_CognitiveServices_Vision_Face_FaceOperationsExtensions_DetectWithStreamAsync_Microsoft_Azure_CognitiveServices_Vision_Face_IFaceOperations_System_IO_Stream_System_Nullable_System_Boolean__System_Nullable_System_Boolean__System_Collections_Generic_IList_System_Nullable_Microsoft_Azure_CognitiveServices_Vision_Face_Models_FaceAttributeType___System_String_System_Nullable_System_Boolean__System_String_System_Threading_CancellationToken_) of the Face service, you can upload an image in which the service tries to detect faces.

+```csharp

+using FileStream fs = File.OpenRead(@"C:\images\face.jpg");

+System.Collections.Generic.IList<DetectedFace> faces = await client.Face.DetectWithStreamAsync(fs, detectionModel: DetectionModel.Detection02);

+```

+If the file to upload is large, that will impact the response time of the `DetectWithStreamAsync` method, for the following reasons:

+- It takes longer to upload the file.

+- It takes the service longer to process the file, in proportion to the file size.

+Mitigations:

+- Consider [storing the image in Azure Premium Blob Storage](../../../storage/blobs/storage-upload-process-images.md?tabs=dotnet). For example:

+``` csharp

+var faces = await client.Face.DetectWithUrlAsync("https://csdx.blob.core.windows.net/resources/Face/Images/Family1-Daughter1.jpg");

+```

+- Consider uploading a smaller file.

+ - See the guidelines regarding [input data for face detection](../concept-face-detection.md#input-data) and [input data for face recognition](../concept-face-recognition.md#input-data).

+ - For face detection, when using detection model `DetectionModel.Detection01`, reducing the image file size will increase processing speed. When you use detection model `DetectionModel.Detection02`, reducing the image file size will only increase processing speed if the image file is smaller than 1920x1080.

+ - For face recognition, reducing the face size to 200x200 pixels doesn't affect the accuracy of the recognition model.

+ - The performance of the `DetectWithUrlAsync` and `DetectWithStreamAsync` methods also depends on how many faces are in an image. The Face service can return up to 100 faces for an image. Faces are ranked by face rectangle size from large to small.

+ - If you need to call multiple service methods, consider calling them in parallel if your application design allows for it. For example, if you need to detect faces in two images to perform a face comparison:

+```csharp

+var faces_1 = client.Face.DetectWithUrlAsync("https://www.biography.com/.image/t_share/MTQ1MzAyNzYzOTgxNTE0NTEz/john-f-kennedymini-biography.jpg");

+var faces_2 = client.Face.DetectWithUrlAsync("https://www.biography.com/.image/t_share/MTQ1NDY3OTIxMzExNzM3NjE3/john-f-kennedydebating-richard-nixon.jpg");

+Task.WaitAll (new Task<IList<DetectedFace>>[] { faces_1, faces_2 });

+IEnumerable<DetectedFace> results = faces_1.Result.Concat (faces_2.Result);

+```

+### Slow connection between your compute resource and the Face service

+If your computer has a slow connection to the Face service, this will affect the response time of service methods.

+Mitigations:

+- When you create your Face subscription, make sure to choose the region closest to where your application is hosted.

+- If you need to call multiple service methods, consider calling them in parallel if your application design allows for it. See the previous section for an example.

+- If longer latencies affect the user experience, choose a timeout threshold (for example, maximum 5 seconds) before retrying the API call.

+## Next steps

+In this guide, you learned how to mitigate latency when using the Face service. Next, learn how to scale up from existing PersonGroup and FaceList objects to LargePersonGroup and LargeFaceList objects, respectively.

+> [!div class="nextstepaction"]

+> [Example: Use the large-scale feature](use-large-scale.md)

+## Related topics

+- [Reference documentation (REST)](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236)

+- [Reference documentation (.NET SDK)](/dotnet/api/overview/azure/cognitiveservices/face-readme)

+ Title: How to specify a detection model - Face

+description: This article will show you how to choose which face detection model to use with your Azure Face application.

+ms.devlang: csharp

+# Specify a face detection model

+This guide shows you how to specify a face detection model for the Azure Face service.

+The Face service uses machine learning models to perform operations on human faces in images. We continue to improve the accuracy of our models based on customer feedback and advances in research, and we deliver these improvements as model updates. Developers have the option to specify which version of the face detection model they'd like to use; they can choose the model that best fits their use case.

+Read on to learn how to specify the face detection model in certain face operations. The Face service uses face detection whenever it converts an image of a face into some other form of data.

+If you aren't sure whether you should use the latest model, skip to the [Evaluate different models](#evaluate-different-models) section to evaluate the new model and compare results using your current data set.

+## Prerequisites

+You should be familiar with the concept of AI face detection. If you aren't, see the face detection conceptual guide or how-to guide:

+* [Face detection concepts](../concept-face-detection.md)

+* [Call the detect API](identity-detect-faces.md)

+## Detect faces with specified model

+Face detection finds the bounding-box locations of human faces and identifies their visual landmarks. It extracts the face's features and stores them for later use in [recognition](../concept-face-recognition.md) operations.

+When you use the [Face - Detect] API, you can assign the model version with the `detectionModel` parameter. The available values are:

+* `detection_01`

+* `detection_02`

+* `detection_03`

+A request URL for the [Face - Detect] REST API will look like this:

+`https://westus.api.cognitive.microsoft.com/face/v1.0/detect[?returnFaceId][&returnFaceLandmarks][&returnFaceAttributes][&recognitionModel][&returnRecognitionModel][&detectionModel]&subscription-key=<Subscription key>`

+If you are using the client library, you can assign the value for `detectionModel` by passing in an appropriate string. If you leave it unassigned, the API will use the default model version (`detection_01`). See the following code example for the .NET client library.

+```csharp

+string imageUrl = "https://news.microsoft.com/ceo/assets/photos/06_web.jpg";

+var faces = await faceClient.Face.DetectWithUrlAsync(imageUrl, false, false, recognitionModel: "recognition_04", detectionModel: "detection_03");

+```

+## Add face to Person with specified model

+The Face service can extract face data from an image and associate it with a **Person** object through the [PersonGroup Person - Add Face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523b) API. In this API call, you can specify the detection model in the same way as in [Face - Detect].

+See the following code example for the .NET client library.

+```csharp

+// Create a PersonGroup and add a person with face detected by "detection_03" model

+string personGroupId = "mypersongroupid";

+await faceClient.PersonGroup.CreateAsync(personGroupId, "My Person Group Name", recognitionModel: "recognition_04");

+string personId = (await faceClient.PersonGroupPerson.CreateAsync(personGroupId, "My Person Name")).PersonId;

+string imageUrl = "https://news.microsoft.com/ceo/assets/photos/06_web.jpg";

+await client.PersonGroupPerson.AddFaceFromUrlAsync(personGroupId, personId, imageUrl, detectionModel: "detection_03");

+```

+This code creates a **PersonGroup** with ID `mypersongroupid` and adds a **Person** to it. Then it adds a Face to this **Person** using the `detection_03` model. If you don't specify the *detectionModel* parameter, the API will use the default model, `detection_01`.

+> [!NOTE]

+> You don't need to use the same detection model for all faces in a **Person** object, and you don't need to use the same detection model when detecting new faces to compare with a **Person** object (in the [Face - Identify] API, for example).

+## Add face to FaceList with specified model

+You can also specify a detection model when you add a face to an existing **FaceList** object. See the following code example for the .NET client library.

+```csharp

+await faceClient.FaceList.CreateAsync(faceListId, "My face collection", recognitionModel: "recognition_04");

+string imageUrl = "https://news.microsoft.com/ceo/assets/photos/06_web.jpg";

+await client.FaceList.AddFaceFromUrlAsync(faceListId, imageUrl, detectionModel: "detection_03");

+```

+This code creates a **FaceList** called `My face collection` and adds a Face to it with the `detection_03` model. If you don't specify the *detectionModel* parameter, the API will use the default model, `detection_01`.

+> [!NOTE]

+> You don't need to use the same detection model for all faces in a **FaceList** object, and you don't need to use the same detection model when detecting new faces to compare with a **FaceList** object.

+## Evaluate different models

+The different face detection models are optimized for different tasks. See the following table for an overview of the differences.

+|**detection_01** |**detection_02** |**detection_03**

+||||

+|Default choice for all face detection operations. | Released in May 2019 and available optionally in all face detection operations. | Released in February 2021 and available optionally in all face detection operations.

+|Not optimized for small, side-view, or blurry faces. | Improved accuracy on small, side-view, and blurry faces. | Further improved accuracy, including on smaller faces (64x64 pixels) and rotated face orientations.

+|Returns main face attributes (head pose, age, emotion, and so on) if they're specified in the detect call. | Does not return face attributes. | Returns mask and head pose attributes if they're specified in the detect call.

+|Returns face landmarks if they're specified in the detect call. | Does not return face landmarks. | Returns face landmarks if they're specified in the detect call.

+The best way to compare the performances of the detection models is to use them on a sample dataset. We recommend calling the [Face - Detect] API on a variety of images, especially images of many faces or of faces that are difficult to see, using each detection model. Pay attention to the number of faces that each model returns.

+## Next steps

+In this article, you learned how to specify the detection model to use with different Face APIs. Next, follow a quickstart to get started with face detection and analysis.

+* [Face .NET SDK](../quickstarts-sdk/identity-client-library.md?pivots=programming-language-csharp%253fpivots%253dprogramming-language-csharp)

+* [Face Python SDK](../quickstarts-sdk/identity-client-library.md?pivots=programming-language-python%253fpivots%253dprogramming-language-python)

+[Face - Detect]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d

+[Face - Find Similar]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237

+[Face - Identify]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239

+[Face - Verify]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a

+[PersonGroup - Create]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244

+[PersonGroup - Get]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395246

+[PersonGroup Person - Add Face]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523b

+[PersonGroup - Train]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249

+[LargePersonGroup - Create]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d

+[FaceList - Create]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b

+[FaceList - Get]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c

+[FaceList - Add Face]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250

+[LargeFaceList - Create]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc

+ Title: How to specify a recognition model - Face

+description: This article will show you how to choose which recognition model to use with your Azure Face application.

+ms.devlang: csharp

+# Specify a face recognition model

+This guide shows you how to specify a face recognition model for face detection, identification and similarity search using the Azure Face service.

+The Face service uses machine learning models to perform operations on human faces in images. We continue to improve the accuracy of our models based on customer feedback and advances in research, and we deliver these improvements as model updates. Developers can specify which version of the face recognition model they'd like to use. They can choose the model that best fits their use case.

+The Azure Face service has four recognition models available. The models _recognition_01_ (published 2017), _recognition_02_ (published 2019), and _recognition_03_ (published 2020) are continually supported to ensure backwards compatibility for customers using FaceLists or **PersonGroup**s created with these models. A **FaceList** or **PersonGroup** will always use the recognition model it was created with, and new faces will become associated with this model when they're added. This can't be changed after creation and customers will need to use the corresponding recognition model with the corresponding **FaceList** or **PersonGroup**.

+You can move to later recognition models at your own convenience; however, you'll need to create new FaceLists and PersonGroups with the recognition model of your choice.

+The _recognition_04_ model (published 2021) is the most accurate model currently available. If you're a new customer, we recommend using this model. _Recognition_04_ will provide improved accuracy for both similarity comparisons and person-matching comparisons. _Recognition_04_ improves recognition for enrolled users wearing face covers (surgical masks, N95 masks, cloth masks). Now you can build safe and seamless user experiences that use the latest _detection_03_ model to detect whether an enrolled user is wearing a face cover. Then you can use the latest _recognition_04_ model to recognize their identity. Each model operates independently of the others, and a confidence threshold set for one model isn't meant to be compared across the other recognition models.

+Read on to learn how to specify a selected model in different Face operations while avoiding model conflicts. If you're an advanced user and would like to determine whether you should switch to the latest model, skip to the [Evaluate different models](#evaluate-different-models) section. You can evaluate the new model and compare results using your current data set.

+## Prerequisites

+You should be familiar with the concepts of AI face detection and identification. If you aren't, see these guides first:

+* [Face detection concepts](../concept-face-detection.md)

+* [Face recognition concepts](../concept-face-recognition.md)

+* [Call the detect API](identity-detect-faces.md)

+## Detect faces with specified model

+Face detection identifies the visual landmarks of human faces and finds their bounding-box locations. It also extracts the face's features and stores them for use in identification. All of this information forms the representation of one face.

+The recognition model is used when the face features are extracted, so you can specify a model version when performing the Detect operation.

+When using the [Face - Detect] API, assign the model version with the `recognitionModel` parameter. The available values are:

+* recognition_01

+* recognition_02

+* recognition_03

+* recognition_04

+Optionally, you can specify the _returnRecognitionModel_ parameter (default **false**) to indicate whether _recognitionModel_ should be returned in response. So, a request URL for the [Face - Detect] REST API will look like this:

+`https://westus.api.cognitive.microsoft.com/face/v1.0/detect[?returnFaceId][&returnFaceLandmarks][&returnFaceAttributes][&recognitionModel][&returnRecognitionModel]&subscription-key=<Subscription key>`

+If you're using the client library, you can assign the value for `recognitionModel` by passing a string representing the version. If you leave it unassigned, a default model version of `recognition_01` will be used. See the following code example for the .NET client library.

+```csharp

+string imageUrl = "https://news.microsoft.com/ceo/assets/photos/06_web.jpg";

+var faces = await faceClient.Face.DetectWithUrlAsync(imageUrl, true, true, recognitionModel: "recognition_01", returnRecognitionModel: true);

+```

+## Identify faces with specified model

+The Face service can extract face data from an image and associate it with a **Person** object (through the [Add face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523b) API call, for example), and multiple **Person** objects can be stored together in a **PersonGroup**. Then, a new face can be compared against a **PersonGroup** (with the [Face - Identify] call), and the matching person within that group can be identified.

+A **PersonGroup** should have one unique recognition model for all of the **Person**s, and you can specify this using the `recognitionModel` parameter when you create the group ([PersonGroup - Create] or [LargePersonGroup - Create]). If you don't specify this parameter, the original `recognition_01` model is used. A group will always use the recognition model it was created with, and new faces will become associated with this model when they're added to it. This can't be changed after a group's creation. To see what model a **PersonGroup** is configured with, use the [PersonGroup - Get] API with the _returnRecognitionModel_ parameter set as **true**.

+See the following code example for the .NET client library.

+```csharp

+// Create an empty PersonGroup with "recognition_04" model

+string personGroupId = "mypersongroupid";

+await faceClient.PersonGroup.CreateAsync(personGroupId, "My Person Group Name", recognitionModel: "recognition_04");

+```

+In this code, a **PersonGroup** with ID `mypersongroupid` is created, and it's set up to use the _recognition_04_ model to extract face features.

+Correspondingly, you need to specify which model to use when detecting faces to compare against this **PersonGroup** (through the [Face - Detect] API). The model you use should always be consistent with the **PersonGroup**'s configuration; otherwise, the operation will fail due to incompatible models.

+There is no change in the [Face - Identify] API; you only need to specify the model version in detection.

+## Find similar faces with specified model

+You can also specify a recognition model for similarity search. You can assign the model version with `recognitionModel` when creating the **FaceList** with [FaceList - Create] API or [LargeFaceList - Create]. If you don't specify this parameter, the `recognition_01` model is used by default. A **FaceList** will always use the recognition model it was created with, and new faces will become associated with this model when they're added to the list; you can't change this after creation. To see what model a **FaceList** is configured with, use the [FaceList - Get] API with the _returnRecognitionModel_ parameter set as **true**.

+See the following code example for the .NET client library.

+```csharp

+await faceClient.FaceList.CreateAsync(faceListId, "My face collection", recognitionModel: "recognition_04");

+```

+This code creates a **FaceList** called `My face collection`, using the _recognition_04_ model for feature extraction. When you search this **FaceList** for similar faces to a new detected face, that face must have been detected ([Face - Detect]) using the _recognition_04_ model. As in the previous section, the model needs to be consistent.

+There is no change in the [Face - Find Similar] API; you only specify the model version in detection.

+## Verify faces with specified model

+The [Face - Verify] API checks whether two faces belong to the same person. There is no change in the Verify API with regard to recognition models, but you can only compare faces that were detected with the same model.

+## Evaluate different models

+If you'd like to compare the performances of different recognition models on your own data, you'll need to:

+1. Create four PersonGroups using _recognition_01_, _recognition_02_, _recognition_03_, and _recognition_04_ respectively.

+1. Use your image data to detect faces and register them to **Person**s within these four **PersonGroup**s.

+1. Train your PersonGroups using the PersonGroup - Train API.

+1. Test with Face - Identify on all four **PersonGroup**s and compare the results.

+If you normally specify a confidence threshold (a value between zero and one that determines how confident the model must be to identify a face), you may need to use different thresholds for different models. A threshold for one model isn't meant to be shared to another and won't necessarily produce the same results.

+## Next steps

+In this article, you learned how to specify the recognition model to use with different Face service APIs. Next, follow a quickstart to get started with face detection.

+* [Face .NET SDK](../quickstarts-sdk/identity-client-library.md?pivots=programming-language-csharp%253fpivots%253dprogramming-language-csharp)

+* [Face Python SDK](../quickstarts-sdk/identity-client-library.md?pivots=programming-language-python%253fpivots%253dprogramming-language-python)

+[Face - Detect]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d

+[Face - Find Similar]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237

+[Face - Identify]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239

+[Face - Verify]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a

+[PersonGroup - Create]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244

+[PersonGroup - Get]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395246

+[PersonGroup Person - Add Face]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523b

+[PersonGroup - Train]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249

+[LargePersonGroup - Create]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d

+[FaceList - Create]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b

+[FaceList - Get]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c

+[LargeFaceList - Create]: https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc

+ Title: Use the HeadPose attribute

+description: Learn how to use the HeadPose attribute to automatically rotate the face rectangle or detect head gestures in a video feed.

+ms.devlang: csharp

+# Use the HeadPose attribute

+In this guide, you'll see how you can use the HeadPose attribute of a detected face to enable some key scenarios.

+## Rotate the face rectangle

+The face rectangle, returned with every detected face, marks the location and size of the face in the image. By default, the rectangle is always aligned with the image (its sides are vertical and horizontal); this can be inefficient for framing angled faces. In situations where you want to programmatically crop faces in an image, it's better to be able to rotate the rectangle to crop.

+The [Cognitive Services Face WPF (Windows Presentation Foundation)](https://github.com/Azure-Samples/cognitive-services-dotnet-sdk-samples/tree/master/app-samples/Cognitive-Services-Face-WPF) sample app uses the HeadPose attribute to rotate its detected face rectangles.

+### Explore the sample code

+You can programmatically rotate the face rectangle by using the HeadPose attribute. If you specify this attribute when detecting faces (see [Call the detect API](identity-detect-faces.md)), you will be able to query it later. The following method from the [Cognitive Services Face WPF](https://github.com/Azure-Samples/cognitive-services-dotnet-sdk-samples/tree/master/app-samples/Cognitive-Services-Face-WPF) app takes a list of **DetectedFace** objects and returns a list of **[Face](https://github.com/Azure-Samples/cognitive-services-dotnet-sdk-samples/blob/master/app-samples/Cognitive-Services-Face-WPF/Sample-WPF/Controls/Face.cs)** objects. **Face** here is a custom class that stores face data, including the updated rectangle coordinates. New values are calculated for **top**, **left**, **width**, and **height**, and a new field **FaceAngle** specifies the rotation.

+```csharp

+/// <summary>

+/// Calculate the rendering face rectangle

+/// </summary>

+/// <param name="faces">Detected face from service</param>

+/// <param name="maxSize">Image rendering size</param>

+/// <param name="imageInfo">Image width and height</param>

+/// <returns>Face structure for rendering</returns>

+public static IEnumerable<Face> CalculateFaceRectangleForRendering(IList<DetectedFace> faces, int maxSize, Tuple<int, int> imageInfo)

+{

+ var imageWidth = imageInfo.Item1;

+ var imageHeight = imageInfo.Item2;

+ var ratio = (float)imageWidth / imageHeight;

+ int uiWidth = 0;

+ int uiHeight = 0;

+ if (ratio > 1.0)

+ {

+ uiWidth = maxSize;

+ uiHeight = (int)(maxSize / ratio);

+ }

+ else

+ {

+ uiHeight = maxSize;

+ uiWidth = (int)(ratio * uiHeight);

+ }

+ var uiXOffset = (maxSize - uiWidth) / 2;

+ var uiYOffset = (maxSize - uiHeight) / 2;

+ var scale = (float)uiWidth / imageWidth;

+ foreach (var face in faces)

+ {

+ var left = (int)(face.FaceRectangle.Left * scale + uiXOffset);

+ var top = (int)(face.FaceRectangle.Top * scale + uiYOffset);

+ // Angle of face rectangles, default value is 0 (not rotated).

+ double faceAngle = 0;

+ // If head pose attributes have been obtained, re-calculate the left & top (X & Y) positions.

+ if (face.FaceAttributes?.HeadPose != null)

+ {

+ // Head pose's roll value acts directly as the face angle.

+ faceAngle = face.FaceAttributes.HeadPose.Roll;

+ var angleToPi = Math.Abs((faceAngle / 180) * Math.PI);

+ // _____ | / \ |

+ // |____| => |/ /|

+ // | \ / |

+ // Re-calculate the face rectangle's left & top (X & Y) positions.

+ var newLeft = face.FaceRectangle.Left +

+ face.FaceRectangle.Width / 2 -

+ (face.FaceRectangle.Width * Math.Sin(angleToPi) + face.FaceRectangle.Height * Math.Cos(angleToPi)) / 2;

+ var newTop = face.FaceRectangle.Top +

+ face.FaceRectangle.Height / 2 -

+ (face.FaceRectangle.Height * Math.Sin(angleToPi) + face.FaceRectangle.Width * Math.Cos(angleToPi)) / 2;

+ left = (int)(newLeft * scale + uiXOffset);

+ top = (int)(newTop * scale + uiYOffset);

+ }

+ yield return new Face()

+ {

+ FaceId = face.FaceId?.ToString(),

+ Left = left,

+ Top = top,

+ OriginalLeft = (int)(face.FaceRectangle.Left * scale + uiXOffset),

+ OriginalTop = (int)(face.FaceRectangle.Top * scale + uiYOffset),

+ Height = (int)(face.FaceRectangle.Height * scale),

+ Width = (int)(face.FaceRectangle.Width * scale),

+ FaceAngle = faceAngle,

+ };

+ }

+}

+```

+### Display the updated rectangle

+From here, you can use the returned **Face** objects in your display. The following lines from [FaceDetectionPage.xaml](https://github.com/Azure-Samples/cognitive-services-dotnet-sdk-samples/blob/master/app-samples/Cognitive-Services-Face-WPF/Sample-WPF/Controls/FaceDetectionPage.xaml) show how the new rectangle is rendered from this data:

+```xaml

+ <DataTemplate>

+ <Rectangle Width="{Binding Width}" Height="{Binding Height}" Stroke="#FF26B8F4" StrokeThickness="1">

+ <Rectangle.LayoutTransform>

+ <RotateTransform Angle="{Binding FaceAngle}"/>

+ </Rectangle.LayoutTransform>

+ </Rectangle>

+</DataTemplate>

+```

+## Detect head gestures

+You can detect head gestures like nodding and head shaking by tracking HeadPose changes in real time. You can use this feature as a custom liveness detector.

+Liveness detection is the task of determining that a subject is a real person and not an image or video representation. A head gesture detector could serve as one way to help verify liveness, especially as opposed to an image representation of a person.

+> [!CAUTION]

+> To detect head gestures in real time, you'll need to call the Face API at a high rate (more than once per second). If you have a free-tier (f0) subscription, this will not be possible. If you have a paid-tier subscription, make sure you've calculated the costs of making rapid API calls for head gesture detection.

+See the [Face HeadPose Sample](https://github.com/Azure-Samples/cognitive-services-dotnet-sdk-samples/tree/master/app-samples/FaceAPIHeadPoseSample) on GitHub for a working example of head gesture detection.

+## Next steps

+See the [Cognitive Services Face WPF](https://github.com/Azure-Samples/cognitive-services-dotnet-sdk-samples/tree/master/app-samples/Cognitive-Services-Face-WPF) app on GitHub for a working example of rotated face rectangles. Or, see the [Face HeadPose Sample](https://github.com/Azure-Samples/cognitive-services-dotnet-sdk-samples/tree/master/app-samples) app, which tracks the HeadPose attribute in real time to detect head movements.

+ Title: "Example: Use the Large-Scale feature - Face"

+description: This guide is an article on how to scale up from existing PersonGroup and FaceList objects to LargePersonGroup and LargeFaceList objects.

+ms.devlang: csharp

+# Example: Use the large-scale feature

+This guide is an advanced article on how to scale up from existing PersonGroup and FaceList objects to LargePersonGroup and LargeFaceList objects, respectively. This guide demonstrates the migration process. It assumes a basic familiarity with PersonGroup and FaceList objects, the [Train](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4) operation, and the face recognition functions. To learn more about these subjects, see the [face recognition](../concept-face-recognition.md) conceptual guide.

+LargePersonGroup and LargeFaceList are collectively referred to as large-scale operations. LargePersonGroup can contain up to 1 million persons, each with a maximum of 248 faces. LargeFaceList can contain up to 1 million faces. The large-scale operations are similar to the conventional PersonGroup and FaceList but have some differences because of the new architecture.

+The samples are written in C# by using the Azure Cognitive Services Face client library.

+> [!NOTE]

+> To enable Face search performance for Identification and FindSimilar in large scale, introduce a Train operation to preprocess the LargeFaceList and LargePersonGroup. The training time varies from seconds to about half an hour based on the actual capacity. During the training period, it's possible to perform Identification and FindSimilar if a successful training operating was done before. The drawback is that the new added persons and faces don't appear in the result until a new post migration to large-scale training is completed.

+## Step 1: Initialize the client object

+When you use the Face client library, the key and subscription endpoint are passed in through the constructor of the FaceClient class. For example:

+```csharp

+string SubscriptionKey = "<Key>";

+// Use your own subscription endpoint corresponding to the key.

+string SubscriptionEndpoint = "https://westus.api.cognitive.microsoft.com";

+private readonly IFaceClient faceClient = new FaceClient(

+ new ApiKeyServiceClientCredentials(subscriptionKey),

+ new System.Net.Http.DelegatingHandler[] { });

+faceClient.Endpoint = SubscriptionEndpoint

+```

+To get the key with its corresponding endpoint, go to the Azure Marketplace from the Azure portal.

+For more information, see [Subscriptions](https://azure.microsoft.com/services/cognitive-services/directory/vision/).

+## Step 2: Code migration

+This section focuses on how to migrate PersonGroup or FaceList implementation to LargePersonGroup or LargeFaceList. Although LargePersonGroup or LargeFaceList differs from PersonGroup or FaceList in design and internal implementation, the API interfaces are similar for backward compatibility.

+Data migration isn't supported. You re-create the LargePersonGroup or LargeFaceList instead.

+### Migrate a PersonGroup to a LargePersonGroup

+Migration from a PersonGroup to a LargePersonGroup is simple. They share exactly the same group-level operations.

+For PersonGroup- or person-related implementation, it's necessary to change only the API paths or SDK class/module to LargePersonGroup and LargePersonGroup Person.

+Add all of the faces and persons from the PersonGroup to the new LargePersonGroup. For more information, see [Add faces](add-faces.md).

+### Migrate a FaceList to a LargeFaceList

+| FaceList APIs | LargeFaceList APIs |

+|::|::|

+| Create | Create |

+| Delete | Delete |

+| Get | Get |

+| List | List |

+| Update | Update |

+| - | Train |

+| - | Get Training Status |

+The preceding table is a comparison of list-level operations between FaceList and LargeFaceList. As is shown, LargeFaceList comes with new operations, Train and Get Training Status, when compared with FaceList. Training the LargeFaceList is a precondition of the

+[FindSimilar](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) operation. Training isn't required for FaceList. The following snippet is a helper function to wait for the training of a LargeFaceList:

+```csharp

+/// <summary>

+/// Helper function to train LargeFaceList and wait for finish.

+/// </summary>

+/// <remarks>

+/// The time interval can be adjusted considering the following factors:

+/// - The training time which depends on the capacity of the LargeFaceList.

+/// - The acceptable latency for getting the training status.

+/// - The call frequency and cost.

+///

+/// Estimated training time for LargeFaceList in different scale:

+/// - 1,000 faces cost about 1 to 2 seconds.

+/// - 10,000 faces cost about 5 to 10 seconds.

+/// - 100,000 faces cost about 1 to 2 minutes.

+/// - 1,000,000 faces cost about 10 to 30 minutes.

+/// </remarks>

+/// <param name="largeFaceListId">The Id of the LargeFaceList for training.</param>

+/// <param name="timeIntervalInMilliseconds">The time interval for getting training status in milliseconds.</param>

+/// <returns>A task of waiting for LargeFaceList training finish.</returns>

+private static async Task TrainLargeFaceList(

+ string largeFaceListId,

+ int timeIntervalInMilliseconds = 1000)

+{

+ // Trigger a train call.

+ await FaceClient.LargeTrainLargeFaceListAsync(largeFaceListId);

+ // Wait for training finish.

+ while (true)

+ {

+ Task.Delay(timeIntervalInMilliseconds).Wait();

+ var status = await faceClient.LargeFaceList.TrainAsync(largeFaceListId);

+ if (status.Status == Status.Running)

+ {

+ continue;

+ }

+ else if (status.Status == Status.Succeeded)

+ {

+ break;

+ }

+ else

+ {

+ throw new Exception("The train operation is failed!");

+ }

+ }

+}

+```

+Previously, a typical use of FaceList with added faces and FindSimilar looked like the following:

+```csharp

+// Create a FaceList.

+const string FaceListId = "myfacelistid_001";

+const string FaceListName = "MyFaceListDisplayName";

+const string ImageDir = @"/path/to/FaceList/images";

+faceClient.FaceList.CreateAsync(FaceListId, FaceListName).Wait();

+// Add Faces to the FaceList.

+Parallel.ForEach(

+ Directory.GetFiles(ImageDir, "*.jpg"),

+ async imagePath =>

+ {

+ using (Stream stream = File.OpenRead(imagePath))

+ {

+ await faceClient.FaceList.AddFaceFromStreamAsync(FaceListId, stream);

+ }

+ });

+// Perform FindSimilar.

+const string QueryImagePath = @"/path/to/query/image";

+var results = new List<SimilarPersistedFace[]>();

+using (Stream stream = File.OpenRead(QueryImagePath))

+{

+ var faces = faceClient.Face.DetectWithStreamAsync(stream).Result;

+ foreach (var face in faces)

+ {

+ results.Add(await faceClient.Face.FindSimilarAsync(face.FaceId, FaceListId, 20));

+ }

+}

+```

+When migrating it to LargeFaceList, it becomes the following:

+```csharp

+// Create a LargeFaceList.

+const string LargeFaceListId = "mylargefacelistid_001";

+const string LargeFaceListName = "MyLargeFaceListDisplayName";

+const string ImageDir = @"/path/to/FaceList/images";

+faceClient.LargeFaceList.CreateAsync(LargeFaceListId, LargeFaceListName).Wait();

+// Add Faces to the LargeFaceList.

+Parallel.ForEach(

+ Directory.GetFiles(ImageDir, "*.jpg"),

+ async imagePath =>

+ {

+ using (Stream stream = File.OpenRead(imagePath))

+ {

+ await faceClient.LargeFaceList.AddFaceFromStreamAsync(LargeFaceListId, stream);

+ }

+ });

+// Train() is newly added operation for LargeFaceList.

+// Must call it before FindSimilarAsync() to ensure the newly added faces searchable.

+await TrainLargeFaceList(LargeFaceListId);

+// Perform FindSimilar.

+const string QueryImagePath = @"/path/to/query/image";

+var results = new List<SimilarPersistedFace[]>();

+using (Stream stream = File.OpenRead(QueryImagePath))

+{

+ var faces = faceClient.Face.DetectWithStreamAsync(stream).Result;

+ foreach (var face in faces)

+ {

+ results.Add(await faceClient.Face.FindSimilarAsync(face.FaceId, largeFaceListId: LargeFaceListId));

+ }

+}

+```

+As previously shown, the data management and the FindSimilar part are almost the same. The only exception is that a fresh preprocessing Train operation must complete in the LargeFaceList before FindSimilar works.

+## Step 3: Train suggestions

+Although the Train operation speeds up [FindSimilar](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237)

+and [Identification](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), the training time suffers, especially when coming to large scale. The estimated training time in different scales is listed in the following table.

+| Scale for faces or persons | Estimated training time |

+|::|::|

+| 1,000 | 1-2 sec |

+| 10,000 | 5-10 sec |

+| 100,000 | 1-2 min |

+| 1,000,000 | 10-30 min |

+To better utilize the large-scale feature, we recommend the following strategies.

+### Step 3.1: Customize time interval

+As is shown in `TrainLargeFaceList()`, there's a time interval in milliseconds to delay the infinite training status checking process. For LargeFaceList with more faces, using a larger interval reduces the call counts and cost. Customize the time interval according to the expected capacity of the LargeFaceList.

+The same strategy also applies to LargePersonGroup. For example, when you train a LargePersonGroup with 1 million persons, `timeIntervalInMilliseconds` might be 60,000, which is a 1-minute interval.

+### Step 3.2: Small-scale buffer

+Persons or faces in a LargePersonGroup or a LargeFaceList are searchable only after being trained. In a dynamic scenario, new persons or faces are constantly added and must be immediately searchable, yet training might take longer than desired.

+To mitigate this problem, use an extra small-scale LargePersonGroup or LargeFaceList as a buffer only for the newly added entries. This buffer takes a shorter time to train because of the smaller size. The immediate search capability on this temporary buffer should work. Use this buffer in combination with training on the master LargePersonGroup or LargeFaceList by running the master training on a sparser interval. Examples are in the middle of the night and daily.

+An example workflow:

+1. Create a master LargePersonGroup or LargeFaceList, which is the master collection. Create a buffer LargePersonGroup or LargeFaceList, which is the buffer collection. The buffer collection is only for newly added persons or faces.

+1. Add new persons or faces to both the master collection and the buffer collection.

+1. Only train the buffer collection with a short time interval to ensure that the newly added entries take effect.

+1. Call Identification or FindSimilar against both the master collection and the buffer collection. Merge the results.

+1. When the buffer collection size increases to a threshold or at a system idle time, create a new buffer collection. Trigger the Train operation on the master collection.

+1. Delete the old buffer collection after the Train operation finishes on the master collection.

+### Step 3.3: Standalone training

+If a relatively long latency is acceptable, it isn't necessary to trigger the Train operation right after you add new data. Instead, the Train operation can be split from the main logic and triggered regularly. This strategy is suitable for dynamic scenarios with acceptable latency. It can be applied to static scenarios to further reduce the Train frequency.

+Suppose there's a `TrainLargePersonGroup` function similar to `TrainLargeFaceList`. A typical implementation of the standalone training on a LargePersonGroup by invoking the [`Timer`](/dotnet/api/system.timers.timer) class in `System.Timers` is:

+```csharp

+private static void Main()

+{

+ // Create a LargePersonGroup.

+ const string LargePersonGroupId = "mylargepersongroupid_001";

+ const string LargePersonGroupName = "MyLargePersonGroupDisplayName";

+ faceClient.LargePersonGroup.CreateAsync(LargePersonGroupId, LargePersonGroupName).Wait();

+ // Set up standalone training at regular intervals.

+ const int TimeIntervalForStatus = 1000 * 60; // 1-minute interval for getting training status.

+ const double TimeIntervalForTrain = 1000 * 60 * 60; // 1-hour interval for training.

+ var trainTimer = new Timer(TimeIntervalForTrain);

+ trainTimer.Elapsed += (sender, args) => TrainTimerOnElapsed(LargePersonGroupId, TimeIntervalForStatus);

+ trainTimer.AutoReset = true;

+ trainTimer.Enabled = true;

+ // Other operations like creating persons, adding faces, and identification, except for Train.

+ // ...

+}

+private static void TrainTimerOnElapsed(string largePersonGroupId, int timeIntervalInMilliseconds)

+{

+ TrainLargePersonGroup(largePersonGroupId, timeIntervalInMilliseconds).Wait();

+}

+```

+For more information about data management and identification-related implementations, see [Add faces](add-faces.md).

+## Summary

+In this guide, you learned how to migrate the existing PersonGroup or FaceList code, not data, to the LargePersonGroup or LargeFaceList:

+- LargePersonGroup and LargeFaceList work similar to PersonGroup or FaceList, except that the Train operation is required by LargeFaceList.

+- Take the proper Train strategy to dynamic data update for large-scale data sets.

+## Next steps

+Follow a how-to guide to learn how to add faces to a PersonGroup or write a script to do the Identify operation on a PersonGroup.

+- [Add faces](add-faces.md)

+- [Face client library quickstart](../quickstarts-sdk/identity-client-library.md)

+ Title: "Example: Use the PersonDirectory structure - Face"

+description: Learn how to use the PersonDirectory data structure to store face and person data at greater capacity and with other new features.

+ms.devlang: csharp

+# Use the PersonDirectory structure

+To perform face recognition operations such as Identify and Find Similar, Face API customers need to create an assorted list of **Person** objects. The new **PersonDirectory** is a data structure that contains unique IDs, optional name strings, and optional user metadata strings for each **Person** identity added to the directory.

+Currently, the Face API offers the **LargePersonGroup** structure, which has similar functionality but is limited to 1 million identities. The **PersonDirectory** structure can scale up to 75 million identities.

+Another major difference between **PersonDirectory** and previous data structures is that you'll no longer need to make any Train calls after adding faces to a **Person** object&mdash;the update process happens automatically.

+## Prerequisites

+* Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-services/).

+* Once you have your Azure subscription, [create a Face resource](https://portal.azure.com/#create/Microsoft.CognitiveServicesFace) in the Azure portal to get your key and endpoint. After it deploys, click **Go to resource**.

+ * You'll need the key and endpoint from the resource you create to connect your application to the Face API. You'll paste your key and endpoint into the code below.

+ * You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.

+## Add Persons to the PersonDirectory

+**Persons** are the base enrollment units in the **PersonDirectory**. Once you add a **Person** to the directory, you can add up to 248 face images to that **Person**, per recognition model. Then you can identify faces against them using varying scopes.

+### Create the Person

+To create a **Person**, you need to call the **CreatePerson** API and provide a name or userData property value.

+```csharp

+using Newtonsoft.Json;

+using System;

+using System.Collections.Generic;

+using System.Linq;

+using System.Net.Http;

+using System.Net.Http.Headers;

+using System.Text;

+using System.Threading.Tasks;

+var client = new HttpClient();

+// Request headers

+client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

+var addPersonUri = "https:// {endpoint}/face/v1.0-preview/persons";

+HttpResponseMessage response;

+// Request body

+var body = new Dictionary<string, object>();

+body.Add("name", "Example Person");

+body.Add("userData", "User defined data");

+byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

+using (var content = new ByteArrayContent(byteData))

+{

+ content.Headers.ContentType = new MediaTypeHeaderValue("application/json");

+ response = await client.PostAsync(addPersonUri, content);

+}

+```

+The CreatePerson call will return a generated ID for the **Person** and an operation location. The **Person** data will be processed asynchronously, so you use the operation location to fetch the results.

+### Wait for asynchronous operation completion

+You'll need to query the async operation status using the returned operation location string to check the progress.

+First, you should define a data model like the following to handle the status response.

+```csharp

+[Serializable]

+public class AsyncStatus

+{

+ [DataMember(Name = "status")]

+ public string Status { get; set; }

+ [DataMember(Name = "createdTime")]

+ public DateTime CreatedTime { get; set; }

+ [DataMember(Name = "lastActionTime")]

+ public DateTime? LastActionTime { get; set; }

+ [DataMember(Name = "finishedTime", EmitDefaultValue = false)]

+ public DateTime? FinishedTime { get; set; }

+ [DataMember(Name = "resourceLocation", EmitDefaultValue = false)]

+ public string ResourceLocation { get; set; }

+ [DataMember(Name = "message", EmitDefaultValue = false)]

+ public string Message { get; set; }

+}

+```

+Using the HttpResponseMessage from above, you can then poll the URL and wait for results.

+```csharp

+string operationLocation = response.Headers.GetValues("Operation-Location").FirstOrDefault();

+Stopwatch s = Stopwatch.StartNew();

+string status = "notstarted";

+do

+{

+ if (status == "succeeded")

+ {

+ await Task.Delay(500);

+ }

+ var operationResponseMessage = await client.GetAsync(operationLocation);

+ var asyncOperationObj = JsonConvert.DeserializeObject<AsyncStatus>(await operationResponseMessage.Content.ReadAsStringAsync());

+ status = asyncOperationObj.Status;

+} while ((status == "running" || status == "notstarted") && s.Elapsed < TimeSpan.FromSeconds(30));

+```

+Once the status returns as "succeeded", the **Person** object is considered added to the directory.

+> [!NOTE]

+> The asynchronous operation from the Create **Person** call does not have to show "succeeded" status before faces can be added to it, but it does need to be completed before the **Person** can be added to a **DynamicPersonGroup** (see below Create and update a **DynamicPersonGroup**) or compared during an Identify call. Verify calls will work immediately after faces are successfully added to the **Person**.

+### Add faces to Persons

+Once you have the **Person** ID from the Create Person call, you can add up to 248 face images to a **Person** per recognition model. Specify the recognition model (and optionally the detection model) to use in the call, as data under each recognition model will be processed separately inside the **PersonDirectory**.

+The currently supported recognition models are:

+* `Recognition_02`

+* `Recognition_03`

+* `Recognition_04`

+Additionally, if the image contains multiple faces, you'll need to specify the rectangle bounding box for the face that is the intended target. The following code adds faces to a **Person** object.

+```csharp

+var client = new HttpClient();

+// Request headers

+client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

+// Optional query strings for more fine grained face control

+var queryString = "userData={userDefinedData}&targetFace={left,top,width,height}&detectionModel={detectionModel}";

+var uri = "https://{endpoint}/face/v1.0-preview/persons/{personId}/recognitionModels/{recognitionModel}/persistedFaces?" + queryString;

+HttpResponseMessage response;

+// Request body

+var body = new Dictionary<string, object>();

+body.Add("url", "{image url}");

+byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

+using (var content = new ByteArrayContent(byteData))

+{

+ content.Headers.ContentType = new MediaTypeHeaderValue("application/json");

+ response = await client.PostAsync(uri, content);

+}

+```

+After the Add Faces call, the face data will be processed asynchronously, and you'll need to wait for the success of the operation in the same manner as before.

+When the operation for the face addition finishes, the data will be ready for in Identify calls.

+## Create and update a **DynamicPersonGroup**

+**DynamicPersonGroups** are collections of references to **Person** objects within a **PersonDirectory**; they're used to create subsets of the directory. A common use is when you want to get fewer false positives and increased accuracy in an Identify operation by limiting the scope to just the **Person** objects you expect to match. Practical use cases include directories for specific building access among a larger campus or organization. The organization directory may contain 5 million individuals, but you only need to search a specific 800 people for a particular building, so you would create a **DynamicPersonGroup** containing those specific individuals.

+If you've used a **PersonGroup** before, take note of two major differences:

+* Each **Person** inside a **DynamicPersonGroup** is a reference to the actual **Person** in the **PersonDirectory**, meaning that it's not necessary to recreate a **Person** in each group.

+* As mentioned in previous sections, there is no need to make Train calls, as the face data is processed at the Directory level automatically.

+### Create the group

+To create a **DynamicPersonGroup**, you need to provide a group ID with alphanumeric or dash characters. This ID will function as the unique identifier for all usage purposes of the group.

+There are two ways to initialize a group collection. You can create an empty group initially, and populate it later:

+```csharp

+var client = new HttpClient();

+// Request headers

+client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

+var uri = "https://{endpoint}/face/v1.0-preview/dynamicpersongroups/{dynamicPersonGroupId}";

+HttpResponseMessage response;

+// Request body

+var body = new Dictionary<string, object>();

+body.Add("name", "Example DynamicPersonGroup");

+body.Add("userData", "User defined data");

+byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

+using (var content = new ByteArrayContent(byteData))

+{

+ content.Headers.ContentType = new MediaTypeHeaderValue("application/json");

+ response = await client.PutAsync(uri, content);

+}

+```

+This process is immediate and there is no need to wait for any asynchronous operations to succeed.

+Alternatively, you can create it with a set of **Person** IDs to contain those references from the beginning by providing the set in the _AddPersonIds_ argument:

+```csharp

+var client = new HttpClient();

+// Request headers

+client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

+var uri = "https://{endpoint}/face/v1.0-preview/dynamicpersongroups/{dynamicPersonGroupId}";

+HttpResponseMessage response;

+// Request body

+var body = new Dictionary<string, object>();

+body.Add("name", "Example DynamicPersonGroup");

+body.Add("userData", "User defined data");

+body.Add("addPersonIds", new List<string>{"{guid1}", "{guid2}", …});

+byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

+using (var content = new ByteArrayContent(byteData))

+{

+ content.Headers.ContentType = new MediaTypeHeaderValue("application/json");

+ response = await client.PutAsync(uri, content);

+ // Async operation location to query the completion status from

+ var operationLocation = response.Headers.Get("Operation-Location");

+}

+```

+> [!NOTE]

+> As soon as the call returns, the created **DynamicPersonGroup** will be ready to use in an Identify call, with any **Person** references provided in the process. The completion status of the returned operation ID, on the other hand, indicates the update status of the person-to-group relationship.

+### Update the DynamicPersonGroup

+After the initial creation, you can add and remove **Person** references from the **DynamicPersonGroup** with the Update Dynamic Person Group API. To add **Person** objects to the group, list the **Person** IDs in the _addPersonsIds_ argument. To remove **Person** objects, list them in the _removePersonIds_ argument. Both adding and removing can be performed in a single call:

+```csharp

+var client = new HttpClient();

+// Request headers

+client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

+var uri = "https://{endpoint}/face/v1.0-preview/dynamicpersongroups/{dynamicPersonGroupId}";

+HttpResponseMessage response;

+// Request body

+var body = new Dictionary<string, object>();

+body.Add("name", "Example Dynamic Person Group updated");

+body.Add("userData", "User defined data updated");

+body.Add("addPersonIds", new List<string>{"{guid1}", "{guid2}", …});

+body.Add("removePersonIds", new List<string>{"{guid1}", "{guid2}", …});

+byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

+using (var content = new ByteArrayContent(byteData))

+{

+ content.Headers.ContentType = new MediaTypeHeaderValue("application/json");

+ response = await client.PatchAsync(uri, content);

+ // Async operation location to query the completion status from

+ var operationLocation = response.Headers.Get("Operation-Location");

+}

+```

+Once the call returns, the updates to the collection will be reflected when the group is queried. As with the creation API, the returned operation indicates the update status of person-to-group relationship for any **Person** that's involved in the update. You don't need to wait for the completion of the operation before making further Update calls to the group.

+## Identify faces in a PersonDirectory

+The most common way to use face data in a **PersonDirectory** is to compare the enrolled **Person** objects against a given face and identify the most likely candidate it belongs to. Multiple faces can be provided in the request, and each will receive its own set of comparison results in the response.

+In **PersonDirectory**, there are three types of scopes each face can be identified against:

+### Scenario 1: Identify against a DynamicPersonGroup

+

+Specifying the _dynamicPersonGroupId_ property in the request compares the face against every **Person** referenced in the group. Only a single **DynamicPersonGroup** can be identified against in a call.

+```csharp

+var client = new HttpClient();

+// Request headers

+client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

+// Optional query strings for more fine grained face control

+var uri = "https://{endpoint}/face/v1.0-preview/identify";

+HttpResponseMessage response;

+// Request body

+var body = new Dictionary<string, object>();

+body.Add("faceIds", new List<string>{"{guid1}", "{guid2}", …});

+body.Add("dynamicPersonGroupId", "{dynamicPersonGroupIdToIdentifyIn}");

+byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

+using (var content = new ByteArrayContent(byteData))

+{

+ content.Headers.ContentType = new MediaTypeHeaderValue("application/json");

+ response = await client.PostAsync(uri, content);

+}

+```

+### Scenario 2: Identify against a specific list of persons

+You can also specify a list of **Person** IDs in the _personIds_ property to compare the face against each of them.

+```csharp

+var client = new HttpClient();

+// Request headers

+client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

+

+var uri = "https://{endpoint}/face/v1.0-preview/identify";

+HttpResponseMessage response;

+// Request body

+var body = new Dictionary<string, object>();

+body.Add("faceIds", new List<string>{"{guid1}", "{guid2}", …});

+body.Add("personIds", new List<string>{"{guid1}", "{guid2}", …});

+byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

+using (var content = new ByteArrayContent(byteData))

+{

+ content.Headers.ContentType = new MediaTypeHeaderValue("application/json");

+ response = await client.PostAsync(uri, content);

+}

+```

+### Scenario 3: Identify against the entire **PersonDirectory**

+Providing a single asterisk in the _personIds_ property in the request compares the face against every single **Person** enrolled in the **PersonDirectory**.

+

+```csharp

+var client = new HttpClient();

+// Request headers

+client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

+

+var uri = "https://{endpoint}/face/v1.0-preview/identify";

+HttpResponseMessage response;

+// Request body

+var body = new Dictionary<string, object>();

+body.Add("faceIds", new List<string>{"{guid1}", "{guid2}", …});

+body.Add("personIds", new List<string>{"*"});

+byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

+using (var content = new ByteArrayContent(byteData))

+{

+ content.Headers.ContentType = new MediaTypeHeaderValue("application/json");

+ response = await client.PostAsync(uri, content);

+}

+```

+For all three scenarios, the identification only compares the incoming face against faces whose AddPersonFace call has returned with a "succeeded" response.

+## Verify faces against persons in the **PersonDirectory**

+With a face ID returned from a detection call, you can verify if the face belongs to a specific **Person** enrolled inside the **PersonDirectory**. Specify the **Person** using the _personId_ property.

+```csharp

+var client = new HttpClient();

+// Request headers

+client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

+var uri = "https://{endpoint}/face/v1.0-preview/verify";

+HttpResponseMessage response;

+// Request body

+var body = new Dictionary<string, object>();

+body.Add("faceId", "{guid1}");

+body.Add("personId", "{guid1}");

+var jsSerializer = new JavaScriptSerializer();

+byte[] byteData = Encoding.UTF8.GetBytes(jsSerializer.Serialize(body));

+using (var content = new ByteArrayContent(byteData))

+{

+ content.Headers.ContentType = new MediaTypeHeaderValue("application/json");

+ response = await client.PostAsync(uri, content);

+}

+```

+The response will contain a Boolean value indicating whether the service considers the new face to belong to the same **Person**, and a confidence score for the prediction.

+## Next steps

+In this guide, you learned how to use the **PersonDirectory** structure to store face and person data for your Face app. Next, learn the best practices for adding your users' face data.

+* [Best practices for adding users](../enrollment-overview.md)

+ Title: API Reference - Face

+description: API reference provides information about the Person, LargePersonGroup/PersonGroup, LargeFaceList/FaceList, and Face Algorithms APIs.

+# Face API reference list

+Azure Face is a cloud-based service that provides algorithms for face detection and recognition. The Face APIs comprise the following categories:

+- Face Algorithm APIs: Cover core functions such as [Detection](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), [Find Similar](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237), [Verification](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), [Identification](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), and [Group](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395238).

+- [FaceList APIs](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b): Used to manage a FaceList for [Find Similar](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237).

+- [LargePersonGroup Person APIs](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/599adcba3a7b9412a4d53f40): Used to manage LargePersonGroup Person Faces for [Identification](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239).

+- [LargePersonGroup APIs](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d): Used to manage a LargePersonGroup dataset for [Identification](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239).

+- [LargeFaceList APIs](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc): Used to manage a LargeFaceList for [Find Similar](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237).

+- [PersonGroup Person APIs](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c): Used to manage PersonGroup Person Faces for [Identification](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239).

+- [PersonGroup APIs](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244): Used to manage a PersonGroup dataset for [Identification](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239).

+- [Snapshot APIs](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/snapshot-take): Used to manage a Snapshot for data migration across subscriptions.

+ Title: Face service encryption of data at rest

+description: Microsoft offers Microsoft-managed encryption keys, and also lets you manage your Cognitive Services subscriptions with your own keys, called customer-managed keys (CMK). This article covers data encryption at rest for Face, and how to enable and manage CMK.

+#Customer intent: As a user of the Face service, I want to learn how encryption at rest works.

+# Face service encryption of data at rest

+The Face service automatically encrypts your data when persisted to the cloud. The Face service encryption protects your data and helps you to meet your organizational security and compliance commitments.

+> [!IMPORTANT]

+> Customer-managed keys are only available on the E0 pricing tier. To request the ability to use customer-managed keys, fill out and submit the [Face Service Customer-Managed Key Request Form](https://aka.ms/cogsvc-cmk). It will take approximately 3-5 business days to hear back on the status of your request. Depending on demand, you may be placed in a queue and approved as space becomes available. Once approved for using CMK with the Face service, you will need to create a new Face resource and select E0 as the Pricing Tier. Once your Face resource with the E0 pricing tier is created, you can use Azure Key Vault to set up your managed identity.

+## Next steps

+* For a full list of services that support CMK, see [Customer-Managed Keys for Cognitive Services](../encryption/cognitive-services-encryption-keys-portal.md)

+* [What is Azure Key Vault](../../key-vault/general/overview.md)?

+* [Cognitive Services Customer-Managed Key Request Form](https://aka.ms/cogsvc-cmk)

+* The [how-to guides](./how-to/call-analyze-image.md) contain instructions for using the service in more specific or customized ways.

+See [How to specify the `Read` model](./how-to/call-read-api.md#determine-how-to-process-the-data-optional) to use the new languages.

+|Lithuanian |`lt`| | ✅| |||||| |||

+|Latvian |`lv`| | ✅| |||||| |||

+| Portuguese-Portugal |`pt`|✅ | ✅| ✅|||||| |✅|✅|

+| Portuguese-Portugal |`pt-PT`| | ✅| |||||| |||

+|Chinese Simplified |`zh`|✅ | ✅| ✅|||||| |✅|✅|

+|Chinese Simplified |`zh-Hans`| | ✅| |||||| |||

+ Title: What is the Azure Face service?

+description: The Azure Face service provides AI algorithms that you use to detect, recognize, and analyze human faces in images.

+keywords: facial recognition, facial recognition software, facial analysis, face matching, face recognition app, face search by image, facial recognition search

+#Customer intent: As the developer of an app that deals with images of humans, I want to learn what the Face service does so I can determine if I should use its features.

+# What is the Azure Face service?

+> [!WARNING]

+> On June 11, 2020, Microsoft announced that it will not sell facial recognition technology to police departments in the United States until strong regulation, grounded in human rights, has been enacted. As such, customers may not use facial recognition features or functionality included in Azure Services, such as Face or Video Indexer, if a customer is, or is allowing use of such services by or for, a police department in the United States. When you create a new Face resource, you must acknowledge and agree in the Azure Portal that you will not use the service by or for a police department in the United States and that you have reviewed the Responsible AI documentation and will use this service in accordance with it.

+The Azure Face service provides AI algorithms that detect, recognize, and analyze human faces in images. Facial recognition software is important in many different scenarios, such as identity verification, touchless access control, and face blurring for privacy.

+This documentation contains the following types of articles:

+* The [quickstarts](./quickstarts-sdk/identity-client-library.md) are step-by-step instructions that let you make calls to the service and get results in a short period of time.

+* The [how-to guides](./how-to/identity-detect-faces.md) contain instructions for using the service in more specific or customized ways.

+* The [conceptual articles](./concept-face-detection.md) provide in-depth explanations of the service's functionality and features.

+* The [tutorials](./enrollment-overview.md) are longer guides that show you how to use this service as a component in broader business solutions.

+## Example use cases

+**Identity verification**: Verify someone's identity against a government-issued ID card like a passport or driver's license or other enrollment image. You can use this verification to grant access to digital or physical services or recover an account. Specific access scenarios include opening a new account, verifying a worker, or administering an online assessment. Identity verification can be done once when a person is onboarded, and repeated when they access a digital or physical service.

+**Touchless access control**: Compared to todayΓÇÖs methods like cards or tickets, opt-in face identification enables an enhanced access control experience while reducing the hygiene and security risks from card sharing, loss, or theft. Facial recognition assists the check-in process with a human in the loop for check-ins in airports, stadiums, theme parks, buildings, reception kiosks at offices, hospitals, gyms, clubs, or schools.

+**Face redaction**: Redact or blur detected faces of people recorded in a video to protect their privacy.

+## Face detection and analysis

+Face detection is required as a first step in all the other scenarios. The Detect API detects human faces in an image and returns the rectangle coordinates of their locations. It also returns a unique ID that represents the stored face data. This is used in later operations to identify or verify faces.

+Optionally, face detection can extract a set of face-related attributes, such as head pose, age, emotion, facial hair, and glasses. These attributes are general predictions, not actual classifications. Some attributes are useful to ensure that your application is getting high-quality face data when users add themselves to a Face service. For example, your application could advise users to take off their sunglasses if they're wearing sunglasses.

+> [!NOTE]

+> The face detection feature is also available through the [Computer Vision service](../computer-vision/overview.md). However, if you want to use other Face operations like Identify, Verify, Find Similar, or Face grouping, you should use this service instead.

+For more information on face detection and analysis, see the [Face detection](concept-face-detection.md) concepts article. Also see the [Detect API](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236) reference documentation.

+## Identity verification

+Modern enterprises and apps can use the Face identification and Face verification operations to verify that a user is who they claim to be.

+### Identification

+Face identification can address "one-to-many" matching of one face in an image to a set of faces in a secure repository. Match candidates are returned based on how closely their face data matches the query face. This scenario is used in granting building or airport access to a certain group of people or verifying the user of a device.

+The following image shows an example of a database named `"myfriends"`. Each group can contain up to 1 million different person objects. Each person object can have up to 248 faces registered.

+

+After you create and train a group, you can do identification against the group with a new detected face. If the face is identified as a person in the group, the person object is returned.

+### Verification

+The verification operation answers the question, "Do these two faces belong to the same person?".

+Verification is also a "one-to-one" matching of a face in an image to a single face from a secure repository or photo to verify that they're the same individual. Verification can be used for Identity Verification, such as a banking app that enables users to open a credit account remotely by taking a new picture of themselves and sending it with a picture of their photo ID.

+For more information about identity verification, see the [Facial recognition](concept-face-recognition.md) concepts guide or the [Identify](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239) and [Verify](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a) API reference documentation.

+## Find similar faces

+The Find Similar operation does face matching between a target face and a set of candidate faces, finding a smaller set of faces that look similar to the target face. This is useful for doing a face search by image.

+The service supports two working modes, **matchPerson** and **matchFace**. The **matchPerson** mode returns similar faces after filtering for the same person by using the [Verify API](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a). The **matchFace** mode ignores the same-person filter. It returns a list of similar candidate faces that may or may not belong to the same person.

+The following example shows the target face:

+

+And these images are the candidate faces:

+

+To find four similar faces, the **matchPerson** mode returns A and B, which show the same person as the target face. The **matchFace** mode returns A, B, C, and D, which is exactly four candidates, even if some aren't the same person as the target or have low similarity. For more information, see the [Facial recognition](concept-face-recognition.md) concepts guide or the [Find Similar API](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) reference documentation.

+## Group faces

+The Group operation divides a set of unknown faces into several smaller groups based on similarity. Each group is a disjoint proper subset of the original set of faces. It also returns a single "messyGroup" array that contains the face IDs for which no similarities were found.

+All of the faces in a returned group are likely to belong to the same person, but there can be several different groups for a single person. Those groups are differentiated by another factor, such as expression, for example. For more information, see the [Facial recognition](concept-face-recognition.md) concepts guide or the [Group API](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395238) reference documentation.

+## Data privacy and security

+As with all of the Cognitive Services resources, developers who use the Face service must be aware of Microsoft's policies on customer data. For more information, see the [Cognitive Services page](https://www.microsoft.com/trustcenter/cloudservices/cognitiveservices) on the Microsoft Trust Center.

+## Next steps

+Follow a quickstart to code the basic components of a face recognition app in the language of your choice.

+- [Client library quickstart](quickstarts-sdk/identity-client-library.md).

+* The [how-to guides](./how-to/call-analyze-image.md) contain instructions for using the service in more specific or customized ways.

+Detect faces in an image and provide information about each detected face. Computer Vision returns the coordinates, rectangle, gender, and age for each detected face.<br/>Computer Vision provides a subset of the [Face](./index-identity.yml) service functionality. You can use the Face service for more detailed analysis, such as facial identification and pose detection. [Detect faces](concept-detecting-faces.md)

+* The [how-to guides](./how-to/call-read-api.md) contain instructions for using the service in more specific or customized ways.

+<!--* The [conceptual articles](how-to/call-read-api.md) provide in-depth explanations of the service's functionality and features.

+See [How to specify the model version](./how-to/call-read-api.md#determine-how-to-process-the-data-optional) to use the preview languages and features. Refer to the full list of [OCR-supported languages](./language-support.md#optical-character-recognition-ocr).

+Learn [how to use the OCR features](./how-to/call-read-api.md).

+| [Face](overview-identity.md) | The Face service provides AI algorithms that detect, recognize, and analyze human faces in images. Facial recognition software is important in many different scenarios, such as identity verification, touchless access control, and face blurring for privacy. Follow the [Face quickstart](quickstarts-sdk/identity-client-library.md) to get started. |

+ Title: 'Quickstart: Use the Face client library'

+description: The Face API offers client libraries that makes it easy to detect, find similar, identify, verify and more.

+zone_pivot_groups: programming-languages-set-face

+ms.devlang: csharp, golang, javascript, python

+keywords: face search by image, facial recognition search, facial recognition, face recognition app

+# Quickstart: Use the Face client library

+description: Stay up to date on recent releases and updates to Azure Computer Vision.

+Learn what's new in the service. These items may be release notes, videos, blog posts, and other types of information. Bookmark this page to stay up to date with new features, enhancements, fixes, and documentation updates.

+See the [OCR how-to guide](how-to/call-read-api.md#determine-how-to-process-the-data-optional) to learn how to use the GA model.

+See the [OCR how-to guide](how-to/call-read-api.md#determine-how-to-process-the-data-optional) to learn how to use the new preview features.

+### New Quality Attribute in Detection_01 and Detection_03

+* To help system builders and their customers capture high quality images which are necessary for high quality outputs from Face API, weΓÇÖre introducing a new quality attribute **QualityForRecognition** to help decide whether an image is of sufficient quality to attempt face recognition. The value is an informal rating of low, medium, or high. The new attribute is only available when using any combinations of detection models `detection_01` or `detection_03`, and recognition models `recognition_03` or `recognition_04`. Only "high" quality images are recommended for person enrollment and quality above "medium" is recommended for identification scenarios. To learn more about the new quality attribute, see [Face detection and attributes](concept-face-detection.md) and see how to use it with [QuickStart](./quickstarts-sdk/identity-client-library.md?pivots=programming-language-csharp&tabs=visual-studio).

+See the [OCR how-to guide](how-to/call-read-api.md#determine-how-to-process-the-data-optional) to learn how to use the new preview features.

+## July 2021

+### New HeadPose and Landmarks improvements for Detection_03

+* The Detection_03 model has been updated to support facial landmarks.

+* The landmarks feature in Detection_03 is much more precise, especially in the eyeball landmarks which are crucial for gaze tracking.

+* Improved image tagging model: analyzes visual content and generates relevant tags based on objects, actions, and content displayed in the image. This model is available through the [Tag Image API](https://westus.dev.cognitive.microsoft.com/docs/services/computer-vision-v3-2/operations/56f91f2e778daf14a499f200). See the Image Analysis [how-to guide](./how-to/call-analyze-image.md) and [overview](./overview-image-analysis.md) to learn more.

+* Updated content moderation model: detects presence of adult content and provides flags to filter images containing adult, racy, and gory visual content. This model is available through the [Analyze API](https://westus.dev.cognitive.microsoft.com/docs/services/computer-vision-v3-2/operations/56f91f2e778daf14a499f21b). See the Image Analysis [how-to guide](./how-to/call-analyze-image.md) and [overview](./overview-image-analysis.md) to learn more.

+### PersonDirectory data structure

+* In order to perform face recognition operations such as Identify and Find Similar, Face API customers need to create an assorted list of **Person** objects. The new **PersonDirectory** is a data structure that contains unique IDs, optional name strings, and optional user metadata strings for each **Person** identity added to the directory. Currently, the Face API offers the **LargePersonGroup** structure which has similar functionality but is limited to 1 million identities. The **PersonDirectory** structure can scale up to 75 million identities.

+* Another major difference between **PersonDirectory** and previous data structures is that you'll no longer need to make any Train calls after adding faces to a **Person** object&mdash;the update process happens automatically. For more details see [Use the PersonDirectory structure](how-to/use-persondirectory.md).

+See the [Read API how-to guide](how-to/call-read-api.md) to learn more.

+### New Face API detection model

+* The new Detection 03 model is the most accurate detection model currently available. If you're a new a customer, we recommend using this model. Detection 03 improves both recall and precision on smaller faces found within images (64x64 pixels). Additional improvements include an overall reduction in false positives and improved detection on rotated face orientations. Combining Detection 03 with the new Recognition 04 model will provide improved recognition accuracy as well. See [Specify a face detection model](./how-to/specify-detection-model.md) for more details.

+### New detectable Face attributes

+* The `faceMask` attribute is available with the latest Detection 03 model, along with the additional attribute `"noseAndMouthCovered"` which detects whether the face mask is worn as intended, covering both the nose and mouth. To use the latest mask detection capability, users need to specify the detection model in the API request: assign the model version with the _detectionModel_ parameter to `detection_03`. See [Specify a face detection model](./how-to/specify-detection-model.md) for more details.

+### New Face API Recognition Model

+* The new Recognition 04 model is the most accurate recognition model currently available. If you're a new customer, we recommend using this model for verification and identification. It improves upon the accuracy of Recognition 03, including improved recognition for users wearing face covers (surgical masks, N95 masks, cloth masks). Note that we recommend against enrolling images of users wearing face covers as this will lower recognition quality. Now customers can build safe and seamless user experiences that detect whether a user is wearing a face cover with the latest Detection 03 model, and recognize them with the latest Recognition 04 model. See [Specify a face recognition model](./how-to/specify-recognition-model.md) for more details.

+### Mitigate latency

+* The Face team published a new article detailing potential causes of latency when using the service and possible mitigation strategies. See [Mitigate latency when using the Face service](./how-to/mitigate-latency.md).

+## December 2020

+### Customer configuration for Face ID storage

+* While the Face Service does not store customer images, the extracted face feature(s) will be stored on server. The Face ID is an identifier of the face feature and will be used in [Face - Identify](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - Verify](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face - Find Similar](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). The stored face features will expire and be deleted 24 hours after the original detection call. Customers can now determine the length of time these Face IDs are cached. The maximum value is still up to 24 hours, but a minimum value of 60 seconds can now be set. The new time ranges for Face IDs being cached is any value between 60 seconds and 24 hours. More details can be found in the [Face - Detect](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236) API reference (the *faceIdTimeToLive* parameter).

+## November 2020

+### Sample Face enrollment app

+* The team published a sample Face enrollment app to demonstrate best practices for establishing meaningful consent and creating high-accuracy face recognition systems through high-quality enrollments. The open-source sample can be found in the [Build an enrollment app](Tutorials/build-enrollment-app.md) guide and on [GitHub](https://github.com/Azure-Samples/cognitive-services-FaceAPIEnrollmentSample), ready for developers to deploy or customize.

+See the [Read API how-to guide](how-to/call-read-api.md) to learn more.

+## August 2020

+### Customer-managed encryption of data at rest

+* The Face service automatically encrypts your data when persisting it to the cloud. The Face service encryption protects your data to help you meet your organizational security and compliance commitments. By default, your subscription uses Microsoft-managed encryption keys. There is also a new option to manage your subscription with your own keys called customer-managed keys (CMK). More details can be found at [Customer-managed keys](./identity-encrypt-data-at-rest.md).

+See the [Read API how-to guide](how-to/call-read-api.md) to learn more.

+## April 2020

+### New Face API Recognition Model

+* The new recognition 03 model is the most accurate model currently available. If you're a new customer, we recommend using this model. Recognition 03 will provide improved accuracy for both similarity comparisons and person-matching comparisons. More details can be found at [Specify a face recognition model](./how-to/specify-recognition-model.md).

+## June 2019

+### New Face API detection model

+* The new Detection 02 model features improved accuracy on small, side-view, occluded, and blurry faces. Use it through [Face - Detect](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), [FaceList - Add Face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250), [LargeFaceList - Add Face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3), [PersonGroup Person - Add Face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523b) and [LargePersonGroup Person - Add Face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/599adf2a3a7b9412a4d53f42) by specifying the new face detection model name `detection_02` in `detectionModel` parameter. More details in [How to specify a detection model](how-to/specify-detection-model.md).

+## April 2019

+### Improved attribute accuracy

+* Improved overall accuracy of the `age` and `headPose` attributes. The `headPose` attribute is also updated with the `pitch` value enabled now. Use these attributes by specifying them in the `returnFaceAttributes` parameter of [Face - Detect](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236) `returnFaceAttributes` parameter.

+### Improved processing speeds

+* Improved speeds of [Face - Detect](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), [FaceList - Add Face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250), [LargeFaceList - Add Face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3), [PersonGroup Person - Add Face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523b) and [LargePersonGroup Person - Add Face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/599adf2a3a7b9412a4d53f42) operations.

+## March 2019

+### New Face API recognition model

+* The Recognition 02 model has improved accuracy. Use it through [Face - Detect](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), [FaceList - Create](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b), [LargeFaceList - Create](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc), [PersonGroup - Create](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) and [LargePersonGroup - Create](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) by specifying the new face recognition model name `recognition_02` in `recognitionModel` parameter. More details in [How to specify a recognition model](how-to/specify-recognition-model.md).

+## January 2019

+### Face Snapshot feature

+* This feature allows the service to support data migration across subscriptions: [Snapshot](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/snapshot-get). More details in [How to Migrate your face data to a different Face subscription](how-to/migrate-face-data.md).

+## October 2018

+### API messages

+* Refined description for `status`, `createdDateTime`, `lastActionDateTime`, and `lastSuccessfulTrainingDateTime` in [PersonGroup - Get Training Status](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395247), [LargePersonGroup - Get Training Status](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/599ae32c6ac60f11b48b5aa5), and [LargeFaceList - Get Training Status](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/5a1582f8d2de3616c086f2cf).

+## May 2018

+### Improved attribute accuracy

+* Improved `gender` attribute significantly and also improved `age`, `glasses`, `facialHair`, `hair`, `makeup` attributes. Use them through [Face - Detect](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236) `returnFaceAttributes` parameter.

+### Increased file size limit

+* Increased input image file size limit from 4 MB to 6 MB in [Face - Detect](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), [FaceList - Add Face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250), [LargeFaceList - Add Face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3), [PersonGroup Person - Add Face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523b) and [LargePersonGroup Person - Add Face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/599adf2a3a7b9412a4d53f42).

+## March 2018

+### New data structure

+* [LargeFaceList](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) and [LargePersonGroup](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). More details in [How to use the large-scale feature](how-to/use-large-scale.md).

+* Increased [Face - Identify](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239) `maxNumOfCandidatesReturned` parameter from [1, 5] to [1, 100] and default to 10.

+## May 2017

+### New detectable Face attributes

+* Added `hair`, `makeup`, `accessory`, `occlusion`, `blur`, `exposure`, and `noise` attributes in [Face - Detect](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236) `returnFaceAttributes` parameter.

+* Supported 10K persons in a PersonGroup and [Face - Identify](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239).

+* Supported pagination in [PersonGroup Person - List](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241) with optional parameters: `start` and `top`.

+* Supported concurrency in adding/deleting faces against different FaceLists and different persons in PersonGroup.

+## March 2017

+### New detectable Face attribute

+* Added `emotion` attribute in [Face - Detect](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236) `returnFaceAttributes` parameter.

+### Fixed issues

+* Face could not be re-detected with rectangle returned from [Face - Detect](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236) as `targetFace` in [FaceList - Add Face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) and [PersonGroup Person - Add Face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523b).

+* The detectable face size is set to ensure it is strictly between 36x36 to 4096x4096 pixels.

+## November 2016

+### New subscription tier

+* Added Face Storage Standard subscription to store additional persisted faces when using [PersonGroup Person - Add Face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523b) or [FaceList - Add Face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) for identification or similarity matching. The stored images are charged at $0.5 per 1000 faces and this rate is prorated on a daily basis. Free tier subscriptions continue to be limited to 1,000 total persons.

+## October 2016

+### API messages

+* Changed the error message of more than one face in the `targetFace` from 'There are more than one face in the image' to 'There is more than one face in the image' in [FaceList - Add Face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) and [PersonGroup Person - Add Face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523b).

+## July 2016

+### New features

+* Supported Face to Person object authentication in [Face - Verify](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a).

+* Added optional `mode` parameter enabling selection of two working modes: `matchPerson` and `matchFace` in [Face - Find Similar](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) and default is `matchPerson`.

+* Added optional `confidenceThreshold` parameter for user to set the threshold of whether one face belongs to a Person object in [Face - Identify](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239).

+* Added optional `start` and `top` parameters in [PersonGroup - List](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395248) to enable user to specify the start point and the total PersonGroups number to list.

+## V1.0 changes from V0

+* Updated service root endpoint from ```https://westus.api.cognitive.microsoft.com/face/v0/``` to ```https://westus.api.cognitive.microsoft.com/face/v1.0/```. Changes applied to:

+ [Face - Detect](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), [Face - Identify](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - Find Similar](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) and [Face - Group](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395238).

+* Updated the minimal detectable face size to 36x36 pixels. Faces smaller than 36x36 pixels will not be detected.

+* Deprecated the PersonGroup and Person data in Face V0. Those data cannot be accessed with the Face V1.0 service.

+* Deprecated the V0 endpoint of Face API on June 30, 2016.

+Data with these errors won't be used for training. Imported data with errors will be ignored, so you don't need to delete them. You can resubmit the corrected data for training.

+1. On the **Train model** tab, select **Train a new model** to create a voice model with the data you've uploaded.

+1. Select the neural training method for your model and target language.

+ By default, your voice model is trained in the same language of your training data. You can also select to create a secondary language for your voice model. For more information, see [language support for Custom Neural Voice](language-support.md#custom-neural-voice). Also see information about [pricing](https://azure.microsoft.com/pricing/details/cognitive-services/speech-services/) for neural training.

+1. Choose your test script. Each training generates 100 sample audio files automatically, to help you test the model with a default script. You can also provide your own test script, including up to 100 utterances. The test script must exclude the filenames (the ID of each utterance). Otherwise, these IDs are spoken. Here's an example of how the utterances are organized in one .txt file:

+ The **Train model** table displays a new entry that corresponds to this newly created model.

+ When the model is training, you can select **Cancel training** to cancel your voice model. You're not charged for this canceled training.

+ :::image type="content" source="media/custom-voice/cnv-cancel-training.png" alt-text="Screenshot that shows how to cancel training for a model.":::

+ The table displays the status: processing, succeeded, failed, and canceled. The status reflects the process of converting your data to a voice model, as shown in this table:

+ | Canceled | The training for your voice model was canceled. |

+ > Standard subscription (S0) users can train four voices simultaneously. If you reach the limit, wait until at least one of your voice models finishes training, and then try again.

+### Rename your model

+If you want to rename the model you built, you can select **Clone model** to create a clone of the model with a new name in the current project.

+Enter the new name on the **Clone voice model** window, then click **Submit**. The text 'Neural' will be automatically added as a suffix to your new model name.

+### Test your voice model

+After you've trained your voice model, you can test the model on the model details page. Select **DefaultTests** under **Testing** to listen to the sample audios. The default test samples include 100 sample audios generated automatically during training to help you test the model. In addition to these 100 audios provided by default, your own test script (at most 100 utterances) provided during training are also added to **DefaultTests** set. You're not charged for the testing with **DefaultTests**.

+If you want to upload your own test scripts to further test your model, select **Add test scripts** to upload your own test script.

+Before uploading test script, check the [test script requirements](#train-your-custom-neural-voice-model). You'll be charged for the additional testing with the batch synthesis based on the number of billable characters. See [pricing page](https://azure.microsoft.com/pricing/details/cognitive-services/speech-services/).

+On **Add test scripts** window, click **Browse for a file** to select your own script, then select **Add** to upload it.

+> Custom Neural Voice training is only available in some regions. But you can easily copy a neural voice model from these regions to other regions. For more information, see the [regions for Custom Neural Voice](regions.md#text-to-speech).

+|[Face](../computer-vision/index-identity.yml "Face")| The Face service provides access to advanced face algorithms, enabling face attribute detection and recognition. |

+ Title: Project best practices

+description: Best practices for Question Answering

+recommendations: false

+# Project best practices

+The following list of QnA pairs will be used to represent a project (knowledge base) to highlight best practices when authoring in custom question answering.

+|Question |Answer |

+|-|-|

+|I want to buy a car. |There are three options for buying a car. |

+|I want to purchase software license. |Software licenses can be purchased online at no cost. |

+|How to get access to WPA? |WPA can be accessed via the company portal. |

+|What is the price of Microsoft stock?|$200. |

+|How do I buy Microsoft Services? |Microsoft services can be bought online. |

+|I want to sell car. |Please send car pictures and documents. |

+|How do I get an identification card? |Apply via company portal to get an identification card.|

+|How do I use WPA? |WPA is easy to use with the provided manual. |

+|What is the utility of WPA? |WPA provides a secure way to access company resources. |

+## When should you add alternate questions to a QnA?

+- Question answering employs a transformer-based ranker that takes care of user queries that are semantically similar to questions in the knowledge base. For example, consider the following question answer pair:

+ **Question: ΓÇ£What is the price of Microsoft Stock?ΓÇ¥**

+ **Answer: ΓÇ£$200ΓÇ¥.**

+ The service can return expected responses for semantically similar queries such as:

+ "How much is Microsoft stock worth?"

+ "How much is Microsoft's share value?"

+ "How much does a Microsoft share cost?"

+ "What is the market value of Microsoft stock?"

+ "What is the market value of a Microsoft share?"

+ However, please note that the confidence score with which the system returns the correct response will vary based on the input query and how different it is from the original question answer pair.

+- There are certain scenarios which require the customer to add an alternate question. When a query does not return the correct answer despite it being present in the knowledge base, we advise adding that query as an alternate question to the intended QnA pair.

+## How many alternate questions per QnA is optimal?

+- Users can add up to 10 alternate questions depending on their scenario. Alternate questions beyond the first 10 arenΓÇÖt considered by our core ranker. However, they are evaluated in the other processing layers resulting in better output overall. All the alternate questions will be considered in the preprocessing step to look for an exact match.

+- Semantic understanding in question answering should be able to take care of similar alternate questions.

+- The return on investment will start diminishing once you exceed 10 questions. Even if youΓÇÖre adding more than 10 alternate questions, try to make the initial 10 questions as semantically dissimilar as possible so that all intents for the answer are captured by these 10 questions. For the knowledge base above, in QNA #1, adding alternate questions such as "How can I buy a car?", "I wanna buy a car." are not required. Whereas adding alternate questions such as "How to purchase a car.", "What are the options for buying a vehicle?" can be useful.

+## When to add synonyms to a knowledge base

+- Question answering provides the flexibility to use synonyms at the knowledge base level, unlike QnA Maker where synonyms are shared across knowledge bases for the entire service.

+- For better relevance, the customer needs to provide a list of acronyms that the end user intends to use interchangeably. For instance, the following is a list of acceptable acronyms:

+ MSFT ΓÇô Microsoft

+ ID ΓÇô Identification

+ ETA ΓÇô Estimated time of Arrival

+- Apart from acronyms, if you think your words are similar in context of a particular domain and generic language models wonΓÇÖt consider them similar, itΓÇÖs better to add them as synonyms. For instance, if an auto company producing a car model X receives queries such as "my carΓÇÖs audio isnΓÇÖt working" and the knowledge base has questions on "fixing audio for car X", then we need to add "X" and "car" as synonyms.

+- The Transformer based model already takes care of most of the common synonym cases, for e.g.- Purchase ΓÇô Buy, Sell - Auction, Price ΓÇô Value. For example, consider the following QnA pair: Q: "What is the price of Microsoft Stock?" A: "$200".

+If we receive user queries like "Microsoft stock value", "Microsoft share value", "Microsoft stock worth", "Microsoft share worth", "stock value", etc., they should be able to get correct answer even though these queries have words like share, value, worth which are not originally present in the knowledge base.

+## How are lowercase/uppercase characters treated?

+Question answering takes casing into account but it's intelligent enough to understand when it is to be ignored. You should not be seeing any perceivable difference due to wrong casing.

+## How are QnAs prioritized for multi-turn questions?

+When a KB has hierarchical relationships (either added manually or via extraction) and the previous response was an answer related to other QnAs, for the next query we give slight preference to all the children QnAs, sibling QnAs and grandchildren QnAs in that order. Along with any query, the [Question Answering API] (/rest/api/cognitiveservices/questionanswering/question-answering/get-answers) expects a "context" object with the property "previousQnAId" which denotes the last top answer. Based on this previous QnA ID, all the related QnAs are boosted.

+## How are accents treated?

+Accents are supported for all major European languages. If the query has an incorrect accent, confidence score might be slightly different, but the service still returns the relevant answer and takes care of minor errors by leveraging fuzzy search.

+## How is punctuation in a user query treated?

+Punctuation is ignored in user query before sending it to the ranking stack. Ideally it should not impact the relevance scores. Punctuations that are ignored are as follows: ,?:;\"'(){}[]-+。./!*؟

+## Next steps

+> [!div class="nextstepaction"]

+> [Get started with Question Answering](../quickstart/sdk.md)

+* [Face](./computer-vision/index-identity.yml)

+|[Face](./computer-vision/index-identity.yml "Face")| The Face service provides access to advanced face algorithms, enabling face attribute detection and recognition.| [Face quickstart](./face/quickstarts/client-libraries.md)|

+The **Network Diagnostics Tool** enables Azure Communication Services developers to ensure that their device and network conditions are optimal for connecting to the service to ensure a great call experience. The tool can be found at [aka.ms/acsdiagnostics](https://azurecommdiagnostics.net/). Users can quickly run a test, by pressing the start test button. The tool performs diagnostics on the network, devices, and call quality. The results of the diagnostics are directly provided through the tools UI. No sign-in required to use the tool. After the test, a GUID is presented which can be provided to our support team for further help.

+## Support

+The test provides a **unique identifier** for your test which you can provide our support team who can provide further help. For more information see [help and support options](../../support.md)

+Azure Communication Services is transforming the way our customers engage with their clients by building rich, custom communication experiences that take advantage of the same enterprise-grade services that back Microsoft Teams, Skype, and Exchange. You can easily integrate SMS and email messaging functionality into your communications solutions to reach your customers anytime and anywhere they need support. You just need to keep in mind a few messaging requirements and industry standards to get started.

+Consent is an agreement between you and the message recipient that allows you to send application to person (A2P) messages to them. You must obtain consent before sending the first message, and you should make clear to the recipient that they're agreeing to receive messages from you. This procedure is known as receiving "prior express consent" from the individual you intend to message.

+The messages that you send must be the same type of messages that the recipient agreed to receive and should only be sent to the number or email address that the recipient provided to you. If you intend to send informational messages, such as appointment reminders or alerts, then consent can be either written or oral. If you intend to send promotional messages, such as sales or marketing messages that promote a product or service, then consent must be written.

+- When a user enters their telephone number or email address into a website,

+- Consent is limited in purpose. An individual who provides their number or an email address for a particular purpose consents to receive communications only for that specific purpose and from that specific message sender. Before obtaining consent, you should clearly notify the intended message recipient if you'll send recurring messages or messages from an affiliate.

+ - The number(s) or email address(es) from which recipients will receive messages, and

+One of the most common opt-out mechanisms in SMS applications is to include a ΓÇ£STOPΓÇ¥ keyword in the initial message of every new conversation. Be prepared to remove customers that reply with a lowercase ΓÇ£stopΓÇ¥ or other common keywords, such as ΓÇ£unsubscribeΓÇ¥ or ΓÇ£cancel.ΓÇ¥

+For email, it is to embed a link to unsubscribe in every email sent to the customer. If the customer selects the unsubscribe link, you should be prepared to remove that customer email address(es) from your communication list.

+After an individual revokes consent, you should remove them from all recurring messaging campaigns unless they expressly elect to continue receiving messages from a particular program.

+In addition to keywords, other common opt-out mechanisms include providing customers with a designated opt-out e-mail address, the phone number of customer support staff, or a link to unsubscribe embedded in an email message you sent or available on your webpage.

+### How we handle opt-out requests for SMS

+### How we handle opt-out requests for email

+If an individual requests to opt out of future messages on Azure Communication Services using the unsubscribe UI page to process the unsubscribe requests, you will have to add the requested recipient's email address to the suppression list that will be used to filter recipients during the send-mail process.

+Spoofing is the act of causing a misleading or inaccurate originating number or email address to display on a message recipientΓÇÖs device. We strongly discourage you and any service provider that you use from sending spoofed messages. Spoofing shields the identity of the message sender and prevents message recipients from easily opting out of unwanted communications. We also require that you abide by all applicable spoofing laws.

+The media traffic flows to and from a separate service in the Microsoft Cloud called Media Processor. The IP address range for media traffic:

+- `20.202.0.0/16 (IP addresses from 20.202.0.1 to 20.202.255.254)`

+### Port ranges

+The port ranges of the Media Processors are shown in the following table:

+Media Processors are placed in the same datacenters as SIP proxies:

+| **Standard** | Single-tenant Azure Logic Apps and App Service Environment v3 (Windows plans only) | [Managed connector - Standard class](managed.md) and [built-in connector](built-in.md), which is [service provider based](../logic-apps/custom-connector-overview.md#service-provider-interface-implementation). For managed connector operations, limits, and other information, review the [SQL Server managed connector reference](/connectors/sql/). <br><br>The built-in connector differs in the following ways: <br><br>- The built-in version has no triggers. <br><br>- The built-in version has a single **Execute Query** action. This action can directly access Azure virtual networks with a connection string and doesn't need the on-premises data gateway. <br><br>For built-in connector operations, limits, and other information, review the [SQL Server built-in connector reference](#built-in-connector-operations). |

+## Limitations

+For more information, review the [SQL Server managed connector reference](/connectors/sql/) or the [SQL Server built-in connector reference](#built-in-connector-operations).

+For other connector requirements, review [SQL Server managed connector reference](/connectors/sql/).

+<a name="built-in-connector-operations"></a>

+## Built-in connector operations

+### Actions

+The SQL Server built-in connector has a single action.

+#### Execute Query

+Operation ID: `executeQuery`

+Runs a query against a SQL database.

+##### Parameters

+| Name | Key | Required | Type | Description |

+||--|-||-|

+| **Query** | `query` | True | Dynamic | The body for your query |

+| **Query Parameters** | `queryParameters` | False | Objects | The parameters for your query |

+||||||

+##### Returns

+The outputs from this operation are dynamic.

+## Built-in connector app settings

+The SQL Server built-in connector includes app settings on your Standard logic app resource that control various thresholds for performance, throughput, capacity, and so on. For example, you can change the default timeout value for connector operations. For more information, review [Reference for app settings - local.settings.json](../logic-apps/edit-app-settings-host-settings.md#reference-local-settings-json).

+- Ingress must be enabled for the container app

+> [!IMPORTANT]

+> If you are using a new certificate, you must have an existing [SNI domain certificate](https://wikipedia.org/wiki/Server_Name_Indication) file available to upload to Azure.

+1. Verify that your app has ingress enabled by selecting **Ingress** in the *Settings* section. If ingress is not enabled, enable it with these steps:

+ 1. Set *HTTP Ingress* to **Enabled**.

+ 1. Select the desired *Ingress traffic* setting.

+ 1. Enter the *Target port*.

+ 1. Select **Save**.

+The Distributed Application Runtime ([Dapr][dapr-concepts]) is a set of incrementally adoptable APIs that simplify the authoring of distributed, microservice-based applications. For example, Dapr provides capabilities for enabling application intercommunication, whether through messaging via pub/sub or reliable and secure service-to-service calls. Once Dapr is enabled in Container Apps, it exposes its HTTP and gRPC APIs via a sidecar: a process that runs in tandem with each of your Container Apps.

+| 3 | Dapr component | Dapr components can be shared by multiple container apps. The Dapr sidecar uses scopes to determine which components to load for a given container app at runtime. |

+You can define the Dapr configuration for a container app through the Azure CLI or using Infrastructure as Code templates like a bicep or an Azure Resource Manager (ARM) template. You can enable Dapr in your app with the following settings:

+| CLI Parameter | Template field | Description |

+| -- | -- | -- |

+| `--enable-dapr` | `dapr.enabled` | Enables Dapr on the container app. |

+| `--dapr-app-port` | `dapr.appPort` | Identifies which port your application is listening. |

+| `--dapr-app-protocol` | `dapr.appProtocol` | Tells Dapr which protocol your application is using. Valid options are `http` or `grpc`. Default is `http`. |

+| `--dapr-app-id` | `dapr.appId` | The unique ID of the application. Used for service discovery, state encapsulation, and the pub/sub consumer ID. |

+The following example shows how to define a Dapr configuration in a template by adding the Dapr configuration to the `properties.configuration` section of your container apps resource declaration.

+# [Bicep](#tab/bicep1)

+```bicep

+ dapr: {

+ enabled: true

+ appId: 'nodeapp'

+ appProtocol: 'http'

+ appPort: 3000

+ }

+```

+# [ARM](#tab/arm1)

+```json

+ "dapr": {

+ "enabled": true,

+ "appId": "nodeapp",

+ "appProcotol": "http",

+ "appPort": 3000

+ }

+

+```

+Since Dapr settings are considered application-scope changes, new revisions aren't created when you change Dapr setting. However, when changing Dapr settings, the container app revisions and replicas are automatically restarted.

+Based on your needs, you can "plug in" certain Dapr component types like state stores, pub/sub brokers, and more. In the examples below, you'll find the various schemas available for defining a Dapr component in Azure Container Apps. The Container Apps manifests differ sightly from the Dapr OSS manifests in order to simplify the component creation experience.

+When defining a Dapr component via YAML, you'll pass your component manifest into the Azure CLI. When configuring multiple components, you'll need to create a separate YAML file and run the Azure CLI command for each component.

+The `pubsub.yaml` spec will be scoped to the dapr-enabled container apps with app IDs `publisher-app` and `subscriber-app`.

+The `dapr-pubsub` component is scoped to the Dapr-enabled container apps with app IDs `publisher-app` and `subscriber-app`:

+This resource defines a Dapr component called `dapr-pubsub` via ARM. The `dapr-pubsub` component will be scoped to the Dapr-enabled container apps with app IDs `publisher-app` and `subscriber-app`:

+Create an ARM template to deploy a Container Apps environment that includes:

+* the Application Insights resource for distributed tracing

+* the two dapr-enabled container apps

+ "external": false,

+ "env": [

+ {

+ "name": "APP_PORT",

+ "value": "3000"

+ }

+ ],

+Create a bicep template to deploy a Container Apps environment that includes:

+* the Application Insights resource for distributed tracing

+ external: false

+ env: [

+ {

+ name: 'APP_PORT'

+ value: '3000'

+ }

+ ]

+Your state store is configured using the Dapr component described in *statestore.yaml*. The component is scoped to a container app named `nodeapp` and isn't available to other container apps.

+ --ingress 'internal' \

+ --dapr-app-id nodeapp \

+ --env-vars 'APP_PORT=3000'

+ --ingress 'internal' `

+ --dapr-app-id nodeapp `

+ --env-vars 'APP_PORT=3000'

+* its accompanying Dapr sidecar configured with `--dapr-app-id nodeapp` and `--dapr-app-port 3000'` for service discovery and invocation

+This command deploys `pythonapp` that also runs with a Dapr sidecar that is used to look up and securely call the Dapr sidecar for `nodeapp`. As this app is headless there's no `--target-port` to start a server, nor is there a need to enable ingress.

+Data logged via a container app are stored in the `ContainerAppConsoleLogs_CL` custom table in the Log Analytics workspace. You can view logs through the Azure portal or with the CLI. Wait a few minutes for the analytics to arrive for the first time before you're able to query the logged data.

+Once you're done, run the following command to delete your resource group along with all the resources you created in this tutorial.

+description: Manage revisions and traffic splitting in Azure Container Apps.

+# Manage revisions in Azure Container Apps

+Supporting multiple revisions in Azure Container Apps allows you to manage the versioning of your container app. With this feature, you can activate and deactivate revisions, and control the amount of [traffic sent to each revision](#traffic-splitting). To learn more about revisions, see [Revisions in Azure Container Apps](revisions.md)

+A revision is created when you first deploy your application. New revisions are created when you [update](#updating-your-container-app) your application with [revision-scope changes](revisions.md#revision-scope-changes). You can also update your container app based on a specific revision.

+This article described the commands to manage your container app's revisions. For more information about Container Apps commands, see [`az containerapp`](/cli/azure/containerapp). For more information about commands to manage revisions, see [`az containerapp revision`](/cli/azure/containerapp/revision).

+## Updating your container app

+To update a container app, use the `az containerapp update` command. With this command you can modify environment variables, compute resources, scale parameters, and deploy a different image. If your container app update includes [revision-scope changes](revisions.md#revision-scope-changes), a new revision will be generated.

+You may also use a YAML file to define these and other configuration options and parameters. For more information regarding this command, see [`az containerapp revision copy`](/cli/azure/containerapp#az-containerapp-update).

+This example updates the container image. (Replace the \<placeholders\> with your values.)

+# [Bash](#tab/bash)

+```azurecli

+az containerapp update \

+ --name <APPLICATION_NAME> \

+ --resource-group <RESOURCE_GROUP_NAME> \

+ --image <IMAGE_NAME>

+```

+# [PowerShell](#tab/powershell)

+```azurecli

+az containerapp update `

+ --name <APPLICATION_NAME> `

+ --resource-group <RESOURCE_GROUP_NAME> `

+ --image <IMAGE_NAME>

+```

+You can also update your container app with the [Revision copy](#revision-copy) command.

+## Revision list

+List all revisions associated with your container app with `az containerapp revision list`. For more information about this command, see [`az containerapp revision list`](/cli/azure/containerapp/revision#az-containerapp-revision-list)

+## Revision show

+Show details about a specific revision by using `az containerapp revision show`. For more information about this command, see [`az containerapp revision show`](/cli/azure/containerapp/revision#az-containerapp-revision-show).

+Example: (Replace the \<placeholders\> with your values.)

+## Revision copy

+To create a new revision based on an existing revision, use the `az containerapp revision copy`. Container Apps will use the configuration of the existing revision, which you then may modify.

+With this command, you can modify environment variables, compute resources, scale parameters, and deploy a different image. You may also use a YAML file to define these and other configuration options and parameters. For more information regarding this command, see [`az containerapp revision copy`](/cli/azure/containerapp/revision#az-containerapp-revision-copy).

+This example copies the latest revision and sets the compute resource parameters. (Replace the \<placeholders\> with your values.)

+az containerapp revision copy \

+ --cpu 0.75 \

+ --memory 1.5Gi

+az containerapp revision copy `

+ --cpu 0.75 `

+ --memory 1.5Gi

+## Revision activate

+Activate a revision by using `az containerapp revision activate`. For more information about this command, see [`az containerapp revision activate`](/cli/azure/containerapp/revision#az-containerapp-revision-activate).

+Example: (Replace the \<placeholders\> with your values.)

+## Revision deactivate

+Deactivate revisions that are no longer in use with `az containerapp revision deactivate`. Deactivation stops all running replicas of a revision. For more information, see [`az containerapp revision deactivate`](/cli/azure/containerapp/revision#az-containerapp-revision-deactivate).

+Example: (Replace the \<placeholders\> with your values.)

+## Revision restart

+This command restarts a revision. For more information about this command, see [`az containerapp revision restart`](/cli/azure/containerapp/revision#az-containerapp-revision-restart).

+When you modify secrets in your container app, you'll need to restart the active revisions so they can access the secrets.

+Example: (Replace the \<placeholders\> with your values.)

+## Revision set mode

+The revision mode controls whether only a single revision or multiple revisions of your container app can be simultaneously active. To set your container app to support [single revision mode](revisions.md#single-revision-mode) or [multiple revision mode](revisions.md#multiple-revision-mode), use the `az containerapp revision set-mode` command.

+The default setting is *single revision mode*. For more information about this command, see [`az containerapp revision set-mode`](/cli/azure/containerapp/revision#az-containerapp-revision-set-mode).

+The mode values are `single` or `multiple`. Changing the revision mode doesn't create a new revision.

+Example: (Replace the \<placeholders\> with your values.)

+# [Bash](#tab/bash)

+```azurecli

+az containerapp revision set-mode \

+ --name <APPLICATION_NAME> \

+ --resource-group <RESOURCE_GROUP_NAME> \

+ --mode single

+```

+# [PowerShell](#tab/powershell)

+```azurecli

+az containerapp revision set-mode `

+ --name <APPLICATION_NAME> `

+ --resource-group <RESOURCE_GROUP_NAME> `

+ --mode single

+```

+## Revision labels

+Labels provide a unique URL that you can use to direct traffic to a revision. You can move a label between revisions to reroute traffic directed to the label's URL to a different revision. For more information about revision labels, see [Revision Labels](revisions.md#revision-labels).

+You can add and remove a label from a revision. For more information about the label commands, see [`az containerapp revision label`](/cli/azure/containerapp/revision/label)

+### Revision label add

+To add a label to a revision, use the [`az containerapp revision label add`](/cli/azure/containerapp/revision/label#az-containerapp-revision-label-add) command.

+You can only assign a label to one revision at a time, and a revision can only be assigned one label. If the revision you specify has a label, the add command will replace the existing label.

+This example adds a label to a revision: (Replace the \<placeholders\> with your values.)

+# [Bash](#tab/bash)

+```azurecli

+az containerapp revision label add \

+ --revision <REVISION_NAME> \

+ --resource-group <RESOURCE_GROUP_NAME> \

+ --label <LABEL_NAME>

+```

+# [PowerShell](#tab/powershell)

+```azurecli

+az containerapp revision set-mode `

+ --revision <REVISION_NAME> `

+ --resource-group <RESOURCE_GROUP_NAME> `

+ --mode <LABEL_NAME>

+### Revision label remove

+To remove a label from a revision, use the [`az containerapp revision label remove`](/cli/azure/containerapp/revision/label#az-containerapp-revision-label-remove) command.

+This example removes a label to a revision: (Replace the \<placeholders\> with your values.)

+# [Bash](#tab/bash)

+```azurecli

+az containerapp revision label add \

+ --revision <REVISION_NAME> \

+ --resource-group <RESOURCE_GROUP_NAME> \

+ --label <LABEL_NAME>

+```

+# [PowerShell](#tab/powershell)

+```azurecli

+az containerapp revision set-mode `

+ --revision <REVISION_NAME> `

+ --resource-group <RESOURCE_GROUP_NAME> `

+ --mode <LABEL_NAME>

+```

+The following example shows how to split traffic between three revisions.

+The sum of all revision weights must equal 100.

+In this example, replace the `<REVISION*_NAME>` placeholders with revision names in your container app. You access revision names via the [revision list](#revision-list) command.

+* [Revisions in Azure Container Apps](revisions.md)

+* [Application lifecycle management in Azure Container Apps](application-lifecycle-management.md)

+If you have an Enterprise Agreement, you can [Create and edit budgets with PowerShell](tutorial-acm-create-budgets.md#create-and-edit-budgets-with-powershell). Customers with a Microsoft Customer Agreement should use the [Budgets REST API](/rest/api/consumption/budgets/create-or-update) to create budgets programmatically.

+> Customers with a Microsoft Customer Agreement should use the [Budgets REST API](/rest/api/consumption/budgets/create-or-update) to create budgets programmatically.

+> The Azure Marketplace price list feature in the EA portal is retired.

+If you have an Enterprise Agreement, you pay for Azure RemoteApp based on your Enterprise Agreement price level. There aren't extra charges. The standard price includes an initial 40 hours. The unlimited price covers an initial 80 hours. RemoteApp stops emitting usage over 80 hours.

+You can download your invoice in the [Azure portal](https://portal.azure.com/) or have it sent in email. Invoices are sent to the person set to receive invoices for the enrollment.

+If you're an Azure customer with an Enterprise Agreement (EA customer), only an EA administrator can download and view your organization's invoice. Direct EA administrators can [Download or view their Azure billing invoice](../manage/direct-ea-azure-usage-charges-invoices.md#download-or-view-your-azure-billing-invoice). Indirect EA administrators can use the information at [Azure Enterprise enrollment invoices](../manage/ea-portal-enrollment-invoices.md) to download their invoice.

+## Where invoices are generated

+An invoice is generated based on your billing account type. Invoices are created for Microsoft Online Service Program (MOSP) also called pay-as-you-go, Microsoft Customer Agreement (MCA), and Microsoft Partner Agreement (MPA) billing accounts. Invoices are also generated for Enterprise Agreement (EA) billing accounts.

+> If you receive an error message that states `The package corresponding to an SQL statement execution request was not found. SQLSTATE=51002 SQLCODE=-805`, the reason is a needed package is not created for the user. By default, the service will try to create the package under the collection named as the user you used to connect to the DB2. Specify the package collection property to indicate under where you want the service to create the needed packages when querying the database. If you can't determine the package collection name, try to set `packageCollection=NULLID`.

+|**24.**|Multi-Process Service (MPS) |When the device software and the Kubernetes cluster are updated, the MPS setting isn't retained for the workloads. |[Re-enable MPS](azure-stack-edge-gpu-connect-powershell-interface.md#connect-to-the-powershell-interface) and redeploy the workloads that were using MPS. |

+|**25.**|Wi-Fi |Wi-Fi doesn't work on Azure Stack Edge Pro 2 in this release. | This functionality may be available in a future release. |

+The current update is Update 2205. This update installs two updates, the device update followed by Kubernetes updates. The associated versions for this update are:

+- Device software version - **2.2.1983.5094**

+- Azure Arc version: **1.6.6**

+- GPU driver version: **510.47.03**

+- CUDA version: **11.6**

+For information on what's new in this update, go to [Release notes](azure-stack-edge-gpu-2205-release-notes.md).

+**To apply 2205 update, your device must be running 2106 or later.**

+- You can update to 2106 from an older version and then install 2205.

+4. Select **Download**. There are two packages to download for the update. The first package will have two files for the device software updates (*SoftwareUpdatePackage.0.exe*, *SoftwareUpdatePackage.1.exe*) and the second package has three files for the Kubernetes updates (*Kubernetes_Package.0.exe*, *Kubernetes_Package.1.exe*, and *Kubernetes_Package.2.exe*), respectively. Download the packages to a folder on the local system. You can also copy the folder to a network share that is reachable from the device.

+7. You will now update the Kubernetes software version. Select the remaining three Kubernetes files together (file with the *Kubernetes_Package.0.exe*, *Kubernetes_Package.1.exe*, and *Kubernetes_Package.2.exe* suffix) and repeat the above steps to apply update.

+| **A history file has been cleared (Preview)**<br>(K8S.NODE_HistoryFileCleared) | Analysis of processes running within a container or directly on a Kubernetes node, has detected that the command history log file has been cleared. Attackers may do this to cover their tracks. The operation was performed by the specified user account. | DefenseEvasion | Medium |

+| **An uncommon connection attempt detected (Preview)**<br>(K8S.NODE_SuspectConnection) | Analysis of processes running within a container or directly on a Kubernetes node, has detected an uncommon connection attempt utilizing a socks protocol. This is very rare in normal operations, but a known technique for attackers attempting to bypass network-layer detections. | Execution, Exfiltration, Exploitation | Medium |

+| **Attempt to stop apt-daily-upgrade.timer service detected (Preview)**<br>(K8S.NODE_TimerServiceDisabled) | Analysis of processes running within a container or directly on a Kubernetes node, has detected an attempt to stop apt-daily-upgrade.timer service. Attackers have been observed stopping this service to download malicious files and grant execution privileges for their attacks. This activity can also happen if the service is updated through normal administrative actions. | DefenseEvasion | Informational |

+| **Behavior similar to common Linux bots detected (Preview)**<br>(K8S.NODE_CommonBot) | Analysis of processes running within a container or directly on a Kubernetes node, has detected the execution of a process normally associated with common Linux botnets. | Execution, Collection, Command And Control | Medium |

+| **Behavior similar to Fairware ransomware detected (Preview)**<br>(K8S.NODE_FairwareMalware) | Analysis of processes running within a container or directly on a Kubernetes node, has detected execution of rm -rf commands applied to suspicious locations. As rm -rf will recursively delete files, it is normally used on discrete folders. In this case, it is being used in a location that could remove a lot of data. Fairware ransomware is known to execute rm -rf commands in this folder. | Execution | Medium |

+| **Container running in privileged mode (Preview)**<br>(K8S.NODE_PrivilegedContainerArtifacts) | Analysis of processes running within a container or directly on a Kubernetes node, has detected the execution of a Docker command that is running a privileged container. The privileged container has full access to the hosting pod or host resource. If compromised, an attacker may use the privileged container to gain access to the hosting pod or host. | PrivilegeEscalation, Execution | Low |

+| **Detected file download from a known malicious source (Preview)**<br>(K8S.NODE_SuspectDownload) | Analysis of processes running within a container or directly on a Kubernetes node, has detected a download of a file from a source frequently used to distribute malware. | PrivilegeEscalation, Execution, Exfiltration, Command And Control | Medium |

+| **Detected Persistence Attempt (Preview)**<br>(K8S.NODE_NewSingleUserModeStartupScript) | Analysis of processes running within a container or directly on a Kubernetes node, has detected the installation of a startup script for single-user mode. It is extremely rare that any legitimate process needs to execute in that mode so it may indicate an attacker has added a malicious process to every run-level to guarantee persistence. | Persistence | Medium |

+| **Detected suspicious file download (Preview)**<br>(K8S.NODE_SuspectDownloadArtifacts) | Analysis of processes running within a container or directly on a Kubernetes node, has detected a suspicious download of a remote file. | Persistence | Low |

+| **Detected suspicious use of the nohup command (Preview)**<br>(K8S.NODE_SuspectNohup) | Analysis of processes running within a container or directly on a Kubernetes node, has detected a suspicious use of the nohup command. Attackers have been seen using the command nohup to run hidden files from a temporary directory to allow their executables to run in the background. It is rare to see this command run on hidden files located in a temporary directory. | Persistence, DefenseEvasion | Medium |

+| **Detected suspicious use of the useradd command (Preview)**<br>(K8S.NODE_SuspectUserAddition) | Analysis of processes running within a container or directly on a Kubernetes node, has detected a suspicious use of the useradd command. | Persistence | Medium |

+| **Digital currency mining related behavior detected (Preview)**<br>(K8S.NODE_DigitalCurrencyMining) | Analysis of processes running within a container or directly on a Kubernetes node, has detected an execution of a process or command normally associated with digital currency mining. | Execution | High |

+| **Executable found running from a suspicious location (Preview)**<br>(K8S.NODE_SuspectExecutablePath) | Analysis of processes running within a container or directly on a Kubernetes node, has detected an executable file that is running from a location associated with known suspicious files. This executable could either be legitimate activity, or an indication of a compromised system. | Execution | Medium |

+| **Execution of hidden file (Preview)**<br>(K8S.NODE_ExecuteHiddenFile) | Analysis of processes running within a container or directly on a Kubernetes node, has detected that a hidden file was executed by the specified user account. | Persistence, DefenseEvasion | Informational |

+| **Exposed Docker daemon on TCP socket (Preview)**<br>(K8S.NODE_ExposedDocker) | Analysis of processes running within a container or directly on a Kubernetes node, has detected that your Docker daemon (dockerd) exposes a TCP socket. By default, Docker configuration, does not use encryption or authentication when a TCP socket is enabled. This enables full access to the Docker daemon, by anyone with access to the relevant port. | Execution, Exploitation | Medium |

+| **Indicators associated with DDOS toolkit detected (Preview)**<br>(K8S.NODE_KnownLinuxDDoSToolkit) ^{[2](#footnote2)} | Analysis of processes running within a container or directly on a Kubernetes node, has detected file names that are part of a toolkit associated with malware capable of launching DDoS attacks, opening ports and services, and taking full control over the infected system. This could also possibly be legitimate activity. | Persistence, LateralMovement, Execution, Exploitation | Medium |

+| **Local host reconnaissance detected (Preview)**<br>(K8S.NODE_LinuxReconnaissance) | Analysis of processes running within a container or directly on a Kubernetes node, has detected the execution of a command normally associated with common Linux bot reconnaissance. | Discovery | Medium |

+| **Manipulation of host firewall detected (Preview)**<br>(K8S.NODE_FirewallDisabled) | Analysis of processes running within a container or directly on a Kubernetes node, has detected a possible manipulation of the on-host firewall. Attackers will often disable this to exfiltrate data. | DefenseEvasion, Exfiltration | Medium |

+| **MITRE Caldera agent detected (Preview)**<br>(K8S.NODE_MitreCalderaTools) | Analysis of processes running within a container or directly on a Kubernetes node, has detected a suspicious process. This is often associated with the MITRE 54ndc47 agent which could be used maliciously to attack other machines. | Persistence, PrivilegeEscalation, DefenseEvasion, CredentialAccess, Discovery, LateralMovement, Execution, Collection, Exfiltration, Command And Control, Probing, Exploitation | Medium |

+| **Possible attack tool detected (Preview)**<br>(K8S.NODE_KnownLinuxAttackTool) | Analysis of processes running within a container or directly on a Kubernetes node, has detected a suspicious tool invocation. This tool is often associated with malicious users attacking others. | Execution, Collection, Command And Control, Probing | Medium |

+| **Possible backdoor detected (Preview)**<br>(K8S.NODE_LinuxBackdoorArtifact) | Analysis of processes running within a container or directly on a Kubernetes node, has detected a suspicious file being downloaded and run. This activity has previously been associated with installation of a backdoor. | Persistence, DefenseEvasion, Execution, Exploitation | Medium |

+| **Possible command line exploitation attempt (Preview)**<br>(K8S.NODE_ExploitAttempt) | Analysis of processes running within a container or directly on a Kubernetes node, has detected a possible exploitation attempt against a known vulnerability. | Exploitation | Medium |

+| **Possible credential access tool detected (Preview)**<br>(K8S.NODE_KnownLinuxCredentialAccessTool) | Analysis of processes running within a container or directly on a Kubernetes node, has detected a possible known credential access tool was running on the container, as identified by the specified process and commandline history item. This tool is often associated with attacker attempts to access credentials. | CredentialAccess | Medium |

+| **Possible Cryptocoinminer download detected (Preview)**<br>(K8S.NODE_CryptoCoinMinerDownload) | Analysis of processes running within a container or directly on a Kubernetes node, has detected download of a file normally associated with digital currency mining. | DefenseEvasion, Command And Control, Exploitation | Medium |

+| **Possible data exfiltration detected (Preview)**<br>(K8S.NODE_DataEgressArtifacts) | Analysis of processes running within a container or directly on a Kubernetes node, has detected a possible data egress condition. Attackers will often egress data from machines they have compromised. | Collection, Exfiltration | Medium |

+| **Possible Log Tampering Activity Detected (Preview)**<br>(K8S.NODE_SystemLogRemoval) | Analysis of processes running within a container or directly on a Kubernetes node, has detected a possible removal of files that tracks user's activity during the course of its operation. Attackers often try to evade detection and leave no trace of malicious activities by deleting such log files. | DefenseEvasion | Medium |

+| **Possible password change using crypt-method detected (Preview)**<br>(K8S.NODE_SuspectPasswordChange) | Analysis of processes running within a container or directly on a Kubernetes node, has detected a password change using the crypt method. Attackers can make this change to continue access and gain persistence after compromise. | CredentialAccess | Medium |

+| **Potential overriding of common files (Preview)**<br>(K8S.NODE_OverridingCommonFiles) | Analysis of processes running within a container or directly on a Kubernetes node, has detected an override for common files as a way to obfuscate actions or for persistence. | Persistence | Medium |

+| **Potential port forwarding to external IP address (Preview)**<br>(K8S.NODE_SuspectPortForwarding) | Analysis of processes running within a container or directly on a Kubernetes node, has detected an initiation of port forwarding to an external IP address. | Exfiltration, Command And Control | Medium |

+| **Potential reverse shell detected (Preview)**<br>(K8S.NODE_ReverseShell) | Analysis of processes running within a container or directly on a Kubernetes node, has detected a potential reverse shell. These are used to get a compromised machine to call back into a machine an attacker owns. | Exfiltration, Exploitation | Medium |

+| **Process associated with digital currency mining detected (Preview)**<br>(K8S.NODE_CryptoCoinMinerArtifacts) | Analysis of processes running within a container or directly on a Kubernetes node, has detected execution of a process normally associated with digital currency mining. | Execution, Exploitation | Medium |

+| **Screenshot taken on host (Preview)**<br>(K8S.NODE_KnownLinuxScreenshotTool) | Analysis of processes running within a container or directly on a Kubernetes node, has detected the use of a screen capture tool. This isn't a common usage scenario for containers and could be part of attackers attempt to access private data. | Collection | Low |

+| **Script extension mismatch detected (Preview)**<br>(K8S.NODE_MismatchedScriptFeatures) | Analysis of processes running within a container or directly on a Kubernetes node, has detected a mismatch between the script interpreter and the extension of the script file provided as input. This has frequently been associated with attacker script executions. | DefenseEvasion | Medium |

+| **Security-related process termination detected (Preview)**<br>(K8S.NODE_SuspectProcessTermination) | Analysis of processes running within a container or directly on a Kubernetes node, has detected an attempt to terminate processes related to security monitoring on the container. Attackers will often try to terminate such processes using predefined scripts post-compromise. | Persistence | Low |

+| **Suspicious compilation detected (Preview)**<br>(K8S.NODE_SuspectCompilation) | Analysis of processes running within a container or directly on a Kubernetes node, has detected a suspicious compilation. Attackers will often compile exploits to escalate privileges. | PrivilegeEscalation, Exploitation | Medium |

+| **Suspicious file timestamp modification (Preview)**<br>(K8S.NODE_TimestampTampering) | Analysis of processes running within a container or directly on a Kubernetes node, has detected a suspicious timestamp modification. Attackers will often copy timestamps from existing legitimate files to new tools to avoid detection of these newly dropped files. | Persistence, DefenseEvasion | Low |

+| **Potential crypto coin miner started (Preview)**<br>(K8S.NODE_CryptoCoinMinerExecution) | Analysis of processes running within a container or directly on a Kubernetes node, has detected a process being started in a way normally associated with digital currency mining. | Execution | Medium |

+| **Suspicious password access (Preview)**<br>(K8S.NODE_SuspectPasswordFileAccess) | Analysis of processes running within a container or directly on a Kubernetes node, has detected suspicious attempt to access encrypted user passwords. | Persistence | Informational |

+| **Suspicious use of DNS over HTTPS (Preview)**<br>(K8S.NODE_SuspiciousDNSOverHttps) | Analysis of processes running within a container or directly on a Kubernetes node, has detected the use of a DNS call over HTTPS in an uncommon fashion. This technique is used by attackers to hide calls out to suspect or malicious sites. | DefenseEvasion, Exfiltration | Medium |

+| **A possible connection to malicious location has been detected. (Preview)**<br>(K8S.NODE_ThreatIntelCommandLineSuspectDomain) | Analysis of processes running within a container or directly on a Kubernetes node, has detected a connection to a location that has been reported to be malicious or unusual. This is an indicator that a compromise may have occured. | InitialAccess | Medium |

+Use an Azure Resource Manager template to deploy an Azure Cosmos DB account with Microsoft Defender for Azure Cosmos DB enabled. For more information, see [Create an Azure Cosmos DB account with Microsoft Defender for Azure Cosmos DB enabled](https://azure.microsoft.com/resources/templates/microsoft-defender-cosmosdb-create-account/).

+| Vulnerability Assessment | Registry scan | ACR, Private ACR | GA | Γ£ô (Preview) | Agentless | Defender for Containers |

+After you sign in for the first time, you need to activate the on-premises management console by getting and uploading an activation file. Activation files on the on-premises management console enforces the number of committed devices configured for your subscription and Defender for IoT plan. For more information, see [Manage Defender for IoT subscriptions](how-to-manage-subscriptions.md).

+**To activate the on-premises management console**:

+### Activation expirations

+After activating an on-premises management console, you'll need to apply new activation files on both the on-premises management console and connected sensors as follows:

+|Location |Activation process |

+|||

+|**On-premises management console** | Apply a new activation file on your on-premises management console if you've [modified the number of committed devices](how-to-manage-subscriptions.md#update-committed-devices-in-a-subscription) in your subscription. |

+|**Cloud-connected sensors** | Cloud-connected sensors remain activated for as long as your Azure subscription with your Defender for IoT plan is active. <br><br>However, you'll also need to apply a new activation file when [updating your sensor software](how-to-manage-individual-sensors.md#download-a-new-activation-file-for-version-221x-or-higher) from a legacy version to version 22.2.x. |

+| **Locally-managed** | Apply a new activation file to locally-managed sensors every year. After a sensor's activation file has expired, the sensor will continue to monitor your network, but you'll see a warning message when signing in to the sensor. |

+For more information, see [Manage Defender for IoT subscriptions](how-to-manage-subscriptions.md).

+### Activate expired licenses from versions earlier than 10.0

+**To activate your license**:

+### Activation expirations

+After activating a sensor, you'll need to apply new activation files as follows:

+|Location |Activation process |

+|||

+|**Cloud-connected sensors** | Cloud-connected sensors remain activated for as long as your Azure subscription with your Defender for IoT plan is active. <br><br>However, you'll also need to apply a new activation file when [updating your sensor software](how-to-manage-individual-sensors.md#download-a-new-activation-file-for-version-221x-or-higher) from a legacy version to version 22.2.x. |

+| **Locally-managed** | Apply a new activation file to locally-managed sensors every year. After a sensor's activation file has expired, the sensor will continue to monitor your network, but you'll see a warning message when signing in to the sensor. |

+For more information, see [Manage Defender for IoT subscriptions](how-to-manage-subscriptions.md) and [Manage the on-premises management console](how-to-manage-the-on-premises-management-console.md).

+| `CorrelationId` | Guid | Unique identifier for the event |

+> Event Grid will start **requiring authorizations to create partner topics or partner destinations** around June 30th, 2022. You should update your documentation asking your customers to grant you the authorization before you attempt to create a channel or an event channel.

+> Event Grid will start requiring authorizations to create partner topics or partner destinations around June 30th, 2022. Meanwhile, requiring your (subscriber's) authorization for a partner to create resources on your Azure subscription is an **optional** feature. We encourage you to opt-in to use this feature and try to use it in non-production Azure subscriptions before it becomes a mandatory step around June 30th, 2022. To opt-in to this feature, reach out to [mailto:askgrid@microsoft.com](mailto:askgrid@microsoft.com) using the subject line **Request to enforce partner authorization on my Azure subscription(s)** and provide your Azure subscription(s) in the email.

+## REST API version 2021-12

+This release corresponds to REST API version 2021-12-01, which includes the following features:

+- [Enable managed identities for system topics](enable-identity-system-topics.md)

+- [Enabled managed identities for custom topics and domains](enable-identity-custom-topics-domains.md)

+- [Use managed identities to deliver events to destinations](add-identity-roles.md)

+- [Support for delivery attributes](delivery-properties.md)

+- [Storage queue - message time-to-live (TTL)](delivery-properties.md#configure-time-to-live-on-outgoing-events-to-azure-storage-queues)-

+- [Azure Active Directory authentication for topics and domains, and partner namespaces](authenticate-with-active-directory.md)

+With FastPath and Private Link, Private Link traffic sent over ExpressRoute bypassess the ExpressRoute virtual network gateway in the data path. This is Generally Available for connections associated to 100Gb ExpressRoute Direct circuits. To enable this, follow the below guidance:

+2. On the Azure portal home page, select **Resource groups** > **Create**.

+1. Select **Create**.

+1. For **Resource group**, select **FW-Hybrid-Test**.

+1. For **Region**, select **(US) East US**.

+1. Select **Next: IP Addresses**.

+1. For **IPv4 address space**, delete the default address and type **10.6.0.0/16**.

+1. Under **Subnet name**, select **Add subnet**.

+1. For **Subnet name** type **SN-Workload**.

+1. For **Subnet address range**, type **10.6.0.0/24**.

+1. Select **Add**.

+1. Select **Review + create**.

+1. Select **Create**.

+5. Select **Save**.

+2. In the left column, select **Networking**, and search for and then select **Firewall**, and then select **Create**.

+ |Firewall tier|**Standard**|

+ |Public IP address |Add new: <br>**fw-pip** |

+1. For the **Address prefix destination**, select **IP Addresses**.

+1. For the **Destination IP addresses/CIDR ranges**, type **10.6.0.0/16**.

+1. For next hop type, select **Virtual appliance**.

+1. For next hop address, type the firewall's private IP address that you noted earlier.

+1. Select **Add**.

+1. For the **Address prefix destination**, select **IP Addresses**.

+1. For the **Destination IP addresses/CIDR ranges**, type **0.0.0.0/0**.

+1. For next hop type, select **Virtual appliance**.

+1. For next hop address, type the firewall's private IP address that you noted earlier.

+1. Select **Add**.

+2. Under **Popular Marketplace products**, select **Windows Server 2019 Datacenter**.

+ - **Resource group** - Select **FW-Hybrid-Test**

+ - **Virtual machine name**: *VM-Spoke-01*

+ - **Region** - Same region that you're used previously

+ - **User name**: \<type a user name\>

+4. For **Public inbound ports**, select **Allow selected ports**, and then select **HTTP (80)**, and **RDP (3389)**.

+After the virtual machine is created, install IIS.

+2. Under **Popular Marketplace products**, select **Windows Server 2019 Datacenter**.

+ New-AzADServicePrincipal -ApplicationId "ad0e1c7e-6d38-4ba4-9efd-0bc77ba9f037"

+ az ad sp create --id ad0e1c7e-6d38-4ba4-9efd-0bc77ba9f037

+ az ad sp create --id 205478c0-bd83-4e1b-a9d6-db63a3e1e1c8

+> [!IMPORTANT]

+> The default metastore provides a basic tier Azure SQL Database with only **5 DTU and 2 GB data max size (NOT UPGRADEABLE)**! Use this for QA and testing purposes only. **For production or large workloads, we recommend migrating to an external metastore!**

+* Limited resources. See notice at the top of the page.

+* The default metastore is part of the cluster lifecycle. When you delete a cluster, the corresponding metastore and metadata are also deleted.

+* The default metastore is recommended only for simple workloads. Workloads that don't require multiple clusters and don't need metadata preserved beyond the cluster's lifecycle.

+* The default metastore can't be shared with other clusters.

+ > This code sends the string `test message` to the topic `testtopic`. The default configuration of Kafka on HDInsight is not to create the topic if it does not exist. See [How to configure Apache Kafka on HDInsight to automatically create topics](./apache-kafka-auto-create-topics.md). Alternatively, you can create topics manually before producing messages.

+

+ GET https://{your app subdomain}.azureiotcentral.com/api/roles?api-version=2022-05-31

+ PUT https://{your app subdomain}.azureiotcentral.com/api/apiToken/operator-token?api-version=2022-05-31

+GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components?api-version=2022-05-31

+GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules?api-version=2022-05-31

+GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules?api-version=2022-05-31

+GET https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/telemetry/temperature?api-version=2022-05-31

+GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/telemetry/temperature?api-version=2022-05-31

+GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules/SimulatedTemperatureSensor/telemetry/ambient?api-version=2022-05-31

+GET https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/properties?api-version=2022-05-31

+GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/properties?api-version=2022-05-31

+GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/properties?api-version=2022-05-31

+GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules/SimulatedTemperatureSensor/properties?api-version=2022-05-31

+PATCH https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/properties?api-version=2022-05-31

+PATCH https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/properties?api-version=2022-05-31

+PUT https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules/SimulatedTemperatureSensor/properties?api-version=2022-05-31

+GET https://{your app subdomain}.azureiotcentral.com/api/devices/{deviceId}/modules/{moduleName}/properties?api-version=2022-05-31

+GET https://{your app subdomain}.azureiotcentral.com/api/devices/{deviceId}/modules/{moduleName}/components/{componentName}/properties?api-version=2022-05-31

+POST https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/commands/getMaxMinReport?api-version=2022-05-31

+GET https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/commands/getMaxMinReport?api-version=2022-05-31

+POST https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/commands/getMaxMinReport?api-version=2022-05-31

+GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/commands/getMaxMinReport?api-version=2022-05-31

+ Title: Integrate Azure IoT Central with CI/CD | Microsoft Docs

+description: Describes how to integrate IoT Central into a pipeline created with Azure Pipelines.

+# Integrate IoT Central with Azure Pipelines for CI/CD

+## Overview

+Continuous integration and continuous delivery (CI/CD) refers to the process of developing and delivering software in short, frequent cycles using automation pipelines. This article shows you how to automate the build, test, and deployment of IoT Central application configuration, to enable development teams to deliver reliable releases more frequently.

+Continuous integration starts with a commit of your code to a branch in a source code repository. Each commit is merged with commits from other developers to ensure that no conflicts are introduced. Changes are further validated by creating a build and running automated tests against that build. This process ultimately results in an artifact, or deployment bundle, to deploy to a target environment, in this case an Azure IoT Central application.

+Just as IoT Central is a part of your larger IoT solution, IoT Central is a part of your CI/CD pipeline. Your CI/CD pipeline should deploy your entire IoT solution and all configurations to each environment from development through to production:

+IoT Central is an *application platform as a service* that has different deployment requirements from *platform as a service* components. For IoT Central, you deploy configurations and device templates. These configurations and device templates are managed and integrated into your release pipeline by using APIs.

+While it's possible to automate IoT Central app creation, you should create an app in each environment before you develop your CI/CD pipeline.

+By using the Azure IoT Central REST API, you can integrate IoT Central app configurations into your release pipeline.

+This guide walks you through the creation of a new pipeline that updates an IoT Central application based on configuration files managed in GitHub. This guide has specific instructions for integrating with [Azure Pipelines](/azure/devops/pipelines/?view=azure-devops&preserve-view=true), but could be adapted to include IoT Central in any release pipeline built using tools such as Tekton, Jenkins, GitLab, or GitHub Actions.

+In this guide, you create a pipeline that only applies an IoT Central configuration to a single instance of an IoT Central application. You should integrate the steps into a larger pipeline that deploys your entire solution and promotes it from *development* to *QA* to *pre-production* to *production*, performing all necessary testing along the way.

+The scripts currently don't transfer the following settings between IoT Central instances: dashboards, views, custom settings in device templates, pricing plan, UX customizations, application image, rules, scheduled jobs, saved jobs, and enrollment groups.

+The scripts currently don't remove settings from the target IoT Central application that aren't present in the configuration file.

+## Prerequisites

+You need the following prerequisites to complete the steps in this guide:

+- Two IoT Central applications - one for your development environment and one for your production environment. To learn more, see [Create an IoT Central application](howto-create-iot-central-application.md).

+- Two Azure Key Vaults - one for your development environment and one for your production environment. It's best practice to have a dedicated Key Vault for each environment. To learn more, see [Create an Azure Key Vault with the Azure portal](../../key-vault/general/quick-create-portal.md).

+- A GitHub account [GitHub](https://github.com/).

+- An Azure DevOps organization. To learn more, see [Create an Azure DevOps organization](/devops/organizations/accounts/create-organization?view=azure-devops&preserve-view=true).

+- PowerShell 7 for Windows, Mac or Linux. [Get PowerShell](/powershell/scripting/install/installing-powershell).

+- Azure Az PowerShell module installed in your PowerShell 7 environment. To learn more, see [Install the Azure Az PowerShell module](/powershell/azure/install-az-ps).

+- Visual Studio Code or other tool to edit PowerShell and JSON files.[Get Visual Studio Code](https://code.visualstudio.com/Download).

+- Git client. Download the latest version from [Git - Downloads (git-scm.com)](https://git-scm.com/downloads).

+## Download the sample code

+To get started, fork the IoT Central CI/CD GitHub repository and then clone your fork to your local machine:

+1. To fork the Git Hub repository, open the [IoT Central CI/CD GitHub repository](https://github.com/Azure/iot-central-CICD-sample) and select **Fork**.

+1. Clone your fork of the repository to your local machine by opening a console or bash window and running the following command.

+ ```cmd\bash

+ git clone https://github.com/{your GitHub username}/iot-central-CICD-sample

+ ```

+## Create a service principal

+While Azure Pipelines can integrate directly with a key vault, your pipeline needs a service principal for some of the dynamic key vault interactions such as fetching secrets for data export destinations.

+To create a service principal scoped to your subscription:

+1. Run the following command to create a new service principal:

+ ```azurecli

+ az ad sp create-for-rbac -n DevOpsAccess --scopes /subscriptions/{your Azure subscription Id} --role Contributor

+ ```

+1. Make a note of the **password**, **appId**, and **tenant** as you need these values later.

+1. Add the service principal password as a secret called `SP-Password` to your production key vault:

+ ```azurecli

+ az keyvault secret set --name SP-Password --vault-name {your production key vault name} --value {your service principal password}

+ ```

+1. Give the service principal permission to read secrets from the key vault:

+ ```azurecli

+ az keyvault set-policy --name {your production key vault name} --secret-permissions get list --spn {the appId of the service principal}

+ ```

+## Generate IoT Central API tokens

+In this guide, your pipeline uses API tokens to interact with your IoT Central applications. It's also possible to use a service principal.

+> [!NOTE]

+> IoT Central API tokens expire after one year.

+Complete the following steps for both your development and production IoT Central apps.

+1. In your IoT Central app, select **Permissions** and then **API tokens**.

+1. Select **New**.

+1. Give the token a name, specify the top-level organization in your app, and set the role to **App Administrator**.

+1. Make a note of the API token from your development IoT Central application. You use it later when you run the *IoTC-Config.ps1* script.

+1. Save the generated token from the production IoT Central application as a secret called `API-Token` to the production key vault:

+ ```azurecli

+ az keyvault secret set --name API-Token --vault-name {your production key vault name} --value '{your production app API token}'

+ ```

+## Generate a configuration file

+These steps produce a JSON configuration file for your development environment based on an existing IoT Central application. You also download all the existing device templates from the application.

+1. Run the following PowerShell 7 script in the local copy of the IoT Central CI/CD repository:

+ ```powershell

+ cd .\iot-central-CICD-sample\PowerShell\

+ .\IoTC-Config.ps1

+ ```

+1. Follow the instructions to sign in to your Azure account.

+1. After you sign in, the script displays the IoTC Config options menu. The script can generate a config file from an existing IoT Central application and apply a configuration to another IoT Central application.

+1. Select option **1** to generate a configuration file.

+1. Enter the necessary parameters and press **Enter**:

+ - The API token you generated for your development IoT Central application.

+ - The subdomain of your development IoT Central application.

+ - Enter *..\Config\Dev* as the folder to store the config file and device templates.

+ - The name of your development key vault.

+1. The script creates a folder called *IoTC Configuration* in the *Config\Dev* folder in your local copy of the repository. This folder contains a configuration file and a folder called *Device Models* for all the device templates in your application.

+## Modify the configuration file

+Now that you have a configuration file that represents the settings for your development IoT Central application instance, make any necessary changes before you apply this configuration to your production IoT Central application instance.

+1. Create a copy of the *Dev* folder created previously and call it *Production*.

+1. Open IoTC-Config.json in the *Production* folder using a text editor.

+1. The file has multiple sections. However, if your application doesn't use a particular setting, that section is omitted from the file:

+ ```json

+ {

+ "APITokens": {

+ "value": [

+ {

+ "id": "dev-admin",

+ "roles": [

+ {

+ "role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"

+ }

+ ],

+ "expiry": "2023-05-31T10:47:08.53Z"

+ }

+ ]

+ },

+ "data exports": {

+ "value": [

+ {

+ "id": "5ad278d6-e22b-4749-803d-db1a8a2b8529",

+ "displayName": "All telemetry to blob storage",

+ "enabled": false,

+ "source": "telemetry",

+ "destinations": [

+ {

+ "id": "393adfc9-0ed8-45f4-aa29-25b5c96ecf63"

+ }

+ ],

+ "status": "notStarted"

+ }

+ ]

+ },

+ "device groups": {

+ "value": [

+ {

+ "id": "66f41d29-832d-4a12-9e9d-18932bee3141",

+ "displayName": "MXCHIP Getting Started Guide - All devices"

+ },

+ {

+ "id": "494dc749-0963-4ec1-89ff-e1de2228e750",

+ "displayName": "RS40 Occupancy Sensor - All devices"

+ },

+ {

+ "id": "dd87877d-9465-410b-947e-64167a7a1c39",

+ "displayName": "Cascade 500 - All devices"

+ },

+ {

+ "id": "91ceac5b-f98d-4df0-9ed6-5465854e7d9e",

+ "displayName": "Simulated devices"

+ }

+ ]

+ },

+ "organizations": {

+ "value": []

+ },

+ "roles": {

+ "value": [

+ {

+ "id": "344138e9-8de4-4497-8c54-5237e96d6aaf",

+ "displayName": "Builder"

+ },

+ {

+ "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4",

+ "displayName": "Administrator"

+ },

+ {

+ "id": "ae2c9854-393b-4f97-8c42-479d70ce626e",

+ "displayName": "Operator"

+ }

+ ]

+ },

+ "destinations": {

+ "value": [

+ {

+ "id": "393adfc9-0ed8-45f4-aa29-25b5c96ecf63",

+ "displayName": "Blob destination",

+ "type": "blobstorage@v1",

+ "authorization": {

+ "type": "connectionString",

+ "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourexportaccount;AccountKey=*****;EndpointSuffix=core.windows.net",

+ "containerName": "dataexport"

+ },

+ "status": "waiting"

+ }

+ ]

+ },

+ "file uploads": {

+ "connectionString": "FileUpload",

+ "container": "fileupload",

+ "sasTtl": "PT1H"

+ },

+ "jobs": {

+ "value": []

+ }

+ }

+ ```

+1. If your application uses file uploads, the script creates a secret in your development key vault with the value shown in the `connectionString` property. Create a secret with the same name in your production key vault that contains the connection string for your production storage account. For example:

+ ```azurecli

+ az keyvault secret set --name FileUpload --vault-name {your production key vault name} --value '{your production storage account connection string}'

+ ```

+1. If your application uses data exports, add secrets for the destinations to the production key vault. The config file doesn't contain any actual secrets for your destination, the secrets are stored in your key vault.

+1. Update the secrets in the config file with the name of the secret in your key vault.

+ | Destination type | Property to change |

+ | | |

+ | Service Bus queue | connectionString |

+ | Service Bus topic | connectionString |

+ | Azure Data Explorer | clientSecret |

+ | Azure Blob Storage | connectionString |

+ | Event Hubs | connectionString |

+ | Webhook No Auth | N/A |

+ For example:

+ ```json

+ "destinations": {

+ "value": [

+ {

+ "id": "393adfc9-0ed8-45f4-aa29-25b5c96ecf63",

+ "displayName": "Blob destination",

+ "type": "blobstorage@v1",

+ "authorization": {

+ "type": "connectionString",

+ "connectionString": "Storage-CS",

+ "containerName": "dataexport"

+ },

+ "status": "waiting"

+ }

+ ]

+ }

+ ```

+1. To upload the *Configuration* folder to your GitHub repository, run the following commands from the *IoTC-CICD-howto* folder.

+ ```cmd/bash

+ git add Config

+ git commit -m "Adding config directories and files"

+ git push

+ ```

+## Create a pipeline

+1. Open your Azure DevOps organization in a web browser by going to `https://dev.azure.com/{your DevOps organization}`

+1. Select **New project** to create a new project.

+1. Give your project a name and optional description and then select **Create**.

+1. On the **Welcome to the project** page, select **Pipelines** and then **Create Pipeline**.

+1. Select **GitHub** as the location of your code.

+1. Select **Authorize AzurePipelines** to authorize Azure Pipelines to access your GitHub account.

+1. On the **Select a repository** page, select your fork of the IoT Central CI/CD GitHub repository.

+1. When prompted to log into GitHub and provide permission for Azure Pipelines to access the repository, select **Approve & install**.

+1. On the **Configure your pipeline** page, select **Starter pipeline** to get started. The *azure-pipelines.yml* is displayed for you to edit.

+## Create a variable group

+An easy way to integrate key vault secrets into a pipeline is through variable groups. Use a variable group to ensure the right secrets are available to your deployment script. To create a variable group:

+1. Select **Library** in the **Pipelines** section of the menu on the left.

+1. Select **+ Variable group**.

+1. Enter `keyvault` as the name for your variable group.

+1. Enable the toggle to link secrets from an Azure key vault.

+1. Select your Azure subscription and authorize it. Then select your production key vault name.

+1. Select **Add** to start adding variables to the group.

+1. Add the following secrets:

+ - The IoT Central API Key for your production app. You called this secret `API-Token` when you created it.

+ - The password for the service principal you created previously. You called this secret `SP-Password` when you created it.

+1. Select **OK**.

+1. Select **Save** to save the variable group.

+## Configure your pipeline

+Now configure the pipeline to push configuration changes to your IoT Central application:

+1. Select **Pipelines** in the **Pipelines** section of the menu on the left.

+1. Replace the contents of your pipeline YAML with the following YAML. The configuration assumes your production key vault contains:

+ - The API token for your production IoT Central app in a secret called `API-Token`.

+ - Your service principal password in a secret called `SP-Password`.

+

+ Replace the values for `-AppName` and `-KeyVault` with the appropriate values for your production instances.

+ You made a note of the `-AppId` and `-TenantId` when you created your service principal.

+ ```yml

+ trigger:

+ - master

+ variables:

+ - group: keyvault

+ - name: buildConfiguration

+ value: 'Release'

+ steps:

+ - task: PowerShell@2

+ displayName: 'IoT Central'

+ inputs:

+ filePath: 'PowerShell/IoTC-Task.ps1'

+ arguments: '-ApiToken "$(API-Token)" -ConfigPath "Config/Production/IoTC Configuration" -AppName "{your production IoT Central app name}" -ServicePrincipalPassword (ConvertTo-SecureString "$(SP-Password)" -AsPlainText -Force) -AppId "{your service principal app id}" -KeyVault "{your production key vault name}" -TenantId "{your tenant id}"'

+ pwsh: true

+ failOnStderr: true

+ ```

+1. Select **Save and run**.

+1. The YAML file is saved to your Git Hub repository, so you need to provide a commit message and then select **Save and run** again.

+Your pipeline is queued. It may take a few minutes before it runs.

+The first time you run your pipeline, you're prompted to give permissions for the pipeline to access your subscription and to access your key vault. Select **Permit** and then **Permit** again for each resource.

+When your pipeline job completes successfully, sign in to your production IoT Central application and verify the configuration was applied as expected.

+## Promote changes from development to production

+Now that you have a working pipeline you can manage your IoT Central instances directly by using configuration changes. You can upload new device templates into the *Device Models* folder and make changes directly to the configuration file. This approach lets you treat your IoT Central application's configuration the same as any other code.

+## Next steps

+Now that know how to integrate IoT Central configurations into your CI/CD pipelines, a suggested next step is to learn how to [Manage and monitor IoT Central from the Azure portal](howto-manage-iot-central-from-portal.md).

+PUT https://{subdomain}.{baseDomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-05-31

+GET https://{subdomain}.{baseDomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-05-31

+PATCH https://{subdomain}.{baseDomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-05-31

+DELETE https://{subdomain}.{baseDomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-05-31

+GET https://{subdomain}.{baseDomain}/api/deviceTemplates?api-version=2022-05-31

+PUT https://{subdomain}.{baseDomain}/api/devices/{deviceId}?api-version=2022-05-31

+GET https://{subdomain}.{baseDomain}/api/devices/{deviceId}?api-version=2022-05-31

+GET https://{subdomain}.{baseDomain}/api/devices/{deviceId}/credentials?api-version=2022-05-31

+PATCH https://{subdomain}.{baseDomain}/api/devices/{deviceId}?api-version=2022-05-31

+DELETE https://{subdomain}.{baseDomain}/api/devices/{deviceId}?api-version=2022-05-31

+GET https://{subdomain}.{baseDomain}/api/devices?api-version=2022-05-31

+PUT https://{subdomain}.{baseDomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-05-31

+GET https://{subdomain}.{baseDomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-05-31

+PATCH https://{subdomain}.{baseDomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-05-31

+DELETE https://{subdomain}.{baseDomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-05-31

+GET https://{subdomain}.{baseDomain}/api/deviceGroups?api-version=2022-05-31

+PUT https://{subdomain}.{baseDomain}/api/organizations/{organizationId}?api-version=2022-05-31

+GET https://{subdomain}.{baseDomain}/api/organizations/{organizationId}?api-version=2022-05-31

+PATCH https://{subdomain}.{baseDomain}/api/organizations/{organizationId}?api-version=2022-05-31

+GET https://{your app subdomain}.azureiotcentral.com/api/organizations?api-version=2022-05-31

+DELETE https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-05-31

+GET https://{your app subdomain}.azureiotcentral.com/api/roles?api-version=2022-05-31

+GET https://{your app subdomain}.azureiotcentral.com/api/users?api-version=2022-05-31

+GET https://{your app subdomain}.azureiotcentral.com/api/users/dc1c916b-a652-49ea-b128-7c465a54c759?api-version=2022-05-31

+PUT https://{your app subdomain}.azureiotcentral.com/api/users/user-001?api-version=2022-05-31

+PATCH https://{your app subdomain}.azureiotcentral.com/api/users/user-001?api-version=2022-05-31

+DELETE https://{your app subdomain}.azureiotcentral.com/api/users/user-001?api-version=2022-05-31

+PUT https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-05-31

+GET https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-05-31

+PATCH https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-05-31

+DELETE https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-05-31

+description: Azure IoT Central is an IoT application platform that simplifies the creation of IoT solutions. This guide describes how to administer your IoT Central application. Application administration includes users, organization, security, and automated deployments.

+- DevOps integration.

+To learn more, see [Create and use a custom application template](howto-create-iot-central-application.md#create-and-use-a-custom-application-template).

+## Integrate with DevOps pipelines

+Continuous integration and continuous delivery (CI/CD) refers to the process of developing and delivering software in short, frequent cycles using automation pipelines. You can use Azure DevOps pipelines to automate the build, test, and deployment of IoT Central application configurations.

+Just as IoT Central is a part of your larger IoT solution, make IoT Central a part of your CI/CD pipeline.

+To learn more, see [Integrate IoT Central into your Azure DevOps CI/CD pipeline](howto-integrate-with-devops.md).

+| CorrelationId | GUID | Unique identifier for the event. |

+description: How to update IoT Edge devices to run the latest versions of the security subsystem and the IoT Edge runtime

+Two logical components of an IoT Edge device need to be updated if you want to move to a newer version. The first is the security subsystem. Although the architecture of the security subsystem [changed between version 1.1 and 1.2](iot-edge-security-manager.md), its overall responsibilities remained the same. It runs on the device, handles security-based tasks, and starts the modules when the device starts. Currently, the security subsystem can only be updated from the device itself. The second component is the runtime, made up of the IoT Edge hub and IoT Edge agent modules. Depending on how you structure your deployment, the runtime can be updated from the device or remotely.

+## Update the security subsystem

+The IoT Edge security subsystem includes a set of native components that need to be updated using the package manager on the IoT Edge device.

+Check the version of the security subsystem running on your device by using the command `iotedge version`. If you're using IoT Edge for Linux on Windows, you need to SSH into the Linux virtual machine to check the version.

+On Linux x64 devices, use apt-get or your appropriate package manager to update the runtime module to the latest version.

+If you want to update to the most recent version of the runtime module, use the following command which also updates **libiothsm-std** to the latest version:

+If you want to update to a specific version of the runtime module, specify the version from the apt list output. Whenever **iotedge** is updated, it automatically tries to update the **libiothsm-std** package to its latest version, which may cause a dependency conflict. If you aren't going to the most recent version, be sure to target both packages for the same version. For example, the following command installs a specific version of the 1.1 release:

+If you want to update to the most recent version of IoT Edge, use the following command which also updates the [identity service](https://azure.github.io/iot-identity-service/) to the latest version:

+It's recommended to install the micro agent with the Edge agent to enable security monitoring and hardening of your Edge devices. To learn more about Microsoft Defender for IoT, see [What is Microsoft Defender for IoT for device builders](../defender-for-iot/device-builders/overview.md).

+>Currently, there's no support for IoT Edge version 1.2 running on Windows devices.

+Use the `Update-IoTEdge` command to update the module runtime. The script automatically pulls the latest version of the module runtime.

+Running the `Update-IoTEdge` command removes and updates the runtime module from your device, along with the two runtime container images. The config.yaml file is kept on the device, as well as data from the Moby container engine. Keeping the configuration information means that you don't have to provide the connection string or Device Provisioning Service information for your device again during the update process.

+If you want to update to a specific version of the security subsystem, find the version from 1.1 release channel you want to target from [IoT Edge releases](https://github.com/Azure/azure-iotedge/releases). In that version, download the **Microsoft-Azure-IoTEdge.cab** file. Then, use the `-OfflineInstallationPath` parameter to point to the local file location. For example:

+Delete the local version of the image from your IoT Edge device. On Windows machines, uninstalling the security subsystem also removes the runtime images, so you don't need to take this step again.

+* A new identity service, **[aziot-identity-service](https://azure.github.io/iot-identity-service/)** was introduced as part of the 1.2 release. This service handles the identity provisioning and management for IoT Edge and for other device components that need to communicate with IoT Hub, like [Device Update for IoT Hub](../iot-hub-device-update/understand-device-update.md).

+It's recommended to install the micro agent with the Edge agent to enable security monitoring and hardening of your Edge devices. To learn more about Microsoft Defender for IoT, see [What is Microsoft Defender for IoT for device builders](../defender-for-iot/device-builders/overview.md).

+Use the sections in this article to learn how to update an IoT Edge device to a specific version of the security subsystem or runtime modules.

+If you're updating a specific version of the Azure IoT Edge security daemon, then you should include the desired version of the `aziot-edge` package and its dependent `aziot-identity-service` package in your APT manifest.

+[Learn More](../iot-edge/how-to-update-iot-edge.md#update-the-security-subsystem)

+Set-AzKeyVaultKeyRotationPolicy -VaultName <vault-name> -KeyName <key-name> -ExpiresIn (New-TimeSpan -Days 720) -KeyRotationLifetimeAction @{Action="Rotate";TimeAfterCreate= (New-TimeSpan -Days 540)}

+description: Create, deploy, and manage an example serverless app with an Azure Quickstart Template, Azure Logic Apps and Azure Functions in Visual Studio.

+This article shows how to create an example serverless app that runs in multi-tenant Azure by using an Azure Quickstart Template. The template creates an Azure resource group project that includes an Azure Resource Manager deployment template. This template defines a basic logic app resource where a predefined a workflow includes a call to an Azure function that you define. The workflow definition includes the following components:

+ Title: Deploy Standard logic apps to private storage accounts

+description: Deploy Standard logic app workflows to Azure storage accounts that use private endpoints and deny public access.

+# As a developer, I want to deploy Standard logic apps to Azure storage accounts that use private endpoints.

+ Title: About Standard logic app workflow designer

+# About the Standard logic app workflow designer in single-tenant Azure Logic Apps

+ Title: Edit runtime and environment settings for Standard logic apps

+description: Change the runtime and environment settings for Standard logic apps in single-tenant Azure Logic Apps.

+# Edit host and app settings for Standard logic apps in single-tenant Azure Logic Apps

+description: Estimate storage costs for Standard logic app workflows using the Logic Apps Storage Calculator.

+# Estimate storage costs for Standard logic app workflows in single-tenant Azure Logic Apps

+description: Monitor health for Azure Logic Apps resources in Azure Security Center by setting up diagnostic logging.

+When you monitor your Azure Logic Apps resources in [Microsoft Azure Security Center](../security-center/security-center-introduction.md), you can [review whether your logic apps are following the default policies](#view-logic-apps-health-status). Azure shows the health status for an Azure Logic Apps resource after you enable logging and correctly set up the logs' destination. This article explains how to configure diagnostic logging and make sure that all your logic apps are healthy resources.

+> To find the current status for the Azure Logic Apps service, review the [Azure status page](https://status.azure.com/), which lists the status for different products and services in each available region.

+> The default recommendation is to enable diagnostic logs for Azure Logic Apps. However, you control this setting for your logic apps. When you enable diagnostic logs for your logic apps, you can use the information to help analyze security incidents.

+1. On the recommendation page, expand the **Remediation steps** section and review the options. You can enable Azure Logic Apps diagnostics by selecting the **Quick Fix!** button, or by following the manual remediation instructions.

+1. On the inventory page, filter your assets list to show only Azure Logic Apps resources. In the page menu, select **Resource types** &gt; **logic apps**.

+If you use Log Analytics or Event Hubs as the destination for your Azure Logic Apps diagnostic logs, check the following settings.

+If you use a storage account as the destination for your Azure Logic Apps diagnostic logs, check the following settings.

+ The batch sender can specify a unique key that *partitions* or divides the target batch into logical subsets, based on that key. For example, a customer number is a unique key. That way, the receiver app can collect all items with the same key and process them together.

+Your batch receiver and batch sender need to share the same Azure subscription *and* Azure region. If they don't, you can't select the batch receiver when you create the batch sender because they're not visible to each other.

+ This **rand** function generates a number between one and five. So, you're dividing this batch into five numbered partitions, which this expression dynamically sets.

+Your batch sender logic app runs every minute and generates a random number between one and five. The batch sender uses this random number as the partition key for the target batch where you send the messages. Each time the batch has five items with the same partition key, your batch receiver logic app fires and sends mail for each message.

+* [Batch and send EDI messages](../logic-apps/logic-apps-scenario-edi-send-batch-messages.md)

+The previous patterns are useful ways to handle errors and exceptions that happen within a run. However, you can also identify and respond to errors that happen independently from the run. To evaluate run statuses, you can monitor the logs and metrics for your runs, or publish them into any monitoring tool that you prefer.

+For example, [Azure Monitor](../azure-monitor/overview.md) provides a streamlined way to send all workflow events, including all run and action statuses, to a destination. You can [set up alerts for specific metrics and thresholds in Azure Monitor](monitor-logic-apps.md#set-up-monitoring-alerts). You can also send workflow events to a [Log Analytics workspace](../azure-monitor/logs/data-platform-logs.md) or [Azure storage account](../storage/blobs/storage-blobs-overview.md). Or, you can stream all events through [Azure Event Hubs](../event-hubs/event-hubs-about.md) into [Azure Stream Analytics](https://azure.microsoft.com/services/stream-analytics/). In Stream Analytics, you can write live queries based on any anomalies, averages, or failures from the diagnostic logs. You can use Stream Analytics to send information to other data sources, such as queues, topics, SQL, Azure Cosmos DB, or Power BI.

+For more information, review [Set up Azure Monitor logs and collect diagnostics data for Azure Logic Apps](monitor-logic-apps-log-analytics.md).

+* [Learn more about Azure Logic Apps examples and scenarios](logic-apps-examples-and-scenarios.md)

+* Kubernetes

+description: Learn how to access and process data in Azure Machine Learning

+Azure Machine Learning lets you bring data from a local machine or an existing cloud-based storage. In this article you will learn the main data concepts in Azure Machine Learning, including:

+> [!div class="checklist"]

+> - [**URIs**](#uris) - A **U**niform **R**esource **I**dentifier that is a reference to a storage location on your local computer or in the cloud that makes it very easy to access data in your jobs.

+> - [**Data asset**](#data-asset) - Create data assets in your workspace to share with team members, version, and track data lineage.

+> - [**Datastore**](#datastore) - Azure Machine Learning Datastores securely keep the connection information to your data storage on Azure, so you don't have to code it in your scripts.

+> - [**MLTable**](#mltable) - a method to abstract the schema definition for tabular data so that it is easier for consumers of the data to materialize the table into a Pandas/Dask/Spark dataframe.

+## URIs

+A URI (uniform resource identifier) represents a storage location on your local computer, an attached Datastore, blob/ADLS storage, or a publicly available http(s) location. In addition to local paths (for example: `./path_to_my_data/`), several different protocols are supported for cloud storage locations:

+- `http(s)` - Private/Public Azure Blob Storage Locations, or publicly available http(s) location

+- `abfs(s)` - Azure Data Lake Storage Gen2 storage location

+- `azureml` - An Azure Machine Learning [Datastore](#datastore) location

+Azure Machine Learning distinguishes two types of URIs:

+Data type | Description | Examples

+||

+`uri_file` | Refers to a specific **file** location | `https://<account_name>.blob.core.windows.net/<container_name>/<folder>/<file>`<br> `azureml://datastores/<datastore_name>/paths/<folder>/<file>` <br> `abfss://<file_system>@<account_name>.dfs.core.windows.net/<folder>/<file>`

+`uri_folder`| Refers to a specific **folder** location | `https://<account_name>.blob.core.windows.net/<container_name>/<folder>`<br> `azureml://datastores/<datastore_name>/paths/<folder>` <br> `abfss://<file_system>@<account_name>.dfs.core.windows.net/<folder>/`

+URIs are mapped to the filesystem on the compute target, hence using URIs is like using files or folders in the command that consumes/produces them. URIs leverage **identity-based authentication** to connect to storage services with either your Azure Active Directory ID (default) or Managed Identity.

+> [!TIP]

+> For data located in an Azure storage account we recommend using the [Azure Storage Explorer](https://azure.microsoft.com/features/storage-explorer/#overview). You can browse data and obtain the URI for any file/folder by right-selecting **Copy URL**:

+> :::image type="content" source="media/concept-data/use-storage-explorer.png" alt-text="Screenshot of the Storage Explorer with Copy URL highlighted.":::

+### Examples

+# [`uri_file`](#tab/uri-file-example)

+Below is an example of a job specification that shows how to access a file from a public blob store. In this example, the job executes the Linux `ls` command.

+```yml

+# hello-data-uri-file.yml

+$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json

+command: |

+ ls ${{inputs.my_csv_file}}

+inputs:

+ my_csv_file:

+ type: uri_file

+ path: https://azuremlexamples.blob.core.windows.net/datasets/titanic.csv

+environment: azureml:AzureML-sklearn-1.0-ubuntu20.04-py38-cpu@latest

+compute: azureml:cpu-cluster

+```

+Create the job using the CLI:

+```azurecli

+az ml job create --file hello-data-uri-file.yml

+```

+When the job has completed the user logs will show the standard output of the Linux command `ls ${{inputs.my_csv_file}}`:

+Notice that the file has been mapped to the filesystem on the compute target and `${{inputs.my_csv_file}}` resolves to that location.

+# [`uri_folder`](#tab/uri-folder-example)

+In the case where you want to map a **folder** to the filesystem of the compute target, you define the `uri_folder` type in your job specification file:

+```yml

+# hello-data-uri-folder.yml

+$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json

+command: |

+ ls ${{inputs.sampledata}}

+inputs:

+ sampledata:

+ type: uri_folder

+ path: https://<account_name>.blob.core.windows.net/<container_name>/<folder>

+environment: azureml:AzureML-sklearn-1.0-ubuntu20.04-py38-cpu@latest

+compute: azureml:cpu-cluster

+```

+Create the job using the CLI:

+```azurecli

+az ml job create --file hello-data-uri-folder.yml

+```

+When the job has completed the user logs will show the standard output of the Linux command `ls ${{inputs.sampledata}}`:

+Notice that the folder has been mapped to the filesystem on the compute target (you can see all the files in the folder), and `${{inputs.sampledata}}` resolves to the folder location.

+## Data asset

+Azure Machine Learning allows you to create and version data assets in a workspace so that other members of your team can easily consume the data asset by using a name/version.

+### Example usage

+# [Create data asset](#tab/cli-data-create-example)

+To create a data asset, firstly define a data specification in a YAML file that provides a name, type and path for the data:

+```yml

+# data-example.yml

+$schema: https://azuremlschemas.azureedge.net/latest/data.schema.json

+name: <name>

+description: <description>

+type: <type> # uri_file, uri_folder, mltable

+path: https://<storage_name>.blob.core.windows.net/<container_name>/path

+```

+Then in the CLI, create the data asset:

+```azurecli

+az ml data create --file data-example.yml --version 1

+```

+# [Consume data asset](#tab/cli-data-consume-example)

+To consume a data asset in a job, define your job specification in a YAML file the path to be `azureml:<NAME_OF_DATA_ASSET>:<VERSION>`, for example:

+```yml

+# hello-data-uri-file.yml

+$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json

+command: |

+ ls ${{inputs.sampledata}}

+code: src

+inputs:

+ sampledata:

+ type: <type> # uri_file, uri_folder, mltable

+ path: azureml:<data_name>@latest

+environment: azureml:<environment_name>@latest

+compute: azureml:<compute_name>

+```

+Next, use the CLI to create your job:

+```azurecli

+az ml job create --file hello-data-uri-file.yml

+```

+## Datastore

+An Azure Machine Learning datastore is a *reference* to an *existing* storage account on Azure. The benefits of creating and using a datastore are:

+1. A common and easy-to-use API to interact with different storage types (Blob/Files/ADLS).

+1. Easier to discover useful datastores when working as a team.

+1. When using credential-based access (service principal/SAS/key), the connection information is secured so you don't have to code it in your scripts.

+When you create a datastore with an existing storage account on Azure, you have the choice between two different authentication methods:

+- **Credential-based** - authenticate access to the data using a service principal, shared access signature (SAS) token or account key. These credentials can be accessed by users who have *Reader* access to the workspace.

+- **Identity-based** - authenticate access to the data using your Azure Active Directory identity or managed identity.

+The table below summarizes which cloud-based storage services in Azure can be created as an Azure Machine Learning datastore and what authentication type can be used to access them.

+> [!NOTE]

+> The URI format to refer to a file/folder/mltable on a datastore is:

+> `azureml://datastores/<name>/paths/<path>`

+## MLTable

+`mltable` is a way to abstract the schema definition for tabular data so that it is easier for consumers of the data to materialize the table into a Pandas/Dask/Spark dataframe.

+> [!TIP]

+> The ideal scenarios to use `mltable` are:

+> - The schema of your data is complex and/or changes frequently.

+> - You only need a subset of data (for example: a sample of rows or files, specific columns, etc).

+> - AutoML jobs requiring tabular data.

+>

+> If your scenario does not fit the above then it is likely that URIs are a more suitable type.

+### A motivating example

+Imagine a scenario where you have many text files in a folder:

+```text

+Γö£ΓöÇΓöÇ my_data

+Γöé Γö£ΓöÇΓöÇ file1.txt

+Γöé Γö£ΓöÇΓöÇ file1_use_this.txt

+Γöé Γö£ΓöÇΓöÇ file2.txt

+Γöé Γö£ΓöÇΓöÇ file2_use_this.txt

+.

+.

+.

+Γöé Γö£ΓöÇΓöÇ file1000.txt

+Γöé Γö£ΓöÇΓöÇ file1000_use_this.txt

+```

+Each text file has the following structure:

+```text

+store_location date zip_code amount x y z noise_col1 noise_col2

+Seattle 20/04/2022 12324 123.4 true false true blah blah

+.

+.

+.

+London 20/04/2022 XX358YY 156 true true true blah blah

+```

+Some important features of this data are:

+- The data of interest is only in files that have the following suffix: `_use_this.txt` and other file names that don't match should be ignored.

+- The date should be represented as a date and not a string.

+- The x, y, z columns are booleans, not strings.

+- The store location is an index that is useful for generating subsets of data.

+- The file is encoded in `ascii` format.

+- Every file in the folder contains the same header.

+- The first million records for zip_code are numeric but later on you can see they're alphanumeric.

+- There are some dummy (noisy) columns in the data that aren't useful for machine learning.

+You could materialize the above text files into a dataframe using Pandas and a URI:

+import glob

+import datetime

+import os

+import argparse

+import pandas as pd

+parser = argparse.ArgumentParser()

+parser.add_argument("--input_folder", type=str)

+args = parser.parse_args()

+path = os.path.join(args.input_folder, "*_use_this.txt")

+files = glob.glob(path)

+# create empty list

+dfl = []

+# dict of column types

+col_types = {

+ "zip": str,

+ "date": datetime.date,

+ "x": bool,

+ "y": bool,

+ "z": bool

+}

+# enumerate files into a list of dfs

+for f in files:

+ csv = pd.read_table(

+ path=f,

+ delimiter=" ",

+ header=0,

+ usecols=["store_location", "zip_code", "date", "amount", "x", "y", "z"],

+ dtype=col_types,

+ encoding='ascii'

+ )

+ dfl.append(csv)

+# concatenate the list of dataframes

+df = pd.concat(dfl)

+# set the index column

+df.index_columns("store_location")

+```

+However, it will be the responsibility of the *consumer* of the data asset to parse the schema into a dataframe. In the scenario defined above, that means the consumers will need to independently ascertain the Python code to materialize the data into a dataframe.

+Passing responsibility to the consumer of the data asset will cause problems when:

+- **The schema changes (for example, a column name changes):** All consumers of the data must update their Python code independently. Other examples can be type changes, columns being added/removed, encoding change, etc.

+- **The data size increases** - If the data gets too large for Pandas to process, then all the consumers of the data need to switch to a more scalable library (PySpark/Dask).

+Under the above two conditions, `mltable` can help because it enables the creator of the data asset to define the schema in a single file and the consumers can materialize the data into a dataframe easily without needing to write Python code to parse the schema. For the above example, the creator of the data asset defines an MLTable file **in the same directory** as the data:

+```text

+Γö£ΓöÇΓöÇ my_data

+Γöé Γö£ΓöÇΓöÇ MLTable

+Γöé Γö£ΓöÇΓöÇ file1.txt

+Γöé Γö£ΓöÇΓöÇ file1_use_this.txt

+.

+.

+.

+```

+The MLTable file has the following definition that specifies how the data should be processed into a dataframe:

+```yaml

+type: mltable

+paths:

+ - pattern: ./*_use_this.txt

+traits:

+ - index_columns: store_location

+transformations:

+ - read_delimited:

+ encoding: ascii

+ header: all_files_have_same_headers

+ delimiter: " "

+ - keep_columns: ["store_location", "zip_code", "date", "amount", "x", "y", "z"]

+ - convert_column_types:

+ - columns: ["x", "y", "z"]

+ to_type: boolean

+ - columns: "date"

+ to_type: datetime

+```

+The consumers can read the data into dataframe using three lines of Python code:

+```python

+import mltable

+tbl = mltable.load("./my_data")

+df = tbl.to_pandas_dataframe()

+If the schema of the data changes, then it can be updated in a single place (the MLTable file) rather than having to make code changes in multiple places.

+Just like `uri_file` and `uri_folder`, you can create a data asset with `mltable` types.

+- [Install and set up the CLI (v2)](how-to-configure-cli.md#install-and-set-up-the-cli-v2)

+- [Create datastores](how-to-datastore.md#create-datastores)

+- [Create data assets](how-to-create-register-data-assets.md#create-data-assets)

+- [Read and write data in a job](how-to-read-write-data-v2.md#read-and-write-data-in-a-job)

+- [Data administration](how-to-administrate-data-authentication.md#data-administration)

+The following are well-known ports used by services listed in this article. If a port range is used in this article and isn't listed in this section, it's specific to the service and may not have published information on what it's used for:

+ | **pypi.org** | Used to list dependencies from the default index, if any, and the index isn't overwritten by user settings. If the index is overwritten, you must also allow **\*.pythonhosted.org**. |

+### Kubernetes Compute

+[Kubernetes Cluster](./how-to-attach-kubernetes-anywhere.md) running behind an outbound proxy server or firewall needs extra network configuration. Configure the [Azure Arc network requirements](../azure-arc/kubernetes/quickstart-connect-cluster.md?tabs=azure-cli#meet-network-requirements) needed by Azure Arc agents. The following outbound URLs are also required for Azure Machine Learning,

+| Outbound Endpoint| Port | Description|Training |Inference |

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

+| __\*.kusto.windows.net__<br>__\*.table.core.windows.net__<br>__\*.queue.core.windows.net__ | https:443 | Required to upload system logs to Kusto. |**&check;**|**&check;**|

+| __\*.azurecr.io__ | https:443 | Azure container registry, required to pull docker images used for machine learning workloads.|**&check;**|**&check;**|

+| __\*.blob.core.windows.net__ | https:443 | Azure blob storage, required to fetch machine learning project scripts,data or models, and upload job logs/outputs.|**&check;**|**&check;**|

+| __\*.workspace.\<region\>.api.azureml.ms__<br>__\<region\>.experiments.azureml.net__<br>__\<region\>.api.azureml.ms__ | https:443 | Azure mahince learning service API.|**&check;**|**&check;**|

+| __pypi.org__ | https:443 | Python package index, to install pip packages used for training job environment initialization.|**&check;**|N/A|

+| __archive.ubuntu.com__<br>__security.ubuntu.com__<br>__ppa.launchpad.net__ | http:80 | Required to download the necessary security patches. |**&check;**|N/A|

+> [!NOTE]

+> `<region>` is the lowcase full spelling of Azure Region, for example, eastus, southeastasia.

+The guidance in this section is generic, as each firewall has its own terminology and specific configurations. If you have questions, check the documentation for the firewall you're using.

+| **pypi.org** | Used to list dependencies from the default index, if any, and the index isn't overwritten by user settings. If the index is overwritten, you must also allow **\*.pythonhosted.org**. |

+# Data administration

+> If you need to access data from outside Azure Machine Learning, such as using Azure Storage Explorer, *user* identity is probably what is used. Consult the documentation for the tool or service you are using for specific information. For more information on how Azure Machine Learning works with data, see [Identity-based data access to storage services on Azure](how-to-identity-based-data-access.md).

+__To use Azure RBAC__, follow the steps in the [Datastore: Azure Storage Account](how-to-enable-studio-virtual-network.md#datastore-azure-storage-account) section of the 'Use Azure Machine Learning studio in an Azure Virtual Network' article. Data Lake Storage Gen2 is based on Azure Storage, so the same steps apply when using Azure RBAC.

+__To use ACLs__, the managed identity of the workspace can be assigned access just like any other security principal. For more information, see [Access control lists on files and directories](../storage/blobs/data-lake-storage-access-control.md#access-control-lists-on-files-and-directories).

+ Title: Configure Kubernetes cluster (Preview)

+# Configure Kubernetes cluster for Azure Machine Learning (Preview)

+Using Kubernetes with Azure Machine Learning enables you to build, train, and deploy models in any infrastructure on-premises and across multi-cloud. With an AzureML extension deployment on Kubernetes, you can instantly onboard teams of ML professionals with AzureML service capabilities. These services include full machine learning lifecycle and automation with MLOps in hybrid cloud and multi-cloud.

+You can easily bring AzureML capabilities to your Kubernetes cluster from cloud or on-premises by deploying AzureML extension.

+- For Azure Kubernetes Service (AKS) in Azure, deploy AzureML extension to the AKS directly. For more information, see [Deploy and manage cluster extensions for Azure Kubernetes Service (AKS)](../aks/cluster-extensions.md).

+- For Kubernetes clusters on-premises or from other cloud providers, connect the cluster with Azure Arc first, then deploy AzureML extension to Azure Arc-enabled Kubernetes. For more information, see [Azure Arc-enabled Kubernetes](../azure-arc/kubernetes/overview.md).

+* [Deploy AzureML extension to Kubernetes cluster](#deploy-azureml-extension)

+* [Attach a Kubernetes cluster to AzureML workspace](#attach-a-kubernetes-cluster-to-an-azureml-workspace)

+## Why use Azure Machine Learning Kubernetes?

+AzureML Kubernetes is customer fully configured and managed compute for machine learning. It can be used as both [training compute target](./concept-compute-target.md#train) and [inference compute target](./concept-compute-target.md#deploy). It provides the following benefits:

+- Harness existing heterogeneous or homogeneous Kubernetes cluster, with CPUs or GPUs.

+- Share the same Kubernetes cluster in multiple AzureML Workspaces across region.

+- Use the same Kubernetes cluster for different machine learning purposes, including model training, batch scoring, and real-time inference.

+- Secure network communication between the cluster and cloud via Azure Private Link and Private Endpoint.

+- Isolate team projects and machine learning workloads with Kubernetes node selector and namespace.

+- [Target certain types of compute nodes and CPU/Memory/GPU resource allocation for training and inference workloads](./reference-kubernetes.md#create-and-use-instance-types-for-efficient-compute-resource-usage).

+- [Connect with custom data sources for machine learning workloads using Kubernetes PV and PVC ](./reference-kubernetes.md#azureml-jobs-connect-with-on-premises-data-storage).

+* A running Kubernetes cluster in [supported version and region](./reference-kubernetes.md#supported-kubernetes-version-and-region). **We recommend your cluster has a minimum of 4 vCPU cores and 8GB memory, around 2 vCPU cores and 3GB memory will be used by Azure Arc and AzureML extension components**.

+* Other than Azure Kubernetes Services (AKS) cluster in Azure, connect your Kubernetes cluster to Azure Arc. Follow instructions in [connect existing Kubernetes cluster to Azure Arc](../azure-arc/kubernetes/quickstart-connect-cluster.md).

+ * If you have an AKS cluster in Azure, **Azure Arc connection is not required and not recommended**.

+

+ * If you have Azure RedHat OpenShift Service (ARO) cluster or OpenShift Container Platform (OCP) cluster, follow another prerequisite step [here](./reference-kubernetes.md#prerequisites-for-aro-or-ocp-clusters) before AzureML extension deployment.

+* Cluster running behind an outbound proxy server or firewall needs additional network configurations. Fulfill the [network requirements](./how-to-access-azureml-behind-firewall.md#kubernetes-compute)

+* Install or upgrade Azure CLI to version >=2.16.0

+* Install the Azure CLI extension ```k8s-extension``` (version>=1.2.3) by running ```az extension add --name k8s-extension```

+AzureML extension consists of a set of system components deployed to your Kubernetes cluster in `azureml` namespace, so you can enable your cluster to run an AzureML workload - model training jobs or model endpoints. You can use an Azure CLI command ```k8s-extension create``` to deploy AzureML extension. General available (GA) version of AzureML extension >= 1.1.1

+For a detailed list of AzureML extension system components, see [AzureML extension components](./reference-kubernetes.md#azureml-extension-components).

+ * Type of workload to enable for your cluster. ```enableTraining``` and ```enableInference``` config settings are your convenient choices here; `enableTraining` will enable **training** and **batch scoring** workload, `enableInference` will enable **real-time inference** workload.

+ * For inference workload support, you would also want to consider using **HTTPS** to restrict access to model endpoints and secure the data that clients submit. For this purpose, you would need to specify either ```sslSecret``` config setting or combination of ```sslKeyPemFile``` and ```sslCertPemFile``` config settings. By default, AzureML extension deployment expects **HTTPS** support required, and you would need to provide above config setting. For development or test purposes, **HTTP** support is conveniently supported through config setting ```allowInsecureConnections=True```.

+For a complete list of configuration settings available to choose at AzureML deployment time, see [Review AzureML extension config settings](#review-azureml-extension-configuration-settings)

+## Deploy AzureML extension

+### [CLI](#tab/deploy-extension-with-cli)

+To deploy AzureML extension with CLI, use `az k8s-extension create` command passing in values for the mandatory parameters.

+We list 4 typical extension deployment scenarios for reference. To deploy extension for your production usage, please carefully read the complete list of [configuration settings](#review-azureml-extension-configuration-settings).

+- **Use AKS in Azure for a quick Proof of Concept, both training and inference workloads support**

+ Ensure you have fulfilled [prerequisites](#prerequisites). For AzureML extension deployment on AKS, make sure to specify ```managedClusters``` value for ```--cluster-type``` parameter. Run the following Azure CLI command to deploy AzureML extension:

+ ```azurecli

+ az k8s-extension create --name <extension-name> --extension-type Microsoft.AzureML.Kubernetes --config enableTraining=True enableInference=True inferenceRouterServiceType=LoadBalancer allowInsecureConnections=True inferenceLoadBalancerHA=False --cluster-type managedClusters --cluster-name <your-AKS-cluster-name> --resource-group <your-RG-name> --scope cluster

+ ```

+- **Use Kubernetes at your lab for a quick Proof of Concept, training workload support only**

+ Ensure you have fulfilled [prerequisites](#prerequisites). For AzureML extension deployment on Azure Arc connected cluster, you would need to specify ```connectedClusters``` value for ```--cluster-type``` parameter. Run following simple Azure CLI command to deploy AzureML extension:

+ ```azurecli

+ az k8s-extension create --name <extension-name> --extension-type Microsoft.AzureML.Kubernetes --config enableTraining=True --cluster-type connectedClusters --cluster-name <your-connected-cluster-name> --resource-group <your-RG-name> --scope cluster

+ ```

+- **Enable an AKS cluster in Azure for production training and inference workload**

+ Ensure you have fulfilled [prerequisites](#prerequisites). For AzureML extension deployment on AKS, make sure to specify ```managedClusters``` value for ```--cluster-type``` parameter. Assuming your cluster has more than 3 nodes, and you will use an Azure public load balancer and HTTPS for inference workload support, run following Azure CLI command to deploy AzureML extension:

+ ```azurecli

+ az k8s-extension create --name <extension-name> --extension-type Microsoft.AzureML.Kubernetes --config enableTraining=True enableInference=True inferenceRouterServiceType=LoadBalancer sslCname=<ssl cname> --config-protected sslCertPemFile=<file-path-to-cert-PEM> sslKeyPemFile=<file-path-to-cert-KEY> --cluster-type managedClusters --cluster-name <your-AKS-cluster-name> --resource-group <your-RG-name> --scope cluster

+ ```

+- **Enable an Azure Arc connected cluster anywhere for production training and inference workload using NVIDIA GPUs**

+ Ensure you have fulfilled [prerequisites](#prerequisites). For AzureML extension deployment on Azure Arc connected cluster, make sure to specify ```connectedClusters``` value for ```--cluster-type``` parameter. Assuming your cluster has more than 3 nodes, you will use a NodePort service type and HTTPS for inference workload support, run following Azure CLI command to deploy AzureML extension:

+ ```azurecli

+ az k8s-extension create --name <extension-name> --extension-type Microsoft.AzureML.Kubernetes --config enableTraining=True enableInference=True inferenceRouterServiceType=NodePort sslCname=<ssl cname> installNvidiaDevicePlugin=True installDcgmExporter=True --config-protected sslCertPemFile=<file-path-to-cert-PEM> sslKeyPemFile=<file-path-to-cert-KEY> --cluster-type connectedClusters --cluster-name <your-connected-cluster-name> --resource-group <your-RG-name> --scope cluster

+ ```

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

+The UI experience to deploy extension is only available for **Azure Arc-enabled Kubernetes**. If you have an AKS cluster without Azure Arc connected, you need to use CLI to deploy AzureML extension.

+1. In the [Azure portal](https://ms.portal.azure.com/#home), navigate to **Kubernetes - Azure Arc** and select your cluster.

+1. Select **Extensions** (under **Settings**), and then select **+ Add**.

+ :::image type="content" source="media/how-to-attach-arc-kubernetes/deploy-extension-from-ui.png" alt-text="Screenshot of adding new extension to the Arc-enabled Kubernetes cluster from Azure portal.":::

+1. From the list of available extensions, select **Azure Machine Learning extension** to deploy the latest version of the extension.

+ :::image type="content" source="media/how-to-attach-arc-kubernetes/deploy-extension-from-ui-extension-list.png" alt-text="Screenshot of selecting AzureML extension from Azure portal.":::

+1. Follow the prompts to deploy the extension. You can customize the installation by configuring the installtion in the tab of **Basics**, **Configurations** and **Advanced**. For a detailed list of AzureML extension configuration settings, see [AzureML extension configuration settings](#review-azureml-extension-configuration-settings).

+ :::image type="content" source="media/how-to-attach-arc-kubernetes/deploy-extension-from-ui-settings.png" alt-text="Screenshot of configuring AzureML extension settings from Azure portal.":::

+1. On the **Review + create** tab, select **Create**.

+

+ :::image type="content" source="media/how-to-attach-arc-kubernetes/deploy-extension-from-ui-create.png" alt-text="Screenshot of deploying new extension to the Arc-enabled Kubernetes cluster from Azure portal.":::

+1. After the deployment completes, you are able to see the AzureML extension in **Extension** page. If the extension installation succeeds, you can see **Installed** for the **Install status**.

+ :::image type="content" source="media/how-to-attach-arc-kubernetes/deploy-extension-from-ui-extension-detail.png" alt-text="Screenshot of installed AzureML extensions listing in Azure portal.":::

+ az k8s-extension show --name <extension-name> --cluster-type connectedClusters --cluster-name <your-connected-cluster-name> --resource-group <resource-group>

+1. In the response, look for "name" and "provisioningState": "Succeeded". Note it might show "provisioningState": "Pending" for the first few minutes.

+### Manage AzureML extension

+Update, list, show and delete an AzureML extension.

+- For AKS cluster without Azure Arc connected, refer to [Usage of AKS extensions](../aks/cluster-extensions.md#usage-of-cluster-extensions).

+- For Azure Arc-enabled Kubernetes, refer to [Usage of cluster extensions](../azure-arc/kubernetes/extensions.md#usage-of-cluster-extensions).

+## Review AzureML extension configuration settings

+For AzureML extension deployment configurations, use ```--config``` or ```--config-protected``` to specify list of ```key=value``` pairs. Following is the list of configuration settings available to be used for different AzureML extension deployment scenario ns.

+|Configuration Setting Key Name |Description |Training |Inference |Training and Inference

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

+ |```enableTraining``` |```True``` or ```False```, default ```False```. **Must** be set to ```True``` for AzureML extension deployment with Machine Learning model training support. | **&check;**| N/A | **&check;** |

+ | ```enableInference``` |```True``` or ```False```, default ```False```. **Must** be set to ```True``` for AzureML extension deployment with Machine Learning inference support. |N/A| **&check;** | **&check;** |

+ | ```allowInsecureConnections``` |```True``` or ```False```, default `False`. **Must** be set to ```True``` to use inference HTTP endpoints for development or test purposes. |N/A| Optional | Optional |

+ | ```inferenceRouterServiceType``` |```loadBalancer```, ```nodePort``` or ```clusterIP```. **Required** if ```enableInference=True```. | N/A| **&check;** | **&check;** |

+ | ```internalLoadBalancerProvider``` | This config is only applicable for Azure Kubernetes Service(AKS) cluster now. Set to ```azure``` to allow the inference router using internal load balancer. | N/A| Optional | Optional |

+ |```sslSecret```| The name of Kubernetes secret in `azureml` namespace to store `cert.pem` (PEM-encoded SSL cert) and `key.pem` (PEM-encoded SSL key), required for inference HTTPS endpoint support, when ``allowInsecureConnections`` is set to False. You can find a sample YAML definition of sslSecret [here](./reference-kubernetes.md#sample-yaml-definition-of-kubernetes-secret-for-tlsssl). Use this config or combination of `sslCertPemFile` and `sslKeyPemFile` protected config settings. |N/A| Optional | Optional |

+ |```sslCname``` |A SSL CName used by inference HTTPS endpoint. **Required** if ```allowInsecureConnections=True``` | N/A | Optional | Optional|

+ | ```inferenceRouterHA``` |```True``` or ```False```, default ```True```. By default, AzureML extension will deploy 3 ingress controller replicas for high availability, which requires at least 3 workers in a cluster. Set to ```False``` if your cluster has fewer than 3 workers, in this case only one ingress controller is deployed. | N/A| Optional | Optional |

+ |```nodeSelector``` | By default, the deployed kubernetes resources are randomly deployed to 1 or more nodes of the cluster, and daemonset resources are deployed to ALL nodes. If you want to restrict the extension deployment to specific nodes with label `key1=value1` and `key2=value2`, use `nodeSelector.key1=value1`, `nodeSelector.key2=value2` correspondingly. | Optional| Optional | Optional |

+ |```installNvidiaDevicePlugin``` | ```True``` or ```False```, default ```False```. [NVIDIA Device Plugin](https://github.com/NVIDIA/k8s-device-plugin#nvidia-device-plugin-for-kubernetes) is required for ML workloads on NVIDIA GPU hardware. By default, AzureML extension deployment will not install NVIDIA Device Plugin regardless Kubernetes cluster has GPU hardware or not. User can specify this setting to ```True```, to install it, but make sure to fulfill [Prerequisites](https://github.com/NVIDIA/k8s-device-plugin#prerequisites). | Optional |Optional |Optional |

+ |```installPromOp```|```True``` or ```False```, default ```True```. AzureML extension needs prometheus operator to manage prometheus. Set to ```False``` to reuse existing prometheus operator. Compatible [kube-prometheus-stack](https://github.com/prometheus-community/helm-charts/blob/main/charts/kube-prometheus-stack/README.md) helm chart versions are from 9.3.4 to 30.0.1.| Optional| Optional | Optional |

+ |```installVolcano```| ```True``` or ```False```, default ```True```. AzureML extension needs volcano scheduler to schedule the job. Set to ```False``` to reuse existing volcano scheduler. Supported volcano scheduler versions are 1.4, 1.5. | Optional| N/A | Optional |

+ |```installDcgmExporter``` |```True``` or ```False```, default ```False```. Dcgm-exporter can expose GPU metrics for AzureML workloads, which can be monitored in Azure portal. Set ```installDcgmExporter``` to ```True``` to install dcgm-exporter. But if you want to utilize your own dcgm-exporter, refer to [DCGM exporter](https://github.com/Azure/AML-Kubernetes/blob/master/docs/troubleshooting.md#dcgm) |Optional |Optional |Optional |

+ |Configuration Protected Setting Key Name |Description |Training |Inference |Training and Inference

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

+ | ```sslCertPemFile```, ```sslKeyPemFile``` |Path to SSL certificate and key file (PEM-encoded), required for AzureML extension deployment with inference HTTPS endpoint support, when ``allowInsecureConnections`` is set to False. | N/A| Optional | Optional |

+

+## Attach a Kubernetes cluster to an AzureML workspace

+Attach an AKS or Arc-enabled Kubernetes cluster with AzureML extension installed to AzureML workspace. The same cluster can be attached and shared by multiple AzureMl Workspaces across region.

+### Prerequisite

+Azure Machine Learning workspace defaults to having a system-assigned managed identity to access Azure ML resources. The steps are completed if the system assigned default setting is on.

+Otherwise, if a user-assigned managed identity is specified in Azure Machine Learning workspace creation, the following role assignments need to be granted to the managed identity manually before attaching the compute.

+|Azure resource name |Role to be assigned|Description|

+|--|--|--|

+|Azure Relay|Azure Relay Owner|Only applicable for Arc-enabled Kubernetes cluster. Azure Relay isn't created for AKS cluster without Arc connected.|

+|Azure Arc-enabled Kubernetes|Reader|Applicable for both Arc-enabled Kubernetes cluster and AKS cluster.|

+Azure Relay resource is created during the extension deployment under the same Resource Group as the Arc-enabled Kubernetes cluster.

+The following commands show how to attach an AKS and Azure Arc-enabled Kubernetes cluster, and use it as a compute target with managed identity enabled.

+az ml compute attach --resource-group <resource-group-name> --workspace-name <workspace-name> --type Kubernetes --name k8s-compute --resource-id "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ContainerService/managedclusters/<cluster-name>" --identity-type SystemAssigned --namespace <Kubernetes namespace to run AzureML workloads> --no-wait

+az ml compute attach --resource-group <resource-group-name> --workspace-name <workspace-name> --type Kubernetes --name amlarc-compute --resource-id "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Kubernetes/connectedClusters/<cluster-name>" --user-assigned-identities "subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>" --no-wait

+Set the `--type` argument to `Kubernetes`. Use the `identity_type` argument to enable `SystemAssigned` or `UserAssigned` managed identities.