A Power Apps ellenőrző webes API használata

Cikk
05/01/2024

A Power Apps ellenőrző webes API egy olyan mechanizmust biztosít, amely a Microsoft Dataverse platformon a testreszabások és bővítmények közötti statikus elemzési ellenőrzéseket futtatja. Elérhető készítők és fejlesztők számára, hogy funkciógazdag statikus elemzési ellenőrzéseket végezhessenek a megoldásaikon a legjobb gyakorlatok készletére alapozott szabályok alapján, és gyorsan azonosíthassák ezeket a problémamintákat. A szolgáltatás a Power Apps készítői portáljának megoldás-ellenőrzési funkciójához biztosít logikát, és az AppSource számára beküldött alkalmazásokhoz használható automatizálás része. A szolgáltatással való közvetlen interakció lehetővé teszi a helyszíni (minden támogatott verzió) és az online környezetek részét képező megoldások elemzését.

További információ az ellenőrző szolgáltatás PowerShell-kódból való használatáról: Megoldások használata a PowerShell használatával.

Feljegyzés

A Power Apps ellenőrző használata nem garantálja, hogy a megoldások importálása sikeres lesz. A megoldásban végrehajtott statikus elemzési ellenőrzések nem ismerik a cél környezet konfigurált állapotát, és az importálás sikere a környezet egyéb megoldásaitól és konfigurációjáról is függhet.

Alternatív megoldások

Mielőtt elolvasná a webes API-kkal való legalacsonyabb szintű interakció részleteit, fontolja meg a Microsoft.PowerApps. PowerShell-modul használatát. Ehelyett Checker.PowerShell. Ez egy teljes mértékben támogatott eszköz, amely a PowerShell-galéria. Korlátozás, hogy Windows PowerShell szükséges a használatához. Ha nem tudja teljesíteni ezt a követelményt, akkor az API-kkal való közvetlen interakció a legjobb megközelítés.

Első lépések

Fontos megjegyezni, hogy a megoldáselemzés hosszú ideig futó folyamatot eredményezhet. Általában hatvan (60) másodperctől öt (5) percig tarthat, különböző tényezőktől függően, például a testreszabások és a kód számától, méretétől és összetettségétől. Az elemzési folyamat több lépésből áll, és a kezdés aszinkron. Az első lépés egy elemzési feladatnak a feladatbefejezés lekérdezéséhez használt állapot API-val történő kezdeményezése. Az alábbi részen egy elemzésre látható példa:

OAuth-jogkivonat beszerzése
Feltöltés meghívása (minden fájlhoz párhuzamosan)
Elemzés meghívása (kezdeményezi az elemzési feladatot)
Állapot meghívása a befejezésig (a hívások között szünettel, amíg a rendszer nem jelzi a végét vagy el nem éri a küszöböt)
Az eredmény(ek) letöltése a rendelkezésre álló SAS URI-ból

Néhány variáció:

Adja meg a szabálykészlet vagy a szabályok keresését előzetes lépésként. Kissé gyorsabb, ha konfigurált vagy kódolt szabálykészlet-azonosítót ad át. Érdemes az igényeinek megfelelő szabálykészletet használni.
Választhatja, hogy nem használja a feltöltési mechanizmust (a korlátozások a feltöltés részletei között láthatók).

Meg kell határoznia a következő követelményeket:

Milyen földrajzi régió?
Melyik verzió?
Milyen szabálykészletek és szabályok?
Mi a bérlő azonosítója?

Az egyes API-kkal kapcsolatos dokumentációért tekintse meg a következő cikkeket:

A szabálykészletek listájának beolvasása
A szabályok listájának beolvasása
Fájl feltöltése
Elemzés meghívása
Az elemzési állapot ellenőrzése

Földrajzi régió meghatározása

Az ellenőrző szolgáltatással való interakció során a rendszer ideiglenesen tárolja a Power Apps fájlokat az Azure-ban a létrehozott jelentésekkel együtt. Földrajzihely-specifikus API használatával szabályozhatja, hogy a rendszer hol tárolja az adatokat. A földrajzi végpontra vonatkozó kérések a régiós példányhoz a legjobb teljesítmény (késés a kérelmező felé) alapján lesznek irányítva. Ha a kérelem egy területi szolgáltatási példányba kerül, a feldolgozás és a megmaradt adatok az adott régión belül maradnak. Bizonyos API-válaszok regionális példányok URL-címeit adják vissza a későbbi kérésekhez, miután egy elemzési feladatot egy adott régióba irányítottak. Előfordulhat, hogy minden földrajzi helyen a szolgáltatás különböző verziója van üzembe helyezve egy adott időpontban. A különböző szolgáltatásverziók használata a többlépcsős biztonságos telepítési folyamatnak köszönhető, amely biztosítja a teljes verziókompatibilitást. Így ugyanazt a földrajzi helyet kell használni minden egyes API-híváshoz az elemzés életciklusa során, és csökkentheti a teljes végrehajtási időt, mivel az adatoknak nem kell olyan messzire eljutniuk a hálózaton. A következő földrajzi helyek állnak rendelkezésre:

