Gunakan API web penyemak Power Apps

API web penyemak Power Apps menyediakan mekanisme untuk menjalankan semakan analisis statik terhadap penyesuaian dan sambungan kepada platform Microsoft Dataverse. Pembuat dan pembangun boleh melakukan pemeriksaan analisis statik yang kaya pada penyelesaian mereka terhadap satu set peraturan amalan terbaik untuk mengenal pasti corak bermasalah dengan cepat. Perkhidmatan ini menyediakan logik untuk ciri penyemak penyelesaian dalam pembuat Power Apps portal dan disertakan sebagai sebahagian daripada automasi untuk permohonan yang diserahkan kepada Marketplace. Berinteraksi dengan perkhidmatan secara langsung dengan cara ini membolehkan analisis penyelesaian yang disertakan sebagai sebahagian daripada premis (semua versi yang disokong) dan persekitaran dalam talian.

Untuk maklumat tentang menggunakan perkhidmatan penyemak daripada kod PowerShell, rujuk Bekerja dengan penyelesaian menggunakan PowerShell.

Nota

Penggunaan penyemak Power Apps tidak menjamin bahawa import penyelesaian akan berjaya. Semakan analisis statik yang dijalankan terhadap penyelesaian tidak tahu akan keadaan konfigurasi persekitaran destinasi dan kejayaan import mungkin bergantung pada penyelesaian atau konfigurasi lain dalam persekitaran.

Pendekatan alternatif

Sebelum membaca butiran cara berinteraksi pada tahap terendah dengan API web, pertimbangkan untuk menggunakan modul PowerShell kami, Microsoft.PowerApps. Checker.PowerShell, sebaliknya. Ia adalah alat yang disokong sepenuhnya yang tersedia dalam PowerShell Gallery. Sekatan semasa ialah ia memerlukan Windows PowerShell. Jika tidak dapat memenuhi keperluan ini, maka berinteraksi dengan API secara langsung ialah pendekatan terbaik.

Mari bermula

Adalah penting untuk ambil perhatian bahawa analisis penyelesaian boleh menghasilkan proses yang berjalan lama. Ia biasanya boleh mengambil masa enam puluh (60) saat hingga lebih daripada lima (5) minit bergantung pada pelbagai faktor, seperti nombor, saiz dan kerumitan penyesuaian dan kod. Aliran analisis adalah berbilang langkah dan tidak segerak, bermula dengan memulakan kerja analisis dengan API status digunakan untuk pertanyaan untuk menyelesaikan kerja. Aliran contoh untuk analisis adalah seperti berikut:

Dapatkan OAuth token
Muat naik panggilan (untuk setiap fail secara selari)
Analisis panggilan (memulakan kerja analisis)
Status panggilan sehingga selesai (penggelungan dengan berhenti seketika di antara panggilan sehingga penamat selesai atau ambang dipenuhi)
Muat turun hasil daripada URI SAS yang disediakan

Beberapa variasi ialah:

Sertakan pencarian ruleset atau peraturan sebagai pralangkah. Walau bagaimanapun, adalah lebih cepat sedikit untuk memasukkan ID ruleset yang dikonfigurasikan atau berkod keras. Anda disyorkan supaya menggunakan ruleset yang memenuhi keperluan anda.
Anda boleh memilih untuk tidak menggunakan mekanisme muat naik (lihat muat naik untuk pengehadan).

Anda perlu menentukan keperluan berikut:

Geografi yang mana?
Versi yang mana?
Set peraturan dan peraturan yang mana?
Apakah ID penyewa anda?

Rujuk artikel berikut untuk dokumentasi tentang API individu:

Dapatkan semula senarai set peraturan
Dapatkan semula senarai peraturan
Muat naik fail
Invoke analisis
Semak status analisis

Menentukan geografi

Apabila anda berinteraksi dengan perkhidmatan penyemak Power Apps, fail disimpan buat sementara waktu dalam Azure bersama-sama dengan laporan yang dijana. Dengan menggunakan API khusus geografi, anda boleh mengawal tempat data disimpan. Permintaan kepada titik tamat geografi dihalakan kepada tika serantau berdasarkan prestasi terbaik (kependaman kepada peminta). Selepas permintaan memasuki tika perkhidmatan serantau, semua data pemprosesan dan tetap kekal dalam rantau khusus tersebut. Respons API tertentu mengembalikan URL tika serantau untuk permintaan seterusnya sebaik sahaja kerja analisis dihalakan ke rantau tertentu. Setiap geografi mungkin mempunyai versi perkhidmatan yang berbeza yang digunakan pada bila-bila masa. Penggunaan versi perkhidmatan yang berbeza adalah disebabkan oleh proses penggunaan selamat berbilang peringkat, yang memastikan keserasian versi penuh. Oleh itu, geografi yang sama harus digunakan untuk setiap panggilan API dalam kitaran hayat analisis dan mungkin mengurangkan masa pelaksanaan keseluruhan kerana data mungkin tidak perlu dialihkan jauh pada kawat. Berikut adalah geografi yang tersedia:

Azure datacenter	Nama	Geografi	URI asas
Awam	Pratonton	Amerika Syarikat	unitedstatesfirstrelease.api.advisor.powerapps.com
Awam	Penerbitan	Amerika Syarikat	unitedstates.api.advisor.powerapps.com
Awam	Penerbitan	Eropah	europe.api.advisor.powerapps.com
Awam	Penerbitan	Asia	asia.api.advisor.powerapps.com
Awam	Penerbitan	Australia	australia.api.advisor.powerapps.com
Awam	Penerbitan	Jepun	japan.api.advisor.powerapps.com
Awam	Penerbitan	India	india.api.advisor.powerapps.com
Awam	Penerbitan	Kanada	canada.api.advisor.powerapps.com
Awam	Penerbitan	Amerika Selatan	southamerica.api.advisor.powerapps.com
Awam	Penerbitan	United Kingdom	unitedkingdom.api.advisor.powerapps.com
Awam	Penerbitan	Perancis	france.api.advisor.powerapps.com
Awam	Penerbitan	Jerman	germany.api.advisor.powerapps.com
Awam	Penerbitan	Emiriah Arab Bersatu	unitedarabemirates.api.advisor.powerapps.com
Awam	Penerbitan	Switzerland	switzerland.api.advisor.powerapps.com
Awam	Penerbitan	Afrika Selatan	southafrica.api.advisor.powerapps.com
Awam	Penerbitan	Korea Selatan	korea.api.advisor.powerapps.com
Awam	Penerbitan	Norway	norway.api.advisor.powerapps.com
Awam	Penerbitan	Singapura	singapore.api.advisor.powerapps.com
Awam	Penerbitan	Sweden	sweden.api.advisor.powerapps.com
Awam	Penerbitan	Poland	poland.api.advisor.powerapps.com
Awam	Penerbitan	Itali	italy.api.advisor.powerapps.com
Awam	Penerbitan	Kerajaan AS	gov.api.advisor.powerapps.us
Awam	Penerbitan	Kerajaan AS L4	high.api.advisor.powerapps.us
Awam	Penerbitan	Kerajaan AS L5 (DOD)	mil.api.advisor.appsplatform.us
Awam	Penerbitan	China dikendalikan oleh 21Vianet	china.api.advisor.powerapps.cn

Nota

Anda boleh memilih untuk menggunakan geografi pratonton bagi menggabungkan ciri terbaharu dan perubahan sebelum ini. Walau bagaimanapun, ambil perhatian bahawa pratonton menggunakan United States Azure rantau sahaja.

Pemversian

Walaupun tidak diperlukan, adalah disyorkan untuk memasukkan parameter rentetan pertanyaan versi api dengan versi API yang dikehendaki. Versi API semasa ialah 2.0 untuk set peraturan dan peraturan dan 1.0 untuk semua permintaan lain. Sebagai contoh, set peraturan berikut ialah 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 terkini digunakan secara lalai. Menggunakan nombor versi eksplisit disyorkan kerana versi ditambah jika perubahan pecah diperkenalkan. Jika nombor versi ditetapkan dalam permintaan, sokongan keserasian ke belakang dalam versi baharu (yang lebih luas) akan dikekalkan.

Ruleset dan peraturan

Penyemak Power Apps memerlukan senarai peraturan apabila dijalankan. Peraturan ini boleh diberikan dalam bentuk peraturan individu atau kumpulan peraturan, dirujuk sebagai ruleset. Ruleset ialah cara mudah untuk menentukan sekumpulan peraturan daripada perlu menentukan setiap peraturan secara individu. Contohnya, ciri penyemak penyelesaian menggunakan ruleset yang dinamakan Penyemak Penyelesaian. Apabila peraturan baharu ditambah atau dialih keluar, perkhidmatan menyertakan perubahan ini secara automatik tanpa memerlukan sebarang perubahan oleh aplikasi pengguna. Jika anda mahu senarai peraturan tidak berubah secara automatik seperti yang dijelaskan di atas, maka peraturan tersebut boleh ditentukan secara individu. Ruleset boleh mempunyai satu atau lebih peraturan tanpa had. Peraturan boleh tiada dalam ruleset atau berada dalam beberapa ruleset. Anda boleh mendapatkan senarai semua ruleset dengan memanggil API seperti berikut: [Geographical URL]/api/ruleset. Titik akhir ini kini memerlukan pengesahan.

