Använda webb_API:n för Power Apps-granskaren

Artikel
05/01/2024

Webb-API-kontrollen för Power Apps tillhandahåller en mekanism för att köra statiska analyskontroller mot anpassningar och tillägg till Microsoft Dataverse-plattformen. Mekanismen låter utvecklare och utvecklare utföra omfattande statiska analyskontroller på sina lösningar mot en uppsättning regler för bästa praxis i syfte att snabbt kunna identifiera problemmönster. Tjänsten tillhandahåller logiken för funktionen för lösningskontroll i Power Apps-utvecklarportalen och ingår som en del av automatiseringen för program som skickas till AppSource. Genom att samverka med tjänsten direkt på det här sättet kan du analysera lösningar som ingår som en del av lokala (alla versioner som stöds) och online-miljöer.

Information om hur du använder granskartjänsten från PowerShell-koden finns i Arbeta med lösningar med hjälp av PowerShell.

Kommentar

Genom att använda Power Apps-kontrollen garanterar inte säkert att en lösningsimport lyckas. De statiska analyskontrollerna som utfördes mot lösningen känner inte till den konfigurerade statusen för målmiljön och importen kan vara beroende av andra lösningar eller konfigurationer i miljön.

Alternativa sätt

Innan du läser igenom detaljerna om hur du interagerar på lägsta nivå med webb-API:erna bör du överväga att använda vår PowerShell-modul, Microsoft.PowerApps. Checker.PowerShell i stället. Denna är ett verktyg som stöds helt och finns tillgängligt i PowerShell-galleriet. Den aktuella begränsningen är att den kräver Windows PowerShell. Om detta krav inte uppfylls är det oftast bäst att interagera med API:erna direkt.

Kom igång

Det är viktigt att komma ihåg att en lösningsanalys kan resultera i en tidskrävande process. Det kan vanligtvis ta allt från 60 sekunder till fem minuter beroende på en mängd olika faktorer, t. ex anpassningarnas antal, storlek och komplexitet, samt kod. Analysflödet är i flera steg och asynkront, och inleds med en initiering av ett analysjobb där status-API:t används för att fråga efter slutförande av jobb. Ett exempelflöde för en analys ser ut på följande sätt:

Hämta en OAuth token
Anropa uppladdning (för respektive fil parallellt)
Anropa analys (startar analysjobbet)
Anropa status tills avslutad (loopar med paus mellan anrop tills slutet signaleras eller tröskelvärdena uppfylls)
Hämta resultatet/resultaten från angiven SAS-URI

Några varianter är:

Inkludera ett uppslag av regeluppsättning/regler som ett försteg. Att skicka med ett konfigurerat eller hårdkodat ID för regeluppsättning skulle emellertid gå något fortare. Vi rekommenderar att du använder en regeluppsättning som passar dina behov.
Du kan välja att inte använda överföringsfunktionen (se överföringen för begränsningar).

Du måste fastställa följande krav:

Vilken geografi?
Vilken version?
Vilka regler och regler?
Vad är ditt klientorganisations-ID?

I följande artiklar finns dokumentation om enskilda API:er:

Hämta listan med regeluppsättningar
Hämta listan med regler
Ladda upp en fil
Anropa analys
Kontrollera analysstatus

Bestäm geografi

När du interagerar med granskartjänsten Power Apps lagras filer temporärt i Azure tillsammans med de rapporter som skapas. Med hjälp av ett geografi-specifikt API kan du styra var informationen lagras. Förfrågningar till en geografi slutpunkt dirigeras till en regional instans utifrån bästa prestanda (svar till den som begär det). När en förfrågan har registrerats för en regional tjänstinstans kvarstår all bearbetning och alla beständiga data inom just den regionen. Vissa API-svar kommer att returnera regionala instans-URL:er för efterföljande förfrågningar när ett analysjobb har dirigerats till en specifik region. Varje geografiskt område kan ha olika versioner av tjänsten som har distribuerats vid en viss tidpunkt. Användning av olika tjänstversioner beror på en säker distributionsprocess i flera steg, vilket garanterar fullständig versionskompatibilitet. Samma geografi ska användas för varje API-anrop i livscykeln för analyser och kan minska den allmänna körningstiden eftersom data kanske inte behöver färdas lika mycket över ledningen. Följande geografier är tillgängliga:

Azure-datacenter	Namn	Geografi	Bas-URI
Offentlig förvaltning	Förhandsgranskning	USA	unitedstatesfirstrelease.api.advisor.powerapps.com
Offentlig förvaltning	Produktion	USA	unitedstates.api.advisor.powerapps.com
Offentlig förvaltning	Produktion	Europa	europe.api.advisor.powerapps.com
Offentlig förvaltning	Produktion	Asien	asia.api.advisor.powerapps.com
Offentlig förvaltning	Produktion	Australien	australia.api.advisor.powerapps.com
Offentlig förvaltning	Produktion	Japan	japan.api.advisor.powerapps.com
Offentlig förvaltning	Produktion	Indien	india.api.advisor.powerapps.com
Offentlig förvaltning	Produktion	Kanada	canada.api.advisor.powerapps.com
Offentlig förvaltning	Produktion	Sydamerika	southamerica.api.advisor.powerapps.com
Offentlig förvaltning	Produktion	Storbritannien	unitedkingdom.api.advisor.powerapps.com
Offentlig förvaltning	Produktion	Frankrike	france.api.advisor.powerapps.com
Offentliga	Produktion	Tyskland	germany.api.advisor.powerapps.com
Offentliga	Produktion	Förenade Arabemiraten	unitedarabemirates.api.advisor.powerapps.com
Publikt	Produktion	Schweiz	switzerland.api.advisor.powerapps.com
Publikt	Produktion	Sydafrika	southafrica.api.advisor.powerapps.com
Publikt	Produktion	Sydkorea	korea.api.advisor.powerapps.com
Publikt	Produktion	Norge	norway.api.advisor.powerapps.com
Publikt	Produktion	Singapore	singapore.api.advisor.powerapps.com
Publikt	Produktion	Sverige	sweden.api.advisor.powerapps.com
Publikt	Produktion	US Government	gov.api.advisor.powerapps.us
Offentlig förvaltning	Produktion	Amerikanska myndigheter L4	high.api.advisor.powerapps.us
Offentlig förvaltning	Produktion	Amerikanska myndigheter L5 (DOD)	mil.api.advisor.appsplatform.us
Offentlig förvaltning	Produktion	Kina drivet av 21Vianet	china.api.advisor.powerapps.cn

Kommentar

Du kan välja att använda en geografi för förhandsgranskning om du vill infoga de senaste funktionerna och ändringarna tidigare. Observera dock att förhandsversionen endast använder Azure-regioner för USA.

Versionshantering

Även om så inte krävs rekommenderas att inkludera parametern för frågesträngen om API-version tillsammans med önskad API-version. Den aktuella API-versionen är 2.0 för regeluppsättningar och regler och 1.0 för alla andra förfrågningar. Till exempel är följande regeluppsättning en HTTP-begäran som anger att 2.0 API-versionen ska användas:

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

Om denna inte anges används den senaste API-versionen som standard. Det rekommenderas att du använder ett explicit versionsnummer eftersom versionsnumret ökar om icke-bakåtkompatibla ändringar introduceras. Om versionsnumret anges i en förfrågan kommer stöd för bakåtkompatibilitet i senare (numeriskt större) versioner att upprätthållas.

Regeluppsättningar och regler

Power Apps-granskaren kräver en lista med regler vid körning. Dessa regler kan tillhandahållas i form av enskilda regler eller en grupp regler som kallas för regeluppsättning. En regeluppsättning är ett bekvämt sätt att ange en grupp regler i stället för att behöva ange varje regel separat. Funktionen för lösningskontroll använder till exempel en regeluppsättning kallad Solution Checker. I takt med att nya regler läggs till eller tas bort tas ändringarna automatiskt med i tjänsten, detta utan att programmet behöver ändras. Om regellistan inte får ändras automatiskt enligt beskrivningen ovan, kan du ange reglerna individuellt. Regeluppsättningar kan ha en eller flera regler utan gräns. En regel kan finnas i ingen eller i flera regeluppsättningar. Du kan visa en lista över alla regeluppsättningar genom att anropa API:t enligt följande: [Geographical URL]/api/ruleset. Denna slutpunkt kräver nu autentisering.

Regeluppsättning för lösningskontroll

Regeluppsättningen för lösningskontroll innehåller en uppsättning effektfulla regler som har begränsade risker att innehålla falska positiva identifieringar. Om du kör en analys mot en befintlig lösning bör du börja med denna regeluppsättning. Detta är den regeluppsättning som används av funktionen för lösningskontroll.

AppSource-regeluppsättning för certifiering

När du publicerar program på AppSource måste du se till att programmet är certifierat. Ansökningar som publiceras på AppSource måste uppfylla en hög kvalitetsstandard. AppSource-regeluppsättningen för certifiering innehåller de regler som ingår i regeluppsättningen för lösningskontroll, plus ytterligare regler för att säkerställa att endast högkvalitativa program publiceras i butiken. Vissa AppSource-certifieringsregler är mer känsliga för falsk positiv identifiering och kan kräva ytterligare uppmärksamhet för att lösas.

Hitta ditt klientorganisations-ID

ID:t för din klientorganisation behövs för att samverka med de API:er som kräver en token. Se denna artikel för information om hur du hämtar ID för klientorganisationen. Du kan också använda PowerShell-kommandon för att hämta klient-ID. I följande exempel utnyttjas de cmdlet som finns i AzureAD-modulen.

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

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

ID för klientorganisation är värdet för den ObjectId-egenskap som returneras från Get-AzureADTenantDetail. Du kan också se det efter det att du har loggat in med cmdlet för Connect-AzureAD i utdatan för cmdlet. Det kommer då att kallas för TenantId.

Autentisering och auktorisering

Frågor efter regler och regeluppsättningar kräver ingen OAuth token, men alla andra API:er kräver token. API:er stöder identifiering av autentisering genom att anropa alla API:er som kräver en token. Svaret blir en otillåten HTTP-statuskod på 401 med ett "WWW-autentisera"-huvud, URI-autentisering och resurs-ID. Du bör också ange ID:t för klientorganisationen i x-ms-tenant-id-huvudet. Se Power Apps Autentisering och auktorisering för granskare för mer information. Nedan visas ett exempel på ett svarshuvud som returneras från en API-begäran:

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

När du har den här informationen kan du välja att använda Microsoft autentiseringsbiblioteket (MSAL) eller någon annan mekanism för att hämta token. Nedan visas ett exempel på hur detta kan utföras med C# och MSAL .NET-biblioteket:

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

Fullständig arbetskod, se Webb-API exemplet med Snabbstart.

När du har skaffat en token bör du ange samma token för efterföljande anrop i livscykeln för förfrågan. Ytterligare förfrågan kommer emellertid troligen att innebära att en ny token måste förvärvas av säkerhetsskäl.

Transportsäkerhet

I syfte att ge bästa möjliga kryptering stöder granskningstjänsten endast kommunikation med TLS (Transport Layer Security) 1.2 och senare. Vägledning om hur du använder bästa metoder för .NET finns i Metodtips för TLS (Transport Layer Security) med .NET Framework.

Rapportformat

Resultatet av lösningsanalysen är en zip-fil som innehåller en eller flera rapporter i ett standardiserat JSON-format. Rapportformatet bygger på statiska analysresultat som kallas för SARIF (Static Analysis Result Interchange Format). Verktyg finns tillgängliga som låter dig visa och interagera med SARIF-dokument. Mer information finns på den här webbplatsen. Tjänsten utnyttjar version två av OASIS-standarden.

Se även