Použitie webového rozhrania API kontroly v rámci platformy Power Apps

Článok
05/01/2024

Web kontroly Power Apps API poskytuje mechanizmus na vykonávanie kontrol statickej analýzy v porovnaní s prispôsobeniami a rozšíreniami platformy Microsoft Dataverse. Je k dispozícii pre tvorcov a vývojárov na realizáciu bohatých štatistických kontrol svojich riešení v porovnaní so súborom pravidiel osvedčených postupov na rýchlu identifikáciu problematických vzorcov. Táto služba poskytuje logiku pre funkciu kontroly riešení na portáli výrobcu Power Apps a je súčasťou automatizácie aplikácií odoslaných do AppSource. Priama interakcia so službou týmto spôsobom umožňuje analýzu riešení, ktoré sú súčasťou lokálny (všetky podporované verzie) a online prostredí.

Informácie o používaní služby kontroly z kódu PowerShell nájdete v časti Práca s riešeniami pomocou prostredia PowerShell.

Poznámka

Použitie kontroly Power Apps nezaručuje, že import riešenia bude úspešný. Kontroly statickej analýzy vykonané voči riešeniu nepoznajú nakonfigurovaný stav cieľového prostredia a úspešnosť importu môže závisieť od iných riešení alebo konfigurácií v prostredí.

Alternatívne prístupy

Pred prečítaním podrobností o tom, ako interagovať na najnižšej úrovni s webovými rozhraniami API, zvážte použitie nášho modulu PowerShell, Microsoft.PowerApps.Checker.PowerShell. Ide o plne podporovaný nástroj, ktorý je dostupný v galérii PowerShell. Aktuálne obmedzenie spočíva v tom, že vyžaduje Windows PowerShell. Ak nie je možné splniť túto požiadavku, potom je najlepším prístupom priama interakcia s API.

Začíname

Je dôležité poznamenať, že analýza riešenia môže viesť k dlhotrvajúcemu procesu. Zvyčajne to môže trvať šesťdesiat (60) sekúnd až päť (5) minút v závislosti od rôznych faktorov, ako je počet, veľkosť a zložitosť prispôsobení a kódu. Priebeh analýzy je viacstupňový a asynchrónny a počína začatím analytickej úlohy s použitím stavového rozhrania API, ktoré sa používa na dotazovanie dokončenia úlohy. Príklad postupu pre analýzu je nasledujúci:

Získanie tokenu OAuth
Nahranie volania (pre každý súbor súčasne)
Analýza volania (iniciuje úlohu analýzy)
Stav volania do skončenia (opakovanie s prestávkou medzi volaniami, kým nie je signalizovaný koniec alebo nie sú splnené prahy)
Stiahnite si výsledky z poskytnutého SAS URI

Niekoľko variácií:

Zahrňte vyhľadávanie sady pravidiel alebo pravidiel ako predbežný krok. Bolo by však o niečo rýchlejšie odovzdať nakonfigurované alebo pevne kódované ID sady pravidiel. Odporúča sa používať sadu pravidiel, ktorá vyhovuje vašim potrebám.
Môžete sa rozhodnúť nepoužiť mechanizmus odovzdávania (obmedzenia nájdete v odovzdávaní).

Musíte určiť nasledujúce požiadavky:

Ktorá geografia?
Ktorá verzia?
Ktoré sady pravidiel a pravidlá?
Aké je vaše ID nájomníka?

Dokumentáciu k jednotlivým rozhraniam API nájdete v nasledujúcich článkoch:

Načítanie zoznamu množín pravidiel
Načítanie zoznamu pravidiel
Odovzdanie súboru
Vyvolanie analýzy
Kontrola stavu analýzy

Určenie geografie

Pri interakcii so službou kontroly Power Apps sa súbory dočasne uložia v Azure spolu s vygenerovanými zostavami. Použitím geografického rozhrania API môžete určiť, kde budú dáta uložené. Žiadosti o geografický koncový bod sa smerujú do regionálnej inštancie na základe najlepšieho výkonu (latencia pre žiadateľa). Len čo požiadavka vstúpi do inštancie regionálnej služby, všetko spracovanie a trvalé údaje zostanú v konkrétnom regióne. Niektoré odpovede rozhrania API vracajú adresy URL regionálnych inštancií pre následné požiadavky, keď je úloha analýzy smerovaná do konkrétnej oblasti. Každá geografická oblasť môže mať v danom čase nasadenú inú verziu služby. Použitie rôznych verzií služieb je spôsobené viacstupňovým bezpečným procesom nasadenia, ktorý zaisťuje plnú kompatibilitu verzií. Rovnaká geografická poloha by sa teda mala použiť pre každé volanie API v životnom cykle analýzy a môže tak znížiť celkový čas vykonania, pretože údaje nemusia cestovať veľmi ďaleko po kábli. Dostupné sú nasledujúce geografie:

