Dijeli putem

Upotreba API-ja na webu alata za provjeru servisa Power Apps

  • Članak

Web API za provjeru aplikacija Power Apps donosi mehanizam za pokretanje statičke analize prema prilagodbama i proširenjima na platformi Microsoft Dataverse. Dostupan je autorima i razvojnim inženjerima za izvršavanje opsežnih statičkih, analitičkih provjera na njihovim rješenjima u odnosu na niz najboljih pravila iz prakse, a u svrhu utvrđivanja problematičnih obrazaca. Usluga pruža logiku za značajku alata za provjeru rješenja na portalu autora servisa Power Apps i uključena je kao dio automatizacije za aplikacije poslane trgovini AppSource. Interakcija s uslugom izravno na ovaj način omogućuje analizu rješenja koja su uključena kao dio lokalno (sve podržane verzije) i mrežnih okruženja.

Informacije o korištenju servisa za provjeru iz koda ljuske PowerShell potražite u članku Rad s rješenjima pomoću komponente PowerShell.

Napomena

  • Upotreba alata za provjeru Power Apps ne jamči da će uvoz rješenja biti uspješan. Provjere statičke analize obavljene na rješenju ne znaju konfigurirano stanje odredišnog okruženja, a uspjeh uvoza može ovisiti o drugim rješenjima ili konfiguracijama u okruženju.

Alternativni pristupi

Prije nego što pročitate detalje o interakciji na najnižoj razini s web-API-jevima, razmislite o korištenju našeg modula PowerShell, Microsoft.PowerApps. Checker.PowerShell, umjesto toga. To je potpuno podržan alat koji je dostupan u galeriji ljuske PowerShell. Trenutno ograničenje zahtijeva korištenje okvira PowerShell sustava Windows. Ako ne možete ispuniti ovaj zahtjev, tada je izravna interakcija s API-jevima najbolji pristup.

Početak rada

Važno je napomenuti da analiza rješenja može rezultirati dugotrajnim procesom. Obično može potrajati šezdeset (60) sekundi do više od pet (5) minuta, ovisno o različitim čimbenicima, kao što su broj, veličina i složenost prilagodbi i koda. Tok analize ima više koraka i asinkron je počevši od pokretanja posla analize s API-jem statusa koji se koristi za upit za dovršavanje posla. Primjer toka za analizu je sljedeći:

  1. Dobivanje OAuth tokena
  2. Prijenos poziva (za svaku datoteku paralelno)
  3. Analiza poziva (pokreće posao analize)
  4. Status poziva do završetka (kružno pozivanje s pauzom između poziva dok se ne signalizira kraj ili se dosegnu ograničenja)
  5. Preuzimanje rezultata iz ponuđenog URI-ja SAS-a

Nekoliko varijacija je:

  • Uključite pretraživanje skupa pravila ili pravila kao pred-korak. Međutim, bit će malo brže predati u konfiguriranom ili ID-u skupa pravila ovisnom o programskom kodu. Preporučuje se upotreba skupa pravila koji odgovara vašim potrebama.
  • Možete se odlučiti da ne koristite mehanizam za prijenos (ograničenja potražite u prijenosu).

Morate odrediti sljedeće zahtjeve:

Dokumentaciju o pojedinačnim API-jevima potražite u sljedećim člancima:

Dohvaćanje popisa skupova pravila
Dohvaćanje popisa pravila
Prijenos datoteke
Pozivanje analize
Provjera statusa analize

Određivanje geografije

Kada stupite u interakciju sa servisom za provjeru, datoteke se privremeno pohranjuju na servisu Power Apps Azure zajedno s generiranim izvješćima. Korištenjem API-ja za specifičnu geografiju, možete kontrolirati gdje se podaci pohranjuju. Zahtjevi na zemljopisnu krajnju točku preusmjeravaju se na regionalnu instancu na temelju najbolje izvedbe (latencija prema podnositelju zahtjeva). Jednom kada zahtjev uđe u regionalnu instancu usluge, svi podaci o obradi i trajni podaci ostaju u toj određenoj regiji. Određeni odgovori API-ja vraćaju URL-ove regionalnih instanci za naknadne zahtjeve nakon što se posao analize usmjeri u određenu regiju. Svaka geografija može imati različitu verziju usluge implementiranu u bilo kojem trenutku. Korištenje različitih verzija usluga posljedica je višestupanjskog postupka sigurne implementacije, koji osigurava potpunu kompatibilnost verzija. Dakle, isto zemljopisno područje treba se koristiti za svaki API poziv u životnom ciklusu analize i može smanjiti sveukupno vrijeme izvršavanja jer podaci možda neće morati putovati tako daleko preko žice. Slijede dostupne geografije:

Podatkovni centar Azure Naziv Geografija Osnovni URI
Javna dobra Pretpregledaj Sjedinjene Američke Države unitedstatesfirstrelease.api.advisor.powerapps.com
Javna dobra Produkcija Sjedinjene Američke Države unitedstates.api.advisor.powerapps.com
Javna dobra Produkcija Europa europe.api.advisor.powerapps.com
Javna dobra Produkcija Azija asia.api.advisor.powerapps.com
Javna dobra Produkcija Australija australia.api.advisor.powerapps.com
Javna dobra Produkcija Japan japan.api.advisor.powerapps.com
Javna dobra Produkcija Indija india.api.advisor.powerapps.com
Javna dobra Produkcija Kanada canada.api.advisor.powerapps.com
Javna dobra Produkcija Južna Amerika southamerica.api.advisor.powerapps.com
Javna dobra Produkcija Velika Britanija unitedkingdom.api.advisor.powerapps.com
Javna dobra Produkcija Francuska france.api.advisor.powerapps.com
Javni podaci Proizvodnja Njemačka germany.api.advisor.powerapps.com
Javni podaci Proizvodnja Ujedinjeni Arapski Emirati unitedarabemirates.api.advisor.powerapps.com
Javni podaci Proizvodnja Švicarska switzerland.api.advisor.powerapps.com
Javni podaci Proizvodnja Južnoafrička Republika southafrica.api.advisor.powerapps.com
Javni podaci Proizvodnja Južna Koreja korea.api.advisor.powerapps.com
Javni podaci Proizvodnja Norveška norway.api.advisor.powerapps.com
Javni podaci Proizvodnja Singapur singapore.api.advisor.powerapps.com
Javni podaci Proizvodnja Švedska sweden.api.advisor.powerapps.com
Javni podaci Proizvodnja za američke državne ustanove gov.api.advisor.powerapps.us
Javna dobra Produkcija Vlada Sjedinjenih Američkih Država L4 high.api.advisor.powerapps.us
Javna dobra Produkcija Vlada Sjedinjenih Američkih Država L5 (DOD) mil.api.advisor.appsplatform.us
Javna dobra Produkcija Upravlja Kina putem 21Vianeta china.api.advisor.powerapps.cn

Napomena

Možete se odlučiti na upotrebu pretpregleda geografije kako biste ranije uključili najnovije značajke i promjene. Međutim, imajte na umu da se pretpregled koristi samo za regije Sjedinjenih Država za Azure.

Određivanje verzije

Iako nije potrebno, preporučuje se uključiti parametar niza upita api-verzije sa željenom verzijom API-ja. Trenutna verzija API-ja je 2.0 za skupove pravila i pravila i 1.0 za sve ostale zahtjeve. Na primjer, sljedeći skup pravila je HTTP zahtjev koji određuje korištenje verzije 2.0 API:

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

Ako nije navedeno, najnovija verzija API-ja koristi se prema zadanim postavkama. Preporučuje se upotreba eksplicitnog broja verzije jer se verzija povećava ako se uvedu prijelomne promjene. Ako je broj verzije naveden u zahtjevu, u novijim (brojčano većim) verzijama zadržat će se podrška za kompatibilnost s prijašnjim verzijama.

Skupovi pravila i pravila

Alat za provjeru servisa Power Apps zahtijeva popis pravila prilikom pokretanja. Ta se pravila mogu pružiti u obliku pojedinačnih pravila ili grupa pravila koje se nazivaju skup pravila. Skup pravila je zgodan način za određivanje grupe pravila umjesto da se svako pravilo pojedinačno određuje. Na primjer, značajka alata za provjeru rješenja koristi skup pravila s nazivom Alat za provjeru rješenja. Kako se nova pravila dodaju ili uklanjaju, usluga automatski uključuje te promjene bez potrebe za promjenom od strane aplikacije koja troši. Ako želite da se popis pravila ne mijenja automatski na prethodno opisani način, pravila se mogu odrediti pojedinačno. Skupovi pravila mogu imati jedno ili više pravila bez ograničenja. Pravilo ne mora biti u skupu pravila ili može biti u više skupova. Popis svih skupova pravila možete dobiti pozivanjem API-ja na sljedeći način: [Geographical URL]/api/ruleset. Ovaj krajnja točka sada zahtijeva provjeru autentičnosti.

