Merge pull request #232999 from laujan/81986-update-immersive-reader

update immersive reader and copy model

Author: Stacyrch140

articles/applied-ai-services/immersive-reader/how-to-create-immersive-reader.md

@@ -1,28 +1,44 @@
 ---
 title: "Create an Immersive Reader Resource"
 titleSuffix: Azure Applied AI Services
-description: This article will show you how to create a new Immersive Reader resource with a custom subdomain and then configure Azure AD in your Azure tenant. 
+description: This article shows you how to create a new Immersive Reader resource with a custom subdomain and then configure Azure AD in your Azure tenant.
 services: cognitive-services
 author: rwallerms
 manager: nitinme
-
 ms.service: applied-ai-services
 ms.subservice: immersive-reader
 ms.custom: devx-track-azurecli
 ms.topic: how-to
-ms.date: 7/1/2022
+ms.date: 03/31/2023
 ms.author: rwaller
 ---
 
 # Create an Immersive Reader resource and configure Azure Active Directory authentication
 
-In this article, we provide a script that will create an Immersive Reader resource and configure Azure Active Directory (Azure AD) authentication. Each time an Immersive Reader resource is created, whether with this script or in the portal, it must also be configured with Azure AD permissions. This script will help you with that.
+In this article, we provide a script that creates an Immersive Reader resource and configure Azure Active Directory (Azure AD) authentication. Each time an Immersive Reader resource is created, whether with this script or in the portal, it must also be configured with Azure AD permissions.
 
 The script is designed to create and configure all the necessary Immersive Reader and Azure AD resources for you all in one step. However, you can also just configure Azure AD authentication for an existing Immersive Reader resource, if for instance, you happen to have already created one in the Azure portal.
 
 For some customers, it may be necessary to create multiple Immersive Reader resources, for development vs. production, or perhaps for multiple different regions your service is deployed in. For those cases, you can come back and use the script multiple times to create different Immersive Reader resources and get them configured with the Azure AD permissions.
 
-The script is designed to be flexible. It will first look for existing Immersive Reader and Azure AD resources in your subscription, and create them only as necessary if they don't already exist. If it's your first time creating an Immersive Reader resource, the script will do everything you need. If you want to use it just to configure Azure AD for an existing Immersive Reader resource that was created in the portal, it will do that too. It can also be used to create and configure multiple Immersive Reader resources.
+The script is designed to be flexible. It first looks for existing Immersive Reader and Azure AD resources in your subscription, and creates them only as necessary if they don't already exist. If it's your first time creating an Immersive Reader resource, the script does everything you need. If you want to use it just to configure Azure AD for an existing Immersive Reader resource that was created in the portal, it does that too.
+It can also be used to create and configure multiple Immersive Reader resources.
+
+## Permissions
+
+The listed **Owner** of your Azure subscription has all the required permissions to create an Immersive Reader resource and configure Azure AD authentication.
+
+If you aren't an owner, the following scope-specific permissions are required:
+
+* **Contributor**. You need to have at least a Contributor role associated with the Azure subscription:
+
+   :::image type="content" source="media/contributor-role.png" alt-text="Screenshot of contributor built-in role description.":::
+
+* **Application Developer**. You need to have at least an Application Developer role associated in Azure AD:
+
+  :::image type="content" source="media/application-developer-role.png" alt-text="{alt-text}":::
+
+For more information, _see_ [Azure AD built-in roles](../../active-directory/roles/permissions-reference.md#application-developer)
 
 ## Set up PowerShell environment
 
@@ -101,7 +117,7 @@ The script is designed to be flexible. It will first look for existing Immersive
                 throw "Error: Failed to create Azure Active Directory application client secret"
             }
             Write-Host "Azure Active Directory application client secret created successfully."
-            
+
             Write-Host "NOTE: To manage your Active Directory application client secrets after this Immersive Reader Resource has been created please visit https://portal.azure.com and go to Home -> Azure Active Directory -> App Registrations -> (your app) '$AADAppDisplayName' -> Certificates and Secrets blade -> Client Secrets section" -ForegroundColor Yellow
         }
 
@@ -143,7 +159,7 @@ The script is designed to be flexible. It will first look for existing Immersive
         Write-Host "Save the following JSON object to a text file for future reference."
         Write-Host "*****"
         if($clientSecret -ne $null) {
-            
+
             Write-Host "This function has created a client secret (password) for you. This secret is used when calling Azure Active Directory to fetch access tokens."
             Write-Host "This is the only time you will ever see the client secret for your Azure Active Directory application, so save it now." -ForegroundColor Yellow
         }