Ruleset penyemak penyelesaian

Ruleset penyemak penyelesaian mengandungi satu set peraturan yang memberikan kesan yang besar yang mempunyai peluang terhad untuk positif palsu. Jika menjalankan analisis terhadap penyelesaian sedia ada, anda disyorkan untuk bermula dengan set peraturan ini. Set peraturan ini digunakan oleh ciri penyemak penyelesaian.

Set peraturan pensijilan pasaran

Apabila menerbitkan permohonan di Marketplace, anda mesti mendapatkan permohonan anda diperakui. Aplikasi yang diterbitkan di Marketplace diperlukan untuk memenuhi standard kualiti yang tinggi. Set peraturan pensijilan Marketplace mengandungi peraturan yang merupakan sebahagian daripada set peraturan penyemak penyelesaian, serta peraturan lain untuk memastikan hanya aplikasi berkualiti tinggi diterbitkan di kedai. Sesetengah peraturan pensijilan Pasaran lebih terdedah kepada positif palsu dan mungkin memerlukan lebih perhatian untuk menyelesaikannya.

Cari ID penyewa anda

ID penyewa anda diperlukan untuk berinteraksi dengan API yang memerlukan token. Rujuk kepada artikel ini untuk mendapatkan butiran tentang cara mendapatkan ID penyewa. Anda juga boleh menggunakan perintah PowerShell untuk mendapatkan semula ID penyewa. Contoh berikut menggunakan cmdlet dalam modul AzureAD.

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

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

ID penyewa ialah nilai bagi sifat ObjectId yang dikembalikan daripada Get-AzureADTenantDetail. Anda juga boleh melihatnya selepas log masuk menggunakan cmdlet Connect-AzureAD dalam output cmdlet. Dalam kes ini, ia akan dinamakan TenantId.

Pengesahan dan kebenaran

Pertanyaan untuk peraturan dan set peraturan tidak memerlukan OAuth token, tetapi semua API lain memerlukan token. API menyokong penemuan kebenaran dengan memanggil mana-mana API yang memerlukan token. Respons ialah kod status HTTP yang tidak dibenarkan 401 dengan pengepala WWW-Authenticate, URI kebenaran dan ID sumber. Anda juga perlu memberikan ID penyewa anda dalam pengepala x-ms-tenant-id. Rujuk Power Apps Pengesahan dan kebenaran penyemak untuk maklumat lanjut. Berikut ialah contoh pengepala respons yang dikembalikan daripada permintaan API:

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

Sebaik sahaja anda mempunyai maklumat ini, anda boleh memilih untuk menggunakan Microsoft Authentication Library (MSAL) atau beberapa mekanisme lain untuk memperoleh token. Berikut ialah contoh cara ini boleh dilakukan menggunakan C# dan perpustakaan 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 kod kerja penuh, lihat sampel Permulaan Pantas APIWeb.

Sebaik sahaja anda telah memperoleh token, anda dinasihatkan agar memberikan token yang sama kepada panggilan berikutnya dalam kitaran hayat permintaan. Walau bagaimanapun, lebih banyak permintaan mungkin menjamin token baharu diperoleh atas sebab keselamatan.

Keselamatan pengangkutan

Untuk penyulitan terbaik dalam kelasnya, perkhidmatan penyemak hanya menyokong komunikasi menggunakan Transport Layer Security (TLS) 1.2 dan lebih tinggi. Untuk panduan tentang amalan terbaik .NET sekitar TLS, rujuk amalan terbaik Transport Layer Security (TLS) dengan Rangka Kerja .NET.

Format laporan

Hasil analisis penyelesaian ialah fail zip yang mengandungi satu atau lebih laporan dalam format JSON yang dipiawaikan. Format laporan adalah berdasarkan keputusan analisis statik yang dirujuk sebagai Format Penukaran Hasil Analisis Statik (SARIF). Terdapat alat yang tersedia untuk melihat dan berinteraksi dengan dokumen SARIF. Rujuk pada laman web ini untuk butiran. Perkhidmatan ini menggunakan versi dua piawaian OASIS.

Lihat juga