كيفية إدارة التعيينات باستخدام PowerShell

مقالة
09/07/2023

هام

في 11 يوليو 2026، سيتم إهمال المخططات (إصدار أولي). قم بترحيل تعريفات المخططات والتعيينات الموجودة إلى مواصفات القالب ومكدسات التوزيع. سيتم تحويل البيانات الاصطناعية للمخطط إلى قوالب ARM JSON أو ملفات Bicep المستخدمة لتعريف مكدسات التوزيع. لمعرفة كيفية تأليف أداة كمورد ARM، راجع:

يمكن إدارة تعيين مخطط باستخدام الوحدة النمطية Azure PowerShell Az.Blueprint. تدعم الوحدة إحضار التعيينات وإنشائها وتحديثها وإزالتها. يمكن للوحدة النمطية أيضاً إحضار تفاصيل حول تعريفات المخطط الموجودة. تتناول هذه المقالة كيفية تثبيت الوحدة النمطية والبدء في استخدامها.

إضافة الوحدة النمطية Az.Blueprint

لتمكين Azure PowerShell لإدارة تعيينات المخطط، يجب إضافة الوحدة النمطية. يمكن استخدام هذه الوحدة مع PowerShell المثبت محلياً، أو مع Azure Cloud Shell، أو مع صورة Azure PowerShell Docker.

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

تتطلب وحدة مخططات Azure البرنامج التالي:

Azure PowerShell 1.5.0 أو أعلى. إذا لم يثبت بعد، اتبع هذه الإرشادات.
تثبيت PowerShellGet 2.0.1 أو أعلى. إذا لم يثبت أو يحدث بعد، اتبع هذه الإرشادات.

تثبيت الوحدة

الوحدة النمطية Azure Blueprints لـ PowerShell هي Az.Blueprint.

من موجه PowerShell إدارة قم بتشغيل الأمر التالي:
```
# Install the Azure Blueprints module from PowerShell Gallery
Install-Module -Name Az.Blueprint
```
ملاحظة

إذا كان Az.Accounts مثبتاً بالفعل، فقد يكون من الضروري استخدام -AllowClobber لفرض التثبيت.
التحقق من صحة أن الوحدة النمطية قد تم استيرادها وأنها الإصدار الصحيح (0.2.6):
```
# Get a list of commands for the imported Az.Blueprint module
Get-Command -Module 'Az.Blueprint' -CommandType 'Cmdlet'
```

الحصول على تعريفات المخطط

غالباً ما تكون الخطوة الأولى للعمل مع أي تعيين هي الحصول على مرجع إلى تعريف مخطط. يحصل cmdlet Get-AzBlueprint على تعريف مخطط واحد أو أكثر. يمكن أن يحصل cmdlet على تعريفات المخطط من مجموعة إدارة مع -ManagementGroupId {mgId} أو اشتراك مع -SubscriptionId {subId}. تحصل معلمة الاسم على تعريف مخطط، ولكن يجب استخدامها مع ManagementGroupId أو SubscriptionId. يمكن استخدام الإصدار مع الاسم ليكون أكثر وضوحاً حول تعريف المخطط الذي يتم إرجاعه. بدلاً من الإصدار، يستحوذ مفتاح التبديل -LatestPublished على أحدث إصدار تم نشره.

يستخدم المثال التالي Get-AzBlueprint للحصول على جميع إصدارات تعريف المخطط المسمى "101-blueprints-definition-subscription" من اشتراك معين ممثل ليكون {subId}:

# Login first with Connect-AzAccount if not using Cloud Shell

# Get all versions of the blueprint definition in the specified subscription
$blueprints = Get-AzBlueprint -SubscriptionId '{subId}' -Name '101-blueprints-definition-subscription'

# Display the blueprint definition object
$blueprints

يبدو إخراج المثال لتعريف مخطط بإصدارات متعددة كما يلي:

Name                 : 101-blueprints-definition-subscription
Id                   : /subscriptions/{subId}/providers/Microsoft.Blueprint/blueprints/101
                       -blueprints-definition-subscription
