Bagikan melalui

Panduan pengembang Azure Functions PowerShell

  • Artikel

Artikel ini menyediakan detail tentang cara Anda menulis Azure Functions menggunakan PowerShell.

Fungsi PowerShell Azure (fungsi) direpresentasikan sebagai skrip PowerShell yang dijalankan saat dipicu. Setiap skrip fungsi memiliki file function.json terkait yang menentukan bagaimana fungsi berperilaku, seperti bagaimana hal itu dipicu dan parameter input dan outputnya. Untuk mempelajari lebih lanjut, lihat artikel Pemicu dan pengikatan.

Seperti jenis fungsi lainnya, fungsi skrip PowerShell mengambil parameter yang cocok dengan nama semua pengikatan input yang ditentukan dalam file function.json. Parameter TriggerMetadata juga diteruskan yang berisi informasi tambahan tentang pemicu yang memulai fungsi.

Artikel ini mengasumsikan bahwa Anda sudah membaca panduan pengembang Azure Functions. Anda juga harus menyelesaikan mulai cepat Functions untuk PowerShell guna membuat fungsi PowerShell pertama Anda.

Struktur folder

Struktur folder yang diperlukan untuk proyek PowerShell terlihat seperti berikut ini. Default ini bisa diubah. Untuk informasi selengkapnya, lihat bagian scriptFile di bawah ini.

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

Di akar proyek, terdapat file host.json bersama yang dapat digunakan untuk mengonfigurasi aplikasi fungsi. Setiap fungsi memiliki folder dengan file kode sendiri (.ps1) dan file konfigurasi pengikatan (function.json). Nama direktori induk file function.json selalu merupakan nama fungsi Anda.

Pengikatan tertentu memerlukan keberadaan file extensions.csproj. Ekstensi pengikatan, yang diperlukan dalam versi 2.x dan versi yang lebih baru dari runtime Functions, didefinisikan dalam file extensions.csproj, dengan file pustaka aktual di folder bin. Saat mengembangkan secara lokal, Anda harus mendaftarkan ekstensi pengikatan. Saat mengembangkan fungsi di portal Microsoft Azure, pendaftaran ini dilakukan untuk Anda.

Di PowerShell Function Apps, Anda mungkin secara opsional memiliki profile.ps1 yang berjalan saat aplikasi fungsi mulai berjalan (jika tidak, ketahui sebagai cold start). Untuk informasi selengkapnya, lihat Profil PowerShell.

Menentukan skrip PowerShell sebagai fungsi

Secara default, runtime Functions mencari fungsi Anda di run.ps1 , tempat run.ps1 berbagi direktori induk yang sama dengan function.json yang sesuai.

Skrip Anda dilewatkan sejumlah argumen saat eksekusi. Untuk menangani parameter ini, tambahkan blok param ke bagian atas skrip Anda seperti dalam contoh berikut:

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

Parameter TriggerMetadata

Parameter TriggerMetadata ini digunakan untuk memberikan informasi tambahan tentang pemicunya. Metadata tambahan bervariasi dari pengikatan ke pengikatan tetapi semuanya berisi properti sys yang berisi data berikut:

$TriggerMetadata.sys
Properti Deskripsi Jenis
UtcNow Ketika, di UTC, fungsi dipicu DateTime
MethodName Nama Fungsi yang dipicu string
RandGuid pengidentifikasi unik untuk pelaksanaan fungsi ini string

Setiap jenis pemicu memiliki sekumpulan metadata yang berbeda. Misalnya, $TriggerMetadata untuk QueueTrigger berisi InsertionTime, Id, DequeueCount, antara lain. Untuk informasi lebih lanjut tentang metadata pemicu antrean, buka dokumentasi resmi untuk pemicu antrean. Periksa dokumentasi tentang pemicu yang sedang Anda kerjakan untuk melihat apa yang ada di dalam metadata pemicu.

Pengikatan

Di PowerShell, pengikatan dikonfigurasi dan ditentukan di function.json fungsi. Fungsi berinteraksi dengan pengikatan dalam berbagai cara.

Membaca pemicu dan memasukkan data

