Power Appsi kontrollija veebi-API kasutamine

Artikkel
05/01/2024

Power Appsi kontrollija veebi API pakub staatilise analüüsi kontrollide teostamise mehhanismi Microsoft Dataverse'i platvormi kohanduste ja laienduste põhjal. See on saadaval koostajatele ja arendajatele oma lahenduste hea tava reeglite osas rikkaliku staatilise analüüsi teostamiseks ja kiiresti nende probleemsete mustrite tuvastamiseks. Teenus pakub Power Appsi looja portaalis lahendusekontrollija funktsiooni loogikat ja on kaasatud automatiseerimise osana AppSource'i rakenduste jaoks. Sel viisil otse teenusega suhtlemine võimaldab analüüsida lahendusi, mis sisalduvad asutusesisene (kõik toetatud versioonid) ja veebikeskkondades.

Lisateavet kontrollija teenuse kasutamise kohta PowerShelli koodist leiate teemast Lahendustega töötamine PowerShelli abil.

Märkus.

Power Apps kontrollija kasutamine ei garanteeri lahenduse importimise õnnestumist. Lahenduse vastu teostatavad staatilised analüüsid ei tea, millist tüüpi sihtkeskkonna konfigureeritud olekut ja impordi edukus võib sõltuda muudest lahendustest või konfiguratsioonist keskkonnas.

Alternatiivsed lähenemisviisid

Enne veebi API-dega madalaimal tasemel suhtlemise üksikasjade lugemist kaaluge meie PowerShelli mooduli MicrosoftPowerApps kasutamist. Selle asemel Checker.PowerShell. See on täielikult toetatud tööriist, mis on saadaval PowerShelli galeriis. Praeguse piirangu korral nõuab see Windows PowerShelli. Kui seda nõuet ei suudeta täita, on parim lähenemisviis otse API-dega suhtlemine.

Alustamine

Oluline on märkida, et lahenduse analüüsi tulemuseks võib olla pikaajaline protsess. Tavaliselt võib see võtta kuuskümmend (60) sekundit kuni üle viie (5) minuti, sõltuvalt erinevatest teguritest, nagu arv, suurus ning kohanduste ja koodi keerukus. Analüüsivoog on mitmeetapiline ja asünkroonne, alustades analüüsi käivitamisest, kus oleku API-d kasutatakse töö lõpuleviimise päringute tegemiseks. Analüüsi näidisvoog on järgmine:

OAuthi sõne hankimine
Kutse üleslaadimine (paralleelselt iga faili jaoks)
Kutse analüüsimine (käivitab analüüsi)
Kutse olek kuni lõpetamiseni (silmuse moodustamine, kui kutsete vahel on paus, kuni lõpule viimisest antakse märku või läviväärtused on täidetud)
Tulemuste allalaadimine esitatud SAS-i URI-st

Mõned variatsioonid on järgmised.

Lisage reeglistiku või reeglite otsing eeletapina. Siiski oleks veidi kiirem edastada konfigureeritud või püsiprogrammeeritud reeglistiku ID. Soovitatav on kasutada reeglistikku, mis vastab teie vajadustele.
Soovi korral saate üleslaadimismehhanismi mitte kasutada (piirangute kohta vaadake üleslaadimist).

Peate kindlaks määrama järgmised nõuded:

Geograafia
Versioon
Reeglistikud ja reeglid
Rentniku ID

Üksikute API-de dokumenteerimise kohta leiate teavet järgmistest artiklitest:

Reeglistiku loendi toomine
Reeglite loendi toomine
Laadi fail üles
Analüüsi käivitamine
Analüüsi oleku kontrollimine

Geograafia määratlemine

Kui suhtlete kontrollimisteenusega Power Apps , salvestatakse failid koos loodud aruannetega ajutiselt Azure’i. Geograafiapõhist API-d kasutades, saate kontrollida, kuhu andmed talletatakse. Geograafilise lõpp-punkti päringud suunatakse piirkondlikule eksemplarile, lähtudes parimast jõudlusest (latentsus). Kui päring siseneb piirkondliku teenuse eksemplari, jäävad kõik töötlemised ja püsivad andmed sellesse kindlasse piirkonda. Teatud API-vastused tagastavad piirkondlike eksemplaride URL-id järgnevate taotluste jaoks, kui analüüsitöö marsruuditakse kindlasse piirkonda. Igal geograafilisel asukohal võib olla igal ajahetkel kasutusele võetud teenuse erinev versioon. Erinevate teenuseversioonide kasutamine on tingitud mitmeastmelisest turvalisest juurutusprotsessist, mis tagab versiooni täieliku ühilduvuse. Seega sama geograafiat tuleks kasutada iga API päringureaktsiooni analüüsi elutsükli puhul ja võib vähendada üldist täitmise aega, kuna andmed ei pruugi liikuda üle juhtme nii kaugele. Saadaval on järgmised geograafilised piirkonnad.

