Power Apps -tarkistustoiminnon verkko-ohjelmointirajapinnan käyttäminen

Artikkeli
02/07/2024

Power Apps -tarkistustoiminnon verkko-ohjelmointirajapinnassa on mekanismi, jonka avulla suoritetaan staattisia analyyseja mukautuksille ja laajennuksille Microsoft Dataverse -ympäristössä. Se on tekijöiden ja kehittäjien käytettävissä monipuolisia staattisia analyysitarkistuksia varten, jossa ratkaisun käyttöä verrataan parhaiden käytäntöjen mukaisiin sääntöihin. Tällä tavoin ongelmalliset kohdat havaitaan nopeasti. Palvelu tarjoaa logiikan ratkaisun tarkistustoiminnolle Power Appsn tekijäportaalissa ja sisältyy osana automaatiota sovelluksiin, jotka lähetetään AppSourceen. Kun käytät palvelua suoraan tällä tavalla, voit analysoida ratkaisuja, jotka sisältyvät paikallisiin ympäristöihin (kaikki tuetut versiot) ja verkkoympäristöihin.

Lisätietoja tarkistuspalvelun käyttämisestä PowerShell-koodilla on kohdassa Ratkaisujen käyttäminen PowerShellin avulla.

Muistiinpano

Power Apps -tarkistuksen käyttö ei takaa ratkaisun tuonnin onnistuvan. Ratkaisun staattiset analyysitarkistukset eivät tiedä kohdeympäristön määritettyä tilaa, ja tuonnin onnistuminen voi riippua muista ympäristön ratkaisuista tai konfiguraatioista.

Vaihtoehtoiset lähestymistavat

Ennen kuin luet yksityiskohtaisesti, miten voit olla vuorovaikutuksessa alimmalla tasolla verkko-ohjelmointirajapintojen kanssa, harkitse sen sijaan PowerShell-moduuliamme Microsoft.PowerApps.Checker.PowerShell. Se on täysin tuettu työkalu, joka on saatavilla PowerShell-valikoimassa. Nykyisenä rajoituksena on, että se edellyttää Windows PowerShelliä. Jos tätä vaatimusta ei voida täyttää, suora vuorovaikutus ohjelmointirajapintojen kanssa on paras lähestymistapa.

Aloitus

On tärkeää ottaa huomioon, että ratkaisuanalyysi voi johtaa pitkäkestoiseen prosessiin. Se voi tyypillisesti kestää 60 sekunnista aina viiteen (5) minuuttiin riippuen useista eri tekijöistä, kuten mukautusten ja koodin määrästä, koosta ja monimutkaisuudesta. Analyysityönkulku on monivaiheinen ja asynkroninen. Se alkaa sellaisen analyysitehtävän alustamisesta, jossa tilan ohjelmointirajapintaa käytetään tehtävän valmistumisen kyselemiseen. Esimerkki analyysityönkulusta:

OAuth-tunnuksen hankkiminen
Lataamisen kutsuminen (jokaisen tiedoston osalta rinnakkain)
Kutsun analysointi (aloittaa analyysitehtävän)
Kutsun tila valmiiseen asti (silmukka, jossa on tauko kutsujen välillä, kunnes lopusta ilmoitetaan tai kynnykset täyttyvät)
Tulosten lataaminen annetusta SAS URI -osoitteesta

Muunnelmia tästä ovat esimerkiksi:

Sääntöjoukon tai sääntöjen haun sisällyttäminen esivaiheena. On kuitenkin hieman nopeampaa välittää määritetty tai kovakoodattu sääntöjoukon tunnus. Suosituksena on sellaisen sääntöjoukon käyttäminen, joka vastaa tarpeitasi.
Voit valita, ettet käytä latausmekanismia (katso rajoitusten lataaminen).

Seuraavat tiedot on määritettävä:

Mikä paikkatieto?
Mikä versio?
Mitkä sääntöjoukot ja säännöt?
Mikä on vuokraajatunnuksesi?

Seuraavissa artikkeleissa on tietoja yksittäisistä ohjelmointirajapinnoista:

Sääntöjoukkoluettelon noutaminen
Sääntöluettelon noutaminen
Tiedoston lataaminen
Analyysin käynnistäminen
Analyysin tilan tarkistaminen

Paikkatiedon määrittäminen

