إدارة موارد Application Insights باستخدام PowerShell

مقالة
10/18/2023

إشعار

نوصي باستخدام الوحدة النمطية Azure Az PowerShell للتفاعل مع Azure. راجع تثبيت Azure PowerShell للبدء. لمعرفة كيفية الترحيل إلى الوحدة النمطية Az PowerShell، راجع ترحيل Azure PowerShell من AzureRM إلى Az.

توضح هذه المقالة كيفية أتمتة إنشاء وتحديث موارد Application Insights تلقائيا باستخدام Azure Resource Manager. قد تقوم بذلك، على سبيل المثال، كجزء من عملية الإنشاء. بالإضافة إلى مورد Application Insights الأساسي، يمكنك إنشاء اختبارات ويب للتوفر، وإعداد التنبيهات،وتعيين نظام التسعير، وإنشاء موارد Azure أخرى.

مفتاح إنشاء هذه الموارد هو قوالب JSON ل Resource Manager. الإجراء الأساسي هو:

قم بتنزيل تعريفات JSON للموارد الموجودة.
تحديد معلمات قيم معينة، مثل الأسماء.
قم بتشغيل القالب كلما أردت إنشاء مورد جديد.

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

الإعداد لمرة واحدة

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

تركيب مثبت النظام الأساسي لويب Microsoft (الإصدار 5 أو أحدث).
استخدمه لتثبيت Azure PowerShell.

بالإضافة إلى استخدام قوالب Azure Resource Manager (قوالب ARM)، هناك مجموعة غنية من Application Insights PowerShell cmdlets. تسهل أوامر cmdlets هذه تكوين موارد Application Insights برمجيا. يمكنك استخدام الإمكانات التي تم تمكينها بواسطة cmdlets من أجل:

إنشاء موارد Application Insights وحذفها.
الحصول على قوائم موارد Application Insights وخصائصها.
إنشاء وإدارة التصدير المستمر.
إنشاء مفاتيح التطبيق وإدارتها.
تعيين الحد الأقصى اليومي.
قم بتعيين خطة التسعير.

إنشاء موارد Application Insights باستخدام PowerShell cmdlet

فيما يلي كيفية إنشاء مورد Application Insights جديد في مركز بيانات Azure East US باستخدام الأمر cmdlet New-AzApplicationInsights :

New-AzApplicationInsights -ResourceGroupName <resource group> -Name <resource name> -location eastus

إنشاء موارد Application Insights باستخدام قالب ARM

فيما يلي كيفية إنشاء مورد Application Insights جديد باستخدام قالب ARM.

إنشاء قالب ARM

