مشاركة عبر

دليل مطور PowerShell في Azure Functions

تقدم هذه المقالة تفاصيل حول كيفية كتابة Azure Functions باستخدام PowerShell.

يتم تمثيل وظيفة PowerShell Azure (الوظيفة) كبرنامج PowerShell نصي يتم تنفيذه عند التشغيل. يحتوي كل برنامج نصي للوظيفة على ملف function.json مرتبط يحدد كيفية تصرف الوظيفة، مثل كيفية تشغيلها ومعلمات إدخالها وإخراجها. لمعرفة المزيد، راجع مفاهيم مشغلات وروابط دالات Azure.

مثل أنواع أخرى من الوظائف، تشتمل وظائف برنامج PowerShell النصي على المعلمات التي تطابق أسماء جميع عمليات ربط بيانات المدخلات المحددة في ملف function.json. يتم تمرير معلمة TriggerMetadata أيضاً التي تحتوي على معلومات إضافية حول المشغِّل الذي بدأ تشغيل الوظيفة.

تفترض هذه المقالة أنك قرأت بالفعل دليل مطور Azure Functions. كما يفترض أنك أكملت التشغيل السريع للوظائف ل PowerShell لإنشاء أول دالة PowerShell.

بنية المجلد

تبدو بنية المجلد المطلوبة لمشروع PowerShell كما يلي. يمكن تغيير هذا الافتراضي. لمزيد من المعلومات، راجع قسم scriptFile .

PSFunctionApp
 | - MyFirstFunction
 | | - run.ps1
 | | - function.json
 | - MySecondFunction
 | | - run.ps1
 | | - function.json
 | - Modules
 | | - myFirstHelperModule
 | | | - myFirstHelperModule.psd1
 | | | - myFirstHelperModule.psm1
 | | - mySecondHelperModule
 | | | - mySecondHelperModule.psd1
 | | | - mySecondHelperModule.psm1
 | - local.settings.json
 | - host.json
 | - requirements.psd1
 | - profile.ps1
 | - extensions.csproj
 | - bin

في جذر المشروع، يوجد ملف host.json مشترك يمكن استخدامه لتكوين تطبيق الوظائف. تحتوي كل وظيفة على مجلد مع ملف التعليمات البرمجية الخاص به (‎.ps1) وملف تكوين ربط البيانات (function.json). يكون اسم الدليل الأصل لملف function.json هو اسم الوظيفة دائماً.

تتطلب عمليات ربط بيانات معينة وجود ملف extensions.csproj. يتم تحديد ملحقات ربط البيانات المطلوبة في الإصدار ‎2.x والإصدارات الأحدث من وقت تشغيل Functions في ملف extensions.csproj، مع ملفات المكتبة الفعلية في مجلد bin. عند التطوير محليًا، يجب عليك تسجيل ملحقات الربط. عند تطوير وظائف في مدخل Microsoft Azure، يتم هذا التسجيل نيابة عنك.

في PowerShell Function Apps، قد يكون لديك profile.ps1 اختياريا الذي يتم تشغيله عند بدء تشغيل تطبيق دالة (وإلا تعرف كبداية باردة). لمزيد من المعلومات، انظر ملف تعريف PowerShell.

تحديد برنامج PowerShell نصي كوظيفة

بشكل افتراضي، يبحث وقت تشغيل الوظائف عن وظيفتك في run.ps1، حيث يشارك run.ps1 نفس الدليل الأصل مثل function.json المطابق له.

يتم تمرير البرنامج النصي الخاص بك عدة وسيطات عند التنفيذ. لمعالجة هذه المعلمات، أضف كتلة param إلى الجزء العلوي من البرنامج النصي كما في المثال التالي:

# $TriggerMetadata is optional here. If you don't need it, you can safely remove it from the param block
param($MyFirstInputBinding, $MySecondInputBinding, $TriggerMetadata)

معلمة TriggerMetadata

يتم استخدام معلمة TriggerMetadata لتوفير معلومات إضافية حول المشغِّل. تختلف بيانات التعريف هذه من ربط إلى ربط ولكنها تحتوي جميعها على sys خاصية تحتوي على البيانات التالية:

$TriggerMetadata.sys
الخاصية الوصف النوع
UtcNow توقيت تشغيل الوظيفة بالتوقيت العالمي المتفق عليه (UTC) التاريخ والوقت
اسم الأسلوب اسم الوظيفة التي تم تشغيلها سلسلة
RandGuid معرّف فريد لتنفيذ الوظيفة سلسلة

