在 Azure 自動化中管理模組

Azure 自動化會使用數個 PowerShell 模組,在 DSC 組態中啟用 Runbook 和 DSC 資源中的 Cmdlet。 支援的模組包括:

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

沙箱

當自動化執行 Runbook 和 DSC 編譯作業時,它會將模組載入到可執行 Runbook 的沙箱中,而 DSC 組態可以編譯。 自動化也會自動將任何 DSC 資源放在 DSC 提取伺服器上的模組中。 機器可以在套用 DSC 設定時提取資源。

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

由於包含的模組和 Cmdlet 數目,因此很難事先知道哪些 Cmdlet 會進行不支援的呼叫。 一般而言,我們發現需要提高存取權、需要認證做為參數的 Cmdlet 或與網路相關的 Cmdlet 的問題。 沙箱中不支援執行完整堆疊網路作業的任何 Cmdlet,包括 AIPService PowerShell 模組中的 連線-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.Aks 使用 Az module 6.3.0 所提供的 2.3.0 版匯入模組,而且您嘗試將 Az 模組更新為最新的 6.4.0 版本。 更新作業會從 6.4.0 套件匯入所有 Az 模組,但 除外 Az.Aks 。 若要擁有最新版本 Az.Aks ,請先刪除現有的模組,然後執行更新作業,或者您也可以依照匯入 Az 模組 中所述 個別更新此模組,以匯入不同版本的特定模組。

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

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

Screenshot of global module property in Azure Portal

注意

我們不建議在自動化帳戶中變更模組和 Runbook,以用於在停機 期間部署 啟動/停止 VM 的功能。

模組名稱 版本
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 自動化支援只能在 Azure 沙箱環境中或 Windows 混合式 Runbook 背景工作角色上執行 Runbook 時,才可用的內部 Cmdlet。 內部模組 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 名稱不會在名詞中包含類似 AzureAz 的字組,但會使用 這個字 Automation 。 建議您在 Azure 沙箱或 Windows 混合式 Runbook 背景工作角色的 Runbook 執行期間使用 Az 或 AzureRM Cmdlet,因為它們需要較少的參數,並在執行期間于作業的內容中執行。

使用 Az 或 AzureRM Cmdlet 在 Runbook 內容之外操作自動化資源。

Python 模組

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

自訂模組

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

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

移轉至 Az 模組

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

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

注意

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

在模組移轉之前測試 Runbook 和 DSC 設定

請務必先在個別自動化帳戶中仔細測試所有 Runbook 和 DSC 設定,再移轉至 Az 模組。

停止並取消排程使用 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 組態以使用新的模組。 測試使用新 Cmdlet 的 Runbook 修改方式之一,是在 Runbook 開頭使用 Enable-AzureRmAlias -Scope Process 命令。 藉由將此命令新增至您的 Runbook,腳本即可執行,而不需要變更。

撰寫模組

當您撰寫自訂 PowerShell 模組以用於Azure 自動化時,建議您遵循本節中的考慮。 若要準備要匯入的模組,您必須至少建立與模組資料夾同名的 .psd1、.psm1 或 PowerShell 模組 .dll 檔案。 然後您壓縮模組資料夾,讓Azure 自動化可以匯入為單一檔案。 .zip 套件的名稱應該與自主模組資料夾相同。

若要深入瞭解撰寫 PowerShell 模組,請參閱 如何撰寫 PowerShell 腳本模組

Version 資料夾

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 組態。

雖然自動化支援在相同套件內包含並存版本的模組,但它不支援跨模組套件匯入使用模組的多個版本。 例如,您會將模組 A 入,其中包含第 1 版和第 2 版至您的自動化帳戶。 稍後您會更新 模組 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 的 Synopsis、描述和說明 URI。 在 PowerShell 中,您可以使用 Cmdlet 來定義 Cmdlet 的說明 Get-Help 資訊。 下列範例示範如何在 .psm1 模組檔案中 定義 Synopsis 和說明 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
  }
}
}

提供這項資訊會顯示透過 Get-Help PowerShell 主控台中的 Cmdlet 解說文字。 此文字也會顯示在Azure 入口網站中。

Screenshot of integration module help

Connection type

如果模組連線到外部服務,請使用 自訂整合模組 來定義連線類型。 模組中的每個 Cmdlet 都應該接受該連線類型 (connection object) 的實例做為參數。 使用者每次呼叫 Cmdlet 時,都會將連接資產的參數對應至 Cmdlet 的對應參數。

Use a custom connection in the Azure portal

下列 Runbook 範例會使用名為 ContosoConnection 的 Contoso 連線資產來存取 Contoso 資源,並從外部服務傳回資料。 在此範例中,欄位會對應至 UserName 物件的 和 Password 屬性 PSCredential ,然後傳遞至 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,而不需要建構雜湊表來做為連線物件。 參數集 UserAccount 是用來傳遞連接欄位屬性。 ConnectionObject 可讓您直接傳遞連線。

輸出類型

定義模組中所有 Cmdlet 的輸出類型。 定義 Cmdlet 的輸出類型可讓設計階段 IntelliSense 協助在撰寫期間判斷 Cmdlet 的輸出屬性。 在圖形化 Runbook 撰寫期間,這種做法特別有用,設計階段知識是您課程模組輕鬆使用者體驗的關鍵。

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

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

Screenshot of graphical runbook output type

此行為類似于 PowerShell 整合服務環境中 Cmdlet 輸出的「提前類型」功能,而不需要執行它。

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 資源庫 抓取 ModuleVersion 擷取 ModuleName

$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>

下一步