Bruge web-API for Power Apps-kontrollen

Artikel
01/25/2024

Web-API'en til Power Apps-checkeren leverer en mekanisme til kørsel af statiske analysetjek set i forhold til tilpasninger og udvidelser til Microsoft Dataverse-platformen. Den er tilgængelig for udviklere, således at de kan udføre omfattende statiske analysetjek af deres løsninger i forhold til et regelsæt for bedste praksis og derved hurtigt identificere problematiske mønstre. Tjenesten angiver logikken for funktionen Løsningskontrol i Power Apps-udviklernes portal og er inkluderet som en del af automatiseringen for de programmer, der er sendt til AppSource. Interaktion med tjenesten direkte på denne måde giver mulighed for at analysere løsninger, der er inkluderet som en del af lokale (alle understøttede versioner) og online miljøer.

Du kan finde oplysninger om, hvordan du bruger kontroltjenesten fra PowerShell-koden, under Arbejde med løsninger ved hjælp af PowerShell.

Bemærk

Brug af Power Apps-kontrol garanterer ikke, at en løsningsimport bliver vellykket. Den statiske analysekontrol, der udføres mod løsningen, kender ikke den konfigurerede tilstand af destinationsmiljøet, og importsucces kan være afhængig af andre løsninger eller konfigurationer i miljøet.

Alternative metoder

Inden du læser detaljerne om, hvordan du kan arbejde på det laveste niveau ved hjælp af web-API'er, skal du overveje at udnytte vores PowerShell-modul Microsoft.PowerApps.Checker.PowerShell i stedet. Det er et fuldt understøttet værktøj, der er tilgængeligt i PowerShell-galleriet. Den nuværende begrænsning er, at den kræver Windows PowerShell. Hvis det ikke er muligt at opfylde dette krav, vil den bedste metode sandsynligvis være at bruge API'erne direkte.

Introduktion

Det er vigtigt at bemærke, at en løsnings analyse kan medføre en langvarig proces. Det kan typisk tage fra 60 sekunder og op til fem minutter afhængigt af en række faktorer, f.eks. antal, størrelse og kompleksitet af tilpasninger og kode. Analyseflowet består af flere trin og er asynkront, hvor der først startes et analysejob med status-API'en, som bruges til at forespørge om jobbets fuldførelse. Et eksempel på et analyseflow er følgende:

Anskaffe et OAuth-token
Kalde overførsel (for hver fil parallelt)
Kalde analyse (starter analysejobbet)
Kalde status indtil fuldført (løkke med pause mellem kald, indtil afslutningen er signaleret, eller tærsklerne er overholdt)
Hente resultat(er) fra den angivne SAS-URI

Her er nogle få variationer:

Inkludere et opslag i regelsættet eller reglerne som et forudgående trin. Det ville dog være en anelse hurtigere at overføre et konfigureret eller hard-coded regelsæt-id. Det anbefales, at du bruger en regelsæt, der opfylder dine behov.
Du kan vælge ikke at bruge overførselsmekanismen (se overførsel til begrænsninger).

Du skal bestemme følgende krav:

Hvilken geografi?
Hvilken version?
Hvilke regelsæt og regler?
Hvad er dit lejer-id?

I følgende artikler finder du dokumentation om de enkelte API'er:

Hente listen over regelsæt
Hente listen over regler
Overføre en fil
Aktivere analyser
Kontrollere analysestatus

Fastlægge en geografi

Under interaktion med Power Apps-kontroltjenesten gemmes filer midlertidigt i Azure sammen med de rapporter, der er oprettet. Hvis du bruger et geografi-specifikt API, kan du styre, hvor dataene lagres. Anmodninger til et geografislutpunkt sendes til en regional forekomst baseret på den bedste ydeevne (ventetid for anmoderen). Når en anmodning ankommer til en regional tjenesteforekomst, forbliver alle behandlingsdata og permanente data inden for det pågældende område. Visse API-svar returnerer den regionale forekomsts URL-adresse for efterfølgende anmodninger, når et analysejob er blevet distribueret til et bestemt område. Hvert geografiske område kan have en anden version af tjenesten installeret på et hvilket som helst tidspunkt. Brugen af forskellige tjenesteversioner skyldes sikker installationsproces med flere faser, der sikrer fuld versionskompatibilitet. Derfor bør den samme geografi bruges til hvert API-opkald i analysens livscyklus, og det kan reducere den samlede udførelsestid, da dataene måske ikke skal rejse så langt over forbindelsen. Der er følgende tilgængelige geografier:

Azure-datacenter	Navn	Geografi	Basis-URI-adresse
Offentligt	Prøveversion	USA	unitedstatesfirstrelease.api.advisor.powerapps.com
Offentligt	Produktion	USA	unitedstates.api.advisor.powerapps.com
Offentligt	Produktion	Europa	europe.api.advisor.powerapps.com
Offentligt	Produktion	Asien	asia.api.advisor.powerapps.com
Offentligt	Produktion	Australien	australia.api.advisor.powerapps.com
Offentligt	Produktion	Japan	japan.api.advisor.powerapps.com
Offentligt	Produktion	Indien	india.api.advisor.powerapps.com
Offentligt	Produktion	Canada	canada.api.advisor.powerapps.com
Offentligt	Produktion	Sydamerika	southamerica.api.advisor.powerapps.com
Offentligt	Produktion	Storbritannien	unitedkingdom.api.advisor.powerapps.com
Offentligt	Produktion	Frankrig	france.api.advisor.powerapps.com
Offentligt	Produktion	Tyskland	germany.api.advisor.powerapps.com
Offentligt	Produktion	De Forenede Arabiske Emirater	unitedarabemirates.api.advisor.powerapps.com
Offentlig	Produktion	Schweiz	switzerland.api.advisor.powerapps.com
Offentlig	Produktion	Sydafrika	southafrica.api.advisor.powerapps.com
Offentlig	Produktion	Korea	korea.api.advisor.powerapps.com
Offentlig	Produktion	Norge	norway.api.advisor.powerapps.com
Offentlig	Produktion	Singapore	singapore.api.advisor.powerapps.com
Offentlig	Produktion	US Government	gov.api.advisor.powerapps.us
Offentligt	Produktion	US Government L4	high.api.advisor.powerapps.us
Offentligt	Produktion	US Government L5 (DOD)	mil.api.advisor.appsplatform.us
Offentligt	Produktion	Kina drevet af 21Vianet	china.api.advisor.powerapps.cn

Bemærk

Du kan vælge at bruge geografieksemplet for hurtigere at inkorporere de nyeste funktioner og ændringer. Bemærk dog, at eksemplet kun bruger amerikanske Azure-områder.

Versionsstyring

Selvom det ikke er påkrævet, anbefales det, at du medtager forespørgselsstrengparameteren for API-version sammen med den ønskede API-version. Den aktuelle API-version er 2.0 for regelsæt og regler og 1.0 for alle andre anmodninger. Følgende regelsæt er f.eks. en HTTP-anmodning, som angiver, at du skal bruge API-version 2.0:

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

Hvis det ikke er angivet, bruges den nyeste API-version som standard. Det anbefales, at du bruger et eksplicit versionsnummer, da versionsnummeret stiger, hvis der indføres vigtige ændringer. Hvis versionsnummeret er angivet i en anmodning, bevares understøttelsen af bagudkompatibilitet i nyere versioner (med højere numre).

Regelsæt og regler

Power Apps-kontrollen kræver en liste over regler under kørsel. Disse regler kan gives i form af individuelle regler eller en gruppering af regler, som kaldes et regelsæt. Et regelsæt er en praktisk metode til at angive en gruppe af regler i stedet for at skulle angive hver enkelt regel hver for sig. Funktionen Løsningskontrol bruger f.eks. et regelsæt kaldet Løsningskontrol. Efterhånden som nye regler tilføjes eller fjernes, vil tjenesten automatisk inkludere disse ændringer uden at kræve ændringer fra brugerprogrammet. Hvis du har brug for, at listen over regler ikke automatisk ændres som beskrevet ovenfor, kan reglerne angives individuelt. Regelsæt kan have en eller flere regler uden begrænsning. En regel kan være på ingen eller flere regelsæt. Du kan få vist en liste over alle regelsæt ved at kalde API'en på følgende måde: [Geographical URL]/api/ruleset. Dette slutpunkt kræver nu godkendelse.

Regelsæt for Løsningskontrol

Regelsættet for Løsningskontrol indeholder et sæt effektive regler, der begrænser sandsynligheden for falske positive værdier. Hvis du kører analyser i forhold til en eksisterende løsning, anbefales det, at du starter med dette regelsæt. Dette regelsæt bruges af funktionen Løsningskontrol.

Regelsæt for AppSource-certificering

Når du publicerer programmer på AppSource, skal du anskaffe dit program som certificeret. De publicerede programmer i AppSource skal opfylde en standardværdi for høj kvalitet. Regelsættet for AppSource-certificering indeholder regler, der er en del af regelsættet for Løsningskontrol, samt andre regler for at sikre, at kun programmer i høj kvalitet publiceres i appstoren. Nogle regler for AppSource-certificering er mere udsatte for falske positive værdier og kan kræve mere opmærksomhed for at løse problemet.

Finde dit lejer-id

Id'et for din lejer skal bruges til at kommunikere med de API'er, der kræver et token. I denne artikel finder du oplysninger om, hvordan du får lejer-id'et. Du kan også bruge PowerShell-kommandoer til at hente lejer-id'et. I følgende eksempel bruges cmdlets i AzureAD-modulet.

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

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

Lejer-id'et er værdien for egenskaben ObjectId, der returneres fra Get-AzureADTenantDetail. Du kan også se det, når du har logget på ved hjælp af Connect-AzureAD-cmdletten i cmdlet-outputtet. I dette tilfælde hedder det TenantId.

Godkendelse og autorisation

Forespørgsel efter regler og regelsæt kræver ikke et OAuth-token, men alle andre API'er kræver tokenet. API'erne understøtter autorisationsregistrering ved at kalde et af de API'er, der kræver et token. Svaret vil være en uautoriseret HTTP-statuskode på 401 med en WWW-Authenticate-overskrift, autorisation-URI'en og ressource-id'et. Du skal også angive dit lejer-id i overskriften x-ms-tenant-id. Du kan finde flere oplysninger under Godkendelse og autorisation for Power Apps-kontrol. Nedenfor vises et eksempel på svaroverskriften, som er returneret fra en API-anmodning:

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 disse oplysninger, kan du vælge at bruge Microsoft-godkendelsesbiblioteket (MSAL) eller en anden metode til at hente tokenet. Nedenfor vises et eksempel på, hvordan dette kan gøres ved hjælp af C# og 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();

Du kan se hele arbejdskoden i Eksempel på Web API QuickStart.

Når du har anskaffet tokenet, anbefales det, at du giver det samme token til efterfølgende kald i anmodningens livscyklus. Flere anmodninger vil dog sandsynligvis kræve, at der anskaffes et nyt token af sikkerhedsmæssige årsager.

Transportsikkerhed

For at opnå den bedste kryptering understøtter kontroltjenesten kun kommunikation ved hjælp af TLS (Transport Layer Security) 1.2 og derover. Du kan finde en vejledning i de bedste fremgangsmåder for .NET til TLS under Bedste praksisser for TLS(Transport Layer Security) i .NET Framework.

Rapportformat

Resultatet af løsningsanalysen er en zip-fil, der indeholder en eller flere rapporter i et standardiseret JSON-format. Rapportformatet er baseret på statiske analyseresultater, der er omhandlet som statiske SARIF (Analysis Results Interchange Format). Der findes værktøjer, du kan bruge til at få vist og interagere med SARIF-dokumenter. Se dette websted for at få flere oplysninger. Tjenesten anvender version 2 af OASIS-standarden.

Se også