يحتوي كل نوع مشغِّل على مجموعة مختلفة من بيانات التعريف. على سبيل المثال، يحتوي $TriggerMetadata لـ QueueTrigger على InsertionTime وId وDequeueCount وغير ذلك من الأمور. لمزيد من المعلومات حول بيانات تعريف مشغِّل قائمة الانتظار، انتقل إلى الوثائق الرسمية لمشغِّلات قائمة الانتظار. تحقق من الوثائق بخصوص المشغِّلات التي تستخدمها لمعرفة ما يرد داخل بيانات تعريف المشغِّل.

الارتباطات

في PowerShell يتم تكوين عمليات ربط البيانات وتحديدها في ملف function.json للوظيفة. تتفاعل الدوال مع الروابط بطرق عديدة.

قراءة بيانات المشغِّل والإدخال

تتم قراءة عمليات ربط بيانات المشغِّل والمدخلات كمعلمات يتم تمريرها إلى الوظيفة. تحتوي عمليات ربط بيانات المدخلات على direction معيناً على in في function.js. تكون خاصية name المحددة في function.json هي اسم المعلمة، في كتلة param. نظراً لأن PowerShell تستخدم معلمات مسماة لربط البيانات، لا يكون ترتيب المعلمات مهماً. ومع ذلك، من أفضل الممارسات اتباع ترتيب عمليات ربط البيانات المحددة في function.json.

param($MyFirstInputBinding, $MySecondInputBinding)

كتابة بيانات الإخراج

في Functions، يحتوي ربط بيانات المخرجات على direction معيناً على out في function.js. يمكنك الكتابة في ربط بيانات المخرجات باستخدام أمر cmdlet‏ Push-OutputBinding، وهو متوفر في وقت تشغيل Functions. في جميع الحالات، تتوافق خاصية name لربط البيانات على النحو المحدد في function.json مع معلمة Name لأمر cmdlet‏ Push-OutputBinding.

يوضح المثال التالي كيفية استدعاء Push-OutputBinding في البرنامج النصي للدالة:

param($MyFirstInputBinding, $MySecondInputBinding)

Push-OutputBinding -Name myQueue -Value $myValue

يمكنك أيضاً تمرير قيمة ربط بيانات محدد من خلال البنية الأساسية لبرنامج ربط العمليات التجارية.

param($MyFirstInputBinding, $MySecondInputBinding)

Produce-MyOutputValue | Push-OutputBinding -Name myQueue

تتصرف Push-OutputBinding بشكل مختلف استناداً إلى القيمة المحددة لـ -Name:

  • عندما لا يمكن حل الاسم المحدد إلى ربط إخراج صالح، يتم طرح خطأ.

  • عندما يقبل ربط بيانات المخرجات مجموعة من القيم، يمكنك استدعاء Push-OutputBinding بشكل متكرر لدفع قيم متعددة.

  • عندما يقبل ربط بيانات المخرجات قيمة قاعدة بيانات أحادية فقط، يؤدي استدعاء Push-OutputBinding مرة ثانية إلى ظهور خطأ.

بناء جملة Push-OutputBinding

فيما يلي معلمات صالحة لاستدعاء Push-OutputBinding:

الاسم النوع موضع الوصف
-Name السلسلة‬ 1 اسم ربط بيانات المخرجات الذي تريد تعيينه.
-Value ‏‏الكائن 2 قيمة ربط بيانات المخرجات الذي تريد تعيينه، والذي يتم قبوله من البنية الأساسية لبرنامج ربط العمليات التجارية ByValue.
-Clobber أداة تبديل المعلمات مسمى (اختياري) عند تحديده، يفرض القيمة التي سيتم تعيينها لربط بيانات مخرجات محدد.

كما يتم دعم المعلمات الشائعة التالية:

  • Verbose
  • Debug
  • ErrorAction
  • ErrorVariable
  • WarningAction
  • WarningVariable
  • OutBuffer
  • PipelineVariable
  • OutVariable

للحصول على مزيدٍ من المعلومات، راجع حول CommonParameters.

مثال Push-OutputBinding: استجابات HTTP

يُرجِع مشغِّل HTTP رداً باستخدام ربط بيانات مخرجات يسمى response. في المثال التالي، قيمة ربط بيانات مخرجات response هي "output #1":

Push-OutputBinding -Name response -Value ([HttpResponseContext]@{
StatusCode = [System.Net.HttpStatusCode]::OK
Body = "output #1"
})

