在 Azure Stack Hub 中從 AzureRM 移轉至 Azure PowerShell Az

發行項
12/01/2023

Az 模組有 AzureRM 的功能同位，但是會使用比較短且更一致的 Cmdlet 名稱。針對 AzureRM Cmdlet 撰寫的指令碼不會自動使用新模組。為了更輕鬆進行轉換，Az 提供一些工具，讓您使用 AzureRM 執行現有的指令碼。不移轉移到新命令集當然很方便，但本文將會協助您開始轉換到新的模組。

若要查看 AzureRM 和 Az 之間重大變更的完整清單，請參閱 Az 1.0.0 的移轉指南

檢查所安裝的 AzureRM 版本

在採取任何移轉步驟之前，請先檢查系統上安裝了哪些版本的 AzureRM。進行檢查可讓您確定指令碼是在最新的版本上執行，而且可讓您知道您是否可以啟用命令別名而不必解除安裝 AzureRM。

若要檢查您所安裝的 AzureRM 版本，請執行下列命令：

Get-InstalledModule -Name AzureRM -AllVersions

檢查 AzureRM 目前使用的指令碼

這是最重要的步驟！執行現有指令碼，並確保其能使用「最新」版的 AzureRM (2.5.0)。如果指令碼沒有作用，請務必閱讀 AzureRM 移轉指南。

安裝 Azure PowerShell Az 模組

第一個步驟是在您的平台上安裝 Az 模組。當您安裝 Az 時，建議您先解除安裝 AzureRM。在下列步驟中，您將了解如何繼續執行現有的指令碼，並且讓舊的 Cmdlet 名稱相容。

若要安裝 Azure PowerShell Az 模組，請遵循下列步驟：

建議：將 AzureRM 模組解除安裝。務必移除 AzureRM 的「所有」安裝版本，而不只是最近版本。
安裝 Az 模組

啟用 AzureRM 相容性別名

重要

在解除安裝「所有」AzureRM 版本後，才可啟用相容性模式。在 AzureRM Cmdlet 仍可使用的情況下啟用相容性模式，可能會導致無法預期的行為。如果您決定讓 AzureRM 繼續保持安裝狀態，請略過此步驟，但請注意所有 AzureRM Cmdlet 均會使用較舊的模組，而不會呼叫任何 Az Cmdlet。

在 AzureRM 已解除安裝且指令碼使用最新 AzureRM 版本的情況下，下一個步驟是啟用 Az 模組的相容性模式。透過以下命令啟用相容性：

Enable-AzureRmAlias -Scope CurrentUser

別名讓您能夠使用舊的 Cmdlet 名稱搭配已安裝的 Az 模組。這些別名會寫入至所選範圍的使用者設定檔。如果沒有使用者設定檔存在，則會建立一個。

警告

您可以將不同的 -Scope 使用於這個命令，但不建議這麼做。別名會寫入至所選範圍的使用者設定檔，所以儘可能在有限範圍內啟用別名。全系統啟用別名，也會對在其本機範圍內安裝 AzureRM 的其他使用者造成問題。

啟用別名模式後，再次執行指令碼以確認它們仍然運作正常。

變更模組和 Cmdlet 名稱

一般情況下，模組名稱已變更，所以 AzureRM 和 Azure 會成為 Az，而 Cmdlet 也是如此。例如，AzureRM.Compute 模組已重新命名為 Az.Compute。 New-AzureRMVM 已成為 New-AzVM，而 Get-AzureStorageBlob 現在為 Get-AzStorageBlob。

此命名變更有一些應該留意的例外狀況。某些模組已重新命名或合併到現有模組，但這不會影響其 Cmdlet 的尾碼，而只會將 AzureRM 或 Azure 變更為 Az。否則，便會變更完整的 Cmdlet 尾碼以反映新的模組名稱。

AzureRM 模組	Az 模組	Cmdlet 尾碼有變更嗎？
AzureRM.Profile	Az.Accounts	Yes
AzureRM.Insights	Az.Monitor	Yes
AzureRM.Tags	Az.Resources	No
AzureRM.UsageAggregates	Az.Billing	No
AzureRM.Consumption	Az.Billing	No

