Utiliser l’API Web du vérificateur Power Apps

Article
05/01/2024

L’API Web du vérificateur Power Apps offre un mécanisme permettant d’exécuter les vérifications d’analyse statique par rapport aux personnalisations et aux extensions vers la plateforme Microsoft Dataverse. Elle reste à la disposition des créateurs et des développeurs dans le cadre d’une vérification d’analyse statique enrichie de leurs solutions par rapport à un ensemble de règles de bonnes pratiques dans le but d’identifier rapidement les schémas problématiques. Le service propose la logique pour la fonctionnalité de vérificateur de solution dans le générateur Power Apps portail et est inclus dans le cadre de l’automatisation pour les applications envoyées vers AppSource. L’interaction directe avec le service de cette manière permet l’analyse des solutions incluses dans le cadre des environnements locaux (toutes les versions prises en charge) et en ligne.

Pour plus d’informations sur l’utilisation du service du vérificateur à partir du code PowerShell, reportez-vous à Utiliser des solutions à l’aide de PowerShell.

Note

L’utilisation du vérificateur Power Apps ne garantit pas que l’importation d’une solution réussira. Les vérifications d’analyse statique effectuées par rapport à la solution ne connaissent pas l’état configuré de l’environnement de destination, et le succès de l’importation peut dépendre d’autres solutions ou configurations dans l’environnement.

Approches secondaires

Avant de lire les détails sur la manière d’interagir au niveau le plus bas avec les API Web, envisagez d’utiliser notre module PowerShell, Microsoft.PowerApps.Checker.PowerShell. C'est un outil intégralement pris en charge qui est disponible dans la galerie PowerShell. La restriction actuelle est que cet outil exige Windows PowerShell. Si vous n’êtes pas en mesure de répondre à cette exigence, l’interaction directe avec les API est la meilleure approche.

Démarrage

Il est important de noter qu’une analyse de solution peut générer un long processus d’exécution. Cela prend généralement soixante (60) secondes à cinq (5) minutes selon divers facteurs, comme le nombre, la taille et la complexité des personnalisations et du code. Le flux d’analyse est constitué de plusieurs étapes et demeure asynchrone, commençant par le lancement d’une tâche d’analyse où l’API d’état est utilisée pour demander l’exécution de la tâche. Voici un exemple de flux d’analyse :

Obtenir un jeton OAuth
Appeler le chargement (pour chaque fichier en parallèle)
Appeler l’analyse (lance la tâche d’analyse)
Appeler le statut jusqu’à la fin de la tâche (boucle avec une pause entre les appels jusqu’au signal de fin ou une fois les seuils atteints)
Télécharger le(s) résultat(s) depuis l’URI SAS fourni

Certaines variantes sont les suivantes :

Ajouter une recherche de l’ensemble de règles ou de règles comme étape anticipée Toutefois, il serait un peu plus rapide de passer dans un ID d’ensemble de règles codé en dur ou configuré. Il est recommandé d’utiliser un ensemble de règles qui répond à vos besoins.
Vous pouvez choisir de ne pas utiliser le mécanisme de chargement (voir la section Télécharger pour connaître les limitations).

Vous devez déterminer les exigences suivantes :

Quel critère géographique ?
Quelle version ?
Quels ensembles de règles et quelles règles ?
Quel est votre ID client ?

Reportez-vous aux articles suivants pour la documentation sur les API individuelles :

Récupérer la liste d’ensembles de règles
Récupérer la liste de règles
Télécharger un fichier
Appeler une analyse
Vérifier le statut d’analyse

Déterminer un critère géographique

Lorsque vous interagissez avec le service du vérificateur Power Apps, les fichiers sont stockés temporairement dans Azure ainsi que les rapports générés. En utilisant une API spécifique à des critères géographiques, vous pouvez vérifier où les données sont stockées. Les requêtes vers un point de terminaison géographique sont acheminées vers une instance régionale en fonction des meilleures performances (latence vers le demandeur). Une fois qu’une requête pénètre dans une instance de service régionale, toutes les données de traitement et persistantes demeurent dans cette région particulière. Certaines réponses de l’API renvoient des URL d’instances régionales pour les requêtes ultérieures une fois qu’une tâche d’analyse est acheminée vers une région spécifique. Chaque zone géographique peut avoir une version différente du service déployé à un moment donné. L’utilisation de différentes versions du service est due au processus de déploiement sécurisé en plusieurs étapes, qui garantit la compatibilité totale des versions. Ainsi, la même zone géographique doit être utilisée pour chaque appel d’API dans le cycle de vie de l’analyse, ce qui peut réduire le temps d’exécution global car les données n’ont pas autant de distance de câble à parcourir. Les critères géographiques disponibles sont les suivants :

Centre de données Azure	Nom	Pays	L’URI de base
///Public	Aperçu	États-Unis	unitedstatesfirstrelease.api.advisor.powerapps.com
///Public	Production	États-Unis	unitedstates.api.advisor.powerapps.com
///Public	Production	Europe	europe.api.advisor.powerapps.com
///Public	Production	Asie	asia.api.advisor.powerapps.com
///Public	Production	Australie	australia.api.advisor.powerapps.com
///Public	Production	Japon	japan.api.advisor.powerapps.com
///Public	Production	Inde	india.api.advisor.powerapps.com
///Public	Production	Canada	canada.api.advisor.powerapps.com
///Public	Production	Amérique du Sud	southamerica.api.advisor.powerapps.com
///Public	Production	Royaume-Uni	unitedkingdom.api.advisor.powerapps.com
Public	Production	France	france.api.advisor.powerapps.com
Public	Production	Allemagne	germany.api.advisor.powerapps.com
Public	Production	Émirats Arabes Unis	unitedarabemirates.api.advisor.powerapps.com
Publique	Production	Suisse	switzerland.api.advisor.powerapps.com
Publique	Production	Afrique du Sud	southafrica.api.advisor.powerapps.com
Publique	Production	Corée	korea.api.advisor.powerapps.com
Publique	Production	Norvège	norway.api.advisor.powerapps.com
Publique	Production	Singapour	singapore.api.advisor.powerapps.com
Publique	Production	Suède	sweden.api.advisor.powerapps.com
Publique	Production	US Government	gov.api.advisor.powerapps.us
Public	Production	Gouvernement des États-Unis L4	high.api.advisor.powerapps.us
Public	Production	Gouvernement des États-Unis L5 (DOD)	mil.api.advisor.appsplatform.us
Public	Production	Chine géré par 21Vianet	china.api.advisor.powerapps.cn

Note

Vous pouvez choisir d’utiliser le critère géographique d’aperçu pour incorporer plus tôt les fonctionnalités et les modifications les plus récentes. Toutefois, notez que l’aperçu utilise les régions Azure des États-Unis uniquement.

Contrôle de version

Même si cela n’est pas obligatoire, il est recommandé d’inclure le paramètre de chaîne de requête de la version de l’API avec la version de l’API souhaitée. La version actuelle de l’API est 2.0 pour les ensembles de règles et les règles et 1.0 pour toutes les autres requêtes. Par exemple, l’ensemble de règles suivant est une requête HTTP qui spécifie d’utiliser la version 2.0 de l’API :

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

Si elle n’est pas fournie, la version la plus récente de l’API est utilisée par défaut. L’utilisation d’un numéro de version explicite est recommandée car la version est incrémentée si des modifications importantes sont introduites. Si le numéro de version est précisé dans une requête, la prise en charge de la rétro-compatibilité reste de mise dans les versions ultérieures (numériquement supérieures).

Ensembles de règles et règles

Le vérificateur Power Apps exige une liste des règles lors de son exécution. Ces règles peuvent être fournies sous la forme de règles individuelles ou d’un regroupement de règles, mentionnées ensemble de règles. Un ensemble de règles est une façon pratique de préciser un groupe de règles plutôt que d’avoir à spécifier chaque règle de manière individuelle. Par exemple, la fonctionnalité Vérificateur de solution utilise un ensemble de règles nommé Vérificateur de solution. Lorsque de nouvelles règles sont ajoutées ou supprimées, le service inclut ces modifications automatiquement sans exiger aucune modification par l’application qui les utilise. Si vous souhaitez que la liste de règles ne change pas automatiquement comme décrit ci-dessus, les règles peuvent être spécifiées de manière individuelle. Les ensembles de règles peuvent contenir une ou plusieurs règles sans limite. Une règle peut se situer dans un, voire plusieurs ensemble de règles. Vous pouvez obtenir une liste de tous les ensembles de règles en appelant l’API comme suit : [Geographical URL]/api/ruleset. Ce point de terminaison nécessite désormais une authentification.

Ensemble de règles du vérificateur de solutions

L’ensemble de règles du vérificateur de solution contient un ensemble de règles importantes qui risquent peu de générer des faux positifs. Si vous exécutez l’analyse sur une solution existante, il est recommandé de commencer avec cet ensemble de règles. Cet ensemble de règles est utilisé par la fonctionnalité du vérificateur de solutions.

Ensemble de règles de certification AppSource

Lors de la publication des applications sur AppSource, vous devez obtenir la certification de votre application. Les applications publiées sur AppSource doivent répondre à une norme de qualité élevée. L’ensemble de règles de certification AppSource contient les règles qui font partie de l’ensemble de règles du vérificateur de solutions, plus d’autres règles pour garantir que seules des applications de haure qualité sont publiées en magasin. Certaines des règles de certification AppSource sont plus sujettes aux faux positifs et peuvent exiger plus d’attention pour les résoudre.

Rechercher votre ID client

Votre ID client est requis pour interagir avec les API qui exigent un jeton. Consultez cet article pour en savoir plus sur la manière d’obtenir l’ID client. Vous pouvez également utiliser les commandes PowerShell pour récupérer l’ID client. L'exemple suivant applique les applets de commande dans le module AzureAD.

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

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

L’ID client désigne la valeur de la propriété ObjectId renvoyée depuis Get-AzureADTenantDetail. Vous pouvez également la voir après connexion à l’aide de l’applet de commande Connect-AzureAD dans la sortie de l’applet de commande. Dans ce cas, il s’intitulera TenantId.

Authentification et autorisation

La recherche de règles et d’ensembles de règles ne nécessite pas de jeton OAuth, mais toutes les autres API nécessitent le jeton. Les API prennent en charge la découverte d’autorisation en appelant une des API qui exigent un jeton. La réponse est un code de statut HTTP non autorisé 401 avec un en-tête WWW-Authenticate, l’URI d’autorisation et l’ID de ressource. Vous devez également fournir votre ID client dans l’en-tête x-ms-tenant-id. Consultez Authentification et autorisation du vérificateur Power Apps pour en savoir plus. Voici un exemple de l’en-tête de réponse renvoyé depuis une requête API :

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

Une fois que vous avez ces informations, vous pouvez choisir d’utiliser la bibliothèque d’authentification Microsoft (MSAL) ou un autre mécanisme pour acquérir le jeton. Voici un exemple de la manière dont cela est possible avec C# et la bibliothèque 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();

Pour le code complet, reportez-vous à l’API web Exemple de démarrage rapide.

Une fois que vous avez acquis le jeton, il est recommandé de fournir le même jeton aux appels ultérieurs au cours du cycle de vie de la requête. Toutefois, les requêtes supplémentaires peuvent garantir l’acquisition d’un nouveau jeton pour des raisons de sécurité.

Sécurité de transport

Pour un chiffrement performant, le service du vérificateur prend en charge uniquement les communications via Transport Layer Security (TLS) 1.2 et les versions supérieures. Pour obtenir des instructions sur les bonnes pratiques .NET concernant TLS, consultez Bonnes pratiques TLS avec .NET Framework.

Format de rapport

Le résultat de l’analyse de la solution prend la forme d’un fichier zip contenant un ou plusieurs rapports dans un format JSON standardisé. Le format de rapport est basé sur les résultats d’analyse statique ciblés appelés format SARIF. Des outils sont disponibles pour afficher et interagir avec les documents SARIF. Reportez-vous à ce site Web pour en savoir plus. Le service utilise la version 2 de la norme OASIS.

Voir aussi