Condividi tramite

Eseguire la migrazione da AzureRM a Azure PowerShell Az nell'hub di Azure Stack

  • Articolo

Il modulo Az offre parità delle funzionalità rispetto ad AzureRM, ma usa nomi di cmdlet più brevi e coerenti. Gli script scritti per i cmdlet di AzureRM non funzioneranno automaticamente con il nuovo modulo. Per facilitare la transizione, Az offre strumenti che consentono di eseguire gli script esistenti con AzureRM. Per quanto nessuna migrazione a un nuovo set di comandi sia immediata, questo articolo consentirà di iniziare la transizione al nuovo modulo.

Per visualizzare l'elenco completo delle modifiche che causano un'interruzione tra AzureRM e Az, vedere Guida alla migrazione per Az 1.0.0

Controllo delle versioni installate di AzureRM

Prima di eseguire i passaggi di migrazione, verificare quali versioni di AzureRM sono installate nel sistema. In questo modo è possibile assicurarsi che gli script siano già in esecuzione nella versione più recente e sapere se è possibile abilitare gli alias dei comandi senza disinstallare AzureRM.

Per controllare quale versione di AzureRM è stata installata, eseguire il comando:

Get-InstalledModule -Name AzureRM -AllVersions

Controllare che gli script correnti funzionino con AzureRM

È il passaggio più importante. Eseguire gli script esistenti e assicurarsi che funzionino con la versione più recente di AzureRM (2.5.0). Se gli script non funzionano, vedere la guida alla migrazione per AzureRM.

Installare il modulo Az di Azure PowerShell

Il primo passaggio consiste nell'installare il modulo Az nella piattaforma. Quando si installa Az, è consigliabile disinstallare AzureRM. I passaggi riportati di seguito illustreranno come continuare a eseguire gli script esistenti e abilitare la compatibilità per i nomi dei cmdlet precedenti.

Per installare il modulo Az di Azure PowerShell, seguire questa procedura:

Abilitare gli alias per la compatibilità di AzureRM

Importante

Abilitare la modalità di compatibilità solo se sono state disinstallate tutte le versioni di AzureRM. L'abilitazione della modalità di compatibilità con i cmdlet di AzureRM ancora disponibili può causare comportamenti imprevisti. Ignorare questo passaggio se si è scelto di mantenere AzureRM installato, ma tenere presente che qualsiasi cmdlet di AzureRM userà i moduli precedenti e non chiamerà i cmdlet di Az.

Dopo la verifica del funzionamento degli script con l'ultima versione di AzureRM e la disinstallazione di AzureRM, il passaggio successivo consiste nell'abilitare la modalità compatibilità per il modulo Az. La compatibilità viene abilitata con questo comando:

Enable-AzureRmAlias -Scope CurrentUser

Gli alias offrono la possibilità di usare i nomi dei cmdlet precedenti con il modulo Az installato. Gli alias vengono scritti nel profilo utente per l'ambito selezionato. Se non esistono profili utente, ne viene creato uno.

Avviso

È possibile usare un valore di -Scope diverso per il comando, ma non è consigliabile. Dato che gli alias vengono scritti nel profilo utente per l'ambito selezionato, abilitarli per un ambito il più limitato possibile. L'abilitazione degli alias a livello di sistema potrebbe anche causare problemi per altri utenti nel cui ambito locale è installato AzureRM.

Dopo aver abilitato la modalità alias, eseguire di nuovo gli script per verificare che continuino a funzionare come previsto.

Modificare i nomi del modulo e dei cmdlet

In generale, i nomi del modulo e i cmdlet sono stati modificati sostituendo AzureRM e Azure con Az. Il modulo AzureRM.Compute, ad esempio, è stato rinominato Az.Compute. New-AzureRMVM è diventato New-AzVM e Get-AzureStorageBlob è ora Get-AzStorageBlob.

È opportuno essere a conoscenza delle eccezioni a tale modifica dei nomi. Alcuni moduli sono stati rinominati o uniti in moduli esistenti senza che questo influenzi il suffisso dei relativi cmdlet, a parte la modifica di AzureRM o Azure in Az. Diversamente il suffisso del cmdlet completo è stato modificato per riflettere il nuovo nome del modulo.

