Migrar do AzureRM para Azure PowerShell Az no Azure Stack Hub

  • Artigo

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:

Ativar aliases de compatibilidade do AzureRM

Importante

Ative o modo de compatibilidade apenas se tiver desinstalado todas as versões do AzureRM. A ativação do modo de compatibilidade com os cmdlets do AzureRM ainda disponíveis pode resultar num comportamento imprevisível. Ignore este passo se optar por manter o AzureRM instalado, mas tenha em atenção que os cmdlets do AzureRM irão utilizar os módulos mais antigos e não vão chamar quaisquer cmdlets do Az.

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.

Aviso

Pode utilizar um -Scope diferente para este comando, mas tal não é recomendado. Os aliases são escritos para o perfil de utilizador para o âmbito selecionado, por isso continue a permitir que tenham um âmbito o mais limitado possível. A ativação dos aliases no sistema em geral também pode causar problemas a outros utilizadores que tenham o AzureRM instalado no respetivo âmbito local.

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.

Módulo do AzureRM Módulo do Az O sufixo do cmdlet foi alterado?
AzureRM.Profile Az.Accounts Yes
AzureRM.Insights Az.Monitor Yes
AzureRM.Tags Az.Resources No
AzureRM.UsageAggregates Az.Billing No
AzureRM.Consumption Az.Billing No

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.

Importante

Quando desativar aliases, certifique-se de que estão desativados para todos os âmbitos que tiveram aliases ativados.

Alterações de nomes de módulos

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

Módulo do AzureRM Módulo do 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

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 1f99cf81-0146-4f4e-beae-2007d0668476 -Password $secPassword

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

    $credential = New-AzAdSpCredential -ObjectId 1f99cf81-0146-4f4e-beae-2007d0668476
$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