在 Azure 自動化中管理模組

  • 發行項

Azure 自動化會使用數個 PowerShell 模組，在 Runbook 中啟用 Cmdlet，以及在 DSC 設定中啟用 DSC 資源。 支援的模組包括：

當您建立自動化帳戶時，Azure 自動化預設會匯入一些模組。 請參閱預設模組。

沙箱

當自動化執行 Runbook 和 DSC 編譯作業時，其會將模組載入至沙箱，Runbook 可在其中執行，而且 DSC 設定可在其中編譯。 自動化也會將所有 DSC 資源自動放置於 DSC 提取伺服器的模組中。 當機器套用 DSC 設定時，即可提取資源。

雲端沙箱最多支援 48 個系統呼叫，並基於安全性考量而限制所有其他呼叫。 雲端沙箱不支援其他功能，例如認證管理和某些網路功能。

由於包含的模組和 Cmdlet 數目，因此在事先很難知道哪一個 Cmdlet 會進行不支援的呼叫。 一般而言，我們已發現需要提高存取權的 Cmdlet、需要認證作為參數，或與網路相關的 Cmdlet 問題。 沙箱不支援執行完整堆疊網路作業的任何 Cmdlet，包括來自 AIPService PowerShell 模組的 Connect-AipService 和來自 DNSClient 模組的 Resolve-DnsName。

這些都是沙箱的已知限制。 建議的因應措施是部署混合式 Runbook 背景工作角色或使用 Azure Functions。

重要

請勿在任何專為 Az 模組執行的指令碼中包含關鍵字 "AzureRm"。 就算只是在註解中包含關鍵字，也可能導致 AzureRm 載入，然後與 Az 模組發生衝突。

預設模組

所有新的自動化帳戶均預設為匯入最新版本的 PowerShell Az 模組。 Az 模組會取代 AzureRM，是搭配 Azure 使用的建議模組。 新自動化帳戶中的預設模組包含現有的 24 個 AzureRM 模組和 60 個以上 Az 模組。

自動化帳戶的使用者可以使用原生原項，將模組更新為最新的 Az 模組。 此作業會處理後端的所有模組相依性，藉此免於手動 更新模組或執行 Runbook 來更新 Azure 模組的麻煩。

如果現有的自動化帳戶只有 AzureRM 模組，則更新 Az 模組選項會以使用者選取的 Az 模組版本來更新自動化帳戶。

如果現有的自動化帳戶有 AzureRM 和某些 Az 模組，此選項會將其餘的 Az 模組匯入至自動化帳戶。 現有的 Az 模組將優先處理，且更新作業不會更新這些模組。 這是為了確保更新模組作業不會因為不小心更新 Runbook 所使用的模組而造成任何 Runbook 執行失敗。 此案例的建議方法是先刪除現有的 Az 模組，然後執行更新作業，以取得自動化帳戶中匯入的最新 Az 模組。 依照預設，並不會匯入這類模組類型，它們稱為自訂。 自訂模組的優先順序一律高於預設模組。

例如：如果您已經使用 Az 模組 6.3.0 所提供的 2.3.0 版匯入 Az.Aks 模組，而且您嘗試將 Az 模組更新為最新的 6.4.0 版。 更新作業會從 6.4.0 套件匯入所有 Az 模組，但 Az.Aks 除外。 若要擁有最新版的 Az.Aks，請先刪除現有的模組，然後執行更新作業，或者您也可以依照匯入 Az 模組所述，個別更新此模組以匯入不同版本的特定模組。

下表列出當您建立自動化帳戶時，Azure 自動化預設匯入的模組。 自動化可以匯入這些模組的較新版本。 不過，即使您刪除了較新版本，也無法從您的自動化帳戶移除原始版本。

預設模組也稱為全域模組。 在 Azure 入口網站中，檢視建立帳戶時匯入的模組時，全域模組屬性會是 true。

Screenshot of global module property in Azure Portal

注意

不建議您在用來部署停機期間啟動/停止 VM 的自動化帳戶中更改模組和 Runbook