إنشاء ملف .json جديد. دعونا نسميها template1.json في هذا المثال. نسخ هذا المحتوى فيه:

    {
        "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
        "contentVersion": "1.0.0.0",
        "parameters": {
            "appName": {
                "type": "string",
                "metadata": {
                    "description": "Enter the name of your Application Insights resource."
                }
            },
            "appType": {
                "type": "string",
                "defaultValue": "web",
                "allowedValues": [
                    "web",
                    "java",
                    "other"
                ],
                "metadata": {
                    "description": "Enter the type of the monitored application."
                }
            },
            "appLocation": {
                "type": "string",
                "defaultValue": "eastus",
                "metadata": {
                    "description": "Enter the location of your Application Insights resource."
                }
            },
            "retentionInDays": {
                "type": "int",
                "defaultValue": 90,
                "allowedValues": [
                    30,
                    60,
                    90,
                    120,
                    180,
                    270,
                    365,
                    550,
                    730
                ],
                "metadata": {
                    "description": "Data retention in days"
                }
            },
            "ImmediatePurgeDataOn30Days": {
                "type": "bool",
                "defaultValue": false,
                "metadata": {
                    "description": "If set to true when changing retention to 30 days, older data will be immediately deleted. Use this with extreme caution. This only applies when retention is being set to 30 days."
                }
            },
            "priceCode": {
                "type": "int",
                "defaultValue": 1,
                "allowedValues": [
                    1,
                    2
                ],
                "metadata": {
                    "description": "Pricing plan: 1 = Per GB (or legacy Basic plan), 2 = Per Node (legacy Enterprise plan)"
                }
            },
            "dailyQuota": {
                "type": "int",
                "defaultValue": 100,
                "minValue": 1,
                "metadata": {
                    "description": "Enter daily quota in GB."
                }
            },
            "dailyQuotaResetTime": {
                "type": "int",
                "defaultValue": 0,
                "metadata": {
                    "description": "Enter daily quota reset hour in UTC (0 to 23). Values outside the range will get a random reset hour."
                }
            },
            "warningThreshold": {
                "type": "int",
                "defaultValue": 90,
                "minValue": 1,
                "maxValue": 100,
                "metadata": {
                    "description": "Enter the % value of daily quota after which warning mail to be sent. "
                }
            }
        },
        "variables": {
            "priceArray": [
                "Basic",
                "Application Insights Enterprise"
            ],
            "pricePlan": "[take(variables('priceArray'),parameters('priceCode'))]",
            "billingplan": "[concat(parameters('appName'),'/', variables('pricePlan')[0])]"
        },
        "resources": [
            {
                "type": "microsoft.insights/components",
                "kind": "[parameters('appType')]",
                "name": "[parameters('appName')]",
                "apiVersion": "2014-04-01",
                "location": "[parameters('appLocation')]",
                "tags": {},
                "properties": {
                    "ApplicationId": "[parameters('appName')]",
                    "retentionInDays": "[parameters('retentionInDays')]",
                    "ImmediatePurgeDataOn30Days": "[parameters('ImmediatePurgeDataOn30Days')]"
                },
                "dependsOn": []
            },
            {
                "name": "[variables('billingplan')]",
                "type": "microsoft.insights/components/CurrentBillingFeatures",
                "location": "[parameters('appLocation')]",
                "apiVersion": "2015-05-01",
                "dependsOn": [
                    "[resourceId('microsoft.insights/components', parameters('appName'))]"
                ],
                "properties": {
                    "CurrentBillingFeatures": "[variables('pricePlan')]",
                    "DataVolumeCap": {
                        "Cap": "[parameters('dailyQuota')]",
                        "WarningThreshold": "[parameters('warningThreshold')]",
                        "ResetTime": "[parameters('dailyQuotaResetTime')]"
                    }
                }
            }
        ]
    }

استخدام قالب ARM لإنشاء مورد Application Insights جديد

في PowerShell، سجل الدخول إلى Azure باستخدام $Connect-AzAccount.
قم بتعيين السياق الخاص بك إلى اشتراك باستخدام Set-AzContext "<subscription ID>".
تشغيل توزيع جديد لإنشاء مورد Application Insights جديد:
```
    New-AzResourceGroupDeployment -ResourceGroupName Fabrikam `
           -TemplateFile .\template1.json `
           -appName myNewApp
```
- -ResourceGroupName هي المجموعة التي تريد إنشاء الموارد الجديدة فيها.
- -TemplateFile يجب أن تحدث قبل المعلمات المخصصة.
- -appName هو اسم المورد المراد إنشاؤه.

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

احصل على مفتاح الجهاز.

بعد إنشاء مورد تطبيق، ستحتاج إلى مفتاح تقرير عن حالة النظام:

سجل الدخول إلى Azure باستخدام $Connect-AzAccount.
قم بتعيين السياق الخاص بك إلى اشتراك باستخدام Set-AzContext "<subscription ID>".
ثم استخدم:
1. $resource = Get-AzResource -Name "<resource name>" -ResourceType "Microsoft.Insights/components"
2. $details = Get-AzResource -ResourceId $resource.ResourceId
3. $details.Properties.InstrumentationKey

لمشاهدة قائمة من العديد من الخصائص الأخرى من مورد Insights التطبيق الخاص بك، استخدم:

Get-AzApplicationInsights -ResourceGroupName Fabrikam -Name FabrikamProd | Format-List

تتوفر المزيد من الخصائص عبر أوامر cmdlets:

Set-AzApplicationInsightsDailyCap
Set-AzApplicationInsightsPricingPlan
Get-AzApplicationInsightsApiKey
Get-AzApplicationInsightsContinuousExport

