Korišćenje Web API-ja za Power Apps kontrolor

Članak
10/16/2024

Power Apps provera Web API-ja nudi mehanizam za pokretanje provera statičke analize u odnosu na prilagođavanja i proširenja na Microsoft Dataverse platformi. Autorima i programerima je dostupno obavljanje obogaćenih provera statičke analize njihovih rešenja u odnosu na skup pravila najboljih praksi da bi brzo identifikovali problematične šablone. Usluga pruža logiku za funkciju provere rešenja na portalu za Power Apps autore i uključena je kao deo automatizacije za aplikacije prosleđene u AppSource. Interakcija sa uslugom direktno na ovaj način omogućava analizu rešenja koja su uključena kao deo lokalni (sve podržane verzije) i online okruženja.

Za informacije o korišćenju usluge za proveru iz PoverShell koda, pogledajte Rad sa rešenjima koja koriste PoverShell.

Belešku

Upotreba Power Apps kontrolora ne garantuje da će uvoz rešenja biti uspešan. Provere statičke analize izvršene prema rešenju ne znaju kako je konfigurisano stanje odredišnog okruženja, a uspeh uvoza može zavisiti od drugih rešenja ili konfiguracija u okruženju.

Alternativni pristupi

Pre nego što pročitate detalje o tome kako da komunicirate na najnižem nivou sa veb API-jima, razmislite o korišćenju našeg PoverShell modula, Microsoft.PowerApps. Checker.PoverShell, umesto toga. To je potpuno podržan alat koji je dostupan u PoverShell galeriji. Trenutno ograničenje je da zahteva Windows PowerShell. Ako ne možete da ispunite ovaj zahtev, onda je interakcija sa API-jima direktno najbolji pristup.

Prvi koraci

Važno je napomenuti da analiza rešenja može rezultirati dugotrajnim procesom. Obično može trajati šezdeset (60) sekundi do više od pet (5) minuta u zavisnosti od različitih faktora, kao što su broj, veličina i složenost prilagođavanja i koda. Tok analize je višestepeni i asinhron, počev od započinjanja posla analize pomoću API-ja statusa koji se koristi za upit za dovršavanje posla. Sledi primer toka za analizu:

Dobijte OAuth token
Otpremanje poziva (za svaku datoteku paralelno)
Analiza poziva (pokreće posao analize)
Status poziva do završetka (petlja sa pauzom između poziva dok se ne signalizira kraj ili se ne dosegnu pragovi)
Preuzimanje rezultata sa obezbeđenog SAS URI-ja

Nekoliko varijacija su:

Uključite pronalaženje skupa pravila ili pravila kao predkorak. Međutim, bilo bi malo brže da prosledite ID konfigurisanog ili direktno kodiranog skupa pravila. Preporučujemo vam da koristite skup pravila koja zadovoljavaju vaše potrebe.
Možete da odlučite da ne koristite mehanizam za otpremanje (pogledajte ograničenja za prenos).

Potrebno je da odredite sledeće uslove:

Koja geografija?
Koja verzija?
Koja pravila i pravila?
Koji je vaš ID stanara?

Pogledajte sledeće članke za dokumentaciju o pojedinačnim API-jima:

Preuzmite listu skupova pravila
Preuzmite listu pravila
Otpremite datoteku
Pozivanje na analizu
Provera statusa analize

Određivanje geografije

Kada stupite u interakciju sa uslugom Power Apps provjere, datoteke se privremeno čuvaju u Azure zajedno sa izveštajima koji se generišu. Korišćenjem API-ja specifičnog za geografsku oblast, možete kontrolisati gde se podaci čuvaju. Zahtevi za geografsku krajnju tačku usmeravaju se na regionalnu instancu na osnovu najboljih performansi (kašnjenje do podnosioca zahteva). Kada zahtev uđe u instancu regionalne usluge, svi podaci o obradi i trajni podaci ostaju u tom određenom regionu. Određeni API odgovori vraćaju URL-ove regionalnih instanci za naredne zahteve kada se posao analize preusmeri u određeni region. Svaka geografija može imati drugačiju verziju usluge raspoređene u bilo kom trenutku. Korišćenje različitih verzija usluga je zbog višestepenog sigurnog procesa raspoređivanja, koji obezbeđuje kompatibilnost pune verzije. Dakle, ista geografija bi trebalo da se koristi za svaki API poziv u životnom ciklusu analize i može smanjiti ukupno vreme izvršavanja, jer podaci možda neće morati da putuju toliko daleko preko žice. Slede dostupne geografske oblasti:

Azure centar podataka	+Ime	Geografska oblast	Osnovni URI
Javno	Verzija za pregled	SAD	unitedstatesfirstrelease.api.advisor.powerapps.com
Javno	Proizvodnja	SAD	unitedstates.api.advisor.powerapps.com
Javno	Proizvodnja	Evropa	europe.api.advisor.powerapps.com
Javno	Proizvodnja	Azija	asia.api.advisor.powerapps.com
Javno	Proizvodnja	Australija	australia.api.advisor.powerapps.com
Javno	Proizvodnja	Japan	japan.api.advisor.powerapps.com
Javno	Proizvodnja	Indija	india.api.advisor.powerapps.com
Javno	Proizvodnja	Kanada	canada.api.advisor.powerapps.com
Javno	Proizvodnja	Južna Amerika	southamerica.api.advisor.powerapps.com
Javno	Proizvodnja	Ujedinjeno Kraljevstvo	unitedkingdom.api.advisor.powerapps.com
Javno	Proizvodnja	Francuska	france.api.advisor.powerapps.com
Javni	Produkcija	Nemačka	germany.api.advisor.powerapps.com
Javni	Produkcija	Ujedinjeni Arapski Emirati	unitedarabemirates.api.advisor.powerapps.com
Javni	Produkcija	Švajcarska	switzerland.api.advisor.powerapps.com
Javni	Produkcija	Južnoafrčka Republika	southafrica.api.advisor.powerapps.com
Javni	Produkcija	Južna Koreja	korea.api.advisor.powerapps.com
Javni	Produkcija	Norveška	norway.api.advisor.powerapps.com
Javni	Produkcija	Singapur	singapore.api.advisor.powerapps.com
Javni	Produkcija	Švedska	sweden.api.advisor.powerapps.com
Javni	Produkcija	US Government	gov.api.advisor.powerapps.us
Javno	Proizvodnja	Državne institucije SAD L4	high.api.advisor.powerapps.us
Javno	Proizvodnja	Državne institucije SAD L5 (DOD)	mil.api.advisor.appsplatform.us
Javno	Proizvodnja	Kina, upravlja 21Vianet	china.api.advisor.powerapps.cn

Belešku

Možete odabrati da koristite geografsku oblast za pregled da biste ranije uključili najnovije funkcije i izmene. Međutim, imajte na umu da se za pregled koristi samo Azure region u SAD.

Kreiranje verzija

Iako nije potrebno, preporučuje se da uključite parametar niza upita API-version sa željenom verzijom API-ja. Trenutna verzija API-ja je 2.0 za skupove pravila i pravila i 1.0 za sve ostale zahteve. Na primer, sledeći skup pravila je HTTP zahtev koji određuje da koristi KSNUMKS API verziju:

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

Ako nije obezbeđen, najnovija verzija API-ja se podrazumevano koristi. Korišćenje eksplicitnog broja verzije se preporučuje jer se verzija povećava ako se uvode razbijajuće izmene. Ako je broj verzije naveden u zahtevu, održaće se podrška za kompatibilnost sa starijim verzijama u kasnijim (brojčano većim) verzijama.

Skupovi pravila i pravila

Power Apps kontrolor zahteva listu pravila kada se pokrene. Ta pravila se mogu navoditi u obliku pojedinačnih pravila ili grupe pravila koja se naziva skup pravila. Skup pravila je prikladan način za određivanje grupe pravila umesto da se svako pravilo pojedinačno određuje. Na primer, funkcija provere rešenja koristi skup pravila pod nazivom Provera rešenja. Kako se nova pravila dodaju ili uklanjaju, usluga automatski uključuje ove promene bez potrebe za bilo kakvom promenom od strane aplikacije koja troši. Ako želite da se lista pravila ne menja automatski kao što je gore opisano, onda se pravila mogu odrediti pojedinačno. Skupovi pravila mogu imati jedno ili više pravila bez ograničenja. Pravilo može biti bez skupa pravila ili u više skupova pravila. Listu svih skupova pravila možete dobiti tako što ćete pozvati API na sledeći način: [Geographical URL]/api/ruleset. Ova krajnja tačka sada zahteva autentifikaciju.

Skup pravila za proveru rešenja

Skup pravila za proveru rešenja sadrži skup uticajnih pravila koja imaju ograničene šanse za lažne pozitivne rezultate. Ako pokrećete analizu u odnosu na postojeće rešenje, preporučuje se da počnete sa ovim setom pravila. Ovaj skup pravila koristi funkcija za proverurešenja.

AppSource set pravila sertifikacije

Prilikom objavljivanja aplikacija na lokaciji AppSource, morate sertifikovati aplikaciju. Prijave objavljene na AppSource moraju zadovoljiti visoke standarde kvaliteta. Skup AppSource pravila za sertifikaciju sadrži pravila koja su deo pravila za proveru rešenja, kao i druga pravila kako bi se osiguralo da se u prodavnici objavljuju samo aplikacije visokog kvaliteta. Neka od AppSource pravila sertifikacije su skloniji lažnim pozitivnim rezultatima i mogu zahtevati više pažnje za rešavanje.

Pronađite ID svog zakupca

ID vašeg zakupca je potreban za interakciju sa API-jima koji zahtevaju token. Pogledajte Ovaj članak za detalje o tome kako da dobijete ID zakupca. Takođe možete da koristite PowerShell komande da biste preuzeli ID zakupca. Sledeći primer primenjuje cmdlete u modulu AzureAD.

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

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

ID zakupca je vrednost svojstva ObjectId koju vraća funkcija Get-AzureADTenantDetail. Možete ga videti i nakon što se prijavite koristeći cmdlet komandu Connect-AzureAD na izlazu cmdlet komande. U ovom slučaju, to će biti imenovano TenantId.

Potvrda identiteta i autorizacija

Upit za pravila i skupove pravila ne zahtevaju OAuth token, ali svi ostali API-ji zahtevaju token. API-ji podržavaju otkrivanje autorizacije pozivanjem bilo kojeg API-ja za koji je potreban token. Odgovor je neovlašćeni HTTP statusni kod 401 sa VVV-Authenticate zaglavljem, autorizacijskim URI-jem i ID-om resursa. Takođe bi trebalo da navedete svoj ID zakupca u zaglavlju x-ms-tenant-id. Pogledajte Power Apps Checker autentifikaciju i autorizaciju za više informacija. Sledi primer zaglavlja odgovor vraćenog iz API zahteva:

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

Kada dobijete ove informacije, možete da izaberete da koristite biblioteku Microsoft za autentifikaciju (MSAL) ili neki drugi mehanizam za sticanje tokena. Sledi primer kako se to može uraditi korišćenjem C# i MSAL .NET biblioteke :

// 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 kompletan radni kod, pogledajte Veb API KuickStart primer.

Kada ste stekli token, savetuje se da obezbedite isti token za naredne pozive u životnom ciklusu zahteva. Međutim, više zahteva može garantovati novi token da se stekne iz bezbednosnih razloga.

Bezbednost u transportu

Za najbolju enkripciju u klasi, usluga provjere podržava samo komunikacije koristeći Transport sloj Securiti (TLS) KSNUMKS i više. Kao uputstvo o najboljim .NET praksama u vezi sa TLS-om, pogledajte Najbolje prakse za Transport Layer Security (TLS) sa platformom .NET Framework.

Format izveštaja

Rezultat analize rešenja je ZIP datoteka koja sadrži jedan ili više izveštaja u standardizovanom JSON formatu. Format izveštaja je zasnovan na rezultatima statičke analize koja se naziva „format razmene rezultata statičke analize“ (SARIF). Na raspolaganju su vam alati za prikaz i interakciju sa SARIF dokumentima. Pogledajte ovu veb-lokaciju za detalje. Usluga koristi drugu verziju OASIS standarda.

Pogledajte i ovo