DefinitionLocationId : {subId}
Versions             : {1.0, 1.1}
TimeCreated          : 2019-02-25
TargetScope          : Subscription
Parameters           : {storageAccount_storageAccountType, storageAccount_location,
                       allowedlocations_listOfAllowedLocations, [Usergrouporapplicationname]:Reader_RoleAssignmentName}
ResourceGroups       : ResourceGroup

يمكن توسيع معلمات المخطط على تعريف المخطط لتوفير مزيد من المعلومات.

$blueprints.Parameters

Key                                                    Value
---                                                    -----
storageAccount_storageAccountType                      Microsoft.Azure.Commands.Blueprint.Models.PSParameterDefinition
storageAccount_location                                Microsoft.Azure.Commands.Blueprint.Models.PSParameterDefinition
allowedlocations_listOfAllowedLocations                Microsoft.Azure.Commands.Blueprint.Models.PSParameterDefinition
[Usergrouporapplicationname]:Reader_RoleAssignmentName Microsoft.Azure.Commands.Blueprint.Models.PSParameterDefinition

الحصول على تعيينات المخطط

إذا كان تعيين المخطط موجوداً بالفعل، يمكنك الحصول على مرجع إليه باستخدام Get-AzBlueprintAssignment cmdlet. يأخذ cmdlet SubscriptionId و Name كمعلمات اختيارية. إذا لم يتم تحديد SubscriptionId، يتم استخدام سياق الاشتراك الحالي.

يستخدم المثال التالي Get-AzBlueprintAssignment للحصول على تعيين مخطط واحد يسمى "Assignment-lock-resource-groups" من اشتراك معين ممثل ليكون {subId}:

# Login first with Connect-AzAccount if not using Cloud Shell

# Get the blueprint assignment in the specified subscription
$blueprintAssignment = Get-AzBlueprintAssignment -SubscriptionId '{subId}' -Name 'Assignment-lock-resource-groups'

# Display the blueprint assignment object
$blueprintAssignment

يبدو إخراج المثال لتعيين مخطط كما يلي:

Name              : Assignment-lock-resource-groups
Id                : /subscriptions/{subId}/providers/Microsoft.Blueprint/blueprintAssignme
                    nts/Assignment-lock-resource-groups
Scope             : /subscriptions/{subId}
LastModified      : 2019-02-19
LockMode          : AllResourcesReadOnly
ProvisioningState : Succeeded
Parameters        :
ResourceGroups    : ResourceGroup

إنشاء تعيينات المخطط

إذا لم يكن تعيين المخطط موجوداً بعد، يمكنك إنشاؤه باستخدام New-AzBlueprintAssignment cmdlet. يستخدم cmdlet هذا المعلمات التالية:

الاسم [مطلوب]
- تحديد اسم تعيين المخطط
- يجب أن يكون فريداً وغير موجود بالفعل في SubscriptionId
المخطط [مطلوب]
- تحديد تعريف المخطط المراد تعيينه
- استخدم Get-AzBlueprint للحصول على العنصر المرجعي
الموقع [مطلوب]
- تحديد المنطقة للهوية المدارة المعينة من قبل النظام وعنصر توزيع الاشتراك المراد إنشاؤه في
الاشتراك (اختياري)
- تحديد الاشتراك الذي يتم توزيع التعيين فيه
- إذا لم يتم توفيره، فسيتم تعيين الإعدادات بشكل افتراضي إلى سياق الاشتراك الحالي
التأمين (اختياري)
- تعريف تأمين موارد المخطط للاستخدام للموارد الموزعة
- الخيارات المدعومة: بلا، AllResourcesReadOnly، AllResourcesDoNotDelete
- إذا لم يتم توفيرها، فسيتم تعيين الإعدادات بشكل افتراضي إلى بلا
SystemAssignedIdentity (اختياري)
- حدد لإنشاء هوية مدارة يعينها النظام للتعيين ولتوزيع الموارد
- افتراضي لمجموعة معلمات "الهوية"
- لا يمكن الاستخدام مع UserAssignedIdentity
UserAssignedIdentity (اختياري)
- تحديد الهوية المدارة المعينة من قبل المستخدم لاستخدامها في التعيين وتوزيع الموارد
- جزء من مجموعة معلمات "الهوية"
- لا يمكن الاستخدام مع SystemAssignedIdentity
المعلمة (اختياري)
- جدول تجزئة لأزواج المفاتيح/القيم لتعيين المعلمات الديناميكية في تعيين المخطط
- الافتراضي لأي معلمة ديناميكية هو defaultValue في التعريف
- إذا لم يتم توفير معلمة وليس لها defaultValue، فإن المعلمة ليست اختيارية
  
  ملاحظة
  
  لا تدعم المعلمة secureStrings.