Pemicu dan pengikatan input dibaca sebagai parameter yang diteruskan ke fungsi Anda. Pengikatan input memiliki direction yang diatur ke in di function.json. Properti name yang ditentukan di function.json adalah nama parameter di blok param. Karena PowerShell menggunakan parameter bernama untuk pengikatan, urutan parameter tidak menjadi masalah. Namun, ini adalah praktik terbaik untuk mengikuti urutan pengikatan yang ditentukan di function.json.

param($MyFirstInputBinding, $MySecondInputBinding)

Menulis data output

Di Functions, pengikatan output memiliki direction yang diatur ke out di function.json. Anda dapat menulis ke pengikatan output dengan menggunakan cmdlet Push-OutputBinding, yang tersedia untuk runtime Functions. Dalam semua kasus, properti name dari pengikatan seperti yang ditentukan di function.json sesuai dengan parameter Name dari cmdlet Push-OutputBinding.

Berikut ini memperlihatkan cara memanggil Push-OutputBinding di skrip fungsi Anda:

param($MyFirstInputBinding, $MySecondInputBinding)

Push-OutputBinding -Name myQueue -Value $myValue

Anda juga dapat meneruskan nilai untuk pengikatan tertentu melalui alur.

param($MyFirstInputBinding, $MySecondInputBinding)

Produce-MyOutputValue | Push-OutputBinding -Name myQueue

Push-OutputBinding berperilaku berbeda berdasarkan nilai yang ditentukan untuk -Name:

  • Ketika nama yang ditentukan tidak dapat diselesaikan menjadi pengikatan output yang valid, maka kesalahan akan terjadi.

  • Saat pengikatan output menerima koleksi nilai, Anda dapat memanggil Push-OutputBinding berulang kali untuk mendorong beberapa nilai.

  • Ketika pengikatan output hanya menerima nilai database tunggal, panggilan Push-OutputBinding untuk kedua kalinya menimbulkan kesalahan.

Sintaks Push-OutputBinding

Berikut ini adalah parameter yang valid untuk memanggil Push-OutputBinding:

Nama Tipe Position Deskripsi
-Name String 1 Nama pengikatan output yang ingin Anda atur.
-Value Objek 2 Nilai pengikatan output yang ingin Anda atur, yang diterima dari alur ByValue.
-Clobber SwitchParameter Dinamai (Opsional) Jika ditentukan, memaksa nilai yang akan diatur untuk pengikatan output tertentu.

Parameter umum berikut juga didukung:

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

Untuk informasi selengkapnya, lihat Tentang CommonParameters.

Contoh Push-OutputBinding: Respons HTTP

Pemicu HTTP mengembalikan respons menggunakan pengikatan output bernama response. Dalam contoh berikut, pengikatan output response memiliki nilai "output #1":

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

Karena output adalah ke HTTP, yang hanya menerima nilai database tunggal, kesalahan muncul ketika Push-OutputBinding dipanggil untuk kedua kalinya.

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

Untuk output yang hanya menerima nilai database tunggal, Anda dapat menggunakan parameter -Clobber untuk mengambil alih nilai lama daripada mencoba menambahkan ke koleksi. Contoh berikut mengasumsikan bahwa Anda telah menambahkan nilai. Dengan menggunakan -Clobber, respons dari contoh berikut mengambil alih nilai yang ada untuk mengembalikan nilai "output #3":

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

Contoh Push-OutputBinding: Pengikatan output antrean

Push-OutputBinding digunakan untuk mengirim data ke pengikatan output, seperti pengikatan output penyimpanan Antrean Azure. Dalam contoh berikut, pesan yang ditulis ke antrean memiliki nilai "output #1":

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

Pengikatan output untuk antrean Storage menerima beberapa nilai output. Dalam hal ini, memanggil contoh berikut setelah penulisan pertama ke daftar antrean dengan dua item: "output #1" dan "output #2".

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

Contoh berikut, ketika dipanggil setelah dua panggilan sebelumnya, menambahkan dua nilai lagi ke koleksi output:

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

