Menggunakan API web pemeriksa Power Apps

Api web pemeriksa Power Apps menyediakan mekanisme untuk menjalankan pemeriksaan analisis statis terhadap penyesuaian dan ekstensi pada platform Microsoft Dataverse. Pembuat dan pengembang dapat melakukan pemeriksaan analisis statis kaya pada solusi mereka terhadap rangkaian aturan praktik terbaik untuk dengan cepat mengidentifikasi pola masalah ini. Layanan menyediakan logika untuk fitur pemeriksa solusi di portal pembuat Power Apps dan disertakan sebagai bagian dari otomatisasi untuk aplikasi yang dikirim ke AppSource. Berinteraksi dengan layanan secara langsung dengan cara ini memungkinkan analisis solusi yang disertakan sebagai bagian dari lokal (semua versi yang didukung) dan lingkungan online.

Untuk informasi tentang menggunakan layanan pemeriksa dari kode PowerShell, lihat Bekerja dengan solusi menggunakan PowerShell.

Pendekatan alternatif

Sebelum membaca detail tentang cara berinteraksi pada tingkat terendah dengan API web, pertimbangkan untuk menggunakan modul PowerShell kami, Microsoft.PowerApps. Checker.PowerShell, sebagai gantinya. Ini adalah alat yang didukung penuh yang tersedia di Galeri PowerShell. Pembatasan saat ini adalah bahwa ia memerlukan Windows PowerShell. Jika tidak dapat memenuhi persyaratan ini, maka berinteraksi dengan API secara langsung adalah pendekatan terbaik.

Mulai

Penting untuk dicatat bahwa analisis solusi dapat menghasilkan proses yang berjalan lama. Biasanya diperlukan waktu enam puluh (60) detik hingga lebih dari lima (5) menit tergantung pada berbagai faktor, seperti jumlah, ukuran, dan kompleksitas penyesuaian dan kode. Alur analisis adalah awal multi-langkah dan asinkron dengan memulai pekerjaan analisis dengan API status yang digunakan untuk kueri penyelesaian pekerjaan. Contoh alur untuk analisis adalah sebagai berikut:

1. Dapatkan OAuth token
2. Upload panggilan (untuk setiap file secara paralel)
3. Analisis panggilan (memprakarsai pekerjaan analisis)
4. Status panggilan hingga selesai (looping dengan jeda di antara panggilan hingga akhir ditandai atau ambang batas terpenuhi)
5. Unduh hasil dari URI SAS yang disediakan

Beberapa variasi adalah:

• Sertakan pencarian rangkaian aturan atau aturan sebagai pra-langkah. Namun, akan sedikit lebih cepat untuk memasukkan ID set aturan berkode keras yang telah dikonfigurasi. Disarankan agar Anda menggunakan ruleset yang memenuhi kebutuhan Anda.
• Anda dapat memilih untuk tidak menggunakan mekanisme Unggah (Lihat upload untuk batasan).

Anda perlu menentukan persyaratan berikut:

• Geografi yang mana?
• Versi yang mana?
• Kumpulan aturan dan aturan yang mana?
• Apa ID penyewa Anda?

Lihat artikel berikut untuk dokumentasi tentang masing-masing API:

Mengambil daftar kumpulan aturan
Mengambil daftar aturan
Mengupload file
Panggil analisis
Periksa status analisis

Tentukan geografi

Saat Anda berinteraksi dengan Power Apps layanan pemeriksa, file disimpan sementara di Azure bersama dengan laporan yang dihasilkan. Dengan menggunakan API khusus geografi, Anda dapat mengontrol lokasi penyimpanan data. Permintaan ke titik akhir geografi dirutekan ke instans kawasan berdasarkan performa terbaik (latensi pemohon). Setelah permintaan memasukkan instans Layanan Regional, semua pemrosesan dan data yang disimpan tetap berada di kawasan tersebut. Respons API tertentu mengembalikan URL instans regional untuk permintaan berikutnya setelah tugas analisis dirutekan ke wilayah tertentu. Setiap geografi mungkin memiliki versi layanan yang berbeda yang disebarkan pada titik waktu tertentu. Penggunaan versi layanan yang berbeda disebabkan oleh proses penerapan aman multi-tahap, yang memastikan kompatibilitas versi penuh. Dengan demikian, geografi yang sama harus digunakan untuk setiap panggilan API di siklus hidup analisis dan dapat mengurangi waktu eksekusi keseluruhan karena data mungkin tidak harus melakukan perjalanan sejauh itu melalui kabel. Geografi yang tersedia adalah sebagai berikut:

Versi

Meskipun tidak diperlukan, disarankan untuk menyertakan parameter string kueri api-version dengan versi API yang diinginkan. Versi API saat ini adalah 2.0 untuk kumpulan aturan dan aturan dan 1.0 untuk semua permintaan lainnya. Misalnya, kumpulan aturan berikut adalah permintaan HTTP yang menentukan untuk menggunakan versi API 2.0:

https://unitedstatesfirstrelease.api.advisor.powerapps.com/api/ruleset?api-version=2.0

Jika tidak disediakan, versi API terbaru digunakan secara default. Disarankan untuk menggunakan nomor versi eksplisit karena versi bertambah jika perubahan yang melanggar diperkenalkan. Jika nomor versi ditentukan dalam permintaan, dukungan kompatibilitas mundur di versi lebih baru (numerik lebih besar) akan dipertahankan.

Set aturan dan aturan

pemeriksa Power Apps memerlukan daftar aturan saat dijalankan. Aturan ini dapat diberikan dalam bentuk aturan individual atau pengelompokan aturan, yang disebut sebagai ruleset. Ruleset adalah cara mudah untuk menentukan grup aturan daripada harus menentukan setiap aturan individual. Contohnya, fitur pemeriksa solusi menggunakan ruleset bernama Solution Checker. Saat aturan baru ditambahkan atau dihapus, layanan menyertakan perubahan ini secara otomatis tanpa memerlukan perubahan apa pun oleh aplikasi yang menggunakan. Jika Anda memerlukan daftar aturan tidak berubah secara otomatis seperti yang dijelaskan di atas, maka aturan dapat ditentukan secara terpisah. Ruleset dapat memiliki satu atau beberapa aturan tanpa batas. Aturan dapat berupa tanpa atau beberapa ruleset. Anda dapat memperoleh daftar semua aturan dengan memanggil API sebagai berikut: [Geographical URL]/api/ruleset. Titik akhir ini sekarang memerlukan autentikasi.

Set aturan Solution checker

Ruleset solution checker berisi seperangkat aturan yang berdampak yang memiliki peluang terbatas untuk positif palsu. Jika menjalankan analisis terhadap solusi yang ada, Anda disarankan untuk memulai dengan kumpulan aturan ini. Kumpulan aturan ini digunakan oleh fitur pemeriksa solusi.

ruleset sertifikasi AppSource

Saat memublikasikan aplikasi AppSource, Anda harus mendapatkan sertifikasi aplikasi. Aplikasi yang dipublikasikan diharuskan AppSource memenuhi standar kualitas tinggi. Kumpulan AppSource aturan sertifikasi berisi aturan yang merupakan bagian dari kumpulan aturan pemeriksa solusi, ditambah aturan lain untuk memastikan hanya aplikasi berkualitas tinggi yang dipublikasikan di toko. Beberapa AppSource aturan sertifikasi lebih rentan terhadap positif palsu dan mungkin memerlukan lebih banyak perhatian untuk menyelesaikannya.

Temukan ID penyewa Anda

ID penyewa Anda diperlukan untuk berinteraksi dengan api yang memerlukan Token. Lihat artikel ini untuk rincian tentang cara mendapatkan id penyewa. Anda juga dapat menggunakan perintah PowerShell untuk mengambil ID penyewa. Contoh berikut menerapkan cmdlet dalam modul AzureAD.

# Login to Microsoft Entra ID as your user
Connect-AzureAD

# Establish your tenant ID
$tenantId = (Get-AzureADTenantDetail).ObjectId

ID penyewa adalah nilai properti ObjectId yang dihasilkan dari Get-AzureADTenantDetail. Anda juga dapat melihatnya setelah masuk menggunakan cmdlet Connect-AzureAD di output cmdlet. Dalam hal ini, itu akan diberi nama TenantId.

Otentikasi dan otorisasi

Mengkueri aturan dan kumpulan aturan tidak memerlukan OAuth token, tetapi semua API lainnya memerlukan token. Api mendukung penemuan otorisasi dengan memanggil salah satu api yang memerlukan Token. Responsnya adalah kode status HTTP 401 yang tidak sah dengan header WWW-Authenticated, URI otorisasi, dan ID sumber daya. Anda juga harus menyediakan ID penyewa di header x-ms-tenant-id. Lihat Autentikasi Power Apps dan otorisasi Pemeriksa untuk informasi selengkapnya. Berikut ini adalah contoh header respons yang dikembalikan dari permintaan API:

WWW-Authenticate →Bearer authorization_uri="https://login.microsoftonline.com/0082fff7-33c5-44c9-920c-c2009943fd1e", resource_id="https://api.advisor.powerapps.com/"

Setelah Anda memiliki informasi ini, Anda dapat memilih untuk menggunakan Microsoft Authentication Library (MSAL) atau beberapa mekanisme lain untuk memperoleh token. Berikut ini adalah contoh bagaimana hal ini dapat dilakukan menggunakan C# dan pustaka MSAL .NET :

// Substitute your own environment URL here.
string resource = "https://<env-name>.api.<region>.dynamics.com";

// Example Microsoft Entra app registration.
// For your custom apps, you will need to register them with Microsoft Entra ID yourself.
// See https://docs.microsoft.com/powerapps/developer/data-platform/walkthrough-register-app-azure-active-directory
var clientId = "51f81489-12ee-4a9e-aaae-a2591f45987d";
var redirectUri = "http://localhost"; // Loopback required for the interactive login.

var authBuilder = PublicClientApplicationBuilder.Create(clientId)
    .WithAuthority(AadAuthorityAudience.AzureAdMultipleOrgs)
    .WithRedirectUri(redirectUri)
    .Build();
var scope = resource + "/.default";
string[] scopes = { scope };

AuthenticationResult tokenResult =
     await authBuilder.AcquireTokenInteractive(scopes).ExecuteAsync();

Untuk kode kerja lengkap, lihat contoh Mulai Cepat API Web.

Setelah Anda memperoleh token, disarankan agar Anda memberikan token yang sama untuk panggilan berikutnya dalam siklus hidup permintaan. Namun, lebih banyak permintaan mungkin menjamin token baru diperoleh karena alasan keamanan.

Keamanan transportasi

Untuk enkripsi terbaik di kelasnya, layanan pemeriksa hanya mendukung komunikasi menggunakan Transport Layer Security (TLS) 1.2 dan yang lebih tinggi. Untuk panduan praktik terbaik .NET di sekitar TLS, lihat praktik terbaik Transport Layer Security (TLS) dengan .NET Framework.

Format Laporan

Hasil analisis solusi adalah file zip yang berisi satu atau beberapa laporan dalam format JSON standar. Format laporan didasarkan pada hasil analisis statis yang disebut sebagai Static Analysis Results Interchange Format (SARIF). Tersedia alat bantu untuk menampilkan dan berinteraksi dengan dokumen SARIF. Untuk informasi lebih lanjut, lihat situs web ini. Layanan ini menggunakan versi dua dari standar OASIS.

Baca juga

Mengambil daftar kumpulan aturan
Mengambil daftar aturan
Mengupload file
Panggil analisis
Periksa status analisis