لأن المخرجات تكون إلى HTTP الذي يقبل قيمة قاعدة بيانات أحادية فقط، يتم طرح خطأ عند استدعاء Push-OutputBinding مرة ثانية.

Push-OutputBinding -Name response -Value ([HttpResponseContext]@{
StatusCode = [System.Net.HttpStatusCode]::OK
Body = "output #2"
})

بالنسبة للمخرجات التي تقبل قيم قاعدة بيانات أحادية فقط، يمكنك استخدام معلمة -Clobber لمنع القيمة القديمة بدلاً من محاولة الإضافة إلى مجموعة. يفترض المثال التالي أنك أضفت قيمة بالفعل. باستخدام -Clobber، يمنع الرد من المثال التالي القيمة الموجودة لإرجاع قيمة "output #3":

Push-OutputBinding -Name response -Value ([HttpResponseContext]@{
StatusCode = [System.Net.HttpStatusCode]::OK
Body = "output #3"
}) -Clobber

مثال Push-OutputBinding: ربط بيانات مخرجات قائمة الانتظار

يتم استخدام Push-OutputBinding لإرسال البيانات إلى عمليات ربط بيانات المخرجات، مثل ربط بيانات مخرجات Azure Queue Storage. في المثال التالي، تحتوي الرسالة المكتوبة في قائمة الانتظار قيمة "output #1":

Push-OutputBinding -Name outQueue -Value "output #1"

يقبل ربط بيانات المخرجات قائمة انتظار تخزين قيم مخرجات متعددة. في هذه الحالة، يستدعي المثال التالي بعد الأول إلى الكتابة في قائمة الانتظار قائمة بعنصرين: "output #1" و"output #2".

Push-OutputBinding -Name outQueue -Value "output #2"

يضيف المثال التالي، عند استدعائه بعد المثالين السابقين، قيمتين أكثر إلى مجموعة المخرجات:

Push-OutputBinding -Name outQueue -Value @("output #3", "output #4")

عند كتابتها في قائمة الانتظار، تحتوي الرسالة على هذه القيم الأربع: "output #1" و"output #2" و"output #3" و"output #4".

أمر cmdlet‏ OutputBinding

يمكنك استخدام أمر cmdlet‏ Get-OutputBinding لاسترداد القيم التي تم تعيينها حالياً لعمليات ربط بيانات المخرجات. يسترد أمر cmdlet جدول تجزئة يحتوي على أسماء عمليات ربط بيانات المخرجات مع قيمها الخاصة.

يستخدم Get-OutputBinding المثال التالي لإرجاع قيم الربط الحالية:

Get-OutputBinding

Name                           Value
----                           -----
MyQueue                        myData
MyOtherQueue                   myData

يحتوي Get-OutputBinding أيضاً على معلمة تسمى -Name، والتي يمكن استخدامها لتصفية ربط البيانات الذي تم إرجاعه، كما في المثال التالي:

Get-OutputBinding -Name MyQ*

Name                           Value
----                           -----
MyQueue                        myData

يتم دعم أحرف البدل (*) في Get-OutputBinding.

تسجيل الدخول

يعمل التسجيل في وظائف PowerShell مثل تسجيل PowerShell العادي. يمكنك استخدام أوامر cmdlet للتسجيل للكتابة في كل تدفق إنتاج. يتم تعيين كل cmdlet إلى مستوى سجل يستخدمه Functions.

مستوى تسجيل Functions أمر cmdlet للتسجيل
خطأ Write-Error
تحذير Write-Warning
‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏المعلومات Write-Information
Write-Host
Write-Output
يكتب إلى مستوى السجل Information.
تصحيح Write-Debug
أثر Write-Progress
Write-Verbose

بالإضافة إلى أوامر cmdlet هذه، يتم إعادة توجيه أي شيء مكتوب في البنية الأساسية لبرنامج ربط العمليات التجارية إلى مستوى سجل Information وعرضها بتنسيق PowerShell الافتراضي.

هام

Write-Verbose لا يكفي استخدام أوامر cmdlets أو Write-Debug لمشاهدة تسجيل مستوى الإسهاب والتصحيح. يجب أيضاً تكوين حد مستوى السجل الذي يعلن مستوى السجلات التي تهتم بها فعلياً. لمعرفة المزيد، راجع تكوين مستوى سجل تطبيق الوظائف.

تكوين مستوى سجل تطبيق الوظائف