Ketika ditulis ke antrean, pesan berisi keempat nilai ini: "output #1", "output #2", "output #3", dan "output #4".

cmdlet Get-OutputBinding

Anda dapat menggunakan cmdlet Get-OutputBinding untuk mengambil nilai yang saat ini ditetapkan untuk pengikatan output Anda. Cmdlet ini mengambil hashtable yang berisi nama-nama pengikatan output dengan nilai mereka masing-masing.

Berikut ini adalah contoh penggunaan Get-OutputBinding untuk mengembalikan nilai pengikatan saat ini:

Get-OutputBinding

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

Get-OutputBinding juga berisi parameter yang disebut -Name, yang dapat digunakan untuk memfilter pengikatan yang dikembalikan, seperti dalam contoh berikut:

Get-OutputBinding -Name MyQ*

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

Wildcard (*) didukung di Get-OutputBinding.

Pencatatan

Pengelogan di fungsi PowerShell berfungsi seperti pencatatan PowerShell biasa. Anda dapat menggunakan cmdlet pengelogan untuk menulis ke setiap aliran output. Setiap cmdlet dipetakan ke tingkat log yang digunakan oleh Functions.

Tingkat pengelogan Functions Cmdlet pengelogan
Kesalahan Write-Error
Peringatan Write-Warning
Informasi Write-Information
Write-Host
Write-Output
Menulis ke tingkat log Information.
Debug Write-Debug
Trace Write-Progress
Write-Verbose

Selain cmdlet ini, apa pun yang ditulis ke alur diarahkan ke tingkat log Information dan ditampilkan dengan pemformatan PowerShell default.

Penting

Menggunakan cmdlet Write-Verbose atau Write-Debug tidak cukup untuk melihat pengelogan tingkat verbose dan debug. Anda juga harus mengonfigurasi ambang tingkat log, yang menyatakan tingkat log yang benar-benar Anda pedulikan. Untuk mempelajari lebih lanjut, lihat Mengonfigurasi tingkat log aplikasi fungsi.

Mengonfigurasi tingkat log aplikasi fungsi

Azure Functions memungkinkan Anda menentukan tingkat ambang untuk memudahkan mengontrol cara Functions menulis ke log. Untuk mengatur ambang untuk semua jejak yang ditulis ke konsol, gunakan properti logging.logLevel.default di host.json file. Pengaturan ini berlaku untuk semua fungsi di aplikasi fungsi Anda.

Contoh berikut menetapkan ambang untuk mengaktifkan pengelogan verbose untuk semua fungsi, tetapi menetapkan ambang guna mengaktifkan pengelogan debug untuk fungsi bernama MyFunction:

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

Untuk informasi selengkapnya, lihat referensi host.json.

Menampilkan log

Jika Aplikasi Fungsi Anda berjalan di Azure, Anda dapat menggunakan Application Insights untuk memantaunya. Baca memantau Azure Functions untuk mempelajari selengkapnya tentang menampilkan dan mengajukan kueri log fungsi.

Jika Anda menjalankan Aplikasi Fungsi secara lokal untuk pengembangan, log default ke sistem file. Untuk melihat log di konsol, atur variabel lingkungan AZURE_FUNCTIONS_ENVIRONMENT ke Development sebelum memulai Aplikasi Fungsi.

Jenis pemicu dan pengikatan

Ada sejumlah pemicu dan pengikatan yang tersedia untuk Anda gunakan dengan aplikasi fungsi Anda. Daftar lengkap pemicu dan pengikatan dapat ditemukan di sini.

Semua pemicu dan pengikatan ditunjukkan dalam kode sebagai beberapa jenis data nyata:

  • Hashtable
  • string
  • byte[]
  • int
  • ganda
  • HttpRequestContext
  • HttpResponseContext

Lima jenis pertama dalam daftar ini adalah jenis .NET standar. Dua terakhir hanya digunakan oleh pemicu HttpTrigger.

Setiap parameter pengikatan dalam fungsi Anda harus salah satu dari jenis ini.

Pemicu dan pengikatan HTTP

Pemicu HTTP dan webhook dan pengikatan output HTTP menggunakan objek permintaan dan respons untuk mewakili olah pesan HTTP.

