بدء تشغيل دفتر تشغيل من الإخطارات على الويب

يسمح webhook لخدمة خارجية ببدء دفتر تشغيل معين في التنفيذ التلقائي في Azure من خلال طلب HTTP واحد. تشمل الخدمات الخارجية خدمات Azure DevOps وGitHub وسجلات Azure Monitor والتطبيقات المخصصة. يمكن لمثل هذه الخدمة استخدام webhook لبدء دفتر التشغيل دون تنفيذ واجهة برمجة التطبيقات الكاملة التنفيذ التلقائي في Azure. يمكنك مقارنة webhooks بطرق أخرى لبدء دفتر تشغيل في بدء دفتر تشغيل في التنفيذ التلقائي في Azure.

WebhooksOverview

لفهم متطلبات العميل ل TLS 1.2 أو أعلى مع webhooks، راجع TLS ل التنفيذ التلقائي في Azure.

خصائص Webhook

يصف الجدول التالي الخصائص التي يجب تكوينها لإخطار على الويب

Property Description
Name اسم إخطار على الويب. يمكنك تقديم أي اسم تريده، مادام أنه لا يتعرض للعميل. يستخدم فقط لتحديد دليل التشغيل في التنفيذ التلقائي في Azure. كأفضل ممارسة، يجب إعطاء إخطار على الويب اسم متعلق بالعميل الذي يستخدمه.
URL عنوان URL الخاص بإخطار على الويب. هذا هو العنوان الفريد الذي يستدعيه عميل باستخدام HTTP POST لبدء تشغيل دفتر التشغيل المرتبط بإ.خطار على الويب. يتم إنشاؤه تلقائيا عند إنشاء إخطار على الويب. لا يمكنك تحديد عنوان URL مخصص.

يحتوي عنوان URL على رمز أمان يسمح لنظام جهة خارجية باستدعاء دفتر التشغيل بدون مصادقة إضافية. لهذا السبب، يجب أن تتعامل مع عنوان URL ككلمة مرور. لأسباب أمنية، يمكنك فقط عرض الرابط في بوابة Azure عند إنشاء webhook. لاحظ عنوان URL في موقع آمن للاستخدام في المستقبل.
تاريخ انتهاء الصلاحية تاريخ انتهاء صلاحية إخطار على الويب، وبعد ذلك لم يعد من الممكن استخدامه. يمكنك تعديل تاريخ انتهاء الصلاحية بعد إنشاء إخطار على الويب طالما لم تنته صلاحية هذا الإخطار.
Enabled إعداد يشير إلى ما إذا كان الإخطار على الويب ممكنًا بشكل افتراضي عند إنشائه. إذا قمت بتعيين هذه الخاصية إلى معطَل، لا يمكن لأي عميل استخدام إخطار على الويب. يمكنك تعيين هذه الخاصية عند إنشاء إخطار على الويب أو أي وقت آخر بعد إنشائه.

المعلمات المستخدمة عند بدء إخطار على الويب تشغل دفتر تشغيل

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

لتلقي البيانات من العميل، يدعم دفتر التشغيل معلمة واحدة تسمى WebhookData. تُعرّف هذه المعلمة عنصر يحتوي على بيانات يتضمنها العميل في طلب POST.

خصائص WebhookData

تحظى ⁧WebhookData⁩ المعلمة بالخصائص التالية:

Property Description
WebhookName اسم إخطار على الويب.
RequestHeader PSCustomObject يحتوي على رؤوس طلب POST الوارد.
RequestBody نص طلب POST الوارد. يحتفظ هذا النص الأساسي بأي تنسيق بيانات، مثل السلسلة أو JSON أو XML أو ترميز النموذج. يجب كتابة دفتر التشغيل للعمل مع تنسيق البيانات المتوقع.

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

Note

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

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

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

على سبيل المثال، إذا كنت تبدأ الكتاب التالي من بوابة Azure وتريد تمرير بعض بيانات webhook النموذجية للاختبار، يجب عليك تمرير البيانات بنظام JSON في واجهة المستخدم.

معلمة WebhookData من واجهة المستخدم

للحصول على مثال دفتر التشغيل التالي، دعنا نعرّف الخصائص التالية WebhookData لـ:

  • Webhook الاسم: MyWebhook
  • RequestBody: *[{'ResourceGroup': 'myResourceGroup','Name': 'vm01'},{'ResourceGroup': 'myResourceGroup','Name': 'vm02'}]*

الآن نمرر عنصر JSON التالي في واجهة المستخدم WebhookData للمعلمة. هذا المثال، مع أحرف أحرف سطر جديد وإرجاع أحرف، يطابق التنسيق الذي تم تمريره من إخطار على الويب.

