Compartir por

Usar a API web do verificador de Power Apps

  • Artigo

A API web do verificador de Power Apps ofrece un mecanismo para executar comprobacións de análises estáticas de personalizacións e extensións na plataforma de Microsoft Dataverse. Está dispoñible para creadores e programadores para realizar completas verificacións de análises estáticas das súas solucións con un conxunto de regras de prácticas recomendadas para identificar rapidamente padróns problemáticos. O servizo fornece a lóxica para a funcionalidade do verificador de solucións no portal de creadores de Power Apps e inclúese como parte da automatización de aplicacións enviadas a AppSource. Interactuar co servizo directamente deste xeito permite analizar as solucións que se inclúen como parte de local (todas as versións compatibles) e dos contornos en liña.

Para obter información sobre como usar o servizo de verificación do código de PowerShell, consulte Traballar con solucións mediante PowerShell.

Nota

  • O uso do verificador de Power Apps non garante que a importación da solución sexa correcta. As comprobacións de análises estáticas realizadas na solución non coñecen o estado configurado do contorno de destino e o éxito da importación pode depender doutras solucións ou configuracións do contorno.

Enfoques alternativos

Antes de ler os detalles de como interactuar ao nivel máis baixo coas API web, considera utilizar o noso módulo PowerShell, Microsoft.PowerApps.Checker.PowerShell. É unha ferramenta totalmente compatible que está dispoñible na Galería de PowerShell. A restrición actual é que require Windows PowerShell. Se non se pode cumprir este requisito, o mellor enfoque é interactuar directamente coas API.

Introdución

É importante ter en conta que unha análise de solucións pode resultar nun proceso longo. Normalmente pode levar de sesenta (60) segundos a máis de cinco (5) minutos, dependendo de varios factores, como o número, o tamaño e a complexidade das personalizacións e do código. O fluxo de análise é de varios pasos e asíncrono, comezando co inicio dun traballo de análise coa API de estado que se utiliza para consultar a finalización do traballo. Un fluxo de exemplo para unha análise é o seguinte:

  1. Obter un token OAuth
  2. Carga de chamadas (para cada ficheiro en paralelo)
  3. Análise de chamadas (inicia o traballo de análise)
  4. Estado da chamada ata que finalice (en bucle cunha pausa entre chamadas ata que o final estea sinalizado ou se cumpran os limiares)
  5. Descargar os resultados do URI de SAS proporcionado

Algunhas variacións son:

  • Inclúa unha busca das regras ou conxunto de regras como paso previo. Non obstante, sería moito máis rápido pasar un ID de conxunto de regras configurado ou codificado. É recomendable que use un conxunto de regras que se axuste ás súas necesidades.
  • Pode optar por non usar o mecanismo de carga (vexa a carga para limitacións).

Debes determinar os seguintes requisitos:

Consulte os seguintes artigos para obter documentación sobre as API individuais:

Recuperar a lista de conxuntos de regras
Recuperar a lista de regras
Cargar un ficheiro
Invocar análise
Comprobar o estado da análise

Determinar unha xeografía

Cando interactúas co Power Apps servizo de verificación, os ficheiros almacénanse temporalmente en Azure xunto cos informes que se xeran. Usando unha API específica de xeografía, pode controlar onde se almacenan os datos. As solicitudes a un extremo da zona xeográfica encamíñanse a unha instancia rexional en función do mellor rendemento (latencia para o solicitante). Unha vez que a solicitude entra nunha instancia de servizo rexional, todos os datos de procesamento e persistencia permanecen nesa rexión en particular. Algunhas respostas da API devolven URL de instancias rexionais para solicitudes posteriores unha vez que se encamiña un traballo de análise a unha rexión específica. Cada xeografía pode ter unha versión diferente do servizo implantada nun momento determinado. O uso de diferentes versións do servizo débese ao proceso de implantación segura en varias etapas, que garante a compatibilidade total das versións. Así, debería empregarse a mesma xeografía para cada chamada á API no ciclo de vida da análise e pódese reducir o tempo de execución global xa que os datos poden non ter que percorrer o fío. As seguintes son as xeografías dispoñibles:

Centro de datos de Azure Nome Zona xeográfica URI base
Pública Previsualizar Estados Unidos unitedstatesfirstrelease.api.advisor.powerapps.com
Pública Produción Estados Unidos unitedstates.api.advisor.powerapps.com
Pública Produción Europa europe.api.advisor.powerapps.com
Pública Produción Asia asia.api.advisor.powerapps.com
Pública Produción Australia australia.api.advisor.powerapps.com
Pública Produción Xapón japan.api.advisor.powerapps.com
Pública Produción India india.api.advisor.powerapps.com
Pública Produción Canadá canada.api.advisor.powerapps.com
Pública Produción América do Sur southamerica.api.advisor.powerapps.com
Pública Produción Reino Unido unitedkingdom.api.advisor.powerapps.com
Pública Produción Francia france.api.advisor.powerapps.com
Pública Produción Alemaña germany.api.advisor.powerapps.com
Pública Produción Emiratos Árabes Unidos unitedarabemirates.api.advisor.powerapps.com
Pública Produción Suíza switzerland.api.advisor.powerapps.com
Pública Produción Sudáfrica southafrica.api.advisor.powerapps.com
Pública Produción Corea korea.api.advisor.powerapps.com
Pública Produción Noruega norway.api.advisor.powerapps.com
Pública Produción Singapur singapore.api.advisor.powerapps.com
Pública Produción Suecia sweden.api.advisor.powerapps.com
Pública Produción US Government gov.api.advisor.powerapps.us
Pública Produción US Government L4 high.api.advisor.powerapps.us
Pública Produción US Government L5 (DOD) mil.api.advisor.appsplatform.us
Pública Produción Operado en China por 21Vianet china.api.advisor.powerapps.cn

Nota

Pode que opte por usar a xeografía de previsualización para incorporar as últimas funcionalidades e modificacións antes. Non obstante, teña en conta que a previsualización usa só as rexións de Azure dos Estados Unidos.

Creación de versións

Aínda que non é necesario, recoméndase incluír o parámetro da cadea de consulta da versión da API coa versión da API desexada. A versión actual da API é 2.0 para conxuntos de regras e regras e 1.0 para todas as demais solicitudes. Por exemplo, o seguinte conxunto de regras é unha solicitude HTTP que especifica utilizar a versión 2.0 da API:

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

Se non se proporciona, utilízase a última versión da API de forma predeterminada. Recoméndase empregar un número de versión explícito xa que a versión increméntase se se introducen cambios rotundos. Se se especifica o número de versión nunha solicitude, manterase a compatibilidade con versións posteriores nas versións posteriores (numericamente maiores).

Regras e conxuntos de regras

O verificador de Power Apps require unha lista de regras cando se executa. Estas regras pódense fornecer en forma de regras individuais ou agrupación de regras, denominada conxunto de regras. Un conxunto de regras é un xeito conveniente de especificar un grupo de regras en lugar de ter que especificar cada regra individualmente. Por exemplo, a funcionalidade do verificador de solucións usa un conxunto de regras denominado Verificador de solucións. A medida que se engaden ou eliminan novas regras, o servizo inclúe estes cambios automaticamente sen que se requira ningún cambio por parte da aplicación consumidora. Se esixe que a lista de regras non cambie automaticamente como se describe anteriormente, entón as regras pódense especificar individualmente. Os conxuntos de regras poden ter unha ou varias regras sen límite. Unha regra pode estar en varios conxuntos de regras ou en ningún. Pode obter unha lista de todos os conxuntos de regras chamando á API do seguinte xeito: [Geographical URL]/api/ruleset. Este punto final agora require autenticación.

Conxunto de regras do verificador de solucións

O conxunto de regras do verificador de solucións contén un conxunto de regras con impacto que teñen posibilidades limitadas de falsos positivos. Se se realiza a análise cunha solución existente, recoméndase que comece con este conxunto de regras. Este conxunto de regras úsao a función de verificación de solucións.

Conxunto de regras de certificación de AppSource

Ao publicar as aplicacións en AppSource, debe certificar a aplicación. As aplicacións publicadas en AppSource están obrigadas a cumprir un estándar de alta calidade. O AppSource conxunto de regras de certificación contén as regras que forman parte do conxunto de regras do comprobador de solucións, ademais doutras regras para garantir que só se publiquen aplicacións de alta calidade na tenda. Algunhas das AppSource regras de certificación son máis propensas a producir falsos positivos e poden requirir máis atención para resolver.

Buscar o ID do arrendatario

O ID do arrendatario é necesario para interactuar coas API que requiren un token. Consulte este artigo para obter máis información sobre como obter o ID do arrendatario. Tamén pode usar os comandos de PowerShell para recuperar o ID do arrendatario. O seguinte exemplo aplica os cmdlets do módulo AzureAD.

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

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

O ID de arrendatario é o valor da propiedade ObjectId que se devolve de Get-AzureADTenantDetail. Tamén o pode ver despois do inicio de sesión usando o cmdlet Connect-AzureAD na saída do cmdlet. Neste caso, chamarase TenantId.

Autenticación e autorización

A consulta de regras e conxuntos de regras non require un token de OAuth, pero todas as outras API si precisan do token. As API permiten a detección da autorización chamando a calquera das API que requiran un token. A resposta é un código de estado HTTP non autorizado de 401 cunha cabeceira WWW-Authenticate, o URI de autorización e o ID do recurso. Tamén debe indicar o ID de arrendatario na cabeceira x-ms-tenant-id. Consulte Power Apps Autenticación e autorización de verificador para obter máis información. O seguinte é un exemplo da cabeceira de resposta devolta dunha solicitude da API:

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

Unha vez que teña esta información, pode optar por utilizar a Biblioteca de autenticación de Microsoft (MSAL) ou algún outro mecanismo para adquirir o token. O seguinte é un exemplo de como se pode facer usando C# e a 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();

Para obter o código de traballo completo, consulte a API web Mostra de inicio rápido.

Unha vez adquirido o token, recoméndase que proporcione o mesmo token ás chamadas posteriores no ciclo de vida da solicitude. Non obstante, máis solicitudes poden xustificar a adquisición dun novo token por motivos de seguridade.

Seguridade do transporte

Para obter o mellor cifrado da súa clase, o servizo de verificación só admite comunicacións mediante Transport Layer Security (TLS) 1.2 ou superior. Para obter máis información sobre as mellores prácticas de .NET acerca de TLS, consulte Mellores prácticas de Seguridade da capa de transporte (TLS) con .NET Framework.

Formato do informe

O resultado da análise da solución é un ficheiro ZIP que contén un ou máis informes nun formato JSON estandarizado. O formato do informe baséase nos resultados da análise estática aos que se fai referencia como Formato de intercambio de resultados da análise estática (SARIF). Hai ferramentas dispoñibles para ver os documentos SARIF e interactuar con eles. Consulte este sitio web para obter máis detalles. O servizo utiliza a segunda versión do estándar OASIS.

Consulte tamén

Recuperar a lista de conxuntos de regras
Recuperar a lista de regras
Cargar un ficheiro
Invocar análise
Comprobar o estado da análise