Objek permintaan

Objek permintaan yang diteruskan ke dalam skrip adalah jenis HttpRequestContext, yang memiliki properti berikut:

Properti Deskripsi Jenis
Body Objek yang memuat isi permintaan. Body diserialisasikan menjadi jenis terbaik berdasarkan data. Misalnya, jika data adalah JSON, data tersebut diteruskan sebagai hashtable. Jika data adalah untai (karakter), data akan diteruskan sebagai string. object
Headers Kamus yang berisi header permintaan. Kamus<string,string>*
Method Metode HTTP permintaan. string
Params Objek yang berisi parameter perutean permintaan. Kamus<string,string>*
Query Objek yang berisi parameter kueri. Kamus<string,string>*
Url URL permintaan. string

*Semua kunci Dictionary<string,string> tidak peka huruf besar/kecil.

Objek respons

Objek respons yang harus Anda kirim kembali adalah jenis HttpResponseContext, yang memiliki properti berikut:

Properti Deskripsi Jenis
Body Objek yang berisi isi respons. object
ContentType Tangan pendek untuk mengatur jenis konten untuk respons. string
Headers Objek yang berisi header respons. Kamus atau Hashtable
StatusCode Kode status HTTP respons. string atau int

Mengakses permintaan dan respons

Ketika Anda bekerja dengan pemicu HTTP, Anda dapat mengakses permintaan HTTP dengan cara yang sama seperti yang Anda lakukan dengan pengikatan input lainnya. Ada di blok param.

Gunakan objek HttpResponseContext untuk mengembalikan respons, seperti yang ditunjukkan berikut ini:

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!"
})

Hasil dari pemanggilan fungsi ini adalah:

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

Type-casting untuk pemicu dan pengikatan

Untuk pengikatan tertentu seperti pengikatan blob, Anda dapat menentukan jenis parameter.

Misalnya, agar data dari penyimpanan Blob disediakan sebagai untai (karakter), tambahkan jenis cast berikut ke blok param saya:

param([string] $myBlob)

Profil PowerShell

Di PowerShell, ada konsep profil PowerShell. Jika Anda tidak terbiasa dengan profil PowerShell, lihat Tentang profil.

