Mengonfigurasi aliran output dan pesan runbook
Sebagian besar runbook Azure Automation memiliki beberapa bentuk output. Output ini dapat berupa pesan kesalahan kepada pengguna atau objek kompleks yang dimaksudkan untuk digunakan dengan runbook lain. Windows PowerShell menyediakan beberapa aliran untuk mengirim output dari skrip atau alur kerja. Azure Automation bekerja dengan masing-masing aliran ini secara berbeda. Anda harus mengikuti praktik terbaik untuk menggunakan aliran saat membuat runbook.
Tabel berikut menjelaskan secara singkat setiap aliran dengan perilakunya di portal Microsoft Azure untuk runbook yang diterbitkan dan selama pengujian runbook. Aliran output adalah aliran utama yang digunakan untuk komunikasi antar-runbook. Aliran lainnya diklasifikasikan sebagai aliran pesan, dimaksudkan untuk mengomunikasikan informasi kepada pengguna.
| Stream | Deskripsi | Diterbitkan | Uji |
|---|---|---|---|
| Kesalahan | Pesan kesalahan yang ditujukan untuk pengguna. Tidak seperti pengecualian, runbook berlanjut setelah pesan kesalahan secara default. | Ditulis dalam riwayat pekerjaan | Ditampilkan di panel output Pengujian |
| Debug | Pesan yang ditujukan untuk pengguna interaktif. Seharusnya tidak digunakan di runbook. | Tidak ditulis dalam riwayat pekerjaan | Tidak ditampilkan di panel output Pengujian |
| Hasil | Objek yang dimaksudkan untuk digunakan oleh runbook lain. | Ditulis dalam riwayat pekerjaan | Ditampilkan di panel output Pengujian |
| Progres | Catatan dibuat secara otomatis sebelum dan sesudah setiap aktivitas di runbook. Runbook tidak boleh mencoba membuat catatan kemajuannya sendiri, karena catatan tersebut ini ditujukan untuk pengguna interaktif. | Ditulis dalam riwayat pekerjaan hanya jika pencatatan kemajuan diaktifkan untuk runbook | Tidak ditampilkan di panel output Pengujian |
| Verbose | Pesan yang memberikan informasi umum atau penelusuran kesalahan. | Ditulis dalam riwayat pekerjaan hanya jika pengelogan verbose diaktifkan untuk runbook | Ditampilkan di panel output Pengujian hanya jika variabel VerbosePreference diatur ke Lanjutkan di runbook |
| Peringatan | Pesan peringatan ditujukan untuk pengguna. | Ditulis dalam riwayat pekerjaan | Ditampilkan di panel output Pengujian |
Menggunakan aliran output
Aliran output digunakan untuk output objek yang dibuat oleh skrip atau alur kerja saat dijalankan dengan benar. Azure Automation terutama menggunakan aliran ini untuk objek yang akan digunakan oleh runbook induk yang memanggil runbook saat ini. Saat induk memanggil runbook sebaris, elemen anak akan mengembalikan data dari aliran output ke induk.
Runbook Anda menggunakan aliran output untuk mengomunikasikan informasi umum kepada klien hanya jika tidak pernah dipanggil oleh runbook lain. Namun, sebagai praktik terbaik, runbook Anda biasanya harus menggunakan aliran verbose untuk mengomunikasikan informasi umum kepada pengguna.
Minta runbook Anda menulis data ke aliran output menggunakan Write-Output. Atau Anda dapat meletakkan objek pada barisnya sendiri dalam skrip.
#The following lines both write an object to the output stream.
Write-Output -InputObject $object
$object
Menangani output dari suatu fungsi
Ketika fungsi runbook menulis ke aliran output, output akan diteruskan kembali ke runbook. Jika runbook menetapkan output tersebut ke variabel, output tidak ditulis ke aliran output. Menulis ke aliran lain dari dalam fungsi menulis ke aliran yang sesuai untuk runbook. Pertimbangkan contoh runbook Alur Kerja PowerShell berikut.
Workflow Test-Runbook
{
Write-Verbose "Verbose outside of function" -Verbose
Write-Output "Output outside of function"
$functionOutput = Test-Function
$functionOutput
Function Test-Function
{
Write-Verbose "Verbose inside of function" -Verbose
Write-Output "Output inside of function"
}
}
Aliran output untuk pekerjaan runbook adalah:
Output inside of function
Output outside of function
Aliran verbose untuk pekerjaan runbook adalah:
Verbose outside of function
Verbose inside of function
Setelah Anda menerbitkan runbook dan sebelum memulainya, Anda juga harus mengaktifkan pengelogan verbose di pengaturan runbook untuk mendapatkan output aliran verbose.
Mendeklarasikan jenis data output
Berikut ini adalah contoh jenis data output:
System.StringSystem.Int32System.Collections.HashtableMicrosoft.Azure.Commands.Compute.Models.PSVirtualMachine
Mendeklarasikan jenis data output dalam alur kerja
Alur kerja menentukan jenis data output-nya menggunakan atribut OutputType. Atribut ini tidak berpengaruh selama runtime, tetapi memberi Anda indikasi pada waktu desain output runbook yang diharapkan. Ketika alat yang ditetapkan untuk runbook terus berkembang, Anda harus mendeklarasikan jenis data output pada waktu desain meningkat. Oleh karena itu, ini adalah praktik terbaik untuk menyertakan deklarasi ini di setiap runbook yang Anda buat.
Contoh runbook berikut menampilkan objek string dan menyertakan deklarasi jenis output-nya. Jika runbook Anda menampilkan larik dengan tipe tertentu, Anda tetap harus menentukan tipenya sebagai lawan dari larik bertipe tersebut.
Workflow Test-Runbook
{
[OutputType([string])]
$output = "This is some string output."
Write-Output $output
}
Mendeklarasikan jenis data output dalam runbook grafis
Untuk mendeklarasikan jenis output dalam runbook Alur Kerja PowerShell grafis atau grafis, Anda dapat memilih opsi menu Input dan Output, lalu memasukkan jenis output. Sebaiknya menggunakan nama kelas .NET lengkap untuk membuat jenisnya mudah diidentifikasi ketika runbook induk mereferensikannya. Menggunakan nama lengkap akan mengekspos semua properti kelas ke data bus di runbook dan meningkatkan fleksibilitas saat properti digunakan untuk logika kondisional, pengelogan, dan referensi sebagai nilai untuk aktivitas runbook lainnya.
Catatan
Setelah Anda memasukkan nilai di bidang Jenis Output di panel properti Input dan Output, pastikan untuk mengeklik di luar kontrol agar runbook mengenali entri Anda.
Contoh berikut menunjukkan dua runbook grafis untuk mendemonstrasikan fitur Input dan Output. Menerapkan model desain runbook modular, Anda memiliki satu runbook sebagai templat Authenticate Runbook yang mengelola autentikasi dengan Azure menggunakan Identitas terkelola. Runbook kedua, yang biasanya menjalankan logika inti untuk mengotomatiskan skenario yang diberikan, dalam hal ini menjalankan templat Authenticate Runbook. Ini menampilkan hasil ke panel output Pengujian Anda. Dalam keadaan normal, Anda akan membuat runbook ini melakukan sesuatu terhadap sumber daya yang memanfaatkan output dari runbook elemen anak.
Berikut adalah logika dasar runbook AuthenticateTo-Azure .
.
Runbook menyertakan jenis output Microsoft.Azure.Commands.Profile.Models.PSAzureProfile, yang mengembalikan properti profil autentikasi.
Meskipun runbook ini mudah, ada satu item konfigurasi untuk dipanggil di sini. Aktivitas terakhir menjalankan cmdlet Write-Output untuk menulis data profil ke variabel menggunakan ekspresi PowerShell untuk parameter Inputobject. Parameter ini diperlukan untuk Write-Output.
Runbook kedua dalam contoh ini, bernama Test-ChildOutputType, hanya mendefinisikan dua aktivitas.
Aktivitas pertama memanggil runbook AuthenticateTo-Azure. Aktivitas kedua menjalankan cmdlet Write-Verbose dengan Sumber data yang diatur ke Output aktivitas. Selain itu, Jalur bidang diatur ke Context.Subscription.Name, output konteks dari runbook AuthenticateTo-Azure .
Output yang dihasilkan adalah nama langganan.
Bekerja dengan aliran pesan
Berbeda dengan aliran output, aliran pesan menyampaikan informasi kepada pengguna. Ada beberapa aliran pesan untuk berbagai jenis informasi dan Azure Automation menangani setiap aliran secara berbeda.
Menulis output ke aliran peringatan dan kesalahan
Aliran peringatan dan kesalahan akan mencatat masalah yang terjadi di runbook. Azure Automation akan menulis aliran ini ke riwayat pekerjaan saat menjalankan runbook. Automation menyertakan aliran di panel output Pengujian di portal Microsoft Azure saat runbook diuji.
Secara default, runbook akan terus dijalankan setelah peringatan atau kesalahan. Anda dapat menentukan bahwa runbook Anda harus ditangguhkan pada peringatan atau kesalahan dengan meminta runbook mengatur variabel preferensi sebelum membuat pesan. Misalnya, agar runbook ditangguhkan pada kesalahan seperti yang terjadi pada pengecualian, atur variabel ErrorActionPreference ke Hentikan.
Membuat pesan peringatan atau kesalahan menggunakan cmdlet Write-Warning atau Write-Error. Aktivitas juga dapat menulis ke aliran peringatan dan kesalahan.
#The following lines create a warning message and then an error message that will suspend the runbook.
$ErrorActionPreference = "Stop"
Write-Warning -Message "This is a warning message."
Write-Error -Message "This is an error message that will stop the runbook because of the preference variable."
Menulis output ke aliran debug
Azure Automation menggunakan aliran pesan debug untuk pengguna interaktif. Secara default Azure Automation tidak menangkap data aliran debug apa pun, hanya data output, kesalahan, dan peringatan yang ditangkap serta data verbose jika runbook dikonfigurasi untuk menangkapnya.
Untuk mengambil data aliran debug, Anda harus melakukan dua tindakan di runbook Anda:
Atur variabel
$GLOBAL:DebugPreference="Continue", yang memberi tahu PowerShell untuk melanjutkan setiap kali pesan debug ditemukan. Bagian $GLOBAL: akan memberi tahu PowerShell untuk melakukan ini dalam cakupan global daripada cakupan lokal apa pun tempat skrip berada pada saat pernyataan dijalankan.Alihkan aliran debug yang tidak kita ambil ke aliran yang kita ambil sebagai output. Ini dilakukan dengan mengatur pengalihan PowerShell terhadap pernyataan yang akan dijalankan. Untuk informasi selengkapnya tentang pengalihan PowerShell, lihat Tentang Pengalihan.
Contoh
Dalam contoh ini, runbook dikonfigurasikan menggunakan cmdlet Write-Output dan Write-Debug dengan tujuan menghasilkan dua aliran berbeda.
Write-Output "This is an output message."
Write-Debug "This is a debug message."
Jika runbook ini dijalankan sebagaimana adanya, panel output untuk pekerjaan runbook akan mengalirkan output berikut:
This is an output message.
Dalam contoh ini, runbook dikonfigurasikan serupa dengan contoh sebelumnya, kecuali pernyataan $GLOBAL:DebugPreference="Continue" akan disertakan dengan penambahan 5>&1 di akhir pernyataan Write-Debug.
Write-Output "This is an output message."
$GLOBAL:DebugPreference="Continue"
Write-Debug "This is a debug message." 5>&1
Jika runbook ini dijalankan, panel output untuk pekerjaan runbook akan mengalirkan output berikut:
This is an output message.
This is a debug message.
Ini terjadi karena pernyataan $GLOBAL:DebugPreference="Continue" memberi tahu PowerShell untuk menampilkan pesan debug dan penambahan 5>&1 di akhir pernyataan Write-Debug memberi tahu PowerShell untuk mengalihkan aliran 5 (debug) ke aliran 1 (output).
Menulis output ke aliran verbose
Aliran pesan Verbose mendukung informasi umum tentang operasi runbook. Karena aliran debug tidak tersedia untuk runbook, runbook Anda harus menggunakan pesan verbose untuk informasi debug.
Secara default, riwayat pekerjaan tidak menyimpan pesan verbose dari runbook yang diterbitkan karena alasan kinerja. Untuk menyimpan pesan verbose, gunakan tab Konfigurasikan portal Microsoft Azure dengan pengaturan Data Log Verbose untuk mengonfigurasi runbook yang diterbitkan untuk mencatat pesan verbose. Aktifkan opsi ini hanya untuk memecahkan masalah atau men-debug runbook. Dalam kebanyakan kasus, Anda harus mempertahankan pengaturan default untuk tidak mencatat data verbose.
Saat menguji runbook, pesan verbose tidak ditampilkan meskipun runbook dikonfigurasi untuk mencatat data verbose. Untuk menampilkan pesan verbose saat menguji runbook, Anda harus mengatur variabel VerbosePreference ke Lanjutkan. Dengan kumpulan variabel tersebut, pesan verbose akan ditampilkan di panel output pengujian portal Microsoft Azure.
Kode berikut membuat pesan verbose menggunakan cmdlet Write-Verbose.
#The following line creates a verbose message.
Write-Verbose -Message "This is a verbose message."
Menangani catatan kemajuan
Anda dapat menggunakan tab Konfigurasikan portal Microsoft Azure untuk mengonfigurasi runbook untuk mencatat catatan kemajuan. Pengaturan default adalah untuk tidak mencatat catatan guna memaksimalkan kinerja. Dalam kebanyakan kasus, Anda harus mempertahankan pengaturan default. Aktifkan opsi ini hanya untuk memecahkan masalah atau men-debug runbook.
Jika Anda mengaktifkan pengelogan catatan kemajuan, runbook Anda akan menulis catatan dalam riwayat pekerjaan sebelum dan setelah setiap aktivitas berjalan. Menguji runbook tidak menampilkan pesan kemajuan meskipun runbook dikonfigurasi untuk mencatat rekaman kemajuan.
Catatan
Cmdlet Write-Progress tidak valid dalam runbook, karena cmdlet ini dimaksudkan untuk digunakan dengan pengguna interaktif.
Bekerja dengan variabel preferensi
Anda dapat mengatur variabel preferensi Windows PowerShell tertentu di runbook Anda untuk mengontrol respons terhadap data yang dikirim ke aliran output yang berbeda. Tabel berikut mencantumkan variabel preferensi yang dapat digunakan dalam runbook, dengan nilai default dan validnya. Nilai tambahan akan tersedia untuk variabel preferensi saat digunakan di Windows PowerShell di luar Azure Automation.
| Variabel | Nilai Default | Nilai yang Valid |
|---|---|---|
WarningPreference |
Lanjutkan | Stop Lanjutkan Lanjutkan Diam-diam |
ErrorActionPreference |
Lanjutkan | Stop Lanjutkan Lanjutkan Diam-diam |
VerbosePreference |
Lanjutkan Diam-diam | Stop Lanjutkan Lanjutkan Diam-diam |
Tabel berikutnya mencantumkan perilaku untuk nilai variabel preferensi yang valid di runbook.
| Nilai | Perilaku |
|---|---|
| Lanjutkan | Mencatat pesan dan melanjutkan menjalankan runbook. |
| Lanjutkan Diam-diam | Melanjutkan menjalankan runbook tanpa mencatat pesan. Nilai ini memiliki efek mengabaikan pesan. |
| Stop | Mencatat pesan dan menangguhkan runbook. |
Mengambil output dan pesan runbook
Mengambil output dan pesan runbook di portal Microsoft Azure
Anda dapat melihat detail pekerjaan runbook di portal Microsoft Azure menggunakan tab Pekerjaan untuk runbook. Ringkasan pekerjaan menampilkan parameter input dan aliran output, selain informasi umum tentang pekerjaan dan pengecualian apa pun yang terjadi. Riwayat pekerjaan mencakup pesan dari aliran output dan aliran peringatan dan kesalahan. Ini juga termasuk pesan dari aliran verbose dan catatan kemajuan jika runbook dikonfigurasi untuk mencatat verbose dan catatan kemajuan.
Catatan
Aliran pekerjaan untuk runbook Python saat ini didukung untuk output dalam bahasa Inggris.
Mengambil output dan pesan runbook di Windows PowerShell
Di Windows PowerShell, Anda dapat mengambil output dan pesan dari runbook menggunakan cmdlet Get-AzAutomationJobOutput. Cmdlet ini memerlukan ID pekerjaan dan memiliki parameter yang disebut Stream untuk menentukan aliran yang akan diambil. Anda dapat menentukan nilai Any untuk parameter ini guna mengambil semua aliran untuk pekerjaan tersebut.
Contoh berikut memulai contoh runbook dan kemudian menunggu hingga selesai. Setelah runbook menyelesaikan eksekusi, skrip akan mengumpulkan aliran output runbook dari pekerjaan.
$job = Start-AzAutomationRunbook -ResourceGroupName "ResourceGroup01" `
-AutomationAccountName "MyAutomationAccount" -Name "Test-Runbook"
$doLoop = $true
While ($doLoop) {
$job = Get-AzAutomationJob -ResourceGroupName "ResourceGroup01" `
-AutomationAccountName "MyAutomationAccount" -Id $job.JobId
$status = $job.Status
$doLoop = (($status -ne "Completed") -and ($status -ne "Failed") -and ($status -ne "Suspended") -and ($status -ne "Stopped"))
}
Get-AzAutomationJobOutput -ResourceGroupName "ResourceGroup01" `
-AutomationAccountName "MyAutomationAccount" -Id $job.JobId -Stream Output
# For more detailed job output, pipe the output of Get-AzAutomationJobOutput to Get-AzAutomationJobOutputRecord
Get-AzAutomationJobOutput -ResourceGroupName "ResourceGroup01" `
-AutomationAccountName "MyAutomationAccount" -Id $job.JobId -Stream Any | Get-AzAutomationJobOutputRecord
Mengambil output dan pesan runbook dalam runbook grafis
Untuk runbook grafis, pengelogan output dan pesan tambahan tersedia dalam bentuk pelacakan tingkat aktivitas. Ada dua tingkat pelacakan: Dasar dan Terperinci. Pelacakan dasar menampilkan waktu mulai dan berakhir untuk setiap aktivitas di runbook, ditambah informasi yang terkait dengan percobaan ulang aktivitas apa pun. Beberapa contoh adalah jumlah upaya dan waktu mulai aktivitas. Pelacakan terperinci mencakup fitur pelacakan dasar ditambah pengelogan data input dan output untuk setiap aktivitas.
Saat ini pelacakan tingkat aktivitas menulis catatan menggunakan aliran verbose. Oleh karena itu Anda harus mengaktifkan pengelogan verbose saat mengaktifkan pelacakan. Untuk runbook grafis dengan pelacakan diaktifkan, tidak perlu mencatat catatan kemajuan. Pelacakan dasar memiliki tujuan yang sama dan lebih informatif.
Anda dapat melihat dari gambar bahwa mengaktifkan pengelogan dan pelacakan verbose untuk runbook grafis membuat lebih banyak informasi tersedia dalam tampilan Aliran Pekerjaan produksi. Informasi tambahan ini dapat menjadi penting untuk memecahkan masalah produksi dengan runbook.
Namun, kecuali Anda memerlukan informasi ini untuk melacak kemajuan runbook untuk pemecahan masalah, Anda mungkin ingin tetap menonaktifkan pelacakan sebagai praktik umum. Catatan pelacakan bisa sangat banyak. Dengan pelacakan runbook grafis, Anda dapat memperoleh dua hingga empat catatan per aktivitas, tergantung pada konfigurasi pelacakan Dasar atau Terperinci.
Untuk mengaktifkan pelacakan tingkat aktivitas:
Dalam portal Microsoft Azure, buka akun Otomatisasi Anda.
Pilih Runbook di bawah Proses Automation untuk membuka daftar runbook.
Pada halaman Runbook, pilih runbook grafis dari daftar runbook Anda.
Di bawah Pengaturan, klik Pengelogan dan pelacakan.
Pada halaman Pengelogan dan Pelacakan, di bawah Catatan verbose log, klik Aktif untuk mengaktifkan pengelogan verbose.
Di bawah Pelacakan tingkat aktivitas, ubah tingkat pelacakan ke Dasar atau Terperinci, berdasarkan tingkat pelacakan yang Anda perlukan.
Mengambil output dan pesan runbook di log Microsoft Azure Monitor
Azure Automation dapat mengirim status pekerjaan runbook dan aliran pekerjaan ke ruang kerja Analitik Log Anda. Azure Monitor mendukung log yang memungkinkan Anda untuk:
- Mendapatkan wawasan tentang pekerjaan Automation Anda.
- Memicu email atau pemberitahuan berdasarkan status pekerjaan runbook Anda, misalnya, Gagal atau Ditangguhkan.
- Menulis kueri lanjutan di seluruh aliran pekerjaan Anda.
- Menghubungkan pekerjaan di seluruh akun Otomatisasi.
- Memvisualisasikan riwayat pekerjaan.
Untuk informasi selengkapnya tentang mengonfigurasi integrasi dengan Log Azure Monitor untuk mengumpulkan, menghubungkan, dan bertindak berdasarkan data pekerjaan, lihat Meneruskan status pekerjaan dan aliran pekerjaan dari Automation ke Log Azure Monitor.
Langkah berikutnya
- Untuk kueri sampel, lihat Contoh kueri untuk log pekerjaan dan aliran pekerjaan
- Untuk bekerja dengan runbook, lihat Mengelola runbook di Azure Automation.
- Jika Anda tidak terbiasa dengan pembuatan skrip PowerShell, lihat dokumentasi PowerShell .
- Untuk referensi cmdlet Azure Automation PowerShell, lihat Az.Automation.