Migrar do AzureRM para Azure PowerShell Az no Azure Stack Hub

O módulo do Az tem paridade de funcionalidades com o AzureRM, mas utiliza nomes de cmdlet mais curtos e mais consistentes. Os scripts escritos para os cmdlets do AzureRM não irão funcionar automaticamente com o módulo novo. Para facilitar a transição, o Az oferece ferramentas para permitir a execução dos seus scripts existentes com o AzureRM. Uma migração para um novo conjunto de comandos nunca é conveniente, mas este artigo ajuda-o a fazer a transição para o novo módulo.

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

Verificar se existem versões instaladas do AzureRM

Antes de realizar quaisquer passos de migração, verifique quais são as versões do AzureRM que se encontram instaladas no sistema. Ao fazê-lo, certifica-se de que os scripts já estão em execução na versão mais recente e fica a saber se pode ativar aliases de comandos sem desinstalar o AzureRM.

Para verificar quais são as versões do AzureRM que se encontram instaladas, execute o comando:

Get-InstalledModule -Name AzureRM -AllVersions

Verificar 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). Se os scripts não funcionarem, certifique-se de que lê o guia de migração do AzureRM.

Instalar o módulo do Azure PowerShell Az

O primeiro passo é instalar o módulo do Az na sua plataforma. Quando instalar o Az, recomenda-se que desinstale o AzureRM. Nos passos seguintes, irá aprender como continuar a executar os scripts existentes e permitir a compatibilidade dos nomes de cmdlet antigos.

Para instalar o módulo do Azure PowerShell Az, siga estes passos:

• Recomendado: desinstale o módulo AzureRM. Certifique-se de que remove todas as versões instaladas do AzureRM, e não apenas a versão mais recente.
• Instalar o módulo Az

Ativar aliases de compatibilidade do AzureRM

Com o AzureRM desinstalado e os scripts a funcionarem com a versão mais recente do AzureRM, chegou o momento de ativar o modo de compatibilidade para o módulo do Az. A compatibilidade é ativada com o comando:

Enable-AzureRmAlias -Scope CurrentUser

Os aliases ativam a capacidade de utilizar nomes de cmdlets antigos com o módulo do Az instalado. Estes aliases são escritos para o perfil de utilizador do âmbito selecionado. Se não existir um perfil de utilizador, é criado um.

Assim que o modo de alias estiver ativado, execute os seus scripts novamente para confirmar que ainda funcionam como esperado.

Alterar nomes de módulos e cmdlets

Em geral, os nomes dos módulos foram alterados para que AzureRM e Azure se tornassem Az, e o mesmo para os 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.

Existem exceções a esta alteração de nomenclatura de que deve estar ciente. Os nomes de alguns módulos foram mudados ou intercalados com os de módulos existentes sem afetar o sufixo dos respetivos cmdlets, exceto o facto de alterar AzureRM ou Azure para Az. Fora isso, o sufixo do cmdlet completo foi alterado de modo a refletir o novo nome do módulo.

Resumo

Ao seguir estes passos, pode atualizar todos os scripts existentes para utilizarem o módulo novo. Se tiver dúvidas ou problemas com estes passos que dificultaram a sua migração, comente este artigo para que possamos melhorar as instruções.

Alterações interruptivas do Az 1.0.0

Este documento fornece informações detalhadas sobre as alterações entre o AzureRM 6.x e o novo módulo do Az, versão 1.x e posterior. O índice irá guiá-lo através de um caminho de migração completo, incluindo alterações específicas do módulo que podem afetar os scripts.

Alterações interruptivas gerais

Esta secção fornece detalhes sobre as alterações interruptivas gerais que fazem parte do novo design do módulo do Az.

Alterações ao prefixo do substantivo do cmdlet

No módulo do AzureRM, os cmdlets utilizavam AzureRM ou Azure como prefixo de nome. O Az simplifica e normaliza os nomes de cmdlets, para que todos os cmdlets utilizem "Az" como prefixo de nome de cmdlet. Por exemplo:

Get-AzureRMVM
Get-AzureKeyVaultSecret

Foi alterado para:

Get-AzVM
Get-AzKeyVaultSecret