تتيح لك خدمة Azure Functions تحديد مستوى الحد لتسهيل التحكم في طريقة كتابة Functions في السجلات. لتعيين الحد لجميع التتبعات المكتوبة في وحدة التحكم، استخدم خاصية logging.logLevel.default في الملف host.json. ينطبق هذا الإعداد على كافة الوظائف في تطبيق الوظائف.

يعين المثال التالي الحد لتمكين التسجيل المطوّل لجميع الوظائف، لكنه يعين الحد لتمكين تسجيل تتبع الأخطاء لوظيفة تسمى MyFunction:

{
    "logging": {
        "logLevel": {
            "Function.MyFunction": "Debug",
            "default": "Trace"
        }
    }
}

لمزيد من المعلومات ، راجع مرجع host.json.

عرض السجلات

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

إذا كنت تشغِّل تطبيق الوظائف محلياً للتطوير، يتم تعيين السجلات افتراضياً إلى نظام الملفات. لعرض السجلات في وحدة التحكم، عيِّن متغير بيئة AZURE_FUNCTIONS_ENVIRONMENT إلى Development قبل تشغيل تطبيق الوظائف.

أنواع المشغِّلات وعمليات ربط البيانات

هناك العديد من المشغلات والروابط المتاحة لك لاستخدامها مع تطبيق الوظائف. للحصول على القائمة الكاملة للمشغلات والروابط، راجع الارتباطات المدعومة.

يتم تمثيل جميع المشغِّلات وعمليات ربط البيانات في التعليمات البرمجية كأنواع بيانات حقيقية قليلة:

  • جدول تجزئة
  • سلسلة
  • بايت[]
  • العدد الصحيح
  • مزدوج
  • HttpRequestContext
  • HttpResponseContext

الأنواع الخمسة الأولى في هذه القائمة هي أنواع ‎.NET القياسية. يتم استخدام الأخيرين فقط بواسطة مشغِّل HttpTrigger.

يجب أن تكون كل معلمة ربط بيانات في الوظائف أحد هذه الأنواع.

مشغلات وارتباطات HTTP

تستخدم مشغلات HTTP وwebhook وارتباطات إخراج HTTP كائنات الطلب والاستجابة لتمثيل مراسلة HTTP.

كائن الطلب

كائن الطلب الذي يتم تمريره إلى البرنامج النصي من النوع HttpRequestContext، والذي يحتوي على الخصائص التالية:

الخاصية الوصف النوع
Body كائن يحتوي على نص الطلب. يتم تسلسل Body إلى أفضل نوع استناداً إلى البيانات. على سبيل المثال، إذا كانت البيانات هي JSON، يتم تمريرها كجدول تجزئة. إذا كانت البيانات سلسلة، يتم تمريرها كسلسلة. كائن
Headers قاموس يحتوي على عناوين الطلبات. القاموس <سلسلة، سلسلة>*
Method طريقة HTTP للطلب. سلسلة
Params كائن يحتوي على معلمات توجيه الطلب. القاموس <سلسلة، سلسلة>*
Query كائن يحتوي على معلمات الاستعلام. القاموس <سلسلة، سلسلة>*
Url عنوان URL للطلب. سلسلة

* جميع مفاتيح Dictionary<string,string> حساسة لحالة الأحرف.

كائن الاستجابة

كائن الرد الذي يجب إرساله مرة أخرى هو من النوع HttpResponseContext، الذي يحتوي على الخصائص التالية:

الخاصية الوصف النوع
Body كائن يحتوي على نص الاستجابة. كائن
ContentType اختصار لتعيين نوع المحتوى للرد. سلسلة
Headers كائن يحتوي على عناوين الاستجابة. القاموس أو جدول التجزئة
StatusCode التعليمات البرمجية لحالة HTTP للاستجابة. سلسلة أو كثافة العمليات

الوصول إلى الطلب والاستجابة

عند استخدام مشغِّلات HTTP، يمكنك الوصول إلى طلب HTTP بنفس الطريقة مع أي ربط بيانات مدخلات آخر. إنه في كتلة param.

استخدم كائنا HttpResponseContext لإرجاع استجابة، كما هو موضح في المثال التالي:

function.json

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "anonymous"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    }
  ]
}

run.ps1

param($req, $TriggerMetadata)

$name = $req.Query.Name

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "Hello $name!"
})

ستكون نتيجة استدعاء هذه الوظيفة:

irm http://localhost:5001?Name=Functions
Hello Functions!

تحويل الأنواع للمشغِّلات وعمليات ربط البيانات

بالنسبة لعمليات ربط بيانات معينة مثل ربط بيانات كائنات ثنائية كبيرة الحجم، يمكنك تحديد نوع المعلمة.