Azure-adatközpont	Név szerint	Földrajzi hely	Alap-URI
Állami	Előzetes	Egyesült Államok	unitedstatesfirstrelease.api.advisor.powerapps.com
Állami	Gyártás	Egyesült Államok	unitedstates.api.advisor.powerapps.com
Állami	Gyártás	Európa	europe.api.advisor.powerapps.com
Állami	Gyártás	Ázsia	asia.api.advisor.powerapps.com
Állami	Gyártás	Ausztrália	australia.api.advisor.powerapps.com
Állami	Gyártás	Japán	japan.api.advisor.powerapps.com
Állami	Gyártás	India	india.api.advisor.powerapps.com
Állami	Gyártás	Kanada	canada.api.advisor.powerapps.com
Állami	Gyártás	Dél-Amerika	southamerica.api.advisor.powerapps.com
Állami	Gyártás	Egyesült Királyság	unitedkingdom.api.advisor.powerapps.com
Állami	Gyártás	Franciaország	france.api.advisor.powerapps.com
Állami	Üzemi	Németország	germany.api.advisor.powerapps.com
Állami	Üzemi	Egyesült Arab Emírségek	unitedarabemirates.api.advisor.powerapps.com
Publikus	Termelési	Svájc	switzerland.api.advisor.powerapps.com
Publikus	Termelési	Dél-afrikai Köztársaság	southafrica.api.advisor.powerapps.com
Publikus	Termelési	Korea	korea.api.advisor.powerapps.com
Publikus	Termelési	Norvégia	norway.api.advisor.powerapps.com
Publikus	Termelési	Szingapúr	singapore.api.advisor.powerapps.com
Publikus	Termelési	Svédország	sweden.api.advisor.powerapps.com
Publikus	Termelési	US Government	gov.api.advisor.powerapps.us
Állami	Gyártás	US Government L4	high.api.advisor.powerapps.us
Állami	Gyártás	US Government L5 (DOD)	mil.api.advisor.appsplatform.us
Állami	Gyártás	Kína, 21Vianet által üzemeltetve	china.api.advisor.powerapps.cn

Feljegyzés

A földrajzi hely előnézetével korábban használhatja a legújabb funkciókat és módosításokat. Ne feledje azonban, hogy az előnézet kizárólag az Egyesült Államok Azure-régióit használja.

Verziókezelés

Bár nem kötelező, javasoljuk, hogy az api-version lekérdezési sztring paramétert a kívánt API-verzióval foglalja bele. Az API jelenlegi verziója 2.0 a szabálykészletek és szabályok, valamint 1.0 az összes többi kérés esetében. A következő szabálykészlet például egy HTTP-kérés, amely a 2.0-s API-verzió használatát adja meg:

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

Ha nincs megadva, a rendszer alapértelmezés szerint a legújabb API-verziót használja. Explicit verziószám használata ajánlott, mivel a verzió növekszik, ha feltörési módosításokat vezetnek be. Ha egy kérésben meg van adva a verziószám, a rendszer támogatja az előző verziókkal való kompatibilitást a későbbi (nagyobb számmal ellátott) verziókban.

Szabálykészletek és szabályok

A Power Apps ellenőrzőjének futtatásához szükség van a szabályok listájára. Ezek a szabályok egyedi szabályok formájában, illetve a szabályok csoportjaként, vagyis szabálykészletként adhatók meg. A szabálykészletekkel kényelmesen határozhatók meg szabályok csoportjai, és nem kell külön megadnia az egyes szabályokat. A megoldás-ellenőrzés funkció például a Megoldás-ellenőrző szabálykészletet használja. Új szabályok hozzáadásakor vagy eltávolításakor a szolgáltatás automatikusan belefoglalja ezeket a módosításokat anélkül, hogy a felhasználó alkalmazásnak módosítania kellene. Ha azt szeretné, hogy a szabályok listája ne módosuljon automatikusan, a fent leírtak szerint, akkor egyénileg is megadhatja a szabályokat. A szabálykészletekben akármennyi szabály lehet. Egy szabálynak nem kell szabálykészletben lennie, és több szabálykészletben is lehet. Az összes szabálykészlet listája az API következő hívásával tekinthető meg: [Geographical URL]/api/ruleset. Ez a végpont most hitelesítést igényel.

