Tworzenie zasobu Czytnik immersyjny i konfigurowanie uwierzytelniania w usłudze Microsoft Entra

  • Artykuł

W tym artykule wyjaśniono, jak utworzyć zasób Czytnik immersyjny przy użyciu dostarczonego skryptu. Ten skrypt konfiguruje również uwierzytelnianie firmy Microsoft Entra. Za każdym razem, gdy jest tworzony zasób Czytnik immersyjny( przy użyciu tego skryptu lub w portalu), musi być skonfigurowany z uprawnieniami firmy Microsoft Entra.

Skrypt tworzy i konfiguruje wszystkie niezbędne zasoby Czytnik immersyjny i Microsoft Entra. Można jednak również skonfigurować uwierzytelnianie microsoft Entra dla istniejącego zasobu Czytnik immersyjny, jeśli został już utworzony w witrynie Azure Portal. Skrypt najpierw wyszukuje istniejące zasoby Czytnik immersyjny i Microsoft Entra w subskrypcji i tworzy je tylko wtedy, gdy jeszcze nie istnieją.

W przypadku niektórych klientów może być konieczne utworzenie wielu zasobów Czytnik immersyjny na potrzeby programowania i produkcji, a może w różnych regionach, w których wdrożono usługę. W takich przypadkach możesz wrócić i użyć skryptu wiele razy, aby utworzyć różne zasoby Czytnik immersyjny i skonfigurować je przy użyciu uprawnień firmy Microsoft Entra.

Uprawnienia

Wymieniony właściciel subskrypcji platformy Azure ma wszystkie wymagane uprawnienia, aby utworzyć zasób Czytnik immersyjny i skonfigurować uwierzytelnianie firmy Microsoft Entra.

Jeśli nie jesteś właścicielem, wymagane są następujące uprawnienia specyficzne dla zakresu:

  • Współautor. Musisz mieć co najmniej rolę Współautor skojarzona z subskrypcją platformy Azure:

    Screenshot of contributor built-in role description.

  • Deweloper aplikacji. Musisz mieć co najmniej rolę dewelopera aplikacji skojarzona z identyfikatorem Entra firmy Microsoft:

    Screenshot of the developer built-in role description.

Aby uzyskać więcej informacji, zobacz Wbudowane role usługi Microsoft Entra.

Konfigurowanie zasobów programu PowerShell

  1. Zacznij od otwarcia usługi Azure Cloud Shell. Upewnij się, że usługa Cloud Shell jest ustawiona na program PowerShell na liście rozwijanej po lewej górnej stronie lub wpisując .pwsh

  2. Skopiuj i wklej poniższy fragment kodu w powłoce.

    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. Uruchom funkcję Create-ImmersiveReaderResource, podając symbole zastępcze "<PARAMETER_VALUES>" z własnymi wartościami zgodnie z potrzebami.

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

    Pełne polecenie wygląda podobnie do poniższego. W tym miejscu umieściliśmy każdy parametr w osobnym wierszu, aby uzyskać czytelność, dzięki czemu można zobaczyć całe polecenie. Nie kopiuj ani nie używaj tego polecenia w taki sposób, jak jest. Skopiuj i użyj polecenia z własnymi wartościami. Ten przykład zawiera fikcyjne wartości dla elementu <PARAMETER_VALUES>. Twoje mogą być inne, ponieważ wymyślisz własne nazwy dla tych wartości.

    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'
    Parametr Komentarze
    SubscriptionName Nazwa subskrypcji platformy Azure do użycia dla zasobu Czytnik immersyjny. Aby utworzyć zasób, musisz mieć subskrypcję.
    ResourceName Musi być alfanumeryczne i może zawierać -wartość , o ile - nie jest to pierwszy lub ostatni znak. Długość nie może przekraczać 63 znaków.
    ZasóbSubdomena Dla zasobu Czytnik immersyjny wymagany jest niestandardowy poddomena podrzędna. Poddomena jest używana przez zestaw SDK podczas wywoływania usługi Czytnik immersyjny w celu uruchomienia czytnika. Poddomena musi być globalnie unikatowa. Poddomena musi być alfanumeryczna i może zawierać -wartość , o ile nie jest to - pierwszy lub ostatni znak. Długość nie może przekraczać 63 znaków. Ten parametr jest opcjonalny, jeśli zasób już istnieje.
    ResourceSKU Opcje: S0 (warstwa Standardowa) lub S1 (organizacje edukacyjne/non-profit). Aby dowiedzieć się więcej na temat każdej dostępnej jednostki SKU, odwiedź stronę cennika usług Azure AI. Ten parametr jest opcjonalny, jeśli zasób już istnieje.
    ResourceLocation Opcje: australiaeast, brazilsouthcanadacentralwestus3eastus2westus2eastuswestusfrancecentraleastasiaswedencentralgermanywestcentralswitzerlandnorthjapaneastswitzerlandwestwestcentralussoutheastasiawesteuropeuksouthuaenorthsouthcentralussouthafricanorthnorwayeastnortheuropekoreacentraljapanwestnorthcentraluscentralindiacentralusjioindiawest. Ten parametr jest opcjonalny, jeśli zasób już istnieje.
    ResourceGroupName Zasoby są tworzone w grupach zasobów w ramach subskrypcji. Podaj nazwę istniejącej grupy zasobów. Jeśli grupa zasobów jeszcze nie istnieje, zostanie utworzona nowa grupa o tej nazwie.
    ResourceGroupLocation Jeśli grupa zasobów nie istnieje, musisz podać lokalizację, w której ma zostać utworzona grupa. Aby znaleźć listę lokalizacji, uruchom polecenie az account list-locations. Użyj właściwości name (bez spacji) zwróconego wyniku. Ten parametr jest opcjonalny, jeśli grupa zasobów już istnieje.
    AADAppDisplayName Nazwa wyświetlana aplikacji Microsoft Entra. Jeśli istniejąca aplikacja Firmy Microsoft Entra nie zostanie znaleziona, zostanie utworzona nowa aplikacja o tej nazwie. Ten parametr jest opcjonalny, jeśli aplikacja Microsoft Entra już istnieje.
    AADAppIdentifierUri Identyfikator URI aplikacji Microsoft Entra. Jeśli istniejąca aplikacja Firmy Microsoft Entra nie zostanie znaleziona, zostanie utworzona nowa aplikacja z tym identyfikatorem URI. Na przykład api://MyOrganizationImmersiveReaderAADApp. W tym miejscu używamy domyślnego prefiksu schematu api:// identyfikatora URI firmy Microsoft w celu zachowania zgodności z zasadami firmy Microsoft Entra używania zweryfikowanych domen.
    AADAppClientSecretExpiration Data lub data/godzina wygaśnięcia wpisu tajnego klienta aplikacji firmy Microsoft (hasło) (na przykład "2020-12-31T11:59:59+00:00" lub "2020-12-31"). Ta funkcja tworzy dla Ciebie wpis tajny klienta.

    Aby zarządzać wpisami tajnymi klienta aplikacji Microsoft Entra po utworzeniu tego zasobu, odwiedź witrynę Azure Portal i przejdź do sekcji Home ->Microsoft Entra ID ->App Registrations -> (Twoja aplikacja) [AADAppDisplayName] ->Certificates and Secrets (Certyfikaty i wpisy tajne klienta>).

    Screenshot of the Azure portal Certificates and Secrets pane.

  4. Skopiuj dane wyjściowe JSON do pliku tekstowego do późniejszego użycia. Dane wyjściowe powinny wyglądać podobnie do poniższych.

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

Następny krok

Jak uruchomić Czytnik immersyjny