على سبيل المثال، للحصول على بيانات من مخزن الكائنات الثنائية كبيرة الحجم المتوفر كسلسلة، أضف تحويل النوع التالي إلى كتلة param الخاصة بي:

param([string] $myBlob)

ملف تعريف PowerShell

في PowerShell، هناك مفهوم ملف تعريف PowerShell. إذا لم تكن على دراية بملفات تعريف PowerShell، فاطلع على حول ملفات التعريف.

في وظائف PowerShell، يتم تنفيذ البرنامج النصي لملف التعريف مرة واحدة لكل مثيل عامل لـ PowerShell في التطبيق عند توزيعه لأول مرة وبعد أن يكون خاملاً (التشغيل العادي). عند تمكين التزامن عن طريق تعيين قيمة PSWorkerInProcConcurrencyUpperBound، يتم تشغيل البرنامج النصي لملف التعريف لكل مساحة تشغيل تم إنشاؤها.

عند إنشاء تطبيق وظائف باستخدام الأدوات، مثل Visual Studio Code وAzure Functions Core Tools، يتم إنشاء profile.ps1 افتراضي لك. يتم الاحتفاظ بملف التعريف الافتراضي على مستودع Core Tools GitHub ويحتوي على:

  • مصادقة MSI التلقائية لـ Azure.
  • القدرة على تشغيل الأسماء المستعارة لـ Azure PowerShell AzureRM PowerShell إذا أردت ذلك.

إصدارات PowerShell

يعرض الجدول التالي إصدارات PowerShell المتوفرة لكل إصدار رئيسي من وقت تشغيل Functions، وإصدار ‎.NET المطلوب:

إصدار الدوال إصدار PowerShell إصدار ‎.NET
4.x PowerShell 7.4 .NET 8
4.x PowerShell 7.2 (انتهاء الدعم) .NET 6

يمكنك عرض الإصدار الحالي عن طريق طباعة $PSVersionTable من أي وظيفة.

لمعرفة المزيد حول نهج دعم وقت تشغيل Azure Functions، راجع هذه المقالة

إشعار

ينتهي دعم PowerShell 7.2 في Azure Functions في 8 نوفمبر 2024. قد تضطر إلى حل بعض التغييرات العاجلة عند ترقية وظائف PowerShell 7.2 لتشغيلها على PowerShell 7.4. اتبع دليل الترحيل هذا للترقية إلى PowerShell 7.4.

التشغيل المحلي على إصدار معين

عند تشغيل وظائف PowerShell محليا، تحتاج إلى إضافة الإعداد "FUNCTIONS_WORKER_RUNTIME_VERSION" : "7.4" إلى Values الصفيف في ملف local.setting.json في جذر المشروع. عند التشغيل محليا على PowerShell 7.4، يبدو ملف local.settings.json الخاص بك مثل المثال التالي:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "FUNCTIONS_WORKER_RUNTIME": "powershell",
    "FUNCTIONS_WORKER_RUNTIME_VERSION" : "7.4"
  }
}

إشعار

في وظائف PowerShell، تشير القيمة "~7" FUNCTIONS_WORKER_RUNTIME_VERSION إلى "7.0.x". لا نقوم تلقائيا بترقية تطبيقات PowerShell Function التي تحتوي على "~7" إلى "7.4". من الآن فصاعدا، بالنسبة لتطبيقات وظائف PowerShell، نطلب من التطبيقات تحديد الإصدار الرئيسي والثانوي الذي تريد استهدافه. من الضروري ذكر "7.4" إذا كنت تريد استهداف "7.4.x"

تغيير إصدار PowerShell

خذ هذه الاعتبارات في الاعتبار قبل ترحيل تطبيق وظائف PowerShell إلى PowerShell 7.4:

  • نظرا لأن الترحيل قد يؤدي إلى تغييرات فاصلة في تطبيقك، راجع دليل الترحيل هذا قبل ترقية تطبيقك إلى PowerShell 7.4.

  • تأكد من تشغيل تطبيق الوظائف على أحدث إصدار من وقت تشغيل الوظائف في Azure، وهو الإصدار 4.x. لمزيد من المعلومات، راجع عرض إصدار وقت التشغيل الحالي.

