Utilizarea API-ului web pentru verificatorul Power Apps

API-ul web al verificatorului Power Apps oferă un mecanism de efectuare a unei verificări de analiză statică în raport cu particularizările și extensiile platformei Microsoft Dataverse. Este disponibil pentru creatori și dezvoltatori în vederea efectuării unor verificări complexe ale analizei statice a soluțiilor lor în raport cu un set de reguli de bune practici în scopul identificării rapide a modelelor problematice. Serviciul oferă logica pentru caracteristica verificator de soluții în producător Power Apps portal și este inclus ca parte a automatizării pentru cereri depuse la AppSource. Interacțiunea directă cu serviciul în acest mod permite analiza soluțiilor incluse ca parte a mediilor locale (toate versiunile acceptate) și online.

Pentru informații despre utilizarea serviciului de verificare din codul PowerShell, consultați Lucrul cu soluții folosind PowerShell.

Notă

Utilizarea verificatorului Power Apps nu garantează că importul soluției va avea succes. Verificările de analiză statică efectuate împotriva soluției nu cunosc starea configurată a mediului de destinație și succesul importului poate depinde de alte soluții sau configurații din mediu.

Abordări alternative

Înainte de a citi detaliile despre cum să interacționați la cel mai scăzut nivel cu API-urile web, luați în considerare utilizarea modulului nostru PowerShell, Microsoft.PowerApps.Checker.PowerShell. Este un instrument complet compatibil, disponibil în Galeria PowerShell . Restricția actuală este aceea că necesită Windows PowerShell. Dacă nu se poate îndeplini această cerință, atunci interacțiunea directă cu API-urile este cea mai bună abordare.

Introducere

Este important de menționat că o analiză a soluției poate duce la un proces de lungă durată. De obicei, poate dura între șaizeci (60) de secunde și peste cinci (5) minute, în funcție de diverși factori, cum ar fi numărul, dimensiunea și complexitatea personalizărilor și a codului. Fluxul de analiză are mai mulți pași și este asincron începând cu inițierea unei lucrări de analiză cu API-ul de stare fiind folosit pentru a interoga pentru finalizarea operațiunii. Un flux de exemplu pentru o analiză este următorul:

Obțineți un OAuth token
Încărcare de apeluri (pentru fiecare fișier în paralel)
Analiza apelurilor (inițiază operațiunea de analiză)
Starea apelului până la terminare (bucla cu o pauză între apeluri până la încheierea semnalului sau până la atingerea pragurilor)
Descărcați rezultatele din URI-ul SAS furnizat

Câteva variațiuni sunt:

Includeți o căutare a setului de reguli sau a regulilor ca pas preliminar. Cu toate acestea, ar fi puțin mai rapid să treceți într-un cod de set de reguli configurat sau codat. Este recomandat să utilizați un set de reguli care să răspundă nevoilor dvs.
Puteți opta pentru a nu utiliza mecanismul de încărcare (consultați încărcarea pentru limitări).

Trebuie să determinați următoarele cerințe:

Care geografie?
Ce versiune?
Ce seturi de reguli și reguli?
Care este ID-ul dumneavoastră de chiriaș?

Consultați următoarele articole pentru documentație despre API-urile individuale:

Recuperează lista de seturi de reguli
Recuperează lista de reguli
Încărcați un fișier
Invocați analiza
Verificați starea analizei

Determinați o geografie

Când interacționați cu serviciul de verificare, fișierele sunt stocate temporar în Azure împreună cu rapoartele generate. Power Apps Utilizând o API specifică geografiei, puteți controla unde sunt stocate datele. Solicitările către un punct final geografic sunt direcționate către o instanță regională pe baza celor mai bune performanțe (latență către solicitant). Odată ce o cerere intră într-o instanță de serviciu regional, toate procesarea și datele persistente rămân în acea regiune anume. Anumite răspunsuri API returnează adrese URL ale instanței regionale pentru solicitările ulterioare, odată ce o lucrare de analiză este direcționată către o anumită regiune. Fiecare zonă geografică poate avea o versiune diferită a serviciului implementată la un moment dat. Utilizarea diferitelor versiuni de servicii se datorează procesului de implementare sigură în mai multe etape, care asigură compatibilitatea completă a versiunilor. Astfel, aceeași geografie ar trebui utilizată pentru fiecare apel API în ciclul de viață al analizei și poate reduce timpul de execuție global, deoarece este posibil ca datele să nu trebuiască să călătorească la fel de mult peste fir. Geografiile disponibile sunt următoarele:

Centrul de date Azure	Nume	Geografie	URI de bază
Public	Previzualizare	Statele Unite	unitedstatesfirstrelease.api.advisor.powerapps.com
Public	Producție	Statele Unite	unitedstates.api.advisor.powerapps.com
Public	Producție	Europa	europe.api.advisor.powerapps.com
Public	Producție	Asia	asia.api.advisor.powerapps.com
Public	Producție	Australia	australia.api.advisor.powerapps.com
Public	Producție	Japonia	japan.api.advisor.powerapps.com
Public	Producție	India	india.api.advisor.powerapps.com
Public	Producție	Canada	canada.api.advisor.powerapps.com
Public	Producție	America de Sud	southamerica.api.advisor.powerapps.com
Public	Producție	Regatul Unit	unitedkingdom.api.advisor.powerapps.com
Public	Producție	Franța	france.api.advisor.powerapps.com
Public	Producție	Germania	germany.api.advisor.powerapps.com
Public	Producție	Emiratele Arabe Unite	unitedarabemirates.api.advisor.powerapps.com
Public	Producție	Elveția	switzerland.api.advisor.powerapps.com
Public	Producție	Africa de Sud	southafrica.api.advisor.powerapps.com
Public	Producție	Coreea de Sud	korea.api.advisor.powerapps.com
Public	Producție	Norvegia	norway.api.advisor.powerapps.com
Public	Producție	Singapore	singapore.api.advisor.powerapps.com
Public	Producție	Suedia	sweden.api.advisor.powerapps.com
Public	Producție	Polonia	poland.api.advisor.powerapps.com
Public	Producție	Italia	italy.api.advisor.powerapps.com
Public	Producție	US Government	gov.api.advisor.powerapps.us
Public	Producție	Guvernul SUA L4	high.api.advisor.powerapps.us
Public	Producție	Guvernul SUA L5 (DOD)	mil.api.advisor.appsplatform.us
Public	Producție	China operat de 21Vianet	china.api.advisor.powerapps.cn

Notă

Puteți alege să utilizați geografia de previzualizare pentru a încorpora cele mai recente caracteristici și modificări anterioare. Cu toate acestea, rețineți că previzualizarea folosește doar regiuni Azure din Statele Unite.

Gestionarea versiunii

Deși nu este obligatoriu, se recomandă includerea parametrului de șir de interogare api-version cu versiunea API dorită. Versiunea actuală a API-ului este 2.0 pentru seturi de reguli și reguli și 1.0 pentru toate celelalte solicitări. De exemplu, următorul set de reguli este o cerere HTTP care specifică utilizarea versiunii API 2.0:

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

Dacă nu este furnizată, cea mai recentă versiune API este utilizată în mod implicit. Se recomandă utilizarea unui număr de versiune explicit, deoarece versiunea este incrementată dacă se introduc modificări importante. Dacă numărul de versiune este specificat într-o solicitare, se va menține suportul de compatibilitate în versiuni ulterioare (numeric mai mare).

Seturi de reguli și reguli

Verificatorul Power Apps necesită o listă de reguli atunci când este executat. Aceste reguli pot fi furnizate sub forma unor reguli individuale sau a unui grup de reguli, denumit drept set de reguli. Un set de reguli este un mod convenabil de a specifica un grup de reguli în loc de a specifica fiecare regulă individual. De exemplu, caracteristica de verificare a soluțiilor utilizează un set de reguli numit Verificator de soluții. Pe măsură ce sunt adăugate sau eliminate reguli noi, serviciul include automat aceste modificări, fără a fi necesară nicio modificare din partea aplicației consumatoare. Dacă doriți ca lista de reguli să nu se modifice automat așa cum este descris mai sus, atunci regulile pot fi specificate individual. Seturile de reguli pot avea una sau mai multe reguli fără limită. O regulă nu poate fi în niciunul sau mai multe seturi de reguli. Puteți obține o listă a tuturor seturilor de reguli apelând la API după cum urmează: [Geographical URL]/api/ruleset. Acest endpoint necesită acum autentificare.

Set de reguli pentru verificator de soluție

Setul de reguli pentru verificatorul de soluții conține un set de reguli de impact care au șanse limitate de fals pozitiv. Dacă rulați o analiză pe baza unei soluții existente, este recomandat să începeți cu acest set de reguli. Acest set de reguli este utilizat de funcția verificator de soluții.

Set de reguli certificare AppSource

La publicarea aplicațiilor pe AppSource, trebuie să vă certificați aplicația. Aplicațiile publicate pe AppSource trebuie să îndeplinească un standard de calitate ridicat. Setul de reguli de certificare conține regulile care fac parte din setul de reguli pentru verificatorul de soluții, plus alte reguli pentru a asigura publicarea în magazin doar a aplicațiilor de înaltă calitate. AppSource Unele dintre regulile de certificare sunt mai predispuse la rezultate fals pozitive și pot necesita mai multă atenție pentru a fi rezolvate. AppSource

Găsiți ID-ul entității dvs. găzduite

ID-ul entității dvs. găzduite este necesar pentru a interacționa cu API-urile care necesită un token. Faceți referire la acest articol pentru detalii despre cum se obține ID-ul entității găzduite. Puteți utiliza, de asemenea, comenzile PowerShell pentru a prelua ID-ul entității găzduite. Următorul exemplu aplică cmdlet-urile din modulul AzureAD.

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

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

ID-ul entității găzduite este valoarea proprietății ObjectId care este returnată din Get-AzureADTenantDetail. Puteți vedea, de asemenea, după logare folosind cmdlet-ul Connect-AzureAD din ieșirea cmdlet. În acest caz, va fi denumită TenantId.

Autentificare și autorizare

Interogarea pentru reguli și seturi de reguli nu necesită un token, dar toate celelalte API-uri necesită token-ul. OAuth API-urile acceptă descoperirea autorizației apelând oricare dintre API-urile care necesită un token. Răspunsul este un cod de stare HTTP neautorizat de 401 cu un antet WWW-Authenticate, URI-ul de autorizare și ID-ul resursei. De asemenea, ar trebui să furnizați ID-ul entității găzduite în antetul x-ms-tenant-id. Consultați Power Apps Verificatorul de autentificare și autorizare pentru mai multe informații. Următorul este un exemplu de antet de răspuns returnat de o solicitare API:

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

După ce aveți aceste informații, puteți alege să utilizați Biblioteca de autentificare Microsoft (MSAL) sau un alt mecanism pentru a obține token-ul. Următorul exemplu este cum se poate realiza acest lucru folosind C# și biblioteca MSAL .NET: ...

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

Pentru codul complet funcțional, consultați exemplul Web API QuickStart.

După ce ați obținut token-ul, este recomandat să îl furnizați apelurilor ulterioare din ciclul de viață al solicitării. Totuși, mai multe solicitări pot justifica achiziționarea unui nou token din motive de securitate.

Securitatea transporturilor

Pentru o criptare de cea mai bună calitate, serviciul de verificare acceptă doar comunicații care utilizează Transport Layer Security (TLS) 1.2 și versiuni ulterioare. Pentru instrucțiuni privind cele mai bune practici .NET în jurul TLS, consultați Cele mai bune practici de Transport Layer Security (TLS) cu .NET Framework.

Format raport

Rezultatul analizei soluției este un fișier zip care conține unul sau mai multe rapoarte într-un format JSON standardizat. Formatul raportului se bazează pe rezultatele analizei statice, denumite Format de schimb de rezultate ale analizei statice (SARIF). Există instrumente disponibile pentru a vizualiza și interacționa cu documentele SARIF. Consultați acest site pentru detalii. Serviciul utilizează versiunea a doua a standardului OASIS. ...

Consultați și