安裝適用於 Azure Stack Hub 的 PowerShell Az 和 Azure Stack 模組

這很重要

所有版本的 Azure Resource Manager （AzureRM） PowerShell 模組都已過期且不支援。 Az PowerShell 模組現在是建議的 PowerShell 模組，可與 Azure 和 Azure Stack Hub 互動。 本文說明如何開始使用 Az PowerShell 模組。 如需如何移轉至 Az PowerShell 模組的資訊，請參閱 從 AzureRM 遷移至 Azure Stack Hub 中的 Azure PowerShell Az。 如需跨全域 Azure 採用的 Az 模組功能增加的詳細資訊，請參閱 Azure Az PowerShell 模組簡介。

Azure Stack Hub 版本	AzureStack PowerShell 版本
2102	2.1.1
2108	2.2.0
2206	2.3.0
2301+	2.4.0

如需 AzureStack 模組的詳細資訊，請參閱 PSGallery。

本文說明如何使用 PowerShellGet 安裝 Azure PowerShell Az 和相容的 Azure Stack Hub 系統管理員模組。 您可以在 Windows、macOS 和 Linux 平台上安裝 Az 模組。

您也可以在 Docker 容器中執行適用於 Azure Stack Hub 的 Az 模組。 如需指示，請參閱 使用 Docker 執行適用於 Azure Stack Hub 的 PowerShell。

您可以使用 API 設定檔 來指定 Azure Stack Hub 資源提供者的相容端點。 API 設定檔可讓您管理 Azure 與 Azure Stack Hub 之間的版本差異。 API 版本設定檔是一組具有特定 API 版本的 Azure Resource Manager PowerShell 模組。 每個雲端平臺都有一組支援的 API 版本設定檔。 例如，Azure Stack Hub 支援特定的配置檔版本 ，例如 2020-09-01-hybrid。 當您安裝配置檔時，會安裝對應至指定配置檔的 Azure Resource Manager PowerShell 模組。

您可以在因特網連線、部分連線或已中斷連線的案例中安裝與 Azure Stack Hub 相容的 PowerShell Az 模組。 本文將逐步指導您完成這些情境的詳細指示。

確認您的必要條件

Az 模組在 Azure Stack Hub 上支援 2002 或更新版本的更新，並且已安裝所有現行修正程式。 如需詳細資訊，請參閱 Azure Stack Hub 版本資訊 。

Azure PowerShell Az 模組適用於 Windows 上的 PowerShell 5.1 或更高版本，以及所有平臺上的 PowerShell Core 6.x 和更新版本。 您應該安裝適用於您作業系統的最新版本 PowerShell Core 。 在 PowerShell Core 上執行時，Azure PowerShell 沒有其他需求。

若要檢查 PowerShell 版本，請執行下列命令：

$PSVersionTable.PSVersion

Windows 的必要條件

若要在 Windows 上的 PowerShell 5.1 中使用 Azure PowerShell：

1. 視需要更新至 Windows PowerShell 5.1 。 如果您是在 Windows 10 上，則已安裝 PowerShell 5.1。

2. 安裝 .NET Framework 4.7.2 或更新版本。

3. 請確定您有最新版的PowerShellGet。 從具備提升權限的命令提示字元執行以下指令集：

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   
   powershell -noprofile
   $PSVersionTable
   Uninstall-Module PowershellGet -AllVersions -Force -Confirm:$false
   Get-module PowershellGet
   Find-module PowershellGet
   Install-Module PowershellGet -MinimumVersion 2.2.3 -Force
   

Linux 和 Mac 的必要條件

需要 PowerShell Core 6.x 或更新版本。 請遵循 連結 以取得指示。

卸載現有的 Azure Stack Hub PowerShell 模組版本

安裝必要版本之前，請確定您卸載任何先前安裝的 Azure Stack Hub Azure Resource Manager 或 Az PowerShell 模組。 使用下列兩種方法之一卸載模組：

