共用方式為

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

  • 發行項
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 系統管理員模組。 Az 模組可以安裝在 Windows、macOS 和 Linux 平台上。

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

如果您想安裝適用於 Azure Stack Hub 的 PowerShell 資源模組 (AzureRM 模組)，請參閱安裝適用於 Azure Stack Hub 的 PowerShell AzureRM 模組。

重要

不會有新的 Azure 資源模組模組版本。 有重大修正時，才會支援 Azure 資源模組。 接下來，Azure Stack Hub 只會有 Az 版本。

您可以使用 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 模組。 本文會引導您執行這些案例的詳細指示。

1.驗證您的必要條件

Az 模組支援 Azure Stack Hub (含更新 2002 或更新版本)，並已安裝最新 Hotfix。 如需詳細資訊，請參閱 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。 從提升權限的提示字元中執行下列 Cmdlet：

    [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

2.Linux 和 Mac 的必要條件

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

3.解除安裝現有的 Azure Stack Hub PowerShell 模組版本

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

  1. 若要將現有的 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

    若您遇到「模組已在使用中」之類的錯誤，請關閉正在使用模組的 PowerShell 工作階段，然後重新執行上面的指令碼。

  2. 如果 Uninstall-Module 失敗，請從 $env:PSModulePath 位置刪除以 Azure、Az 或 Azs. 開頭的所有資料夾。 若是 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 模組。

4.已連線：透過網際網路連線安裝

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

    Install-Module -Name AzureStack -RequiredVersion 2.3.0

    Install-Module -Name AzureStack -RequiredVersion 2.2.0

    Install-Module -Name AzureStack -RequiredVersion 2.1.1

警告

您無法同時為適用於 Windows 的 PowerShell 5.1 安裝 Azure Resource Manager (AzureRM) 和 Az 模組。 如果您需要確保可在系統上使用 Azure Resource Manager，請安裝適用於 PowerShell Core 6.x 或更新版本的 Az 模組。 若要這樣做，請安裝 PowerShell Core 6.x 或更新版本，然後在 PowerShell Core 終端機中依照這些指示操作。

5.已中斷連線：在沒有網際網路連線的情況下安裝

在中斷連線的情況下，您必須先將 PowerShell 模組下載至具有網際網路連線能力的電腦。 然後，將它們傳輸至 Azure Stack 開發套件 (ASDK) 進行安裝。

登入具有網際網路連線能力的電腦，然後根據您的 Azure Stack Hub 版本，使用下列指令碼下載 Azure Resource Manager 和 Azure Stack Hub 套件。

安裝有五個步驟：

  1. 將 Azure Stack Hub PowerShell 安裝至已連線的電腦。
  2. 啟用其他儲存體功能。
  3. 將 PowerShell 套件傳輸到已中斷連線的工作站。
  4. 在中斷連線的工作站中，手動啟動 NuGet 提供者。
  5. 確認 PowerShell 的安裝。

安裝 Azure Stack Hub PowerShell

  1. 您可以使用 AzureRM 或 Az 模組。 下列程式代碼會從可信任的在線存放庫 https://www.powershellgallery.com/儲存 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

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

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

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

注意

在沒有網際網路連線的電腦上，建議您執行下列 Cmdlet 以停用遙測資料收集。 若未停用遙測資料收集，可能會發生 Cmldet 效能降低的狀況。 不具網際網路連線的電腦才有可能發生此狀況

Disable-AzDataCollection

將您的套件新增至您的工作站

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

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

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

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

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

確認 PowerShell 的安裝

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

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

6.設定 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

7.使用 Az 模組

您可以根據 AzureRM 模組使用 Cmdlet 和程式代碼範例。 不過，您應該變更模組和 Cmdlet 的名稱。 模組名稱已變更，所以 AzureRM 和 Azure 會成為 Az，而 Cmdlet 也是如此。 例如，AzureRM.Compute 模組已重新命名為 Az.Compute。 New-AzureRMVM 已成為 New-AzVM，而 Get-AzureStorageBlob 現在為 Get-AzStorageBlob。

如需在 Azure Stack Hub 的 Az 模組中，將 AzurRM 指令碼移至 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. Accounts 模組。
  • 發生次數：通用

使用 2020-09-01-hybrid 設定檔時，Cmdlet New-AzVmss 失敗

  • 適用於：此問題適用於 2020-09-01-hybrid 設定檔。
  • 原因：Cmdlet New-AzVmss 無法與 2020-09-01-hybrid 設定檔搭配使用。
  • 補救：使用範本來建立虛擬機器擴展集。 您可以在 GitHub 存放庫中找到 Azure Stack Hub Resource Manager 範本的範例 AzureStack-QuickStart-Templates/101-vmss-windows-vm，且您可以找到搭配 Visual Studio Code 使用 Azure Stack Hub Resource Manager 的指示。
  • 發生次數：通用

執行 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 AzureRM 模組的 PowerShell Az 模組。 如果您嘗試在安裝 Az 模組之後執行呼叫 AzureRM 命令的指令碼，則指令碼將會擲回錯誤。 或者，如果您嘗試在安裝 AzureRM 模組之後執行呼叫 Az 命令的指令碼，則指令碼將會擲回錯誤。

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

  • 發生次數：通用

使用 New-AzADServicePrincipal 和 New-AzADApplication 時擲回錯誤

  • 適用：使用 Microsoft Entra ID 的 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。 使用下列 Cmdlet：

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

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

    • 建立提供有效 IdentifierUri Microsoft Entra 應用程式，然後使用下列 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 版。
  • 發生次數：通用

後續步驟