A Megoldás-ellenőrző szabálykészlet

A Megoldás-ellenőrző szabálykészlet számos olyan hatásos szabályt tartalmaz, amely csökkenti a vakriasztások esélyét. Ha egy meglévő megoldáson futtat elemzést, javasoljuk, hogy kezdje ezzel a szabálykészlettel. Ezt a szabálykészletet a megoldás-ellenőrző funkció használja.

Az AppSource minősítési szabálykészlete

Az alkalmazások AppSource rendszerben való közzétételéhez minősítést kell szerezni az alkalmazás számára. Az AppSource rendszerben közzétett alkalmazásoknak kiváló minőségűnek kell lenniük. A AppSource tanúsítási szabálykészlet tartalmazza a megoldás-ellenőrző szabálykészletének részét képező szabályokat, valamint egyéb szabályokat, amelyek biztosítják, hogy csak kiváló minőségű alkalmazások legyenek közzétéve az áruházban. AppSource Egyes tanúsítási szabályok hajlamosabbak a téves riasztásokra, és megoldásuk nagyobb figyelmet igényelhet.

A bérlő azonosítójának megkeresése

A bérlő azonosítójára szükség van a lexikális elemeket igénylő API-k használatához. A bérlő azonosítójának beszerzéséről ebben a cikkben olvashat. A bérlő azonosítójának beolvasására PowerShell-parancsok is használhatók. Az alábbi példa az AzureAD modul parancsmagjaitalkalmazza.

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

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

A bérlő azonosítója a Get-AzureADTenantDetail visszaküldött ObjectId tulajdonságának értéke. Akkor is láthatja, ha a parancsmag kimenetében lévő Connect-AzureAD parancsmag használatával jelentkezik be. Ebben az esetben meg lesz nevezve TenantId.

Hitelesítés és engedélyezés

A szabályok és szabálykészletek lekérdezéséhez nincs szükség OAuth-jogkivonatra, de az összes többi API-hoz szükség van a jogkivonatra. Az API-k támogatják az engedélyezés bármilyen, jogkivonatot igénylő API meghívásával történő észlelését. A válasz egy 401-es jogosulatlan HTTP-állapotkód WWW-Authenticate fejléccel, engedélyezési URI-val és erőforrás-azonosítóval. Az x-ms-tenant-id fejlécben a bérlő azonosítóját is meg kell adni. További Power Apps információ: Ellenőrző hitelesítés és engedélyezés . Az alábbi példa egy API-kérés által visszaadott válaszfejlécet mutat be:

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

Ha már rendelkezik ezekkel az információkkal, dönthet úgy, hogy a Microsoft Authentication Library (MSAL) vagy más mechanizmus használatával szerzi be a jogkivonatot. Az alábbi példa bemutatja, hogyan lehet ezt megtenni a C# és az MSAL .NET kódtár használatával:

// 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();

A teljes működő kódért tekintse meg a webes API rövid útmutatójának mintáját.

A jogkivonat beszerzése után javasoljuk, hogy ugyanazt a jogkivonatot adja meg a kérés életciklusának későbbi hívásaihoz. Több kérés azonban biztonsági okokból új jogkivonat beszerzését indokolhatja.

Biztonságos szállítás

A kategóriájában legjobb titkosítás érdekében az ellenőrző szolgáltatás csak a Transport Layer Security (TLS) 1.2-es vagy újabb verzióját használó kommunikációt támogatja. A TLS-hez használható bevált .NET-gyakorlatokra vonatkozó útmutató: A .NET-keretrendszer bevált TLS-megoldásai.

Jelentés formátuma

A megoldás elemzése egy olyan zip-fájlt ad eredményként, amely egy vagy több szabványosított JSON-formátumú jelentést tartalmaz. A jelentés formátuma a statikus elemzési eredményeken alapul. Ezt statikus elemzési eredmények adatcsere-formátumának nevezik (SARIF). A SARIF-dokumentumok megtekintéséhez és használatához különféle eszközök állnak rendelkezésre. A részletek ezen a webhelyen találhatók. A szolgáltatás az OASIS szabvány második verzióját használja.

Kapcsolódó információk