Uporaba spletnega API-ja pregledovalnika za Power Apps

Članek
02/05/2024

Spletni API preverjevalnika aplikacij Power Apps nudi mehanizem za izvajanje preverjanj statične analize, ki temelji na prilagoditvah in razširitvah platforme Microsoft Dataverse. Ustvarjalcem in razvijalcem omogoča izvajanje preverjanj rešitev s podrobno statično analizo, ki temelji na pravilih najboljših praks, da lahko hitro prepoznajo težavne vzorce. Storitev zagotavlja logiko za funkcijo pregledovalnika rešitev v portalu za ustvarjalce Power Apps in je vključena kot del avtomatizacije za aplikacije, poslane v AppSource. Neposredna interakcija s storitvijo na ta način omogoča analizo rešitev, ki so vključene kot del na mestu uporabe (vse podprte različice) in spletnih okolij.

Za informacije o uporabi storitve preverjanja iz kode PowerShell glejte Delo z rešitvami z uporabo PowerShell.

opomba,

Uporaba pregledovalnika za Power Apps ne jamči, da bo uvoz rešitve uspešen. Pregledi s statično analizo, opravljeni pri rešitvi, ne poznajo konfiguriranega stanja ciljnega okolja, uspeh pri uvozu pa je lahko odvisen od drugih rešitev ali konfiguracij v okolju.

Alternativni pristopi

Preden preberete podrobnosti o interakciji na najnižji ravni s spletnimi API-ji, razmislite o uporabi našega modula PowerShell, Microsoft.PowerApps.Checker.PowerShell, namesto tega. To je popolnoma podprto orodje, ki je na voljo v galeriji PowerShell. Trenutna omejitev je, da za to potrebujete Windows PowerShell. Če te zahteve ne morete izpolniti, je najboljši pristop neposredna interakcija z API-ji.

Začetek

Pomembno je vedeti, da lahko analiza rešitve povzroči dolgotrajen proces. Običajno lahko traja od šestdeset (60) sekund do več kot pet (5) minut, odvisno od različnih dejavnikov, kot so število, velikost in kompleksnost prilagoditev in kode. Potek analize je sestavljen iz več korakov in asinhronega začetka z zagonom posla analize z API-jem stanja, ki se uporablja za poizvedbo o dokončanju posla. Vzorčni potek analize je naslednji:

Pridobite žeton OAuth
Nalaganje klica (za vsako datoteko vzporedno)
Analiza klicev (inicializira posel analize)
Stanje klica do konca (ponavljanje s premori med klici, dokler se ne oznani konec ali so doseženi pragi)
Prenesite rezultate z navedenega URI-ja za SAS

Nekaj različic je:

Kot predhodni korak vključite iskanje nabora pravil ali posameznih pravil. Vendar bi bilo nekoliko hitrejše posredovati v konfiguriranem ali vprogramiranem ID-ju nabora pravil. Priporočljivo je, da uporabite nabor pravil, ki ustreza vašim potrebam.
Lahko se odločite, da ne boste uporabili mehanizma za nalaganje (glejte nalaganje za omejitve).

Določiti morate naslednje zahteve:

Katera geografska lokacija?
Katera različica?
Kateri nabori pravil in pravila?
Kakšen je ID vašega najemnika?

Glejte naslednje članke za dokumentacijo o posameznih API-jih:

Pridobivanje seznama nizov pravil
Pridobivanje seznama pravil
Prenos datoteke
Priklic analize
Preverjanje stanja analize

Določanje geografske lokacije

Ko komunicirate s storitvijo Power Apps checker, se datoteke začasno shranijo v Azure skupaj z ustvarjenimi poročili. Z uporabo API-ja za določeno geografsko lokacijo lahko nadzorujete, kje so podatki shranjeni. Zahteve za geografsko končno točko se preusmerijo v regionalni primerek na podlagi najboljše zmogljivosti (zakasnitev osebe, ki je podala zahtevo). Ko zahteva vstopi v regionalni primerek storitve, ostanejo vsi obdelani in ohranjeni podatki znotraj te regije. Nekateri odgovori API-ja vrnejo regionalne URL-je primerkov za nadaljnje zahteve, ko je opravilo analize usmerjeno v določeno regijo. Vsaka geografska regija ima lahko v katerem koli trenutku razporejeno drugačno različico storitve. Uporaba različnih različic storitev je posledica večstopenjskega procesa varne uvedbe, ki zagotavlja popolno združljivost različic. Tako je treba za vsak klic API v življenjskem ciklu analize uporabiti isto geografijo in se lahko skrajša skupni čas izvedbe, saj podatki morda ne bodo morali potovati tako daleč po žicah. Geografske lokacije, ki so na voljo:

Podatkovno središče Azure	Ime	Geografsko območje	Osnovni URI
Javni sektor	Prikaz predogleda	Združene države Amerike	unitedstatesfirstrelease.api.advisor.powerapps.com
Javni sektor	Produkcija	Združene države Amerike	unitedstates.api.advisor.powerapps.com
Javni sektor	Produkcija	Evropa	europe.api.advisor.powerapps.com
Javni sektor	Produkcija	Azija	asia.api.advisor.powerapps.com
Javni sektor	Produkcija	Avstralija	australia.api.advisor.powerapps.com
Javni sektor	Produkcija	Japonska	japan.api.advisor.powerapps.com
Javni sektor	Produkcija	Indija	india.api.advisor.powerapps.com
Javni sektor	Produkcija	Kanada	canada.api.advisor.powerapps.com
Javni sektor	Produkcija	Južna Amerika	southamerica.api.advisor.powerapps.com
Javni sektor	Produkcija	Združeno kraljestvo	unitedkingdom.api.advisor.powerapps.com
Javni sektor	Produkcija	Francija	france.api.advisor.powerapps.com
Javni	Proizvodnja	Nemčija	germany.api.advisor.powerapps.com
Javni	Proizvodnja	Združeni arabski emirati	unitedarabemirates.api.advisor.powerapps.com
Javni	Proizvodnja	Švica	switzerland.api.advisor.powerapps.com
Javni	Proizvodnja	Južnoafriška republika	southafrica.api.advisor.powerapps.com
Javni	Proizvodnja	Koreja	korea.api.advisor.powerapps.com
Javni	Proizvodnja	Norveška	norway.api.advisor.powerapps.com
Javni	Proizvodnja	Singapur	singapore.api.advisor.powerapps.com
Javni	Proizvodnja	Javna uprava ZDA	gov.api.advisor.powerapps.us
Javni sektor	Produkcija	Javna uprava ZDA L4	high.api.advisor.powerapps.us
Javni sektor	Produkcija	Javna uprava ZDA L5 (DOD)	mil.api.advisor.appsplatform.us
Javni sektor	Produkcija	Kitajsko upravlja ponudnik 21Vianet	china.api.advisor.powerapps.cn

opomba,

Za zgodnejšo vključitev najnovejših funkcij in sprememb lahko uporabite predogled geografske lokacije. Kljub temu upoštevajte, da predogled uporablja samo regije Azure za Združene države Amerike.

Shranjevanje različic

Čeprav ni obvezno, je priporočljivo vključiti parameter poizvedbenega niza različice api z želeno različico API-ja. Trenutna različica API-ja je 2.0 za nabore pravil in pravila ter 1.0 za vse druge zahteve. Naslednji nabor pravil je na primer zahteva HTTP, ki določa uporabo različice API-ja 2.0:

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

Če ni na voljo, se privzeto uporablja najnovejša različica API-ja. Priporočljiva je uporaba eksplicitne številke različice, saj se različica poveča, če so uvedene prelomne spremembe. Če je številka različice določena v zahtevi, bo ohranjena podpora za vzvratno združljivost v poznejših (številčno večjih) različicah.

Nabori pravil in pravila

Pregledovalnik Power Apps zahteva seznam pravil, ko se zažene. Ta pravila so lahko navedena v obliki posameznih pravil ali skupine pravil, imenovane nabor pravil. Nabor pravil je priročen način za določitev skupine pravil, namesto da bi bilo treba določati vsako pravilo posebej. Na primer, funkcija pregledovalnika rešitev uporablja nabor pravil z imenom Pregledovalnik rešitev. Ko so nova pravila dodana ali odstranjena, storitev samodejno vključi te spremembe, ne da bi zahtevala kakršno koli spremembo s strani aplikacije uporabnika. Če zahtevate, da se seznam pravil ne spreminja samodejno, kot je opisano zgoraj, potem lahko pravila določite posebej. Nabori pravil lahko imajo eno ali več pravil brez omejitev. Pravilo je lahko v več naborih pravil ali v nobenem. Seznam vseh naborov pravil lahko dobite tako, da pokličete API na naslednji način: [Geographical URL]/api/ruleset. Ta končna točka zdaj zahteva preverjanje pristnosti.

Nabor pravil pregledovalnika rešitev

Nabor pravil pregledovalnika rešitev vsebuje nabor vplivnih pravil, ki imajo omejene možnosti za napačne pozitivne prepoznave. Če izvajate analizo glede na obstoječo rešitev, je priporočljivo, da začnete s tem naborom pravil. Ta nabor pravil uporablja funkcija preverjevalnik rešitev.

Nabor pravil potrdila AppSource

Ob objavi aplikacij v storitvi AppSource morate pridobiti potrdilo za svojo aplikacijo. Aplikacije, objavljene v storitvi AppSource morajo izpolnjevati visoke standarde kakovosti. Nabor pravil za AppSource certificiranje vsebuje pravila, ki so del nabora pravil za preverjanje rešitev, in druga pravila, ki zagotavljajo, da so v trgovini objavljene samo visokokakovostne aplikacije. Nekatera AppSource certifikacijska pravila so bolj nagnjena k napačno pozitivnim rezultatom in morda zahtevajo več pozornosti za razrešitev.

Iskanje ID-ja najemnika

ID najemnika je potreben za interakcijo z API-ji, ki potrebujejo žeton. Glejte ta članek za podrobnosti o tem, kako pridobiti ID najemnika. Za pridobitev ID-ja najemnika lahko uporabite tudi ukaze PowerShell. Naslednji primer uporablja ukaze cmdlets v modulu AzureAD.

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

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

ID najemnika je vrednost lastnosti ObjectId, ki se vrne iz Get-AzureADTenantDetail. Morda ga boste videli tudi po prijavi z ukazom cmdlet Connect-AzureAD v rezultatih cmdlet. V tem primeru se bo imenoval TenantId.

Preverjanje pristnosti in avtorizacija

Poizvedovanje po pravilih in naborih pravil ne zahteva žetona OAuth, vendar vsi drugi API-ji zahtevajo žeton. API-ji podpirajo odkrivanje avtorizacije tako, da pokličejo kateri koli API, za katerega je potreben žeton. Odgovor je nepooblaščena statusna koda HTTP 401 z glavo WWW-Authenticate, avtorizacijskim URI-jem in ID-jem vira. Svoj ID najemnika morate navesti tudi v glavi x-ms-tenant-id. Za več informacij glejte Power Apps Preverjanje pristnosti in avtorizacija s pregledovalnikom . Sledi primer glave odgovora, vrnjene iz zahteve API-ja:

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

Ko imate te informacije, se lahko odločite za uporabo Microsoftove knjižnice za preverjanje pristnosti (MSAL) ali katerega koli drugega mehanizma za pridobitev žetona. Sledi primer, kako je to mogoče storiti s C# in knjižnico 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();

Za celotno delovno kodo glejte spletni API QuickStart vzorec.

Ko pridobite žeton, je priporočljivo, da zagotovite isti žeton za naslednje klice v življenjskem ciklu zahteve. Vendar pa lahko več zahtev iz varnostnih razlogov zahteva pridobitev novega žetona.

Varnost prenosa

Za najboljše šifriranje v razredu storitev preverjanja podpira samo komunikacije z uporabo Transport Layer Security (TLS) 1.2 in novejših. Za navodila o najboljših praksah .NET glede TLS-ja glejte Najboljše prakse glede varnosti na prenosni plasti (TLS) s storitvijo .NET Framework.

Oblika zapisa poročila

Rezultat analize rešitve je datoteka zip, ki vsebuje eno ali več poročil v standardizirani obliki zapisa JSON. Oblika zapisa poročila temelji na rezultatih statične analize in se imenuje oblika zapisa izmenjave rezultatov statične analize (SARIF). Na voljo so orodja za ogled in interakcijo z dokumenti SARIF. Glej to spletno mesto za podrobnosti. Storitev uporablja drugo različico standarda OASIS.

Glejte tudi