إدارة المصنفات برمجيًا

مقالة
06/21/2023

يمكن لمالكي الموارد إنشاء مصنفاتهم وإدارتها برمجيا عبر قوالب Azure Resource Manager (قوالب ARM).

يمكن أن تكون هذه الإمكانية مفيدة في سيناريوهات مثل:

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

سيتم إنشاء المصنف في المجموعة الفرعية/مجموعة الموارد المطلوبة ومع المحتوى المحدد في قوالب ARM.

يمكن إدارة نوعين من موارد المصنف برمجيا:

قوالب المصنفات
مثيلات المصنفات

قالب ARM لنشر قالب مصنف

افتح مصنفًا تريد نشره برمجيًا.
قم بتبديل المصنف إلى وضع التحرير عن طريق تحديد تحرير.
افتح المحرر المتقدم باستخدام <الزر /> على شريط الأدوات.
تأكد من أنك في علامة التبويب قالب المعرض.
انسخ JSON في قالب المعرض إلى الحافظة.

يقوم نموذج قالب ARM التالي بتوزيع قالب مصنف إلى معرض مصنف Azure Monitor. الصق JSON الذي نسخته بدلاً من <PASTE-COPIED-WORKBOOK_TEMPLATE_HERE>. للحصول على قالب ARM مرجعي يقوم بإنشاء قالب مصنف، راجع مستودع GitHub هذا.

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "resourceName": {
            "type": "string",
            "defaultValue": "my-workbook-template",
            "metadata": {
                "description": "The unique name for this workbook template instance"
            }
        }
    },
    "resources": [
        {
            "name": "[parameters('resourceName')]",
            "type": "microsoft.insights/workbooktemplates",
            "location": "[resourceGroup().location]",
            "apiVersion": "2019-10-17-preview",
            "dependsOn": [],
            "properties": {
                "galleries": [
                    {
                        "name": "A Workbook Template",
                        "category": "Deployed Templates",
                        "order": 100,
                        "type": "workbook",
                        "resourceType": "Azure Monitor"
                    }
                ],
                "templateData": <PASTE-COPIED-WORKBOOK_TEMPLATE_HERE>
            }
        }
    ]
}

في galleries الكائن ، املأ المفتاحين name و category بقيمك. تعرف على المزيد عن المعلمات في القسم التالي.
انشر قالب ARM هذا باستخدام إما مدخل Azure أو واجهة سطر الأوامر أو PowerShell.
افتح مدخل Microsoft Azure وانتقل إلى معرض المصنفات المختار في قالب ARM. في نموذج القالب، انتقل إلى معرض مصنفات Azure Monitor:
1. افتح مدخل Microsoft Azure وانتقل إلى Azure Monitor.
2. فتح Workbooks من جدول المحتويات.
3. ابحث عن قالبك في المعرض ضمن الفئة Deployed Templates. (سيكون أحد العناصر الأرجوانية.)

معلمات

معلمات	الشرح
`name`	اسم مورد قالب المصنف في Azure Resource Manager.
`type`	دائما microsoft.insights/workbooktemplates.
`location`	موقع Azure حيث سيتم إنشاء المصنف.
`apiVersion`	معاينة 2019-10-17.
`type`	دائما microsoft.insights/workbooktemplates.
`galleries`	مجموعة المعارض التي سيتم عرض قالب المصنف هذا فيها.
`gallery.name`	الاسم المألوف لقالب المصنف في المعرض.
`gallery.category`	المجموعة في المعرض الذي سيتم وضع القالب فيه.
`gallery.order`	رقم يحدد الترتيب لإظهار القالب داخل فئة في المعرض. يعني الترتيب الأدنى أولوية أعلى.
`gallery.resourceType`	نوع المورد المقابل للمعرض. عادة ما يكون هذا النوع سلسلة نوع المورد المطابقة للمورد (على سبيل المثال، microsoft.operationalinsights/workspaces).
`gallery.type`	يشار إليه بنوع المصنف. يميز هذا المفتاح الفريد المعرض ضمن نوع مورد. يحتوي Application Insights، على سبيل المثال، على الأنواع `workbook` التي `tsg` تتوافق مع معارض مصنفات مختلفة.

المعارض

المعرض	نوع المورد	نوع المصنف
المصنفات في Azure Monitor	`Azure Monitor`	`workbook`
نتائج تحليلات الجهاز الظاهري في Azure Monitor	`Azure Monitor`	`vm-insights`
المصنفات في مساحة عمل Log Analytics	`microsoft.operationalinsights/workspaces`	`workbook`
المصنفات في Application Insights	`microsoft.insights/components`	`workbook`
أدلة استكشاف الأخطاء وإصلاحها في Application Insights	`microsoft.insights/components`	`tsg`
الاستخدام في Application Insights	`microsoft.insights/components`	`usage`
المصنفات في خدمة Kubernetes	`Microsoft.ContainerService/managedClusters`	`workbook`
المصنفات في مجموعات الموارد	`microsoft.resources/subscriptions/resourcegroups`	`workbook`
المصنفات في معرف Microsoft Entra	`microsoft.aadiam/tenant`	`workbook`
VM Insights في الأجهزة الظاهرية	`microsoft.compute/virtualmachines`	`insights`
نتائج تحليلات الجهاز الظاهري في مجموعات مقياس الجهاز الظاهري	`microsoft.compute/virtualmachinescalesets`	`insights`

قالب ARM لنشر مثيل مصنف

افتح المصنف الذي تريد نشره برمجيًا.
قم بتبديل المصنف إلى وضع التحرير عن طريق تحديد تحرير.
افتح المحرر المتقدم عن طريق تحديد< />.
في المحرر، قم بتبديل نوع القالب إلى قالب ARM.
يظهر قالب ARM للإنشاء في المحرر. انسخ المحتوى واستخدمه كما هو أو ادمجه مع قالب أكبر يقوم أيضًا بنشر المورد المستهدفة.

نموذج قالب ARM

يوضح هذا القالب كيفية نشر مصنف يعرض Hello World!.

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "workbookDisplayName":  {             
            "type":"string",
            "defaultValue": "My Workbook",
            "metadata": {
                "description": "The friendly name for the workbook that is used in the Gallery or Saved List. Needs to be unique in the scope of the resource group and source" 
            }
        },
        "workbookType":  {             
            "type":"string",
            "defaultValue": "tsg",
            "metadata": {
                "description": "The gallery that the workbook will be shown under. Supported values include workbook, `tsg`, Azure Monitor, etc." 
            }
        },
        "workbookSourceId":  {             
            "type":"string",
            "defaultValue": "<insert-your-resource-id-here>",
            "metadata": {
                "description": "The id of resource instance to which the workbook will be associated" 
            }
        },
        "workbookId": {
            "type":"string",
            "defaultValue": "[newGuid()]",
            "metadata": {
                "description": "The unique guid for this workbook instance" 
            }
        }
    },    
    "resources": [
        {
            "name": "[parameters('workbookId')]",
            "type": "Microsoft.Insights/workbooks",
            "location": "[resourceGroup().location]",
            "kind": "shared",
            "apiVersion": "2018-06-17-preview",
            "dependsOn": [],
            "properties": {
                "displayName": "[parameters('workbookDisplayName')]",
                "serializedData": "{\"version\":\"Notebook/1.0\",\"items\":[{\"type\":1,\"content\":\"{\\\"json\\\":\\\"Hello World!\\\"}\",\"conditionalVisibility\":null}],\"isLocked\":false}",
                "version": "1.0",
                "sourceId": "[parameters('workbookSourceId')]",
                "category": "[parameters('workbookType')]"
            }
        }
    ],
    "outputs": {
        "workbookId": {
            "type": "string",
            "value": "[resourceId( 'Microsoft.Insights/workbooks', parameters('workbookId'))]"
        }
    }
}

معلمات القالب

المعلمة	‏‏الوصف‬
`workbookDisplayName`	الاسم المألوف للمصنف المستخدم في المعرض أو القائمة المحفوظة. يجب أن يكون فريدا في نطاق مجموعة الموارد والمصدر.
`workbookType`	المعرض حيث يظهر المصنف. تتضمن القيم المدعومة المصنف و `tsg`وAzure Monitor.
`workbookSourceId`	معرّف مثيل المورد الذي سيتم إقران المصنف به. سيظهر المصنف الجديد مرتبطا بمثيل المورد هذا، على سبيل المثال، في جدول محتويات المورد ضمن المصنف. إذا كنت تريد أن يظهر المصنف في معرض المصنفات في Azure Monitor، فاستخدم السلسلة Azure Monitor بدلا من معرف المورد.
`workbookId`	الدليل الفريد لمثيل المصنف هذا. استخدم `[newGuid()]` لإنشاء معرف فريد عمومي جديد تلقائيا.
`kind`	يُستخدم لتحديد ما إذا كان المصنف الذي تم إنشاؤه مشتركًا أم لا. ستستخدم كافة المصنفات الجديدة القيمة المشتركة.
`location`	موقع Azure حيث سيتم إنشاء المصنف. استخدم `[resourceGroup().location]` لإنشائه في نفس موقع مجموعة الموارد.
`serializedData`	يحتوي على المحتوى أو الحمولة التي سيتم استخدامها في المصنف. استخدم قالب ARM من واجهة مستخدم المصنفات للحصول على القيمة.

أنواع المصنفات

تحدد أنواع المصنفات نوع معرض المصنفات حيث يظهر مثيل المصنف الجديد. تتضمن الخيارات:

نوع	موقع المعرض
`workbook`	الافتراضي المستخدم في معظم التقارير، بما في ذلك معرض المصنفات ل Application Insights وAzure Monitor.
`tsg`	معرض أدلة استكشاف الأخطاء وإصلاحها في Application Insights.
`usage`	معرض المزيد ضمن الاستخدام في Application Insights.

العمل مع بيانات المصنف بتنسيق JSON في معلمة قالب serializedData

عند تصدير قالب ARM لمصنف Azure، غالبا ما تكون هناك ارتباطات موارد ثابتة مضمنة داخل معلمة القالب المصدرة serializedData . تتضمن هذه الارتباطات قيما حساسة محتملة مثل معرف الاشتراك واسم مجموعة الموارد وأنواع أخرى من معرفات الموارد.

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