• 若要卸載現有的 Azure Resource Manager 和 Az PowerShell 模組，請關閉所有作用中的 PowerShell 會話，然後執行下列 Cmdlet：

  Get-Module -Name Azure* -ListAvailable | Uninstall-Module -Force -Verbose -ErrorAction Continue
  Get-Module -Name Azs.* -ListAvailable | Uninstall-Module -Force -Verbose -ErrorAction Continue
  Get-Module -Name Az.* -ListAvailable | Uninstall-Module -Force -Verbose -ErrorAction Continue
  

  如果您遇到「模組已使用中」之類的錯誤，請關閉使用模組並重新執行這些 Cmdlet 的 PowerShell 會話。

• 如果Uninstall-Module失敗，請從位置刪除以 Azure、Az 或 Azs 開頭的所有資料夾。$env:PSModulePath 針對 Windows PowerShell，位置可能是 C:\Program Files\WindowsPowerShell\Modules 和 C:\Users\{yourusername}\Documents\WindowsPowerShell\Modules。 針對 PowerShell Core，位置可能是 C:\Program Files\PowerShell\7\Modules 和 C:\Users\{yourusername}\Documents\PowerShell\Modules。 刪除這些資料夾會移除任何現有的 Azure PowerShell 模組。

已連線：使用因特網連線進行安裝

Azure Stack Az 模組適用於 Windows 電腦上的 PowerShell 5.1 或更新版本，或 Linux 或 macOS 平臺上的 PowerShell 6.x 或更新版本。 使用 PowerShellGet Cmdlet 是慣用的安裝方法。 此方法在支持的平臺上的運作方式相同。

1. 從 PowerShell 會話執行下列命令，將 PowerShellGet 更新為最低 2.2.3 版：

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   Install-Module PowerShellGet -MinimumVersion 2.2.3 -Force
   

2. 關閉 PowerShell 會話，然後開啟新的 PowerShell 工作階段，讓更新生效。

3. 執行下列命令以安裝 Az 模組：

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   Install-Module -Name Az.BootStrapper -Force
   Install-AzProfile -Profile 2020-09-01-hybrid -Force
   

4. 安裝 AzureStack PowerShell 模組：

   Install-Module -Name AzureStack -RequiredVersion 2.4.0
   

已中斷連線：在沒有因特網連線的情況下安裝

在中斷連線的案例中，您會先將PowerShell模組下載到具有因特網連線的電腦。 然後，您會將它們傳輸至 Azure Stack 開發工具套件 （ASDK） 進行安裝。

登入具有因特網連線的計算機，並使用下列腳本來下載 Azure Resource Manager 和 Azure Stack Hub 套件，視您的 Azure Stack Hub 版本而定。

安裝有五個步驟：

1. 在連線的電腦上安裝 Azure Stack Hub PowerShell。
2. 啟用其他記憶體功能。
3. 將 PowerShell 套件傳輸至已中斷連線的工作站。
4. 在沒有網路連線的工作站上手動初始化 NuGet 提供程式。
5. 確認 PowerShell 的安裝。

安裝 Azure Stack Hub PowerShell

1. 下列程式代碼會從 可信任的線上存放庫安裝 Az 模組：

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   Install-module -Name PowerShellGet -MinimumVersion 2.2.3 -Force
   Import-Module -Name PackageManagement -ErrorAction Stop
   $savedModulesPath = "<Path that is used to save the packages>"
   Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name Az -Path $savedModulesPath -Force -RequiredVersion 2.0.1
   

2. 安裝 Az 模組之後，請繼續安裝 AzureStack 模組：

   Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureStack -Path $savedModulesPath -Force -RequiredVersion 2.4.0
   

備註

在沒有因特網連線的機器上，建議您執行 Disable-AzDataCollection Cmdlet 來停用遙測數據收集。 否則，您可能會遇到 Cmdlet 效能降低的情況。 這隻適用於沒有因特網連線的計算機。

將套件新增至工作站

1. 將下載的套件複製到 USB 裝置。

2. 登入已中斷連線的工作站，並將套件從USB裝置複製到工作站上的位置。

