Používání webového rozhraní API služby Power Apps Checker

Webové rozhraní API Power Apps Checker poskytuje mechanismus pro spouštění kontrol statické analýzy proti přizpůsobení a rozšíření platformy Microsoft Dataverse. Je k dispozici pro tvůrce a vývojáře, kteří mohou provést bohatou kontrolu statické analýzy svých řešení proti souboru pravidel osvědčených postupů a rychle identifikovat problematické vzorce. Služba kontroly poskytuje logiku pro funkce pro kontrolu řešení v Power Apps Maker Portal a je součástí automatizace systému pro žádosti předložené do AppSource. Přímá interakce se službou umožňuje analýzu řešení, která jsou součástí místních (všechny podporované verze) a online prostředí.

Informace o používání služby kontroly z kódu PowerShell naleznete v části Práce s řešeními pomocí PowerShell.

Poznámka

Power Apps Checker nezaručuje, že import řešení bude úspěšný. Kontroly statické analýzy řešení neznají nakonfigurovaný stav cílového prostředí a úspěch importu může záviset na jiných řešeních nebo konfiguracích v prostředí.

Alternativní přístupy

Před přečtením podrobností o tom, jak komunikovat na nejnižší úrovni s webovými rozhraními API, zvažte místo toho využití našeho modulu PowerShell, Microsoft.PowerApps.Checker.PowerShell. Jedná se o plně podporovaný nástroj, který je k dispozici v galerii PowerShell. Aktuální omezení je, že to vyžaduje Windows PowerShell. Pokud nebudete schopen splnit tento požadavek, je nejlepším řešením interakce s rozhraními API.

Začínáme

Je důležité si uvědomit, že analýza řešení může vést k dlouhodobému procesu. Obvykle to může trvat šedesát (60) vteřin až pět (5) minut v závislosti na různých faktorech, jako je počet, velikost a složitost vlastních nastavení a kódu. Tok analýzy je vícestupňový a asynchronní počínaje zahájením úlohy analýzy s použitím stavového rozhraní API, které se používá k dotazování na dokončení úlohy. Příklad toku pro analýzu je následující:

Obdržení tokenu OAuth
Odeslání volání (pro každý soubor paralelně)
Analýza volání (inicializuje úlohu analýzy)
Stav hovoru do ukončení (opakování s přestávkou mezi hovory, dokud není signalizován konec nebo není dosaženo prahových hodnot)
Stáhněte si výsledky z poskytnutého SAS URI.

Zde je několik variant:

Zahrňte vyhledávání sady pravidel nebo pravidel jako předběžný krok. Bylo by však o něco rychlejší předat v ID konfigurované nebo pevně kódované sady pravidel. Doporučujeme používat sadu pravidel, která vyhovuje vašim potřebám.
Můžete se rozhodnout, že nebudete používat mechanismus nahrávání (omezení naleznete v části věnující se nahrávání).

Budete muset určit následující požadavky:

Která geografie?
Která verze?
Které sady pravidel a pravidla?
Jaké je ID vašeho tenanta?

Dokumentaci k jednotlivým rozhraním API naleznete v následujících článcích:

Načtení seznamu sad pravidel
Načtení seznamu pravidel
Odeslání souboru
Vyvolání analýzy
Kontrola stavu analýzy

Určení geografie

Při interakci se službou Power Apps Checker jsou soubory dočasně uloženy v Azure spolu s generovanými sestavami. Pomocí rozhraní API pro danou geografii můžete určit, kde budou data uložena. Požadavky na geografický koncový bod jsou směrovány do oblastní instance na základě nejlepšího výkonu (latence směrem k žadateli). Jakmile požadavek vstoupí do instance oblastní služby, veškeré zpracování a trvalá data zůstanou v dané konkrétní oblasti. Určité odpovědi API vrátí adresy URL oblastní instance pro následné požadavky, jakmile je úloha analýzy směrována do konkrétní oblasti. Každá geografická oblast může mít v daném časovém okamžiku nasazenou jinou verzi služby. Použití různých verzí služeb je způsobeno vícestupňovým bezpečným procesem nasazení, který zajišťuje plnou kompatibilitu verzí. Pro každé volání API v životním cyklu analýzy by tedy měla být použita stejná geografie a může zkrátit celkovou dobu provádění, protože data nemusí cestovat tak daleko po drátu. K dispozici jsou následující geografie:

Datové centrum Azure	Název	Zeměpisná oblast	Základní identifikátor URI
Veřejná	Preview	USA	unitedstatesfirstrelease.api.advisor.powerapps.com
Veřejná	Výroba	USA	unitedstates.api.advisor.powerapps.com
Veřejná	Výroba	Evropa	europe.api.advisor.powerapps.com
Veřejná	Výroba	Asie	asia.api.advisor.powerapps.com
Veřejná	Výroba	Austrálie	australia.api.advisor.powerapps.com
Veřejná	Výroba	Japonsko	japan.api.advisor.powerapps.com
Veřejná	Výroba	Indie	india.api.advisor.powerapps.com
Veřejná	Výroba	Kanada	canada.api.advisor.powerapps.com
Veřejná	Výroba	Jižní Amerika	southamerica.api.advisor.powerapps.com
Veřejná	Výroba	Spojené království	unitedkingdom.api.advisor.powerapps.com
Veřejná	Výroba	Francie	france.api.advisor.powerapps.com
Veřejná	Výroba	Německo	germany.api.advisor.powerapps.com
Public	Výroba	Spojené arabské emiráty	unitedarabemirates.api.advisor.powerapps.com
Veřejná	Výroba	Švýcarsko	switzerland.api.advisor.powerapps.com
Veřejná	Výroba	Jihoafrická republika	southafrica.api.advisor.powerapps.com
Veřejná	Výroba	Korea	korea.api.advisor.powerapps.com
Veřejná	Výroba	Norsko	norway.api.advisor.powerapps.com
Veřejná	Výroba	Singapur	singapore.api.advisor.powerapps.com
Veřejná	Výroba	Švédsko	sweden.api.advisor.powerapps.com
Veřejná	Výroba	Polsko	poland.api.advisor.powerapps.com
Veřejná	Výroba	Itálie	italy.api.advisor.powerapps.com
Veřejná	Výroba	Vláda USA	gov.api.advisor.powerapps.us
Veřejná	Výroba	Vláda USA L4	high.api.advisor.powerapps.us
Veřejná	Výroba	Vláda Spojených států L5 (Ministerstvo obrany)	mil.api.advisor.appsplatform.us
Veřejná	Výroba	Čína provozována 21Vianet	china.api.advisor.powerapps.cn

Poznámka:

Můžete se rozhodnout použít geografii ve verzi Preview k dřívějšímu začlenění nejnovějších funkcí a změn. Pamatujte si však, že verze Preview používá pouze oblasti Azure v USA.

Vytváření verzí

Přestože to není vyžadováno, doporučujeme zahrnout parametr řetězce dotazu na verzi rozhraní API do požadované verze rozhraní API. Aktuální verze rozhraní API je 2.0 pro sady pravidel a pravidel a 1.0 pro všechny ostatní požadavky. Například následující sada pravidel je požadavek HTTP sady pravidel, který určuje použití verze rozhraní API 2.0:

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

Pokud není k dispozici, použije se ve výchozím nastavení nejnovější verze rozhraní API. Doporučuje se použít explicitní číslo verze, protože verze bude zvýšena, pokud dojde ke změně způsobující chybu. Pokud je v žádosti uvedeno číslo verze, bude zachována podpora zpětné kompatibility v pozdějších (číselně vyšších) verzích.

Sady pravidel a pravidla

