在 Azure Stack Hub 中从 AzureRM 迁移到 Azure PowerShell Az
Az 模块与 AzureRM 具有功能奇偶一致性,但 Az 模块使用更短且更一致的 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
。
应当注意此命名更改有一些例外。 某些模块已重命名或合并到了现有模块中(在此命名更改未影响这些模块的 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 参考。
重要
禁用别名时,请确保在启用了别名的所有范围内禁用别名。
模块名称更改
模块名称已从 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 与 Windows 版 PowerShell 5.1 配合使用需要安装 .NET Framework 4.7.2。 使用 PowerShell Core 6.x 或更高版本不需要 .NET Framework。
暂时删除了使用 PSCredential 的用户登录
由于 .NET Standard 的身份验证流发生更改,我们暂时删除了通过 PSCredential 进行的用户登录。 将在 2019 年 1 月 15 日的 Windows 版 PowerShell 5.1 中重新引入此功能。 此 GitHub 问题中详细讨论了这方面的内容。
默认设备代码登录替换了 Web 浏览器提示
由于 .NET Standard 的身份验证流发生更改,我们在交互式登录期间使用设备登录作为默认登录流。 将在 2019 年 1 月 15 日的 Windows 版 PowerShell 5.1 中重新引入基于 Web 浏览器的登录作为默认登录流。 到那时,用户将能够使用一个 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)
- 从
Get-AzConsumptionUsageDetail
cmdlet 中删除了InvoiceName
参数。 脚本将需要为发票使用其他标识参数。
Az.Compute(以前的 AzureRM.Compute)
- 从
PSVirtualMachine
和PSVirtualMachineScaleSet
对象中的Identity
属性中删除了IdentityIds
。脚本不应当再使用此字段的值来做出处理决策。 PSVirtualMachineScaleSetVM
对象的InstanceView
属性的类型已从VirtualMachineInstanceView
更改为VirtualMachineScaleSetVMInstanceView
- 从
UpgradePolicy
属性中删除了AutoOSUpgradePolicy
和AutomaticOSUpgrade
属性 PSSnapshotUpdate
对象中的Sku
属性的类型已从DiskSku
更改为SnapshotSku
VmScaleSetVMParameterSet
已从Add-AzVMDataDisk
cmdlet 中删除,你不再能够将数据磁盘单独添加到规模集 VM。
Az.KeyVault(以前的 AzureRM.KeyVault)
- 从
PSKeyVaultKeyAttributes
、PSKeyVaultKeyIdentityItem
和PSKeyVaultSecretAttributes
对象中删除了PurgeDisabled
属性。脚本不再应该引用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 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 模块