3. 在沒有網路連線的工作站上手動初始化 NuGet 提供程式。 如需指示，請參閱 在未連線到網路的電腦上手動引導 NuGet 提供者。

4. 將此位置註冊為預設存放庫，並從此存放庫安裝 AzureRM 和 AzureStack 模組：

    # requires -Version 5
    # requires -RunAsAdministrator
    # requires -Module PowerShellGet
    # requires -Module PackageManagement
   
    $SourceLocation = "<Location on the development kit that contains the PowerShell packages>"
    $RepoName = "MyNuGetSource"
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
    Register-PSRepository -Name $RepoName -SourceLocation $SourceLocation -InstallationPolicy Trusted
   

5. 安裝 Az 模組。

    Install-Module -Name Az -Repository $RepoName -RequiredVersion 2.0.1 -Scope AllUsers
   

6. 安裝 AzureStack 模組L

   Install-Module -Name AzureStack -Repository $RepoName -RequiredVersion 2.4.0 -Scope AllUsers
   

確認 PowerShell 的安裝

執行下列命令來確認安裝：

Get-Module -Name "Az*" -ListAvailable
Get-Module -Name "Azs*" -ListAvailable

將 PowerShell 設定為使用 Proxy 伺服器

在需要 Proxy 伺服器存取因特網的案例中，您必須先將 PowerShell 設定為使用現有的 Proxy 伺服器：

1. 開啟提升權限的 PowerShell 提示符號。

2. 執行以下命令：

   #To use Windows credentials for proxy authentication
   [System.Net.WebRequest]::DefaultWebProxy.Credentials = [System.Net.CredentialCache]::DefaultCredentials
   
   #Alternatively, to prompt for separate credentials that can be used for #proxy authentication
   [System.Net.WebRequest]::DefaultWebProxy.Credentials = Get-Credential
   

使用 Az 模組

您仍然可以使用以 AzureRM 模組為基礎的 Cmdlet 和程式代碼範例。 不過，您必須變更模組和 Cmdlet 的名稱。 模組名稱已變更，因此 AzureRM Azure 會變成 Az，而且 Cmdlet 也是如此。 例如，模組 AzureRM.Compute 已重新命名為 Az.Compute。 New-AzureRMVM 是 New-AzVM，而 Get-AzureStorageBlob 現在是 Get-AzStorageBlob。

如需將 AzureRM 腳本移至 Az 的更深入討論和指引，以及 Azure Stack Hub Az 模組中重大變更的相關信息，請參閱 從 AzureRM 遷移至 Azure PowerShell Az。

已知問題

安裝 Az 模組時擲回的錯誤

• 適用：此問題適用於 2002 和更新版本
• 原因：安裝模組時，會發生錯誤。 錯誤訊息開始： Register-PacakgeSource : A parameter cannot be found that matches parameter name. 'PackageManagementProvider'. 或錯誤訊息可能包含下列文字： PackageManagement\Install-Package : Cannot convert value "2.0.1-preview" to type "System.Version". Error: "Input string was not in a correct format."
• 補救：在相同的會話中執行下列 cmdlet：
  Install-Module PowershellGet -MinimumVersion 2.3.0 -Force
  關閉您的會話，然後啟動新的提升許可權的 PowerShell 會話。
• 發生次數：一般

安裝 Az 模組時，錯誤地顯示需要系統管理員權限的訊息。

• 適用：此問題適用於 2002 和更新版本
• 原因：從提升許可權的提示字元安裝模組時，會發生錯誤。 錯誤說： Administrator rights required。
• 補救：關閉您的會話，並啟動新的提升許可權的 PowerShell 會話。 請確認沒有現有的 Az。 在工作階段中載入的帳戶模組。
• 發生次數：一般

使用 2020-09-01-hybrid 配置檔時，Cmdlet New-AzVmss 失敗

• 適用：此問題適用於 2020-09-01-hybrid 配置檔。
• 原因： Cmdlet New-AzVmss 不適用於 2020-09-01-hybrid 配置檔。
• 整改措施：使用範本來創建虛擬機擴展集。 您可以在 GitHub 存放庫 AzureStack-QuickStart-Templates/101-vmss-windows-vm 中找到 Azure Stack Hub Resource Manager 範例，您可以找到搭配 Visual Studio Code 使用 Azure Stack Hub 資源管理員的指示。
• 發生次數：一般

