从 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 版本,不只是最新版本。
- 安装 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
。
应注意的此命名更改存在例外情况。 某些模块已重命名或合并到现有模块中,除了将 AzureRM
或 Azure
更改为 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 使用 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
必须更改以使用新的模块和命令行小程序名称:
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
的属性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
从Identity
属性中删除,该属性属于PSVirtualMachine
和PSVirtualMachineScaleSet
对象,脚本不应再使用此字段的值来做出处理决策。PSVirtualMachineScaleSetVM
对象的InstanceView
属性的类型从VirtualMachineInstanceView
更改为VirtualMachineScaleSetVMInstanceView
- 从
UpgradePolicy
属性中删除了AutoOSUpgradePolicy
和AutomaticOSUpgrade
属性 PSSnapshotUpdate
对象中Sku
属性的类型从DiskSku
更改为SnapshotSku
VmScaleSetVMParameterSet
从Add-AzVMDataDisk
cmdlet 中删除,无法再单独向 ScaleSet VM 添加数据磁盘。
Az.KeyVault (以前为 AzureRM.KeyVault)
PurgeDisabled
属性已从PSKeyVaultKeyAttributes
、PSKeyVaultKeyIdentityItem
和PSKeyVaultSecretAttributes
对象中删除,脚本不应再引用PurgeDisabled
属性来做出处理决策。
Az.Monitor (以前为 AzureRM.Insights)
从
Set-AzDiagnosticSetting
cmdlet 中删除了复数名称Categories
和Timegrains
参数并将其替换为单数参数名称。使用以下内容的脚本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
对象中删除了弃用的属性
后续步骤
- 详细了解 Azure Stack Hub 上的 PowerShell,请参阅 Azure Stack Hub 中的 PowerShell 入门
- 安装 PowerShell Az 模块,请参阅 安装适用于 Azure Stack Hub 的 PowerShell Az 模块