Tilbakemeldinger

Bruke nett-API-en for Power Apps-kontroll

  • Artikkel
  • 7 minutter å lese

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. Produsenter og utviklere kan bruke den til å utvikle en omfattende statisk analysekontroll av løsningene mot et sett med regler for beste fremgangsmåte og raskt finne disse problematiske mønstrene. 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.

Obs!

  • 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 sannsynligvis samhandlingen med APIene direkte knyttet til den beste metoden.

Komme i gang

Det er viktig å merke seg at en løsningsanalyse kan føre til at prosessen blir langvarig. Den kan vanligvis ta 60 sekunder til opptil fem 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:

  1. Få et OAuth-token
  2. Samtaleopplasting (for hver fil parallelt)
  3. Samtaleanalyse (starter analysejobben)
  4. Samtalestatus til ferdig (løkke med pause i mellom kall til enden er signalisert, eller terskelverdier er oppfylt)
  5. 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:

Se følgende emner 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 vil returnere URL-adresser for regionale forekomster for etterfølgende forespørsler når en analysejobb har blitt rutet til et bestemt område. Vær oppmerksom på at hver enkelt geografi kan ha en annen versjon av den distribuerte tjenesten på et gitt tidspunkt på grunn av vår flertrinns fremgangsmåte for sikker distribusjon, noe som sikrer full 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
Offentlig Produksjon for 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

Obs!

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 1.0. Nedenfor finner du for eksempel et regelsett for HTTP-forespørsel som angir at du skal bruke 1.0 API-versjonen:

https://unitedstatesfirstrelease.api.advisor.powerapps.com/api/ruleset?api-version=1.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. Denne endepunktet er åpent og krever ikke 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 er regelsettet som 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 tilleggsregler 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 ytterligere 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 benytter cmdleter i AzureAD-modulen.

# Login to AAD 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 vil være 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 Azure Active Directory Authentication Library (ADAL) eller en annen mekanisme for å hente tokenet. Nedenfor vises et eksempel på hvordan dette kan utføres ved hjelp av C# og ADAL-biblioteket versjon 4.5.1:

// Call the status URI as it is the most appropriate to use with a GET.
// The GUID here is just random, but needs to be there.
Uri queryUri = new Uri($"{targetServiceUrl}/api/status/4799049A-E623-4B2A-818A-3A674E106DE5");
AuthenticationParameters authParams = null;

using (var client = new HttpClient())
{
    var request = new HttpRequestMessage(HttpMethod.Get, queryUri);
    request.Headers.Add("x-ms-tenant-id", tenantId.ToString());

    // NOTE - It is highly recommended to use async/await
    using (var response = client.SendAsync(request).GetAwaiter().GetResult())
    {
        if (response.StatusCode == System.Net.HttpStatusCode.Unauthorized)
        {
            // NOTE - It is highly recommended to use async/await
            authParams = AuthenticationParameters.CreateFromUnauthorizedResponseAsync(response).GetAwaiter().GetResult();
        }
        else
        {
            throw new Exception($"Unable to connect to the service for authorization information. {response.ReasonPhrase}");
        }
    }
}

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 benytter versjon to av OASIS-standarden.

Se også

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

Obs!

Kan du fortelle oss om språkinnstillingene for dokumentasjonen? Ta en kort undersøkelse. (vær oppmerksom på at denne undersøkelsen er på engelsk)

Undersøkelsen tar rundt sju minutter. Det blir ikke samlet inn noen personopplysninger (personvernerklæring).