Ús de l'API web del comprovador del Power Apps

Article
05/01/2024

L'API web del Verificador del Power Apps proporciona un mecanisme per executar comprovacions d'anàlisi estàtica sobre les personalitzacions i les extensions de la plataforma del Microsoft Dataverse. Està disponible per a creadors i desenvolupadors per realitzar verificacions d'anàlisi estàtica rica a les solucions amb un conjunt de regles de pràctiques recomanades i identificar ràpidament patrons problemàtics. El servei proporciona la lògica per a la característica de comprovador de solucions al portal de creadors del Power Apps i s'inclou com a part de l'automatització per a les aplicacions presentades a AppSource. La interacció directa amb el servei d'aquesta manera permet analitzar les solucions que s'inclouen com a part d'entorns local (totes les versions suportades) i en línia.

Per obtenir informació sobre l'ús del servei de verificació des del codi del PowerShell, consulteu Treballar amb solucions mitjançant el PowerShell.

Nota

L'ús del verificador del Power Apps no garanteix que la importació d'una solució es realitzi correctament. Les comprovacions d'anàlisi estàtiques realitzades a la solució no coneixen l'estat configurat de l'entorn de destinació i l'execució correcta de la importació pot dependre d'altres solucions o configuracions de l'entorn.

Enfocaments alternatius

Abans de llegir els detalls de com interactuar al nivell més baix amb les API web, considereu utilitzar el nostre mòdul de PowerShell, Microsoft.PowerApps. Checker.PowerShell, en canvi. És una eina totalment compatible que està disponible a la Galeria del PowerShell. La restricció actual és que requereix el Windows PowerShell. Si no podeu complir aquest requisit, interactuar directament amb les API és el millor enfocament.

Introducció

És important tenir en compte que una anàlisi de solucions pot resultar en un procés de llarga durada. Normalment pot trigar de seixanta (60) segons a més de cinc (5) minuts, depenent de diversos factors, com ara el nombre, la mida i la complexitat de les personalitzacions i el codi. El flux d'anàlisi és de diversos passos i asíncron, i comença iniciant una feina d'anàlisi amb l'API d'estat que s'utilitza per fer la consulta de l'acabament de la feina. Un flux d'exemple per a una anàlisi és el següent:

Obtenir un testimoni d'OAuth
Càrrega de trucades (per a cada fitxer en paral·lel)
Anàlisi de trucades (inicia la feina d'anàlisi)
Estat de les trucades fins a la finalització (bucle amb una pausa entre trucades fins que s'indiqui el final o es compleixin els llindars)
Baixar els resultats de l'URI de SAS proporcionat

Algunes variacions són:

Incloeu una cerca del conjunt de normes o normes com un pas previ. No obstant, seria una mica més ràpid passar un identificador de conjunt de normes configurat o codificat de manera permanent. Es recomana utilitzar un conjunt de normes que s'ajusti a les vostres necessitats.
Podeu optar per no utilitzar el mecanisme de càrrega (vegeu la càrrega per conèixer les limitacions).

Heu de determinar els requisits següents:

Quina zona geogràfica?
Quina versió?
Quins conjunts de normes i normes?
Quin és l'identificador de l'inquilí?

Consulteu els articles següents per obtenir documentació sobre les API individuals:

Recuperar la llista de conjunts de normes
Recuperar la llista de normes
Carregar un fitxer
Invocar l'anàlisi
Comprovar l'estat de l'anàlisi

Determinar una zona geogràfica

Quan interactueu amb el servei de verificació, els fitxers s'emmagatzemen temporalment a l'Azure Power Apps juntament amb els informes que es generen. Mitjançant l'ús d'una API específica de la zona geogràfica, podeu controlar on s'emmagatzemen les dades. Les sol·licituds a un extrem geogràfic s'envien a una instància regional en funció del millor rendiment (latència fins al sol·licitant). Quan una sol·licitud entra en una instància de servei regional, tot el processament i les dades persistents romanen dins d'aquesta regió en particular. Algunes respostes de l'API retornen URL d'instància regionals per a sol·licituds posteriors un cop s'encamina un treball d'anàlisi a una regió específica. Cada geografia pot tenir una versió diferent del servei desplegada en un moment determinat. L'ús de diferents versions de servei es deu al procés d'implementació segura en diverses etapes, que garanteix la compatibilitat completa de la versió. Per tant, la mateixa zona geogràfica s'hauria d'utilitzar per a cada trucada a l'API en el cicle de vida de l'anàlisi i pot reduir el temps d'execució global, ja que les dades no hauran de viatjar tan lluny. Estan disponibles les zones geogràfiques següents:

Centre de dades de l'Azure	Nom	Zona geogràfica	URI base
Pública	Versió preliminar	Estats Units	unitedstatesfirstrelease.api.advisor.powerapps.com
Pública	Producció	Estats Units	unitedstates.api.advisor.powerapps.com
Pública	Producció	Europa	europe.api.advisor.powerapps.com
Pública	Producció	Àsia	asia.api.advisor.powerapps.com
Pública	Producció	Austràlia	australia.api.advisor.powerapps.com
Pública	Producció	Japó	japan.api.advisor.powerapps.com
Pública	Producció	Índia	india.api.advisor.powerapps.com
Pública	Producció	Canadà	canada.api.advisor.powerapps.com
Pública	Producció	Amèrica del Sud	southamerica.api.advisor.powerapps.com
Pública	Producció	Regne Unit	unitedkingdom.api.advisor.powerapps.com
Pública	Producció	França	france.api.advisor.powerapps.com
Pública	Producció	Alemanya	germany.api.advisor.powerapps.com
Pública	Producció	Emirats Àrabs Units	unitedarabemirates.api.advisor.powerapps.com
Pública	Producció	Suïssa	switzerland.api.advisor.powerapps.com
Pública	Producció	República de Sud-àfrica	southafrica.api.advisor.powerapps.com
Pública	Producció	Corea del Sud	korea.api.advisor.powerapps.com
Pública	Producció	Noruega	norway.api.advisor.powerapps.com
Pública	Producció	Singapur	singapore.api.advisor.powerapps.com
Pública	Producció	Suècia	sweden.api.advisor.powerapps.com
Pública	Producció	US Government	gov.api.advisor.powerapps.us
Pública	Producció	US Government L4	high.api.advisor.powerapps.us
Pública	Producció	US Government L5 (DOD)	mil.api.advisor.appsplatform.us
Pública	Producció	Xina operat per 21Vianet	china.api.advisor.powerapps.cn

Nota

Podeu utilitzar la zona geogràfica de visualització prèvia per incorporar les característiques més recents i els canvis anteriors. No obstant, tingueu en compte que la visualització prèvia utilitza només les regions de l'Azure dels Estats Units.

Versions

Tot i que no és necessari, es recomana incloure el paràmetre de cadena de consulta de versió API amb la versió de l'API desitjada. La versió actual de l'API és 2.0 per a reglaments i regles i 1.0 per a la resta de sol·licituds. Per exemple, el conjunt de regles següent és una sol·licitud HTTP que especifica utilitzar la versió de l'API 2.0:

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

Si no es proporciona, s'utilitza per defecte l'última versió de l'API. Es recomana utilitzar un número de versió explícit, ja que la versió s'incrementa si s'introdueixen canvis de ruptura. Si el número de versió s'especifica a una sol·licitud, es mantindrà la retrocompatibilitat en versions posteriors (numèricament superiors).

Conjunts de normes i normes

El comprovador del Power Apps necessita una llista de normes quan s'executa. Aquestes normes es poden proporcionar en forma de normes individuals o d'un agrupament de normes, anomenats conjunts de normes. Un conjunt de normes és una manera pràctica d'especificar un grup de normes en comptes d'haver d'especificar cada norma individualment. Per exemple, la característica de comprovació de la solució utilitza un conjunt de normes anomenat Comprovador de la solució. A mesura que s'afegeixen o eliminen noves regles, el servei inclou aquests canvis automàticament sense necessitat de cap canvi per part de l'aplicació consumidora. Si necessiteu que la llista de normes no canviï automàticament com s'ha descrit anteriorment, les normes es poden especificar individualment. Els conjunts de normes poden tenir una o diverses normes sense límit. Una norma pot ser en cap o diversos conjunts de normes. Podeu obtenir una llista de tots els conjunts de normes trucant a l'API de la següent manera: [Geographical URL]/api/ruleset. Aquest punt final ara requereix autenticació.

Conjunt de normes del comprovador de solucions

El conjunt de normes del comprovador de solucions conté un conjunt de normes impactants amb poques oportunitats de falsos positius. Si executeu anàlisis amb una solució existent, us recomanem que comenceu amb aquest conjunt de regles. Aquest conjunt de regles l'utilitza la funció de verificació de solucions.

Conjunt de normes de certificació d'AppSource

Quan publiqueu aplicacions a AppSource, heu d'obtenir la certificació de l'aplicació. Les aplicacions publicades a AppSource cal que compleixin un estàndard d'alta qualitat. El AppSource conjunt de regles de certificació conté les regles que formen part del conjunt de regles de verificació de solucions, a més d'altres regles per garantir que només es publiquin aplicacions d'alta qualitat a la botiga. Algunes de les normes són AppSource més propenses a donar falsos positius i poden requerir més atenció per resoldre-les.

Cercar l'identificador de l'inquilí

L'identificador del vostre inquilí és necessari per interactuar amb les API que necessiten un testimoni. Consulteu aquest article per obtenir més informació sobre com s'obté l'identificador d'inquilí. També podeu utilitzar ordres del PowerShell per recuperar l'identificador d'inquilí. L'exemple següent aplica els cmdlets al mòdul de l'AzureAD.

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

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

L'identificador d'inquilí és el valor de la propietat ObjectId que es torna de Get-AzureADTenantDetail. També podeu veure'l després d'iniciar la sessió amb el cmdlet Connect-AzureAD a la sortida del cmdlet. En aquest cas, es nomenarà TenantId.

Autenticació i autorització

La consulta de regles i regles no requereix un testimoni OAuth, però totes les altres API requereixen el testimoni. Les API admeten el descobriment de l'autorització trucant a qualsevol de les API que requereixin un testimoni. La resposta és un codi d'estat HTTP no autoritzat de 401 amb una capçalera WWW-Authenticate, l'URI d'autorització i l'ID del recurs. També heu d'indicar a la capçalera x-ms-tenant-id l'identificador d'inquilí. Consulteu l'autenticació i l'autorització Power Apps del verificador per obtenir més informació. A continuació es mostra un exemple de la capçalera de resposta retornada d'una sol·licitud de l'API:

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

Un cop tingueu aquesta informació, podeu optar per utilitzar la biblioteca d'autenticació de Microsoft (MSAL) o algun altre mecanisme per adquirir el testimoni. El següent és un exemple de com es pot fer utilitzant C# i la 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();

Per obtenir el codi de treball complet, vegeu l'exemple d'inici ràpid de l'APIweb.

Un cop hàgiu adquirit el testimoni, us recomanem que proporcioneu el mateix testimoni a les trucades posteriors del cicle de vida de la sol·licitud. No obstant això, més sol·licituds poden justificar l'adquisició d'un nou testimoni per motius de seguretat.

Seguretat del transport

Per al xifratge millor de la seva classe, el servei de verificació només admet comunicacions mitjançant Seguretat de la capa de transport (TLS) 1.2 i superior. Per veure orientació sobre les millors pràctiques de .NET sobre TLS, consulteu Pràctiques recomanades de seguretat Transport Layer Security (TLS) amb .NET Framework.

Format de l'informe

El resultat de l'anàlisi de la solució és un fitxer zip que conté un o diversos informes en un format JSON estandarditzat. El format de l'informe es basa en els resultats de l'anàlisi estàtica anomenats com a format d'intercanvi de resultats d'anàlisi estàtics (SARIF). Hi ha eines disponibles per visualitzar i interactuar amb els documents SARIF. Consulteu aquest lloc web per obtenir més informació. El servei utilitza la segona versió de l'estàndard OASIS.

Consulteu també