Modulo AzureRM Modulo Az Modifica del suffisso del cmdlet
AzureRM.Profile Az.Accounts Sì
AzureRM.Insights Az.Monitor Sì
AzureRM.Tags Az.Resources No
AzureRM.UsageAggregates Az.Billing No
AzureRM.Consumption Az.Billing No

Riepilogo

Seguendo questi passaggi è possibile aggiornare tutti gli script esistenti in modo da usare il nuovo modulo. In caso di domande o problemi con questi passaggi che hanno reso difficile la migrazione, lasciare un commento su questo articolo per consentire un miglioramento delle istruzioni.

Modifiche che causano un'interruzione per Az 1.0.0

Questo documento include informazioni dettagliate sulle modifiche apportate nella migrazione da AzureRM 6.x al nuovo modulo Az 1.x e versioni successive. Il sommario include tutti i passaggi di un percorso di migrazione completo, incluse le modifiche specifiche dei singoli moduli che potrebbero influire sugli script.

Modifiche di rilievo di carattere generale

Questa sezione illustra in dettaglio le modifiche di rilievo di carattere generale incluse nella riprogettazione del modulo Az.

Modifiche del prefisso del nome del cmdlet

Nel modulo AzureRM come prefisso dei nomi dei cmdlet si usava AzureRM o Azure. Az semplifica e normalizza i nomi dei cmdlet, in modo che tutti i cmdlet usino 'Az' come prefisso dei nomi dei cmdlet. Ad esempio:

Get-AzureRMVM
Get-AzureKeyVaultSecret

È stato modificato in:

Get-AzVM
Get-AzKeyVaultSecret

Per semplificare la transizione a questi nuovi nomi dei cmdlet, Az introduce due nuovi cmdlet, ovvero Enable-AzureRmAlias e Disable-AzureRmAlias. Enable-AzureRmAlias crea gli alias per i nomi dei cmdlet precedenti in AzureRM per i quali viene eseguito il mapping ai nuovi nomi dei cmdlet Az. Se si usa l'argomento -Scope con Enable-AzureRmAlias, è possibile scegliere dove abilitare gli alias.

Ad esempio, lo script seguente in AzureRM:

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

Può essere eseguito con modifiche minime usando Enable-AzureRmAlias:

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

L'esecuzione di Enable-AzureRmAlias -Scope CurrentUser abilita gli alias per tutte le sessioni di PowerShell che vengono aperte, in modo che dopo l'esecuzione di questo cmdlet non sarà necessario modificare uno script simile al seguente:

Get-AzureRmStorageAccount | Get-AzureStorageContainer | Get-AzureStorageBlob

Per informazioni dettagliate sull'utilizzo dei cmdlet alias, vedere la guida di riferimento per Enable-AzureRmAlias.

Quando si è pronti per disabilitare gli alias, usare Disable-AzureRmAlias per rimuovere gli alias creati. Per informazioni dettagliate, vedere la guida di riferimento per Disable-AzureRmAlias.

Importante

Quando si disabilitano gli alias, assicurarsi che vengano disabilitati per tutti gli ambiti in cui erano abilitati.

Modifiche ai nomi dei moduli

I nomi dei moduli sono stati modificati da AzureRM.* a Az.*, fatta eccezione per i moduli seguenti:

Modulo AzureRM Modulo 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

Le modifiche nei nomi dei moduli significano che tutti gli script che usano #Requires o Import-Module per caricare moduli specifici dovranno essere modificati per usare il nuovo modulo. Per i moduli in cui il suffisso del cmdlet non è cambiato, anche se il nome del modulo è cambiato il suffisso che indica lo spazio dell'operazione non ha subito variazioni.

La migrazione richiede e importare istruzioni del modulo

Gli script che usano #Requires o Import-Module per dichiarare una dipendenza dai moduli AzureRM devono essere aggiornati in modo che usino i nuovi nomi dei moduli. Ad esempio:

#Requires -Module AzureRM.Compute

Devono essere modificati in:

#Requires -Module Az.Compute

Per Import-Module:

Import-Module -Name AzureRM.Compute

Devono essere modificati in:

Import-Module -Name Az.Compute

Migrazione di chiamate di cmdlet complete

Gli script che usano le chiamate dei cmdlet qualificate di modulo, come:

AzureRM.Compute\Get-AzureRmVM

Devono essere modificati in modo che usino i nuovi nomi dei moduli e dei cmdlet:

Az.Compute\Get-AzVM

Migrazione delle dipendenze del manifesto del modulo

I moduli che esprimono le dipendenze dai moduli AzureRM tramite un file del manifesto del modulo (con estensione psd1) dovranno aggiornare i nomi dei moduli nella sezione RequiredModules:

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

Devono essere modificati in:

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

Moduli rimossi

I moduli seguenti sono stati rimossi:

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

Gli strumenti per questi servizi non sono più supportati attivamente. I clienti sono invitati a passare a servizi alternativi non appena possibile.

Windows PowerShell 5.1 e .NET 4.7.2

Per usare Az con PowerShell 5.1 per Windows è richiesta l'installazione di .NET Framework 4.7.2. Se invece si usa PowerShell Core 6.x o versioni successive, .NET Framework non è richiesto.

Rimozione temporanea dell'account di accesso utente tramite PSCredential

A causa delle modifiche nel flusso di autenticazione per .NET Standard verrà temporaneamente rimosso l'accesso utente tramite PSCredential. Questa funzionalità sarà reintrodotta nella versione del 15/01/2019 per PowerShell 5.1 per Windows. Questa modifica è descritta in dettaglio in questo problema di GitHub.

Accesso predefinito del codice dispositivo anziché del prompt del Web browser

A causa delle modifiche nel flusso di autenticazione per .NET Standard, viene usato l'accesso del dispositivo come flusso di accesso predefinito durante l'accesso interattivo. L'accesso basato su Web browser verrà reintrodotto per PowerShell 5.1 per Windows come impostazione predefinita nella versione del 15/01/2019. A quel punto, gli utenti potranno scegliere l'accesso del dispositivo usando un parametro Switch.

Modifiche che causano un'interruzione dei moduli

Questa sezione illustra in dettaglio le modifiche di rilievo per singoli cmdlet e moduli.

Az.ApiManagement (in precedenza AzureRM.ApiManagement)

  • Sono stati rimossi i cmdlet seguenti:
    • New-AzureRmApiManagementHostnameConfiguration
    • Set-AzureRmApiManagementHostnames
    • Update-AzureRmApiManagementDeployment
    • Import-AzureRmApiManagementHostnameCertificate
    • Usare il cmdlet Set-AzApiManagement per impostare queste proprietà
  • Sono state rimosse le proprietà seguenti:
    • Sono state rimosse le proprietà PortalHostnameConfiguration, ProxyHostnameConfiguration, ManagementHostnameConfiguration e ScmHostnameConfiguration di tipo PsApiManagementHostnameConfiguration da PsApiManagementContext. Usare PortalCustomHostnameConfiguration, ProxyCustomHostnameConfiguration, ManagementCustomHostnameConfiguration e ScmCustomHostnameConfiguration di tipo PsApiManagementCustomHostNameConfiguration.
    • È stata rimossa la proprietà StaticIPs da PsApiManagementContext. La proprietà è stata suddivisa in PublicIPAddresses e PrivateIPAddresses.
    • È stata rimossa la proprietà obbligatoria Location dal cmdlet New-AzureApiManagementVirtualNetwork.

Az.Billing (in precedenza AzureRM.Billing, AzureRM.Consumption e AzureRM.UsageAggregates)

  • Il parametro InvoiceName è stato rimosso dal cmdlet Get-AzConsumptionUsageDetail. Gli script dovranno usare altri parametri di identità per la fatturazione.

Az.Compute (in precedenza AzureRM.Compute)

  • IdentityIds è stato rimosso dalla proprietà Identity negli oggetti PSVirtualMachine e PSVirtualMachineScaleSet. Gli script non devono più usare il valore di questo campo per le decisioni di elaborazione.
  • Il tipo della proprietà InstanceView dell'oggetto PSVirtualMachineScaleSetVM è stato modificato da VirtualMachineInstanceView a VirtualMachineScaleSetVMInstanceView
  • Le proprietà AutoOSUpgradePolicy e AutomaticOSUpgrade sono state rimosse dalla proprietà UpgradePolicy
  • Il tipo della proprietà Sku nell'oggetto PSSnapshotUpdate è stato modificato da DiskSku a SnapshotSku
  • VmScaleSetVMParameterSet è stato rimosso dal cmdlet Add-AzVMDataDisk. Non è più possibile aggiungere singolarmente un disco dati a una macchina virtuale del set di scalabilità.

