Partager via

Migrer d’AzureRM vers Azure PowerShell Az dans Azure Stack Hub

  • Article

Le module Az a une parité de fonctionnalité avec AzureRM, mais utilise des noms d’applets de commande plus courts et plus cohérents. Les scripts écrits pour les applets de commande AzureRM ne fonctionnent pas automatiquement avec le nouveau module. Pour faciliter la transition, Az offre des outils pour vous permettre d’exécuter vos scripts existants à l’aide d’AzureRM. Aucune migration vers un nouveau jeu de commandes n’est jamais pratique, mais cet article vous aidera à commencer à passer au nouveau module.

Pour afficher la liste complète des modifications majeures entre AzureRM et Az, consultez le guide de migration pour Az 1.0.0

Rechercher les versions installées d’AzureRM

Avant de suivre les étapes de migration, vérifiez quelles versions d’AzureRM sont installées sur votre système. Cela vous permet de vous assurer que les scripts sont déjà en cours d’exécution sur la dernière version et indiquez si vous pouvez activer des alias de commande sans désinstaller AzureRM.

Pour vérifier la ou les versions d’AzureRM que vous avez installées, exécutez la commande :

Get-InstalledModule -Name AzureRM -AllVersions

Vérifier que les scripts actuels fonctionnent avec AzureRM

C’est l’étape la plus importante ! Exécutez vos scripts existants et assurez-vous qu’ils fonctionnent avec la dernière version d’AzureRM (2.5.0). Si vos scripts ne fonctionnent pas, veillez à lire le guide de migration AzureRM.

Installer le module Azure PowerShell Az

La première étape consiste à installer le module Az sur votre plateforme. Lorsque vous installez Az, il est recommandé de désinstaller AzureRM. Dans les étapes suivantes, vous allez apprendre à continuer à exécuter vos scripts existants et à activer la compatibilité pour les anciens noms d’applet de commande.

Pour installer le module Azure PowerShell Az, procédez comme suit :

Activer les alias de compatibilité AzureRM

Important

Activez uniquement le mode de compatibilité si vous avez désinstallé toutes les versions d’AzureRM. L’activation du mode de compatibilité avec les applets de commande AzureRM toujours disponibles peut entraîner un comportement imprévisible. Ignorez cette étape si vous avez décidé de conserver AzureRM installé, mais sachez que toutes les applets de commande AzureRM utilisent les anciens modules et n’appellent pas d’applets de commande Az.

Avec AzureRM désinstallé et vos scripts qui fonctionnent avec la dernière version d’AzureRM, l’étape suivante consiste à activer le mode de compatibilité pour le module Az. La compatibilité est activée avec la commande :

Enable-AzureRmAlias -Scope CurrentUser

Les alias permettent d’utiliser les anciens noms d’applet de commande avec le module Az installé. Ces alias sont enregistrés dans le profil utilisateur pour l’étendue sélectionnée. Si aucun profil utilisateur n’existe, il en est créé un.

Avertissement

Vous pouvez utiliser une autre -Scope pour cette commande, mais il n’est pas recommandé. Les alias sont écrits dans le profil utilisateur pour l’étendue sélectionnée. Ainsi, poursuivez leur activation pour une étendue aussi limitée que possible. L'activation des alias à l'échelle du système peut également entraîner des problèmes pour d'autres utilisateurs pour lesquels AzureRM est installé dans leur environnement local.

Une fois le mode alias activé, réexécutez vos scripts pour confirmer qu’ils fonctionnent toujours comme prévu.

Modifier les noms des modules et des applets de commande

En général, les noms des modules ont été modifiés afin que AzureRM et Azure deviennent Az, et les mêmes pour les applets de commande. Par exemple, le module AzureRM.Compute a été renommé en Az.Compute. New-AzureRMVM est devenu New-AzVM, et Get-AzureStorageBlob est maintenant Get-AzStorageBlob.

Il existe des exceptions à cette modification de nommage dont vous devez être conscient. Certains modules ont été renommés ou fusionnés dans des modules existants sans affecter le suffixe de leurs applets de commande, autre que la modification de AzureRM ou de Azure à Az. Sinon, le suffixe complet de l’applet de commande a été modifié pour refléter le nouveau nom du module.

Module AzureRM Module Az Le suffixe de la cmdlet a-t-il été modifié ?
AzureRM.Profile Az.Accounts Oui
AzureRM.Insights Az.Monitor Oui
AzureRM.Tags Az.Resources Non
AzureRM.UsageAggregates Az.Billing Non
AzureRM.Consumption Az.Billing Non

Résumé

En suivant ces étapes, vous pouvez mettre à jour tous vos scripts existants pour utiliser le nouveau module. Si vous avez des questions ou des problèmes avec ces étapes qui ont rendu votre migration difficile, veuillez commenter cet article afin que nous puissions améliorer les instructions.

Changements cassants pour Az 1.0.0

Ce document fournit des informations détaillées sur les modifications entre AzureRM 6.x et le nouveau module Az, version 1.x et ultérieure. La table des matières vous aidera à parcourir un chemin de migration complet, y compris les modifications spécifiques au module susceptibles d’affecter vos scripts.