總結

依照下列步驟，您可以將所有現有的指令碼更新為使用新模組。如果您對於讓移轉變困難的這些步驟有任何疑問或問題，請對本文發表意見，以便我們改進指示。

Az 1.0.0 的重大變更

本文件詳細說明 AzureRM 6.x 與新的 Az 模組 1.x 版和更新版本之間的變更。目錄有助於引導您進行完整移轉路徑，包括可能會對您的指令碼產生影響的模組特有變更。

一般重大變更

本節將詳細說明 Az 模組的重新設計中包含的一般重大變更。

Cmdlet 名詞前置詞的變更

在 AzureRM 模組中，Cmdlet 使用 AzureRM 或 Azure 作為名詞前置詞。 Az 則將 Cmdlet 名稱予以簡化和標準化，讓所有 Cmdlet皆使用 'Az' 作為其 Cmdlet 名詞前置詞。例如：

Get-AzureRMVM
Get-AzureKeyVaultSecret

已變更為：

Get-AzVM
Get-AzKeyVaultSecret

為了讓您更輕鬆地轉為使用這些新的 Cmdlet 名稱，Az 導入了兩個新的 Cmdlet，即 Enable-AzureRmAlias 和 Disable-AzureRmAlias。 Enable-AzureRmAlias 會為 AzureRM 中較舊的 Cmdlet 名稱建立對應於較新 Az Cmdlet 名稱的別名。搭配使用 -Scope 引數與 Enable-AzureRmAlias 可讓您選擇要啟用別名的位置。

例如，下列的 AzureRM 指令碼：

#Requires -Modules AzureRM.Storage
Get-AzureRmStorageAccount | Get-AzureStorageContainer | Get-AzureStorageBlob

只要使用 Enable-AzureRmAlias 稍做變更即可執行：

#Requires -Modules Az.Storage
Enable-AzureRmAlias -Scope Process
Get-AzureRmStorageAccount | Get-AzureStorageContainer | Get-AzureStorageBlob

執行 Enable-AzureRmAlias -Scope CurrentUser 會對所有已開啟的 PowerShell 工作階段啟用別名，因此在執行此 Cmdlet 之後，就完全不需要變更這類指令碼：

Get-AzureRmStorageAccount | Get-AzureStorageContainer | Get-AzureStorageBlob

如需如何使用別名 Cmdlet 的完整詳細資訊，請參閱 Enable-AzureRmAlias 參考資料。

當您準備好要停用別名時，Disable-AzureRmAlias 會移除已建立的別名。如需完整的詳細資訊，請參閱 Disable-AzureRmAlias 參考資料。

重要

停用別名時，請確實在所有已啟用別名的範圍加以停用。

模組名稱的變更

模組名稱已從 AzureRM.* 變更為 Az.*，但下列模組除外：

AzureRM 模組	Az 模組
Azure.Storage	Az.Storage
Azure.AnalysisServices	Az.AnalysisServices
AzureRM.Profile	Az.Accounts
AzureRM.Insights	Az.Monitor
AzureRM.RecoveryServices.Backup	Az.RecoveryServices
AzureRM.RecoveryServices.SiteRecovery	Az.RecoveryServices
AzureRM.Tags	Az.Resources
AzureRM.MachineLearningCompute	Az.MachineLearning
AzureRM.UsageAggregates	Az.Billing
AzureRM.Consumption	Az.Billing

模組名稱的變更表示，只要指令碼使用 #Requires 或 Import-Module 來載入特定模組，就需要進行變更，以改為使用新的模組。對 Cmdlet 後置詞未變更的模組而言，這表示模組名稱雖已變更，但表示作業空間的後置詞並未變更。

移轉 Requires 和 Import Module 陳述式

使用 #Requires 或 Import-Module 來宣告 AzureRM 模組相依性的指令碼，必須更新為使用新的模組名稱。例如：

#Requires -Module AzureRM.Compute

應變更為：

#Requires -Module Az.Compute

針對 Import-Module：

