Použití webového rozhraní API pro kontrolu Power Apps

Webové rozhraní API pro kontrolu Power Apps poskytuje mechanismus pro spouštění kontrol statických analýz proti přizpůsobením a rozšířením 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 poskytuje logiku pro funkci kontroly řešení na portálu pro tvůrce Power Apps a je součástí automatizace pro aplikace odeslané na Marketplace. 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.

Note

Použití kontroly Power Apps 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. Je to plně podporovaný nástroj, který je k dispozici v Galerie prostředí PowerShell. Aktuální omezení spočívá v tom, že 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 kontrola se soubory dočasně ukládají společně s vygenerovanými reporty do Azure. 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:

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

Note

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. Mějte však na paměti, že náhledová verze používá pouze americké Azure regiony.

Versioning

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

Kontrola Power Apps při spuštění vyžaduje 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 Marketplace

Při publikování aplikací na Marketplace musíte aplikaci certifikovat. Aplikace publikované na Marketplace se vyžadují, aby splňovaly vysoký standard kvality. Sada pravidel certifikace Marketplace obsahuje pravidla, která jsou součástí sady pravidel kontroly řešení a další pravidla, která zajišťují, aby se v obchodě publikovaly jenom vysoce kvalitní aplikace. Některá pravidla certifikace Marketplace jsou náchylnější k falešně pozitivním výsledkům a mohou vyžadovat větší 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.

Autentizace 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. Další informace najdete v tématu ověřování a autorizace Power Apps Checker. 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 k získání tokenu použít Identity a ověřování Microsoftu (MSAL) nebo jiný mechanismus. Následuje příklad toho, jak to lze provést pomocí jazyka 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í dopravy

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 osvědčeným postupům pro protokol TLS v .NET najdete v dokumentu Osvědčené postupy TLS (Transport Layer Security) 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é