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

Artykuł
09/02/2024

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:
Deweloper aplikacji. Musisz mieć co najmniej rolę dewelopera aplikacji skojarzona z identyfikatorem Entra firmy Microsoft:

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 program PowerShell na liście rozwijanej po lewej górnej stronie lub wpisując .pwsh

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

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>).

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

Udostępnij za pośrednictwem

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

Uprawnienia

Konfigurowanie zasobów programu PowerShell

Następny krok

Opinia

Dodatkowe zasoby