Dernières modifications générales

Cette section détaille les changements cassants généraux qui font partie de cette reconception du module Az.

Modifications des préfixes des noms des applets de commande

Dans le module AzureRM, les applets de commande ont utilisé AzureRM ou Azure comme préfixe de nom. Az simplifie et normalise les noms des applets de commande afin que toutes les applets de commande utilisent « Az » comme préfixe de nom d’applet de commande. Par exemple:

Get-AzureRMVM
Get-AzureKeyVaultSecret

A changé en :

Get-AzVM
Get-AzKeyVaultSecret

Pour simplifier la transition vers ces nouveaux noms d’applets de commande, Az introduit deux nouvelles applets de commande, Enable-AzureRmAlias et Disable-AzureRmAlias. Enable-AzureRmAlias crée des alias pour les anciens noms d’applets de commande dans AzureRM qui correspondent aux noms d’applets de commande Az plus récents. L’utilisation de l’argument -Scope avec Enable-AzureRmAlias vous permet de choisir l’emplacement où les alias sont activés.

Par exemple, le script suivant dans AzureRM :

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

Peut être exécuté avec des modifications minimales à l’aide de Enable-AzureRmAlias:

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

L’exécution de Enable-AzureRmAlias -Scope CurrentUser active les alias pour toutes les sessions PowerShell que vous ouvrez, de sorte qu’après l’exécution de cette applet de commande, un script semblable à celui-ci n’a pas besoin d’être modifié du tout :

Get-AzureRmStorageAccount | Get-AzureStorageContainer | Get-AzureStorageBlob

Pour plus d’informations sur l’utilisation des alias des applets de commande, consultez les Informations de référence sur Enable-AzureRmAlias.

Lorsque vous êtes prêt à désactiver les alias, Disable-AzureRmAlias supprime les alias créés. Pour des détails complets, voir la référence Disable-AzureRmAlias.

Important

Quand vous désactivez les alias, vérifiez qu’ils sont désactivés pour toutes les étendues où les alias étaient activés.

Modifications du nom du module

Les noms des modules ont changé de AzureRM.* à Az.*, à l’exception des modules suivants :

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

Les modifications apportées aux noms de modules signifient que tout script qui utilise #Requires ou Import-Module pour charger des modules spécifiques doit être modifié pour utiliser le nouveau module à la place. Pour les modules où le suffixe d’applet de commande n’a pas changé, cela signifie que même si le nom du module a changé, le suffixe indiquant l’espace d’opération n’a pas.

Migration des instructions requires et d’importation de module

Les scripts qui utilisent #Requires ou Import-Module pour déclarer une dépendance sur les modules AzureRM doivent être mis à jour pour utiliser les nouveaux noms de modules. Par exemple:

#Requires -Module AzureRM.Compute

Doit être remplacé par :

#Requires -Module Az.Compute

Pour Import-Module:

Import-Module -Name AzureRM.Compute

Doit être remplacé par :

Import-Module -Name Az.Compute

Migration des appels d’applets de commande complets

Les scripts qui utilisent des appels d’applets de commande qualifiés par module, comme :

AzureRM.Compute\Get-AzureRmVM

Doit être modifié pour utiliser les nouveaux noms de module et d’applet de commande :

Az.Compute\Get-AzVM

Migration des dépendances de manifeste de module

Les modules qui expriment des dépendances sur les modules AzureRM via un fichier manifeste de module (.psd1) doivent mettre à jour les noms des modules dans leur section RequiredModules :

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

Doit être remplacé par :

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

Modules supprimés

Les modules suivants ont été supprimés :

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

Les outils de ces services ne sont plus pris en charge activement. Les clients sont encouragés à passer à des services alternatifs dès qu’il est pratique.

Windows PowerShell 5.1 et .NET 4.7.2

L’utilisation d’Az avec PowerShell 5.1 pour Windows nécessite l’installation de .NET Framework 4.7.2. L’utilisation de PowerShell Core 6.x ou version ultérieure ne nécessite pas .NET Framework.

Suppression temporaire de la connexion utilisateur à l’aide de PSCredential

En raison des modifications apportées au flux d’authentification pour .NET Standard, nous supprimons temporairement la connexion utilisateur via PSCredential. Cette fonctionnalité sera re-introduite dans la version 1/15/2019 de PowerShell 5.1 pour Windows. Les détails sont abordés dans ce problème GitHub.

Connexion via le code d’appareil par défaut au lieu de l’invite du navigateur web

En raison des modifications apportées au flux d’authentification pour .NET Standard, nous utilisons la connexion de l’appareil comme flux de connexion par défaut lors de la connexion interactive. La connexion basée sur un navigateur web sera réinitie pour PowerShell 5.1 pour Windows comme valeur par défaut dans la version 1/15/2019. À ce stade, les utilisateurs pourront choisir la connexion de l’appareil à l’aide d’un paramètre Switch.

Changements cassants de module

Cette section détaille les changements cassants spécifiques à des applets de commande et des modules individuels.

