設定 Runbook 輸出和訊息串流
大部分 Azure 自動化 Runbook 都有一些輸出形式。 此輸出可能是給使用者的錯誤訊息,或是要與另一個 Runbook 搭配使用的複雜物件。 Windows PowerShell 提供 多個資料流 從指令碼或工作流程傳送輸出。 Azure 自動化會以不同方式處理這些資料流中的每一個。 建立 Runbook 時,應遵循使用資料流的最佳做法。
下表簡述每個資料流及其針對已發佈 Runbook 在 Azure 入口網站中的行為,以及在測試 Runbook期間的行為。 輸出資料流是用於 Runbook 之間進行通訊的主要資料流。 其他資料流分類為訊息資料流,其用意在於將資訊傳達給使用者。
串流 | 描述 | 已發行 | Test |
---|---|---|---|
錯誤 | 適用於使用者的錯誤訊息。 與例外狀況不同,Runbook 預設會在出現錯誤訊息後繼續執行。 | 寫入作業記錄 | 在 [測試輸出] 窗格中顯示 |
偵錯 | 適用於互動式使用者的訊息。 不應在 Runbook 中使用。 | 不會寫入作業記錄 | 在 [測試輸出] 窗格中不顯示 |
輸出 | 供其他 Runbook 使用的物件。 | 寫入作業記錄 | 在 [測試輸出] 窗格中顯示 |
進度 | 在 Runbook 中每項活動之前和之後自動產生記錄。 Runbook 不應嘗試建立它自己的進度記錄,因為這些記錄是供互動式使用者使用。 | 只有為 Runbook 開啟進度記錄時,才會寫入作業記錄 | 在 [測試輸出] 窗格中不顯示 |
詳細資訊 | 提供一般或偵錯資訊的訊息。 | 只有為 Runbook 開啟詳細記錄時,才會寫入作業記錄 | 只有在 Runbook 中將 VerbosePreference 變數設為 Continue 時,才會在 [測試輸出] 窗格中顯示 |
警告 | 適用於使用者的警告訊息。 | 寫入作業記錄 | 在 [測試輸出] 窗格中顯示 |
使用輸出資料流
輸出資料流用於指令碼或工作流程正確執行時所建立的物件輸出。 Azure 自動化主要將此資料流用於由呼叫 目前 Runbook 的父代 Runbook 所使用的物件。 從父代呼叫 Runbook 內嵌時,子系會將輸出資料流的資料傳回父代。
只有在您的 Runbook 絕對不會被另一個 Runbook 呼叫時,該 Runbook 才能使用輸出資料流,將一般資訊傳達給用戶端。 但最佳做法是,您的 Runbook 通常會使用詳細資訊資料流,將一般資訊傳達給使用者。
讓您的 Runbook 使用 Write-Output,將資料寫入輸出資料流。 或者,您也可以在指令碼中,將物件放在它自己的行上。
#The following lines both write an object to the output stream.
Write-Output -InputObject $object
$object
處理函式的輸出
當 Runbook 函式寫入輸出資料流時,會將輸出傳遞回 Runbook。 如果 Runbook 將該輸出指派給變數,則不會將輸出寫入輸出資料流。 若從函式中寫入至任何其他資料流,將會寫入至 Runbook 的相對應資料流。 請考慮下列範例 PowerShell 工作流程 Runbook。
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"
}
}
Runbook 作業的輸出資料流是:
Output inside of function
Output outside of function
Runbook 作業的詳細資訊資料流是:
Verbose outside of function
Verbose inside of function
在您發佈 Runbook 之後,並在啟動之前,您還必須在 Runbook 設定中開啟詳細資訊記錄,以取得詳細資訊資料流的輸出。
宣告輸出資料類型
以下是輸出資料類型的範例:
System.String
System.Int32
System.Collections.Hashtable
Microsoft.Azure.Commands.Compute.Models.PSVirtualMachine
在工作流程中宣告輸出資料類型
工作流程可使用 OutputType 屬性指定其輸出的資料類型。 這個屬性在執行階段沒有任何作用,但會在設計時指示預期的 Runbook 輸出。 隨著 Runbook 的工具組持續發展,在設計時宣告輸出資料類型的重要性也隨之提升。 因此,最佳做法是在您建立的任何 Runbook 中包含此宣告。
下列 Runbook 範例輸出字串物件,並包含其輸出類型的宣告。 如果您的 Runbook 會輸出特定類型的陣列,則您仍應指定類型而非類型陣列。
Workflow Test-Runbook
{
[OutputType([string])]
$output = "This is some string output."
Write-Output $output
}
在圖形化 Runbook 中宣告輸出資料類型
若要在圖形化或圖形化 PowerShell 工作流程 Runbook 中宣告輸出類型,您可以選取 [輸入和輸出] 功能表選項,然後輸入輸出類型。 建議您使用完整的 .NET 類別名稱,以便父代 Runbook 在參考此名稱時,可以輕鬆地找到類型。 使用全名會將該類別的所有屬性公開至 Runbook 中的資料匯流排,並在將其用於條件式邏輯、記錄及參考以做為其他 Runbook 活動的值時,提供彈性。
注意
在 [輸入和輸出屬性] 窗格的 [輸出類型] 欄位中輸入值之後,請務必按一下控制項外部,使其能夠辨識您的輸入。
下列範例顯示兩個圖形化 Runbook,以示範 [輸入和輸出] 功能。 套用模組化 Runbook 設計模型後,您就有一個 Runbook 做為「驗證 Runbook 範本」,可以使用受控識別來管理 Azure 的驗證。 第二個 Runbook 通常會執行核心邏輯,以自動化特定案例,在這種情況下,會執行驗證 Runbook 範本。 它會將結果顯示在 [測試輸出] 窗格中。 在正常情況下,您會讓此 Runbook 針對運用子 Runbook 輸出的資源執行某些工作。
以下是 AuthenticateTo-Azure Runbook 的基本邏輯。
.
Runbook 包含輸出類型 Microsoft.Azure.Commands.Profile.Models.PSAzureProfile
,它會傳回驗證設定檔屬性。
雖然這個 Runbook 很簡單,但這裡必須呼叫一個設定項目。 最後一個活動會執行 Write-Output
Cmdlet,使用 Inputobject
參數的 PowerShell 運算式,將設定檔資料寫入變數。 Write-Output
需要此參數。
此範例中名為 Test-ChildOutputType 的第二個 Runbook,僅定義兩個活動。
第一個活動會呼叫 AuthenticateTo-Azure Runbook。 第二個活動會透過設為 [活動輸出] 的 [資料來源],執行 Write-Verbose
Cmdlet。 此外,[欄位路徑] 設為 [Context.Subscription.Name],這是來自 AuthenticateTo-Azure Runbook 的內容輸出。
產生的輸出是訂用帳戶的名稱。
使用訊息串流
與輸出資料流不同,訊息資料流可將資訊傳達給使用者。 有多個訊息資料流適用於不同類型的資訊,且 Azure 自動化會以不同的方式處理每個資料流。
將輸出寫入到警告和錯誤串流
警告和錯誤資料流會記錄在 Runbook 中發生的問題。 Azure 自動化會在執行 Runbook 時,將這些資料流寫入作業記錄。 測試 Runbook 時,自動化包括 Azure 入口網站中 [測試輸出] 窗格中的資料流。
根據預設,Runbook 會在警告或錯誤之後繼續執行。 建立訊息之前,您可以藉由讓 Runbook 設定 喜好設定變數,指定 Runbook 應該在警告或錯誤時暫停。 例如,若要讓 Runbook 在發生錯誤時暫停 (就像發生例外狀況時一樣),請將 ErrorActionPreference
變數設為 Stop。
使用 Write-Warning 或 Write-Error Cmdlet 建立警告或錯誤訊息。 活動也可以寫入警告和錯誤資料流。
#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."
將輸出寫入到偵錯串流
Azure 自動化為互動式使用者使用偵錯訊息資料流。 根據預設,Azure 自動化不會擷取任何偵錯串流資料,只會擷取輸出、錯誤和警告資料以及詳細資訊資料 (如果 Runbook 已設定為要擷取此資料的話)。
若要擷取偵錯串流資料,您必須在 Runbook 中執行兩個動作:
設定變數
$GLOBAL:DebugPreference="Continue"
,以指示 PowerShell 每當遇到偵錯訊息時繼續執行。 $GLOBAL: 部分會指示 PowerShell 在全域範圍執行此動作,而不是在執行陳述式時指令碼所在的任何本機範圍內執行。將我們不會擷取的偵錯串流重新導向至我們會擷取的串流,例如輸出。 若要進行此作業,請針對要執行的陳述式設定 PowerShell 重新導向。 如需 PowerShell 重新導向的詳細資訊,請參閱關於重新導向。
範例
此範例會使用 Write-Output
和 Write-Debug
Cmdlet 來設定 Runbook,目的是要輸出兩個不同的串流。
Write-Output "This is an output message."
Write-Debug "This is a debug message."
如果要依原樣執行此 Runbook,Runbook 作業的輸出窗格會串流處理下列輸出:
This is an output message.
在此範例中,Runbook 的設定方式與上一個範例類似,但在納入 $GLOBAL:DebugPreference="Continue"
陳述式時,會於 Write-Debug
陳述式的結尾加上 5>&1
。
Write-Output "This is an output message."
$GLOBAL:DebugPreference="Continue"
Write-Debug "This is a debug message." 5>&1
如果要執行此 Runbook,Runbook 作業的輸出窗格會串流處理下列輸出:
This is an output message.
This is a debug message.
會發生此情況是因為,$GLOBAL:DebugPreference="Continue"
陳述式會指示 PowerShell 顯示偵錯訊息,而在 Write-Debug
陳述式結尾加上 5>&1
則會指示 PowerShell 將串流 5 (偵錯) 重新導向至串流 1 (輸出)。
將輸出寫入到詳細資訊串流
詳細資訊訊息資料流支援 Runbook 作業的一般相關資訊。 由於 Runbook 無法使用偵錯資料流,因此,您的 Runbook 應該使用詳細資訊訊息來處理偵錯資訊。
基於效能考量,作業記錄依預設不會儲存已發佈 Runbook 的詳細資訊訊息。 若要儲存詳細資訊訊息,請使用 Azure 入口網站的 [設定] 索引標籤與 [記錄詳細資訊記錄] 設定,將已發佈的 Runbook 設為記錄詳細資訊訊息。 只有在疑難排解或偵錯 Runbook 時才開啟這個選項。 在大部分情況下,您應該保留預設設定,不記錄詳細資訊記錄。
測試 Runbook時,即使 Runbook 設為記錄詳細記錄,也不會顯示詳細訊息。 若要在測試 Runbook 時,顯示詳細資訊訊息,您必須將 VerbosePreference
變數設為 Continue。 設定該變數後,詳細資訊訊息會顯示在 Azure 入口網站的 [測試輸出] 窗格中。
下列程式碼使用 Write-Verbose Cmdlet 建立詳細資訊訊息。
#The following line creates a verbose message.
Write-Verbose -Message "This is a verbose message."
處理進度記錄
您可以使用 Azure 入口網站的 [設定] 索引標籤,設定 Runbook 來記錄進度記錄。 預設設定為不記錄記錄,以發揮最大效能。 在大部分的情況下,您應該保留預設設定。 只有在疑難排解或偵錯 Runbook 時才開啟這個選項。
如果您啟用進度記錄記錄,Runbook 會在每個活動執行前後,將記錄寫入作業記錄。 即使 Runbook 設為記錄進度記錄,測試 Runbook 也不會顯示進度訊息。
注意
Write-Progress Cmdlet 在 Runbook 中無效,因為此 Cmdlet 是用來和互動式使用者搭配使用的。
使用喜好設定變數
您可以在 Runbook 中設定特定的 Windows PowerShell 喜好設定變數,以控制傳送至不同輸出資料流的資料回應。 下表列出可用於 Runbook 的喜好設定變數,及其預設值和有效值。 其他的值是在 Azure 自動化外部的 Windows PowerShell 中使用喜好設定變數時的可用值。
變數 | 預設值 | 有效的值 |
---|---|---|
WarningPreference |
繼續 | 停止 繼續 SilentlyContinue |
ErrorActionPreference |
繼續 | 停止 繼續 SilentlyContinue |
VerbosePreference |
SilentlyContinue | 停止 繼續 SilentlyContinue |
下表針對 Runbook 中有效的喜好設定變數,列出其行為。
值 | 行為 |
---|---|
繼續 | 將訊息記錄,並繼續執行 Runbook。 |
SilentlyContinue | 繼續執行 Runbook 而不記錄訊息。 此值有忽略訊息的作用。 |
停止 | 將訊息記錄並擱置 Runbook。 |
擷取 Runbook 輸出和訊息
擷取 Azure 入口網站中的 Runbook 輸出和訊息
您可以針對 Runbook,使用 [作業] 索引標籤,在 Azure 入口網站中,檢視 Runbook 作業的詳細資料。 除了作業和任何發生的例外狀況一般資訊以外,作業摘要也會顯示輸入參數和輸出資料流。 作業記錄包含來自輸出資料流和警告與錯誤資料流的訊息。 如果 Runbook 設為記錄詳細資訊和進度記錄,作業記錄也會包含來自詳細資訊資料流和進度記錄的訊息。
注意
Python Runbook 的作業串流目前支援英文輸出。
在 Windows PowerShell 中擷取 Runbook 輸出和訊息
在 Windows PowerShell 中,您可以使用 Get-AzAutomationJobOutput Cmdlet,從 Runbook 擷取輸出與訊息。 這個 Cmdlet 需要作業的識別碼,而且具有稱為 Stream
的參數,可讓您指定要擷取的資料流。 您可以為此參數指定 Any 的值,以擷取作業的所有資料流。
下列範例會啟動 Runbook 範例,然後等待其完成。 Runbook 完成執行後,指令碼會從作業收集 Runbook 輸出資料流。
$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
在圖形化 Runbook 中擷取 Runbook 輸出和訊息
對於圖形化 Runbook,會以活動層級追蹤的形式,提供額外記錄輸出和訊息的功能。 追蹤有兩種等級:基本及詳細。 基本追蹤會顯示 Runbook 中每個活動的開始及結束時間,以及任何活動重試的相關資訊。 例如,嘗試次數及活動開始時間。 詳細追蹤包含基本追蹤功能,加上每個活動的輸入及輸出資料的記錄。
目前活動層級追蹤會使用詳細資訊資料流來寫入記錄。 因此,當您啟用追蹤時,必須啟用詳細資訊記錄。 已啟用追蹤的圖形化 Runbook 則不需要記錄進度記錄。 基本追蹤有同樣的效果,且更具參考價值。
從圖片中可以看出,為圖形化 Runbook 啟用詳細資訊記錄及追蹤功能時,實際執行的作業資料流檢視會提供更多資訊。 此額外資訊對於疑難排解使用 Runbook 所產生的實際執行問題是不可或缺的。
然而,除非您需要這項資訊來追蹤 Runbook 的進度以便疑難排解,否則我們通常會建議您關閉追蹤功能。 追蹤記錄的數量可以非常多。 只要利用圖形化 Runbook 追蹤功能,您就可以為每個活動取得二到四個記錄,取決於您的設定是基本追蹤還是詳細追蹤而定。
若要啟用活動層級追蹤:
在 Azure 入口網站中,開啟自動化帳戶。
選取 [程序自動化] 底下的 [Runbook],以開啟 Runbook 清單。
在 [Runbook] 頁面中,從 Runbook 清單中選取圖形化 Runbook。
在 [設定] 底下,按一下 [記錄和追蹤]。
在 [記錄和追蹤] 頁面的 [記錄詳細資訊記錄] 下,按一下 [開啟],以啟用詳細資訊記錄。
在 [活動層級追蹤] 下,根據您所需的追蹤層級,將追蹤層級變更為 [基本] 或 [詳細]。
在 Microsoft Azure 監視器記錄中擷取 Runbook 輸出與訊息
Azure 自動化可將 Runbook 作業狀態和作業串流傳送至您的 Log Analytics 工作區。 Azure 監視器支援記錄,可讓您:
- 取得自動化作業的相關見解。
- 根據您的 Runbook 作業狀態 (例如失敗或已暫止) 觸發電子郵件或警示。
- 撰寫作業資料流之間的進階查詢。
- 使自動化帳戶之間的作業相互關聯。
- 視覺化作業記錄。
如需設定與 Azure 監視器記錄整合以收集、相互關聯及處理作業資料的詳細資訊,請參閱將作業狀態和作業資料流從自動化轉送到 Azure 監視器記錄。
下一步
- 如需範例查詢,請參閱工作記錄和工作串流的範例查詢
- 若要使用 Runbook,請參閱在 Azure 自動化中管理 Runbook。
- 如果您不熟悉 PowerShell 指令碼,請參閱 PowerShell 文件。
- 如需 Azure 自動化 PowerShell Cmdlet 參考,請參閱 Az.Automation。
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應