Para simplificar a transição para estes novos nomes de cmdlets, o Az apresenta dois novos cmdlets, Enable-AzureRmAlias e Disable-AzureRmAlias. Enable-AzureRmAlias cria aliases para os nomes de cmdlets mais antigos no AzureRM que os mapeia para os nomes de cmdlets do Az mais recentes. A utilização do argumento -Scope com Enable-AzureRmAlias permite-lhe escolher onde os aliases estão ativados.

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 com Enable-AzureRmAlias:

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

A utilização de Enable-AzureRmAlias -Scope CurrentUser permite atualizar os aliases em todas as sessões do PowerShell que forem abertas, para que, após a execução deste cmdlet, não seja necessário alterar um script deste tipo:

Get-AzureRmStorageAccount | Get-AzureStorageContainer | Get-AzureStorageBlob

Para obter detalhes completos sobre a utilização de cmdlets de aliases,veja a referência Enable-AzureRmAlias.

Quando estiver pronto para desativar aliases, Disable-AzureRmAlias remove os aliases criados. Para obter detalhes completos, veja a referência Disable-AzureRmAlias.

Alterações de nomes de módulos

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

As alterações realizadas ao nível dos nomes de módulos significam que qualquer script que utilizar #Requires ou Import-Module para carregar módulos específicos terá de ser alterado de modo a utilizar o novo módulo. Para os módulos em que o sufixo de cmdlet não foi alterado, embora o nome do módulo tenha sido alterado, o sufixo que indica o espaço da operação não foi alterado.

Migrar requer e importar instruções do módulo

Os scripts que utilizam #Requires ou Import-Module para declarar uma dependência nos módulos do AzureRM devem ser atualizados de modo a utilizarem os novos nomes de módulos. 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

Migrar invocações de cmdlets completamente qualificados

Os scripts que utilizam invocações de cmdlets qualificados por módulo, como:

AzureRM.Compute\Get-AzureRmVM

Têm de ser alterados de modo a utilizarem os novos nomes de módulos e cmdlets:

Az.Compute\Get-AzVM

Migrar dependências de manifestos de módulos

Os módulos que expressam dependências nos módulos do AzureRM através de um ficheiro (.psd1) de manifesto de módulo terão de atualizar os nomes de módulos na respetiva secção RequiredModules:

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

Tem de ser alterado para:

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

Módulos removidos

Os módulos seguintes foram removidos:

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

As ferramentas para estes serviços já não são suportadas ativamente. Os clientes são incentivados a mudar para serviços alternativos assim que for possível.

Windows PowerShell 5.1 e .NET 4.7.2

Para utilizar o Az com o PowerShell 5.1 para Windows, tem de instalar o .NET Framework 4.7.2. A utilização do PowerShell Core 6.x ou posterior não requer o .NET Framework.

Remoção temporária do início de sessão do utilizador com o PSCredential

Devido a alterações no fluxo de autenticação para o .NET Standard, estamos a remover temporariamente o início de sessão do utilizador através de PSCredential. Esta capacidade será introduzida novamente na versão de 15/01/2019 para o PowerShell 5.1 para Windows. Este assunto é abordado em detalhe neste debate sobre o problema no GitHub.

Início de sessão com o código de dispositivo predefinido em vez da linha de comandos do browser

Devido a alterações no fluxo de autenticação para o .NET Standard, estamos a utilizar o início de sessão de dispositivo como o fluxo de início de sessão predefinido durante o início de sessão interativo. O início de sessão baseado no browser será introduzido novamente para o PowerShell 5.1 para Windows como a predefinição na versão de 15/01/2019. Nessa altura, os utilizadores poderão escolher o início de sessão de dispositivo através de um parâmetro de mudança (Switch).

Alterações interruptivas do módulo

Esta secção fornece detalhes sobre alterações interruptivas específicas para cmdlets e módulos individuais.

Az.ApiManagement (anteriormente AzureRM.ApiManagement)

• Foram removidos os seguintes cmdlets:
  • New-AzureRmApiManagementHostnameConfiguration
  • Set-AzureRmApiManagementHostnames
  • Update-AzureRmApiManagementDeployment
  • Import-AzureRmApiManagementHostnameCertificate
  • Em alternativa, utilize o cmdlet Set-AzApiManagement para definir estas propriedades