模組名稱 版本
Az.* 如需完整清單，請參閱 PowerShell 資源庫的套件詳細資料
AuditPolicyDsc 1.1.0.0
Azure 1.0.3
Azure.Storage 1.0.3
AzureRM.Automation 1.0.3
AzureRM.Compute 1.2.1
AzureRM.Profile 1.0.3
AzureRM.Resources 1.0.3
AzureRM.Sql 1.0.3
AzureRM.Storage 1.0.3
ComputerManagementDsc 5.0.0.0
GPRegistryPolicyParser 0.2
Microsoft.PowerShell.Core 0
Microsoft.PowerShell.Diagnostics
Microsoft.PowerShell.Management
Microsoft.PowerShell.Security
Microsoft.PowerShell.Utility
Microsoft.WSMan.Management
Orchestrator.AssetManagement.Cmdlets 1
PSDscResources 2.9.0.0
SecurityPolicyDsc 2.1.0.0
StateConfigCompositeResources 1
xDSCDomainjoin 1.1
xPowerShellExecutionPolicy 1.1.0.0
xRemoteDesktopAdmin 1.1.0.0

內部 Cmdlet

Azure 自動化支援的內部 Cmdlet 只有當您在 Azure 沙箱環境或 Windows 混合式 Runbook 背景工作角色執行 Runbook 時才可以使用。 內部模組 Orchestrator.AssetManagement.Cmdlets 預設會安裝在您的自動化帳戶中，安裝時機為在電腦上安裝 Windows 混合式 Runbook 背景工作角色時。

下表定義內部 Cmdlet。 這些 Cmdlet 的設計目的是代替 Azure PowerShell Cmdlet，用來與自動化帳戶資源互動。 其可以從加密的變數、認證及加密的連線中擷取祕密。

名稱 描述
Get-AutomationCertificate Get-AutomationCertificate [-Name] <string> [<CommonParameters>]
Get-AutomationConnection Get-AutomationConnection [-Name] <string> [-DoNotDecrypt] [<CommonParameters>]
Get-AutomationPSCredential Get-AutomationPSCredential [-Name] <string> [<CommonParameters>]
Get-AutomationVariable Get-AutomationVariable [-Name] <string> [-DoNotDecrypt] [<CommonParameters>]
Set-AutomationVariable Set-AutomationVariable [-Name] <string> -Value <Object> [<CommonParameters>]
Start-AutomationRunbook Start-AutomationRunbook [-Name] <string> [-Parameters <IDictionary>] [-RunOn <string>] [-JobId <guid>] [<CommonParameters>]
Wait-AutomationJob Wait-AutomationJob -Id <guid[]> [-TimeoutInMinutes <int>] [-DelayInSeconds <int>] [-OutputJobsTransitionedToRunning] [<CommonParameters>]

請注意，內部 Cmdlet 的命名方式與 Az 和 AzureRM Cmdlet 不同。 內部 Cmdlet 名稱不會在名詞中包含 Azure 或 Az 之類的字組，但會使用 Automation 字組。 建議您在 Azure 沙箱或 Windows 混合式 Runbook 背景工作角色中執行 Runbook 期間這些 Cmdlet 而不是使用 Az 或 AzureRM Cmdlet，因為它們需要的參數較少且在執行期間可在您工作的內容中執行。

使用 Az 或 AzureRM Cmdlet 來操作 Runbook 內容以外的自動化資源。

Python 模組

您可以在 Azure 自動化中建立 Python 2 Runbook。 如需 Python 模組資訊，請參閱管理 Azure 自動化中的 Python 2 套件。

自訂模組

Azure 自動化支援您建立來搭配 Runbook 和 DSC 設定使用的自訂 PowerShell 模組。 其中一種自訂模組類型是整合模組，可選擇性地包含中繼資料的檔案來定義模組 Cmdlet 的自訂功能。 新增連線類型中提供整合模組的使用範例。

Azure 自動化可以匯入自訂模組，以使其 Cmdlet 可供使用。 就像其他模組一樣，其會在幕後儲存模組，並在 Azure 沙箱中加以使用。

移轉至 Az 模組

此節說明如何在自動化中移轉至 Az 模組。 如需詳細資訊，請參閱將 Azure PowerShell 從 AzureRM 移轉至 Az。

