Skapa en Avancerad läsare resurs och konfigurera Microsoft Entra-autentisering

  • Artikel

Den här artikeln beskriver hur du skapar en Avancerad läsare resurs med hjälp av det angivna skriptet. Det här skriptet konfigurerar även Microsoft Entra-autentisering. Varje gång en Avancerad läsare resurs skapas, oavsett om det är med det här skriptet eller i portalen, måste den konfigureras med Microsoft Entra-behörigheter.

Skriptet skapar och konfigurerar alla nödvändiga Avancerad läsare och Microsoft Entra-resurser åt dig. Du kan dock även konfigurera Microsoft Entra-autentisering för en befintlig Avancerad läsare resurs, om du redan har skapat en i Azure-portalen. Skriptet söker först efter befintliga Avancerad läsare- och Microsoft Entra-resurser i din prenumeration och skapar dem endast om de inte redan finns.

För vissa kunder kan det vara nödvändigt att skapa flera Avancerad läsare resurser, för utveckling kontra produktion, eller kanske för olika regioner där tjänsten distribueras. I dessa fall kan du komma tillbaka och använda skriptet flera gånger för att skapa olika Avancerad läsare resurser och konfigurera dem med Microsoft Entra-behörigheter.

Behörigheter

Den listade ägaren av din Azure-prenumeration har alla behörigheter som krävs för att skapa en Avancerad läsare resurs och konfigurera Microsoft Entra-autentisering.

Om du inte är ägare krävs följande omfångsspecifika behörigheter:

  • Deltagare. Du måste ha minst en deltagarroll som är associerad med Azure-prenumerationen:

    Screenshot of contributor built-in role description.

  • Programutvecklare. Du måste ha minst en programutvecklare som är associerad med Microsoft Entra-ID:

    Screenshot of the developer built-in role description.

Mer information finns i Inbyggda roller i Microsoft Entra.

Konfigurera PowerShell-resurser

  1. Börja med att öppna Azure Cloud Shell. Kontrollera att Cloud Shell är inställt på PowerShell i den övre vänstra listrutan eller genom att pwshskriva .

  2. Kopiera och klistra in följande kodfragment i gränssnittet.

    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. Kör funktionen Create-ImmersiveReaderResourceoch ange platshållarna "<PARAMETER_VALUES>" med dina egna värden efter behov.

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

    Det fullständiga kommandot ser ut ungefär så här. Här placerar vi varje parameter på sin egen rad för tydlighetens skull, så att du kan se hela kommandot. Kopiera inte eller använd inte det här kommandot som det är. Kopiera och använd kommandot med dina egna värden. Det här exemplet har dummy-värden för <PARAMETER_VALUES>. Din kan vara annorlunda, eftersom du kommer med dina egna namn för dessa värden.

    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'
    Parameter Kommentarer
    SubscriptionName Namnet på den Azure-prenumeration som ska användas för din Avancerad läsare resurs. Du måste ha en prenumeration för att kunna skapa en resurs.
    ResourceName Måste vara alfanumeriskt och kan innehålla -, så länge som - inte är det första eller sista tecknet. Längden får inte överstiga 63 tecken.
    ResourceSubdomain Du behöver en anpassad underdomän för din Avancerad läsare resurs. Underdomänen används av SDK:et när Avancerad läsare-tjänsten anropas för att starta läsaren. Underdomänen måste vara globalt unik. Underdomänen måste vara alfanumerisk och kan innehålla -, så länge som - inte är det första eller sista tecknet. Längden får inte överstiga 63 tecken. Den här parametern är valfri om resursen redan finns.
    ResourceSKU Alternativ: S0 (standardnivå) eller S1 (utbildnings-/ideella organisationer). Mer information om varje tillgänglig SKU finns på prissättningssidan för Azure AI-tjänster. Den här parametern är valfri om resursen redan finns.
    ResourceLocation Alternativ: australiaeast, brazilsouth, canadacentral, centralindia, centralus, eastasia, eastus, eastus2, francecentral, germanywestcentral, japaneast, japanwest, jioindiawest, koreacentral, northcentralus, northeuropenorwayeastsouthafricanorthsouthcentralus, , southeastasia, uaenorthswitzerlandnorthuksouthswitzerlandwestswedencentral, westcentralus, westeurope, westus, , . westus2westus3 Den här parametern är valfri om resursen redan finns.
    ResourceGroupName Resurser skapas i resursgrupper i prenumerationer. Ange namnet på en befintlig resursgrupp. Om resursgruppen inte redan finns skapas en ny med det här namnet.
    ResourceGroupLocation Om resursgruppen inte finns måste du ange en plats där gruppen ska skapas. Om du vill hitta en lista över platser kör du az account list-locations. Använd namnegenskapen (utan blanksteg) för det returnerade resultatet. Den här parametern är valfri om resursgruppen redan finns.
    AADAppDisplayName Visningsnamnet för Microsoft Entra-programmet. Om ett befintligt Microsoft Entra-program inte hittas skapas en ny med det här namnet. Den här parametern är valfri om Microsoft Entra-programmet redan finns.
    AADAppIdentifierUri URI:n för Microsoft Entra-programmet. Om ett befintligt Microsoft Entra-program inte hittas skapas en ny med den här URI:n. Exempel: api://MyOrganizationImmersiveReaderAADApp Här använder vi standardprefixet api:// för Microsoft Entra-URI-schema för kompatibilitet med Microsoft Entra-principen för att använda verifierade domäner.
    AADAppClientSecretExpiration Det datum eller datum då din Microsoft Entra-programklienthemlighet (lösenord) upphör att gälla (till exempel "2020-12-31T11:59:59+00:00" eller "2020-12-31"). Den här funktionen skapar en klienthemlighet åt dig.

    Om du vill hantera dina Microsoft Entra-programklienthemligheter när du har skapat den här resursen går du till Azure-portalen och går till Home ->Microsoft Entra ID ->App Registrations -> (din app) [AADAppDisplayName] ->Certificates and Secrets section -Client Secrets section (>Klienthemligheter).

    Screenshot of the Azure portal Certificates and Secrets pane.

  4. Kopiera JSON-utdata till en textfil för senare användning. Resultatet bör likna följande.

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

Gå vidare

Så här startar du Avancerad läsare