Share via

إنشاء مورد القارئ الشامل وتكوين مصادقة Microsoft Entra

  • مقالة

توضح هذه المقالة كيفية إنشاء مورد القارئ الشامل باستخدام البرنامج النصي المتوفر. يقوم هذا البرنامج النصي أيضا بتكوين مصادقة Microsoft Entra. في كل مرة يتم فيها إنشاء مورد القارئ الشامل، سواء باستخدام هذا البرنامج النصي أو في المدخل، يجب تكوينه باستخدام أذونات Microsoft Entra.

يقوم البرنامج النصي بإنشاء وتكوين جميع موارد القارئ الشامل وMicrosoft Entra الضرورية لك. ومع ذلك، يمكنك أيضا تكوين مصادقة Microsoft Entra لمورد القارئ الشامل موجود، إذا قمت بالفعل بإنشاء واحد في مدخل Microsoft Azure. يبحث البرنامج النصي أولا عن موارد القارئ الشامل وMicrosoft Entra الموجودة في اشتراكك، وينشئها فقط إذا لم تكن موجودة بالفعل.

بالنسبة لبعض العملاء، قد يكون من الضروري إنشاء موارد القارئ الشامل متعددة، للتطوير مقابل الإنتاج، أو ربما للمناطق المختلفة حيث يتم نشر خدمتك. بالنسبة لهذه الحالات، يمكنك العودة واستخدام البرنامج النصي عدة مرات لإنشاء موارد القارئ الشامل مختلفة وتكوينها باستخدام أذونات Microsoft Entra.

الأذونات

يمتلك مالك اشتراك Azure المدرج جميع الأذونات المطلوبة لإنشاء مورد القارئ الشامل وتكوين مصادقة Microsoft Entra.

إذا لم تكن مالكا، فإن الأذونات الخاصة بالنطاق التالية مطلوبة:

  • المساهم. يجب أن يكون لديك على الأقل دور مساهم مقترن باشتراك Azure:

    Screenshot of contributor built-in role description.

  • مطور التطبيق. يجب أن يكون لديك على الأقل دور مطور تطبيقات مقترن في معرف Microsoft Entra:

    Screenshot of the developer built-in role description.

لمزيد من المعلومات، راجع الأدوار المضمنة في Microsoft Entra.

إعداد موارد PowerShell

  1. ابدأ بفتح Azure Cloud Shell. تأكد من تعيين Cloud Shell إلى PowerShell في القائمة المنسدلة العلوية اليمنى أو بكتابة pwsh.

  2. انسخ والصق القصاصة البرمجية التالية في shell.

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

  3. قم بتشغيل الدالة 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'
    المعلمة‬ التعليقات
    اسم الاشتراك اسم اشتراك Azure لاستخدامه لمورد القارئ الشامل. يجب أن يكون لديك اشتراك لإنشاء مورد.
    ResourceName يجب أن تكون أبجدية رقمية، ويمكن أن تحتوي على -، طالما - أن ليس الحرف الأول أو الأخير. لا يمكن أن يتجاوز الطول 63 حرفا.
    ResourceSubdomain مطلوب مجال فرعي مخصص لمورد القارئ الشامل. يستخدم SDK المجال الفرعي عند استدعاء خدمة القارئ الشامل لتشغيل القارئ. يجب أن يكون المجال الفرعي فريدا عموميا. يجب أن يكون المجال الفرعي أبجديا رقميا، ويمكن أن يحتوي على -، طالما - أن ليس الحرف الأول أو الأخير. لا يمكن أن يتجاوز الطول 63 حرفا. هذه المعلمة اختيارية إذا كان المورد موجودا بالفعل.
    ResourceSKU الخيارات: S0 (المستوى القياسي) أو S1 (مؤسسات التعليم/المؤسسات غير الربحية). لمعرفة المزيد حول كل وحدة SKU متوفرة، تفضل بزيارة صفحة تسعير خدمات Azure الذكاء الاصطناعي. هذه المعلمة اختيارية إذا كان المورد موجودا بالفعل.
    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. استخدم خاصية الاسم (بدون مسافات) للنتيجة التي تم إرجاعها. هذه المعلمة اختيارية إذا كانت مجموعة الموارد موجودة بالفعل.
    AADAppDisplayName اسم عرض تطبيق Microsoft Entra. إذا لم يتم العثور على تطبيق Microsoft Entra موجود، يتم إنشاء تطبيق جديد بهذا الاسم. هذه المعلمة اختيارية إذا كان تطبيق Microsoft Entra موجودا بالفعل.
    AADAppIdentifierUri URI لتطبيق Microsoft Entra. إذا لم يتم العثور على تطبيق Microsoft Entra موجود، يتم إنشاء تطبيق جديد مع URI هذا. على سبيل المثال، api://MyOrganizationImmersiveReaderAADApp هنا نستخدم بادئة api:// نظام URI الافتراضية ل Microsoft Entra للتوافق مع نهج Microsoft Entra لاستخدام المجالات التي تم التحقق منها.
    AADAppClientSecretExpiration التاريخ أو التاريخ الذي تنتهي بعده صلاحية سر عميل تطبيق Microsoft Entra (كلمة المرور) (على سبيل المثال، '2020-12-31T11:59:59+00:00' أو '2020-12-31'). تنشئ هذه الدالة سر عميل لك.

    لإدارة أسرار عميل تطبيق Microsoft Entra بعد إنشاء هذا المورد، قم بزيارة مدخل Microsoft Azure وانتقل إلى Home ->Microsoft Entra ID ->App Registrations -> (تطبيقك) [AADAppDisplayName] ->قسم Certificates and Secrets ->Client Secrets.

    Screenshot of the Azure portal Certificates and Secrets pane.

  4. انسخ إخراج JSON إلى ملف نصي لاستخدامه لاحقا. يجب أن يبدو الناتج كما يلي.

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

الخطوة التالية

كيفية تشغيل القارئ الشامل