設定 Runbook 輸出和訊息串流

發行項
03/22/2024

大部分 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 的基本邏輯。
Authenticate Runbook Template Example .

Runbook 包含輸出類型 Microsoft.Azure.Commands.Profile.Models.PSAzureProfile，它會傳回驗證設定檔屬性。
Runbook Output Type Example

雖然這個 Runbook 很簡單，但這裡必須呼叫一個設定項目。最後一個活動會執行 Write-Output Cmdlet，使用 Inputobject 參數的 PowerShell 運算式，將設定檔資料寫入變數。 Write-Output 需要此參數。

此範例中名為 Test-ChildOutputType 的第二個 Runbook，僅定義兩個活動。
Example Child Output Type Runbook

第一個活動會呼叫 AuthenticateTo-Azure Runbook。第二個活動會透過設為 [活動輸出] 的 [資料來源]，執行 Write-Verbose Cmdlet。此外，[欄位路徑] 設為 [Context.Subscription.Name]，這是來自 AuthenticateTo-Azure Runbook 的內容輸出。

產生的輸出是訂用帳戶的名稱。
Test-ChildOutputType Runbook Results

使用訊息串流

與輸出資料流不同，訊息資料流可將資訊傳達給使用者。有多個訊息資料流適用於不同類型的資訊，且 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 則不需要記錄進度記錄。基本追蹤有同樣的效果，且更具參考價值。

Graphical authoring job streams view

從圖片中可以看出，為圖形化 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。