مشاركة عبر

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

  • مقالة

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

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

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

تفترض هذه المقالة أنك قد قرأت مرجع مطور Azure Functions. يجب أن تكون قد أكملت أيضاً تشغيل 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. عند التطوير محليًا، يجب عليك تسجيل ملحقات الربط. عند تطوير الوظائف في Azure portal، يتم هذا التسجيل لك.

في 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) DateTime
MethodName اسم الوظيفة التي تم تشغيلها سلسلة
RandGuid معرّف فريد لتنفيذ الوظيفة سلسلة

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

Bindings

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

PS >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
Trace Write-Progress
Write-Verbose

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

هام

لا يكون استخدام أمر cmdlet‏ Write-Verbose أو 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 قبل تشغيل تطبيق الوظائف.

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

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

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

  • جدول تجزئة
  • سلسلة
  • byte[]
  • العدد الصحيح
  • مزدوج
  • 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!"
})

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

PS > 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.2 .NET 6

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

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

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

انتهى دعم PowerShell 7.0 في Azure Functions في 3 ديسمبر 2022. لاستخدام PowerShell 7.2 عند التشغيل محليا، تحتاج إلى إضافة الإعداد "FUNCTIONS_WORKER_RUNTIME_VERSION" : "7.2" إلى Values الصفيف في ملف local.setting.json في جذر المشروع. عند التشغيل محليا على PowerShell 7.2، يبدو ملف local.settings.json الخاص بك مثل المثال التالي:

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

إشعار

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

تغيير إصدار PowerShell

انتهى دعم PowerShell 7.0 في Azure Functions في 3 ديسمبر 2022. لترقية Function App إلى PowerShell 7.2، تأكد من تعيين قيمة FUNCTIONS_EXTENSION_VERSION إلى ~4. لمعرفة كيفية إجراء ذلك، راجع عرض إصدار وقت التشغيل الحالي وتحديثه.

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

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

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

    صورة

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

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

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

تتيح لك Functions الاستفادة من معرض PowerShell لإدارة التبعيات. مع تمكين إدارة التبعيات، يتم استخدام ملف requirements.psd1 لتنزيل الوحدات النمطية المطلوبة تلقائياً. يمكنك تمكين هذا السلوك عن طريق تعيين خاصية managedDependency إلى true في جذر ملف host.json، كما في المثال التالي:

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

عند إنشاء مشروع وظائف PowerShell جديد، يتم تمكين إدارة التبعيات بشكل افتراضي، مع تضمين Azوحدة Azure النمطية. الحد الأقصى لعدد الوحدات النمطية المدعومة حالياً هو 10. بناء الجملة المدعوم هو MajorNumber.* أو إصدار الوحدة النمطية الدقيق كما هو موضح في مثال requirements.psd1 التالي:

@{
	Az = '1.*'
	SqlServer = '21.1.18147'
}

عند تحديث ملف requirements.psd1، يتم تثبيت الوحدات النمطية المحدثة بعد إعادة التشغيل.

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

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

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

في هذه الحالة، تحتاج أيضاً إلى إضافة عبارة استيراد إلى أعلى ملف profile.ps1، والذي يبدو مثل المثال التالي:

Import-Module Az.Accounts -RequiredVersion '1.9.5'

وبهذه الطريقة، يتم تحميل الإصدار الأقدم من وحدة Az.Account النمطية أولاً عند بدء تشغيل الوظيفة.

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

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

  • تتطلب التبعيات المدارة الوصول https://www.powershellgallery.com إلى لتنزيل الوحدات النمطية. عند التشغيل محلياً، تأكد من أن وقت التشغيل يمكنه الوصول إلى عنوان URL هذا من خلال إضافة أي قواعد جدار حماية مطلوبة.

  • لا تدعم التبعيات المدارة حالياً الوحدات النمطية التي تتطلب من المستخدم قبول ترخيص، إما بقبول الترخيص بشكل تفاعلي، وإما بتوفير مفتاح التبديل -AcceptLicense عند استدعاء Install-Module.

  • لا يتم دعم التبعيات المدارة عند استضافة تطبيق الوظائف في خطة استهلاك Flex. يجب عليك بدلا من ذلك تحديد الوحدات النمطية المخصصة الخاصة بك.

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

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

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

بصفة أساسية، تبدأ ترقية التطبيق خلال MDMaxBackgroundUpgradePeriod، وتكتمل عملية الترقية خلال MDNewSnapshotCheckPeriod تقريباً.

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

تختلف الاستفادة من الوحدات النمطية المخصصة في Azure Functions عن كيفية الاستفادة منها عادةً لـ PowerShell.

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

في Functions، يحتوي PSModulePath على مسارين:

  • مجلد Modules موجود في جذر تطبيق الوظائف.
  • مسار إلى مجلد Modules الذي يتم التحكم به بواسطة عامل لغة PowerShell.

مجلد الوحدات النمطية على مستوى تطبيق الوظائف

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

إشعار

يتم تنزيل الوحدات النمطية المحددة في ملف requirements.psd1 تلقائياً وتضمينها في المسار بحيث لا تحتاج إلى تضمينها في مجلد الوحدات النمطية. يتم تخزين هذه الوحدات محلياً في مجلد $env:LOCALAPPDATA/AzureFunctions وفي مجلد /data/ManagedDependencies عند تشغيلها في السحابة.

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

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

مع مجلد Modules، يجب أن يكون لتطبيق الوظائف بنية المجلد التالية:

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

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

مجلد الوحدات النمطية على مستوى عامل اللغة

يتم استخدام عدة وحدات نمطية عادة بواسطة عامل لغة PowerShell. يتم تحديد هذه الوحدات النمطية في الموضع الأخير من PSModulePath.

تكون القائمة الحالية من الوحدات النمطية كما يلي:

  • Microsoft.PowerShell.Archive: وحدة نمطية تُستخدم لاستخدام الأرشيفات، مثل .zip و.nupkg وغيرهما.
  • ThreadJob: عملية تطبيق تستند إلى مؤشر ترابط لواجهات برمجة تطبيقات مهمة PowerShell.

بشكل افتراضي، تستخدم Functions أحدث إصدار من هذه الوحدات النمطية. لاستخدام إصدار وحدة نمطية محدد، ضع هذا الإصدار المحدد في مجلد 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. يسمح هذا بمعالجة استدعاءات الوظائف في عمليات متعددة ضمن المثيل نفسه، والذي يقدم حمل وحدة معالجة مركزية (CPU) وذاكرة معيناً. بشكل عام، لن تعاني الوظائف المرتبطة بالإدخال/الإخراج من هذا الحمل. بالنسبة للوظائف المرتبطة بوحدة المعالجة المركزية، قد يكون التأثير كبيراً.

  • زيادة قيمة إعداد تطبيق 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)

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

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

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