Power Apps Checker vyžaduje při spuštění seznam pravidel. Tato pravidla mohou být poskytována ve formě individuálních pravidel nebo seskupení pravidel, označovaných jako sada pravidel. Sada pravidel je pohodlný způsob, jak určit skupinu pravidel, aniž byste museli jednotlivě určovat každé pravidlo. Například funkce pro kontrolu řešení používá sadu pravidel s názvem Kontrola řešení. Jakmile jsou nová pravidla přidána nebo odebrána, služba tyto změny automaticky zahrne, aniž by vyžadovala jakoukoli změnu ze strany využívající aplikace. Pokud požadujete, aby se seznam pravidel nezměnil automaticky, jak je popsáno výše, pak lze pravidla zadat jednotlivě. Sady pravidel mohou mít jedno nebo více pravidel bez omezení. Pravidlo může být v žádné nebo ve více sadách pravidel. Seznam všech sad pravidel získáte voláním rozhraní API takto: [Geographical URL]/api/ruleset. Tento koncový bod nyní vyžaduje ověření.

Sada pravidel kontroly řešení

Sada pravidel pro kontrolu řešení obsahuje sadu vlivných pravidel, která mají omezené šance na falešně pozitivní výsledek. Pokud provádíte analýzu existujícího řešení, doporučujeme začít s touto sadou pravidel. Tato sada pravidel je používána funkcí pro kontrolu řešení.

Sada pravidel certifikace AppSource

Při publikování aplikací v AppSource musíte svou aplikaci certifikovat. Aplikace publikované v AppSource musí splňovat vysoký standard kvality. Sada pravidel certifikace AppSource obsahuje pravidla, která jsou součástí sady pravidel pro kontrolu řešení, plus další pravidla, která zajistí, že v obchodě budou publikovány pouze vysoce kvalitní aplikace. Některá z pravidel certifikace AppSource jsou náchylnější k falešně pozitivním výsledkům a mohou vyžadovat další pozornost k vyřešení.

Vyhledání ID klienta

ID vašeho klienta je potřeba pro interakci s rozhraními API, která vyžadují token. V tomto článku najdete podrobnosti, jak získat ID klienta. K získání ID klienta můžete také použít příkazy PowerShell. Následující příklad využívá rutiny v modulu AzureAD.

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

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

ID klienta je hodnota vlastnosti ObjectId, která je vrácena z Get-AzureADTenantDetail. Můžete ji také vidět po přihlášení pomocí rutiny Connect-AzureAD ve výstupu rutiny. V tomto případě bude její název TenantId.

Ověřování a autorizace

Dotazy na pravidla a sady pravidel nevyžadují token OAuth, ale všechna ostatní rozhraní API vyžadují token. Rozhraní API podporují vyhledávání autorizací voláním kteréhokoli rozhraní API, které vyžaduje token. Odpověď je neautorizovaný stavový kód HTTP 401 se záhlavím WWW-Authenticate, autorizačním URI a ID zdroje. Měli byste také uvést ID svého klienta do záhlaví x-ms-tenant-id. V části Ověřování a autorizace Power Apps Checker najdete další informace. Níže je uveden příklad záhlaví odpovědi vrácené z požadavku rozhraní API:

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

Jakmile budete mít tyto informace, můžete se rozhodnout použít knihovnu pro ověřování Microsoft (MSAL) nebo nějaký jiný mechanismus pro získání tokenu. Níže je uveden příklad, jak toho lze dosáhnout pomocí C# a knihovny 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ý pracovní kód naleznete ve webovém rozhraní API ukázce rychlého zprovoznění.

Po získání tokenu se doporučuje poskytnout stejný token pro další volání v životním cyklu žádosti. Další žádosti však budou pravděpodobně vyžadovat získání nového tokenu z bezpečnostních důvodů.

Zabezpečení přenosu

Pro nejlepší šifrování ve své třídě podporuje služba kontroly pouze komunikaci pomocí Transport Layer Security (TLS) 1.2 a vyšší. Pokyny k doporučeným postupům .NET ohledně TLS naleznete v části Osvědčené postupy při použití Transport Layer Security (TLS) s .NET Framework.

Formát sestavy

Výsledkem analýzy řešení je soubor .zip obsahující jednu nebo více sestav ve standardizovaném formátu JSON. Formát sestavy je založen na výsledcích statické analýzy označovaných jako formát výměny výsledků statické analýzy (SARIF). K dispozici jsou nástroje pro prohlížení a interakci s dokumenty SARIF. Podrobnosti viz webová stránka. Tato služba využívá druhou verzi standardu OASIS.

Viz také