Immersive Reader リソースを作成して Microsoft Entra 認証を構成する

[アーティクル]
02/22/2024

この記事では、提供されたスクリプトを使用して Immersive Reader リソースを作成する方法について説明します。このスクリプトでは、Microsoft Entra 認証も構成します。このスクリプトとポータルのどちらを使用した場合でも、Immersive Reader リソースが作成されるたびに、Microsoft Entra のアクセス許可を構成する必要があります。

このスクリプトは、必要なすべての Immersive Reader と Microsoft Entra リソースを作成して構成します。ただし、Azure portal で既に Immersive Reader リソースを作成している場合は、既存の Immersive Reader リソースに対して Microsoft Entra 認証を構成することもできます。このスクリプトは最初に、サブスクリプション内で既存の Immersive Reader と Microsoft Entra リソースを探し、まだ存在しておらず必要な場合にのみ作成します。

お客様によっては、開発向けと運用向け、またはサービスのデプロイ先となる異なるリージョン向けなど、複数の Immersive Reader リソースを作成しなければならない場合もあります。そのような場合は、スクリプトを複数回使用してさまざまな Immersive Reader リソースを作成し、Microsoft Entra のアクセス許可を構成することができます。

アクセス許可

一覧表示されている Azure サブスクリプションの所有者には、Immersive Reader リソースの作成と Microsoft Entra 認証の構成に必要なすべてのアクセス許可があります。

所有者でない場合は、次のスコープ固有のアクセス許可が必要です。

共同作成者。 Azure サブスクリプションに、少なくとも共同作成者ロールが関連付けられている必要があります。
アプリケーション開発者。 Microsoft Entra ID に、少なくとも次のアプリケーション開発者ロールが関連付けられている必要があります。

詳細については、「Microsoft Entra 組み込みロール」を参照してください。

PowerShell のセットアップリソース

まず、Azure Cloud Shell を開きます。左上のドロップダウンを参照するか、「pwsh」と入力して、Cloud Shell が PowerShell に設定されていることを確認します。

以下のコードスニペットをコピーしてシェルに貼り付けます。

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

関数 Create-ImmersiveReaderResource を実行し、'<PARAMETER_VALUES>' プレースホルダーには、必要に応じて独自の値を指定します。

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

コマンド全体は次のようになります。こちらでは、わかりやすくするためにパラメーターごとに改行しているので、コマンド全体を確認できます。 このコマンドをこのままコピーしたり、使用したりしないでください。 コマンドをコピーし、独自の値を指定して使用してください。この例では、<PARAMETER_VALUES> に対してダミーの値が使用されています。これらの値には独自の名前を使用するので、実際はこれとは異なるかもしれません。

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'

パラメーター	説明
SubscriptionName	イマーシブリーダーリソースで使用する Azure サブスクリプションの名前。リソースを作成するには、サブスクリプションが必要です。
ResourceName	英数字を使用する必要があります。`-` が最初や最後の文字でなければ、"`-`" を含めることができます。長さは 63 文字を超えることはできません。
ResourceSubdomain	イマーシブリーダーリソースには、カスタムサブドメインが必要です。サブドメインは、イマーシブリーダーサービスを呼び出してリーダーを起動する際に、SDK によって使用されます。サブドメインはグローバルに一意である必要があります。サブドメインには英数字を使用する必要があります。`-` が最初や最後の文字でなければ、"`-`" を含めることができます。長さは 63 文字を超えることはできません。リソースが既に存在する場合、このパラメーターは省略可能です。
ResourceSKU	オプション:`S0` (Standard レベル) または `S1` (教育/非営利組織)。使用可能な各 SKU の詳細については、「Azure AI サービスの価格に関するページ」を参照してください。リソースが既に存在する場合、このパラメーターは省略可能です。
ResourceLocation	オプションは、`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` です。リソースが既に存在する場合、このパラメーターは省略可能です。
ResourceGroupName	リソースは、サブスクリプション内のリソースグループに作成されます。既存のリソースグループの名前を指定します。リソースグループがまだ存在しない場合は、この名前で新たに作成されます。
ResourceGroupLocation	リソースグループが存在しない場合は、グループの作成先の場所を指定する必要があります。場所の一覧を表示するには、`az account list-locations` を実行します。返された結果の name プロパティ (スペースなし) を使用します。リソースグループが既に存在する場合、このパラメーターは省略可能です。
AADAppDisplayName	Microsoft Entra アプリケーションの表示名。既存の Microsoft Entra アプリケーションが見つからない場合は、この名前で新たに作成されます。 Microsoft Entra アプリケーションが既に存在する場合、このパラメーターは省略可能です。
AADAppIdentifierUri	Microsoft Entra アプリケーションの URI。既存の Microsoft Entra アプリケーションが見つからない場合は、この URI で新たに作成されます。たとえば、`api://MyOrganizationImmersiveReaderAADApp` のようにします。ここでは、検証済みドメインを使用する Microsoft Entra ポリシーに対応するように、既定の Microsoft Entra URI スキームのプレフィックス `api://` を使用しています。
AADAppClientSecretExpiration	Microsoft Entra アプリケーションクライアントシークレット (パスワード) の有効期限が切れる日付または日時 (例: '2020-12-31T11:59:59+00:00' または '2020-12-31')。この関数により、クライアントシークレットが作成されます。

このリソースを作成した後で Microsoft Entra アプリケーションクライアントシークレットを管理するには、Azure portal にアクセスし、[ホーム] - >[Microsoft Entra ID] - >[アプリの登録] - > (あなたのアプリ) [AADAppDisplayName] ‐ >[証明書とシークレット] セクション ->[クライアントシークレット] セクションに移動します。

後で使用するために、JSON 出力をテキストファイルにコピーします。出力は次のようになります。
```
{
  "TenantId": "...",
  "ClientId": "...",
  "ClientSecret": "...",
  "Subdomain": "..."
}
```

次のステップ

Immersive Reader の起動方法

Share via

Immersive Reader リソースを作成して Microsoft Entra 認証を構成する

アクセス許可

PowerShell のセットアップリソース

次のステップ

その他のリソース

Share via

Immersive Reader リソースを作成して Microsoft Entra 認証を構成する

アクセス許可

PowerShell のセットアップ リソース

次のステップ

その他のリソース

PowerShell のセットアップリソース