Menggunakan API web pemeriksa Power Apps

Artikel
05/01/2024

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.

Catatan

Penggunaan pemeriksa Power Apps tidak menjamin bahwa impor solusi akan berhasil. Pemeriksaan analisis statis yang dilakukan terhadap solusi tidak mengetahui status dikonfigurasi dari lingkungan tujuan dan keberhasilan impor mungkin tergantung pada solusi atau konfigurasi lain di lingkungan.

Pendekatan alternatif

Sebelum membaca detail tentang cara berinteraksi di tingkat terendah dengan API web, pertimbangkan untuk menggunakan modul PowerShell kami, MicrosoftPowerApps. 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.

Persiapan

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:

Mendapatkan token OAuth
Upload panggilan (untuk setiap file secara paralel)
Analisis panggilan (memprakarsai pekerjaan analisis)
Status panggilan hingga selesai (looping dengan jeda di antara panggilan hingga akhir ditandai atau ambang batas terpenuhi)
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?
Set aturan dan aturan yang mana?
Apa ID penyewa Anda?

Lihat artikel berikut untuk dokumentasi tentang API individual:

Ambil daftar rangkaian aturan
Ambil daftar aturan
Unggah file
Minta analisis
Memeriksa 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 diterapkan pada titik waktu tertentu. Penggunaan versi layanan yang berbeda disebabkan oleh proses penyebaran aman multi-tahap, yang memastikan kompatibilitas versi lengkap. 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:

Pusat data Azure	Nama	Geografi	URI dasar
Publik	Pratinjau	Amerika Serikat	unitedstatesfirstrelease.api.advisor.powerapps.com
Publik	Produksi	Amerika Serikat	unitedstates.api.advisor.powerapps.com
Publik	Produksi	Eropa	europe.api.advisor.powerapps.com
Publik	Produksi	Asia	asia.api.advisor.powerapps.com
Publik	Produksi	Australia	australia.api.advisor.powerapps.com
Publik	Produksi	Jepang	japan.api.advisor.powerapps.com
Publik	Produksi	India	india.api.advisor.powerapps.com
Publik	Produksi	Kanada	canada.api.advisor.powerapps.com
Publik	Produksi	Amerika Selatan	southamerica.api.advisor.powerapps.com
Publik	Produksi	Inggris Raya	unitedkingdom.api.advisor.powerapps.com
Publik	Produksi	Prancis	france.api.advisor.powerapps.com
Publik	Produksi	Jerman	germany.api.advisor.powerapps.com
Publik	Produksi	Uni Emirat Arab	unitedarabemirates.api.advisor.powerapps.com
Publik	Produksi	Swiss	switzerland.api.advisor.powerapps.com
Publik	Produksi	Afrika Selatan	southafrica.api.advisor.powerapps.com
Publik	Produksi	Korea Selatan	korea.api.advisor.powerapps.com
Publik	Produksi	Norwegia	norway.api.advisor.powerapps.com
Publik	Produksi	Singapura	singapore.api.advisor.powerapps.com
Publik	Produksi	Swedia	sweden.api.advisor.powerapps.com
Publik	Produksi	US Government	gov.api.advisor.powerapps.us
Publik	Produksi	Pemerintah AS L4	high.api.advisor.powerapps.us
Publik	Produksi	Pemerintah AS L5 (DOD)	mil.api.advisor.appsplatform.us
Publik	Produksi	Tiongkok dioperasikan oleh 21Vianet	china.api.advisor.powerapps.cn

Catatan

Anda dapat memilih menggunakan geografi pratinjau untuk menggabungkan fitur terbaru dan perubahan sebelumnya. Namun, perhatikan bahwa pratinjau menggunakan wilayah Azure Amerika Serikat saja.

Versi

Meskipun tidak diperlukan, sebaiknya sertakan parameter string kueri versi api dengan versi API yang diinginkan. Versi API saat ini adalah 2.0 untuk set aturan dan aturan dan 1.0 untuk semua permintaan lainnya. Misalnya, set 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. Sebaiknya gunakan 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 otentikasi.

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, sebaiknya Anda mulai dengan kumpulan aturan ini. Himpunan aturan ini digunakan oleh fitur pemeriksa solusi.

ruleset sertifikasi AppSource

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

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 TenantId nama.

Otentikasi dan otorisasi

Kueri untuk aturan dan set aturan tidak memerlukan token OAuth, 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-Authenticate, URI otorisasi, dan ID sumber daya. Anda juga harus menyediakan ID penyewa di header x-ms-tenant-id. Lihat Power Apps Autentikasi dan otorisasi Pemeriksa untuk informasi selengkapnya. Berikut ini adalah contoh header respons yang ditampilkan 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 mekanisme lain untuk memperoleh token. Berikut ini adalah contoh bagaimana hal ini dapat dilakukan menggunakan C# dan pustaka .NET MSAL:

// 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 sampel Mulai Cepat APIWeb.

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

Keamanan transportasi

Untuk enkripsi terbaik di kelasnya, layanan pemeriksa hanya mendukung komunikasi menggunakan Transport Layer Security (TLS) 1.2 dan yang lebih baru. 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.

Bagikan melalui