Import-Module -Name AzureRM.Compute

應變更為：

Import-Module -Name Az.Compute

遷移完整的 Cmdlet 叫用

使用模組完整 Cmdlet 叫用的指令碼，例如：

AzureRM.Compute\Get-AzureRmVM

必須變更為使用新的模組和 Cmdlet 名稱：

Az.Compute\Get-AzVM

移轉模組資訊清單相依性

透過模組資訊清單 (.psd1) 檔案來表達 AzureRM 模組相依性的模組，必須更新其 RequiredModules 區段中的模組名稱：

RequiredModules = @(@{ModuleName="AzureRM.Profile"; ModuleVersion="5.8.2"})

必須變更為：

RequiredModules = @(@{ModuleName="Az.Accounts"; ModuleVersion="1.0.0"})

移除的模組

下列模組已移除：

AzureRM.Backup
AzureRM.Compute.ManagedService
AzureRM.Scheduler

目前已不再支援這些服務的工具。建議客戶一有空就立刻遷移至替代服務。

Windows PowerShell 5.1 和 .NET 4.7.2

若要搭配使用 Az 與 PowerShell 5.1 for Windows，則必須安裝 .NET Framework 4.7.2。使用 PowerShell Core 6.x 或更新版本則不需要 .NET Framework。

由於 .NET Standard 的驗證流程有變，我們暫時移除透過 PSCredential 來登入使用者的功能。這項功能會在 2019 年 1 月 15 日版本的 PowerShell 5.1 for Windows 重新導入。我們會在此 GitHub 問題中加以詳細討論。

由於 .NET Standard 的驗證流程有變，我們會在互動式登入期間使用裝置登入作為預設的登入流程。在 2019 年 1 月 15 日的版本中，會重新導入透過網頁瀏覽器登入的功能，作為 PowerShell 5.1 for Windows 的預設登入功能。屆時，使用者將能夠使用切換參數來選擇裝置登入功能。

模組的重大變更

本節將詳細說明個別模組和 Cmdlet 的特定重大變更。

Az.ApiManagement (先前是 AzureRM.ApiManagement)

已移除下列 Cmdlet：
- New-AzureRmApiManagementHostnameConfiguration
- Set-AzureRmApiManagementHostnames
- Update-AzureRmApiManagementDeployment
- Import-AzureRmApiManagementHostnameCertificate
- 請改為使用 Set-AzApiManagement Cmdlet 來設定這些屬性
已移除下列屬性：
- 已從 PsApiManagementContext 移除 PsApiManagementHostnameConfiguration 類型的 PortalHostnameConfiguration、ProxyHostnameConfiguration、ManagementHostnameConfiguration 和 ScmHostnameConfiguration 屬性。請改為使用 PsApiManagementCustomHostNameConfiguration 類型的 PortalCustomHostnameConfiguration、ProxyCustomHostnameConfiguration、ManagementCustomHostnameConfiguration 和 ScmCustomHostnameConfiguration。
- 已從 PsApiManagementContext 移除 StaticIPs 屬性。此屬性已分割為 PublicIPAddresses 和 PrivateIPAddresses。
- 已從 New-AzureApiManagementVirtualNetwork Cmdlet 移除必要的 Location 屬性。

Az.Billing (先前是 AzureRM.Billing、AzureRM.Consumption 和 AzureRM.UsageAggregates)

已從 Get-AzConsumptionUsageDetail Cmdlet 移除 InvoiceName 參數。指令碼必須針對發票使用其他身分識別參數。

Az.Compute (先前是 AzureRM.Compute)

已從 PSVirtualMachine 和 PSVirtualMachineScaleSet 物件中的 Identity 屬性移除 IdentityIds。指令碼不應再使用這個欄位的值來決定處理方式。
PSVirtualMachineScaleSetVM 物件的 InstanceView 屬性，其類型已從 VirtualMachineInstanceView 變更為 VirtualMachineScaleSetVMInstanceView
已從 UpgradePolicy 屬性移除 AutoOSUpgradePolicy 和 AutomaticOSUpgrade 屬性
PSSnapshotUpdate 物件中的 Sku 屬性，其類型已從 DiskSku 變更為 SnapshotSku
已從 Add-AzVMDataDisk Cmdlet 移除 VmScaleSetVMParameterSet，您無法再個別地將資料磁碟新增至擴展集 VM。