我們不建議在相同的自動化帳戶中執行 AzureRM 模組和 Az 模組。 當您確定要從 AzureRM 移轉至 Az 時，最好完全認可至完整移轉。 自動化通常會重複使用自動化帳戶內的沙箱，以節省啟動時間。 如果您未進行完整模組移轉，您可能會啟動僅使用 AzureRM 模組的作業，然後啟動另一個只使用 Az 模組的作業。 沙箱很快就會損毀，而您會收到錯誤，指出模組不相容。 這種情況會導致任何特定 Runbook 或設定隨機發生損毀。

注意

當您建立新的自動化帳戶時，即使是在移轉至 Az 模組之後，自動化仍會依預設安裝 AzureRM 模組。

模組移轉之前，先測試您的 Runbook 和 DSC 設定

移轉至 Az 模組之前，請務必謹慎地在個別自動化帳戶中測試所有 Runbook 和 DSC 設定。

停止並取消排程使用 AzureRM 模組的所有 Runbook

為了確保您不會執行任何使用 AzureRM 模組的現有 Runbook 或 DSC 設定，您必須停止並取消排程所有受影響的 Runbook 和設定。 首先，確定您會分別檢閱每個 Runbook 或 DSC 設定及其排程，以確保您可以在未來視需要重新排程項目。

當您準備好移除排程時，您可以使用 Azure 入口網站或 Remove-AzureRmAutomationSchedule \(英文\) Cmdlet。 請參閱移除排程。

移除 AzureRM 模組

您可以先移除 AzureRM 模組，然後再匯入 Az 模組。 不過，如果這樣做，您可能會中斷原始程式碼控制同步處理，並導致任何仍排定的指令碼失敗。 如果您決定移除模組，請參閱解除安裝 AzureRM。

匯入 Az 模組

在您的自動化帳戶中匯入 Az 模組，不會在 Runbook 使用的 PowerShell 工作階段中自動匯入該模組。 模組會在下列情況下匯入到 PowerShell 工作階段：

  • 當 Runbook 從模組中叫用 Cmdlet 時。
  • 當 Runbook 使用 Import-Module \(英文\) Cmdlet 明確匯入模組時。
  • 當 Runbook 使用 using module 陳述式明確匯入模組時。 從 Windows PowerShell 5.0 開始支援 using 陳述式，並支援類別和列舉類型匯入。
  • 當 Runbook 匯入另一個相依模組時。

您可以從 Azure 入口網站將 Az 模組匯入自動化帳戶。 由於 Az.Accounts \(英文\) 是其他 Az 模組的相依性，因此，務必在任何其他模組之前匯入此模組。

注意

隨著 PowerShell 7.1 (預覽) 支援的建立，[瀏覽資源庫] 選項已更新，且變更如下：

  • 瀏覽資源庫位於 [程序自動化]>[模組] 刀鋒視窗。
  • [模組] 頁面會顯示兩個新的資料行：[模組版本] 和 [執行階段版本]

  1. 登入 Azure 入口網站。

  2. 搜尋並選取 [自動化帳戶]。

  3. 在自動化帳戶分頁上，從清單中選取您的自動化帳戶。

  4. 從您的自動化帳戶中，選取 [共用資源] 下的 [模組]。

  5. 選取 [新增模組]。 在 [新增模組] 頁面中，您可以選取下列選項之一：

    1. 瀏覽檔案 - 從本機電腦中選取檔案。
    2. 瀏覽資源庫 - 您可以瀏覽資源庫並選取現有的模組。

  6. 按下 [選取] 以選取模組。

  7. 選取 [執行階段版本]，然後按下 [匯入]。

    Screenshot of importing modules into your Automation account.

  8. 在 [模組] 頁面上，您可以在自動化帳戶下檢視匯入的模組。

您也可以透過 PowerShell 資源庫 \(英文\)，藉由搜尋要匯入的模組來進行此匯入。 當您找到模組時，請加以選取，然後選擇 [Azure 自動化] 索引標籤。選取 [部署至 Azure 自動化]。

Screenshot of importing modules directly from PowerShell Gallery.

測試您的 Runbook