{
  "contentVersion": "1.0.0.0",
  "parameters": {
    "workbookDisplayName": {
      "type": "string"
    },
    "workbookSourceId": {
      "type": "string",
      "defaultValue": "[resourceGroup().id]"
    },
    "workbookId": {
      "type": "string",
      "defaultValue": "[newGuid()]"
    }
  },
  "variables": {
    // serializedData from original exported Azure Resource Manager template
    "serializedData": "{\"version\":\"Notebook/1.0\",\"items\":[{\"type\":1,\"content\":{\"json\":\"Replace with Title\"},\"name\":\"text - 0\"},{\"type\":3,\"content\":{\"version\":\"KqlItem/1.0\",\"query\":\"{\\\"version\\\":\\\"ARMEndpoint/1.0\\\",\\\"data\\\":null,\\\"headers\\\":[],\\\"method\\\":\\\"GET\\\",\\\"path\\\":\\\"/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/resourceGroups\\\",\\\"urlParams\\\":[{\\\"key\\\":\\\"api-version\\\",\\\"value\\\":\\\"2019-06-01\\\"}],\\\"batchDisabled\\\":false,\\\"transformers\\\":[{\\\"type\\\":\\\"jsonpath\\\",\\\"settings\\\":{\\\"tablePath\\\":\\\"$..*\\\",\\\"columns\\\":[]}}]}\",\"size\":0,\"queryType\":12,\"visualization\":\"map\",\"tileSettings\":{\"showBorder\":false},\"graphSettings\":{\"type\":0},\"mapSettings\":{\"locInfo\":\"AzureLoc\",\"locInfoColumn\":\"location\",\"sizeSettings\":\"location\",\"sizeAggregation\":\"Count\",\"opacity\":0.5,\"legendAggregation\":\"Count\",\"itemColorSettings\":null}},\"name\":\"query - 1\"}],\"isLocked\":false,\"fallbackResourceIds\":[\"/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/resourceGroups/XXXXXXX\"]}",

    // parse the original into a JSON object, so that it can be manipulated
    "parsedData": "[json(variables('serializedData'))]",

    // create new JSON objects that represent only the items/properties to be modified
    "updatedTitle": {
      "content":{
        "json": "[concat('Resource Group Regions in subscription \"', subscription().displayName, '\"')]"
      }
    },
    "updatedMap": {
      "content": {
        "path": "[concat('/subscriptions/', subscription().subscriptionId, '/resourceGroups')]"
      }
    },

    // the union function applies the updates to the original data
    "updatedItems": [
      "[union(variables('parsedData')['items'][0], variables('updatedTitle'))]",
      "[union(variables('parsedData')['items'][1], variables('updatedMap'))]"
    ],

    // copy to a new workbook object, with the updated items
    "updatedWorkbookData": {
      "version": "[variables('parsedData')['version']]",
      "items": "[variables('updatedItems')]",
      "isLocked": "[variables('parsedData')['isLocked']]",
      "fallbackResourceIds": ["[parameters('workbookSourceId')]"]
    },

    // convert back to an encoded string
    "reserializedData": "[string(variables('updatedWorkbookData'))]"
  },
  "resources": [
    {
      "name": "[parameters('workbookId')]",
      "type": "microsoft.insights/workbooks",
      "location": "[resourceGroup().location]",
      "apiVersion": "2018-06-17-preview",
      "dependsOn": [],
      "kind": "shared",
      "properties": {
        "displayName": "[parameters('workbookDisplayName')]",
        "serializedData": "[variables('reserializedData')]",
        "version": "1.0",
        "sourceId": "[parameters('workbookSourceId')]",
        "category": "workbook"
      }
    }
  ],
  "outputs": {
    "workbookId": {
      "type": "string",
      "value": "[resourceId( 'microsoft.insights/workbooks', parameters('workbookId'))]"
    }
  },
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#"
}

في هذا المثال، تسهل الخطوات التالية تخصيص قالب ARM مصدر:

تصدير المصنف كقالب ARM كما هو موضح في القسم السابق.
في قسم القالب variables :
1. serializedData تحليل القيمة في متغير كائن JSON، والذي ينشئ بنية JSON بما في ذلك صفيف من العناصر التي تمثل محتوى المصنف.
2. أنشئ كائنات JSON جديدة تمثل فقط العناصر/الخصائص التي سيتم تعديلها.
3. عرض مجموعة جديدة من عناصر محتوى JSON (updatedItems) باستخدام الدالة union() لتطبيق التعديلات على عناصر JSON الأصلية.
4. إنشاء كائن مصنف جديد، updatedWorkbookDataيحتوي على updatedItems/versionisLocked والبيانات من البيانات الأصلية التي تم تحليلها ومجموعة مصححة من .fallbackResourceIds
5. إعادة ترتيب محتوى JSON الجديد إلى متغير سلسلة جديد، reserializedData.
استخدم المتغير reserializedData الجديد بدلاً من خاصية serializedData الأصلية.
نشر مورد المصنف الجديد باستخدام قالب ARM المحدث.

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

اكتشف كيف يتم استخدام المصنفات لتشغيل تجربة نتيجة تحليلات التخزين الجديدة.

مشاركة عبر