البرنامج التعليمي: استخدام البرامج النصية للنشر لإنشاء شهادة موقعة ذاتيا

تعرف على كيفية استخدام البرامج النصية للتوزيع في قوالب Azure Resource Manager (قوالب ARM). يمكن استخدام البرامج النصية للنشر لتنفيذ خطوات مخصصة لا يمكن تنفيذها بواسطة قوالب ARM. على سبيل المثال، إنشاء شهادة موقعة ذاتيا. في هذا البرنامج التعليمي، يمكنك إنشاء قالب لنشر مخزن مفاتيح Azure، ثم استخدام Microsoft.Resources/deploymentScripts مورد في نفس القالب لإنشاء شهادة ثم إضافة الشهادة إلى مخزن المفاتيح. لمعرفة المزيد حول البرنامج النصي للنشر، راجع استخدام البرامج النصية للنشر في قوالب ARM.

هام

يتم إنشاء موردين لبرنامج نصي للنشر، وحساب تخزين ومثيل حاوية، في نفس مجموعة الموارد لتنفيذ البرنامج النصي واستكشاف الأخطاء وإصلاحها. عادة ما يتم حذف هذه الموارد بواسطة خدمة البرنامج النصي عندما يصبح تنفيذ البرنامج النصي في حالة طرفية. تتم محاسبتك على الموارد حتى يتم حذف الموارد. لمعرفة المزيد، راجع تنظيف موارد البرنامج النصي للنشر.

يغطي هذا البرنامج التعليمي المهام التالية:

فتح قالب بدء سريع
تحرير القالب
نشر القالب
تصحيح أخطاء البرنامج النصي الفاشل
تنظيف الموارد

للحصول على وحدة Learn النمطية التي تغطي البرامج النصية للنشر، راجع توسيع قوالب ARM باستخدام البرامج النصية للنشر.

المتطلبات الأساسية

لإكمال هذه المقالة ، تحتاج إلى:

كود الاستوديو المرئي.
هوية مدارة معينة من قبل المستخدم. تستخدم هذه الهوية لتنفيذ إجراءات خاصة ب Azure في البرنامج النصي. لإنشاء واحدة، راجع الهوية المدارة المعينة من قبل المستخدم. تحتاج إلى معرف الهوية عند نشر القالب. شكل الهوية هو:
```
/subscriptions/<SubscriptionID>/resourcegroups/<ResourceGroupName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<IdentityID>
```
استخدم البرنامج النصي CLI التالي للحصول على المعرف عن طريق توفير اسم مجموعة الموارد واسم الهوية.
- المبادره القطريه
- بوويرشيل
```
echo "Enter the Resource Group name:" &&
read resourceGroupName &&
az identity list -g $resourceGroupName
```
```
$resourceGroupName = Read-Host -Prompt "Enter the Resource Group name"
(Get-AzUserAssignedIdentity -ResourceGroupName $resourceGroupname).id

Write-Host "Press [ENTER] to continue ..."
```

فتح قالب التشغيل السريع

بدلا من إنشاء قالب من البداية، يمكنك فتح قالب من قوالب Azure Quickstart. قوالب Azure Quickstart هي مستودع لقوالب ARM.

يسمى القالب المستخدم في هذا التشغيل السريع إنشاء Azure Key Vault وسر. يقوم القالب بإنشاء مخزن مفاتيح، ثم يضيف سرا إلى مخزن المفاتيح.

من Visual Studio Code، حدد ملف>مفتوح ملف.

في اسم الملف، الصق عنوان URL التالي:

https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.keyvault/key-vault-create/azuredeploy.json

حدد فتح لفتح الملف.
حدد ملف>حفظ باسم لحفظ الملف azuredeploy.json على جهاز الكمبيوتر المحلي الخاص بك.

تحرير القالب

قم بإجراء التغييرات التالية على القالب:

تنظيف القالب (اختياري)