@@ -155,13 +171,13 @@ The script is designed to be flexible. It will first look for existing Immersive
     }
     ```
 
-1. Run the function `Create-ImmersiveReaderResource`, supplying the '<PARAMETER_VALUES>' placeholders below with your own values as appropriate.
+1. Run the function `Create-ImmersiveReaderResource`, supplying the '<PARAMETER_VALUES>' placeholders with your own values as appropriate.
 
     ```azurepowershell-interactive
     Create-ImmersiveReaderResource -SubscriptionName '<SUBSCRIPTION_NAME>' -ResourceName '<RESOURCE_NAME>' -ResourceSubdomain '<RESOURCE_SUBDOMAIN>' -ResourceSKU '<RESOURCE_SKU>' -ResourceLocation '<RESOURCE_LOCATION>' -ResourceGroupName '<RESOURCE_GROUP_NAME>' -ResourceGroupLocation '<RESOURCE_GROUP_LOCATION>' -AADAppDisplayName '<AAD_APP_DISPLAY_NAME>' -AADAppIdentifierUri '<AAD_APP_IDENTIFIER_URI>' -AADAppClientSecretExpiration '<AAD_APP_CLIENT_SECRET_EXPIRATION>'
     ```
 
-    The full command will look something like the following. Here we have put each parameter on its own line for clarity, so you can see the whole command. __Do not copy or use this command as-is.__ Copy and use the command above with your own values. This example has dummy values for the '<PARAMETER_VALUES>' above. Yours will be different, as you will come up with your own names for these values.
+    The full command looks something like the following. Here we have put each parameter on its own line for clarity, so you can see the whole command. __Do not copy or use this command as-is.__ Copy and use the command with your own values. This example has dummy values for the '<PARAMETER_VALUES>'. Yours may be different, as you come up with your own names for these values.
 
     ```
     Create-ImmersiveReaderResource
@@ -180,15 +196,15 @@ The script is designed to be flexible. It will first look for existing Immersive
     | Parameter | Comments |
     | --- | --- |
     | SubscriptionName |Name of the Azure subscription to use for your Immersive Reader resource. You must have a subscription in order to create a resource. |