Dátové centrum Azure	Meno	Geografická oblasť	Základné URI
Verejná	Ukážková	USA	unitedstatesfirstrelease.api.advisor.powerapps.com
Verejná	Výrobná verzia	USA	unitedstates.api.advisor.powerapps.com
Verejná	Výrobná verzia	Európa	europe.api.advisor.powerapps.com
Verejná	Výrobná verzia	Ázia	asia.api.advisor.powerapps.com
Verejná	Výrobná verzia	Austrália	australia.api.advisor.powerapps.com
Verejná	Výrobná verzia	Japonsko	japan.api.advisor.powerapps.com
Verejná	Výrobná verzia	India	india.api.advisor.powerapps.com
Verejná	Výrobná verzia	Kanada	canada.api.advisor.powerapps.com
Verejná	Výrobná verzia	Južná Amerika	southamerica.api.advisor.powerapps.com
Verejná	Výrobná verzia	Spojené kráľovstvo	unitedkingdom.api.advisor.powerapps.com
Verejná	Výrobná verzia	Francúzsko	france.api.advisor.powerapps.com
Verejná	Produkčné	Nemecko	germany.api.advisor.powerapps.com
Verejná	Produkčné	Spojené Arabské Emiráty	unitedarabemirates.api.advisor.powerapps.com
Verejný	Produkčné	Švajčiarsko	switzerland.api.advisor.powerapps.com
Verejný	Produkčné	Južná Afrika	southafrica.api.advisor.powerapps.com
Verejný	Produkčné	Kórejská republika	korea.api.advisor.powerapps.com
Verejný	Produkčné	Nórsko	norway.api.advisor.powerapps.com
Verejný	Produkčné	Singapur	singapore.api.advisor.powerapps.com
Verejný	Produkčné	Švédsko	sweden.api.advisor.powerapps.com
Verejný	Produkčné	US Government	gov.api.advisor.powerapps.us
Verejná	Výrobná verzia	Vláda USA L4	high.api.advisor.powerapps.us
Verejná	Výrobná verzia	Vláda USA L5 (DOD)	mil.api.advisor.appsplatform.us
Verejná	Výrobná verzia	Čína cez 21Vianet	china.api.advisor.powerapps.cn

Poznámka

Môžete sa rozhodnúť použiť geografiu ukážky na skoršie včlenenie najnovších funkcií a zmien. Všimnite si však, že náhľad používa iba regióny Azure v USA.

Určovanie verzie

Hoci sa to nevyžaduje, odporúča sa zahrnúť parameter reťazca dotazu verzie rozhrania API s požadovanou verziou rozhrania API. Aktuálna verzia API je 2.0 pre sady pravidiel a pravidlá a 1.0 pre všetky ostatné požiadavky. Napríklad nasledujúca sada pravidiel je požiadavka HTTP špecifikujúca použitie verzie 2.0 API:

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

Ak nie je k dispozícii, predvolene sa použije najnovšia verzia rozhrania API. Odporúča sa použiť explicitné číslo verzie, pretože verzia sa zvýši, ak sa zavedú rušivé zmeny. Ak je v žiadosti uvedené číslo verzie, zachová sa podpora spätnej kompatibility v neskorších (číselne) verziách.

Sady pravidiel a pravidlá

Kontrola Power Apps vyžaduje pri spustení zoznam pravidiel. Tieto pravidlá môžu byť stanovené vo forme individuálnych pravidiel alebo zoskupení pravidiel, ktoré sa označujú ako sada pravidiel. Sada pravidiel je pohodlný spôsob, ako určiť skupinu pravidiel namiesto toho, aby ste museli každé pravidlo špecifikovať jednotlivo. Napríklad funkcia kontroly riešení používa sadu pravidiel s názvom Kontrola riešenia. Pri pridávaní alebo odstraňovaní nových pravidiel služba tieto zmeny automaticky zahŕňa bez toho, aby vyžadovala akúkoľvek zmenu zo strany spotrebúvajúcej aplikácie. Ak požadujete, aby sa zoznam pravidiel nezmenil automaticky, ako je opísané vyššie, potom je možné pravidlá špecifikovať individuálne. Pravidlá môžu mať jedno alebo viac pravidiel bez obmedzenia. Pravidlo môže byť v žiadnej alebo viacerých sadách pravidiel. Zoznam všetkých sád pravidiel môžete získať tak, že zavoláte API nasledovne: [Geographical URL]/api/ruleset. Tento koncový bod teraz vyžaduje autentifikáciu.