Kun olet vuorovaikutuksessa Power Appsin tarkistuspalvelun kanssa, tiedostoja tallennetaan väliaikaisesti Azureen yhdessä luotavien raporttien kanssa. Käyttämällä paikkatietokohtaista ohjelmointirajapintaa voit määrätä, minne tiedot tallennetaan. Pyynnöt maantieteellisen sijainnin päätepisteeseen reititetään alueelliseen esiintymään parhaan suorituskyvyn perusteella (latenssi pyytäjälle). Kun pyyntö siirtyy alueelliseen palveluesiintymään, kaikki käsittelyt ja pysyvät tiedot pysyvät tietyllä alueella. Tietyt ohjelmointirajapinnan vastaukset palauttavat alueellisten esiintymien URL-osoitteet seuraavia pyyntöjä varten, kun analyysityö on reititetty tietylle alueelle. Kullakin maantieteellisellä alueella voi olla käytössä palvelun eri versio minä tahansa hetkenä. Palvelun eri versioiden käyttö johtuu monivaiheisesta turvallisen käyttöönoton prosessista. Tämä takaa versioiden täydellisen yhteensopivuuden. Näin ollen samaa maantieteellistä sijaintia olisi käytettävä jokaisessa API-kutsussa analyysin elinkaaren aikana, ja se voi lyhentää yleistä suoritusaikaa, koska tietojen ei ehkä tarvitse kulkea niin pitkälle verkon yli. Seuraavat paikkatiedot ovat käytettävissä:

Azure-palvelinkeskus	Nimi	Maantieteellinen alue	Perus-URI
Julkinen	Esikatselu	Yhdysvallat	unitedstatesfirstrelease.api.advisor.powerapps.com
Julkinen	Tuotanto	Yhdysvallat	unitedstates.api.advisor.powerapps.com
Julkinen	Tuotanto	Eurooppa	europe.api.advisor.powerapps.com
Julkinen	Tuotanto	Aasia	asia.api.advisor.powerapps.com
Julkinen	Tuotanto	Australia	australia.api.advisor.powerapps.com
Julkinen	Tuotanto	Japani	japan.api.advisor.powerapps.com
Julkinen	Tuotanto	Intia	india.api.advisor.powerapps.com
Julkinen	Tuotanto	Kanada	canada.api.advisor.powerapps.com
Julkinen	Tuotanto	Etelä-Amerikka	southamerica.api.advisor.powerapps.com
Julkinen	Tuotanto	Yhdistynyt kuningaskunta	unitedkingdom.api.advisor.powerapps.com
Julkinen	Tuotanto	Ranska	france.api.advisor.powerapps.com
Julkinen	Tuotanto	saksa	germany.api.advisor.powerapps.com
Julkinen	Tuotanto	Yhdistyneet Arabiemiirikunnat	unitedarabemirates.api.advisor.powerapps.com
Julkinen	Tuotantoympäristö	Sveitsi	switzerland.api.advisor.powerapps.com
Julkinen	Tuotantoympäristö	Etelä-Afrikka	southafrica.api.advisor.powerapps.com
Julkinen	Tuotantoympäristö	Etelä-Korea	korea.api.advisor.powerapps.com
Julkinen	Tuotantoympäristö	Norja	norway.api.advisor.powerapps.com
Julkinen	Tuotantoympäristö	Singapore	singapore.api.advisor.powerapps.com
Julkinen	Tuotantoympäristö	US Government	gov.api.advisor.powerapps.us
Julkinen	Tuotanto	US Government L4	high.api.advisor.powerapps.us
Julkinen	Tuotanto	US Government L5 (DOD)	mil.api.advisor.appsplatform.us
Julkinen	Tuotanto	China operated by 21Vianet	china.api.advisor.powerapps.cn

Muistiinpano

Voit päättää käyttää esikatselupaikkatietoa ottaaksesi viimeisimmät toiminnot ja muutokset käyttöön aikaisemmin. Huomaa kuitenkin, että esikatselu käyttää vain Yhdysvaltojen Azure-alueita.

Versionhallinta

On suositeltavaa lisätä ohjelmistorajapinnan version kyselymerkkijonoparametri, jossa on haluttu ohjelmistorajapinnan versio, vaikka tämä ei ole pakollista. Nykyinen ohjelmointirajapinnan versio on 2.0 sääntöjoukkoja ja sääntöjä varten ja 1.0 kaikkia muita pyyntöjä varten. Esimerkiksi seuraava sääntöjoukko on HTTP-pyyntö, jossa määritetään ohjelmistorajapinnan version 2.0 käyttö:

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

Jos sitä ei anneta, ohjelma käyttää oletusarvoisesti viimeisintä ohjelmistorajapinnan versiota. Tarkan versionumeron käyttöä suositellaan, koska versionumero kasvaa, jos käyttöön otetaan uusia muutoksia. Jos versio numero on määritetty pyynnössä, aiempien versioiden yhteensopivuuden tukea ylläpidetään myöhemmissä versioissa (numeerisesti suuremmat).

Sääntöjoukot ja säännöt

Power Appsin tarkistus edellyttää sääntöluetteloa, kun se suoritetaan. Nämä säännöt voidaan antaa yksittäisten sääntöjen muodossa tai sääntöryhmissä, jota kutsutaan sääntöjoukoiksi. Sääntöjoukko on kätevä tapa määrittää sääntöryhmä sen sijaan, että kukin sääntö määritetään erikseen. Esimerkiksi ratkaisun tarkistustoiminto käyttää sääntöjoukkoa, jonka nimi on Ratkaisun tarkistus. Kun uusia sääntöjä lisätään tai poistetaan, palvelu sisältää nämä muutokset automaattisesti muutosten vaatimista käyttävältä sovellukselta. Jos haluat, että sääntöluettelo ei muutu automaattisesti yllä kuvatulla tavalla, säännöt voidaan määrittää yksitellen. Sääntöjoukolla voi olla yksi tai useampia sääntöjä ilman rajoitusta. Sääntö voi olla yhdessä tai useammassa sääntöjoukossa. Voit saada luettelon kaikista sääntöjoukoista kutsumalla rajapintaa seuraavasti: [Geographical URL]/api/ruleset. Tämä päätepiste edellyttää nyt todennusta.