執行 PowerShell 腳本時擲回的錯誤

• 適用：此問題適用於 2002 和更新版本。

• 原因：使用 Azure Stack Hub 特定模組執行腳本或 PowerShell 命令時，您需要在模組中提供您的腳本或命令。 您可能會看到下列錯誤：

  Method 'get_SerializationSettings' in type 'Microsoft.Azure.Management.Internal.Resources.ResourceManagementClient' from assembly 'Microsoft.Azure.Commands.ResourceManager.Common, Version=4.0.0.0, 
  Culture=neutral, PublicKeyToken=31bf3856ad364e35' does not have an implementation.
  

  目前的模組是 PowerShell Az 模組，已取代 PowerShell AzureRM 模組。 如果您嘗試在安裝 Az 模組時執行呼叫 AzureRM 命令的腳本，您的腳本將會擲回錯誤。 或者，如果您嘗試在安裝 AzureRM 模組時執行呼叫 Az 命令的腳本，您的腳本將會擲回錯誤。

• 補救：卸載 AzureRM 模組並安裝 Az 模組。 如需指示，請參閱 安裝適用於 Azure Stack Hub 的 PowerShell Az 模組。 如果您使用 Azure Stack Hub 工具，請使用 Az 工具。 從 az 分支複製工具存放庫，或從 az branch 下載 AzureStack-Tools。 如需指示，請參閱 從 GitHub 下載 Azure Stack Hub 工具

• 發生次數：一般

使用 New-AzADServicePrincipal 和 New-AzADApplication 丟出的錯誤

• 適用：使用 Microsoft Entra 識別符的 Azure Stack 環境。

• 原因：Azure Active Directory Graph 引入了不兼容變更，限制 Active Directory 應用程式的 IdentifierUri 必須是目錄中已驗證網域的子域。 變更之前，此限制只會針對多租使用者應用程式強制執行。 現在此限制也適用於單一租用戶應用程式。 變更會導致下列錯誤： Values of identifierUris property must use a verified domain of the organization or its subdomain' is displayed when running。

• 補救：您可以透過兩種方式解決這項限制。

  • 您必須使用服務主體名稱，此名稱是目錄租使用者的子域。 例如，如果目錄是 contoso.onmicrosoft.com，服務主體名稱必須是 的格式 <foo>.contoso.onmicrosoft.com。 使用下列指令集：

    New-AzADServicePrincipal -Role Owner -DisplayName <foo>.contoso.onmicrosoft.com
    

    如需身分識別及搭配 Azure Stack Hub 使用服務主體的詳細資訊，請參閱 Azure Stack Hub 的身分識別提供者概觀。

  • 首先，建立 Microsoft Entra 應用程式並提供有效的 IdentifierUri，然後使用下列 Cmdlet 建立服務主體，並將其與應用程式關聯。

    $app=New-AzADApplication -DisplayName 'newapp' -IdentifierUris http://anything.contoso.onmicrosoft.com
    New-AzADServicePrincipal -Role Owner -ApplicationId $app.ApplicationId
    

• 發生次數：一般

錯誤：「SharedTokenCacheCredential 驗證失敗」

• 適用：此問題適用於所有支援的版本。
• 原因：使用 Azure Stack Hub PowerShell 模組 2.1.1 版安裝多個 AzAccounts 版本時，會擲回 SharedTokenCacheCredential 驗證失敗錯誤。
• 補救：移除所有 AzAccounts 版本，並只安裝支援的 AzAccounts 2.2.8 版。
• 發生次數：一般

後續步驟

• 從 GitHub 下載 Azure Stack Hub 工具
• 設定 Azure Stack Hub 使用者的 PowerShell 環境
• 設定 Azure Stack Hub作員的 PowerShell 環境
• 在 Azure Stack Hub 中管理 API 版本設定檔