Creare una risorsa Strumento di lettura immersiva e configurare l'autenticazione di Microsoft Entra
Questo articolo illustra come creare una risorsa Strumento di lettura immersiva usando lo script fornito. Questo script configura anche l'autenticazione di Microsoft Entra. Ogni volta che viene creata una risorsa Strumento di lettura immersiva, con questo script o nel portale, deve essere configurata con le autorizzazioni di Microsoft Entra.
Lo script crea e configura automaticamente tutte le risorse necessarie Strumento di lettura immersiva e Microsoft Entra. Tuttavia, è anche possibile configurare l'autenticazione di Microsoft Entra per una risorsa di Strumento di lettura immersiva esistente, se ne è già stata creata una nella portale di Azure. Lo script cerca prima di tutto le risorse esistenti Strumento di lettura immersiva e Microsoft Entra nella sottoscrizione e le crea solo se non esistono già.
Per alcuni clienti, potrebbe essere necessario creare più risorse Strumento di lettura immersiva, per lo sviluppo e la produzione o per aree diverse in cui viene distribuito il servizio. Per questi casi, è possibile tornare indietro e usare lo script più volte per creare diverse risorse Strumento di lettura immersiva e configurarle con le autorizzazioni di Microsoft Entra.
Autorizzazioni
Il proprietario elencato della sottoscrizione di Azure ha tutte le autorizzazioni necessarie per creare una risorsa 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, specificando i segnaposto "<PARAMETER_VALUES>" con i propri 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 è simile al seguente. In questo caso ogni parametro viene inserito nella propria 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 valori personalizzati. In questo esempio sono presenti valori fittizi per .
<PARAMETER_VALUES>I tuoi valori potrebbero essere diversi, man mano che hai i tuoi 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 Strumento di lettura immersiva. Per creare una risorsa, è necessario disporre di una sottoscrizione. NomeRisorsa 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 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 reader. Il sottodominio deve essere globalmente univoco. Il 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 education/no profit). Per altre informazioni su ogni SKU disponibile, visitare la pagina dei prezzi dei servizi di intelligenza artificiale di Azure. Questo parametro è facoltativo se la risorsa esiste già.ResourceLocation Opzioni: australiaeast,brazilsouthcentralindiacanadacentralcentralus,japaneastjapanwestgermanywestcentralfrancecentraleastus2jioindiawesteastasiaswitzerlandwestswitzerlandnortheastusnorwayeastsouthafricanorthnortheuropesouthcentralusnorthcentralussoutheastasiawestcentralusuaenorthswedencentralkoreacentralwesteuropewestusuksouth, .westus3westus2Questo 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 creare il gruppo. Per trovare un elenco di percorsi, eseguire az account list-locations. Utilizzare 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 predefinito dello schema URI di Microsoft Entra perapi://garantire la compatibilità con i criteri di Microsoft Entra dell'uso di domini verificati.AADAppClientSecretExpiration Data o data/ora successiva alla quale scade il segreto client dell'applicazione Microsoft Entra (password), 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 alla sezione Home ->Microsoft Entra ID ->App Registrations -> (app)
[AADAppDisplayName]->Certificates and Secrets (Segreti client).>
Copiare l'output JSON in un file di testo per usarlo in un secondo momento. L'output sarà simile al seguente.
{ "TenantId": "...", "ClientId": "...", "ClientSecret": "...", "Subdomain": "..." }
