„Power Apps“ tikrintuvo žiniatinklio API naudojimas

Straipsnis
10/16/2024

„Power Apps“ tikrintuvo žiniatinklio API suteikia mechanizmą, kurį naudojant galima vykdyti „Microsoft Dataverse“ platformos tinkinimų ir plėtinių statinės analizės patikras. Ją naudodami kūrėjai ir programuotojai gali atlikti išsamias statinės savo sprendimų analizės patikras, pagrįstas geriausios praktikos taisyklėmis ir greitai nustatyti probleminius modelius. Paslauga užtikrina sprendimų tikrintuvo funkcijos logiką „Power Apps“ kūrėjo portale ir yra įtraukta kaip programų, pateiktų „AppSource“, automatizavimo dalis. Tokiu būdu tiesiogiai sąveikaujant su paslauga galima analizuoti sprendimus, kurie yra įtraukti į vietinis (visos palaikomos versijos) ir internetinę aplinką.

Informacijos apie tikrintuvo paslaugos naudojimą iš "PowerShell" kodo ieškokite Darbas su sprendimais naudojant "PowerShell".

Pastaba.

Sprendimo „Power Apps“ tikrintuvo naudojimas neužtikrina, kad sprendimas bus sėkmingai importuotas. Statinės analizė tikrinimai atlikti sprendime nežino, paskirties aplinkos sukonfigūruotos būsenos ir importavimo pasisekimas gali skirtis priklausomai nuo kitų sprendimų ar aplinkos konfigūravimų.

Alternatyvūs metodai

Prieš skaitydami išsamią informaciją apie tai, kaip žemiausiu lygiu sąveikauti su žiniatinklio API, apsvarstykite galimybę naudoti mūsų "PowerShell" modulį. Microsoft.PowerApps Vietoj to patikrinkite.PowerShell. Tai visiškai palaikomas įrankis, kurį galima rasti "PowerShell" galerijoje. Šiuo metu jis reikalauja „Windows PowerShell“. Jei negalite įvykdyti šio reikalavimo, geriausias būdas yra tiesiogiai bendrauti su API.

Darbo pradžia

Svarbu pažymėti, kad sprendimo analizė gali lemti ilgą procesą. Paprastai tai gali užtrukti nuo šešiasdešimties (60) sekundžių iki penkių (5) minučių, atsižvelgiant į įvairius veiksnius, pvz., tinkinimų skaičių, dydį ir sudėtingumą bei kodą. Analizės procesas yra kelių žingsnių ir asinchroninis, pradedant nuo analizės užduoties inicijavimo pagal užduoties vykdymo užklausai naudojamos API būseną. Analizės procedūros pavyzdys:

Gaukite atpažinimo OAuth ženklą
Įkėlimo iškvietimas (kiekvienam failui lygiagrečiai)
Analizės iškvietimas (inicijuojama analizės užduotis)
Būsenos iškvietimas, kol procedūra bus baigta (ciklas su pauze tarp iškvietimų, kol bus gautas pabaigos signalas arba tenkinamos sąlygos)
Rezultato (-ų) atsisiuntimas iš pateikto SAS URI

Galimi variantai:

Kaip išankstinį žingsnį įtraukite taisyklių rinkinio arba taisyklių paiešką. Vis dėlto gali būti šiek tiek greičiau perduoti sukonfigūruotą arba užkoduotą taisyklių rinkinio ID. Rekomenduojama naudoti taisyklių rinkinį, atitinkantį jūsų poreikius.
Galite pasirinkti nenaudoti įkėlimo mechanizmo (žr. įkėlimo apribojimus).

Turite nustatyti šiuos reikalavimus:

Kuri geografija?
Kuri versija?
Kokios taisyklės ir taisyklės?
Kas yra jūsų nuomotojo ID?

Atskirų API dokumentaciją rasite šiuose straipsniuose:

Taisyklių rinkinių sąrašo gavimas
Taisyklių sąrašo gavimas
Failo nusiuntimas
Iškviesti analizę
Patikrinkite analizės būseną

Geografijos nustatymas

Kai sąveikaujate Power Apps su tikrintuvo tarnyba, failai laikinai saugomi "Azure" kartu su sugeneruotomis ataskaitomis. Naudodami su konkrečia geografija susijusią API, galite kontroliuoti, kur saugomi duomenys. Užklausos geografiniam galutiniam taškui yra nukreipiamos į regiono elementą priklausomai nuo geriausio vykdymo (atsakiusio asmens greičio). Kai užklausa patenka į regiono paslaugų elementą, visi apdorojami ir esantys duomenys išliks tame regione. Tam tikri API atsakymai grąžina regioninių egzempliorių URL vėlesnėms užklausoms, kai analizės užduotis nukreipiama į konkretų regioną. Kiekviena geografinė vietovė gali turėti skirtingą paslaugos versiją, įdiegtą bet kuriuo metu. Skirtingų paslaugų versijų naudojimas priklauso nuo daugiapakopio saugaus diegimo proceso, kuris užtikrina visišką versijų suderinamumą. Dėl to, ta pati geografija turi būti naudojama kiekvienam API skambučiui gyvavimo ciklo analizavimui ir gali sumažinti bendrą vykdymo laiką, nes duomenims gali nereikėti keliauti per tinklą. Galimos toliau nurodytos geografijos.

