Creare una risorsa dello strumento di lettura immersiva e configurare l'autenticazione di Microsoft Entra
Questo articolo illustra come creare una risorsa dello strumento di lettura immersiva usando lo script fornito. Questo script configura anche l'autenticazione di Microsoft Entra. Ogni volta che si crea una risorsa dello Strumento di lettura immersiva, mediante questo script oppure nel portale, occorre anche configurarla con le autorizzazioni di Microsoft Entra.
Lo script crea e configura automaticamente tutte le risorse dello strumento di lettura immersiva e Microsoft Entra necessarie. Tuttavia, è anche possibile configurare l'autenticazione di Microsoft Entra per una risorsa dello strumento di lettura immersiva esistente, se ne è già stata creata una nel portale di Azure. Lo script cerca prima di tutto le risorse dello strumento di lettura immersiva e Microsoft Entra nella sottoscrizione e le crea solo se non esistono già.
Per alcuni clienti può essere necessario creare più risorse dello Strumento di lettura immersiva, per lo sviluppo anziché per la produzione o magari per le diverse aree in cui viene distribuito il servizio. In questi casi, è possibile utilizzare lo script più volte per creare più risorse dello Strumento di lettura immersiva e configurarle con le autorizzazioni di Microsoft Entra.
Autorizzazioni
Il Proprietario della sottoscrizione di Azure indicato dispone di tutte le autorizzazioni necessarie per creare una risorsa dello Strumento di lettura immersiva e configurare l'autenticazione di Microsoft Entra.
Se non si è proprietari, sono necessarie le autorizzazioni specifiche dell'ambito seguenti:
Collaboratore. È necessario avere almeno un ruolo Collaboratore associato alla sottoscrizione di Azure:
Sviluppatore di applicazioni. È necessario avere almeno un ruolo Sviluppatore di applicazioni associato in Microsoft Entra ID:
Per altre informazioni, vedere Ruoli predefiniti di Microsoft Entra.
Configurare le risorse di PowerShell
Per iniziare, aprire Azure Cloud Shell. Assicurarsi che Cloud Shell sia impostato su PowerShell, nell'elenco a discesa in alto a sinistra o digitando
pwsh.Copiare e incollare il frammento di codice seguente nella shell.
function Create-ImmersiveReaderResource( [Parameter(Mandatory=$true, Position=0)] [String] $SubscriptionName, [Parameter(Mandatory=$true)] [String] $ResourceName, [Parameter(Mandatory=$true)] [String] $ResourceSubdomain, [Parameter(Mandatory=$true)] [String] $ResourceSKU, [Parameter(Mandatory=$true)] [String] $ResourceLocation, [Parameter(Mandatory=$true)] [String] $ResourceGroupName, [Parameter(Mandatory=$true)] [String] $ResourceGroupLocation, [Parameter(Mandatory=$true)] [String] $AADAppDisplayName, [Parameter(Mandatory=$true)] [String] $AADAppIdentifierUri, [Parameter(Mandatory=$true)] [String] $AADAppClientSecretExpiration ) { $unused = '' if (-not [System.Uri]::TryCreate($AADAppIdentifierUri, [System.UriKind]::Absolute, [ref] $unused)) { throw "Error: AADAppIdentifierUri must be a valid URI" } Write-Host "Setting the active subscription to '$SubscriptionName'" $subscriptionExists = Get-AzSubscription -SubscriptionName $SubscriptionName if (-not $subscriptionExists) { throw "Error: Subscription does not exist" } az account set --subscription $SubscriptionName $resourceGroupExists = az group exists --name $ResourceGroupName if ($resourceGroupExists -eq "false") { Write-Host "Resource group does not exist. Creating resource group" $groupResult = az group create --name $ResourceGroupName --location $ResourceGroupLocation if (-not $groupResult) { throw "Error: Failed to create resource group" } Write-Host "Resource group created successfully" } # Create an Immersive Reader resource if it doesn't already exist $resourceId = az cognitiveservices account show --resource-group $ResourceGroupName --name $ResourceName --query "id" -o tsv if (-not $resourceId) { Write-Host "Creating the new Immersive Reader resource '$ResourceName' (SKU '$ResourceSKU') in '$ResourceLocation' with subdomain '$ResourceSubdomain'" $resourceId = az cognitiveservices account create ` --name $ResourceName ` --resource-group $ResourceGroupName ` --kind ImmersiveReader ` --sku $ResourceSKU ` --location $ResourceLocation ` --custom-domain $ResourceSubdomain ` --query "id" ` -o tsv if (-not $resourceId) { throw "Error: Failed to create Immersive Reader resource" } Write-Host "Immersive Reader resource created successfully" } # Create an Microsoft Entra app if it doesn't already exist $clientId = az ad app show --id $AADAppIdentifierUri --query "appId" -o tsv if (-not $clientId) { Write-Host "Creating new Microsoft Entra app" $clientId = az ad app create --display-name $AADAppDisplayName --identifier-uris $AADAppIdentifierUri --query "appId" -o tsv if (-not $clientId) { throw "Error: Failed to create Microsoft Entra application" } Write-Host "Microsoft Entra application created successfully." $clientSecret = az ad app credential reset --id $clientId --end-date "$AADAppClientSecretExpiration" --query "password" | % { $_.Trim('"') } if (-not $clientSecret) { throw "Error: Failed to create Microsoft Entra application client secret" } Write-Host "Microsoft Entra application client secret created successfully." Write-Host "NOTE: To manage your Microsoft Entra application client secrets after this Immersive Reader Resource has been created please visit https://portal.azure.com and go to Home -> Microsoft Entra ID -> App Registrations -> (your app) '$AADAppDisplayName' -> Certificates and Secrets blade -> Client Secrets section" -ForegroundColor Yellow } # Create a service principal if it doesn't already exist $principalId = az ad sp show --id $AADAppIdentifierUri --query "id" -o tsv if (-not $principalId) { Write-Host "Creating new service principal" az ad sp create --id $clientId | Out-Null $principalId = az ad sp show --id $AADAppIdentifierUri --query "id" -o tsv if (-not $principalId) { throw "Error: Failed to create new service principal" } Write-Host "New service principal created successfully" # Sleep for 5 seconds to allow the new service principal to propagate Write-Host "Sleeping for 5 seconds" Start-Sleep -Seconds 5 } Write-Host "Granting service principal access to the newly created Immersive Reader resource" $accessResult = az role assignment create --assignee $principalId --scope $resourceId --role "Cognitive Services Immersive Reader User" if (-not $accessResult) { throw "Error: Failed to grant service principal access" } Write-Host "Service principal access granted successfully" # Grab the tenant ID, which is needed when obtaining a Microsoft Entra token $tenantId = az account show --query "tenantId" -o tsv # Collect the information needed to obtain a Microsoft Entra token into one object $result = @{} $result.TenantId = $tenantId $result.ClientId = $clientId $result.ClientSecret = $clientSecret $result.Subdomain = $ResourceSubdomain Write-Host "`nSuccess! " -ForegroundColor Green -NoNewline 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 Microsoft Entra to fetch access tokens." Write-Host "This is the only time you will ever see the client secret for your Microsoft Entra application, so save it now." -ForegroundColor Yellow } else{ Write-Host "You will need to retrieve the ClientSecret from your original run of this function that created it. If you don't have it, you will need to go create a new client secret for your Microsoft Entra application. Please visit https://portal.azure.com and go to Home -> Microsoft Entra ID -> App Registrations -> (your app) '$AADAppDisplayName' -> Certificates and Secrets blade -> Client Secrets section." -ForegroundColor Yellow } Write-Host "*****`n" Write-Output (ConvertTo-Json $result) }Eseguire la funzione
Create-ImmersiveReaderResource, sostituendo i segnaposto "<PARAMETER_VALUES>" con i rispettivi valori in base alle esigenze.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 '<MICROSOFT_ENTRA_DISPLAY_NAME>' -AADAppIdentifierUri '<MICROSOFT_ENTRA_IDENTIFIER_URI>' -AADAppClientSecretExpiration '<MICROSOFT_ENTRA_CLIENT_SECRET_EXPIRATION>'Il comando completo ha un aspetto simile al seguente. Qui è stato inserito ogni parametro nella rispettiva riga per maggiore chiarezza, in modo da poter visualizzare l'intero comando. Non copiare o usare questo comando così com'è. Copiare e usare il comando con i propri valori. In questo esempio sono presenti valori fittizi per
<PARAMETER_VALUES>. Il risultato effettivo sarà diverso, in quanto si inseriranno i propri nomi per questi valori.Create-ImmersiveReaderResource -SubscriptionName 'MyOrganizationSubscriptionName' -ResourceName 'MyOrganizationImmersiveReader' -ResourceSubdomain 'MyOrganizationImmersiveReader' -ResourceSKU 'S0' -ResourceLocation 'westus2' -ResourceGroupName 'MyResourceGroupName' -ResourceGroupLocation 'westus2' -AADAppDisplayName 'MyOrganizationImmersiveReaderAADApp' -AADAppIdentifierUri 'api://MyOrganizationImmersiveReaderAADApp' -AADAppClientSecretExpiration '2021-12-31'Parametro Commenti SubscriptionName Nome della sottoscrizione di Azure da usare per la risorsa dello Strumento di lettura immersiva. Per creare una risorsa è necessario avere una sottoscrizione. NomeRisorsa Il nome deve essere alfanumerico e può contenere -, purché-non sia il primo o l'ultimo carattere. La lunghezza non può superare i 63 caratteri.ResourceSubdomain Per la risorsa dello Strumento di lettura immersiva è necessario un sottodominio personalizzato. Il sottodominio viene usato dall'SDK quando si chiama il servizio Strumento di lettura immersiva per avviare il lettore. Il sottodominio deve essere univoco a livello globale. Il nome del sottodominio deve essere alfanumerico e può contenere -, purché-non sia il primo o l'ultimo carattere. La lunghezza non può superare i 63 caratteri. Questo parametro è facoltativo se la risorsa esiste già.ResourceSKU Opzioni: S0(livello Standard) oS1(organizzazioni didattiche/no profit). Per altre informazioni su ogni SKU disponibile, visitare la pagina dei prezzi dei Servizi di Azure AI. Questo parametro è facoltativo se la risorsa esiste già.ResourceLocation Opzioni: 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. Questo parametro è facoltativo se la risorsa esiste già.ResourceGroupName Le risorse vengono create nei gruppi di risorse all'interno delle sottoscrizioni. Specificare il nome di un gruppo di risorse esistente. Se il gruppo di risorse non esiste già, ne viene creato uno nuovo con questo nome. ResourceGroupLocation Se il gruppo di risorse non esiste, è necessario specificare una posizione in cui crearlo. Per trovare un elenco di posizioni, eseguire az account list-locations. Usare la proprietà name (senza spazi) del risultato restituito. Questo parametro è facoltativo se il gruppo di risorse esiste già.AADAppDisplayName Nome visualizzato dell'applicazione Microsoft Entra. Se non viene trovata un'applicazione Microsoft Entra esistente, ne viene creata una nuova con questo nome. Questo parametro è facoltativo se l'applicazione Microsoft Entra esiste già. AADAppIdentifierUri URI per l'applicazione Microsoft Entra. Se non viene trovata un'applicazione Microsoft Entra esistente, ne viene creata una nuova con questo URI. Ad esempio: api://MyOrganizationImmersiveReaderAADApp. In questo caso viene usato il prefisso predefinitoapi://dello schema URI di Microsoft Entra, per compatibilità con il criterio di Microsoft Entra che prevede l'uso di domini verificati.AADAppClientSecretExpiration Data o data/ora dopo cui il segreto client dell'applicazione Microsoft Entra (password) scade (ad esempio, "2020-12-31T11:59:59+00:00" o "2020-12-31"). Questa funzione crea automaticamente un segreto client. Per gestire i segreti client dell'applicazione Microsoft Entra dopo aver creato questa risorsa, visitare il portale di Azure e passare a Home ->Microsoft Entra ID ->Registrazioni app -> (l'app)
[AADAppDisplayName]->Sezione Certificati e segreti ->Sezione Segreti client.
Copiare l'output JSON in un file di testo per un uso successivo. L'output sarà simile al seguente.
{ "TenantId": "...", "ClientId": "...", "ClientSecret": "...", "Subdomain": "..." }