{"WebhookName":"mywebhook","RequestBody":"[\r\n {\r\n \"ResourceGroup\": \"vm01\",\r\n \"Name\": \"vm01\"\r\n },\r\n {\r\n \"ResourceGroup\": \"vm02\",\r\n \"Name\": \"vm02\"\r\n }\r\n]"}

بدء تشغيل المعلمة WebhookData من واجهة المستخدم

Note

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

أمان Webhook

يعتمد أمان إخطار الويب على خصوصية عنوان URL الخاص به، والذي يحتوي على رمز أمان يسمح باستدعاء هذا الإخطار. التنفيذ التلقائي في Azure لا يقوم بأي مصادقة على الطلب طالما تم تنفيذه على العنوان الصحيح. لهذا السبب، يجب أن لا يستخدم العملاء إخطار على الويب لدفاتر التشغيل التي تقوم بعمليات حساسة للغاية دون استخدام وسيلة بديلة للتحقق من صحة الطلب.

ضع في الاعتبار الإستراتيجيات التالية:

  • يمكنك تضمين منطق داخل دفتر تشغيل لتحديد ما إذا قد تم استدعاؤه من خلال إخطار على الويب. لديك دفتر التشغيل-تحقق من WebhookName خاصية WebhookData المعلمة. يمكن لدفتر التشغيل إجراء مزيد من التحقق من الصحة من خلال البحث عن معلومات معينة في RequestHeaderRequestBody وخصائص.

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

  • يدعم التنفيذ التلقائي في Azure وسوم خدمات الشبكة الافتراضية Azure، وتحديدا GuestAndHybridManagement. يمكنك استخدام علامات الخدمة لتعريف ضوابط الوصول إلى الشبكة على network security groups أو Azure Firewall وتفعيل webhooks من داخل شبكتك الافتراضية. يمكن استخدام علامات الخدمة بدلا من عناوين IP معينة عند إنشاء قواعد الأمان. من خلال تحديد اسم وسم الخدمة GuestAndHybridManagement في حقل المصدر أو الوجهة المناسب لقاعدة، يمكنك السماح أو رفض حركة المرور الخاصة بخدمة الأتمتة. لا تدعم علامة الخدمة هذه السماح بمزيد من التحكم الدقيق عن طريق تقييد نطاقات IP بمنطقة معينة.

إنشاء إخطار على الويب

Note

  • عند استخدام خطاف الويب مع دفتر تشغيل PowerShell 7، فإنه يحول معلمة إدخال خطاف الويب تلقائيا إلى JSON غير صالح. لمزيد من المعلومات، راجع المشكلات المعروفة - PowerShell 7.1 (معاينة). نوصي باستخدام خطاف الويب مع دفتر تشغيل PowerShell 5.
  • استخدام webhook لبدء دفتر تشغيل Python غير مدعوم.

لإنشاء إخطار على الويب، اتبع الخطوات التالية:

  1. إنشاء دفتر تشغيل PowerShell باستخدام التعليمات البرمجية التالية:

    param
(
    [Parameter(Mandatory=$false)]
    [object] $WebhookData
)

write-output "start"
write-output ("object type: {0}" -f $WebhookData.gettype())
write-output $WebhookData
write-output "`n`n"
write-output $WebhookData.WebhookName
write-output $WebhookData.RequestBody
write-output $WebhookData.RequestHeader
write-output "end"

if ($WebhookData.RequestBody) { 
    $names = (ConvertFrom-Json -InputObject $WebhookData.RequestBody)

        foreach ($x in $names)
        {
            $name = $x.Name
            Write-Output "Hello $name"
        }
}
else {
    Write-Output "Hello World!"
}

  2. إنشاء webhook باستخدام بوابة Azure أو PowerShell أو REST API. يتطلب الإخطار على الويب كتاب تشغيل منشور. تستخدم هذه الجولة نسخة معدلة من دليل الجولات تم إنشاؤها من إنشاء التنفيذ التلقائي في Azure runbook.

    لإنشاء webhook باستخدام بوابة Azure، قم بما يلي:

    1. سجل الدخول إلى بوابة Azure.

    2. في بوابة Azure، انتقل إلى حساب الأتمتة الخاص بك.

    3. تحت أتمتة العمليات، اختر كتب التشغيل لفتح صفحة دفاتر التشغيل .

    4. اختر دفتر التشغيل الخاص بك من القائمة لفتح صفحة نظرة عامة على كتاب التشغيل.

    5. اختر إضافة webhook لفتح صفحة إضافة Webhook .

      صفحة نظرة عامة على دفتر التشغيل مع تمييز أضف إخطار على الويب

    6. في صفحة إضافة Webhook ، اختر إنشاء webhook جديد.

      قم بإضافة صفحة إخطار على الويب مع إنشاء تمييز.

    7. أدخل اسم الهوك اللاسلكي. تاريخ انتهاء صلاحية حقل Expired افتراضيا ليصبح سنة واحدة من التاريخ الحالي.

    8. حدد أيقونة النسخ أو اضغط على Ctrl + C نسخ عنوان URL لخطاف الويب. ثم احفظ عنوان URL في موقع آمن.

      إنشاء صفحة إخطار على الويب مع تمييز عنوان URL.

      Important

      بمجرد إنشاء إخطار على الويب لا يمكنك استرداد عنوان URL مرة أخرى. تأكد من نسخه وتسجيله كما هو بالأعلى.

    9. اختر OK للعودة إلى صفحة إضافة Webhook .

    10. من صفحة إضافة Webhook ، اختر إعداد المعلمات وشغل الإعدادات لفتح صفحة المعلمات .

      إضافة صفحة إخطار ويب مع المعلمات المميزة

    11. راجع صفحة المعلمات . على سبيل المثال فإن دفتر التشغيل المستخدم في هذه المقالة، لا توجد تغييرات مطلوبة. اختر OK للعودة إلى صفحة إضافة Webhook .

    12. من صفحة إضافة Webhook ، اختر إنشاء (Create). يتم إنشاء webhook وتعود إلى صفحة Runbook Overview View.

