Creación de un recurso del Lector inmersivo y configuración de la autenticación de Azure Active Directory

En este artículo, se proporciona un script que creará un recurso del Lector inmersivo y configurará la autenticación de Azure Active Directory (Azure AD). Cada vez que se crea un recurso del Lector inmersivo, ya sea con este script o en el portal, también debe configurarse con permisos de Azure AD. Este script le ayudará a hacerlo.

El script está diseñado para crear y configurar automáticamente todos los recursos necesarios del Lector inmersivo y de Azure AD en un solo paso. Sin embargo, también puede configurar la autenticación de Azure AD para un recurso existente del Lector inmersivo, si, por ejemplo, ya ha creado uno en Azure Portal.

En el caso de algunos clientes, puede que sea necesario crear varios recursos del Lector inmersivo, para desarrollo frente a producción, o quizás para varias regiones diferentes en las que se implemente el servicio. En esos casos, puede volver y usar el script varias veces para crear distintos recursos del Lector inmersivo y configurarlos con los permisos de Azure AD.

El script está diseñado para ser flexible. En primer lugar, buscará los recursos existentes del Lector inmersivo y de Azure AD en su suscripción, y solo los creará según sea necesario si aún no existen. Si es la primera vez que crea un recurso del Lector inmersivo, el script hará todo lo que necesita. Si desea usarlo solo para configurar Azure AD para un recurso existente del Lector inmersivo creado en el portal, también se encargará. Asimismo, se puede usar para crear y configurar varios recursos del Lector inmersivo.

Configuración del entorno de PowerShell

  1. Para empezar, abra Azure Cloud Shell. Asegúrese de que Cloud Shell está establecido en PowerShell en la lista desplegable de la parte superior izquierda o escriba pwsh.

  2. Copie y pegue el siguiente fragmento de código en el 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 Azure Active Directory 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 Azure Active Directory app"
            $clientId = az ad app create --display-name $AADAppDisplayName --identifier-uris $AADAppIdentifierUri --query "appId" -o tsv
            if (-not $clientId) {
                throw "Error: Failed to create Azure Active Directory application"
            }
            Write-Host "Azure Active Directory 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 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
        }
    
        # 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 an Azure AD token
        $tenantId = az account show --query "tenantId" -o tsv
    
        # Collect the information needed to obtain an Azure AD 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 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
        }
        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 Azure Active Directory application. 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
        }
        Write-Host "*****`n"
        Write-Output (ConvertTo-Json $result)
    }
    
  3. Ejecute la función Create-ImmersiveReaderResource y proporcione los marcadores de posición "<VALORES_DE_PARÁMETROS>" a continuación con sus propios valores, según corresponda.

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

    El comando completo tendrá un aspecto similar al siguiente. Aquí hemos colocado cada parámetro en su propia línea para mayor claridad, para que pueda ver el comando completo. No copie ni use este comando tal cual. Copie y use el comando anterior con sus propios valores. Este ejemplo tiene valores ficticios para los "<VALORES_DE_PARÁMETROS>" anteriores. Los suyos serán diferentes, ya que tendrá sus propios nombres para estos valores.

    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'
    
    Parámetro Comentarios
    SubscriptionName Nombre de la suscripción a Azure que se va a usar para el recurso del Lector inmersivo. Debe tener una suscripción para poder crear un recurso.
    nombreDelRecurso Debe ser alfanumérico y puede contener "-", siempre y cuando "-" no sea el primer ni el último carácter. No puede tener una longitud de más de 63 caracteres.
    ResourceSubdomain Subdominio personalizado necesario para el recurso del Lector inmersivo. El SDK usa el subdominio al llamar al servicio del Lector inmersivo para iniciar el Lector. El subdominio debe ser único globalmente. El subdominio debe ser alfanumérico y puede contener "-", siempre y cuando "-" no sea el primer ni el último carácter. No puede tener una longitud de más de 63 caracteres. Este parámetro es opcional si el recurso ya existe.
    ResourceSKU Opciones: S0 (nivel Estándar) o S1 (organizaciones educativas o sin ánimo de lucro). Visite nuestra página de precios de Cognitive Services para obtener más información sobre cada SKU disponible. Este parámetro es opcional si el recurso ya existe.
    ResourceLocation Opciones: 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. Este parámetro es opcional si el recurso ya existe.
    ResourceGroupName Los recursos se crean en grupos de recursos dentro de las suscripciones. Suministre el nombre de un grupo de recursos existente. Si el grupo de recursos todavía no existe, se creará uno con este nombre.
    ResourceGroupLocation Si el grupo de recursos no existe, debe proporcionar una ubicación donde se creará el grupo. Ejecute az account list-locations para obtener una lista de ubicaciones. Use la propiedad name (sin espacios) del resultado devuelto. Este parámetro es opcional si el grupo de recursos ya existe.
    AADAppDisplayName El nombre para mostrar de la aplicación de Azure Active Directory. Si no se encuentra una aplicación de Azure AD existente, se creará una con este nombre. Este parámetro es opcional si la aplicación de Azure AD ya existe.
    AADAppIdentifierUri El URI de la aplicación de Azure AD. Si no se encuentra una aplicación de Azure AD existente, se creará una con este URI. Por ejemplo, api://MyOrganizationImmersiveReaderAADApp. Aquí se usa el prefijo de esquema del identificador URI de Azure AD api:// para tener compatibilidad con la directiva de usar dominios comprobados de Azure AD.
    AADAppClientSecretExpiration La fecha o datetime tras la que su secreto de cliente de la aplicación AAD (contraseña) caducará (por ejemplo: '2020-12-31T11:59:59+00:00' or '2020-12-31'). Esta función creará un secreto de cliente de manera automática. Para administrar secretos de cliente de aplicaciones de Azure AD después de haber creado este recurso, visite https://portal.azure.com y vaya a Inicio -> Azure Active Directory -> Registros de aplicaciones -> (su aplicación) [AADAppDisplayName] -> hoja "Certificados y secretos" -> sección "Secretos de clientes" (como se muestra a continuación en la captura de pantalla "Administración de los secretos de aplicación de Azure AD").

    Administración de los secretos de aplicación de Azure AD

    Hoja Certificados y secretos de Azure Portal

  4. Copie la salida JSON en un archivo de texto para usarla en otro momento. La salida debe tener un aspecto similar al siguiente.

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

Pasos siguientes