ResourceGroupParameter (اختياري)
- جدول تجزئة للبيانات الاصطناعية لمجموعة الموارد
- يحتوي كل عنصر نائب للبيانات الاصطناعية لمجموعة الموارد على أزواج مفاتيح/قيمة لإعداد الاسم و الموقع ديناميكياً على البيانات الاصطناعية لمجموعة الموارد هذه
- إذا لم يتم توفير معلمة مجموعة موارد ولم يكن لها defaultValue، فإن معلمة مجموعة الموارد ليست اختيارية
AssignmentFile (اختياري)
- المسار إلى تمثيل ملف JSON لتعيين مخطط
- هذه المعلمة هي جزء من مجموعة معلمات PowerShell التي تتضمن الاسم و المخطط و SubscriptionId فقط، بالإضافة إلى المعلمات الشائعة.

مثال 1: توفير المعلمات

ينشئ المثال التالي تعييناً جديداً للإصدار "1.1" من تعريف مخطط "my-blueprint" الذي تم إحضاره باستخدام Get-AzBlueprint، ويعين موقع عنصر التعيين والهوية المدارة إلى "westus2"، ويؤمن الموارد بواسطة AllResourcesReadOnly، ويعين جداول التجزئة لكل من المعلمة و ResourceGroupParameter على اشتراك معين ممثل ليكون {subId}:

# Login first with Connect-AzAccount if not using Cloud Shell

# Get version '1.1' of the blueprint definition in the specified subscription
$bpDefinition = Get-AzBlueprint -SubscriptionId '{subId}' -Name 'my-blueprint' -Version '1.1'

# Create the hash table for Parameters
$bpParameters = @{storageAccount_storageAccountType='Standard_GRS'}

# Create the hash table for ResourceGroupParameters
# ResourceGroup is the resource group artifact placeholder name
$bpRGParameters = @{ResourceGroup=@{name='storage_rg';location='westus2'}}

# Create the new blueprint assignment
$bpAssignment = New-AzBlueprintAssignment -Name 'my-blueprint-assignment' -Blueprint $bpDefinition `
    -SubscriptionId '{subId}' -Location 'westus2' -Lock AllResourcesReadOnly `
    -Parameter $bpParameters -ResourceGroupParameter $bpRGParameters

يبدو إخراج المثال لإنشاء تعيين مخطط كما يلي:

Name              : my-blueprint-assignment
Id                : /subscriptions/{subId}/providers/Microsoft.Blueprint/blueprintAssi
                    gnments/my-blueprint-assignment
Scope             : /subscriptions/{subId}
LastModified      : 2019-03-13
LockMode          : AllResourcesReadOnly
ProvisioningState : Creating
Parameters        : {storageAccount_storageAccountType}
ResourceGroups    : ResourceGroup

مثال 2: استخدام ملف تعريف تعيين JSON

ينشئ المثال التالي نفس التعيين تقريباً مثل المثال 1. بدلاً من تمرير المعلمات إلى cmdlet، يوضح المثال استخدام ملف تعريف تعيين JSON والمعلمة AssignmentFile. بالإضافة إلى ذلك، يتم تكوين الخاصية excludedPrincipals كجزء من التأمينات. لا توجد معلمة PowerShell من أجل excludedPrincipals ولا يمكن تكوين الخاصية إلا عن طريق تعيينها من خلال ملف تعريف تعيين JSON.