يضيف القالب الأصلي سرا إلى مخزن المفاتيح. لتبسيط البرنامج التعليمي، قم بإزالة المورد التالي:

Microsoft.KeyVault/vaults/secrets

قم بإزالة تعريفي المعلمات التاليين:

secretName
secretValue

إذا اخترت عدم إزالة هذه التعريفات، فستحتاج إلى تحديد قيم المعلمات أثناء النشر.

تكوين نهج الوصول إلى مخزن المفاتيح

يضيف البرنامج النصي للنشر شهادة إلى مخزن المفاتيح. قم بتكوين نهج الوصول إلى مخزن المفاتيح لمنح الإذن للهوية المدارة:

أضف معلمة للحصول على معرف الهوية المدارة:

"identityId": {
  "type": "string",
  "metadata": {
    "description": "Specifies the ID of the user-assigned managed identity."
  }
},

أضف معلمة لتكوين نهج الوصول إلى مخزن المفاتيح بحيث يمكن للهوية المدارة إضافة شهادات إلى مخزن المفاتيح:

"certificatesPermissions": {
  "type": "array",
  "defaultValue": [
    "get",
    "list",
    "update",
    "create"
  ],
  "metadata": {
  "description": "Specifies the permissions to certificates in the vault. Valid values are: all, get, list, update, create, import, delete, recover, backup, restore, manage contacts, manage certificate authorities, get certificate authorities, list certificate authorities, set certificate authorities, delete certificate authorities."
  }
}

قم بتحديث نهج الوصول إلى مخزن المفاتيح الحالية للمورد Microsoft.KeyVault/vaults إلى:

"accessPolicies": [
  {
    "objectId": "[parameters('objectId')]",
    "tenantId": "[parameters('tenantId')]",
    "permissions": {
      "keys": "[parameters('keysPermissions')]",
      "secrets": "[parameters('secretsPermissions')]",
      "certificates": "[parameters('certificatesPermissions')]"
    }
  },
  {
    "objectId": "[reference(parameters('identityId'), '2018-11-30').principalId]",
    "tenantId": "[parameters('tenantId')]",
    "permissions": {
      "keys": "[parameters('keysPermissions')]",
      "secrets": "[parameters('secretsPermissions')]",
      "certificates": "[parameters('certificatesPermissions')]"
    }
  }
],

هناك نهجان محددان، أحدهما للمستخدم الذي قام بتسجيل الدخول، والآخر للهوية المدارة. يحتاج المستخدم الذي قام بتسجيل الدخول فقط إلى إذن القائمة للتحقق من النشر. لتبسيط البرنامج التعليمي، يتم تعيين نفس الشهادة لكل من الهوية المدارة والمستخدمين الذين قاموا بتسجيل الدخول.

إضافة البرنامج النصي للنشر

أضف ثلاث معلمات يستخدمها البرنامج النصي للنشر:

"certificateName": {
  "type": "string",
  "defaultValue": "DeploymentScripts2019"
},
"subjectName": {
  "type": "string",
  "defaultValue": "CN=contoso.com"
},
"utcValue": {
  "type": "string",
  "defaultValue": "[utcNow()]"
}

إضافة deploymentScripts مورد:

‏‫‏‫‏‫‏‫‏‫ملاحظة

