Erstellen einer Plastischer Reader-Ressource und Konfigurieren der Azure Active Directory-Authentifizierung

In diesem Artikel wird ein Skript bereitgestellt, mit dem eine Plastischer Reader-Ressource erstellt und die Azure AD-Authentifizierung (Azure Active Directory) konfiguriert wird. Jedes Mal, wenn eine Plastischer Reader-Ressource mit diesem Skript oder im Portal erstellt wird, muss sie unabhängig davon auch mit Azure AD-Berechtigungen konfiguriert werden. Dieses Skript unterstützt Sie dabei.

Das Skript ist darauf ausgelegt, alle notwendigen Plastischer Reader- und Azure AD-Ressourcen für Sie in einem Schritt zu erstellen und zu konfigurieren. Sie können jedoch auch nur die Azure AD-Authentifizierung für eine vorhandene Plastischer Reader-Ressource konfigurieren, wenn Sie beispielsweise bereits eine im Azure-Portal erstellt haben.

Einige Kunden müssen möglicherweise mehrere Plastischer Reader-Ressourcen für Entwicklung und Produktion erstellen, oder vielleicht für mehrere verschiedene Regionen, in denen ihr Dienst bereitgestellt wird. In diesen Fällen können Sie das Skript mehrmals verwenden, um unterschiedliche Plastischer Reader-Ressourcen zu erstellen und sie mit den Azure AD-Berechtigungen zu konfigurieren.

Das Skript ist flexibel ausgelegt. Zuerst wird nach vorhandenen Plastischer Reader- und Azure AD-Ressourcen in Ihrem Abonnement gesucht, und sie werden nur nach Bedarf erstellt, wenn sie nicht bereits vorhanden sind. Wenn Sie zum ersten Mal eine Plastischer Reader-Ressource erstellen, führt das Skript alles aus, was Sie benötigen. Wenn Sie es nur zum Konfigurieren von Azure AD für eine vorhandene Plastischer Reader-Ressource verwenden möchten, die im Portal erstellt wurde, wird dies ebenfalls durchgeführt. Es kann auch verwendet werden, um mehrere Plastischer Reader-Ressourcen zu erstellen und zu konfigurieren.