استخدم الخطوات التالية لتغيير إصدار PowerShell الذي يستخدمه تطبيق الوظائف. يمكنك تنفيذ هذه العملية إما في مدخل Microsoft Azure أو باستخدام PowerShell.

  1. في مدخل Microsoft Azure، استعرض للوصول إلى تطبيق الوظائف.

  2. ضمن Settings، اختر Configuration. في علامة التبويب General settings، حدد موقع إصدار PowerShell.

    لقطة شاشة توضح كيفية تحديد إصدار PowerShell.

  3. اختر إصدار Core PowerShell المطلوب، وحدد Save. عندما تتلقى تحذيراً بشأن إعادة التشغيل المعلقة، اختر Continue. يتم إعادة تشغيل تطبيق الوظائف على إصدار PowerShell المختار.

إشعار

يتوفر دعم Azure Functions ل PowerShell 7.4 بشكل عام (GA). قد ترى PowerShell 7.4 لا يزال يشار إليه كمعاينة في مدخل Microsoft Azure، ولكن سيتم تحديث هذه القيمة قريبا لتعكس حالة GA.

يتم إعادة تشغيل تطبيق الوظائف بعد إجراء التغيير على التكوين.

إدارة التبعية

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

اختيار نهج إدارة الوحدة النمطية المناسب

لماذا تستخدم ميزة التبعيات المدارة؟

  • التثبيت الأولي المبسط: يعالج تلقائيا تثبيت الوحدة النمطية استنادا إلى الملف الخاص بك requirements.psd1 .
  • الترقيات التلقائية: يتم تحديث الوحدات النمطية تلقائيا، بما في ذلك إصلاحات الأمان، دون الحاجة إلى تدخل يدوي.

لماذا تضمين الوحدات النمطية في محتوى التطبيق؟

  • لا توجد تبعية على معرض PowerShell: يتم تجميع الوحدات النمطية مع تطبيقك، مما يلغي التبعيات الخارجية.
  • مزيد من التحكم: يتجنب مخاطر التراجعات الناجمة عن الترقيات التلقائية، مما يمنحك التحكم الكامل في إصدارات الوحدة النمطية المستخدمة.
  • التوافق: يعمل على استهلاك Flex ويوصى به لوحدات Linux SKU الأخرى.

ميزة التبعيات المدارة

تسمح ميزة التبعيات المدارة ل Azure Functions بتنزيل وحدات PowerShell النمطية المحددة في requirements.psd1 الملف وإدارتها تلقائيا. يتم تمكين هذه الميزة بشكل افتراضي في تطبيقات وظائف PowerShell الجديدة.

تكوين requirements.psd1

لاستخدام التبعيات المدارة في Azure Functions مع PowerShell، تحتاج إلى تكوين requirements.psd1 ملف. يحدد هذا الملف الوحدات النمطية التي تتطلبها دالتك، وتنزل Azure Functions هذه الوحدات النمطية وتحديثها تلقائيا لضمان بقاء بيئتك محدثة.

فيما يلي كيفية إعداد الملف وتكوينه requirements.psd1 :

  1. requirements.psd1 إنشاء ملف في الدليل الجذر لدالة Azure إذا لم يكن أحدها موجودا بالفعل.
  2. حدد الوحدات النمطية وإصداراتها في بنية بيانات PowerShell.

مثال requirements.psd1 على الملف:

@{
    'Az' = '9.*'  # Specifies the Az module and will use the latest version with major version 9
}

تضمين الوحدات النمطية في محتوى التطبيق

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

لتضمين وحدات نمطية مخصصة:

  1. Modules إنشاء مجلد في جذر تطبيق الوظائف.

    mkdir ./Modules

  2. انسخ الوحدات النمطية Modules إلى المجلد باستخدام إحدى الطرق التالية:

    • إذا كانت الوحدات النمطية متاحة محليا بالفعل:

      Copy-Item -Path /mymodules/mycustommodule -Destination ./Modules -Recurse

    • استخدام Save-Module لاسترداد من معرض PowerShell:

      Save-Module -Name MyCustomModule -Path ./Modules

    • استخدام Save-PSResource من الوحدة النمطيةPSResourceGet:

      Save-PSResource -Name MyCustomModule -Path ./Modules

يجب أن يحتوي تطبيق الوظائف على البنية التالية:

PSFunctionApp
 | - MyFunction
 | | - run.ps1
 | | - function.json
 | - Modules
 | | - MyCustomModule
 | | - MyOtherCustomModule
 | | - MySpecialModule.psm1
 | - local.settings.json
 | - host.json
 | - requirements.psd1

عند بدء تشغيل تطبيق الوظائف، يضيف عامل لغة PowerShell مجلد Modules هذا إلى $env:PSModulePath بحيث يمكنك الاعتماد على التحميل التلقائي للوحدات النمطية تماماً كما تفعل في برنامج PowerShell النصي العادي.