Skup pravila alata za provjeru rješenja

Skup pravila alata za provjeru rješenja sadrži skup djelotvornih pravila u kojima su šanse za pogrešno otkrivanje ograničene. Ako pokrećete analizu u odnosu na postojeće rješenje, preporučuje se da započnete s ovim skupom pravila. Ovaj skup pravila koristi značajka alata za provjeru rješenja.

Skup pravila certifikacije trgovine AppSource

Prilikom objavljivanja aplikacija u trgovini AppSource, vašu aplikaciju morate certificirati. Aplikacije objavljene u trgovini AppSource moraju ispunjavati visoke standarde kvalitete. Skup AppSource pravila certificiranja sadrži pravila koja su dio skupa pravila za provjeru rješenja, kao i druga pravila kako bi se osiguralo da se u trgovini objavljuju samo visokokvalitetne aplikacije. Neka od AppSource pravila certificiranja sklonija su lažno pozitivnim rezultatima i mogu zahtijevati više pozornosti za rješavanje.

Pronalaženje ID-a svog klijenta

ID vašeg klijenta potreban je za interakciju s API-jima koji zahtijevaju token. Pogledajte ovaj članak za pojedinosti o tome kako dobiti ID klijenta. Također možete koristiti naredbe okvira PowerShell za dohvaćanje ID-a klijenta. Sljedeći primjer primjenjuje cmdlete u modulu AzureAD.

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

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

ID klijenta je vrijednost svojstva ObjectId dobivena iz Get-AzureADTenantDetail. Također ga možete vidjeti nakon prijave pomoću cmdleta Connect-AzureAD u rezultatu cmdleta. U ovom slučaju, bit će imenovan. TenantId

Provjera autentičnosti i autorizacija

Za traženje pravila i skupova pravila nije potreban OAuth token, ali svi ostali API-ji zahtijevaju token. API-ji podržavaju otkrivanje autorizacije pozivanjem bilo kojeg API-ja za koji je potreban token. Odgovor je neovlašteni HTTP kod stanja 401 sa zaglavljem WWW-Authenticate, URI autorizacije i ID-om resursa. Trebate također navesti ID svog klijenta u zaglavlju x-ms-tenant-id. Dodatne informacije potražite u Power Apps provjeri autentičnosti i autorizaciji . Slijedi primjer zaglavlja odgovora vraćenog iz API zahtjeva:

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

Nakon što dobijete te podatke, možete odabrati korištenje Microsoftove biblioteke provjere autentičnosti (MSAL) ili nekog drugog mehanizma za dohvaćanje tokena. Slijedi primjer kako se to može učiniti pomoću 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();

Potpuni radni kod potražite u uzorku QuickStart web-API-ja.

Nakon što nabavite token, savjetuje se da navedete isti token za sljedeće pozive u životnom ciklusu zahtjeva. Međutim, više zahtjeva može jamčiti da se novi token nabavi iz sigurnosnih razloga.

Sigurnost prijenosa

Za najbolju enkripciju u klasi, usluga provjere podržava komunikaciju samo pomoću Transport Layer Security (TLS) 1.2 i novijih. Smjernice o najboljim praksama za .NET u vezi s TLS-om potražite u odjeljku Najbolje prakse za Transport Layer Security (TLS) s okvirom .NET Framework.

Format izvješća

Rezultat analize rješenja je zip datoteka koja sadrži jedno ili više izvješća u standardiziranom JSON formatu. Format izvješća temelji se na rezultatima statičke analize koji se nazivaju Format razmjene rezultata statičke analize (SARIF). Dostupni su alati za pregled i interakciju sa SARIF dokumentima. Pogledajte ovo web-mjesto za pojedinosti. Usluga koristi drugu verziju OASIS standarda.

Pogledajte

Dohvaćanje popisa skupova pravila
Dohvaćanje popisa pravila
Prijenos datoteke
Pozivanje analize
Provjera statusa analize