Usar la API web del comprobador de Power Apps

  • Artículo

La API web del comprobador de Power Apps proporciona un mecanismo para ejecutar comprobaciones de análisis estático con personalizaciones y extensiones de la plataforma Microsoft Dataverse. Está disponible para que fabricantes y desarrolladores realicen comprobaciones de análisis estático de sus soluciones con un conjunto de reglas de prácticas recomendadas para identificar rápidamente patrones problemáticos. El servicio proporciona la lógica para la característica del comprobador de soluciones en el portal del fabricante de Power Apps y se incluye como parte de la automatización para solicitudes enviadas a AppSource. La interacción directamente con el servicio de esta manera permite el análisis de soluciones que se incluyen como parte de entornos locales (todas las versiones admitidas) y en línea.

Para obtener información sobre el uso del servicio del comprobador del código de PowerShell, consulte Trabajar con soluciones usando PowerShell.

Nota

  • El uso del comprobador de Power Apps no garantiza que la importación de una solución tenga éxito. Las comprobaciones de análisis estático realizadas contra la solución no conocen el estado configurado del entorno de destino y el éxito de la importación puede depender de otras soluciones o configuraciones en el entorno.

Enfoques alternativos

Antes de leer los detalles de cómo interactuar en el nivel más bajo con las API web, considere usar el módulo PowerShell, Microsoft.PowerApps.Checker.PowerShell, en su lugar. Es una herramienta completamente compatible disponible en la Galería de PowerShell. La restricción actual es que requiere Windows PowerShell. Si no puede satisfacer este requisito, la interacción directamente con las API es la mejor opción.

Comienzo

Cabe dejar constancia que los análisis de soluciones pueden producir procesos de ejecución larga. Pueden llevar normalmente desde sesenta (60) segundos hasta cinco (5) minutos en función de diversos factores, como número, tamaño, y complejidad de personalizaciones y código. El flujo de análisis tiene varias fases y es asincrónico empezando por iniciar un trabajo de análisis con la API de estado que se usa para consultar la finalización de trabajos. Un flujo de ejemplo para un análisis es el siguiente:

  1. Obtener un símbolo de OAuth
  2. Carga de llamada (para cada archivo en paralelo)
  3. Análisis de llamada (inicia el trabajo de análisis)
  4. Estado de llamada hasta terminada (bucle con una pausa entre llamadas hasta que se señala el final o se llega a los umbrales)
  5. Descargar los resultados del URI de SAS proporcionado

Algunas variaciones:

  • Incluir una búsqueda del conjunto de reglas o de las reglas como paso previo. Sin embargo, sería un poco más rápido pasar en un identificador de conjunto de reglas configurado o codificado de forma rígida. Se recomienda usar un conjunto de reglas que cubra sus necesidades.
  • Puede optar por no usar el mecanismo de carga (vea la carga para limitaciones).

Deberá determinar los siguientes requisitos:

Consulte los artículos siguientes para documentación sobre las API individuales:

Recuperar la lista de conjuntos de reglas
Recuperar la lista de reglas
Cargar un archivo
Invocar análisis
Comprobar estado de análisis

Determinar una geografía

Cuando interactúa con el servicio del comprobador de Power Apps, los archivos se almacenan temporalmente en Azure junto con informes que se generan. Mediante el uso de una API específica de la geografía puede controlar dónde se almacenan los datos. Las solicitudes a un punto de conexión geográfico se enrutan a una instancia regional según el mejor rendimiento (latencia para el solicitante). Una vez que una solicitud entra en una instancia de servicio regional, todo el procesamiento y los datos persistentes permanecen dentro de esa región en particular. Algunas respuestas de API devolverán URL de instancia regional para solicitudes posteriores una vez que un trabajo de análisis se haya enrutado a una región específica. Cada geografía puede tener una versión diferente del servicio implementada en un momento dado. El uso de diferentes versiones del servicio se debe al proceso de implementación segura de varias etapas, que garantiza la compatibilidad total de las versiones. Por lo tanto, se debe usar la misma geografía para cada llamada a la API en el ciclo de vida del análisis y puede reducirse el tiempo de ejecución general, ya que es posible que los datos no tengan que viajar tan lejos por el medio de transmisión. Las siguientes son las geografías disponibles:

Centro de datos de Azure Nombre Zona geográfica URI base
Pública Vista previa Estados Unidos unitedstatesfirstrelease.api.advisor.powerapps.com
Pública Producción Estados Unidos unitedstates.api.advisor.powerapps.com
Pública Producción Europa europe.api.advisor.powerapps.com
Pública Producción Asia asia.api.advisor.powerapps.com
Pública Producción Australia australia.api.advisor.powerapps.com
Pública Producción Japón japan.api.advisor.powerapps.com
Pública Producción India india.api.advisor.powerapps.com
Pública Producción Canadá canada.api.advisor.powerapps.com
Pública Producción Sudamérica southamerica.api.advisor.powerapps.com
Pública Producción Reino Unido unitedkingdom.api.advisor.powerapps.com
Sector público Producción Francia france.api.advisor.powerapps.com
Pública Producción Alemania germany.api.advisor.powerapps.com
Pública Producción Emiratos Árabes Unidos unitedarabemirates.api.advisor.powerapps.com
Sector público Producción Suiza switzerland.api.advisor.powerapps.com
Sector público Producción Sudáfrica southafrica.api.advisor.powerapps.com
Sector público Producción Corea del Sur korea.api.advisor.powerapps.com
Sector público Producción Noruega norway.api.advisor.powerapps.com
Sector público Producción Singapur singapore.api.advisor.powerapps.com
Sector público Producción US Government gov.api.advisor.powerapps.us
Sector público Producción US Government L4 high.api.advisor.powerapps.us
Sector público Producción US Government L5 (DOD) mil.api.advisor.appsplatform.us
Sector público Producción China operado por 21Vianet china.api.advisor.powerapps.cn

Nota

Puede optar por usar la geografía de vista previa para incorporar antes las últimas características y cambios. Sin embargo, tenga en cuenta que la vista previa usa solo las regiones de Azure de Estados Unidos.

Control de versiones

Aunque no es necesario, se recomienda incluir el parámetro de cadena de consulta de la versión de API con la versión de la API deseada. La versión actual de la API es 2.0 para conjuntos de reglas y reglas y 1.0 para todas las demás solicitudes. Por ejemplo, el siguiente conjunto de reglas es una petición HTTP que especifica utilizar la versión 2.0 de la API:

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

Si no se proporciona, se usará de forma predeterminada la última versión de la API. Se recomienda utilizar un número de versión explícito ya que la versión se incrementa si se introducen cambios importantes. Si el número de versión se especifica en una solicitud, se mantendrá el soporte de compatibilidad con versiones anteriores en versiones posteriores (numéricamente mayores).

Conjuntos de reglas y reglas

l comprobador de Power Apps requiere una lista de reglas cuando se ejecuta. Estas reglas se pueden proporcionar en forma de reglas individuales o agrupaciones de reglas, denominadas conjuntos de reglas. Un conjunto de reglas es una forma cómoda de especificar un grupo de reglas en lugar de especificar cada regla individualmente. Por ejemplo, la característica del comprobador de soluciones usa un conjunto de reglas llamado Comprobador de soluciones. Cuando se agregan o se quitan reglas, el servicio incluye estos cambios automáticamente sin requerir ningún cambio por parte de la aplicación que consume. Si requiere que la lista de reglas no cambie automáticamente como se describe anteriormente, pueden especificar reglas de forma individual. Los conjuntos de reglas pueden tener runa o varias reglas sin límite. Una regla puede no estar en ningún conjunto de reglas o en varios. Puede obtener una lista de todos los conjuntos de reglas llamando a la API de la siguiente manera: [Geographical URL]/api/ruleset. Este punto de conexión ahora requiere autenticación.

Conjunto de reglas del comprobador de soluciones

El conjunto de reglas del comprobador de soluciones contiene un conjunto de reglas que repercuten que tienen posibilidades limitadas de falsos positivos. Si ejecuta análisis con una solución existente, se recomienda que comience con este conjunto de reglas. Este conjunto de reglas es el que utiliza la característica del comprobador de soluciones.

Conjunto de reglas de certificación de AppSource

Cuando se publican aplicaciones en AppSource, debe certificar su aplicación. Las aplicaciones publicadas en AppSource son necesarias para cumplir un estándar de alta calidad. El conjunto de reglas de certificación de AppSource contiene las reglas que forman parte del conjunto de reglas del comprobador de soluciones, además de reglas adicionales para garantizar que solo aplicaciones de alta calidad se publican en el almacén. Algunas reglas de certificación de AppSource son más propensas a falsos positivos y pueden requerir atención adicional para su resolución.

Buscar el identificador de inquilino

El identificador del inquilino es necesario para interactuar con las API que requieren un símbolo. Consulte este artículo para los detalles sobre cómo obtener el identificador de inquilinos. También puede usar los comandos de PowerShell para recuperar el identificador de inquilinos. El siguiente ejemplo aplica los cmdlets en el módulo de AzureAD.

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

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

El identificador de inquilinos es el valor de la propiedad ObjectId que se devuelve de Get-AzureADTenantDetail. También puede verlo después de iniciar sesión utilizando el cmdlet Connect-AzureAD en la salida de cmdlet. En este caso, se llamará TenantId.

Autenticación y autorización

La consulta de reglas y conjuntos de reglas no requiere un símbolo OAuth, pero todas las demás API requieren el símbolo. Las API admiten detección de autorización llamando a cualquiera de las API que requieren un símbolo. La respuesta es un código de estado HTTP no autorizado de 401 con un encabezado de WWW-Authenticate, el URI de autorización y el ID de recursos. También debe proporcionar el identificador de inquilinos en el encabezado x-ms-tenant-id. Consulte Autenticación y autorización del Comprobador de Power Apps para obtener más información. A continuación se proporciona un ejemplo del encabezado de respuesta devuelto de una solicitud API:

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

Cuando tenga esta información, puede elegir usar la Microsoft Authentication Library (MSAL) o algún otro mecanismo para adquirir el símbolo. A continuación se proporciona un ejemplo de cómo se realiza esto mediante C# y 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();

Vea el código funcional completo en el ejemplo de inicio rápido de la API web.

Una vez que ha adquirido el símbolo, se aconseja que proporcione el mismo símbolo a las llamadas posteriores en el ciclo de vida de la solicitud. Sin embargo, las solicitudes adicionales pueden garantizar probablemente que se adquiera un nuevo símbolo por razones de seguridad.

Seguridad de transporte

Para el conseguir el mejor cifrado de su clase, el servicio del comprobador sólo admite comunicaciones usando Seguridad de la capa de transporte (TLS) 1.2 y superior. Para obtener instrucciones sobre las prácticas recomendadas de .NET en relación con TLS, consulte Prácticas recomendadas de Seguridad de la capa de transporte (TLS) con .NET Framework.

Formato de informe

El resultado del análisis de soluciones es un archivo zip que contiene uno o varios informes en formato estandarizado JSON. El formato de informe se basa en resultados de análisis estáticos denominado Static Analysis Results Interchange Format (SARIF). Hay herramientas disponibles para ver e interactuar con documentos SARIF. Consulte este sitio web para detalles. El servicio usa la versión dos de la norma OASIS.

Consulte también

Recuperar la lista de conjuntos de reglas
Recuperar la lista de reglas
Cargar un archivo
Invocar análisis
Comprobar estado de análisis