Použití webového rozhraní API kontroly Power Apps

Článek
05/01/2024

Kontrolní webové rozhraní API Power Apps 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. Tato služba poskytuje logiku pro funkci kontroly řešení v portálu pro tvůrce Power Apps a je součástí automatizace aplikací odeslaných 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:

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. 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 klienta?

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 s kontrolou Power Apps 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é	Ukázková	Spojené státy	unitedstatesfirstrelease.api.advisor.powerapps.com
Veřejné	Produkční	Spojené státy	unitedstates.api.advisor.powerapps.com
Veřejné	Produkční	Evropa	europe.api.advisor.powerapps.com
Veřejné	Produkční	Asie	asia.api.advisor.powerapps.com
Veřejné	Produkční	Austrálie	australia.api.advisor.powerapps.com
Veřejné	Produkční	Japonsko	japan.api.advisor.powerapps.com
Veřejné	Produkční	Indie	india.api.advisor.powerapps.com
Veřejné	Produkční	Kanada	canada.api.advisor.powerapps.com
Veřejné	Produkční	Jižní Amerika	southamerica.api.advisor.powerapps.com
Veřejné	Produkční	Spojené království	unitedkingdom.api.advisor.powerapps.com
Veřejné	Produkční	Francie	france.api.advisor.powerapps.com
Public	Provozní	Německo	germany.api.advisor.powerapps.com
Public	Provozní	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	Vláda USA	gov.api.advisor.powerapps.us
Veřejné	Produkční	US Government L4	high.api.advisor.powerapps.us
Veřejné	Produkční	US Government L5 (DOD)	mil.api.advisor.appsplatform.us
Veřejné	Produkční	Čí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

Kontrola Power Apps 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 kontroly Power Apps 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í Mocrosoft (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žadivat 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 setavy 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é