„Azure“ duomenų centras	Vardas ir pavardė	Geografija	Bazinis URI
Viešasis	Peržiūros versija	Jungtinės Valstijos	unitedstatesfirstrelease.api.advisor.powerapps.com
Viešasis	Gamyba	Jungtinės Valstijos	unitedstates.api.advisor.powerapps.com
Viešasis	Gamyba	Europa	europe.api.advisor.powerapps.com
Viešasis	Gamyba	Azija	asia.api.advisor.powerapps.com
Viešasis	Gamyba	Australija	australia.api.advisor.powerapps.com
Viešasis	Gamyba	Japonija	japan.api.advisor.powerapps.com
Viešasis	Gamyba	Indija	india.api.advisor.powerapps.com
Viešasis	Gamyba	Kanada	canada.api.advisor.powerapps.com
Viešasis	Gamyba	Pietų Amerika	southamerica.api.advisor.powerapps.com
Viešasis	Gamyba	Jungtinė Karalystė	unitedkingdom.api.advisor.powerapps.com
Viešasis	Gamyba	Prancūzija	france.api.advisor.powerapps.com
Viešas	Gamyba	Vokietija	germany.api.advisor.powerapps.com
Viešas	Gamyba	Jungtiniai Arabų Emyratai	unitedarabemirates.api.advisor.powerapps.com
Vieša	Gamyba	Šveicarija	switzerland.api.advisor.powerapps.com
Vieša	Gamyba	Pietų Afrika	southafrica.api.advisor.powerapps.com
Vieša	Gamyba	Pietų Korėja	korea.api.advisor.powerapps.com
Vieša	Gamyba	Norvegija	norway.api.advisor.powerapps.com
Vieša	Gamyba	Singapūras	singapore.api.advisor.powerapps.com
Vieša	Gamyba	Švedija	sweden.api.advisor.powerapps.com
Vieša	Gamyba	„ US Government“	gov.api.advisor.powerapps.us
Viešasis	Gamyba	JAV valstybinė institucija L4	high.api.advisor.powerapps.us
Viešasis	Gamyba	JAV valstybinė institucija L5 (DOD)	mil.api.advisor.appsplatform.us
Viešasis	Gamyba	Valdoma Kinijos per „21Vianet“	china.api.advisor.powerapps.cn

Pastaba.

Galite nuspręsti naudoti geografijos peržiūros versiją, kad galėtumėte anksčiau pradėti naudotis naujausiomis funkcijomis ir pakeitimais. Tačiau atkreipkite dėmesį, kad peržiūros versijoje naudojami tik Jungtinių Valstijų „Azure“ regionai.

Versijų sistema

Nors tai nėra būtina, rekomenduojama įtraukti api versijos užklausos eilutės parametrą su norima API versija. Dabartinė API versija yra 2.0 taisyklių rinkiniams ir taisyklėms ir 1.0 visoms kitoms užklausoms. Pavyzdžiui, šis taisyklių rinkinys yra HTTP užklausa, nurodanti naudoti 2.0 API versiją:

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

Jei nepateikta, pagal numatytuosius nustatymus naudojama naujausia API versija. Rekomenduojama naudoti aiškų versijos numerį, nes versija padidinama, jei įvedami esminių pakeitimų. Jei versijos numeris bus nurodytas užklausoje, vėlesnėse versijose (kurių numeris yra didesnis) bus užtikrintas atgalinis suderinamumas.

Taisyklių rinkiniai ir taisyklės

Tam, kad galėtų veikti, „Power Apps“ tikrintuvui reikia taisyklių sąrašo. Šios taisyklės gali būti pateikiamos kaip atskiros taisyklės arba taisyklių grupė, vadinama taisyklių rinkiniu. Taisyklių rinkinys yra patogus būdas nurodyti taisyklių grupę užuot nurodant kiekvieną taisyklę atskirai. Pavyzdžiui, sprendimų tikrintuvo funkcijos naudoja taisyklių rinkinį, kurio pavadinimas yra Sprendimų tikrintuvas. Kai pridedamos arba pašalinamos naujos taisyklės, paslauga įtraukia šiuos pakeitimus automatiškai, nereikalaujant, kad vartojanti programa atliktų jokių pakeitimų. Jei reikia, kad taisyklių sąrašas nebūtų keičiamas automatiškai, kaip aprašyta prieš tai, taisykles galima nurodyti atskirai. Taisyklių rinkiniai gali turėti vieną ar daugiau taisyklių be apribojimų. Taisyklė gali būti nepriklausyti jokiam arba priklausyti keliems taisyklių rinkiniams. Visų taisyklių rinkinių sąrašą galite gauti pateikdami API iškvietimą:[Geographical URL]/api/ruleset. Dabar šį galinį punktą reikia autentifikuoti.