Sada pravidiel kontroly riešenia

Sada pravidiel pre kontrolu riešení obsahuje súbor efektívnych pravidiel, ktoré majú obmedzené šance na falošné poplachy. Ak spúšťate analýzu oproti existujúcemu riešeniu, odporúča sa začať s touto sadou pravidiel. Túto sadu pravidiel používa funkcia kontroly riešení.

Sada pravidiel certifikácie AppSource

Pri publikovaní aplikácií na AppSource musíte svoju aplikáciu certifikovať. Aplikácie publikované na AppSource musia spĺňať vysoký štandard kvality. Sada AppSource certifikačných pravidiel obsahuje pravidlá, ktoré sú súčasťou sady pravidiel kontroly riešení, plus ďalšie pravidlá, ktoré zaisťujú, že v obchode budú zverejnené iba aplikácie vysokej kvality. Niektoré z AppSource pravidiel certifikácie sú náchylnejšie na falošné poplachy a ich vyriešenie môže vyžadovať väčšiu pozornosť.

Nájdite ID svojho nájomníka

ID vášho nájomníka je potrebné na interakciu s API, ktoré vyžadujú token. Prečítajte si tento článok, kde nájdete podrobnosti o tom, ako získať ID nájomníka. Príkazy PowerShell môžete tiež použiť na získanie ID nájomníka. Nasledujúci príklad aplikuje rutiny cmdlet v module AzureAD.

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

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

ID nájomníka je hodnota vlastností ObjectId, ktorá sa vracia z Get-AzureADTenantDetail. Môžete ju vidieť aj po prihlásení pomocou rutiny cmdlet Connect-AzureAD vo výstupe rutiny cmdlet. V tomto prípade bude mať názov TenantId.

Autentifikácia a autorizácia

Dopyt na pravidlá a sady pravidiel nevyžaduje token OAuth, ale všetky ostatné rozhrania API token vyžadujú. Rozhrania API podporujú zisťovanie autorizácie volaním ktoréhokoľvek z rozhraní API, ktoré vyžadujú token. Odpoveďou je neautorizovaný stavový kód HTTP 401 s hlavičkou WWW-Authenticate, autorizačným URI a ID prostriedku. Mali by ste uviesť aj svoje ID nájomníka v hlavičke x-ms-tenant-id. Ďalšie informácie nájdete v časti Power Apps Kontrola overenia a autorizácie . Nasleduje príklad hlavičky odpovede vrátenej z požiadavky API:

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

Keď budete mať tieto informácie, môžete sa rozhodnúť použiť na získanie tokenu knižnicu Microsoft Authentication Library (MSAL) alebo iný mechanizmus. Nasleduje príklad toho, ako to možno urobiť pomocou jazyka C# a knižnice 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();

Úplný funkčný kód nájdete vo webovom rozhraní API Ukážka rýchleho spustenia.

Po získaní tokenu sa odporúča poskytnúť rovnaký token pre nasledujúce volania v životnom cykle žiadosti. Viac žiadostí však môže z bezpečnostných dôvodov vyžadovať získanie nového tokenu.

Bezpečnosť prenosu

Pre najlepšie šifrovanie vo svojej triede služba checker podporuje iba komunikáciu pomocou Transport Layer Security (TLS) 1.2 a vyššej. Informácie o osvedčených postupoch .NET týkajúcich sa TLS nájdete na stránke Najlepšie postupy týkajúce sa zabezpečenia transportnej vrstvy (TLS) s .NET Framework.

Formát zostavy

Výsledkom analýzy riešenia je súbor zip obsahujúci jednu alebo viac zostáv v štandardizovanom formáte JSON. Formát zostavy je založený na výsledkoch statickej analýzy označovaných ako Static Analysis Results Interchange Format (SARIF). K dispozícii sú nástroje na prezeranie a interakciu s dokumentmi SARIF. Pozrite si tieto webové stránky pre viac informácií. Služba používa verziu dva štandardu OASIS.

Pozrite si tiež