Bruke nett-API-en for Power Apps-kontroll

Artikkel
02/07/2024

I Power Apps-kontrollens API-for web får du en mekanisme for å kjøre statiske analysekontroller mot tilpassinger og utvidelser til Microsoft Dataverse-plattformen. Den er tilgjengelig for oppretter og utviklere som kan utføre omfattende statiske analysekontroller av løsningene mot et sett med regler for beste fremgangsmåte og raskt finne problematiske mønstre. Tjenesten inneholder logikken for løsningskontrollen i Power Apps-utviklerportalen, og den inkluderes som en del av automatiseringen av programmer som sendes til AppSource. Hvis du samhandler med tjenesten direkte på denne måten, kan du analysere løsninger som er inkludert som en del av lokal versjon (alle støttede versjoner) og nettmiljøer.

Hvis du vil ha mer informasjon om hvordan du bruker kontrolltjenesten fra PowerShell-kode, kan du se Arbeide med løsninger ved hjelp av PowerShell.

Merk

Bruk av Power Apps-kontroll garanterer ikke at en løsningsimport blir vellykket. De statiske analysekontrollene som utføres mot løsningen, kjernner ikke til den konfigurerte tilstanden til målmiljøet, og importsuksess kan være avhengig av andre løsninger eller konfigurasjoner i miljøet.

Alternative tilnærminger

Før du leser gjennom detaljene for hvordan du samhandler på det laveste nivået med nett-APIene, bør du bruke vår PowerShell-modul, Microsoft.PowerApps.Checker.PowerShell i stedet. Det er et fullt støttet verktøy som er tilgjengelig i PowerShell-galleriet. Den gjeldende begrensningen er at den krever Windows PowerShell. Hvis det ikke er mulig å oppfylle dette kravet, er samhandlingen med API-ene direkte den beste metoden.

Kom i gang

Det er viktig å merke seg at en løsningsanalyse kan føre til at prosessen blir langvarig. Den kan vanligvis ta seksti (60) sekunder til opptil fem (5) minutter avhengig av en rekke faktorer, for eksempel antall, størrelse og kompleksitet for tilpassinger og kode. Analyseflyten er asynkron og består av flere trinn, og begynner med å starte en analysejobb med status-API som brukes til å spørre om fullføring av jobb. Eksempel på en flyt for en analyse er som følger:

Få et OAuth-token
Samtaleopplasting (for hver fil parallelt)
Samtaleanalyse (starter analysejobben)
Samtalestatus til ferdig (løkke med pause i mellom kall til enden er signalisert, eller terskelverdier er oppfylt)
Last ned resultatene fra den angitte SAS URI-en

Følgende er noen variasjoner:

Inkluder et oppslag for regelsettet eller regler som et forhåndstrinn. Det vil imidlertid være litt raskere å sende en konfigurert eller hardkodet regelsett-ID. Det anbefales at du bruker et regelsett som dekker behovene dine.
Du kan velge ikke å bruke opplastingsmekanismen (se opplastingen for begrensninger).

Du må fastslå følgende krav:

Hvilken geografi?
Hvilken versjon?
Hvilke regelsett og regler?
Hva er din leier-ID?

Se følgende artikler for å få dokumentasjon om de enkelte API-ene:

Hente regelsettlisten
Hente regellisten
Laste opp en fil
Aktivere analyse
Kontrollere analysestatus

Bestemme en geografi

Når du samhandler med Power Apps-kontrolltjenesten, lagres filene midlertidig i Azure sammen med rapportene som genereres. Ved å bruke et geografispesifikt API, kan du bestemme hvor dataene skal lagres. Forespørsler til et geografisk endepunkt rutes til en regional forekomst basert på den beste ytelsen (ventetid til anmoderen). Når en forespørsel legges til i en forekomst av en regional tjeneste, beholdes alle behandlings- og faste data innenfor dette bestemte området. Enkelte API-svar returnerer URL-adresser for regionale forekomster for etterfølgende forespørsler når en analysejobb er rutet til et bestemt område. Hver geografi kan ha en annen versjon av tjenesten distribuert på et gitt tidspunkt. Bruk av forskjellige tjenesteversjoner skyldes prosessen med sikker distribusjon i flere faser, noe som sikrer fullstendig versjonskompatibilitet. Den samme geografien bør derfor brukes for hvert API-kall i analyselivssyklusen, og dette kan redusere den totale kjøretiden fordi dataene ikke trenger å reise så langt. Følgende er tilgjengelige geografiske områder:

Azure Datacenter	Navn	Område	Basis-URI
Offentlig	Forhåndsversjon	USA	unitedstatesfirstrelease.api.advisor.powerapps.com
Offentlig	Produksjon	USA	unitedstates.api.advisor.powerapps.com
Offentlig	Produksjon	Europa	europe.api.advisor.powerapps.com
Offentlig	Produksjon	Asia	asia.api.advisor.powerapps.com
Offentlig	Produksjon	Australia	australia.api.advisor.powerapps.com
Offentlig	Produksjon	Japan	japan.api.advisor.powerapps.com
Offentlig	Produksjon	India	india.api.advisor.powerapps.com
Offentlig	Produksjon	Canada	canada.api.advisor.powerapps.com
Offentlig	Produksjon	Sør-Amerika	southamerica.api.advisor.powerapps.com
Offentlig	Produksjon	Storbritannia	unitedkingdom.api.advisor.powerapps.com
Offentlig	Produksjon	Frankrike	france.api.advisor.powerapps.com
Felles	Produksjon	Tyskland	germany.api.advisor.powerapps.com
Felles	Produksjon	Forente arabiske emirater	unitedarabemirates.api.advisor.powerapps.com
Felles	Produksjon	Sveits	switzerland.api.advisor.powerapps.com
Felles	Produksjon	Sør-Afrika	southafrica.api.advisor.powerapps.com
Felles	Produksjon	Sør-Korea	korea.api.advisor.powerapps.com
Felles	Produksjon	Norge	norway.api.advisor.powerapps.com
Felles	Produksjon	Singapore	singapore.api.advisor.powerapps.com
Felles	Produksjon	USAs offentlige sektor	gov.api.advisor.powerapps.us
Offentlig	Produksjon	US Government L4	high.api.advisor.powerapps.us
Offentlig	Produksjon	US Government L5 (DOD)	mil.api.advisor.appsplatform.us
Offentlig	Produksjon	Kina styrt av 21Vianet	china.api.advisor.powerapps.cn

Merk

Du kan velge å bruke forhåndsversjonsgeografien for å inkludere de nyeste funksjonene og endringene tidligere. Vær imidlertid oppmerksom på at forhåndsversjonen bare bruker Azure-områder i USA.

Versjonskontroll

Når det ikke er nødvendig, anbefales det at du inkluderer spørringsstrengparameteren for api-versjon med den ønskede API-versjonen. Gjeldende API-versjon er 2.0 for regelsett og regler og 1.0 for alle andre forespørsler. Regelsettet nedenfor er for eksempel en HTTP-forespørsel som angir at du skal bruke 2.0 API-versjonen:

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

Hvis det ikke er angitt, brukes den nyeste API-versjonen som standard. Det anbefales å bruke et eksplisitt versjonsnummer siden versjonen økes trinnvis ved eventuelle viktige endringer. Hvis versjonsnummeret er angitt i en forespørsel, opprettholdes støtte for bakoverkompatibilitet i senere versjoner (numerisk større).

Regelsett og regler

Power Apps Checker krever en liste over regler ved kjøring. Disse reglene kan gis i form av enkeltregler eller en gruppering av regler, som kalles et regelsett. Et regelsett er en nyttig måte å angi en gruppe regler på, i stedet for å måtte angi hver regel for seg. Løsningskontrollen bruker for eksempel et regelsett med navnet Løsningskontroll. Når nye regler blir lagt til eller fjernet, inkluderer tjenesten disse endringene automatisk uten at det kreves endringer i programmet som brukes. Hvis du krever at listen over regler ikke endres automatisk som beskrevet ovenfor, kan reglene angis enkeltvis. Regelsett kan ha én eller flere regler uten grense. En regel kan være i ingen eller flere regelsett. Du kan gå en liste over alle regelsett ved å kalle API-en som følger: [Geographical URL]/api/ruleset. Dette endepunktet krever nå godkjenning.

Løsningskontroll-regelsett

Løsningskontroll-regelsettet inneholder et sett med virkningsfulle regler som har begrenset fare for falske positiver. Hvis du kjører en analyse mot en eksisterende løsning, anbefales det at du starter med dette regelsettet. Dette regelsettet brukes av løsningskontrollen.

Regelsettet AppSource-sertifisering

Når du publiserer programmer på AppSource, må du få programmet sertifisert. Programmer som publiseres på AppSource, må tilfredsstille en høy kvalitetsstandard. Regelsettet AppSource-sertifisering inneholder reglene som er en del av løsningskontroll-regelsettet, samt andre regler for å sikre at bare programmer med høy kvalitet publiseres i butikken. Noen av AppSource-sertifiseringsreglene er mer utsatt for falske positiver, og kan kreve ekstra oppmerksomhet for å løse problemet.

Finne leier-IDen din

ID-en til leieren din er nødvendig for å samhandle med APIene som krever et token. Se denne artikkelen hvis du vil ha informasjon om hvordan du skaffer leier-IDen. Du kan også bruke PowerShell-kommandoer til å hente leier-IDen. Følgende eksempel bruker cmdleter i AzureAD-modulen.

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

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

Leier-IDen er verdien til ObjectId-egenskapen som returneres fra Get-AzureADTenantDetail. Du kan også se den etter at du har logget på med cmdleten Connect-AzureAD i cmdlet-utdataene. I dette tilfellet får den navnet TenantId.

Godkjenning og autorisasjon

Spørringer etter regler og regelsett krever ikke et OAuth-token, men alle de andre APIene krever tokenet. APIene støtter godkjenningsregistrering ved å kalle noen av APIene som krever et token. Svaret er en uautorisert HTTP-statuskode på 401 med et WWW-Authenticate-hode, autorisasjons-URIen og ressurs-IDen. Du må også angi leier-IDen i x-ms-tenant-id-hodet. Referer til Godkjenning og autorisasjon for Power Apps hvis du vil ha mer informasjon. Nedenfor vises et eksempel på svarhodet som returneres fra en API-forespørsel:

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 denne informasjonen, kan du velge å bruke Microsoft Authentication Library (MSAL) eller en annen mekanisme for å hente tokenet. Nedenfor vises et eksempel på hvordan dette kan utføres ved hjelp av 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();

Hvis du vil se den fullstendige arbeidskoden, kan du se eksemplet på Hurtigstart for web-API.

Når du har hentet tokenet, anbefales det at du oppgir det samme tokenet til etterfølgende kall i forespørselssyklusen. Flere forespørsler vil imidlertid sannsynligvis garantere at et nytt token blir hentet av sikkerhetshensyn.

Transportsikkerhet

Kontrolltjenesten støtter bare kommunikasjon ved hjelp av TLS (Transport Layer Security) 1.2 og senere for å oppnå best mulig kryptering. For veiledning om .NET gode fremgangsmåter for TLS, se Gode fremgangsmåter for TLS (Transport Layer Security) med .NET Framework.

Rapportformat

Resultatet av løsningsanalysen er en zip-fil som inneholder én eller flere rapporter i et standardisert JSON-format. Rapportformatet er basert på statiske analyseresultater som kalles for Static Analysis Results Interchange Format (SARIF). Det finnes verktøy som er tilgjengelige for å vise og samhandle med SARIF-dokumenter. Se dette nettstedet for mer informasjon. Tjensten bruker versjon to av OASIS-standarden.

Se også