Migrowanie z modułu AzureRM do modułu Azure PowerShell Az w usłudze Azure Stack Hub

  • Artykuł

Moduł Az zapewnia równoważność funkcji z modułem AzureRM, jednak używa krótszych i bardziej spójnych nazw poleceń cmdlet. Skrypty napisane dla poleceń cmdlet modułu AzureRM nie będą automatycznie działać z nowym modułem. Aby ułatwić przejście, moduł Az oferuje narzędzia umożliwiające uruchamianie istniejących skryptów przy użyciu modułu AzureRM. Każda migracja do nowego zestawu poleceń jest kłopotliwa, jednak ten artykuł pomoże Ci rozpocząć przejście do nowego modułu.

Aby wyświetlić pełną listę zmian powodujących niezgodność między modułami AzureRM i Az, zobacz Przewodnik migracji modułu Az 1.0.0

Sprawdzanie pod kątem zainstalowanych wersji modułu AzureRM

Przed wykonaniem jakichkolwiek kroków związanych z migracją sprawdź, które wersje modułu AzureRM są zainstalowane w systemie. Dzięki temu możesz się upewnić, że skrypty są już uruchamiane w najnowszej wersji, i dowiedzieć, czy możesz włączyć aliasy poleceń bez odinstalowywania modułu AzureRM.

Aby sprawdzić, które wersje modułu AzureRM są zainstalowane, uruchom polecenie:

Get-InstalledModule -Name AzureRM -AllVersions

Sprawdzanie, czy bieżące skrypty działają z modułem AzureRM

To jest najważniejszy krok! Uruchom istniejące skrypty i upewnij się, że działają z najnowszą wersją modułu AzureRM (2.5.0). Jeśli Twoje skrypty nie działają, zapoznaj się z przewodnikiem po migracji modułu AzureRM.

Instalowanie modułu Az programu Azure PowerShell

Pierwszym krokiem jest zainstalowanie modułu Az na Twojej platformie. Po zainstalowaniu modułu Az zaleca się odinstalowanie modułu AzureRM. W poniższych krokach opisano, co zrobić, aby istniejące skrypty nadal działały, i jak włączyć zgodność ze starymi nazwami poleceń cmdlet.

Aby zainstalować moduł Az programu Azure PowerShell, wykonaj następujące kroki:

Włączanie aliasów zapewniających zgodność z modułem AzureRM

Ważne

Tryb zgodności włącz tylko wtedy, gdy zostały odinstalowane wszystkie wersje modułu AzureRM. Włączenie trybu zgodności, gdy polecenia cmdlet modułu AzureRM są nadal dostępne, może spowodować nieprzewidywalne zachowanie. Pomiń ten krok, jeśli chcesz pozostawić zainstalowany moduł AzureRM, ale pamiętaj, że wszelkie polecenia cmdlet modułu AzureRM będą używać starszych modułów i nie będą wywoływać żadnych poleceń cmdlet modułu Az.

Po upewnieniu się, że skrypty działają z najnowszą wersją modułu AzureRM, i odinstalowaniu modułu AzureRM następny krok to włączenie trybu zgodności dla modułu Az. Zgodność należy włączyć za pomocą polecenia:

Enable-AzureRmAlias -Scope CurrentUser

Aliasy umożliwiają używanie starych nazw poleceń cmdlet po zainstalowaniu modułu Az. Te aliasy są wpisane w profil użytkownika dla wybranego zakresu. Jeśli profil użytkownika nie istnieje, jest on tworzony.

Ostrzeżenie

Dla tego polecenia możesz użyć innego parametru -Scope, ale nie jest to zalecane. Aliasy są wpisane w profil użytkownika dla wybranego zakresu, dlatego włączaj je dla tak ograniczonego zakresu, jak to możliwe. Włączenie aliasów dla całego systemu może także spowodować problemy dla innych użytkowników, którzy mają zainstalowany moduł AzureRM w swoim zakresie lokalnym.

Po włączeniu trybu aliasów ponownie uruchom skrypty, aby potwierdzić, że nadal działają zgodnie z oczekiwaniami.

Zmienianie nazw modułów i poleceń cmdlet

Ogólnie rzecz biorąc, nazwy modułu zostały zmienione tak, aby nazwy AzureRM i Azure stały się nazwą Az — to samo dotyczy poleceń cmdlet. Na przykład nazwa modułu AzureRM.Compute została zmieniona na Az.Compute. Polecenie New-AzureRMVM stało się poleceniem New-AzVM, a polecenie Get-AzureStorageBlob to teraz polecenie Get-AzStorageBlob.

Istnieją wyjątki od tej reguły zmiany nazw, o których należy wiedzieć. Nazwy niektórych modułów zostały zmienione lub te moduły zostały scalone z istniejącymi modułami, przy czym nie miało to wpływu na sufiks ich poleceń cmdlet poza zmianą ciągu AzureRM lub Azure na Az. W pozostałych przypadkach pełny sufiks polecenia cmdlet został zmieniony, aby odzwierciedlić nową nazwę modułu.

Moduł AzureRM Moduł Az Czy sufiks poleceń cmdlet uległ zmianie?
AzureRM.Profile Az.Accounts Tak
AzureRM.Insights Az.Monitor Tak
AzureRM.Tags Az.Resources Nie
AzureRM.UsageAggregates Az.Billing Nie
AzureRM.Consumption Az.Billing Nie

Podsumowanie

Wykonując powyższe czynności, można zaktualizować wszystkie istniejące skrypty w celu korzystania z nowego modułu. Jeśli masz jakiekolwiek pytania lub problemy dotyczące tych kroków, które utrudniały migrację, dodaj komentarz do tego artykułu, abyśmy mogli ulepszyć instrukcje.

Zmiany powodujące niezgodność w module Az 1.0.0

Ten dokument zawiera szczegółowe informacje na temat różnic między modułem AzureRM w wersji 6.x i nowym modułem Az w wersji 1.x i nowszych. Spis treści pomoże przeprowadzić Cię przez pełną ścieżkę migracji, w tym zmiany specyficzne dla modułu, które mogą mieć wpływ na skrypty.

Ogólne zmiany powodujące niezgodność

W tej sekcji przedstawiono ogólne zmiany powodujące niezgodność wprowadzone w ramach przeprojektowania modułu Az.

Zmiany prefiksu noun polecenia cmdlet

W module AzureRM polecenia cmdlet używały ciągu AzureRM lub Azure jako prefiksu w postaci rzeczownika. Moduł Az upraszcza i normalizuje nazwy poleceń cmdlet, więc wszystkie polecenia cmdlet mają prefiks w postaci rzeczownika „Az”. Przykład:

Get-AzureRMVM
Get-AzureKeyVaultSecret

Zmieniono na:

Get-AzVM
Get-AzKeyVaultSecret

Aby ułatwić przejście na te nowe nazwy poleceń cmdlet, moduł Az wprowadza dwa nowe polecenia cmdlet, Enable-AzureRmAlias i Disable-AzureRmAlias. Polecenie cmdlet Enable-AzureRmAlias tworzy aliasy dla starszych nazw poleceń cmdlet w module AzureRM mapowane na nowsze nazwy poleceń cmdlet w module Az. Argument -Scope polecenia cmdlet Enable-AzureRmAlias pozwala wybrać, gdzie aliasy zostaną włączone.

Na przykład poniższy skrypt w module AzureRM:

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

Może zostać uruchomiony tylko z niewielkimi zmianami, jeśli zostanie użyte polecenie cmdlet Enable-AzureRmAlias:

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

Uruchomienie polecenia cmdlet Enable-AzureRmAlias -Scope CurrentUser spowoduje włączenie aliasów dla wszystkich otwieranych sesji programu PowerShell, więc po jego wykonaniu nie trzeba w ogóle zmieniać skryptów podobnych do poniższego:

Get-AzureRmStorageAccount | Get-AzureStorageContainer | Get-AzureStorageBlob

Aby uzyskać szczegółowe informacje dotyczące użycia aliasów poleceń cmdlet, zobacz Dokumentacja polecenia cmdlet Enable-AzureRmAlias.

Gdy wszystko będzie gotowe do wyłączenia aliasów, możesz usunąć utworzone aliasy za pomocą polecenia cmdlet Disable-AzureRmAlias. Aby uzyskać szczegółowe informacje, zobacz Dokumentacja polecenia cmdlet Disable-AzureRmAlias.

Ważne

Podczas wyłączania aliasów upewnij się, że zostaną one wyłączone dla wszystkich zakresów, w których je włączono.

Zmiany nazw modułów

Nazwy modułów zostały zmienione z AzureRM.* na Az.*, z wyjątkiem następujących modułów:

Moduł AzureRM Moduł 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

Zmiany nazw modułów oznaczają, że każdy skrypt, który używa instrukcji #Requires lub Import-Module do ładowania określonych modułów, będzie trzeba zmienić tak, aby używał nowego modułu. Jeśli dla danego modułu sufiks polecenia cmdlet pozostał taki sam, oznacza to, że chociaż nazwa modułu się zmieniła, to sufiks wskazujący obszar operacji nie uległ zmianie.

Migrowanie instrukcji modułu wymaga i importowanie ich

Skrypty używające instrukcji #Requires lub Import-Module do deklarowania zależności od modułów AzureRM należy zaktualizować tak, aby używały nowych nazw modułów. Przykład:

#Requires -Module AzureRM.Compute

Należy zmienić na:

#Requires -Module Az.Compute

Instrukcję Import-Module:

Import-Module -Name AzureRM.Compute

Należy zmienić na:

Import-Module -Name Az.Compute

Migrowanie w pełni kwalifikowanych wywołań poleceń cmdlet

Skrypty używające wywołań poleceń cmdlet kwalifikowanych za pomocą modułu, takie jak:

AzureRM.Compute\Get-AzureRmVM

Należy zmienić tak, aby używały nowych nazw modułów i poleceń cmdlet:

Az.Compute\Get-AzVM

Migrowanie zależności manifestu modułów

W przypadku modułów, w których zależności od modułów AzureRM są wyrażane za pomocą pliku manifestu modułów (psd1), należy zaktualizować nazwy modułów w sekcji RequiredModules:

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

Należy zmienić na:

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

Usunięte moduły

Następujące moduły zostały usunięte:

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

Narzędzia dla tych usług nie są już aktywnie wspierane. Zachęcamy klientów do jak najszybszego przechodzenia do alternatywnych usług.

Windows PowerShell 5.1 i .NET 4.7.2

Korzystanie z modułu Az w programie PowerShell 5.1 dla systemu Windows wymaga zainstalowania programu .NET Framework 4.7.2. Jeśli używasz programu PowerShell Core w wersji 6.x lub nowszej, program .NET Framework nie jest wymagany.

Tymczasowe usunięcie logowania użytkownika przy użyciu obiektu PSCredential

Ze względu na zmiany w przepływie uwierzytelniania dla platformy .NET Standard tymczasowo usuwamy możliwość logowania użytkownika za pomocą obiektu PSCredential. Ta możliwość zostanie ponownie udostępniona w wersji dla programu PowerShell 5.1 dla systemu Windows opublikowanej 15.01.2019. Ta kwestia została szczegółowo omówiona w ramach tego problemu w usłudze GitHub.

Domyślne logowanie za pomocą kodu urządzenia zamiast monitu przeglądarki internetowej

Ze względu na zmiany w przepływie uwierzytelniania dla platformy .NET Standard używamy logowania urządzenia jako domyślnego przepływu logowania podczas logowania interakcyjnego. Logowanie oparte na przeglądarce internetowej ponownie stanie się domyślne dla programu PowerShell 5.1 dla systemu Windows w wersji opublikowanej 15.01.2019. Użytkownicy będą wtedy mogli wybrać logowanie urządzenia za pomocą parametru przełącznika.

Zmiany powodujące niezgodność modułów

W tej sekcji szczegółowo opisano konkretne zmiany powodujące niezgodność w poszczególnych modułach i poleceniach cmdlet.

Az.ApiManagement (wcześniej AzureRM.ApiManagement)

  • Usunięto następujące polecenia cmdlet:
    • New-AzureRmApiManagementHostnameConfiguration
    • Set-AzureRmApiManagementHostnames
    • Update-AzureRmApiManagementDeployment
    • Import-AzureRmApiManagementHostnameCertificate
    • Zamiast nich do ustawiania tych właściwości użyj polecenia cmdlet Set-AzApiManagement
  • Usunięto następujące właściwości:
    • Usunięto właściwości PortalHostnameConfiguration, ProxyHostnameConfiguration, ManagementHostnameConfiguration i ScmHostnameConfiguration typu PsApiManagementHostnameConfiguration z klasy PsApiManagementContext. Zamiast nich używaj właściwości PortalCustomHostnameConfiguration, ProxyCustomHostnameConfiguration, ManagementCustomHostnameConfiguration i ScmCustomHostnameConfiguration typu PsApiManagementCustomHostNameConfiguration.
    • Usunięto właściwość StaticIPs z klasy PsApiManagementContext. Właściwość została podzielona na właściwości PublicIPAddresses i PrivateIPAddresses.
    • Usunięto wymaganą właściwość Location z polecenia cmdlet New-AzureApiManagementVirtualNetwork.

