Použitie webového rozhrania API kontroly v rámci platformy Power Apps
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ískajte OAuth token
- 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:
Dokumentáciu k jednotlivým rozhraniam API nájdete v nasledujúcich článkoch:
Získajte zoznam sád pravidiel
Získajte zoznam pravidiel
Nahrajte súbor
Vyvolajte analýzu
Skontrolujte stav 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ť. Žiadosti zverejnené 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é zabezpečia, že v obchode budú zverejnené iba aplikácie vysokej kvality. Niektoré z AppSource pravidiel certifikácie sú náchylnejšie na falošné pozitíva 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ď 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 odpoveď hlavičky 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ť Microsoft Authentication Library (MSAL) alebo nejaký iný mechanizmus na získanie tokenu. Nasleduje príklad toho, ako sa to dá 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 podporuje kontrolná služba iba komunikáciu pomocou Transport vrstva 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ž
Získajte zoznam sád pravidiel
Získajte zoznam pravidiel
Nahrajte súbor
Vyvolajte analýzu
Skontrolujte stav analýzy