Azure'i andmekeskus	Nimi	Geograafiline ala	Alus-URI
Avalik	Tutvu eelvaatega	Ameerika Ühendriigid	unitedstatesfirstrelease.api.advisor.powerapps.com
Avalik	Tootmine	Ameerika Ühendriigid	unitedstates.api.advisor.powerapps.com
Avalik	Tootmine	Euroopa	europe.api.advisor.powerapps.com
Avalik	Tootmine	Aasia	asia.api.advisor.powerapps.com
Avalik	Tootmine	Austraalia	australia.api.advisor.powerapps.com
Avalik	Tootmine	Jaapan	japan.api.advisor.powerapps.com
Avalik	Tootmine	India	india.api.advisor.powerapps.com
Avalik	Tootmine	Kanada	canada.api.advisor.powerapps.com
Avalik	Tootmine	Lõuna-Ameerika	southamerica.api.advisor.powerapps.com
Avalik	Tootmine	Suurbritannia	unitedkingdom.api.advisor.powerapps.com
Avalik	Tootmine	Prantsusmaa	france.api.advisor.powerapps.com
Avalik	Tootmine	Saksamaa	germany.api.advisor.powerapps.com
Avalik	Tootmine	Araabia Ühendemiraadid	unitedarabemirates.api.advisor.powerapps.com
Avalik	Tootmine	Šveits	switzerland.api.advisor.powerapps.com
Avalik	Tootmine	Lõuna-Aafrika	southafrica.api.advisor.powerapps.com
Avalik	Tootmine	Korea	korea.api.advisor.powerapps.com
Avalik	Tootmine	Norra	norway.api.advisor.powerapps.com
Avalik	Tootmine	Singapur	singapore.api.advisor.powerapps.com
Avalik	Tootmine	Rootsi	sweden.api.advisor.powerapps.com
Avalik	Tootmine	US Government	gov.api.advisor.powerapps.us
Avalik	Tootmine	US Government L4	high.api.advisor.powerapps.us
Avalik	Tootmine	US Government L5 (DOD)	mil.api.advisor.appsplatform.us
Avalik	Tootmine	Hiina teenusepakkuja on 21Vianet	china.api.advisor.powerapps.cn

Märkus.

Uusimate funktsioonide ja varasemate muudatuste kaasamiseks võite kasutada geograafilise piirkonna eelversiooni. Pange tähele, et eelversioonis kasutatakse ainult Ameerika Ühendriikide Azure'i piirkondi.

Versioonimine

Kuigi see pole nõutav, on soovitatav lisada API-versiooni päringustringi parameeter soovitud API versioonile. Praegune API versioon on reeglite ja reeglite puhul 2.0 ja kõigi muude taotluste puhul 1.0. Näiteks järgmine reeglistik on HTTP-päring, mis määrab 2.0 API versiooni kasutamise:

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

Kui seda ei pakuta, kasutatakse vaikimisi uusimat API versiooni. Selgesõnalise versiooninumbri kasutamine on soovitatav, kuna versiooni suurendatakse, kui tehakse murrangulisi muudatusi. Kui taotluses on määratud versiooninumber, säilitatakse hilisemates (arvult suuremates) versioonides tagasiühilduvuse tugi.

Reeglistikud ja reeglid

Power Appsi kontrollija vajab käitamisel reeglite loendit. Neid reegleid võib esitada üksikute reeglite või reeglite rühmana, mida nimetatakse reeglistikuks. Reeglistik on mugav viis reeglite rühma määramiseks, mitte iga reegli eraldi määramiseks. Lahendusekontrollija funktsioon kasutab näiteks reeglistikku nimega Lahendusekontrollija. Uute reeglite lisamisel või eemaldamisel sisaldab teenus neid muudatusi automaatselt, ilma et tarbiv rakendus peaks neid muutma. Kui teil on vaja, et reeglite loend ei muutuks automaatselt vastavalt eespool kirjeldatule, saab reeglid määrata eraldi. Reeglistikus võib olla üks või piiramatu hulk reegleid. Reeglit ei pruugi olla reeglistikus ning see võib olla mitmes reeglistikus. Reeglistike loendi saamiseks kutsuge API järgmiselt: [Geographical URL]/api/ruleset. See lõpp-punkt nõuab nüüd autentimist.