استخدم إخطار ويب

يستخدم هذا المثال نموذج PowerShell cmdlet Invoke-WebRequest لإرسال طلب POST إلى webhook الجديد الخاص بك.

لاستخدام إخطار على الويب، اتبع الخطوات التالية:

  1. إعداد القيم للتمرير إلى دفتر التشغيل كإطار لاستدعاء إخطار الويب. بالنسبة للقيم البسيطة نسبيا، يمكنك كتابة القيم كما يلي:

    $Names  = @(
            @{ Name="Hawaii"},
            @{ Name="Seattle"},
            @{ Name="Florida"}
        )

$body = ConvertTo-Json -InputObject $Names

  2. بالنسبة إلى مجموعات أكبر، قد ترغب في استخدام ملف. قم بإنشاء ملف يسمى names.json والصق التعليمة البرمجية التالية فيه.

    [
    { "Name": "Hawaii" },
    { "Name": "Florida" },
    { "Name": "Seattle" }
]

    تغيير قيمة المتغير$file مع المسار الفعلي إلى ملف json قبل تشغيل أوامر PowerShell التالية.

    # Revise file path with actual path
$file = "path\names.json"
$bodyFile = Get-Content -Path $file

  3. تشغيل أوامر PowerShell التالية لاستدعاء إخطار ويب باستخدام API REST.

    $response = Invoke-WebRequest -Method Post -Uri $webhookURI -Body $body -UseBasicParsing
$response

$responseFile = Invoke-WebRequest -Method Post -Uri $webhookURI -Body $bodyFile -UseBasicParsing
$responseFile

    لأغراض توضيحية، تم إجراء استدعاءين للأسلوبين المختلفتين لإنتاج الجسم. للإنتاج، استخدم أسلوب واحد فقط. يجب أن الناتج مشابها كما يلي (يظهر ناتج واحد فقط):

    الناتج من استدعاء إخطار ويب.

    يتلقى العميل أحد تعلمات الإرجاع البرمجية التالية من POST الطلب.

    Code Text Description
    202 Accepted تم قبول الطلب، وتم وضع دفتر التشغيل في قائمة الانتظار بنجاح.
    400 طلب غير صحيح لم يتم قبول الطلب لأحد الأسباب التالية:
    • انتهت صلاحية إخطار الويب.
    • تم تعطيل إخطار الويب.
    • الرمز المميز في محدد موقع المعلومات غير صالح.
    404 غير موجود لم يتم قبول الطلب لأحد الأسباب التالية:
    • لم يتم العثور على إخطار الويب.
    • لم يتم العثور على دفتر التشغيل.
    • لم يتم العثور على الحساب.
    500 خطأ خادم داخلي كان محدد موقع الويب (URL) صالحًا، ولكن حدث خطأ. قم بإعادة إرسال الطلب.

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

    {"JobIds":["<JobId>"]}

  4. سيتم استخدام أداة PowerShell cmdlet Get-AzAutomationJobOutput للحصول على المخرجات. يمكن أيضا استخدام واجهة برمجة التطبيقات التنفيذ التلقائي في Azure.

    #isolate job ID
$jobid = (ConvertFrom-Json ($response.Content)).jobids[0]

# Get output
Get-AzAutomationJobOutput `
    -AutomationAccountName $automationAccount `
    -Id $jobid `
    -ResourceGroupName $resourceGroup `
    -Stream Output

    عند تشغيل دفتر تشغيل تم إنشاؤه في الخطوة السابقة، فإنه سيتم إنشاء وظيفة ويجب أن يبدو الإخراج مشابها لما يلي:

    الناتج من استدعاء إخطار ويب.