Az.ApiManagement (précédemment AzureRM.ApiManagement)

  • Suppression des applets de commande suivantes :
    • New-AzureRmApiManagementHostnameConfiguration
    • Set-AzureRmApiManagementHostnames
    • Update-AzureRmApiManagementDeployment
    • Import-AzureRmApiManagementHostnameCertificate
    • Utilisez le cmdlet Set-AzApiManagement pour définir ces propriétés à la place.
  • Suppression des propriétés suivantes :
    • Suppression des propriétés PortalHostnameConfiguration, ProxyHostnameConfiguration, ManagementHostnameConfiguration et ScmHostnameConfiguration de type PsApiManagementHostnameConfiguration de PsApiManagementContext. Utilisez plutôt PortalCustomHostnameConfiguration, ProxyCustomHostnameConfiguration, ManagementCustomHostnameConfiguration et ScmCustomHostnameConfiguration de type PsApiManagementCustomHostNameConfiguration.
    • La propriété StaticIPs a été supprimée de PsApiManagementContext. La propriété a été divisée en PublicIPAddresses et PrivateIPAddresses.
    • Suppression de la propriété obligatoire Location dans la cmdlet New-AzureApiManagementVirtualNetwork.

Az.Billing (précédemment AzureRM.Billing, AzureRM.Consumption et AzureRM.UsageAggregates)

  • Le paramètre InvoiceName a été supprimé de l’applet de commande Get-AzConsumptionUsageDetail. Les scripts devront utiliser d’autres paramètres d’identité pour la facture.

Az.Compute (précédemment AzureRM.Compute)

  • Les IdentityIds ont été supprimés de la propriété Identity dans les objets PSVirtualMachine et PSVirtualMachineScaleSet. Les scripts ne devraient plus utiliser la valeur de ce champ pour prendre des décisions de traitement.
  • Le type de propriété InstanceView de l’objet PSVirtualMachineScaleSetVM est remplacé de VirtualMachineInstanceView à VirtualMachineScaleSetVMInstanceView
  • les propriétés AutoOSUpgradePolicy et AutomaticOSUpgrade sont supprimées de la propriété UpgradePolicy
  • Le type de propriété Sku dans PSSnapshotUpdate objet est remplacé de DiskSku à SnapshotSku
  • VmScaleSetVMParameterSet est supprimé de Add-AzVMDataDisk applet de commande, vous ne pouvez plus ajouter un disque de données individuellement à une machine virtuelle ScaleSet.

Az.KeyVault (précédemment AzureRM.KeyVault)

  • La propriété PurgeDisabled a été supprimée des objets PSKeyVaultKeyAttributes, PSKeyVaultKeyIdentityItem, et PSKeyVaultSecretAttributes; les scripts ne doivent plus référencer la propriété PurgeDisabled pour prendre des décisions de traitement.

Az.Monitor (précédemment AzureRM.Insights)

  • Suppression des paramètres pluriels Categories et Timegrains, remplacés par des noms de paramètres singuliers dans les scripts utilisant l’applet de commande Set-AzDiagnosticSetting.

    Set-AzureRmDiagnosticSetting -Timegrains PT1M -Categories Category1, Category2

    Doit être remplacé par

    Set-AzDiagnosticSetting -Timegrain PT1M -Category Category1, Category2

Az.Network (précédemment AzureRM.Network)

  • Suppression du paramètre ResourceId, désormais obsolète, de l’applet de commande Get-AzServiceEndpointPolicyDefinition
  • Suppression de la propriété déconseillée EnableVmProtection de l’objet PSVirtualNetwork
  • Suppression de la cmdlet déconseillée Set-AzVirtualNetworkGatewayVpnClientConfig

Les scripts ne doivent plus prendre de décisions de traitement en fonction des valeurs de ces champs.

Az.Resources (précédemment AzureRM.Resources)

  • Paramètre Sku supprimé de l’applet de commande New/Set-AzPolicyAssignment

  • Suppression du paramètre Password dans les cmdlets New-AzADServicePrincipal et New-AzADSpCredential. Les mots de passe sont automatiquement générés. Tout script qui a fourni le mot de passe :

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

    Doit être modifié pour récupérer le mot de passe à partir de la sortie :

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

Az.Storage (précédemment Azure.Storage et AzureRM.Storage)

  • Pour prendre en charge la création d’un contexte de stockage Oauth avec uniquement le nom du compte de stockage, le jeu de paramètres par défaut a été modifié en OAuthParameterSet
    • Exemple : $ctx = New-AzureStorageContext -StorageAccountName $accountName
  • Le paramètre Location est devenu obligatoire dans l’applet de commande Get-AzStorageUsage
  • Les méthodes d’API de stockage utilisent désormais le modèle asynchrone basé sur les tâches (TAP) au lieu d’appels d’API synchrones. Les exemples suivants illustrent les nouvelles commandes asynchrones :

Instantané d’objet 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

Partager un instantané

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

Annuler la suppression d’un objet blob supprimé de manière réversible

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

Définir un niveau d’objet 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 (précédemment AzureRM.Websites)

  • Suppression des propriétés déconseillées des objets PSAppServicePlan, PSCertificate, PSCloningInfoet PSSite

Étapes suivantes