Lahendusekontrollija reeglistik

Lahendusekontrollija reeglistik sisaldab mõjusate reeglite komplekti, millel on piiratud võimalused olla valepositiivne. Kui käivitate analüüsi olemasoleva lahenduse suhtes, on soovitatav alustada sellest reeglistikust. Seda reeglistikku kasutab lahendusekontrolli funktsioon.

AppSource'i sertifitseerimise reeglistik

Rakenduste avaldamisel AppSource'is peate oma rakenduse sertifitseerima. rakendus mis on avaldatud AppSource on vajalik kvaliteedi tagamiseks. Sertimisreeglistik AppSource sisaldab reegleid, mis on osa lahendusekontrolli reeglistikust, ja muid reegleid, mis tagavad, et poes avaldatakse ainult kvaliteetseid rakendusi. AppSource Mõned sertifitseerimiseeskirjad on valepositiivsete tulemuste suhtes altimad ja nende lahendamiseks võib vaja minna rohkem tähelepanu.

Rentniku ID leidmine

Teie rentniku ID on vajalik sõne nõudvate API-dega suhtlemiseks. Lisateavet rentniku ID hankimise kohta leiate sellest artiklist. Rentniku ID toomiseks saate kasutada ka PowerShelli käske. Järgmises näites rakendatakse AzureAD mooduli cmdlet-käske.

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

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

Rentniku ID on atribuudi ObjectId väärtus, mis tagastatakse üksusest Get-AzureADTenantDetail. Võite seda näha ka pärast cmdlet-käsu väljundis Connect-AzureAD cmdlet-käsu abil sisselogimist. Sel juhul nimetatakse TenantId seda.

Autentimine ja autoriseerimine

Reeglite ja reeglistike kohta päringute tegemiseks ei ole vaja OAuthi tõendit, kuid kõik teised API-d nõuavad seda tõendit. API-d toetavad autoriseerimise tuvastamist, kutsudes mõnda sõne nõudvat API-d. Vastus on volitamata HTTP-olekukood 401, millel on WWW-Authenticate päis, autoriseerimise URI ja ressursi ID. Rentniku ID peaksite sisestama ka päisesse x-ms-tenant-id. Lisateavet leiate teemast Power Apps Kontrollija autentimine ja autoriseerimine . Järgmine näide on API-päringust tagastatud vastuse päise kohta.

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

Kui olete selle teabe saanud, saate tõendi hankimiseks kasutada Microsofti autentimisteeki (MSAL) või mõnda muud mehhanismi. Järgnev on näide sellest, kuidas seda saab teha C# ja MSAL .NET teegi abil:

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

Täieliku töökoodi leiate Web API kiirkäivituse näidisest.

Kui olete tokeni omandanud, on soovitatav anda sama luba taotluse elutsükli järgmistele kõnedele. Siiski võib turvakaalutlustel olla õigustatud uue tokeni hankimine rohkemate taotluste korral.

Transpordi turvalisus

Oma klassi parimaks krüptimiseks toetab kontrollimisteenus suhtlust ainult transpordikihi turbe (TLS) 1.2 ja uuema versiooni abil. Juhiseid .NET-i TLS-i kohaste heade tavade kohta leiate teemast Transpordikihi turbe (TLS) .NET Frameworkiga seotud parimad tavad.

Aruande vorming

Lahenduse analüüsi tulemus on ZIP-fail, mis sisaldab ühte või mitut standardiseeritud JSON-vormingus aruannet. Aruande vorming põhineb staatilise analüüsi tulemustel, mida nimetatakse staatilise analüüsi tulemuste vahetuse vorminguks (SARIF). SARIF-i dokumentide vaatamiseks ja nendega suhtlemiseks on saadaval tööriistad. Lisateavet leiate sellelt veebisaidilt. Teenus kasutab OASIS standardi teistversiooni.

Vaata ka