التشغيل السريع: تحديد وتعيين مخطط Azure باستخدام واجهة برمجة تطبيقات REST

مقالة
09/07/2023

هام

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

في هذا البرنامج التعليمي، تتعلم استخدام Azure Blueprints للقيام ببعض المهام الشائعة المتعلقة بإنشاء مخطط ونشره وتعيينه داخل مؤسستك. تساعدك هذه المهارة في تعريف الأنماط الشائعة لتطوير تكوينات قابلة لإعادة الاستخدام والتوزيع السريع، استناداً إلى الأمان والنُهج والقوالب الخاصة بـ Azure Resource Manager (ARM).

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

في حال لم يكن لديك اشتراك Azure، فأنشئ حساباً مجانيّاً قبل البدء.
سجل مزود الموارد Microsoft.Blueprint. للحصول على الاتجاهات، راجع أنواع موفري الموارد وأنواعها.

Azure Cloud Shell

Azure يستضيف Azure Cloud Shell، بيئة تفاعلية يمكن استخدامها من خلال المستعرض. يمكنك استخدام Bash أو PowerShell مع Cloud Shell للعمل مع خدمات Azure. يمكنك استخدام أوامر Cloud Shell المثبتة مسبقًا لتشغيل التعليمات البرمجية في هذه المقالة دون الحاجة إلى تثبيت أي شيء على البيئة المحلية.

لبدء Azure Cloud Shell:

خيار	مثال/ رابط
انقر فوق ⁧⁩جربه⁧⁩ في الزاوية العلوية اليسرى من التعليمة البرمجية أو كتلة الأمر. تحديد ⁧⁩جربه⁧⁩ لا يقوم بنسخ التعليمة البرمجية أو الأمر تلقائيًا إلى Cloud Shell.
انتقل إلى ⁧⁩⁧ https://shell.azure.com⁩⁧⁩، أو حدد زر ⁩تشغيل Cloud Shell لفتح Cloud Shell في المتصفح لديك.
حدد زر Cloud Shell على شريط القوائم في أعلى اليمين في مدخل Microsoft Azure.

لاستخدام Azure Cloud Shell:

ابدأ تشغيل Cloud Shell.
حدد الزر نسخ على كتلة التعليمات البرمجية (أو كتلة الأوامر) لنسخ التعليمات البرمجية أو الأمر.
ألصق التعليمة البرمجية أو الأمر في جلسة Cloud Shell بتحديد Ctrl+Shift+Vعلى Windows وLunix، أو بتحديد Cmd+Shift+Vعلى macOS.
حدد Enter لتشغيل التعليمات البرمجية أو الأمر.

الشروع في العمل مع واجهة برمجة تطبيقات REST

إذا لم تكن على دراية بواجهة برمجة تطبيقات REST، فابدأ بمراجعة مرجع واجهة برمجة تطبيقات Azure REST، خاصة الأقسام الخاصة بطلب URI وطلب نص أساسي. يستخدم هذا التشغيل السريع هذه المفاهيم لتوفير توجيهات للعمل مع مخططات Azure، وتفترض معرفة عملية بها. قد تتعامل أدوات مثل ARMClient مع التخويل تلقائياً، ويوصى بها للمبتدئين.

للحصول على مواصفات Azure Blueprints، راجع Azure Blueprints REST API.

واجهة برمجة تطبيقات REST وPowerShell

إذا لم يكن لديك بالفعل أداة لإجراء مكالمات REST API، ففكر في استخدام PowerShell لهذه التعليمات. فيما يلي نموذج عنوان للمصادقة باستخدام Azure. أنشئ عنوان مصادقة، يُطلق عليه أحياناً الرمز المميز للحامل، وقدم URI برمجة واجهة تطبيقات REST للاتصال بأي معلمات أو Request Body:

# Log in first with Connect-AzAccount if not using Cloud Shell