تحديث إخطار على الويب

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

  1. انتقل إلى دفتر التشغيل الذي يحتوي على إخطار ويب
  2. تحت قسم الموارد، اختر Webhooks، ثم webhook الذي تريد توسيعه.
  3. من صفحة Webhook ، اختر تاريخ ووقت انتهاء جديد ثم اختر حفظ.

مراجعة استدعاء API Webhook - Update و PowerShell cmdlet Set-AzAutomationWebhook للتعديلات المحتملة الأخرى.

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

فيما يلي أمثلة لإزالة إخطار ويب من كتاب التشغيل التلقائي.

  • باستخدام PowerShell، يمكن استخدام أداة Remove-AzAutomationWebhook cmdlet كما هو موضح أدناه. لم يتم إرجاع أي ناتج.

    Remove-AzAutomationWebhook `
    -ResourceGroup $resourceGroup `
    -AutomationAccountName $automationAccount `
    -Name $psWebhook

  • باستخدام REST، يمكن استخدام REST Webhook - حذف API كما هو موضح أدناه.

    Invoke-WebRequest -Method Delete -Uri $restURI -Headers $authHeader

    ناتج StatusCode : 200 يعني حذف ناجح.

إنشاء دفتر التشغيل وإخطار ويب مع قالب ARM

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

لإنشاء خطاف ويب باستخدام قالب ARM، اتبع الخطوات التالية:

  1. قم بإنشاء ملف يسمى webhook_deploy.json والصق التعليمة البرمجية التالية فيه.

    {
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "automationAccountName": {
            "type": "String",
            "metadata": {
                "description": "Automation account name"
            }
        },
        "webhookName": {
            "type": "String",
            "metadata": {
                "description": "Webhook Name"
            }
        },
        "runbookName": {
            "type": "String",
            "metadata": {
                "description": "Runbook Name for which webhook will be created"
            }
        },
        "WebhookExpiryTime": {
            "type": "String",
            "metadata": {
                "description": "Webhook Expiry time"
            }
        },
        "_artifactsLocation": {
            "defaultValue": "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.automation/101-automation/",
            "type": "String",
            "metadata": {
                "description": "URI to artifacts location"
            }
        }
    },
    "resources": [
        {
            "type": "Microsoft.Automation/automationAccounts",
            "apiVersion": "2020-01-13-preview",
            "name": "[parameters('automationAccountName')]",
            "location": "[resourceGroup().location]",
            "properties": {
                "sku": {
                    "name": "Free"
                }
            },
            "resources": [
                {
                    "type": "runbooks",
                    "apiVersion": "2018-06-30",
                    "name": "[parameters('runbookName')]",
                    "location": "[resourceGroup().location]",
                    "dependsOn": [
                        "[parameters('automationAccountName')]"
                    ],
                    "properties": {
                        "runbookType": "Python2",
                        "logProgress": "false",
                        "logVerbose": "false",
                        "description": "Sample Runbook",
                        "publishContentLink": {
                            "uri": "[uri(parameters('_artifactsLocation'), 'scripts/AzureAutomationTutorialPython2.py')]",
                            "version": "1.0.0.0"
                        }
                    }
                },
                {
                    "type": "webhooks",
                    "apiVersion": "2018-06-30",
                    "name": "[parameters('webhookName')]",
                    "dependsOn": [
                        "[parameters('automationAccountName')]",
                        "[parameters('runbookName')]"
                    ],
                    "properties": {
                        "isEnabled": true,
                        "expiryTime": "[parameters('WebhookExpiryTime')]",
                        "runbook": {
                            "name": "[parameters('runbookName')]"
                        }
                    }
                }
            ]
        }
    ],
    "outputs": {
        "webhookUri": {
            "type": "String",
            "value": "[reference(parameters('webhookName')).uri]"
        }
    }
}

  2. يقوم نموذج التعليمات البرمجية PowerShell التالي بتوزيع القالب من الجهاز. قم بتوفير قيمة مناسبة للمتغيرات، ثم قم بتنفيذ البرنامج النصي.

    $resourceGroup = "resourceGroup"
$templateFile = "path\webhook_deploy.json"
$armAutomationAccount = "automationAccount"
$armRunbook = "ARMrunbookName"
$armWebhook = "webhookName"
$webhookExpiryTime = "12-31-2022"

New-AzResourceGroupDeployment `
    -Name "testDeployment" `
    -ResourceGroupName $resourceGroup `
    -TemplateFile $templateFile `
    -automationAccountName $armAutomationAccount `
    -runbookName $armRunbook `
    -webhookName $armWebhook `
    -WebhookExpiryTime $webhookExpiryTime

    Note

    لأسباب أمنية، يتم إرجاع عنوان URI فقط في المرة الأولى التي يتم فيها نشر قالب.

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

  • Last updated on