نظرا لأن البرامج النصية للنشر المضمنة محاطة بعلامات اقتباس مزدوجة، يجب أن تكون السلاسل الموجودة داخل البرامج النصية للنشر محاطة بعلامات اقتباس مفردة بدلا من ذلك. حرف الهروب من PowerShell هو الرمز الخلفي (`).
```
{
  "type": "Microsoft.Resources/deploymentScripts",
  "apiVersion": "2023-08-01",
  "name": "createAddCertificate",
  "location": "[resourceGroup().location]",
  "dependsOn": [
    "[resourceId('Microsoft.KeyVault/vaults', parameters('keyVaultName'))]"
  ],
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "[parameters('identityId')]": {
      }
    }
  },
  "kind": "AzurePowerShell",
  "properties": {
    "forceUpdateTag": "[parameters('utcValue')]",
    "azPowerShellVersion": "3.0",
    "timeout": "PT30M",
    "arguments": "[format(' -vaultName {0} -certificateName {1} -subjectName {2}', parameters('keyVaultName'), parameters('certificateName'), parameters('subjectName'))]", // can pass an argument string, double quotes must be escaped
    "scriptContent": "
      param(
        [string] [Parameter(Mandatory=$true)] $vaultName,
        [string] [Parameter(Mandatory=$true)] $certificateName,
        [string] [Parameter(Mandatory=$true)] $subjectName
      )

      $ErrorActionPreference = 'Stop'
      $DeploymentScriptOutputs = @{}

      $existingCert = Get-AzKeyVaultCertificate -VaultName $vaultName -Name $certificateName

      if ($existingCert -and $existingCert.Certificate.Subject -eq $subjectName) {

        Write-Host 'Certificate $certificateName in vault $vaultName is already present.'

        $DeploymentScriptOutputs['certThumbprint'] = $existingCert.Thumbprint
        $existingCert | Out-String
      }
      else {
        $policy = New-AzKeyVaultCertificatePolicy -SubjectName $subjectName -IssuerName Self -ValidityInMonths 12 -Verbose

        # private key is added as a secret that can be retrieved in the Resource Manager template
        Add-AzKeyVaultCertificate -VaultName $vaultName -Name $certificateName -CertificatePolicy $policy -Verbose

        # it takes a few seconds for KeyVault to finish
        $tries = 0
        do {
          Write-Host 'Waiting for certificate creation completion...'
          Start-Sleep -Seconds 10
          $operation = Get-AzKeyVaultCertificateOperation -VaultName $vaultName -Name $certificateName
          $tries++

          if ($operation.Status -eq 'failed')
          {
            throw 'Creating certificate $certificateName in vault $vaultName failed with error $($operation.ErrorMessage)'
          }

          if ($tries -gt 120)
          {
            throw 'Timed out waiting for creation of certificate $certificateName in vault $vaultName'
          }
        } while ($operation.Status -ne 'completed')

        $newCert = Get-AzKeyVaultCertificate -VaultName $vaultName -Name $certificateName
        $DeploymentScriptOutputs['certThumbprint'] = $newCert.Thumbprint
        $newCert | Out-String
      }
    ",
    "cleanupPreference": "OnSuccess",
    "retentionInterval": "P1D"
  }
}
```
يعتمد المورد deploymentScripts على مورد مخزن المفاتيح ومورد تعيين الدور. لها هذه الخصائص:
- identityيستخدم البرنامج النصي للنشر هوية مدارة معينة من قبل المستخدم لتنفيذ العمليات في البرنامج النصي.:
- kindحدد نوع البرنامج النصي.: حاليا، يتم دعم البرامج النصية PowerShell فقط.
- forceUpdateTagحدد ما إذا كان يجب تنفيذ البرنامج النصي للنشر حتى إذا لم يتغير مصدر البرنامج النصي.: يمكن أن يكون الطابع الزمني الحالي أو GUID. لمعرفة المزيد، راجع تشغيل البرنامج النصي أكثر من مرة.
- azPowerShellVersionيحدد إصدار الوحدة النمطية Azure PowerShell المراد استخدامه.: حاليا، يدعم البرنامج النصي للنشر الإصدار 2.7.0 و2.8.0 و3.0.0.
- timeoutحدد الحد الأقصى المسموح به لوقت تنفيذ البرنامج النصي المحدد بتنسيق ISO 8601.: القيمة الافتراضية هي P1D.
- argumentsحدد قيم المعلمات.: يتم فصل القيم بمسافات.
- scriptContentحدد محتوى البرنامج النصي.: لتشغيل برنامج نصي خارجي، استخدم primaryScriptURI بدلا من ذلك. لمزيد من المعلومات، راجع استخدام البرنامج النصي الخارجي. $DeploymentScriptOutputs الإعلان مطلوب فقط عند اختبار البرنامج النصي على جهاز محلي. يسمح الإعلان عن المتغير بتشغيل البرنامج النصي على جهاز محلي وفي مورد deploymentScript دون الحاجة إلى إجراء تغييرات. تتوفر القيمة المعينة كمخرجات $DeploymentScriptOutputs في عمليات النشر. لمزيد من المعلومات، راجع العمل مع المخرجات من البرامج النصية لنشر PowerShell أو العمل مع المخرجات من البرامج النصية لنشر CLI.
- cleanupPreferenceحدد التفضيل عند حذف موارد البرنامج النصي للنشر.: القيمة الافتراضية هي دائما، مما يعني حذف موارد البرنامج النصي للتوزيع على الرغم من حالة المحطة الطرفية (نجح، فشل، ملغا). في هذا البرنامج التعليمي، يتم استخدام OnSuccess بحيث تحصل على فرصة لعرض نتائج تنفيذ البرنامج النصي.
- retentionIntervalحدد الفاصل الزمني الذي تحتفظ فيه الخدمة بموارد البرنامج النصي بعد وصولها إلى حالة المحطة الطرفية.: سيتم حذف الموارد عند انتهاء هذه المدة. تعتمد المدة على نمط ISO 8601. يستخدم هذا البرنامج التعليمي P1D ، مما يعني يوما ما. يتم استخدام هذه الخاصية عند cleanupPreference تعيينها إلى OnExpiration. هذه الخاصية غير ممكنة حاليا.
يأخذ البرنامج النصي للنشر ثلاث معلمات: keyVaultName، certificateNameو.subjectName يقوم بإنشاء شهادة، ثم يضيف الشهادة إلى مخزن المفاتيح.

$DeploymentScriptOutputs يستخدم لتخزين قيمة الإخراج. لمعرفة المزيد، راجع العمل مع المخرجات من البرامج النصية لنشر PowerShell أو العمل مع المخرجات من البرامج النصية لنشر CLI.

يمكن العثور على القالب المكتمل هنا.
للاطلاع على عملية تصحيح الأخطاء، ضع خطأ في التعليمات البرمجية عن طريق إضافة السطر التالي إلى البرنامج النصي للنشر:
```
Write-Output1 $keyVaultName
```
الأمر الصحيح هو Write-Output بدلا من Write-Output1.
حدد حفظ الملف> لحفظ الملف.

نشر القالب

سجل الدخول إلى Azure Cloud Shell
اختر بيئتك المفضلة عن طريق تحديد إما PowerShell أو Bash (ل CLI) في الزاوية العلوية اليمنى. يلزم إعادة تشغيل الغلاف عند التبديل.
حدد تحميل/تنزيل الملفات، ثم حدد تحميل. انظر لقطة الشاشة السابقة. حدد الملف الذي قمت بحفظه في القسم السابق. بعد تحميل الملف ، يمكنك استخدام ls الأمر والأمر cat للتحقق من تحميل الملف بنجاح.

قم بتشغيل البرنامج النصي Azure CLI أو Azure PowerShell التالي لنشر القالب.

المبادره القطريه
بوويرشيل

echo "Enter a project name that is used to generate resource names:" &&
read projectName &&
echo "Enter the location (i.e. centralus):" &&
read location &&
echo "Enter your email address used to sign in to Azure:" &&
read upn &&
echo "Enter the user-assigned managed identity ID:" &&
read identityId &&
adUserId=$((az ad user show --id ${upn}) | jq -r '.id') &&
resourceGroupName="${projectName}rg" &&
keyVaultName="${projectName}kv" &&
az group create --name $resourceGroupName --location $location &&
az deployment group create --resource-group $resourceGroupName --template-file "$HOME/azuredeploy.json" --parameters identityId=$identityId keyVaultName=$keyVaultName objectId=$adUserId

$projectName = Read-Host -Prompt "Enter a project name that is used to generate resource names"
$location = Read-Host -Prompt "Enter the location (i.e. centralus)"
$upn = Read-Host -Prompt "Enter your email address used to sign in to Azure"
$identityId = Read-Host -Prompt "Enter the user-assigned managed identity ID"

$adUserId = (Get-AzADUser -UserPrincipalName $upn).Id
$resourceGroupName = "${projectName}rg"
$keyVaultName = "${projectName}kv"

New-AzResourceGroup -Name $resourceGroupName -Location $location

New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName -TemplateFile "$HOME/azuredeploy.json" -identityId $identityId -keyVaultName $keyVaultName -objectId $adUserId

Write-Host "Press [ENTER] to continue ..."

تحتاج خدمة البرنامج النصي للنشر إلى إنشاء موارد إضافية لبرنامج نصي للنشر لتنفيذ البرنامج النصي. يمكن أن تستغرق عملية التحضير والتنظيف ما يصل إلى دقيقة واحدة لإكمالها بالإضافة إلى وقت تنفيذ البرنامج النصي الفعلي.

فشل النشر لأنه يتم استخدام الأمر Write-Output1 غير صالح في البرنامج النصي. ستحصل على خطأ يقول:

The term 'Write-Output1' is not recognized as the name of a cmdlet, function, script file, or operable
program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

يتم تخزين نتيجة تنفيذ البرنامج النصي للنشر في موارد البرنامج النصي للنشر لغرض استكشاف الأخطاء وإصلاحها.

تصحيح أخطاء البرنامج النصي الفاشل

قم بتسجيل الدخول إلى بوابة Azure.
افتح مجموعة الموارد. إنه اسم المشروع مع rg الملحق. سترى موردين إضافيين في مجموعة الموارد. يشار إلى هذه الموارد باسم موارد البرنامج النصي للتوزيع.

كلا الملفين لهما لاحقة azscripts . أحدهما هو حساب تخزين والآخر مثيل حاوية.

حدد إظهار الأنواع المخفية لإدراج المورد deploymentScripts .
حدد حساب التخزين الذي يحتوي على لاحقة azscripts .
حدد لوحة مشاركات الملفات . سترى مجلد azscripts يحتوي على ملفات تنفيذ البرنامج النصي للنشر.
حدد azscripts. سترى مجلدين azscriptinput و azscriptoutput. يحتوي مجلد الإدخال على ملف برنامج نصي PowerShell للنظام وملفات البرنامج النصي لنشر المستخدم. يحتوي مجلد الإخراج على executionresult.json وملف إخراج البرنامج النصي. يمكنك رؤية رسالة الخطأ في executionresult.json. ملف الإخراج غير موجود بسبب فشل التنفيذ.

قم بإزالة السطر Write-Output1 وإعادة توزيع القالب.

عند تشغيل التوزيع الثاني بنجاح، ستتم إزالة موارد البرنامج النصي للتوزيع بواسطة خدمة البرنامج النصي، لأنه cleanupPreference تم تعيين الخاصية إلى OnSuccess.

تنظيف الموارد

عندما لا تكون هناك حاجة إلى موارد Azure، قم بتنظيف الموارد التي قمت بنشرها عن طريق حذف مجموعة الموارد.

من مدخل Microsoft Azure، حدد مجموعة الموارد من القائمة اليسرى.
أدخل اسم مجموعة الموارد في حقل التصفية حسب الاسم .
حدد اسم مجموعة الموارد.
حدد حذف مجموعة الموارد من القائمة العلوية.

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

في هذا البرنامج التعليمي، تعلمت كيفية استخدام برنامج نصي للنشر في قوالب ARM. لمعرفة كيفية توزيع موارد Azure استنادا إلى الشروط، راجع:

شروط الاستخدام

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2025-10-29