Einrichten der PowerShell-Umgebung

  1. Öffnen Sie als Erstes die Azure Cloud Shell. Stellen Sie in der Dropdownliste oben links oder durch Eingabe von pwsh sicher, dass Cloud Shell auf PowerShell festgelegt ist.

  2. Kopieren Sie den folgenden Codeausschnitt, und fügen Sie ihn in die Shell ein.

    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. Führen Sie die Funktion Create-ImmersiveReaderResource aus, und stellen Sie unten den <PARAMETER_VALUES>-Platzhaltern (Parameterwerte) Ihre eigenen Werte bereit.

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

    Der vollständige Befehl sieht in etwa wie folgt aus. Hier wurde jeder Parameter aus Gründen der Übersichtlichkeit in eine eigene Zeile eingefügt, damit Sie den gesamten Befehl sehen können. Kopieren oder verwenden Sie diesen Befehl nicht unverändert. Kopieren Sie den obigen Befehl mit Ihren eigenen Werten, und verwenden Sie ihn erst dann. Dieses Beispiel enthält Pseudowerte für die oben genannten <PARAMETER_VALUES>. Ihre unterscheiden sich davon, da Sie eigene Namen für diese Werte verwenden.

    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 Kommentare
    SubscriptionName Der Name des Azure-Abonnements, das für Ihre Plastischer Reader-Ressource verwendet werden soll. Sie müssen über ein Abonnement verfügen, um eine Ressource zu erstellen.
    Ressourcenname Muss alphanumerisch sein und darf „-“ enthalten, solange „-“ nicht das erste oder letzte Zeichen ist. Die Länge darf 63 Zeichen nicht überschreiten.
    ResourceSubdomain Eine benutzerdefinierte Unterdomäne ist für Ihre Plastischer Reader-Ressource erforderlich. Die Unterdomäne wird vom SDK verwendet, wenn der Plastischer Reader-Dienst aufgerufen wird, um den Reader zu starten. Die Unterdomäne muss global eindeutig sein. Die Unterdomäne muss alphanumerisch sein und darf „-“ enthalten, solange „-“ nicht das erste oder letzte Zeichen ist. Die Länge darf 63 Zeichen nicht überschreiten. Dieser Parameter ist optional, wenn die Ressource bereits vorhanden ist.
    ResourceSKU Optionen: S0 (Standardebene) oder S1 (Bildungsorganisationen bzw. Non-Profit-Organisationen). Besuchen Sie unsere Seite Preise für Cognitive Services – Plastischer Reader, um mehr über jede verfügbare SKU zu erfahren. Dieser Parameter ist optional, wenn die Ressource bereits vorhanden ist.
    ResourceLocation Optionen: 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. Dieser Parameter ist optional, wenn die Ressource bereits vorhanden ist.
    ResourceGroupName Ressourcen werden in Ressourcengruppen in Abonnements erstellt. Geben Sie den Namen einer vorhandenen Ressourcengruppe an. Wenn die Ressourcengruppe nicht bereits vorhanden ist, wird eine neue mit diesem Namen erstellt.
    ResourceGroupLocation Wenn die Ressourcengruppe nicht vorhanden ist, müssen Sie einen Speicherort angeben, an dem die Gruppe erstellt werden soll. Verwenden Sie az account list-locations zum Abrufen einer Speicherortliste. Verwenden Sie die Eigenschaft Name (ohne Leerzeichen) des zurückgegebenen Ergebnisses. Dieser Parameter ist optional, wenn die Ressource bereits vorhanden ist.
    AADAppDisplayName Der Anzeigename der Azure Active Directory-Anwendung. Wenn eine vorhandene Azure AD-Anwendung nicht gefunden wird, wird eine neue mit diesem Namen erstellt. Dieser Parameter ist optional, wenn die Azure AD-Anwendung bereits vorhanden ist.
    AADAppIdentifierUri Der URI für die Azure AD-Anwendung. Wenn eine vorhandene Azure AD-Anwendung nicht gefunden wird, wird eine neue mit diesem URI erstellt. Beispiel: api://MyOrganizationImmersiveReaderAADApp. Hier verwenden wir das standardmäßige URI-Schemapräfix von Azure AD „api://“, um die Kompatibilität mit der Azure AD-Richtlinie zur Verwendung verifizierter Domänen zu gewährleisten.
    AADAppClientSecretExpiration Datum (date) oder Datum/Uhrzeit (datetime), nach dem/der der geheime Clientschlüssel der AAD-Anwendung (Kennwort) abläuft (z. B. „2020-12-31T11:59:59+00:00“ oder „2020-12-31“). Diese Funktion erstellt einen geheimen Clientschlüssel für Sie. Um geheime Clientschlüssel von Azure AD-Anwendungen zu verwalten, nachdem Sie diese Ressource erstellt haben, besuchen Sie https://portal.azure.com, und navigieren Sie zu „Home“ > „Azure Active Directory“ > „App-Registrierungen“ > (Ihre App) [AADAppDisplayName]> Blatt „Zertifikate und Geheimnisse“ > Abschnitt „Geheime Clientschlüssel“ (siehe Screenshot „Verwalten Ihrer Azure AD-Anwendungsgeheimnisse“ weiter unten).

    Verwalten Ihrer Azure AD-Anwendungsgeheimnisse

    Azure-Portal-Zertifikate und Blatt „Geheimnisse“

  4. Kopieren Sie die JSON-Ausgabe zur späteren Verwendung in eine Textdatei. Die Ausgabe sollte wie im folgenden Beispiel aussehen.

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

Nächste Schritte

  • Sehen Sie sich die Node.js-Schnellstartanleitung an, um zu erfahren, welche weiteren Möglichkeiten das SDK für den plastischen Reader in Verbindung mit Node.js bietet.
  • Sehen Sie sich das Android-Tutorial an, um zu erfahren, welche weiteren Möglichkeiten das SDK für den plastischen Reader in Verbindung mit Java oder Kotlin für Android bietet.
  • Sehen Sie sich das iOS-Tutorial an, um zu erfahren, welche weiteren Möglichkeiten das SDK für den plastischen Reader in Verbindung mit Swift für iOS bietet.
  • Sehen Sie sich das Python-Tutorial an, um zu erfahren, welche weiteren Möglichkeiten das SDK für den plastischen Reader in Verbindung mit Python bietet.
  • Machen Sie sich mit dem SDK für Plastischer Reader und der zugehörigen Referenz vertraut.