將 Az 模組匯入至自動化帳戶之後，您就可以開始編輯 Runbook 和 DSC 設定，以使用新的模組。 測試 Runbook 的修改以使用新 Cmdlet 的方式之一，是在 Runbook 開頭使用 Enable-AzureRmAlias -Scope Process 命令。 藉由將此命令新增至您的 Runbook，不需變更指令碼就可加以執行。

撰寫模組

當您撰寫自訂 PowerShell 模組以在 Azure 自動化中使用時，建議您遵循此節中的考慮事項。 若要準備要匯入的模組，您至少必須建立一個 psd1、psm1 或 PowerShell 模組 .dll 檔案，且名稱與模組資料夾相同。 然後壓縮模組資料夾，讓 Azure 自動化能夠以單一檔案形式匯入。 .zip 套件的名稱應該與內含的模組資料夾相同。

若要深入了解如何撰寫 PowerShell 模組，請參閱如何撰寫 PowerShell 指令碼模組 \(部分機器翻譯\)。

版本資料夾

PowerShell 並存模組版本設定可讓您在 PowerShell 中使用一個以上的模組版本。 如果您有經過測試且僅適用於特定 PowerShell 模組版本的舊版指令碼，這會非常有用，但其他指令碼需要較新版本的相同 PowerShell 模組。

若要建構 PowerShell 模組，使其包含多個版本，請建立模組資料夾，然後在此模組資料夾中為您想要使用的每個模組版本建立一個資料夾。 在下列範例中，名為 TestModule 的模組提供兩個版本：1.0.0 和 2.0.0。

TestModule
   1.0.0
   2.0.0

在每個版本資料夾中，將組成模組的 PowerShell .psm1、.psd1 或 PowerShell 模組 .dll 檔案複製到各自的版本資料夾中。 壓縮模組資料夾，讓 Azure 自動化能夠以單一 .zip 檔案形式匯入該資料夾。 雖然自動化只會顯示匯入模組的最高版本，但如果模組套件包含模組的並存版本，則全部可用於 Runbook 或 DSC 設定。

雖然自動化支援在相同套件內包含並存版本的模組，但不支援在模組套件匯入中使用多版本的模組。 例如，您將包含第 1 版和第 2 版的模組 A 匯入您的自動化帳戶。 稍後您更新模組 A 以包含第 3 版和第 4 版，當您匯入自動化帳戶時，在任何 Runbook 或 DSC 設定中只能使用第 3 版和第 4 版。 如果您需要能夠使用所有版本：1、2、3 和 4，則匯入的 .zip 檔案應包含版本 1、2、3 和 4。

如果您要在 Runbook 之間使用相同模組的不同版本，您應該一律使用 Import-Module Cmdlet 宣告要在 Runbook 中使用的版本，並包含參數 -RequiredVersion <version>。 即使您要使用的版本是最新版本也一樣。 這是因為 Runbook 作業可以在相同的沙箱中執行。 如果沙箱已明確載入特定版本號碼的模組，因為該沙箱中先前的作業表示要這麼做，因此該沙箱中的未來作業將不會自動載入該模組的最新版本。 這是因為該模組的某些版本已在沙箱中載入。

針對 DSC 資源，請使用下列命令來指定特定版本：

Import-DscResource -ModuleName <ModuleName> -ModuleVersion <version>

說明資訊

在您的模組中包含每個 Cmdlet 的概要、描述和說明 URI。 在 PowerShell 中，您可以使用 Get-Help Cmdlet 來定義 Cmdlet 的說明資訊。 下列範例示範如何在 .psm1 模組檔案中定義概要和說明 URI。

<#
     .SYNOPSIS
      Gets a Contoso User account
