Immersive Reader 리소스 만들기 및 Microsoft Entra 인증 구성

아티클
10/16/2024

이 문서에서는 제공된 스크립트를 사용하여 Immersive Reader 리소스를 만드는 방법을 설명합니다. 이 스크립트는 Microsoft Entra 인증도 구성합니다. 이 스크립트를 사용하든 포털에서든 Immersive Reader 리소스를 만들 때마다 Microsoft Entra 권한으로 구성해야 합니다.

스크립트는 필요한 모든 Immersive Reader 및 Microsoft Entra 리소스를 만들고 구성합니다. 그러나 Azure Portal에서 이미 만든 경우 기존 Immersive Reader 리소스에 대한 Microsoft Entra 인증을 구성할 수도 있습니다. 스크립트는 먼저 구독에서 기존 Immersive Reader 및 Microsoft Entra 리소스를 찾고, 아직 없는 경우에만 만듭니다.

일부 고객에 대해서는 개발용 및 프로덕션용으로 또는 아마도 서비스가 배포되는 다른 지역용으로 여러 개의 Immersive Reader 리소스를 만들어야 할 수 있습니다. 이러한 경우 다시 돌아와서 스크립트를 여러 번 사용하여 다른 Immersive Reader 리소스를 만들고 Microsoft Entra 권한으로 구성할 수 있습니다.

사용 권한

나열된 Azure 구독의 소유자는 Immersive Reader 리소스를 만들고 Microsoft Entra 인증을 구성하는 데 필요한 모든 권한을 가지고 있습니다.

소유자가 아닌 경우 다음과 같은 범위별 권한이 필요합니다.

Contributor. 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`(표준 계층) 또는 `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를 시작하는 방법

다음을 통해 공유

Immersive Reader 리소스 만들기 및 Microsoft Entra 인증 구성

사용 권한

PowerShell 리소스 설정

다음 단계

피드백

추가 리소스