• Foram removidas as seguintes propriedades:
  • As propriedades PortalHostnameConfiguration, ProxyHostnameConfiguration, ManagementHostnameConfiguration e ScmHostnameConfiguration do tipo PsApiManagementHostnameConfiguration foram removidas de PsApiManagementContext. Em vez disso, utilize PortalCustomHostnameConfiguration, ProxyCustomHostnameConfiguration, ManagementCustomHostnameConfiguration e ScmCustomHostnameConfiguration do tipo PsApiManagementCustomHostNameConfiguration.
  • A propriedade StaticIPs foi removida de PsApiManagementContext. A propriedade foi dividida em PublicIPAddresses e PrivateIPAddresses.
  • A propriedade necessária Location foi removida 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 terão de utilizar outros parâmetros de identidade para a faturação.

Az.Compute (anteriormente AzureRM.Compute)

• Os IdentityIds foram removidos da propriedade Identity nos objetos PSVirtualMachine e PSVirtualMachineScaleSet. Os scripts devem deixar de utilizar o valor deste campo para tomar decisões de processamento.
• O tipo de propriedade InstanceView do objeto PSVirtualMachineScaleSetVM foi alterado de VirtualMachineInstanceView para VirtualMachineScaleSetVMInstanceView
• As propriedades AutoOSUpgradePolicy e AutomaticOSUpgrade foram removidas da propriedade UpgradePolicy
• O tipo de propriedade Sku no objeto PSSnapshotUpdate foi alterado de DiskSku para SnapshotSku
• VmScaleSetVMParameterSet foi removido do cmdlet Add-AzVMDataDisk. Já não pode adicionar um disco de dados individualmente a uma VM de conjunto de dimensionamento (ScaleSet).

Az.KeyVault (anteriormente AzureRM.KeyVault)

• A propriedade PurgeDisabled foi removida dos objetos PSKeyVaultKeyAttributes, PSKeyVaultKeyIdentityItem e PSKeyVaultSecretAttributes. Os scripts devem deixar de fazer referência à propriedade PurgeDisabled para tomar decisões de processamento.

Az.Monitor (anteriormente AzureRM.Insights)

• Os nomes de parâmetros no plural Categories e Timegrains foram removidos em prol de nomes de parâmetros no singular do cmdlet Set-AzDiagnosticSetting. Os scripts que utilizam

  Set-AzureRmDiagnosticSetting -Timegrains PT1M -Categories Category1, Category2
  

  Devem ser alterados para

  Set-AzDiagnosticSetting -Timegrain PT1M -Category Category1, Category2
  

Az.Network (anteriormente AzureRM.Network)

• O parâmetro preterido ResourceId foi removido do cmdlet Get-AzServiceEndpointPolicyDefinition
• A propriedade preterida EnableVmProtection foi removida do objeto PSVirtualNetwork
• O cmdlet preterido Set-AzVirtualNetworkGatewayVpnClientConfig foi removido

Os scripts devem deixar de tomar decisões de processamento com base nos valores destes campos.

Az.Resources (anteriormente AzureRM.Resources)

• O parâmetro Sku foi removido do cmdlet New/Set-AzPolicyAssignment

• O parâmetro Password foi removido dos cmdlets New-AzADServicePrincipal e New-AzADSpCredential. As palavras-passe são geradas automaticamente e o scripts que forneciam a palavra-passe:

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

  Devem ser alterados de modo a obterem a palavra-passe a partir da saída:

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

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

• Para suportar a criação de um contexto de armazenamento de Oauth com apenas o nome da conta de armazenamento, o conjunto de parâmetros predefinido 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 utilizam agora o Padrão Assíncrono Baseado em Tarefas (TAP), em vez de chamadas síncronas à API. Os exemplos seguintes demonstram os novos comandos assíncronos:

Instantâneo de blobs

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

Partilhar 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

Anular eliminação do blob eliminado de forma recuperável

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 blobs

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)

• As propriedades preteridas foram removidas dos objetos PSAppServicePlan, PSCertificate, PSCloningInfo e PSSite

Passos seguintes

• Saiba mais sobre o PowerShell no Azure Stack Hub. Veja Introdução ao PowerShell no Azure Stack Hub
• Instale o módulo Az do PowerShell, veja Instalar o módulo do PowerShell Az para o Azure Stack Hub