Az.KeyVault (in precedenza AzureRM.KeyVault)

  • La proprietà PurgeDisabled è stata rimossa dagli oggetti PSKeyVaultKeyAttributes, PSKeyVaultKeyIdentityItem e PSKeyVaultSecretAttributes. Gli script non devono più fare riferimento alla proprietà PurgeDisabled per le decisioni di elaborazione.

Az.Monitor (in precedenza AzureRM.Insights)

  • Sono stati rimossi i nomi plurali del parametro Categories e Timegrains sostituendoli con nomi di parametro singolari dal cmdlet Set-AzDiagnosticSetting. Lo script che usa

    Set-AzureRmDiagnosticSetting -Timegrains PT1M -Categories Category1, Category2

    Deve essere modificato in

    Set-AzDiagnosticSetting -Timegrain PT1M -Category Category1, Category2

Az.Network (in precedenza AzureRM.Network)

  • È stato rimosso il parametro ResourceId deprecato dal cmdlet Get-AzServiceEndpointPolicyDefinition
  • È stata rimossa la proprietà EnableVmProtection deprecata dall'oggetto PSVirtualNetwork
  • È stato rimosso il cmdlet Set-AzVirtualNetworkGatewayVpnClientConfig deprecato

Gli script non devono più prendere decisioni di elaborazione in base ai valori di questi campi.

Az.Resources (in precedenza AzureRM.Resources)

  • È stato rimosso il parametro Sku dal cmdlet New/Set-AzPolicyAssignment

  • È stato rimosso il parametro Password dal cmdlet New-AzADServicePrincipal e New-AzADSpCredential. Le password vengono generate automaticamente e gli script che fornivano la password:

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

    Devono essere modificati per recuperare la password dall'output:

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

Az.Storage (in precedenza Azure.Storage e AzureRM.Storage)

  • Per supportare la creazione di un contesto di archiviazione Oauth con solo il nome dell'account di archiviazione, il set di parametri predefinito è stato modificato in OAuthParameterSet
    • Esempio: $ctx = New-AzureStorageContext -StorageAccountName $accountName
  • Il parametro Location è diventato obbligatorio nel cmdlet Get-AzStorageUsage
  • I metodi dell'API di archiviazione usano ora il Modello asincrono basato su attività (TAP), invece delle chiamate API sincrone. Gli esempi seguenti illustrano i nuovi comandi asincroni:

Snapshot BLOB

Modulo AzureRM:

$b = Get-AzureStorageBlob -Container $containerName -Blob $blobName -Context $ctx
$b.ICloudBlob.Snapshot()

Modulo Az:

$b = Get-AzStorageBlob -Container $containerName -Blob $blobName -Context $ctx
$task = $b.ICloudBlob.SnapshotAsync()
$task.Wait()
$snapshot = $task.Result

Condividi snapshot

Modulo AzureRM:

$Share = Get-AzureStorageShare -Name $containerName -Context $ctx
$snapshot = $Share.Snapshot()

Modulo Az:

$Share = Get-AzStorageShare -Name $containerName -Context $ctx
$task = $Share.SnapshotAsync()
$task.Wait()
$snapshot = $task.Result

Annullare l'eliminazione del BLOB eliminato temporaneamente

Modulo AzureRM:

$b = Get-AzureStorageBlob -Container $containerName -Blob $blobName -IncludeDeleted -Context $ctx
$b.ICloudBlob.Undelete()

Modulo Az:

$b = Get-AzStorageBlob -Container $containerName -Blob $blobName -IncludeDeleted -Context $ctx
$task = $b.ICloudBlob.UndeleteAsync()
$task.Wait()

Impostare il livello di BLOB

Modulo 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")

Modulo 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 (in precedenza AzureRM.Websites)

  • Sono state rimosse le proprietà deprecate dagli oggetti PSAppServicePlan, PSCertificate, PSCloningInfo e PSSite

Passaggi successivi