共用方式為

從 AzureRM 遷移至 Azure Stack Hub 中的 Azure PowerShell Az

  • 發行項

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 時，才啟用相容性模式。 啟用相容性模式並同時保留 AzureRM Cmdlet 的可用性，可能會導致無法預期的行為。 如果您決定要繼續安裝 AzureRM，請略過此步驟，但請注意，任何 AzureRM Cmdlet 都會使用較舊的模組，而不會呼叫任何 Az Cmdlet。

卸載 AzureRM 後，您的腳本會使用最新的 AzureRM 版本，下一個步驟是啟用 Az 模組的相容性模式。 使用 命令開啟相容性：

Enable-AzureRmAlias -Scope CurrentUser

別名可讓您使用已安裝 Az 模組的舊 Cmdlet 名稱。 這些別名會寫入所選範圍的使用者配置檔。 如果沒有使用者帳戶檔案，將會建立一個。

警告

您可以針對此命令使用不同的 -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 是的
AzureRM.Insights Az.Monitor 是的
AzureRM.Tags Az.Resources 不
AzureRM.UsageAggregates Az.Billing 不
AzureRM.Consumption Az.Billing 不

總結

依照下列步驟，您可以更新所有現有的腳本，以使用新的模組。 如果您對這些步驟有任何疑問或問題，這些步驟令您在移轉過程中遇到困難，請在此文章下留言，以便我們改進指示。

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 參考。

重要

zh-TW: 停用別名時，請確保在所有曾啟用別名的範圍 中將其停用。

模組名稱變更

模組名稱已從 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 來宣告對 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。

使用 PSCredential 暫時停用使用者登入

由於 .NET Standard 的驗證流程變更，我們暫時透過 PSCredential 移除使用者登入。 此功能將會在適用於 Windows 的 PowerShell 5.1 的 2019/15 版本中重新推出。 這會在此 GitHub 問題 詳細討論。

默認裝置程式代碼登入，而不是網頁瀏覽器提示

由於 .NET Standard 的驗證流程變更，我們會在互動式登入期間使用裝置登入作為默認登入流程。 在 2019/1/15 版本中，將會為 Windows 的 PowerShell 5.1 重新引入基於網頁瀏覽器的登入作為預設。 屆時，用戶將能夠使用 Switch 參數來選擇裝置登入。

模組重大變更

本節詳細說明個別模組和 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）

  • InvoiceName 參數已從 Get-AzConsumptionUsageDetail Cmdlet 中移除。 腳本必須使用發票的其他身分識別參數。

Az.Compute （先前是 AzureRM.Compute）

  • IdentityIds 會從 PSVirtualMachine 中的 Identity 屬性中移除，而且 PSVirtualMachineScaleSet 物件腳本不應再使用此欄位的值來進行處理決策。
  • PSVirtualMachineScaleSetVM 物件的 InstanceView 屬性類型會從 VirtualMachineInstanceView 變更為 VirtualMachineScaleSetVMInstanceView
  • AutoOSUpgradePolicy 和 AutomaticOSUpgrade 屬性會從 UpgradePolicy 屬性中移除
  • PSSnapshotUpdate 物件中的 Sku 屬性類型從 DiskSku 變更為 SnapshotSku
  • VmScaleSetVMParameterSet 已從 Add-AzVMDataDisk Cmdlet 中移除，您無法再個別將數據磁碟新增至 ScaleSet VM。

Az.KeyVault （先前是 AzureRM.KeyVault）

  • PurgeDisabled 屬性已從 PSKeyVaultKeyAttributes、PSKeyVaultKeyIdentityItem和 PSKeyVaultSecretAttributes 物件中移除腳本不應再參考 PurgeDisabled 屬性來進行處理決策。

Az.Monitor （先前是 AzureRM.Insights）

  • 已移除複數名稱 Categories 和 Timegrains 參數，以便在 Set-AzDiagnosticSetting 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 aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb -Password $secPassword

    應該調整為從輸出取得密碼：

    $credential = New-AzAdSpCredential -ObjectId aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
$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 物件中移除已淘汰的屬性

後續步驟