{
  "identity": {
    "type": "SystemAssigned"
  },
  "location": "westus2",
  "properties": {
    "description": "Assignment of the 101-blueprint-definition-subscription",
    "blueprintId": "/subscriptions/{subId}/providers/Microsoft.Blueprint/blueprints/101-blueprints-definition-subscription",
    "locks": {
      "mode": "AllResourcesReadOnly",
      "excludedPrincipals": [
          "7be2f100-3af5-4c15-bcb7-27ee43784a1f",
          "38833b56-194d-420b-90ce-cff578296714"
      ]
    },
    "parameters": {
      "storageAccount_storageAccountType": {
        "value": "Standard_GRS"
      }
    },
    "resourceGroups": {
      "ResourceGroup": {
        "name": "storage_rg",
        "location": "westus2"
      }
    }
  }
}

# Login first with Connect-AzAccount if not using Cloud Shell

# Create the new blueprint assignment
$bpAssignment = New-AzBlueprintAssignment -Name 'my-blueprint-assignment' -SubscriptionId '{subId}' `
    -AssignmentFile '.\assignment.json'

للحصول على مثال لملف تعريف تعيين JSON لهوية مدارة معينة من قبل المستخدم، راجع نص الطلب في مثال: التعيين مع الهوية المدارة المعينة من قبل المستخدم لواجهة برمجة تطبيقات REST.

تحديث تعيينات المخطط

في بعض الأحيان، من الضروري تحديث تعيين مخطط تم إنشاؤه بالفعل. يعالج Set-AzBlueprintAssignment cmdlet هذا الإجراء. يأخذ cmdlet معظم المعلمات نفسها التي يقوم بها New-AzBlueprintAssignment cmdlet، ما يسمح بتحديث أي شيء تم تعيينه على التعيين. الاستثناءات هي الاسم والمخطط وSubscriptionId. يتم تحديث القيم المقدمة فقط.

لفهم ما يحدث عند تحديث تعيين مخطط، راجع قواعد تحديث التعيينات.

الاسم [مطلوب]
- تحديد اسم تعيين المخطط للتحديث
- يستخدم لتحديد موقع التعيين للتحديث، وليس لتغيير التعيين
المخطط [مطلوب]
- تحديد تعريف المخطط لتعيين المخطط
- استخدم Get-AzBlueprint للحصول على العنصر المرجعي
- يستخدم لتحديد موقع التعيين للتحديث، وليس لتغيير التعيين
الموقع (اختياري)
- تحديد المنطقة للهوية المدارة المعينة من قبل النظام وعنصر توزيع الاشتراك المراد إنشاؤه في
الاشتراك (اختياري)
- تحديد الاشتراك الذي يتم توزيع التعيين فيه
- إذا لم يتم توفيره، فسيتم تعيين الإعدادات بشكل افتراضي إلى سياق الاشتراك الحالي
- يستخدم لتحديد موقع التعيين للتحديث، وليس لتغيير التعيين
التأمين (اختياري)
- تعريف تأمين موارد المخطط للاستخدام للموارد الموزعة
- الخيارات المدعومة: بلا، AllResourcesReadOnly، AllResourcesDoNotDelete
SystemAssignedIdentity (اختياري)
- حدد لإنشاء هوية مدارة يعينها النظام للتعيين ولتوزيع الموارد
- افتراضي لمجموعة معلمات "الهوية"
- لا يمكن الاستخدام مع UserAssignedIdentity
UserAssignedIdentity (اختياري)
- تحديد الهوية المدارة المعينة من قبل المستخدم لاستخدامها في التعيين وتوزيع الموارد
- جزء من مجموعة معلمات "الهوية"
- لا يمكن الاستخدام مع SystemAssignedIdentity
المعلمة (اختياري)
- جدول تجزئة لأزواج المفاتيح/القيم لتعيين المعلمات الديناميكية في تعيين المخطط
- الافتراضي لأي معلمة ديناميكية هو defaultValue في التعريف
- إذا لم يتم توفير معلمة وليس لها defaultValue، فإن المعلمة ليست اختيارية
  
  ملاحظة
  
  لا تدعم المعلمة secureStrings.
ResourceGroupParameter (اختياري)
- جدول تجزئة للبيانات الاصطناعية لمجموعة الموارد
- يحتوي كل عنصر نائب للبيانات الاصطناعية لمجموعة الموارد على أزواج مفاتيح/قيمة لإعداد الاسم و الموقع ديناميكياً على البيانات الاصطناعية لمجموعة الموارد هذه
- إذا لم يتم توفير معلمة مجموعة موارد ولم يكن لها defaultValue، فإن معلمة مجموعة الموارد ليست اختيارية

يحدث المثال التالي تعيين الإصدار "1.1" من تعريف مخطط "my-blueprint" الذي تم إحضاره باستخدام Get-AzBlueprint عن طريق تغيير وضع التأمين:

# Login first with Connect-AzAccount if not using Cloud Shell

# Get version '1.1' of the blueprint definition in the specified subscription
$bpDefinition = Get-AzBlueprint -SubscriptionId '{subId}' -Name 'my-blueprint' -Version '1.1'

# Update the existing blueprint assignment
$bpAssignment = Set-AzBlueprintAssignment -Name 'my-blueprint-assignment' -Blueprint $bpDefinition `
    -SubscriptionId '{subId}' -Lock AllResourcesDoNotDelete

