Créer une ressource Immersive Reader et configurer l’authentification Microsoft Entra

  • Article

Cet article explique comment créer une ressource Immersive Reader à l’aide du script fourni. Ce script configure également l’authentification Microsoft Entra. Chaque fois qu’une ressource Immersive Reader est créée, avec ce script ou dans le portail, elle doit être configurée avec les autorisations Microsoft Entra.

Le script crée et configure toutes les ressources Immersive Reader et Microsoft Entra nécessaires pour vous. Toutefois, vous pouvez également configurer l’authentification Microsoft Entra pour une ressource Immersive Reader existante si vous en avez déjà créé une dans le Portail Azure. Le script recherche d’abord les ressources Immersive Reader et Microsoft Entra existantes dans votre abonnement, et les crée uniquement si elles n’existent pas encore.

Pour certains clients, il peut être nécessaire de créer plusieurs ressources Immersive Reader, pour le développement ou la production, ou encore pour les différentes régions où votre service est déployé. Dans ces cas, vous pouvez revenir en arrière et utiliser le script plusieurs fois pour créer différentes ressources Immersive Reader et les configurer avec des autorisations Microsoft Entra.

Autorisations

Le propriétaire indiqué de votre abonnement Azure dispose de toutes les autorisations nécessaires pour créer une ressource Immersive Reader et configurer l’authentification Microsoft Entra.

Si vous n’êtes pas propriétaire, les autorisations spécifiques à l’étendue suivantes sont requises :

  • Contributeur. Vous devez avoir au moins un rôle Contributeur associé à l’abonnement Azure :

    Screenshot of contributor built-in role description.

  • Développeur d’applications. Vous devez avoir au moins un rôle Développeur d’applications associé dans Microsoft Entra ID :

    Screenshot of the developer built-in role description.

Pour plus d’informations, consultez Rôles intégrés Microsoft Entra.

Configurer des ressources PowerShell

  1. Commencez par ouvrir Azure Cloud Shell. Assurez-vous que Cloud Shell est défini sur PowerShell dans la liste déroulante en haut à gauche, ou sinon tapez pwsh.

  2. Copiez et collez l’extrait de code suivant dans le 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)
}

  3. Exécutez la fonction Create-ImmersiveReaderResource en remplaçant les espaces réservés « <PARAMETER_VALUES> » par vos propres valeurs, selon le cas.

    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>'

    La commande complète ressemble à ce qui suit. Ici, nous avons placé chaque paramètre sur sa propre ligne pour plus de clarté, ce qui vous permet de voir l’ensemble de la commande. Ne copiez pas ou n’utilisez pas cette commande telle quelle. Copiez et utilisez la commande avec vos propres valeurs. Cet exemple contient des valeurs factices pour les <PARAMETER_VALUES>. Votre commande peut être différente, car vous indiquez vos propres noms pour ces valeurs.

    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'
    Paramètre Commentaires
    SubscriptionName Nom de l’abonnement Azure à utiliser pour votre ressource Lecteur immersif. Vous devez avoir un abonnement pour pouvoir créer une ressource.
    Nom_ressource Doit être de type alphanumérique et peut contenir -, à condition que le - ne soit pas le premier ou le dernier caractère. La longueur ne peut excéder 63 caractères.
    ResourceSubdomain Un sous-domaine personnalisé est nécessaire pour votre ressource Lecteur immersif. Le sous-domaine est utilisé par le kit SDK lors de l’appel du service Lecteur immersif pour lancer le Lecteur. Le sous-domaine doit être globalement unique. Le sous-domaine doit être de type alphanumérique et peut contenir -, à condition que le - ne soit pas le premier ou le dernier caractère. La longueur ne peut excéder 63 caractères. Ce paramètre est facultatif si la ressource existe déjà.
    ResourceSKU Options : S0 (niveau standard) ou S1 (établissements scolaires/associations à but non lucratif). Pour en savoir plus sur chaque référence SKU disponible, consultez notre page de tarification Azure AI services. Ce paramètre est facultatif si la ressource existe déjà.
    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. Ce paramètre est facultatif si la ressource existe déjà.
    ResourceGroupName Les ressources sont créées dans des groupes de ressources au sein d’abonnements. Donnez le nom d’un groupe de ressources existant. Si le groupe de ressources n’existe pas encore, un nouveau groupe avec ce nom est créé.
    ResourceGroupLocation Si votre groupe de ressources n’existe pas, vous devez fournir un emplacement dans lequel créer le groupe. Pour trouver une liste d’emplacements, exécutez az account list-locations. Utilisez la propriété name (sans espaces) du résultat retourné. Ce paramètre est facultatif si votre groupe de ressources existe déjà.
    AADAppDisplayName Nom d’affichage de l’application Microsoft Entra. Si une application Microsoft Entra existante est introuvable, une nouvelle application avec ce nom est créée. Ce paramètre est facultatif si l’application Microsoft Entra existe déjà.
    AADAppIdentifierUri URI pour l’application Microsoft Entra. Si une application Microsoft Entra existante est introuvable, une nouvelle application avec cet URI est créée. Par exemple : api://MyOrganizationImmersiveReaderAADApp. Ici, nous utilisons le préfixe de schéma d’URI Microsoft Entra par défaut de api:// pour la compatibilité avec la stratégie Microsoft Entra sur l’utilisation des domaines vérifiés.
    AADAppClientSecretExpiration La date ou DateHeure à partir de laquelle votre clé secrète client d’application Microsoft Entra (mot de passe) expire (par exemple, « 2020-12-31T11:59:59+00:00 » ou « 2020-12-31 »). Cette fonction crée une clé secrète client pour vous.

    Pour gérer les clés secrètes client de votre application Microsoft Entra après avoir créé cette ressource, rendez-vous sur le portail Azure et accédez à Accueil ->Microsoft Entra ID ->Inscriptions d’applications -> (votre application) [AADAppDisplayName] - Section >Certificats et Secrets -Section >Clés secrètes client.

    Screenshot of the Azure portal Certificates and Secrets pane.

  4. Copiez la sortie JSON dans un fichier texte pour l’utiliser ultérieurement. La sortie doit se présenter comme suit.

    {
  "TenantId": "...",
  "ClientId": "...",
  "ClientSecret": "...",
  "Subdomain": "..."
}

Étape suivante

Guide de lancement d’Immersive Reader