$azContext = Get-AzContext
$azProfile = [Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile
$profileClient = New-Object -TypeName Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient -ArgumentList ($azProfile)
$token = $profileClient.AcquireAccessToken($azContext.Subscription.TenantId)
$authHeader = @{
    'Content-Type'='application/json'
    'Authorization'='Bearer ' + $token.AccessToken
}

# Invoke the REST API
$restUri = 'https://management.azure.com/subscriptions/{subscriptionId}?api-version=2020-01-01'
$response = Invoke-RestMethod -Uri $restUri -Method Get -Headers $authHeader

استبدل {subscriptionId} في المتغير $restUri السابق للحصول على معلومات بشأن اشتراكك. يحتوي المتغير $response على نتيجة cmdlet Invoke-RestMethod، التي يمكن توزيعها باستخدام أوامر cmdlets مثل ConvertFrom-Json. إذا كانت نقطة نهاية خدمة واجهة برمجة تطبيقات REST تتوقع Request Body، فقدم متغيراً بتنسيق JSON للمعلمة -Body الخاصة بـ Invoke-RestMethod.

إنشاء مخطط

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

إشعار

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

في كل URI واجهة برمجة تطبيقات REST، استبدل المتغيرات التالية بقيمك الخاصة:

{YourMG} - استبدل بمعرّف مجموعتك للإدارة.
{subscriptionId} - استبدل بمعرّف اشتراكك.

إشعار

يمكنك أيضاً إنشاء مخططات على مستوى الاشتراك. لمزيد من المعلومات، انظرإنشاء مخطط في مثال الاشتراك.

إنشاء كائن المخطط الأول. يتضمن Request Body خصائص بشأن المخطط وأي مجموعات موارد يتم إنشاؤها، وجميع معلمات مستوى المخطط. يمكنك تحديد المعايير خلال التعيين، ويتم استخدامها من قبل البيانات الاصطناعية التي تضيفها في الخطوات اللاحقة.

REST API URI

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint?api-version=2018-11-01-preview

نص الطلب

{
    "properties": {
        "description": "This blueprint sets tag policy and role assignment on the subscription, creates a ResourceGroup, and deploys a resource template and role assignment to that ResourceGroup.",
        "targetScope": "subscription",
        "parameters": {
            "storageAccountType": {
                "type": "string",
                "metadata": {
                    "displayName": "storage account type.",
                    "description": null
                }
            },
            "tagName": {
                "type": "string",
                "metadata": {
                    "displayName": "The name of the tag to provide the policy assignment.",
                    "description": null
                }
            },
            "tagValue": {
                "type": "string",
                "metadata": {
                    "displayName": "The value of the tag to provide the policy assignment.",
                    "description": null
                }
            },
            "contributors": {
                "type": "array",
                "metadata": {
                    "description": "List of AAD object IDs that is assigned Contributor role at the subscription"
                }
            },
            "owners": {
                "type": "array",
                "metadata": {
                    "description": "List of AAD object IDs that is assigned Owner role at the resource group"
                }
            }
        },
        "resourceGroups": {
            "storageRG": {
                "description": "Contains the resource template deployment and a role assignment."
            }
        }
    }
}

أضف تعيين دور على الاشتراك. يحدد Request Body نوع البيانات الاصطناعية، وتصبح الخصائص محاذية لمُعرّف تعريف الدور، ويتم تمرير الهويات الأساسية كمصفوفة من القيم. في المثال التالي، يتم تكوين الهويات الأساسية الممنوحة للدور المحدد لمعامل تم تعيينه في أثناء تعيين المخطط. يستخدم هذا المثال الدور المضمن Contributor، مع معرف GUID لـ b24988ac-6180-42a0-ab88-20f7382dd24c.
- REST API URI
```
PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/artifacts/roleContributor?api-version=2018-11-01-preview
```
- نص الطلب
```
{
    "kind": "roleAssignment",
    "properties": {
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c",
        "principalIds": "[parameters('contributors')]"
    }
}
```

أضف تعيين نهج على مستوى الاشتراك. يُعرّف Request Body نوع البيانات الاصطناعية، وتصبح الخصائص محاذية لتعريف نهج أو مبادرة، ويتم تكوين تعيين النهج لاستخدام معلمات المخطط المحددة خلال تعيين المخطط. يستخدم هذا المثال النهج المضمن Apply tag and its default value to resource groups، مع مُعرّف GUID لـ 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.

REST API URI

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/artifacts/policyTags?api-version=2018-11-01-preview

نص الطلب

{
    "kind": "policyAssignment",
    "properties": {
        "description": "Apply tag and its default value to resource groups",
        "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/49c88fc8-6fd1-46fd-a676-f12d1d3a4c71",
        "parameters": {
            "tagName": {
                "value": "[parameters('tagName')]"
            },
            "tagValue": {
                "value": "[parameters('tagValue')]"
            }
        }
    }
}

أضف تعيين نهج آخر لعلامة التخزين (عن طريق إعادة استخدام storageAccountType_ parameter) في الاشتراك. توضح هذه الأداة الإضافية لتعيين النهج أن المعامل المحدد في المخطط يمكن استخدامه بواسطة أكثر من عنصر واحد. في المثال، يتم استخدام storageAccountType لتعيين علامة على مجموعة الموارد. توفر هذه القيمة معلومات بشأن حساب التخزين الذي تم إنشاؤه في الخطوة التالية. يستخدم هذا المثال النهج المضمن Apply tag and its default value to resource groups، مع مُعرّف GUID لـ 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.
- REST API URI
```
PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/artifacts/policyStorageTags?api-version=2018-11-01-preview
```
- نص الطلب
```
{
    "kind": "policyAssignment",
    "properties": {
        "description": "Apply storage tag and the parameter also used by the template to resource groups",
        "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/49c88fc8-6fd1-46fd-a676-f12d1d3a4c71",
        "parameters": {
            "tagName": {
                "value": "StorageType"
            },
            "tagValue": {
                "value": "[parameters('storageAccountType')]"
            }
        }
    }
}
```

إضافة قالب ضمن مجموعة الموارد. يشتمل Request Body لقالب ARM على مكوّن JSON العادي للقالب، ويحدد مجموعة الموارد المستهدفة باستخدام properties.resourceGroup. يعيد القالب أيضا استخدام معلمات storageAccountTypetagNameالمخطط و و tagValue عن طريق تمرير كل منها إلى القالب. تتوفر معلمات المخطط للقالب من خلال تحديد properties.parameters، وداخل القالب JSON الذي يستخدمه زوج قيم المفاتيح لإدخال القيمة. يمكن أن تكون أسماء معلمات المخطط والقالب متطابقة، ولكنها مختلفة هنا لتوضيح كيف تمر كل منهما من المخطط إلى البيانات الاصطناعية للقالب.

REST API URI

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/artifacts/templateStorage?api-version=2018-11-01-preview

نص الطلب

{
    "kind": "template",
    "properties": {
        "template": {
            "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
            "contentVersion": "1.0.0.0",
            "parameters": {
                "storageAccountTypeFromBP": {
                    "type": "string",
                    "defaultValue": "Standard_LRS",
                    "allowedValues": [
                        "Standard_LRS",
                        "Standard_GRS",
                        "Standard_ZRS",
                        "Premium_LRS"
                    ],
                    "metadata": {
                        "description": "Storage Account type"
                    }
                },
                "tagNameFromBP": {
                    "type": "string",
                    "defaultValue": "NotSet",
                    "metadata": {
                        "description": "Tag name from blueprint"
                    }
                },
                "tagValueFromBP": {
                    "type": "string",
                    "defaultValue": "NotSet",
                    "metadata": {
                        "description": "Tag value from blueprint"
                    }
                }
            },
            "variables": {
                "storageAccountName": "[concat(uniquestring(resourceGroup().id), 'standardsa')]"
            },
            "resources": [{
                "type": "Microsoft.Storage/storageAccounts",
                "name": "[variables('storageAccountName')]",
                "apiVersion": "2016-01-01",
                "tags": {
                   "[parameters('tagNameFromBP')]": "[parameters('tagValueFromBP')]"
                },
                "location": "[resourceGroups('storageRG').location]",
                "sku": {
                    "name": "[parameters('storageAccountTypeFromBP')]"
                },
                "kind": "Storage",
                "properties": {}
            }],
            "outputs": {
                "storageAccountSku": {
                    "type": "string",
                    "value": "[variables('storageAccountName')]"
                }
            }
        },
        "resourceGroup": "storageRG",
        "parameters": {
            "storageAccountTypeFromBP": {
                "value": "[parameters('storageAccountType')]"
            },
            "tagNameFromBP": {
                "value": "[parameters('tagName')]"
            },
            "tagValueFromBP": {
                "value": "[parameters('tagValue')]"
            }
        }
    }
}

إضافة تعيين دور ضمن مجموعة الموارد. كما الحال في إدخال تعيين الدور السابق، يستخدم المثال أدناه معرّف التعريف الدور لـ Owner، ويوفر له معلمة مختلفة عن المخطط. يستخدم هذا المثال الدور المضمن Owner، مع معرف GUID لـ 8e3af657-a8ff-443c-a75c-2fe8c4bcb635.

REST API URI

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/artifacts/roleOwner?api-version=2018-11-01-preview

نص الطلب

{
    "kind": "roleAssignment",
    "properties": {
        "resourceGroup": "storageRG",
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635",
        "principalIds": "[parameters('owners')]"
    }
}

انشر مخططًا

الآن وقد تمت إضافة البيانات الاصطناعية إلى المخطط، فقد حان الوقت لنشرها. النشر يجعل المخطط متاحاً ليُعين للاشتراك.

REST API URI

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/versions/{BlueprintVersion}?api-version=2018-11-01-preview

القيمة لـ {BlueprintVersion} هي عبارة عن سلسلة من الأحرف، والأرقام، والواصلات (دون مسافات أو أحرف خاصة أخرى). الحد الأقصى لعدد الحروف هو 20 حرفًا. استخدم شيئاً فريداً ومعلوماتيا، مثل v20180622-135541.

تعيين مخطط

بعد أن قمت بنشر مخطط باستخدام واجهة برمجة تطبيقات REST، يمكن تعيينه إلى اشتراك. تعيين المخطط المُنشأ لأحد الاشتراكات ضمن التسلسل الهرمي لمجموعة الإدارة. إذا تم حفظ المخطط في اشتراك، فيمكن تعيينه لهذا الاشتراك فقط. يحدد Request Body المخطط الذي سيتم تعيينه، ويوفر الاسم والموقع لأي مجموعات موارد في تعريف المخطط. Request Body يوفر أيضاً جميع المعلمات المحددة على المخطط والمستخدمة من قبل واحدة أو أكثر من البيانات الاصطناعية المرفقة.

في كل URI واجهة برمجة تطبيقات REST، استبدل المتغيرات التالية بقيمك الخاصة:

{tenantId} - استبدل بمعرّفك للمستأجر.
{YourMG} - استبدل بمعرّف مجموعتك للإدارة.
{subscriptionId} - استبدل بمعرّف اشتراكك.

قدم مدير خدمة Azure Blueprint الدور Owner في الاشتراك المستهدف. إن AppId ثابت (f71766dc-90d9-4b7d-bd9d-4499c4331c3f)، لكن معرف الخدمة الأساسي يختلف باختلاف المستأجر. استخدام واجهة برمجة تطبيقات REST التالية لطلب تفاصيل للمستأجر الخاص بك. يستخدم واجهة برمجة تطبيقات Azure Active Directory Graph API، والتي لها تفويض مختلف.
- REST API URI
```
GET https://graph.windows.net/{tenantId}/servicePrincipals?api-version=1.6&$filter=appId eq 'f71766dc-90d9-4b7d-bd9d-4499c4331c3f'
```

قم بتشغيل نشر المخطط عن طريق تخصيصه لاشتراك. نظراً لأن المعلمات contributors وowners تتطلب مصفوفة من objectIds خاصة بالأساسيات ليتم منحها تعيين الدور، استخدم واجهة برمجة تطبيقات Microsoft Azure Active Directory Graph لتجميع objectIds للاستخدام في Request Body للمستخدمين أو المجموعات أو كيانات الخدمة.

REST API URI

PUT https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Blueprint/blueprintAssignments/assignMyBlueprint?api-version=2018-11-01-preview

نص الطلب

{
    "properties": {
        "blueprintId": "/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint",
        "resourceGroups": {
            "storageRG": {
                "name": "StorageAccount",
                "location": "eastus2"
            }
        },
        "parameters": {
            "storageAccountType": {
                "value": "Standard_GRS"
            },
            "tagName": {
                "value": "CostCenter"
            },
            "tagValue": {
                "value": "ContosoIT"
            },
            "contributors": {
                "value": [
                    "7be2f100-3af5-4c15-bcb7-27ee43784a1f",
                    "38833b56-194d-420b-90ce-cff578296714"
                ]
            },
            "owners": {
                "value": [
                    "44254d2b-a0c7-405f-959c-f829ee31c2e7",
                    "316deb5f-7187-4512-9dd4-21e7798b0ef9"
                ]
            }
        }
    },
    "identity": {
        "type": "systemAssigned"
    },
    "location": "westus"
}

الهوية المُدارة التي يعيّنها المُستخدم

يمكن أن يستخدم تعيين المخطط أيضًا هوية مُدارة يعينها المستخدم. في هذه الحالة، identity يتغير جزء نص الطلب كما يلي. استبدل {yourRG} و{userIdentity} باسم مجموعة الموارد واسم الهوية المُدارة التي عيّنها المستخدم، على التوالي.
```
"identity": {
    "type": "userAssigned",
    "tenantId": "{tenantId}",
    "userAssignedIdentities": {
        "/subscriptions/{subscriptionId}/resourceGroups/{yourRG}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{userIdentity}": {}
    }
},
```
يمكن للهوية المُدارة المعينة من قِبل المستخدم أن تكون في أي اشتراك ومجموعة موارد يمتلك المستخدم الذي يقوم بتعيين المخطط أذونات لها.

هام

لا تدير Azure Blueprints الهوية المدارة المعينة من قِبل المستخدم. يتحمل المستخدمون مسؤولية تعيين الأدوار والأذونات الكافية، وإلا سيفشل تعيين المخطط.

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

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

يمكنك إزالة مخطط من الاشتراك. تتم الإزالة غالبًا عندما لا تعود هناك حاجة إلى موارد الأداة. عند إزالة مخطط، يتم ترك المصطنعات (بيانات اصطناعية) التي تم تعيينها كجزء من ذلك المخطط وراءها. لإزالة تعيين مخطط، استخدم عملية REST API التالية:

REST API URI

DELETE https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Blueprint/blueprintAssignments/assignMyBlueprint?api-version=2018-11-01-preview

حذف مخطط

لإزالة المخطط نفسه، استخدم عملية REST API التالية:

REST API URI

DELETE https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint?api-version=2018-11-01-preview

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

في هذه البداية السريعة، قمت بإنشاء blueprint وتعيينه، وإزالته باستخدام REST API. لمعرفة المزيد حول Azure Blueprints، تابع إلى مقالة دورة حياة المخطط.

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

Share via

التشغيل السريع: تحديد وتعيين مخطط Azure باستخدام واجهة برمجة تطبيقات REST

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

Azure Cloud Shell

الشروع في العمل مع واجهة برمجة تطبيقات REST

واجهة برمجة تطبيقات REST وPowerShell

إنشاء مخطط

انشر مخططًا

تعيين مخطط

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

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

حذف مخطط

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

الموارد الإضافية