Ratkaisun tarkistuksen sääntöjoukko

Ratkaisun tarkistuksen sääntöjoukko sisältää joukon vaikuttavia sääntöjä, joilla on rajalliset virheellisten esiintymien mahdollisuudet. Jos analyysi suoritetaan aiemmin luotuun ratkaisuun verrattuna, suositellaan aloittamista tällä sääntöjoukolla. Tämä on sääntöjoukko, jota ratkaisun tarkistustoiminto käyttää.

AppSourcen sertifioinnin sääntöjoukko

Kun julkaiset sovelluksia AppSourcessa, sinun on sertifioitava sovelluksesi. AppSourcessa julkaistavien sovellusten on täytettävä korkea laatustandardi. AppSource-sertifioinnin sääntöjoukko sisältää säännöt, jotka kuuluvat ratkaisun tarkistuksen sääntöjoukkoon, sekä muita sääntöjä, joilla varmistetaan, että kaupassa julkaistaan vain korkealaatuisia sovelluksia. Osa AppSourcen sertifiointisäännöistä tuottavat useammin virheellisiä esiintymiä, ja niiden ratkaiseminen voi vaatia lisähuomiota.

Etsi vuokraajatunnuksesi

Vuokraajatunnuksesi tarvitaan vuorovaikutukseen ohjelmistorajapintojen kanssa, jotka vaativat tunnuksen. Lue lisätietoja vuokraajatunnuksen hankkimiseen tästä artikkelista. Voit käyttää vuokraajatunnuksen hakemiseen myös PowerShell-komentoja. Seuraavassa esimerkissä käytetään AzureAD-moduulin cmdlet-komentosarjoja.

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

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

Vuokraajatunnus on sen ObjectId-ominaisuuden arvo, joka palautetaan kohteesta Get-AzureADTenantDetail. Voit myös tarkastella sitä, kun olet kirjautunut käyttämällä Connect-AzureAD-cmdlet-komentoa tulosteessa. Tässä tapauksessa sen nimeksi tulee TenantId.

Todentaminen ja hyväksyminen

Sääntöjen ja sääntöjoukkojen kysely ei edellytä OAuth-tunnusta, mutta kaikki muut ohjelmointirajapinnat vaativat tunnuksen. Ohjelmistorajapinnat tukevat hyväksymisten etsintää kutsumalla ohjelmistorajapintoja, jotka vaativat tunnuksen. Vastauksena on luvaton HTTP-tilakoodi 401 ja verkkotodennusotsikko, hyväksynnän URI sekä resurssitunnus. Anna myös vuokraajatunnuksesi x-ms-tenant-id-otsikossa. Katso lisätietoja Power Appsin tarkistuksen todentamisesta ja hyväksymisestä. Seuraavassa esimerkissä on ohjelmistorajapintakyselyn palauttama vastausotsikko:

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

Kun sinulla on nämä tiedosto, voit päättää käyttää Microsoft -todennuskirjastoa (MSAL) tai muuta mekanismia tunnuksen hankkimiseen. Seuraavassa esimerkissä kerrotaan, miten tämä voidaan tehdä käyttämällä C#:tä ja MSAL .NET-kirjastoa:

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

Täydellinen toimiva koodi löytyy Web API:n pika-aloituksen esimerkissä.

Kun olet hankkinut tunnuksen, on suositeltavaa, että annat saman tunnuksen seuraaville kutsuille pyynnön elinkaaressa. Lisäpyynnöt kuitenkin todennäköisesti edellyttävät uuden tunnuksen hankkimista suojaussyistä.

Kuljetusten suojaus

Luokan parasta salausta varten tarkistuspalvelu tukee vain tiedonsiirtoa, jossa käytetään Transport Layer Securityn (TLS) versiota 1.2 tai uudempaa versiota. Tietoja TLS:ään liittyvistä parhaista .NET-käytännöistä löytyy ohjeaiheesta Transport Layer Securityn (TLS) parhaat käytännöt .NET-kehyksessä.

Raportin muoto

Ratkaisuanalyysin tuloksena on zip-tiedosto, joka sisältää yhden tai useamman raportin standardoidussa JSON-muodossa. Raportin muoto perustuu staattisen analyysin tuloksiin, joihin viitataan nimellä Static Analysis Results Interchange Format (SARIF). SARIF asiakirjoja voi tarkastella ja käsitellä erilaisilla työkaluilla. Lisätietoja on tällä verkkosivustolla. Tämä palvelu käyttää OASIS-standardin toista versiota.

Katso myös