Zdieľať cez

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

  • Článok

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:

  1. Získajte OAuth token
  2. Nahranie volania (pre každý súbor súčasne)
  3. Analýza volania (iniciuje úlohu analýzy)
  4. Stav volania do skončenia (opakovanie s prestávkou medzi volaniami, kým nie je signalizovaný koniec alebo nie sú splnené prahy)
  5. 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