Dalam PowerShell Functions, skrip profil dijalankan sekali per instans pekerja PowerShell di aplikasi saat pertama kali disebarkan dan setelah tidak digunakan (awal dingin. Ketika konkurensi diaktifkan dengan mengatur nilai PSWorkerInProcConcurrencyUpperBound, skrip profil dijalankan untuk setiap runspace yang dibuat.

Saat Anda membuat aplikasi fungsi menggunakan alat, seperti Visual Studio Code dan Azure Functions Core Tools, profile.ps1 default dibuat untuk Anda. Profil default dipertahankan di repositori Core Tools GitHub dan berisi:

  • Autentikasi MSI otomatis ke Azure.
  • Kemampuan untuk mengaktifkan Azure PowerShell AzureRM alias PowerShell jika Anda suka.

Versi PowerShell

Tabel berikut menunjukkan versi PowerShell yang tersedia untuk setiap versi utama runtime Functions, dan versi .NET yang diperlukan:

Versi Azure Functions Versi PowerShell Versi .NET
4.x PowerShell 7.4 .NET 8
4.x PowerShell 7.2 (akhir dukungan) .NET 6

Anda dapat melihat versi saat ini dengan mencetak $PSVersionTable dari fungsi apa pun.

Untuk mempelajari lebih lanjut tentang kebijakan dukungan waktu proses untuk Azure Functions, lihat artikel ini

Catatan

Dukungan untuk PowerShell 7.2 di Azure Functions berakhir pada 8 November 2024. Anda mungkin harus mengatasi beberapa perubahan yang melanggar saat memutakhirkan fungsi PowerShell 7.2 anda untuk dijalankan di PowerShell 7.4. Ikuti panduan migrasi ini untuk meningkatkan ke PowerShell 7.4.

Menjalankan lokal pada versi tertentu

Saat menjalankan fungsi PowerShell Anda secara lokal, Anda perlu menambahkan pengaturan "FUNCTIONS_WORKER_RUNTIME_VERSION" : "7.4" ke Values array dalam file local.setting.json di akar proyek. Saat berjalan secara lokal di PowerShell 7.4, file local.settings.json Anda terlihat seperti contoh berikut:

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

Catatan

Di PowerShell Functions, nilai "~7" untuk FUNCTIONS_WORKER_RUNTIME_VERSION mengacu pada "7.0.x". Kami tidak secara otomatis meningkatkan aplikasi Fungsi PowerShell yang memiliki "~7" ke "7.4". Ke depannya, untuk PowerShell Function Apps, kami akan mengharuskan aplikasi menentukan versi utama dan minor yang ingin mereka targetkan. Oleh karena itu, perlu disebutkan "7.4" jika Anda ingin menargetkan "7.4.x"

Mengubah versi PowerShell

Pertimbangkan pertimbangan ini sebelum Anda memigrasikan aplikasi fungsi PowerShell ke PowerShell 7.4:

  • Karena migrasi mungkin memperkenalkan perubahan yang melanggar di aplikasi Anda, tinjau panduan migrasi ini sebelum memutakhirkan aplikasi Anda ke PowerShell 7.4.

  • Pastikan aplikasi fungsi Anda berjalan pada versi terbaru runtime Functions di Azure, yaitu versi 4.x. Untuk informasi selengkapnya, lihat Menampilkan dan memperbarui versi runtime saat ini.

Gunakan langkah-langkah berikut untuk mengubah versi PowerShell yang digunakan oleh aplikasi fungsi Anda. Anda dapat melakukan ini baik di portal Microsoft Azure atau dengan menggunakan PowerShell.

  1. Di portal Microsoft Azure, telusuri ke aplikasi fungsi Anda.

  2. Di bawah Setelan, pilih Konfigurasi. Di tab Pengaturan umum, temukan versi PowerShell.

    gambar

  3. Pilih versi PowerShell Core yang Anda inginkan dan pilih Simpan. Ketika diperingatkan tentang hidupkan ulang tertunda pilih Lanjutkan. Aplikasi fungsi dimulai ulang pada versi PowerShell yang dipilih.

Catatan

Dukungan Azure Functions untuk PowerShell 7.4 tersedia secara umum (GA). Anda mungkin melihat PowerShell 7.4 masih ditunjukkan sebagai pratinjau di portal Azure, tetapi ini akan segera diperbarui untuk mencerminkan status GA.

Aplikasi fungsi dihidupkan ulang setelah perubahan dilakukan pada konfigurasi.

Manajemen dependensi

Fungsi memungkinkan Anda memanfaatkan galeri PowerShell untuk mengelola dependensi. Dengan diaktifkannya manajemen dependensi, file requirements.psd1 digunakan untuk mengunduh modul yang diperlukan secara otomatis. Anda mengaktifkan perilaku ini dengan mengatur properti managedDependency ke true di akar file host.json, seperti dalam contoh berikut:

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

Saat Anda membuat proyek fungsi PowerShell baru, manajemen dependensi diaktifkan secara default, dengan Az modul Azure disertakan. Jumlah maksimum modul yang saat ini didukung adalah 10. Sintaksis yang didukung adalah MajorNumber.* atau versi modul mutlak, seperti yang ditunjukkan dalam contoh requirements.psd1 berikut:

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

Saat Anda memperbarui file requirements.psd1, modul yang diperbarui dipasang setelah menghidupkan kembali.

Menargetkan versi tertentu

Anda mungkin ingin menargetkan versi modul tertentu dalam file requirements.psd1 Anda. Misalnya, jika Anda ingin menggunakan Az.Account versi lama daripada yang ada di modul Az yang disertakan, Anda harus menargetkan versi tertentu seperti yang ditunjukkan dalam contoh berikut:

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

Dalam hal ini, Anda juga perlu menambahkan pernyataan impor ke bagian atas file profile.ps1 Anda, yang terlihat seperti contoh berikut:

Import-Module Az.Accounts -RequiredVersion '1.9.5'

Dengan cara ini, versi lama modul Az.Account dimuat terlebih dahulu ketika fungsi dimulai.

Pertimbangan manajemen dependensi

Pertimbangan berikut berlaku saat menggunakan manajemen dependensi:

  • Dependensi terkelola memerlukan akses ke https://www.powershellgallery.com untuk mengunduh modul. Ketika berjalan secara lokal, pastikan bahwa runtime dapat mengakses URL ini dengan menambahkan aturan firewall yang diperlukan.

  • Dependensi terkelola saat ini tidak mendukung modul yang mengharuskan pengguna untuk menerima lisensi, baik dengan menerima lisensi secara interaktif, atau dengan menyediakan sakelar -AcceptLicense saat memanggil Install-Module.

  • Dependensi terkelola tidak didukung saat Anda menghosting aplikasi fungsi Anda dalam paket Konsumsi Flex. Anda harus menentukan modul kustom Anda sendiri.

Pengaturan aplikasi manajemen dependensi

Pengaturan aplikasi berikut dapat digunakan untuk mengubah cara dependensi terkelola diunduh dan dipasang.

Pengaturan Aplikasi Fungsi Nilai default Deskripsi
MDMaxBackgroundUpgradePeriod 7.00:00:00 (tujuh hari) Mengontrol periode pembaruan latar belakang untuk aplikasi fungsi PowerShell. Untuk mempelajari lebih lanjut, lihat MDMaxBackgroundUpgradePeriod.
MDNewSnapshotCheckPeriod 01:00:00 (satu jam) Menentukan seberapa sering setiap pekerja PowerShell memeriksa apakah peningkatan dependensi terkelola telah dipasang. Untuk mempelajari lebih lanjut, lihat MDNewSnapshotCheckPeriod.
MDMinBackgroundUpgradePeriod 1.00:00:00 (satu hari) Jangka waktu setelah pemeriksaan peningkatan sebelumnya sebelum pemeriksaan peningkatan lainnya dimulai. Untuk mempelajari lebih lanjut, lihat MDMinBackgroundUpgradePeriod.

Pada dasarnya, peningkatan aplikasi Anda dimulai dalam MDMaxBackgroundUpgradePeriod, dan proses peningkatan selesai dalam kira-kira MDNewSnapshotCheckPeriod.

Modul kustom

Memanfaatkan modul kustom Anda sendiri di Azure Functions berbeda dari cara Anda melakukannya secara normal untuk PowerShell.

Di komputer lokal Anda, modul akan dipasang di salah satu folder yang tersedia secara global di $env:PSModulePath Anda. Saat berjalan di Azure, Anda tidak memiliki akses ke modul yang dipasang di komputer Anda. Ini berarti bahwa $env:PSModulePath untuk aplikasi fungsi PowerShell berbeda dari $env:PSModulePath di skrip PowerShell biasa.

Di Functions, PSModulePath berisi dua jalur:

  • Folder Modules yang ada di akar aplikasi fungsi Anda.
  • Jalur ke folder Modules yang dikontrol oleh pekerja bahasa PowerShell.

Folder modul tingkat aplikasi fungsi

Untuk menggunakan modul kustom, Anda dapat menempatkan modul tempat fungsi Anda bergantung pada folder Modules. Dari folder ini, modul secara otomatis tersedia untuk runtime fungsi. Fungsi apa pun dalam aplikasi fungsi dapat menggunakan modul ini.

Catatan

Modul yang ditentukan dalam file requirements.psd1 secara otomatis diunduh dan disertakan dalam jalur sehingga Anda tidak perlu memasukkannya ke dalam folder modul. Modul-modul disimpan secara lokal di folder $env:LOCALAPPDATA/AzureFunctions dan di folder /data/ManagedDependencies saat dijalankan di cloud.

Untuk memanfaatkan fitur modul kustom, buat folder Modules di akar aplikasi fungsi Anda. Salin modul yang ingin Anda gunakan dalam fungsi Anda ke lokasi ini.

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

Dengan folder Modules, aplikasi fungsi Anda harus memiliki struktur folder berikut:

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

Saat memulai aplikasi fungsi Anda, pekerja bahasa PowerShell menambahkan folder Modules ini ke $env:PSModulePath sehingga Anda dapat mengandalkan autoloading modul seperti yang Anda lakukan dalam skrip PowerShell biasa.

Folder modul tingkat pekerja bahasa

Beberapa modul umumnya digunakan oleh pekerja bahasa PowerShell. Modul-modul ini ditentukan dalam posisi terakhir dari PSModulePath.

Daftar modul saat ini adalah sebagai berikut:

  • Microsoft.PowerShell.Archive: modul yang digunakan untuk bekerja dengan arsip, seperti .zip, .nupkg, dan lainnya.
  • ThreadJob: Implementasi berbasis rangkaian dari API pekerjaan PowerShell.

Secara default, Functions menggunakan versi terbaru dari modul ini. Untuk menggunakan versi modul tertentu, letakkan versi tertentu tersebut di folder Modules aplikasi fungsi Anda.

Variabel lingkungan

Di Azure Functions, pengaturan aplikasi, seperti string koneksi layanan, diekspos sebagai variabel lingkungan selama eksekusi. Anda dapat mengakses pengaturan ini menggunakan $env:NAME_OF_ENV_VAR, seperti yang ditunjukkan dalam contoh berikut:

param($myTimer)

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

Ada beberapa cara yang dapat Anda tambahkan, perbarui, dan hapus pengaturan aplikasi fungsi:

Perubahan pada pengaturan aplikasi fungsi mengharuskan aplikasi fungsi Anda dimulai ulang.

Saat berjalan secara lokal, pengaturan aplikasi dibaca dari file proyek local.settings.json.

Konkurensi

Secara default, runtime Functions PowerShell hanya dapat memproses satu pemanggilan fungsi pada satu waktu. Namun, tingkat konkurensi ini mungkin tidak cukup dalam situasi berikut:

  • Ketika Anda mencoba untuk menangani sejumlah besar pemanggilan pada saat yang sama.
  • Ketika Anda memiliki fungsi yang memanggil fungsi lain di dalam aplikasi fungsi yang sama.

Ada beberapa model konkurensi yang dapat Anda jelajahi tergantung pada jenis beban kerja:

  • Tingkatkan FUNCTIONS_WORKER_PROCESS_COUNT. Ini memungkinkan penanganan pemanggilan fungsi dalam beberapa proses dalam instans yang sama, yang memperkenalkan CPU dan biaya tambahan memori tertentu. Secara umum, fungsi terikat I/O tidak akan dikenakan biaya tambahan ini. Untuk fungsi terikat CPU, dampaknya mungkin signifikan.

  • Menambah nilai pengaturan aplikasi PSWorkerInProcConcurrencyUpperBound. Ini memungkinkan pembuatan beberapa runspace dalam proses yang sama, yang secara signifikan mengurangi CPU dan biaya tambahan memori.

Anda mengatur variabel lingkungan ini di pengaturan aplikasi dari aplikasi fungsi Anda.

Bergantung pada kasus penggunaan Anda, Durable Functions dapat secara signifikan meningkatkan skalabilitas. Untuk mempelajari lebih lanjut, lihat Pola aplikasi Durable Functions.

Catatan

Anda mungkin mendapatkan peringatan "permintaan sedang diantrekan karena tidak ada runspace yang tersedia", harap diperhatikan bahwa ini bukan kesalahan. Pesan memberi tahu Anda bahwa permintaan sedang diantrekan dan permintaan tersebut akan ditangani ketika permintaan sebelumnya selesai.

Pertimbangan untuk menggunakan konkurensi

PowerShell adalah bahasa pembuatan skrip single_threaded secara default. Namun, konkurensi dapat ditambahkan dengan menggunakan beberapa runspace PowerShell dalam proses yang sama. Jumlah runspace yang dibuat, dan oleh karena itu jumlah utas serentak per pekerja, dibatasi oleh pengaturan aplikasi PSWorkerInProcConcurrencyUpperBound. Secara default, jumlah runspace diatur ke 1.000 di versi 4.x dari runtime Functions. Di versi 3.x dan di bawahnya, jumlah maksimum runspace diatur ke 1. Throughput akan dipengaruhi oleh jumlah CPU dan memori yang tersedia dalam paket yang dipilih.

Azure PowerShell menggunakan beberapa konteks dan status tingkat proses untuk membantu menyelamatkan Anda dari pengetikan berlebih. Namun, jika Anda mengaktifkan konkurensi di aplikasi fungsi Anda dan memanggil tindakan yang mengubah status, Anda bisa berakhir dengan kondisi bersaing. Kondisi bersaing ini sulit di-debug karena satu pemanggilan bergantung pada status tertentu dan pemanggilan lainnya mengubah status.

Ada nilai besar dalam konkurensi dengan Azure PowerShell, karena beberapa operasi dapat memakan waktu yang cukup lama. Namun, Anda harus melanjutkan dengan hati-hati. Jika Anda curiga bahwa Anda mengalami kondisi bersaing, atur pengaturan aplikasi PSWorkerInProcConcurrencyUpperBound ke 1 dan sebagai gantinya gunakan isolasi tingkat proses pekerja bahasa untuk konkurensi.

Mengonfigurasi fungsi scriptFile

Secara default, fungsi PowerShell dijalankan dari run.ps1, file yang berbagi direktori induk yang sama dengan function.json yang sesuai.

Properti scriptFile di function.json dapat digunakan untuk mendapatkan struktur folder yang terlihat seperti contoh berikut:

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

Dalam hal ini, function.json untuk myFunction menyertakan properti scriptFile yang mereferensikan file dengan fungsi yang diekspor untuk dijalankan.

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

Menggunakan modul PowerShell dengan mengonfigurasi entryPoint

Artikel ini telah menunjukkan fungsi PowerShell dalam file skrip run.ps1 default yang dibuat oleh templat. Namun, Anda juga dapat menyertakan fungsi Anda dalam modul PowerShell. Anda dapat mereferensikan kode fungsi spesifik Anda dalam modul dengan menggunakan scriptFile dan bidang entryPoint di file konfigurasi function.json.

Dalam hal ini, entryPoint adalah nama fungsi atau cmdlet dalam modul PowerShell yang direferensikan dalam scriptFile.

Pertimbangkan struktur folder berikut ini:

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

Dengan PSFunction.psm1 berisi:

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

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

Export-ModuleMember -Function "Invoke-PSTestFunc"

Dalam contoh ini, konfigurasi untuk myFunction menyertakan properti scriptFile yang mereferensikan PSFunction.psm1, yang merupakan modul PowerShell di folder lain. Properti entryPoint mereferensikan fungsi Invoke-PSTestFunc, yang merupakan titik masuk dalam modul.

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

Dengan konfigurasi ini, Invoke-PSTestFunc dieksekusi persis seperti yang akan dilakukan run.ps1.

Pertimbangan untuk fungsi PowerShell

Saat Anda bekerja dengan fungsi PowerShell, perhatikan pertimbangan di bagian berikut.

Cold Start

Saat mengembangkan Azure Functions dalam model hosting tanpa server, awal dingin adalah kenyataan. Awal dingin mengacu pada periode waktu yang diperlukan agar aplikasi fungsi Anda mulai berjalan untuk memproses permintaan. Awal dingin terjadi lebih sering dalam paket Konsumsi karena aplikasi fungsi Anda dimatikan selama periode tidak aktif.

Membundel modul alih-alih menggunakan Install-Module

Skrip Anda dijalankan pada setiap pemanggilan. Hindari menggunakan Install-Module dalam skrip Anda. Alih-alih gunakan Save-Module sebelum menerbitkan sehingga fungsi Anda tidak perlu membuang waktu mengunduh modul. Jika awal dingin memengaruhi fungsi Anda, pertimbangkan untuk menyebarkan aplikasi fungsi Anda ke paket App Service yang diatur untuk selalu aktif atau ke paket Premium.

Langkah berikutnya

Untuk informasi selengkapnya, lihat sumber daya berikut: