Pemecahan masalah modul Az PowerShell

Mengaktifkan pengelogan debug

Salah satu langkah pertama yang harus Anda ambil dalam memecahkan masalah dengan modul Az PowerShell adalah mengaktifkan pengelogan debug.

Untuk mengaktifkan pengelogan debug berdasarkan perintah, tentukan parameter Debug.

Get-AzResource -Name 'DoesNotExist' -Debug

Untuk mengaktifkan pengelogan debug untuk seluruh sesi PowerShell, Anda menetapkan nilai variabel DebugPreference menjadi Continue.

$DebugPreference = 'Continue'

Masalah umum: Penginstalan modul Az dari MAR gagal

Saat menginstal modul Az PowerShell tertentu dari Microsoft Artefact Registry (MAR) menggunakan PSResourceGet, Anda mungkin mengalami kesalahan seperti:

Install-PSResource: Package(s) 'Az.Keyvault' could not be installed from repository 'MAR'.

Note

Sebagai solusi sementara, instal modul dari repositori lain, seperti PowerShell Gallery, hingga masalah diselesaikan.

Untuk informasi selengkapnya, lihat Bugfix untuk membandingkan nama jalur file untuk menentukan kecocokan yang tepat.

Pemecahan masalah autentikasi multifaktor (MFA)

Kegagalan masuk interaktif

Jika Anda mengalami kesalahan saat menjalankan cmdlet Azure PowerShell yang membuat, memodifikasi, atau menghapus sumber daya, masalah tersebut mungkin disebabkan oleh kebijakan Akses Bersyarat Microsoft Entra ID yang memerlukan autentikasi multifaktor (MFA).

Kesalahan ini biasanya terjadi ketika otentikasi multi-faktor (MFA) diperlukan oleh kebijakan tetapi tidak diberlakukan saat proses masuk.

Autentikasi SharedTokenCacheCredential tidak tersedia

Anda mungkin melihat kesalahan ini saat menggunakan:

  • Az Modul PowerShell versi 14.2.0 atau yang lebih lama
  • Modul PowerShell Az.Accounts versi 5.1.1 atau yang lebih lama
SharedTokenCacheCredential authentication unavailable. Token acquisition failed for user
someone@contoso.com. Ensure that you have authenticated with a developer tool that supports Azure
single sign on.

Tingkatkan ke versi berikut atau yang lebih baru untuk menerima pesan kesalahan dan detail kebijakan yang lebih informatif:

  • Az Modul PowerShell: versi 14.3.0 atau yang lebih baru
  • Modul Az.Accounts: versi 5.2.0 atau yang lebih baru

Sumber daya tidak diizinkan oleh kebijakan

Kesalahan ini terjadi dalam versi modul yang lebih baru (Az 14.3.0+ dan Az.Accounts 5.2.0+), di mana MFA diperlukan oleh Akses Bersyarat untuk operasi tertentu.

Resource was disallowed by policy. Users must use MFA for Create operation.
Users must authenticate with multi-factor authentication to create or update resources.
Run the cmdlet below to authenticate interactively; additional parameters may be added as needed.
Connect-AzAccount -Tenant (Get-AzContext).Tenant.Id -ClaimsChallenge "<claims-challenge-token>"

Pilihan resolusi

  • Minta administrator Azure Anda untuk menerapkan MFA saat masuk. Ini memungkinkan sesi Anda memenuhi persyaratan Akses Bersyarat tanpa langkah tambahan.

  • Jika penerapan MFA saat masuk tidak dimungkinkan, gunakan parameter ClaimsChallenge untuk mengautentikasi secara interaktif:

    Connect-AzAccount -Tenant (Get-AzContext).Tenant.Id -ClaimsChallenge "<claims-challenge-token>"

Untuk informasi selengkapnya, lihat Merencanakan autentikasi multifaktor wajib untuk Azure dan portal admin lainnya

Kesalahan ROPC: Karena perubahan konfigurasi yang dilakukan oleh administrator Anda

Anda menggunakan alur Kredensial Kata Sandi Pemilik Sumber Daya (ROPC) saat menggunakan kata sandi untuk masuk ke Azure. Metode autentikasi ini tidak mendukung MFA. Berikut adalah sebuah contoh:

Connect-AzAccount -Credential $Credential

Jika akun pengguna memerlukan MFA, perintah gagal dengan kesalahan berikut:

Connect-AzAccount : UsernamePasswordCredential authentication failed: Response status code does not
indicate success: 400 (BadRequest). See the troubleshooting guide for more information
https://aka.ms/azsdk/net/identity/usernamepasswordcredential/troubleshoot

solusi : Gunakan metode autentikasi yang kompatibel dengan MFA.

Peringatan lintas penyewa: Autentikasi gagal terhadap tenant

Jika Anda memiliki akses ke beberapa penyewa, dan salah satunya memerlukan MFA, Azure PowerShell mungkin menampilkan peringatan berikut:

WARNING: Unable to acquire token for tenant '00000000-0000-0000-0000-000000000000' with error
'Authentication failed against tenant 00000000-0000-0000-0000-000000000000. User interaction is
required. This may be due to the conditional access policy settings such as multi-factor
authentication (MFA). If you need to access subscriptions in that tenant, please rerun
'Connect-AzAccount' with additional parameter '-TenantId 00000000-0000-0000-0000-000000000000.'

Azure PowerShell mencoba masuk dengan penyewa pertama yang ditemukan selama masuk. Jika penyewa tersebut memberlakukan MFA, autentikasi mungkin gagal. Untuk menghindari masalah ini, tentukan penyewa target secara eksplisit menggunakan parameter TenantId:

Connect-AzAccount -TenantId 00000000-0000-0000-0000-000000000000

Ini memastikan bahwa autentikasi dicoba terhadap penyewa yang benar, mengurangi kemungkinan kegagalan terkait MFA.

Pesan pengumuman dalam skenario otomatisasi

Saat menyambungkan ke Azure dengan Azure PowerShell, pesan pengumuman ditampilkan menggunakan aliran informasi PowerShell untuk mencegahnya mengubah output berbasis objek yang dikembalikan. Meskipun kami telah melakukan setiap upaya untuk memastikan pesan pengumuman tidak memengaruhi pengalaman Anda, ada beberapa skenario otomatisasi di mana pesan tersebut dapat memengaruhi penggunaan. Jika Anda mengalami masalah, kami sarankan Anda menekan aliran informasi dalam skenario tersebut:

Connect-AzAccount -Subscription '<subscription name or id>' -InformationAction Ignore

Pengelola Akun Web (WAM)

  • Metode masuk interaktif tidak dapat membuka jendela untuk WAM dan mengembalikan kesalahan: Pengguna membatalkan autentikasi.
  • Cmdlet Azure PowerShell tidak dapat berjalan setelah masuk dengan nama pengguna dan kata sandi atau kode perangkat.
  • Jendela popup WAM tidak menampilkan opsi Akun Kantor dan Sekolah.
  • Metode masuk interaktif tidak dapat membuka jendela WAM di konsol ISE PowerShell Windows.

Solusi untuk masalah ini adalah menonaktifkan WAM:

Update-AzConfig -EnableLoginByWam $false
  • Jendela popup WAM untuk memilih akun tidak mudah ditemukan. Minimalkan jendela lain untuk menemukan jendela popup.

Installation

Bagian ini berisi daftar solusi untuk masalah umum saat menginstal modul Az PowerShell.

Koeksistensi Az dan AzureRM

Peringatan

Kami tidak mendukung penginstalan modul AzureRM dan Az PowerShell di Windows PowerShell 5.1 secara bersamaan.

Dalam skenario di mana Anda perlu menginstal modul AzureRM dan Az PowerShell pada sistem Windows yang sama:

  • AzureRM harus diinstal hanya dalam cakupan pengguna Windows PowerShell 5.1 saat ini.
  • Instal modul Az PowerShell di PowerShell 7.2 atau yang lebih tinggi.

Peringatan

Modul AzureRM PowerShell telah resmi tidak digunakan lagi per 29 Februari 2024. Pengguna disarankan untuk bermigrasi dari AzureRM ke modul Az PowerShell untuk memastikan dukungan dan pembaruan yang berkelanjutan.

Meskipun modul AzureRM mungkin masih berfungsi, modul ini tidak lagi dipelihara atau didukung, sehingga penggunaan yang berkelanjutan menjadi tanggung jawab dan risiko pengguna. Silakan merujuk ke sumber daya migrasi kami untuk petunjuk dalam beralih ke modul Az.

Visual Studio

Versi Visual Studio yang lebih lama dapat menginstal Azure PowerShell sebagai bagian dari beban kerja pengembangan Azure, yang menginstal modul AzureRM. Azure PowerShell dapat dihapus menggunakan penginstal Visual Studio atau dengan menggunakan "Uninstall" di Aplikasi & fitur. Jika Anda telah menginstal PowerShell 7.x, Anda mungkin perlu menginstal modul Az PowerShell secara manual.

Koneksi diblokir oleh proksi

Jika Anda mendapatkan pesan kesalahan dari Install-Module bahwa Galeri PowerShell tidak dapat dijangkau, mungkin Anda berada di belakang proksi. Sistem operasi dan lingkungan jaringan yang berbeda memiliki persyaratan yang berbeda untuk mengonfigurasi proksi di seluruh sistem. Hubungi administrator sistem untuk pengaturan proksi Anda dan cara mengonfigurasinya untuk lingkungan Anda.

PowerShell sendiri mungkin tidak dikonfigurasi untuk menggunakan proksi ini secara otomatis. Dengan PowerShell 5.1 dan yang lebih baru, konfigurasikan sesi PowerShell untuk menggunakan proksi menggunakan perintah berikut:

$webClient = New-Object -TypeName System.Net.WebClient
$webClient.Proxy.Credentials = [System.Net.CredentialCache]::DefaultNetworkCredentials

Jika kredensial sistem operasi Anda dikonfigurasi dengan benar, konfigurasi ini merutekan permintaan PowerShell melalui proksi. Agar pengaturan ini bertahan di antara sesi, tambahkan perintah ke profil PowerShell Anda.

Untuk menginstal paket, proksi Anda harus mengizinkan koneksi HTTPS ke www.powershellgallery.com.

Referensi objek tidak diatur ke instance objek

Pesan "referensi objek tidak disetel ke instans objek" berarti Anda merujuk ke objek yang bernilai null, sumber daya Azure yang tidak ada, atau Anda tidak memiliki izin untuk mengaksesnya.

$resourceId =  '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/<resource-group-name>/providers/Microsoft.Web/sites/<webapp-name>/privateEndpointConnections/<endpoint-name>'
Get-AzPrivateEndpointConnection -ResourceId $resourceId

Get-AzPrivateEndpointConnection: Object reference not set to an instance of an object.

Anda dapat menggunakan cmdlet Get-AzResource untuk memverifikasi bahwa sumber daya Azure yang ditentukan ada.

Get-AzResource -ResourceId $resourceId

Masalah izin dengan cmdlet AzAD

Modul Az PowerShell menggunakan Microsoft Graph API. Mengelola atau mengelola sumber daya di Azure dengan modul Az PowerShell memerlukan izin yang sama seperti melakukan tugas yang identik dari portal Microsoft Azure atau alat baris perintah Azure lainnya. Untuk pertanyaan spesifik tentang izin, lihat referensi izin Microsoft Graph.

Parameter Microsoft Graph untuk kueri

Cmdlet AzAd pada Az.Resources kini mendukung parameter kueri dan parameter kueri pencarian. Untuk detail tentang sintaks, lihat tautan yang dirujuk sebelumnya.

Get-AzAdGroupMember tidak mengembalikan prinsipal layanan

Karena keterbatasan dengan Graph API saat ini, layanan prinsipal tidak dapat dikembalikan oleh Get-AzAdGroupMember di Az 7.x. Sebagai solusinya, Invoke-AzRestMethod dapat digunakan dengan versi beta dari API Microsoft Graph.

Contoh berikut memerlukan modul Az PowerShell. Ganti myGroupName di baris pertama dengan nama grup Anda.

$Group = Get-AzADGroup -DisplayName myGroupName
((Invoke-AzRestMethod -Uri "https://graph.microsoft.com/beta/groups/$($Group.id)/members").Content |
  ConvertFrom-Json).value |
  Select-Object -Property DisplayName, Id, @{label='OdataType';expression={$_.'@odata.type'}}

Perintah ditemukan tetapi tidak dapat dimuat

Pesan berikut dikembalikan oleh PowerShell saat Anda mencoba menjalankan salah satu perintah Az PowerShell.

Connect-AzAccount: The 'Connect-AzAccount' command was found in the module 'Az.Accounts', but the module could not be loaded. For more information, run 'Import-Module Az.Accounts'.

Pesan ini terjadi ketika Anda menginstal modul Az dan AzureRM PowerShell pada sistem berbasis Windows yang sama dan modul tersebut ada di $env:PSModulePath untuk versi PowerShell yang sama.

Important

Saat AzureRM diinstal dalam cakupan AllUsers Windows PowerShell, AzureRM diinstal di lokasi yang merupakan bagian dari $env:PSModulePath untuk PowerShell 7. Ini tidak didukung karena konflik antara modul AzureRM dan Az PowerShell.

Az dan AzureRM dapat hidup berdampingan pada sistem Windows yang sama, tetapi hanya jika AzureRM diinstal dalam cakupan CurrentUser Windows PowerShell dan Az yang diinstal di PowerShell 7. Untuk informasi selengkapnya, lihat Menginstal modul Az PowerShell.

Peringatan

Modul AzureRM PowerShell telah resmi tidak digunakan lagi per 29 Februari 2024. Pengguna disarankan untuk bermigrasi dari AzureRM ke modul Az PowerShell untuk memastikan dukungan dan pembaruan yang berkelanjutan.

Meskipun modul AzureRM mungkin masih berfungsi, modul ini tidak lagi dipelihara atau didukung, sehingga penggunaan yang berkelanjutan menjadi tanggung jawab dan risiko pengguna. Silakan merujuk ke sumber daya migrasi kami untuk petunjuk dalam beralih ke modul Az.

Di MacOS, kesalahan akan kembali terjadi saat otorisasi KeyChain gagal

Saat menjalankan Azure PowerShell di MacOS, Anda mungkin mengalami pesan kesalahan saat mencoba masuk ke akun Azure Anda dari sesi PowerShell.

DeviceCodeCredential authentication failed: Persistence check failed. Reason: KeyChain authorization/authentication failed. .Error code: -25293. OS error code -25293.

Sebagai solusi untuk masalah ini, Anda dapat menonaktifkan penyimpanan kredensial antar sesi dengan menjalankan perintah berikut. Namun, setelah membuat perubahan ini, Anda perlu menjalankan Connect-AzAccount setiap kali Anda memulai sesi PowerShell baru.

Disable-AzContextAutosave

Sambungan untuk situs ini tidak aman

Saat browser default Anda adalah Microsoft Edge, Anda mungkin mengalami kesalahan berikut saat mencoba masuk ke Azure secara interaktif dengan Connect-AzAccount: "Koneksi untuk situs ini tidak aman." Untuk mengatasi masalah ini, kunjungi edge://net-internals/#hsts di Microsoft Edge. Tambahkan localhost di bawah "Hapus kebijakan keamanan domain" dan klik Hapus.

Kesalahan verifikasi domain pada Service Principal IdentifierUri

Kesalahan: Nilai properti IdentifierUris harus menggunakan domain terverifikasi dari organisasi atau subdomainnya ditampilkan saat menjalankan New-AzADServicePrincipal atau New-AzADApplication.

Karena perubahan signifikan pada Microsoft Entra yang mengharuskan AppId Uri dalam aplikasi penyewa tunggal agar menggunakan skema default atau domain terverifikasi, Anda harus meningkatkan modul Az.Resources ke versi 4.1.0 atau lebih baru untuk terus menggunakan cmdlet New-AzADServicePrincipal atau New-AzADApplication.

Anda juga dapat meningkatkan ke modul Az PowerShell versi 6.0 atau yang lebih tinggi.

Timeline

Persyaratan mulai berlaku 15 Oktober 2021.

Versi yang terdampak

Versi Azure PowerShell berikut terdampak oleh perubahan signifikan di AzureAD:

  • Modul Az.Resources PowerShell versi 3.5.1-preview atau lebih rendah.
  • Modul Az PowerShell versi 5.9.0 atau lebih rendah.

Jika Anda masih mengalami masalah setelah pemutakhiran, jangan ragu untuk membuka issue.

Penanganan masalah

Jika Anda tidak dapat meningkatkan ke modul PowerShell yang dijelaskan sebelumnya, Anda dapat mengikuti langkah-langkah tersebut saat membuat perwakilan layanan:

Masalah Lain

Jika Anda mengalami masalah produk dengan Azure PowerShell yang tidak tercantum dalam artikel ini atau memerlukan bantuan lebih lanjut, ajukan masalah di GitHub.

  • Last updated on