-    | ResourceName |  Must be alphanumeric, and may contain '-', as long as the '-' is not the first or last character. Length may not exceed 63 characters.|
-    | ResourceSubdomain |A custom subdomain is needed for your Immersive Reader resource. The subdomain is used by the SDK when calling the Immersive Reader service to launch the Reader. The subdomain must be globally unique. The subdomain must be alphanumeric, and may contain '-', as long as the '-' is not the first or last character. Length may not exceed 63 characters. This parameter is optional if the resource already exists. |
+    | ResourceName |  Must be alphanumeric, and may contain '-', as long as the '-' isn't the first or last character. Length may not exceed 63 characters.|
+    | ResourceSubdomain |A custom subdomain is needed for your Immersive Reader resource. The subdomain is used by the SDK when calling the Immersive Reader service to launch the Reader. The subdomain must be globally unique. The subdomain must be alphanumeric, and may contain '-', as long as the '-' isn't the first or last character. Length may not exceed 63 characters. This parameter is optional if the resource already exists. |
     | ResourceSKU |Options: `S0` (Standard tier) or `S1` (Education/Nonprofit organizations). Visit our [Cognitive Services pricing page](https://azure.microsoft.com/pricing/details/cognitive-services/immersive-reader/) to learn more about each available SKU. This parameter is optional if the resource already exists. |
     | ResourceLocation |Options: `australiaeast`, `brazilsouth`, `canadacentral`, `centralindia`, `centralus`, `eastasia`, `eastus`, `eastus2`, `francecentral`, `germanywestcentral`, `japaneast`, `japanwest`, `jioindiawest`, `koreacentral`, `northcentralus`, `northeurope`, `norwayeast`, `southafricanorth`, `southcentralus`, `southeastasia`, `swedencentral`, `switzerlandnorth`, `switzerlandwest`, `uaenorth`, `uksouth`, `westcentralus`, `westeurope`, `westus`, `westus2`, `westus3`. This parameter is optional if the resource already exists. |
-    | ResourceGroupName |Resources are created in resource groups within subscriptions. Supply the name of an existing resource group. If the resource group does not already exist, a new one with this name will be created. |
+    | ResourceGroupName |Resources are created in resource groups within subscriptions. Supply the name of an existing resource group. If the resource group doesn't already exist, a new one with this name is created. |
     | ResourceGroupLocation |If your resource group doesn't exist, you need to supply a location in which to create the group. To find a list of locations, run `az account list-locations`. Use the *name* property (without spaces) of the returned result. This parameter is optional if your resource group already exists. |
-    | AADAppDisplayName |The Azure Active Directory application display name. If an existing Azure AD application is not found, a new one with this name will be created. This parameter is optional if the Azure AD application already exists. |
-    | AADAppIdentifierUri |The URI for the Azure AD application. If an existing Azure AD application is not found, a new one with this URI will be created. For example, `api://MyOrganizationImmersiveReaderAADApp`. Here we are using the default Azure AD URI scheme prefix of `api://` for compatibility with the [Azure AD policy of using verified domains](../../active-directory/develop/reference-breaking-changes.md#appid-uri-in-single-tenant-applications-will-require-use-of-default-scheme-or-verified-domains). |
-    | AADAppClientSecretExpiration |The date or datetime after which your AAD Application Client Secret (password) will expire (e.g. '2020-12-31T11:59:59+00:00' or '2020-12-31'). This function will create a client secret for you. To manage Azure AD application client secrets after you've created this resource, please visit https://portal.azure.com and go to Home -> Azure Active Directory -> App Registrations -> (your app) `[AADAppDisplayName]` -> Certificates and Secrets blade -> Client Secrets section (as shown in the "Manage your Azure AD application secrets" screenshot below).|
+    | AADAppDisplayName |The Azure Active Directory application display name. If an existing Azure AD application isn't found, a new one with this name is created. This parameter is optional if the Azure AD application already exists. |
+    | AADAppIdentifierUri |The URI for the Azure AD application. If an existing Azure AD application isn't found, a new one with this URI is created. For example, `api://MyOrganizationImmersiveReaderAADApp`. Here we're using the default Azure AD URI scheme prefix of `api://` for compatibility with the [Azure AD policy of using verified domains](../../active-directory/develop/reference-breaking-changes.md#appid-uri-in-single-tenant-applications-will-require-use-of-default-scheme-or-verified-domains). |
+    | AADAppClientSecretExpiration |The date or datetime after which your Azure AD Application Client Secret (password) will expire (for example, '2020-12-31T11:59:59+00:00' or '2020-12-31'). This function creates a client secret for you. To manage Azure AD application client secrets after you've created this resource, visit https://portal.azure.com and go to Home -> Azure Active Directory -> App Registrations -> (your app) `[AADAppDisplayName]` -> Certificates and Secrets section -> Client Secrets section (as shown in the "Manage your Azure AD application secrets" screenshot).|
 
     Manage your Azure AD application secrets
 

articles/applied-ai-services/immersive-reader/media/application-developer-role.png

@@ -30,29 +30,24 @@ Copying a model to other workspaces enables model lifecycle management (for exam
 
 1. Fill out the target details.
 
-1. Select **Copy model**.
-
-1. A notification panel shows the copy progress. The process should complete fairly quickly:
-
-1. Complete the **workspace**, **project**, and **model name** sections of the copy model dialog window:
+   :::image type="content" source="../media/how-to/copy-model-1.png" alt-text="Screenshot illustrating the copy model dialog window.":::
 
-      :::image type="content" source="../media/how-to/copy-model-1.png" alt-text="Screenshot illustrating the copy model dialog window.":::
-
-1. A **notifications** window displays the copy process status:
-
-      :::image type="content" source="../media/how-to/copy-model-2.png" alt-text="Screenshot illustrating notification that the copy model is in process.":::
+   > [!Note]
+      >
+      > A dropdown list displays the list of workspaces available to use. Otherwise, select **Create a new workspace**.
+      >
+      > If selected workspace contains a project for the same language pair, it can be selected from the Project dropdown list, otherwise, select **Create a new project** to create one.
 
-1. A **model details** window appears when the copy process is complete.
+1. Select **Copy model**.
 
-      :::image type="content" source="../media/how-to/copy-model-3.png" alt-text="Screenshot illustrating the copy complete dialog window.":::
+1. A notification panel shows the copy progress. The process should complete fairly quickly:
 
-      > [!Note]
-      >
-      > A dropdown list displays the list of workspaces available to use. Otherwise, click **Create a new workspace**.
-      > If selected workspace contains a project for the same language pair, it can be selected from the Project dropdown list, otherwise, click **Create a new project** to create one.
+   :::image type="content" source="../media/how-to/copy-model-2.png" alt-text="Screenshot illustrating notification that the copy model is in process.":::
 
 1. After **Copy model** completion, a copied model is available in the target workspace and ready to publish. A **Copied model** watermark is appended to the model name.
 
+   :::image type="content" source="../media/how-to/copy-model-3.png" alt-text="Screenshot illustrating the copy complete dialog window.":::
+
 ## Next steps
 
 > [!div class="nextstepaction"]