Sprendimų tikrintuvo taisyklių rinkinys

Sprendimų tikrintuvo taisyklių rinkinys apima darančias poveikį taisykles, kurios pasižymi maža klaidingai teigiamų rezultatų tikimybe. Jei vykdote analizę pagal esamą sprendimą, rekomenduojama pradėti nuo šio taisyklių rinkinio. Šį taisyklių rinkinį naudoja sprendimų tikrintuvo funkcija.

„AppSource“ sertifikavimo taisyklių rinkinys

Prieš publikuojant programą „AppSource“, programa turi būti sertifikuota. Skelbiamos AppSource paraiškos turi atitikti aukštus kokybės standartus. Sertifikavimo AppSource taisyklių rinkinyje yra taisyklės, kurios yra sprendimų tikrintuvo taisyklių rinkinio dalis, ir kitos taisyklės, užtikrinančios, kad parduotuvėje būtų skelbiamos tik aukštos kokybės programos. AppSource Kai kurios sertifikavimo taisyklės yra labiau linkusios į klaidingus teigiamus rezultatus ir joms išspręsti gali prireikti daugiau dėmesio.

Nuomotojo ID paieška

Nuomotojo ID reikalingas sąveikai su API, kurioms reikia atpažinimo ženklo. Informacijos, kaip gauti nuomotojo ID, ieškokite šiame straipsnyje. Norėdami gauti nuomotojo ID, taip pat galite naudoti „PowerShell“ komandas. Toliau pateiktame pavyzdyje taikomos "Cmdlet" AzureAD modulyje.

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

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

Nuomotojo ID yra ObjectId ypatybės reikšmė, grąžinama iš Get-AzureADTenantDetail. Ją taip pat galite matyti „cmdlet“ išvestyje po to, kai prisijungėte naudodami Connect-AzureAD „cmdlet“. Tokiu atveju jis bus pavadintas TenantId.

Autentifikavimas ir autorizavimas

Taisyklių ir taisyklių rinkinių užklausai nereikia atpažinimo ženklo OAuth , tačiau visoms kitoms API reikia atpažinimo ženklo. API leidžia vykdyti autorizavimą kviesdama kiekvieną API, kuriai būtinas atpažinimo ženklas. Atsakymas yra neteisėtas HTTP būsenos kodas 401 su WWW-Authenticate antrašte, autorizacijos URI ir išteklių ID. Savo nuomotojo ID taip pat turite pateikti x-ms-tenant-id antraštėje. Daugiau informacijos rasite Power Apps Tikrintuvo autentifikavimas ir autorizacija . Toliau pateikiamas atsakymas antraštės, grąžintos iš API užklausos, pavyzdys:

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

Kai turėsite šią informaciją, galite pasirinkti naudoti Microsoft autentifikavimo biblioteką (MSAL) arba kitą mechanizmą, kad gautumėte atpažinimo ženklą. Toliau pateikiamas pavyzdys, kaip tai galima padaryti naudojant C# ir MSAL .NET biblioteką:

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

Visą darbo kodą rasite žiniatinklio API "QuickStart" pavyzdyje.

Kai įsigysite prieigos raktą, patariama tą patį žetoną pateikti vėlesniems skambučiams užklausos gyvavimo ciklo metu. Tačiau saugumo sumetimais gali prireikti įsigyti daugiau užklausų, kad būtų įsigytas naujas žetonas.

Transportavimo lygmens sauga

Siekiant geriausio savo klasėje šifravimo, tikrintuvo paslauga palaiko ryšius tik naudojant "Transport sluoksnis Security" (TLS) 1.2 ir naujesnę versiją. Rekomendacijų dėl geriausių TLS praktikų dirbant su .NET žr. Geriausios Transport Layer Security (TLS) praktikos dirbant su „.NET Framework“.

Ataskaitos formatas

Sprendimo analizės rezultatas yra zip failas, kuriame yra viena ar daugiau ataskaitų standartiniu JSON formatu. Ataskaitos formatas yra paremtas statinės analizės rezultatais ir vadinamas statinės analizės rezultatų mainų formatu (SARIF). Yra įrankių, kurie leidžia peržiūrėti ir sąveikauti su SARIF dokumentais. Išsamesnės informacijos žr. šioje svetainėje. Paslauga naudoja antrąją OASIS standarto versiją.

Taip pat žr.