#>
function Get-ContosoUser {
[CmdletBinding](DefaultParameterSetName='UseConnectionObject', `
HelpUri='https://www.contoso.com/docs/information')]
[OutputType([String])]
param(
   [Parameter(ParameterSetName='UserAccount', Mandatory=true)]
   [ValidateNotNullOrEmpty()]
   [string]
   $UserName,

   [Parameter(ParameterSetName='UserAccount', Mandatory=true)]
   [ValidateNotNullOrEmpty()]
   [string]
   $Password,

   [Parameter(ParameterSetName='ConnectionObject', Mandatory=true)]
   [ValidateNotNullOrEmpty()]
   [Hashtable]
   $Connection
)

switch ($PSCmdlet.ParameterSetName) {
   "UserAccount" {
      $cred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $UserName, $Password
      Connect-Contoso -Credential $cred
   }
   "ConnectionObject" {
      Connect-Contoso -Connection $Connection
  }
}
}

提供此資訊，即可透過 PowerShell 主控台中的 Get-Help Cmdlet 來顯示說明文字。 此文字也會顯示於 Azure 入口網站中。

Screenshot of integration module help

連線類型

如果模組連線至外部服務，請使用自訂整合模組來定義連線類型。 模組中的每個 Cmdlet 都應該接受該連線類型的執行個體 (連線物件) 作為參數。 使用者會在每次呼叫 Cmdlet 時，將連線資產的參數對應至 Cmdlet 的對應參數。

Use a custom connection in the Azure portal

下列 Runbook 範例會使用名為 ContosoConnection 的 Contoso 連線資產來存取 Contoso 資源，並從外部服務傳回資料。 在此範例中，欄位會對應至 PSCredential 物件的 UserName 和 Password 屬性，然後傳遞給 Cmdlet。

$contosoConnection = Get-AutomationConnection -Name 'ContosoConnection'

$cred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $contosoConnection.UserName, $contosoConnection.Password
Connect-Contoso -Credential $cred
}

更容易且更好處理此行為的方式是直接將連線物件傳遞給 Cmdlet：

$contosoConnection = Get-AutomationConnection -Name 'ContosoConnection'

Connect-Contoso -Connection $contosoConnection
}

您可以透過讓 Cmdlet 能夠直接接受連線物件作為參數，而不是只接受連線欄位作為參數，來讓 Cmdlet 具有類似行為。 通常您會想要針對每個 Cmdlet 設定參數，讓未使用自動化的使用者可以呼叫 Cmdlet，而不需建構雜湊表作為連線物件。 UserAccount 參數集可用來傳遞連線欄位屬性。 ConnectionObject 則可讓您直接傳遞連線。

輸出類型

為模組中的所有 Cmdlet 定義輸出類型。 為 Cmdlet 定義輸出類型，可讓設計階段的 IntelliSense 在撰寫期間協助判斷 Cmdlet 的輸出屬性。 在撰寫圖形化 Runbook 期間，此練習特別有幫助，因為設計階段的知識是讓模組使用者獲得容易使用體驗的關鍵。

新增 [OutputType([<MyOutputType>])]，其中 MyOutputType 是有效的類型。 若要深入了解 OutputType，請參閱關於函式 OutputTypeAttribute。 下列程式碼是將 OutputType 新增至 Cmdlet 的範例：

function Get-ContosoUser {
[OutputType([String])]
param(
   [string]
   $Parameter1
)
# <script location here>
}

Screenshot of graphical runbook output type

此行為類似於 Cmdlet 在 PowerShell ISE 整合服務環境中輸出的「自動提示」功能，但不需加以執行。

Screenshot of POSH IntelliSense

Cmdlet 狀態

讓模組中的所有 Cmdlet 變成無狀態。 多個 Runbook 作業可以同時在同一個 AppDomain 以及相同的程序和沙箱中執行。 如果那些層級上有任何共用的狀態，則作業可能會互相影響。 這種行為可能導致間歇性且難以診斷的問題。 以下是不需進行的作業範例：

$globalNum = 0
function Set-GlobalNum {
   param(
       [int] $num
   )

   $globalNum = $num
}
function Get-GlobalNumTimesTwo {
   $output = $globalNum * 2

   $output
}

模組相依性

確定模組會完全包含於可使用 xcopy 複製的套件中。 自動化模組會在 Runbook 執行時，散發到自動化沙箱。 模組必須在其執行所在的主機以外單獨運作。

您應該能夠壓縮並移動模組套件，在將其匯入至另一部主機的 PowerShell 環境時，讓其能夠正常運作。 若要這樣做，請確定模組不會相依於在將模組匯入自動化時所壓縮之模組資料夾以外的任何檔案。

您的模組不應相依於主機上任何唯一的登錄設定。 範例是安裝產品時所進行的設定。

模組檔案路徑

確定模組中所有檔案的路徑均少於 140 個字元。 大小超過 140 個字元的路徑會導致匯入 Runbook 時發生問題。 自動化無法使用 Import-Module，將路徑大小超過 140 個字元的檔案匯入至 PowerShell 工作階段。

匯入模組

此節定義數種方式，可讓您將模組匯入至您的自動化帳戶。

在 Azure 入口網站中匯入模組

在 Azure 入口網站中匯入模組：

  1. 在入口網站中，搜尋並選取 [自動化帳戶]。
  2. 在自動化帳戶分頁上，從清單中選取您的自動化帳戶。
  3. 在 [共用資源] 底下，選取 [模組]。
  4. 選取 [新增模組]。
  5. 選取包含您模組的 .zip 檔案。
  6. 選取 [確定] 以開始匯入程序。

使用 PowerShell 匯入模組

您可以使用 New-AzAutomationModule \(英文\) Cmdlet，將模組匯入至您的自動化帳戶。 此 Cmdlet 會取得模組 .zip 套件的 URL。

New-AzAutomationModule -Name <ModuleName> -ContentLinkUri <ModuleUri> -ResourceGroupName <ResourceGroupName> -AutomationAccountName <AutomationAccountName>

您也可以使用相同的 Cmdlet，直接從 PowerShell 資源庫匯入模組。 請務必從 PowerShell 資源庫 \(英文\) 擷取 ModuleName 和 ModuleVersion。

$moduleName = <ModuleName>
$moduleVersion = <ModuleVersion>
New-AzAutomationModule -AutomationAccountName <AutomationAccountName> -ResourceGroupName <ResourceGroupName> -Name $moduleName -ContentLinkUri "https://www.powershellgallery.com/api/v2/package/$moduleName/$moduleVersion"

您可以直接從資源庫或您的自動化帳戶匯入 PowerShell 資源庫 \(英文\) 模組。

直接從 PowerShell 資源庫匯入模組：

  1. 移至 https://www.powershellgallery.com，然後搜尋要匯入的模組。
  2. 在 [安裝選項] 下方的 [Azure 自動化] 索引標籤中，選取 [部署至 Azure 自動化]。 此動作會開啟 Azure 入口網站。
  3. 在 [匯入] 頁面上，選取您的自動化帳戶，然後選取 [確定]。

Screenshot of the PowerShell Gallery import module

直接從您的自動化帳戶匯入 PowerShell 資源庫模組：

  1. 在入口網站中，搜尋並選取 [自動化帳戶]。
  2. 在自動化帳戶分頁上，從清單中選取您的自動化帳戶。
  3. 在 [共用資源] 底下，選取 [模組]。
  4. 選取 [瀏覽資源庫]，然後在資源庫中搜尋模組。
  5. 選取要匯入的模組，然後選取 [匯入]。
  6. 選取 [確定] 以開始匯入程序。

Screenshot of importing a PowerShell Gallery module from the Azure portal

刪除模組

如果您遇到有關模組的問題，或需要復原為舊版模組，您可以從自動化帳戶中將其刪除。 當您建立自動化帳戶時，就無法刪除已匯入的預設模組原始版本。 如果要刪除的模組是其中一個預設模組的較新版本，則會復原為隨您的自動化帳戶一起安裝的版本。 否則，會移除您從自動化帳戶中刪除的任何模組。

在 Azure 入口網站中刪除模組

在 Azure 入口網站中移除模組：

  1. 在入口網站中，搜尋並選取 [自動化帳戶]。
  2. 在自動化帳戶分頁上，從清單中選取您的自動化帳戶。
  3. 在 [共用資源] 底下，選取 [模組]。
  4. 選取您想要移除的模組。
  5. 在 [模組] 頁面上，選取 [刪除]。 如果此模組是其中一個預設模組，則其會復原為建立自動化帳戶時就已存在的版本。

使用 PowerShell 刪除模組

若要透過 PowerShell 移除模組，請執行下列命令：

Remove-AzAutomationModule -Name <moduleName> -AutomationAccountName <automationAccountName> -ResourceGroupName <resourceGroupName>

下一步