Az.Billing (wcześniej AzureRM.Billing, AzureRM.Consumption i AzureRM.UsageAggregates)

  • Parametr InvoiceName został usunięty z polecenia cmdlet Get-AzConsumptionUsageDetail. W skryptach będzie trzeba używać innych parametrów tożsamości na potrzeby faktury.

Az.Compute (wcześniej AzureRM.Compute)

  • Pole IdentityIds zostało usunięte z właściwości Identity w obiektach PSVirtualMachine i PSVirtualMachineScaleSet. Skrypty nie powinny już używać wartości tego pola do podejmowania decyzji dotyczących przetwarzania.
  • Typ właściwości InstanceView obiektu PSVirtualMachineScaleSetVM został zmieniony z VirtualMachineInstanceView na VirtualMachineScaleSetVMInstanceView
  • Właściwości AutoOSUpgradePolicy i AutomaticOSUpgrade zostały usunięte z właściwości UpgradePolicy
  • Typ właściwości Sku w obiekcie PSSnapshotUpdate został zmieniony z DiskSku na SnapshotSku
  • Zestaw VmScaleSetVMParameterSet został usunięty z polecenia cmdlet Add-AzVMDataDisk. Nie można już dodawać pojedynczego dysku danych do maszyny wirtualnej w zestawie skalowania.

Az.KeyVault (wcześniej AzureRM.KeyVault)

  • Właściwość PurgeDisabled została usunięta z obiektów PSKeyVaultKeyAttributes, PSKeyVaultKeyIdentityItem i PSKeyVaultSecretAttributes. Skrypty nie powinny już odwoływać się do właściwości PurgeDisabled w celu podejmowania decyzji dotyczących przetwarzania.

Az.Monitor (wcześniej AzureRM.Insights)

  • Z polecenia cmdlet Set-AzDiagnosticSetting usunięto parametry o nazwach w liczbie mnogiej Categories i Timegrains, aby zastąpić je nazwami parametrów w liczbie pojedynczej. Skrypty używające kodu

    Set-AzureRmDiagnosticSetting -Timegrains PT1M -Categories Category1, Category2

    Należy zmienić na

    Set-AzDiagnosticSetting -Timegrain PT1M -Category Category1, Category2

Az.Network (wcześniej AzureRM.Network)

  • Usunięto przestarzały parametr ResourceId z polecenia cmdlet Get-AzServiceEndpointPolicyDefinition
  • Usunięto przestarzałą właściwość EnableVmProtection z obiektu PSVirtualNetwork
  • Usunięto przestarzałe polecenie cmdlet Set-AzVirtualNetworkGatewayVpnClientConfig

Skrypty nie powinny już podejmować decyzji dotyczących przetwarzania na podstawie wartości tych pól.

Az.Resources (wcześniej AzureRM.Resources)

  • Usunięto parametr Sku z polecenia cmdlet New/Set-AzPolicyAssignment

  • Usunięto parametr Password z poleceń cmdlet New-AzADServicePrincipal i New-AzADSpCredential. Hasła są generowane automatycznie, a skrypty, które podawały hasło:

    New-AzAdSpCredential -ObjectId 1f99cf81-0146-4f4e-beae-2007d0668476 -Password $secPassword

    Należy zmienić tak, aby uzyskiwały hasło z danych wyjściowych:

    $credential = New-AzAdSpCredential -ObjectId 1f99cf81-0146-4f4e-beae-2007d0668476
$secPassword = $credential.Secret

Az.Storage (wcześniej Azure.Storage i AzureRM.Storage)

  • Aby obsługiwać tworzenie kontekstu magazynu OAuth za pomocą tylko nazwy konta magazynu, domyślny zestaw parametrów został zmieniony na OAuthParameterSet
    • Przykład: $ctx = New-AzureStorageContext -StorageAccountName $accountName
  • Parametr Location stał się obowiązkowy w poleceniu cmdlet Get-AzStorageUsage
  • Metody interfejsu API magazynu używają teraz wzorca asynchronicznego opartego na zadaniach zamiast synchronicznych wywołań interfejsu API. W poniższych przykładach pokazano nowe polecenia asynchroniczne:

Migawka obiektu 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

Udostępnianie migawki

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

Cofanie usunięcia nietrwale usuniętego obiektu blob

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

Ustawianie warstwy obiektu 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 (wcześniej AzureRM.Websites)

  • Usunięto przestarzałe właściwości z obiektów PSAppServicePlan, PSCertificate, PSCloningInfo i PSSite

Następne kroki