Az.KeyVault (先前是 AzureRM.KeyVault)

PurgeDisabled 屬性已從 PSKeyVaultKeyAttributes、PSKeyVaultKeyIdentityItem 和 PSKeyVaultSecretAttributes 物件中移除指令碼不應再參考 PurgeDisabled 屬性來做出處理決策。

Az.Monitor (先前是 AzureRM.Insights)

已從 Set-AzDiagnosticSetting Cmdlet 移除複數名稱 Categories 和 Timegrains 參數，以便支援單一參數名稱。使用下列 Cmdlet 的指令碼
```
Set-AzureRmDiagnosticSetting -Timegrains PT1M -Categories Category1, Category2
```
應變更為
```
Set-AzDiagnosticSetting -Timegrain PT1M -Category Category1, Category2
```

Az.Network (先前是 AzureRM.Network)

已從 Get-AzServiceEndpointPolicyDefinition Cmdlet 移除淘汰的 ResourceId 參數
已從 PSVirtualNetwork 物件移除淘汰的 EnableVmProtection 屬性
已移除淘汰的 Set-AzVirtualNetworkGatewayVpnClientConfig Cmdlet

指令碼不應再根據這些欄位的值來決定處理方式。

Az.Resources (先前是 AzureRM.Resources)

已從 New/Set-AzPolicyAssignment Cmdlet 移除 Sku 參數

已從 New-AzADServicePrincipal 和 New-AzADSpCredential Cmdlet 移除 Password 參數。密碼會自動產生，提供密碼的指令碼：

New-AzAdSpCredential -ObjectId 1f99cf81-0146-4f4e-beae-2007d0668476 -Password $secPassword

應變更為從輸出擷取密碼：

$credential = New-AzAdSpCredential -ObjectId 1f99cf81-0146-4f4e-beae-2007d0668476
$secPassword = $credential.Secret

Az.Storage (先前是 Azure.Storage 和 AzureRM.Storage)

為了支援建立僅具有儲存體帳戶名稱的 Oauth 儲存體內容，預設參數集已變更為 OAuthParameterSet
- 範例： $ctx = New-AzureStorageContext -StorageAccountName $accountName
Location 已成為 Get-AzStorageUsage Cmdlet 的必要參數
儲存體 API 方法現在會使用以工作為基礎的非同步模式 (TAP)，而非使用同步 API 呼叫。下列範例示範新的非同步命令：

Blob 快照集

AzureRM：

$b = Get-AzureStorageBlob -Container $containerName -Blob $blobName -Context $ctx
$b.ICloudBlob.Snapshot()

Az：

$b = Get-AzStorageBlob -Container $containerName -Blob $blobName -Context $ctx
$task = $b.ICloudBlob.SnapshotAsync()
$task.Wait()
$snapshot = $task.Result

AzureRM：

$Share = Get-AzureStorageShare -Name $containerName -Context $ctx
$snapshot = $Share.Snapshot()

Az：

$Share = Get-AzStorageShare -Name $containerName -Context $ctx
$task = $Share.SnapshotAsync()
$task.Wait()
$snapshot = $task.Result

取消刪除虛刪除的 Blob

AzureRM：

$b = Get-AzureStorageBlob -Container $containerName -Blob $blobName -IncludeDeleted -Context $ctx
$b.ICloudBlob.Undelete()

Az：

$b = Get-AzStorageBlob -Container $containerName -Blob $blobName -IncludeDeleted -Context $ctx
$task = $b.ICloudBlob.UndeleteAsync()
$task.Wait()

設定 Blob 層

AzureRM：

$blockBlob = Get-AzureStorageBlob -Container $containerName -Blob $blockBlobName -Context $ctx
$blockBlob.ICloudBlob.SetStandardBlobTier("hot")

$pageBlob = Get-AzureStorageBlob -Container $containerName -Blob $pageBlobName -Context $ctx
$pageBlob.ICloudBlob.SetPremiumBlobTier("P4")

Az：

$blockBlob = Get-AzStorageBlob -Container $containerName -Blob $blockBlobName -Context $ctx
$task = $blockBlob.ICloudBlob.SetStandardBlobTierAsync("hot")
$task.Wait()

$pageBlob = Get-AzStorageBlob -Container $containerName -Blob $pageBlobName -Context $ctx
$task = $pageBlob.ICloudBlob.SetPremiumBlobTierAsync("P4")
$task.Wait()

Az.Websites (先前是 AzureRM.Websites)

已從 PSAppServicePlan、PSCertificate、PSCloningInfo 和 PSSite 物件移除淘汰的屬性

後續步驟

了解 Azure Stack Hub 上的 PowerShell，請參閱開始在 Azure Stack Hub 中使用 PowerShell
安裝 PowerShell Az 模組，請參閱安裝適用於 Azure Stack Hub 的 PowerShell Az 模組

在 Azure Stack Hub 中從 AzureRM 移轉至 Azure PowerShell Az

檢查所安裝的 AzureRM 版本

檢查 AzureRM 目前使用的指令碼

安裝 Azure PowerShell Az 模組

啟用 AzureRM 相容性別名

變更模組和 Cmdlet 名稱

總結

Az 1.0.0 的重大變更

一般重大變更

Cmdlet 名詞前置詞的變更

模組名稱的變更

移轉 Requires 和 Import Module 陳述式

遷移完整的 Cmdlet 叫用

移轉模組資訊清單相依性

移除的模組

Windows PowerShell 5.1 和 .NET 4.7.2

模組的重大變更

Az.ApiManagement (先前是 AzureRM.ApiManagement)

Az.Billing (先前是 AzureRM.Billing、AzureRM.Consumption 和 AzureRM.UsageAggregates)

Az.Compute (先前是 AzureRM.Compute)

Az.KeyVault (先前是 AzureRM.KeyVault)

Az.Monitor (先前是 AzureRM.Insights)

Az.Network (先前是 AzureRM.Network)

Az.Resources (先前是 AzureRM.Resources)

Az.Storage (先前是 Azure.Storage 和 AzureRM.Storage)

Blob 快照集

取消刪除虛刪除的 Blob

設定 Blob 層

Az.Websites (先前是 AzureRM.Websites)

後續步驟

意見反應

意見反應

其他資源

在 Azure Stack Hub 中從 AzureRM 移轉至 Azure PowerShell Az

檢查所安裝的 AzureRM 版本

檢查 AzureRM 目前使用的指令碼

安裝 Azure PowerShell Az 模組

啟用 AzureRM 相容性別名

變更模組和 Cmdlet 名稱

總結

Az 1.0.0 的重大變更

一般重大變更

Cmdlet 名詞前置詞的變更

模組名稱的變更

移轉 Requires 和 Import Module 陳述式

遷移完整的 Cmdlet 叫用

移轉模組資訊清單相依性

移除的模組

Windows PowerShell 5.1 和 .NET 4.7.2

使用 PSCredential 暫時移除使用者登入

預設使用裝置程式碼登入，而非網頁瀏覽器提示

模組的重大變更

Az.ApiManagement (先前是 AzureRM.ApiManagement)

Az.Billing (先前是 AzureRM.Billing、AzureRM.Consumption 和 AzureRM.UsageAggregates)

Az.Compute (先前是 AzureRM.Compute)

Az.KeyVault (先前是 AzureRM.KeyVault)

Az.Monitor (先前是 AzureRM.Insights)

Az.Network (先前是 AzureRM.Network)

Az.Resources (先前是 AzureRM.Resources)

Az.Storage (先前是 Azure.Storage 和 AzureRM.Storage)

Blob 快照集

共用快照集

取消刪除虛刪除的 Blob

設定 Blob 層

Az.Websites (先前是 AzureRM.Websites)

後續步驟

意見反應

意見反應

其他資源