إشعار

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

**/bin/**
!Modules/**

استكشاف أخطاء التبعيات المدارة وإصلاحها

تمكين التبعيات المدارة

لكي تعمل التبعيات المدارة، يجب تمكين الميزة في host.json:

{
  "managedDependency": {
          "enabled": true
       }
}

استهداف إصدارات محددة

عند استهداف إصدارات وحدة نمطية معينة، من المهم اتباع كلتا الخطوتين التاليتين لضمان تحميل إصدار الوحدة النمطية الصحيح:

  1. حدد إصدار الوحدة النمطية في requirements.psd1:

    @{
  'Az.Accounts' = '1.9.5'
}

  2. إضافة عبارة استيراد إلى profile.ps1:

    Import-Module Az.Accounts -RequiredVersion '1.9.5'

يضمن اتباع هذه الخطوات تحميل الإصدار المحدد عند بدء تشغيل الدالة.

تكوين إعدادات محددة للفاصل الزمني للتبعية المدارة

يمكنك تكوين كيفية تنزيل التبعيات المدارة وتثبيتها باستخدام إعدادات التطبيق التالية:

الإعدادات القيمة الافتراضية الوصف
MDMaxBackgroundUpgradePeriod 7.00:00:00 (سبعة أيام) التحكم في فترة تحديث الخلفية لتطبيقات وظائف PowerShell.
MDNewSnapshotCheckPeriod 01:00:00 (ساعة واحدة) تحديد عدد المرات التي يتحقق فيها عامل PowerShell من وجود تحديثات.
MDMinBackgroundUpgradePeriod 1.00:00:00 (يوم واحد) الحد الأدنى من الوقت بين عمليات التحقق من الترقية.

اعتبارات إدارة التبعيات

  • الوصول إلى الإنترنت: تتطلب التبعيات المدارة الوصول إلى https://www.powershellgallery.com لتنزيل الوحدات النمطية. تأكد من أن بيئتك تسمح بهذا الوصول، بما في ذلك تعديل قواعد جدار الحماية/الشبكة الظاهرية حسب الحاجة. يتم وصف نقاط النهاية المطلوبة في Cmdlets استكشاف الأخطاء وإصلاحها. يمكن إضافة نقاط النهاية هذه إلى قائمة السماح، كما هو مطلوب.
  • قبول الترخيص: لا تدعم التبعيات المدارة الوحدات النمطية التي تتطلب قبول الترخيص.
  • خطة استهلاك Flex: ميزة التبعيات المدارة غير مدعومة في خطة استهلاك Flex. استخدم الوحدات النمطية المخصصة بدلا من ذلك.
  • مواقع الوحدة النمطية: على الكمبيوتر المحلي، يتم عادة تثبيت الوحدات النمطية في أحد المجلدات المتوفرة عالميا في .$env:PSModulePath عند التشغيل في Azure، $env:PSModulePath يختلف تطبيق وظيفة PowerShell عن $env:PSModulePath في برنامج PowerShell النصي العادي ويحتوي على كل من المجلد الذي Modules تم تحميله مع محتويات التطبيق وموقع منفصل تديره التبعيات المدارة.

متغيرات البيئة

في Functions، يتم عرض إعدادات التطبيق، مثل سلاسل اتصال الخدمة، كمتغيرات بيئة أثناء التنفيذ. يمكنك الوصول إلى هذه الإعدادات باستخدام $env:NAME_OF_ENV_VAR، كما هو موضح في المثال التالي:

param($myTimer)

Write-Host "PowerShell timer trigger function ran! $(Get-Date)"
Write-Host $env:AzureWebJobsStorage
Write-Host $env:WEBSITE_SITE_NAME

توجد عدة طرق يمكنك من خلالها إضافة إعدادات تطبيق الوظائف وتحديثها وحذفها:

تتطلب التغييرات في إعدادات تطبيق الوظائف إعادة تشغيل تطبيق الوظائف.

عند التشغيل محلياً، تتم قراءة إعدادات التطبيق من ملف مشروع local.settings.json.

التزامن

بشكل افتراضي، يمكن لوقت تشغيل Functions PowerShell معالجة استدعاء واحد فقط لوظيفة في كل مرة. ومع ذلك، قد لا يكون هذا مستوى التزامن هذا كافياً في الحالات التالية:

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

هناك بعض نماذج التزامن التي يمكنك استكشافها اعتماداً على نوع حمل العمل:

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

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

يمكنك تعيين متغيرات البيئة هذه في إعدادات التطبيق لتطبيق الوظائف.

اعتمادا على حالة الاستخدام الخاصة بك، قد تحسن Durable Functions قابلية التوسع بشكل كبير. لمعرفة المزيد، راجع أنماط تطبيق Durable Functions.

إشعار

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

اعتبارات استخدام التزامن

PowerShell هي لغة برمجة نصية ذات مؤشر ترابط واحد بشكل افتراضي. ومع ذلك، يمكن إضافة التزامن باستخدام مساحات تشغيل PowerShell متعددة في العملية نفسها. عدد مساحات التشغيل التي تم إنشاؤها، وبالتالي عدد سلاسل الرسائل المتزامنة لكل عامل، مقيد بإعداد التطبيق PSWorkerInProcConcurrencyUpperBound. بشكل افتراضي، يتم تعيين عدد مساحات التشغيل إلى 1000 في الإصدار ‎4.x من وقت تشغيل الوظائف. في الإصدار ‎3.x والإصدارات الأقدم، يتم تعيين الحد الأقصى لعدد مساحات التشغيل إلى 1. يتأثر معدل نقل تطبيق الوظائف بمقدار وحدة المعالجة المركزية والذاكرة المتوفرة في الخطة المحددة.

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

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

تكوين scriptFile للوظيفة

بشكل افتراضي، يتم تنفيذ وظيفة PowerShell من run.ps1، وهو ملف يشارك الدليل الأصل نفسه الذي يشاركه الملف المطابق له function.json.

يمكن استخدام خاصية scriptFile في function.json للحصول على بنية مجلد تبدو مثل لمثال التالي:

FunctionApp
 | - host.json
 | - myFunction
 | | - function.json
 | - lib
 | | - PSFunction.ps1

في هذه الحالة، يشتمل function.json لـ myFunction على خاصية scriptFile التي تشير إلى الملف بالوظيفة المصدَّرة لتشغيلها.

{
  "scriptFile": "../lib/PSFunction.ps1",
  "bindings": [
    // ...
  ]
}

استخدام وحدات PowerShell النمطية عن طريق تكوين نقطة إدخال

يتم عرض وظائف PowerShell في هذه المقالة مع ملف البرنامج النصي الافتراضي run.ps1 الذي تم إنشاؤه بواسطة القوالب. ومع ذلك، يمكنك أيضاً تضمين الوظائف في وحدات PowerShell النمطية. يمكنك الإشارة إلى التعليمات البرمجية للوظيفة المحددة في الوحدة النمطية باستخدام حقلي scriptFile وentryPoint في ملف تكوين function.json.

في هذه الحالة، يكون entryPoint هو اسم وظيفة أو أمر cmdlet في وحدة PowerShell النمطية المشار إليها في scriptFile.

خذ بعين الاعتبار بنية المجلد التالية:

FunctionApp
 | - host.json
 | - myFunction
 | | - function.json
 | - lib
 | | - PSFunction.psm1

حيث PSFunction.psm1 يحتوي على:

function Invoke-PSTestFunc {
    param($InputBinding, $TriggerMetadata)

    Push-OutputBinding -Name OutputBinding -Value "output"
}

Export-ModuleMember -Function "Invoke-PSTestFunc"

في هذا المثال، يتضمن تكوين myFunction خاصية scriptFile التي تشير إلى PSFunction.psm1، وهي وحدة PowerShell نمطية في مجلد آخر. تشير خاصية entryPoint إلى وظيفة Invoke-PSTestFunc، وهي نقطة الإدخال في الوحدة النمطية.

{
  "scriptFile": "../lib/PSFunction.psm1",
  "entryPoint": "Invoke-PSTestFunc",
  "bindings": [
    // ...
  ]
}

مع هذا التكوين، يتم تنفيذ Invoke-PSTestFunc تماماً مثل run.ps1.

اعتبارات وظائف PowerShell

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

تشغيل بارد

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

تجنب استخدام وحدة التثبيت

يمكن أن يؤدي التشغيل Install-Module في البرنامج النصي للدالة على كل استدعاء إلى حدوث مشكلات في الأداء. بدلا من ذلك، استخدم Save-Module أو Save-PSResource قبل نشر تطبيق الوظائف لتجميع الوحدات النمطية الضرورية.

لمزيد من المعلومات، راجع إدارة التبعية.

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

لمزيد من المعلومات، راجع الموارد التالية: