Partilhar via

Migrar do AzureRM para o Azure PowerShell Az no Azure Stack Hub

  • Artigo

O módulo Az tem paridade de recursos com o AzureRM, mas usa nomes de cmdlet mais curtos e consistentes. Os scripts escritos para os cmdlets do AzureRM não funcionarão automaticamente com o novo módulo. Para facilitar a transição, o Az oferece ferramentas para permitir que você execute seus scripts existentes usando o AzureRM. Nenhuma migração para um novo conjunto de comandos é conveniente, mas este artigo irá ajudá-lo a começar a transição para o novo módulo.

Para ver a lista completa de alterações significativas entre o AzureRM e o Az, consulte o Guia de migração de para o Az 1.0.0

Verifique se há versões instaladas do AzureRM

Antes de executar qualquer etapa de migração, verifique quais versões do AzureRM estão instaladas em seu sistema. Isso permite que você verifique se os scripts já estão em execução na versão mais recente e informa se você pode habilitar aliases de comando sem desinstalar o AzureRM.

Para verificar quais versões do AzureRM você instalou, execute o comando:

Get-InstalledModule -Name AzureRM -AllVersions

Verifique se os scripts atuais funcionam com o AzureRM

Este é o passo mais importante! Execute os scripts existentes e certifique-se de que funcionam com a versão mais recente do AzureRM (2.5.0). Caso os seus scripts não funcionem, certifique-se de ler o guia de migração do AzureRM.

Instalar o módulo Az do Azure PowerShell

O primeiro passo é instalar o módulo Az na sua plataforma. Ao instalar o Az, é recomendável desinstalar o AzureRM. Nas etapas a seguir, você aprenderá como continuar executando seus scripts existentes e habilitar a compatibilidade para nomes de cmdlets antigos.

Para instalar o módulo Az do Azure PowerShell, siga estas etapas:

Habilitar aliases de compatibilidade do AzureRM

Importante

Habilite o modo de compatibilidade somente se você tiver desinstalado todas as versões do AzureRM. Habilitar o modo de compatibilidade com cmdlets do AzureRM ainda disponíveis pode resultar em comportamento imprevisível. Ignore esta etapa se você decidiu manter o AzureRM instalado, mas esteja ciente de que qualquer cmdlet do AzureRM usará os módulos mais antigos e não chamará nenhum cmdlet Az.

Com o AzureRM desinstalado e seus scripts trabalhando com a versão mais recente do AzureRM, a próxima etapa é habilitar o modo de compatibilidade para o módulo Az. A compatibilidade é ativada com o comando:

Enable-AzureRmAlias -Scope CurrentUser

Os aliases permitem a capacidade de usar nomes de cmdlets antigos com o módulo Az instalado. Esses aliases são gravados no perfil de usuário para o escopo selecionado. Se não existir um perfil de utilizador, é criado um.

Advertência

Você pode usar um -Scope diferente para esse comando, mas não é recomendado. Os aliases são gravados no perfil de usuário para o escopo selecionado, portanto, continue habilitando-os para um escopo o mais limitado possível. Habilitar aliases em todo o sistema também pode causar problemas para outros usuários que têm o AzureRM instalado em seu escopo local.

Quando o modo alias estiver ativado, execute os scripts novamente para confirmar se eles ainda funcionam conforme o esperado.

Alterar nomes de módulos e cmdlets

Em geral, os nomes dos módulos foram alterados para que AzureRM e Azure se tornem Aze o mesmo para cmdlets. Por exemplo, o módulo AzureRM.Compute foi renomeado para Az.Compute. New-AzureRMVM tornou-se New-AzVM, e Get-AzureStorageBlob agora é Get-AzStorageBlob.

Há exceções a essa alteração de nomenclatura que você deve estar ciente. Alguns módulos foram renomeados ou combinados em módulos existentes sem que isso afetasse o sufixo dos seus cmdlets, exceto pela alteração de AzureRM ou Azure para Az. Caso contrário, o sufixo completo do cmdlet foi alterado para refletir o novo nome do módulo.

Módulo AzureRM Módulo Az O sufixo do Cmdlet foi alterado?
AzureRM.Profile Az.Contas Sim
AzureRM.Insights Az.Monitor Sim
AzureRM.Tags Az.Recursos Não
AzureRM.UsageAggregates Az.Faturação Não
AzureRM.Consumption A faturação Az. Não

Resumo

Seguindo estas etapas, você pode atualizar todos os scripts existentes para usar o novo módulo. Se você tiver alguma dúvida ou problema com essas etapas que dificultaram sua migração, comente este artigo para que possamos melhorar as instruções.

Alterações significativas para Az 1.0.0

Este documento fornece informações detalhadas sobre as alterações entre o AzureRM 6.x e o novo módulo Az, versão 1.x e posterior. O sumário ajudará a guiá-lo por um caminho de migração completo, incluindo alterações específicas do módulo que podem afetar seus scripts.

Alterações gerais disruptivas

Esta seção detalha as alterações gerais de quebra que fazem parte do redesenho do módulo Az.

Alterações no prefixo do substantivo do cmdlet

No módulo AzureRM, os cmdlets usavam AzureRM ou Azure como um prefixo substantivo. Az simplifica e normaliza os nomes de cmdlets, para que todos os cmdlets usem 'Az' como prefixo de substantivo do cmdlet. Por exemplo:

Get-AzureRMVM
Get-AzureKeyVaultSecret

Mudou para:

Get-AzVM
Get-AzKeyVaultSecret

Para tornar a transição para esses novos nomes de cmdlet mais simples, o Az apresenta dois novos cmdlets, Enable-AzureRmAlias e Disable-AzureRmAlias. Enable-AzureRmAlias cria aliases para os nomes de cmdlet mais antigos no AzureRM que são mapeados para os nomes de cmdlet Az mais recentes. Usar o argumento -Scope com Enable-AzureRmAlias permite que você escolha onde os aliases estão habilitados.

Por exemplo, o seguinte script no AzureRM:

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

Pode ser executado com alterações mínimas usando Enable-AzureRmAlias:

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

A execução Enable-AzureRmAlias -Scope CurrentUser habilitará os aliases para todas as sessões do PowerShell abertas, de modo que, depois de executar esse cmdlet, um script como esse não precise ser alterado:

Get-AzureRmStorageAccount | Get-AzureStorageContainer | Get-AzureStorageBlob

Para obter detalhes completos sobre o uso dos cmdlets de alias, consulte a referência Enable-AzureRmAlias.

Quando estiver pronto para desativar os aliases, Disable-AzureRmAlias remove os aliases criados. Para obter detalhes completos, consulte as referências Disable-AzureRmAlias no.

Importante

Ao desativar aliases, certifique-se de que eles estão desabilitados para todos os escopos que tinham aliases habilitados.

Alterações no nome do módulo

Os nomes dos módulos foram alterados de AzureRM.* para Az.*, exceto para os seguintes módulos:

Módulo AzureRM Módulo Az
Azure.Storage Az.Storage
Azure.AnalysisServices Az.AnalysisServices
AzureRM.Profile Az.Contas
AzureRM.Insights Az.Monitor
AzureRM.RecoveryServices.Backup Az.RecoveryServices
AzureRM.RecoveryServices.SiteRecovery Az.RecoveryServices
AzureRM.Tags Az.Recursos
AzureRM.MachineLearningCompute Az.Aprendizagem Automática
AzureRM.UsageAggregates Az.Faturação
AzureRM.Consumption Az. Faturação

As alterações nos nomes dos módulos significam que qualquer script que use #Requires ou Import-Module para carregar módulos específicos precisará ser alterado para usar o novo módulo. Para módulos em que o sufixo do cmdlet não foi alterado, isso significa que, embora o nome do módulo tenha sido alterado, o sufixo que indica o espaço de operação não .

A migração requer a importação de declarações de módulo

Os scripts que usam #Requires ou Import-Module para declarar uma dependência nos módulos do AzureRM devem ser atualizados para usar os novos nomes de módulo. Por exemplo:

#Requires -Module AzureRM.Compute

Deve ser alterado para:

#Requires -Module Az.Compute

Para Import-Module:

Import-Module -Name AzureRM.Compute

Deve ser alterado para:

Import-Module -Name Az.Compute

Migrando invocações de cmdlet totalmente qualificadas

Scripts que usam invocações de cmdlet qualificadas por módulo, como:

AzureRM.Compute\Get-AzureRmVM

Deve ser alterado para usar os novos nomes de módulo e cmdlet:

Az.Compute\Get-AzVM

Migrando dependências de manifesto do módulo

Os módulos que expressam dependências nos módulos AzureRM por meio de um arquivo de manifesto de módulo (.psd1) precisarão atualizar os nomes dos módulos em sua seção RequiredModules:

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

Deve ser alterado para:

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

Módulos removidos

Os seguintes módulos foram removidos:

  • AzureRM.Backup
  • AzureRM.Compute.ManagedService
  • AzureRM.Scheduler

As ferramentas para esses serviços não são mais suportadas ativamente. Os clientes são incentivados a mudar para serviços alternativos assim que for conveniente.

Windows PowerShell 5.1 e .NET 4.7.2

Usar o Az com o PowerShell 5.1 para Windows requer a instalação do .NET Framework 4.7.2. Usar o PowerShell Core 6.x ou posterior não requer o .NET Framework.

Remoção temporária do login do usuário usando PSCredential

Devido a alterações no fluxo de autenticação para o .NET Standard, estamos removendo temporariamente o login do usuário via PSCredential. Esse recurso será reintroduzido na versão 15/01/2019 do PowerShell 5.1 para Windows. Isso é discutido em detalhes nesta questão do GitHub .

Login de código de dispositivo padrão em vez de solicitação no navegador

Devido a alterações no fluxo de autenticação para o .NET Standard, estamos usando o login do dispositivo como o fluxo de login padrão durante o login interativo. O login baseado em navegador da Web será reintroduzido para o PowerShell 5.1 para Windows como padrão na versão 15/01/2019. Nesse momento, os usuários poderão escolher o login do dispositivo usando um parâmetro Switch.

Alterações significativas no módulo

Esta seção detalha alterações de quebra específicas para módulos e cmdlets individuais.

Az.ApiManagement (anteriormente AzureRM.ApiManagement)

  • Removidos os seguintes cmdlets:
    • New-AzureRmApiManagementHostnameConfiguration
    • Set-AzureRmApiManagementHostnames
    • Update-AzureRmApiManagementDeployment
    • Import-AzureRmApiManagementHostnameCertificate
    • Utilize o cmdlet Set-AzApiManagement para definir estas propriedades
  • Removidas as seguintes propriedades:
    • Propriedades removidas PortalHostnameConfiguration, ProxyHostnameConfiguration, ManagementHostnameConfiguration e ScmHostnameConfiguration do tipo PsApiManagementHostnameConfiguration de PsApiManagementContext. Em vez disso, use PortalCustomHostnameConfiguration, ProxyCustomHostnameConfiguration, ManagementCustomHostnameConfiguration e ScmCustomHostnameConfiguration do tipo PsApiManagementCustomHostNameConfiguration.
    • A propriedade StaticIPs foi removida de PsApiManagementContext. A propriedade foi dividida em PublicIPAddresses e PrivateIPAddresses.
    • Removida a propriedade necessária Location do cmdlet New-AzureApiManagementVirtualNetwork.

Az.Billing (anteriormente AzureRM.Billing, AzureRM.Consumption e AzureRM.UsageAggregates)

  • O parâmetro InvoiceName foi removido do cmdlet Get-AzConsumptionUsageDetail. Os scripts precisarão usar outros parâmetros de identidade para a fatura.

Az.Compute (anteriormente AzureRM.Compute)

  • IdentityIds é removido da propriedade Identity nos objetos PSVirtualMachine e PSVirtualMachineScaleSet. Os scripts não devem mais usar o valor deste campo para tomar decisões de processamento.
  • O tipo de propriedade InstanceView de PSVirtualMachineScaleSetVM objeto é alterado de VirtualMachineInstanceView para VirtualMachineScaleSetVMInstanceView
  • AutoOSUpgradePolicy e AutomaticOSUpgrade propriedades são removidas de UpgradePolicy propriedade
  • O tipo de propriedade Sku em PSSnapshotUpdate objeto é alterado de DiskSku para SnapshotSku
  • VmScaleSetVMParameterSet for removido de Add-AzVMDataDisk cmdlet, você não poderá mais adicionar um disco de dados individualmente a uma VM ScaleSet.

Az.KeyVault (anteriormente AzureRM.KeyVault)

  • A propriedade PurgeDisabled foi removida dos objetos PSKeyVaultKeyAttributes, PSKeyVaultKeyIdentityIteme PSKeyVaultSecretAttributes Os scripts não devem mais fazer referência à propriedade PurgeDisabled para tomar decisões de processamento.

Az.Monitor (anteriormente AzureRM.Insights)

  • Removidos os nomes de parâmetros plurais Categories e Timegrains em favor de nomes singulares nos scripts do cmdlet Set-AzDiagnosticSetting.

    Set-AzureRmDiagnosticSetting -Timegrains PT1M -Categories Category1, Category2

    Deve ser alterado para

    Set-AzDiagnosticSetting -Timegrain PT1M -Category Category1, Category2

Az.Network (anteriormente AzureRM.Network)

  • Removido parâmetro ResourceId preterido do cmdlet Get-AzServiceEndpointPolicyDefinition
  • Propriedade preterida EnableVmProtection removida de um objeto PSVirtualNetwork
  • Cmdlet preterido Set-AzVirtualNetworkGatewayVpnClientConfig removido

Os scripts não devem mais tomar decisões de processamento com base nos valores desses campos.

Az.Resources (anteriormente AzureRM.Resources)

  • Removido o parâmetro Sku do cmdlet New/Set-AzPolicyAssignment

  • Removido Password parâmetro do cmdlet New-AzADServicePrincipal e New-AzADSpCredential As senhas são geradas automaticamente, scripts que forneciam a senha:

    New-AzAdSpCredential -ObjectId aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb -Password $secPassword

    Deve ser alterado para recuperar a senha da saída:

    $credential = New-AzAdSpCredential -ObjectId aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
$secPassword = $credential.Secret

Az.Storage (anteriormente Azure.Storage e AzureRM.Storage)

  • Para dar suporte à criação de um contexto de armazenamento Oauth apenas com o nome da conta de armazenamento, o conjunto de parâmetros padrão foi alterado para OAuthParameterSet
    • Exemplo: $ctx = New-AzureStorageContext -StorageAccountName $accountName
  • O parâmetro Location tornou-se obrigatório no cmdlet Get-AzStorageUsage
  • Os métodos da API de armazenamento agora usam o padrão assíncrono baseado em tarefas (TAP), em vez de chamadas de API síncronas. Os exemplos a seguir demonstram os novos comandos assíncronos:

Cópia instantânea de 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

Compartilhar instantâneo

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

Restaurar blob com exclusão temporária

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

Definir camada de 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 (anteriormente AzureRM.Websites)

  • Propriedades preteridas removidas dos objetos PSAppServicePlan, PSCertificate, PSCloningInfoe PSSite

Próximos passos