راجع الوثائق التفصيلية للمعلمات الخاصة ب cmdlets هذه.

إشعار

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

تعيين استبقاء البيانات

يمكنك استخدام الطرق الثلاث التالية لتعيين استبقاء البيانات برمجيا على مورد Application Insights.

تعيين استبقاء البيانات باستخدام أوامر PowerShell

إليك مجموعة بسيطة من أوامر PowerShell لتعيين الاحتفاظ بالبيانات لمورد Application Insights الخاص بك:

$Resource = Get-AzResource -ResourceType Microsoft.Insights/components -ResourceGroupName MyResourceGroupName -ResourceName MyResourceName
$Resource.Properties.RetentionInDays = 365
$Resource | Set-AzResource -Force

تعيين استبقاء البيانات باستخدام REST

للحصول على الاحتفاظ بالبيانات الحالية لمورد Insights التطبيق الخاص بك، يمكنك استخدام أداة OSS ARMClient. تعرف على المزيد حول ARMClient من مقالات ديفيد إيبو ودانيال بوبيز. فيما يلي مثال يستخدم ARMClient للحصول على الاستبقاء الحالي:

armclient GET /subscriptions/00000000-0000-0000-0000-00000000000/resourceGroups/MyResourceGroupName/providers/microsoft.insights/components/MyResourceName?api-version=2018-05-01-preview

لتعيين الاستبقاء، الأمر هو PUT مشابه:

armclient PUT /subscriptions/00000000-0000-0000-0000-00000000000/resourceGroups/MyResourceGroupName/providers/microsoft.insights/components/MyResourceName?api-version=2018-05-01-preview "{location: 'eastus', properties: {'retentionInDays': 365}}"

لتعيين الاحتفاظ بالبيانات إلى 365 يوما باستخدام القالب السابق، قم بتشغيل:

New-AzResourceGroupDeployment -ResourceGroupName "<resource group>" `
       -TemplateFile .\template1.json `
       -retentionInDays 365 `
       -appName myApp

تعيين استبقاء البيانات باستخدام برنامج نصي PowerShell

يمكن أيضاً استخدام البرنامج النصي التالي لتغيير الاستبقاء. انسخ هذا البرنامج النصي لحفظه ك Set-ApplicationInsightsRetention.ps1.

Param(
    [Parameter(Mandatory = $True)]
    [string]$SubscriptionId,

    [Parameter(Mandatory = $True)]
    [string]$ResourceGroupName,

    [Parameter(Mandatory = $True)]
    [string]$Name,

    [Parameter(Mandatory = $True)]
    [string]$RetentionInDays
)
$ErrorActionPreference = 'Stop'
if (-not (Get-Module Az.Accounts)) {
    Import-Module Az.Accounts
}
$azProfile = [Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile
if (-not $azProfile.Accounts.Count) {
    Write-Error "Ensure you have logged in before calling this function."    
}
$currentAzureContext = Get-AzContext
$profileClient = New-Object Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient($azProfile)
$token = $profileClient.AcquireAccessToken($currentAzureContext.Tenant.TenantId)
$UserToken = $token.AccessToken
$RequestUri = "https://management.azure.com/subscriptions/$($SubscriptionId)/resourceGroups/$($ResourceGroupName)/providers/Microsoft.Insights/components/$($Name)?api-version=2015-05-01"
$Headers = @{
    "Authorization"         = "Bearer $UserToken"
    "x-ms-client-tenant-id" = $currentAzureContext.Tenant.TenantId
}
## Get Component object via ARM
$GetResponse = Invoke-RestMethod -Method "GET" -Uri $RequestUri -Headers $Headers 

## Update RetentionInDays property
if($($GetResponse.properties | Get-Member "RetentionInDays"))
{
    $GetResponse.properties.RetentionInDays = $RetentionInDays
}
else
{
    $GetResponse.properties | Add-Member -Type NoteProperty -Name "RetentionInDays" -Value $RetentionInDays
}
## Upsert Component object via ARM
$PutResponse = Invoke-RestMethod -Method "PUT" -Uri "$($RequestUri)" -Headers $Headers -Body $($GetResponse | ConvertTo-Json) -ContentType "application/json"
$PutResponse

يمكن استخدام هذا البرنامج النصي بعد ذلك كما يلي:

Set-ApplicationInsightsRetention `
        [-SubscriptionId] <String> `
        [-ResourceGroupName] <String> `
        [-Name] <String> `
        [-RetentionInDays <Int>]

تعيين نقطة الارتكاز اليومية

للحصول على خصائص الحد الأقصى اليومي، استخدم Set-AzApplicationInsightsPricingPlan cmdlet:

Set-AzApplicationInsightsDailyCap -ResourceGroupName <resource group> -Name <resource name> | Format-List

لتعيين خصائص الحد الأقصى اليومي، استخدم نفس cmdlet. على سبيل المثال، لتعيين الحد الأقصى إلى 300 غيغابايت في اليوم:

Set-AzApplicationInsightsDailyCap -ResourceGroupName <resource group> -Name <resource name> -DailyCapGB 300

يمكنك أيضًا استخدام ARMClient للحصول على معلمات الحد الأقصى اليومي وتعيينها. للحصول على القيم الحالية، استخدم:

armclient GET /subscriptions/00000000-0000-0000-0000-00000000000/resourceGroups/MyResourceGroupName/providers/microsoft.insights/components/MyResourceName/CurrentBillingFeatures?api-version=2018-05-01-preview

تعيين وقت إعادة تعيين الحد الأقصى اليومي

لتعيين وقت إعادة تعيين الحد الأقصى اليومي، يمكنك استخدام ARMClient. فيما يلي مثال يستخدم ARMClient لتعيين وقت إعادة الضبط إلى ساعة جديدة. يوضح هذا المثال التوقيت العالمي المتفق عليه 12:00:

armclient PUT /subscriptions/00000000-0000-0000-0000-00000000000/resourceGroups/MyResourceGroupName/providers/microsoft.insights/components/MyResourceName/CurrentBillingFeatures?api-version=2018-05-01-preview "{'CurrentBillingFeatures':['Basic'],'DataVolumeCap':{'Cap':100,'WarningThreshold':80,'ResetTime':12}}"

قم بتعيين خطة التسعير

للحصول على خطة التسعير الحالية، استخدم Set-AzApplicationInsightsPricingPlan cmdlet:

Set-AzApplicationInsightsPricingPlan -ResourceGroupName <resource group> -Name <resource name> | Format-List

لتعيين خطة التسعير، استخدم نفس cmdlet مع -PricingPlan المحدد:

Set-AzApplicationInsightsPricingPlan -ResourceGroupName <resource group> -Name <resource name> -PricingPlan Basic

يمكنك أيضا تعيين خطة التسعير على مورد Application Insights موجود باستخدام قالب ARM السابق، مع حذف مورد "microsoft.insights/components" والعقدة dependsOn من مورد الفوترة. على سبيل المثال، لتعيينه إلى خطة لكل جيجابايت (تسمى سابقا الخطة الأساسية)، قم بتشغيل:

        New-AzResourceGroupDeployment -ResourceGroupName "<resource group>" `
               -TemplateFile .\template1.json `
               -priceCode 1 `
               -appName myApp

يتم تعريف priceCodeعلى النحو التالي:

priceCode	الخطة
1	لكل جيجابايت (كان يُسمى سابقًا الخطة الأساسية)
2	لكل عقدة (الاسم السابق لخطة Enterprise)

وأخيرًا، يمكنك استخدام ARMClient للحصول على خطط التسعير والمعلمات الحد الأقصى اليومي وتعيينها. للحصول على القيم الحالية، استخدم:

armclient GET /subscriptions/00000000-0000-0000-0000-00000000000/resourceGroups/MyResourceGroupName/providers/microsoft.insights/components/MyResourceName/CurrentBillingFeatures?api-version=2018-05-01-preview

يمكنك تعيين كافة هذه المعلمات باستخدام:

armclient PUT /subscriptions/00000000-0000-0000-0000-00000000000/resourceGroups/MyResourceGroupName/providers/microsoft.insights/components/MyResourceName/CurrentBillingFeatures?api-version=2018-05-01-preview
"{'CurrentBillingFeatures':['Basic'],'DataVolumeCap':{'Cap':200,'ResetTime':12,'StopSendNotificationWhenHitCap':true,'WarningThreshold':90,'StopSendNotificationWhenHitThreshold':true}}"

ستقوم هذه التعليمة البرمجية بتعيين الحد الأقصى اليومي إلى 200 جيجابايت يوميا، وتكوين وقت إعادة تعيين الحد الأقصى اليومي إلى 12:00 بالتوقيت العالمي المتفق عليه، وإرسال رسائل البريد الإلكتروني عند الوصول إلى الحد الأقصى واستيفاء مستوى التحذير، وتعيين حد التحذير إلى 90٪ من الحد الأقصى.

قم بإضافة تنبيه متري

لأتمتة إنشاء تنبيهات قياسية، راجع مقالة قالب التنبيهات القياسية.

قم بإضافة اختبار التوافر

لأتمتة اختبارات التوفر، راجع مقالة قالب التنبيهات القياسية.

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

لأتمتة إنشاء أي مورد آخر من أي نوع، قم بإنشاء مثال يدويا ثم انسخ التعليمات البرمجية الخاصة به وحدد معلمات لها من Azure Resource Manager.

حول Azure Resource Manager. انتقل لأسفل إلى subscriptions/resourceGroups/<your resource group>/providers/Microsoft.Insights/components مورد التطبيق الخاص بك.

المكونات هي موارد Application Insights الأساسية لعرض التطبيقات. هناك موارد منفصلة لقواعد التنبيه المقترنة واختبارات ويب التوفر.
نسخ JSON المكون إلى المكان المناسب في template1.json.
حذف هذه الخصائص:
- id
- InstrumentationKey
- CreationDate
- TenantId
افتح أقسام webtests وalertrules ونسخ JSON للعناصر الفردية في القالب. لا تنسخ من webtests العقد أو alertrules . انتقل إلى العناصر الموجودة أسفلها.

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

"apiVersion": "2015-05-01",

تعيين معلمات القالب

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

لا يمكنك تحديد معلمات جزء فقط من سلسلة، لذا استخدم concat() لإنشاء سلاسل.

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

بحث	استبدال بـ
`"hidden-link:/subscriptions/.../../components/MyAppName"`	`"[concat('hidden-link:',` `resourceId('microsoft.insights/components',` `parameters('appName')))]"`
`"/subscriptions/.../../alertrules/myAlertName-myAppName-subsId",`	`"[resourceId('Microsoft.Insights/alertrules', variables('alertRuleName'))]",`
`"/subscriptions/.../../webtests/myTestName-myAppName",`	`"[resourceId('Microsoft.Insights/webtests', parameters('webTestName'))]",`
`"myWebTest-myAppName"`	`"[variables(testName)]"'`
`"myTestName-myAppName-subsId"`	`"[variables('alertRuleName')]"`
`"myAppName"`	`"[parameters('appName')]"`
`"myappname"` (أحرف صغيرة)	`"[toLower(parameters('appName'))]"`
`"<WebTest Name=\"myWebTest\" ...` `Url=\"http://fabrikam.com/home\" ...>"`	`[concat('<WebTest Name=\"',` `parameters('webTestName'),` `'\" ... Url=\"', parameters('Url'),` `'\"...>')]"`

تعيين التبعيات بين الموارد

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

في مورد اختبار التوفر:

"dependsOn": ["[resourceId('Microsoft.Insights/components', parameters('appName'))]"],
في مورد التنبيه لاختبار التوفر:

"dependsOn": ["[resourceId('Microsoft.Insights/webtests', variables('testName'))]"],

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

راجع مقالات التشغيل التلقائي الأخرى هذه:

إنشاء مورد Application Insights
إنشاء اختبارات ويب.
إرسال تشخيصات Azure إلى Application Insights.
إنشاء تعليقات توضيحية للإصدار.