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

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 Czytnika Immersyjnego, czy to przy użyciu tego skryptu, czy w portalu, musi być skonfigurowany z uprawnieniami Microsoft Entra.

Skrypt tworzy i konfiguruje wszystkie niezbędne zasoby dla Czytnika immersyjnego oraz Microsoft Entra. Można jednak również skonfigurować uwierzytelnianie Microsoft Entra dla istniejącego zasobu Immersive Reader, jeśli został już utworzony w portalu Azure. Skrypt najpierw wyszukuje istniejące zasoby Czytnika Immersyjnego i Microsoft Entra w tej subskrypcji i tworzy je tylko wtedy, gdy jeszcze nie istnieją.

W przypadku niektórych klientów może być konieczne utworzenie wielu zasobów Immersive Reader, na potrzeby rozwoju versus produkcji lub dla różnych regionów, 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 Immersive Reader i skonfigurować uwierzytelnianie 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ółtwórca skojarzoną z subskrypcją platformy Azure.
Deweloper aplikacji. Musisz mieć co najmniej rolę dewelopera aplikacji skojarzoną z Microsoft Entra ID.

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

Konfigurowanie zasobów programu PowerShell

Zacznij od otwarcia usługi Azure Cloud Shell. Upewnij się, że usługa Cloud Shell jest ustawiona na PowerShell na liście rozwijanej w lewym górnym rogu lub wpisując pwsh.

Skopiuj i wklej poniższy fragment kodu do powłoki.

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 a 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)
}

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
Nazwa subskrypcji	Nazwa subskrypcji platformy Azure do użycia dla zasobu Czytnik immersyjny. Aby utworzyć zasób, musisz mieć subskrypcję.
NazwaZasobu	Musi być alfanumeryczne i może zawierać `-`, pod warunkiem że `-` nie jest pierwszym ani ostatnim znakiem. Długość nie może przekraczać 63 znaków.
Poddomena zasobu	Dla zasobu Immersive Reader potrzebna jest niestandardowa subdomena. 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ć `-`, o ile `-` nie jest pierwszym ani ostatnim znakiem. 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.
LokalizacjaZasobu	Opcje: `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`. Ten parametr jest opcjonalny, jeśli zasób już istnieje.
NazwaGrupyZasobów	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.
LokalizacjaGrupyZasobów	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.
Nazwa aplikacji AAD	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 dla 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.
Wygaśnięcie tajnego klucza klienta aplikacji AAD	Data lub data/godzina po której wygaśnie tajne hasło klienta aplikacji Microsoft Entra (na przykład "2020-12-31T11:59:59+00:00" lub "2020-12-31"). Ta funkcja tworzy dla użytkownika tajny klucz klienta.

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

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

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-04-22