يبدو إخراج المثال لإنشاء تعيين مخطط كما يلي:

Name              : my-blueprint-assignment
Id                : /subscriptions/{subId}/providers/Microsoft.Blueprint/blueprintAssi
                    gnments/my-blueprint-assignment
Scope             : /subscriptions/{subId}
LastModified      : 2019-03-13
LockMode          : AllResourcesDoNotDelete
ProvisioningState : Updating
Parameters        : {storageAccount_storageAccountType}
ResourceGroups    : ResourceGroup

إزالة تعيينات المخطط

عندما يحين الوقت لإزالة تعيين مخطط، يعالج Remove-AzBlueprintAssignment cmdlet هذا الإجراء. يأخذ cmdlet إما الاسم أو InputObject لتحديد تعيين المخطط الذي يجب إزالته. SubscriptionIdمطلوب ويجب توفيره في جميع الحالات.

يحضر المثال التالي تعيين مخطط موجود مع Get-AzBlueprintAssignment ثم يزيله من الاشتراك المحدد الممثل ليكون {subId}:

# Login first with Connect-AzAccount if not using Cloud Shell

# Get the blueprint assignment in the specified subscription
$blueprintAssignment = Get-AzBlueprintAssignment -Name 'Assignment-lock-resource-groups'

# Remove the existing blueprint assignment
Remove-AzBlueprintAssignment -InputObject $blueprintAssignment -SubscriptionId '{subId}'

مثال على التعليمة البرمجية

يجمع كل الخطوات معاً، يحصل المثال التالي على تعريف المخطط، ثم ينشئ ويحدث ويزيل تعيين مخطط في الاشتراك المحدد الممثل ليكون {subId}:

# Login first with Connect-AzAccount if not using Cloud Shell

#region GetBlueprint
# Get version '1.1' of the blueprint definition in the specified subscription
$bpDefinition = Get-AzBlueprint -SubscriptionId '{subId}' -Name 'my-blueprint' -Version '1.1'
#endregion

#region CreateAssignment
# Create the hash table for Parameters
$bpParameters = @{storageAccount_storageAccountType='Standard_GRS'}

# Create the hash table for ResourceGroupParameters
# ResourceGroup is the resource group artifact placeholder name
$bpRGParameters = @{ResourceGroup=@{name='storage_rg';location='westus2'}}

# Create the new blueprint assignment
$bpAssignment = New-AzBlueprintAssignment -Name 'my-blueprint-assignment' -Blueprint $bpDefinition `
    -SubscriptionId '{subId}' -Location 'westus2' -Lock AllResourcesReadOnly `
    -Parameter $bpParameters -ResourceGroupParameter $bpRGParameters
#endregion CreateAssignment

# Wait for the blueprint assignment to finish deployment prior to the next steps

#region UpdateAssignment
# Update the existing blueprint assignment
$bpAssignment = Set-AzBlueprintAssignment -Name 'my-blueprint-assignment' -Blueprint $bpDefinition `
    -SubscriptionId '{subId}' -Lock AllResourcesDoNotDelete
#endregion UpdateAssignment

# Wait for the blueprint assignment to finish deployment prior to the next steps

#region RemoveAssignment
# Remove the existing blueprint assignment
Remove-AzBlueprintAssignment -InputObject $bpAssignment -SubscriptionId '{subId}'
#endregion

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

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

Share via