从 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 名称

通常,模块名称已更改,以便 AzureRMAzure 变为 Az,并且 cmdlet 也是如此。 例如,AzureRM.Compute 模块已重命名为 Az.ComputeNew-AzureRMVM 已成为 New-AzVMGet-AzureStorageBlob 现在 Get-AzStorageBlob

应注意的此命名更改存在例外情况。 某些模块已重命名或合并到现有模块中,除了将 AzureRMAzure 更改为 Az外,这不会影响其 cmdlet 的后缀。 其他情况下,完整的 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 使用 AzureRMAzure 作为名词前缀。 Az 简化了 cmdlet 名称并规范化,以便所有 cmdlet 都使用“Az”作为其 cmdlet 名词前缀。 例如:

Get-AzureRMVM
Get-AzureKeyVaultSecret

已更改为:

Get-AzVM
Get-AzKeyVaultSecret

为了简化对这些新 cmdlet 名称的转换,Az 引入了两个新的 cmdlet,Enable-AzureRmAliasDisable-AzureRmAliasEnable-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

模块名称中的更改意味着需要更改使用 #RequiresImport-Module 加载特定模块的任何脚本,才能改用新模块。 对于其中的 cmdlet 后缀尚未更改的模块,这意味着,虽然模块名称已更改,但指示操作空间的后缀尚未更改。

迁移 requires 和 import module 语句

必须更新那些使用 #RequiresImport-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

必须更改以使用新的模块和命令行小程序名称:

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 删除用户登录名。 此功能将在 2019 年 1 月 15 日版本的 PowerShell 5.1 for Windows 中重新引入。 此 GitHub 问题中详细讨论了这方面的内容。

改为使用默认设备代码登录,而不使用 Web 浏览器提示。

由于 .NET Standard 的身份验证流发生更改,我们在交互式登录期间使用设备登录作为默认登录流。 对于 Windows 的 PowerShell 5.1,基于网络浏览器的登录将在 2019 年 1 月 15 日发布的版本中重新引入,并作为默认方式。 届时,用户将能够使用切换参数选择设备登录。

模块中断性变更

此部分详述单个模块和 cmdlet 的具体中断性变更。

Az.ApiManagement (以前为 AzureRM.ApiManagement)

  • 删除了以下 cmdlet:
    • New-AzureRmApiManagementHostnameConfiguration
    • Set-AzureRmApiManagementHostnames
    • Update-AzureRmApiManagementDeployment
    • Import-AzureRmApiManagementHostnameCertificate
    • 改用 Set-AzApiManagement cmdlet 设置这些属性
  • 删除了以下属性:
    • PsApiManagementContext中删除了类型 PsApiManagementHostnameConfiguration 的属性 PortalHostnameConfigurationProxyHostnameConfigurationManagementHostnameConfigurationScmHostnameConfiguration。 请改用 PsApiManagementCustomHostNameConfiguration 类型的 PortalCustomHostnameConfigurationProxyCustomHostnameConfigurationManagementCustomHostnameConfigurationScmCustomHostnameConfiguration
    • 从 PsApiManagementContext 中删除了属性 StaticIPs。 该属性已拆分为 PublicIPAddressesPrivateIPAddresses
    • 从 New-AzureApiManagementVirtualNetwork cmdlet 中删除了所需的属性 Location

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

  • InvoiceName 参数已从 Get-AzConsumptionUsageDetail cmdlet 中删除。 脚本需要使用发票的其他标识参数。

Az.Compute (以前为 AzureRM.Compute)

  • IdentityIdsIdentity 属性中删除,该属性属于 PSVirtualMachinePSVirtualMachineScaleSet 对象,脚本不应再使用此字段的值来做出处理决策。
  • PSVirtualMachineScaleSetVM 对象的 InstanceView 属性的类型从 VirtualMachineInstanceView 更改为 VirtualMachineScaleSetVMInstanceView
  • UpgradePolicy 属性中删除了 AutoOSUpgradePolicyAutomaticOSUpgrade 属性
  • PSSnapshotUpdate 对象中 Sku 属性的类型从 DiskSku 更改为 SnapshotSku
  • VmScaleSetVMParameterSetAdd-AzVMDataDisk cmdlet 中删除,无法再单独向 ScaleSet VM 添加数据磁盘。

Az.KeyVault (以前为 AzureRM.KeyVault)

  • PurgeDisabled 属性已从 PSKeyVaultKeyAttributesPSKeyVaultKeyIdentityItemPSKeyVaultSecretAttributes 对象中删除,脚本不应再引用 PurgeDisabled 属性来做出处理决策。

Az.Monitor (以前为 AzureRM.Insights)

  • Set-AzDiagnosticSetting cmdlet 中删除了复数名称 CategoriesTimegrains 参数并将其替换为单数参数名称。使用以下内容的脚本

    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-AzADServicePrincipalNew-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)

  • PSAppServicePlanPSCertificatePSCloningInfoPSSite 对象中删除了弃用的属性

后续步骤