De web-API Power Apps-controle gebruiken

Artikel
05/01/2024

De web-API Power Apps-controle biedt een mechanisme om statische analysecontroles uit te voeren voor aanpassingen en uitbreidingen van het Microsoft Dataverse-platform. Deze is beschikbaar voor makers en ontwikkelaars om uitgebreide statische analysecontrole op hun oplossingen uitvoeren waarbij een set regels voor aanbevolen procedures wordt toegepast, en deze problematische patronen snel vaststellen. De service biedt de logica voor de oplossingscontrolefunctie in de Power Apps-maker portal en is opgenomen als onderdeel van de automatisering voor aanvragen ingediend bij AppSource. Door op deze manier rechtstreeks met de service te communiceren, kunnen oplossingen worden geanalyseerd die zijn opgenomen als onderdeel van on-premises (alle ondersteunde versies) en online omgevingen.

Zie voor informatie over het gebruik van de controleservice vanuit PowerShell-code Werken met oplossingen via PowerShell.

Notitie

Het gebruik van Power Apps-controle garandeert niet dat het importeren van een oplossing zal slagen. De statische analysecontroles die aan de hand van de oplossing worden uitgevoerd, kennen de geconfigureerde status van de doelomgeving niet en het succes van de import kan afhankelijk zijn van andere oplossingen of configuraties in de omgeving.

Alternatieve benaderingen

Voordat u de details leest over hoe u op het laagste niveau met de web-API's kunt communiceren, kunt u overwegen in plaats daarvan gebruik te maken van onze PowerShell-module Microsoft.PowerApps .Checker.PowerShell. Dit is een volledig ondersteund hulpprogramma dat beschikbaar is in de PowerShell Gallery. De huidige beperking is dat het Windows PowerShell vereist. Als u niet aan deze vereiste kunt voldoen, is rechtstreekse interactie met de API's de beste aanpak.

Aan de slag

Het is belangrijk op te merken dat een oplossingsanalyse kan leiden tot een langlopend proces. Het kan doorgaans zestig (60) seconden tot meer dan vijf (5) minuten duren, afhankelijk van verschillende factoren, zoals het aantal, de grootte en complexiteit van aanpassingen en code. De analysestroom is asynchroon en bestaat uit meerdere stappen, te beginnen met het starten van een analysetaak waarbij de status-API wordt gebruikt om te vragen naar taakvoltooiing. Een voorbeeldstroom voor een analyse is als volgt:

Een OAuth-token verkrijgen
Upload aanroepen (voor elk parallel bestand)
Analyse aanroepen (start de analysetaak)
Status aanroepen tot beëindigd (lussen met een pauze tussen aanroepen totdat het einde wordt gesignaleerd of drempelwaarden worden bereikt)
De resultaten van de verstrekte SAS-URI downloaden

Enkele variaties zijn:

Neem een opzoekactie van de regelset of regels op als een voorbereidende stap. Het gaat echter iets sneller wanneer u een geconfigureerde of hard gecodeerde regelset-id doorgeeft. U wordt aangeraden een regelset te gebruiken die aan uw behoeften voldoet.
U kunt ervoor kiezen om het uploadmechanisme niet te gebruiken (zie de upload voor beperkingen).

U moet de volgende vereisten bepalen:

Welke geografie?
Welke versie?
Welke regelsets en regels?
Wat is uw tenant-id?

Raadpleeg de volgende artikelen voor documentatie over de afzonderlijke API's:

De lijst met regelsets ophalen
De lijst met regels ophalen
Een bestand uploaden
Analyse aanroepen
Controleren op de status van de analyse

Een geografie bepalen

Bij interactie met de Power Apps-controleservice worden bestanden tijdelijk in Azure opgeslagen met de rapporten die worden gegenereerd. Door een geografiespecifieke API te gebruiken, kunt u bepalen waar de gegevens worden opgeslagen. Aanvragen bij een geografisch eindpunt worden doorgestuurd naar een regionale instantie op basis van de beste prestaties (latentie naar de aanvrager). Zodra een aanvraag bij een regionaal service-exemplaar binnenkomt, blijven alle verwerkte en persistente gegevens binnen die specifieke regio. Bepaalde API-responsen retourneren regionale exemplaar-URL's voor volgende aanvragen zodra een analysetaak naar een specifieke regio wordt doorgestuurd. Elke geografie kan op elk moment een andere versie van de service hebben geïmplementeerd. Het gebruik van verschillende serviceversies is te danken aan het veilige implementatieproces in meerdere fasen, dat volledige versiecompatibiliteit garandeert. Daarom moet dezelfde geografie worden gebruikt voor elke API-aanroep in de analyselevenscyclus en kan de algehele uitvoeringstijd korter worden omdat de gegevens mogelijk niet zo ver hoeven te reizen. De volgende geografieën zijn beschikbaar:

Azure-datacentrum	Naam	Geografie	Basis-URI
Openbaar	Preview uitvoeren	Verenigde Staten	unitedstatesfirstrelease.api.advisor.powerapps.com
Openbaar	Productie	Verenigde Staten	unitedstates.api.advisor.powerapps.com
Openbaar	Productie	Europa	europe.api.advisor.powerapps.com
Openbaar	Productie	Azië	asia.api.advisor.powerapps.com
Openbaar	Productie	Australië	australia.api.advisor.powerapps.com
Openbaar	Productie	Japan	japan.api.advisor.powerapps.com
Openbaar	Productie	India	india.api.advisor.powerapps.com
Openbaar	Productie	Canada	canada.api.advisor.powerapps.com
Openbaar	Productie	Zuid-Amerika	southamerica.api.advisor.powerapps.com
Openbaar	Productie	Verenigd Koninkrijk	unitedkingdom.api.advisor.powerapps.com
Openbaar	Productie	Frankrijk	france.api.advisor.powerapps.com
Openbaar	Productie	Duitsland	germany.api.advisor.powerapps.com
Openbaar	Productie	Verenigde Arabische Emiraten	unitedarabemirates.api.advisor.powerapps.com
Openbaar	Productie	Zwitserland	switzerland.api.advisor.powerapps.com
Openbaar	Productie	Zuid-Afrika	southafrica.api.advisor.powerapps.com
Openbaar	Productie	Zuid-Korea	korea.api.advisor.powerapps.com
Openbaar	Productie	Noorwegen	norway.api.advisor.powerapps.com
Openbaar	Productie	Singapore	singapore.api.advisor.powerapps.com
Openbaar	Productie	Zweden	sweden.api.advisor.powerapps.com
Openbaar	Productie	US Government	gov.api.advisor.powerapps.us
Openbaar	Productie	US Government L4	high.api.advisor.powerapps.us
Openbaar	Productie	US Government L5 (DOD)	mil.api.advisor.appsplatform.us
Openbaar	Productie	China uitgevoerd door 21Vianet	china.api.advisor.powerapps.cn

Notitie

U kunt ervoor kiezen om de previewgeografie te gebruiken om de nieuwste functies en wijzigingen eerder op te nemen. Houd er echter rekening mee dat de preview alleen gebruikmaakt van de Azure-regio's van de Verenigde Staten.

Versiebeheer

Hoewel dit niet vereist is, wordt aanbevolen om de queryreeksparameter api-version op te nemen met de gewenste API-versie. De huidige API-versie is 2.0 voor regelsets en regels, en 1.0 voor alle andere aanvragen. De volgende regelset is bijvoorbeeld een HTTP-verzoek waarin wordt opgegeven dat de 2.0 API-versie moet worden gebruikt:

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

Indien niets wordt opgegeven, wordt standaard de nieuwste API-versie gebruikt. Het gebruik van een expliciet versienummer wordt aanbevolen omdat de versie wordt verhoogd als er wijzigingen worden aangebracht die fouten veroorzaken. Als het versienummer in een aanvraag wordt opgegeven, blijft de ondersteuning voor compatibiliteit met eerdere versies in latere (numeriek grotere) versies behouden.

Regelsets en regels

Power Apps-controle heeft bij uitvoering een lijst met regels nodig. Deze regels kunnen worden verstrekt in de vorm van afzonderlijke regels of een groep regels, waarnaar wordt verwezen als regelset. Een regelset is een handige manier om een groep regels op te geven in plaats van elke regel afzonderlijk te moeten opgeven. De functie voor oplossingscontrole gebruikt bijvoorbeeld een regelset met de naam Oplossingscontrole. Als er nieuwe regels worden toegevoegd of verwijderd, neemt de service deze wijzigingen automatisch op zonder dat er wijzigingen nodig zijn door de verbruikende toepassing. Als u wilt dat de lijst met regels niet automatisch wordt gewijzigd op de wijze die hierboven wordt beschreven, kunt u de regels afzonderlijk opgeven. Regelsets kunnen een of meer regels hebben zonder limiet. Een regel kan zich in geen of meerdere regelsets bevinden. U kunt een lijst met alle regelsets opvragen door de API als volgt aan te roepen: [Geographical URL]/api/ruleset. Voor dit eindpunt is nu verificatie nodig.

Regelset voor oplossingscontrole

De regelset voor oplossingscontrole bevat een reeks impactvolle regels met beperkte kansen op fout-positieven. Als u een analyse uitvoert op basis van een bestaande oplossing, is het raadzaam om met deze regelset te beginnen. Deze regelset wordt gebruikt door de functie voor oplossingscontrole.

Regelset voor AppSource-certificering

Bij het publiceren van applicaties op AppSource moet u uw aanvraag laten certificeren. Toepassingen gepubliceerd op AppSource moeten voldoen aan een hoge kwaliteitsnorm. De regelset voor AppSource-certificering bevat de regels die deel uitmaken van de regelset voor oplossingscontrole, plus andere regels om ervoor te zorgen dat alleen hoogwaardige toepassingen in de Store worden gepubliceerd. Enkele van de regels voor AppSource-certificering zijn vatbaarder voor fout-positieven en vereisen mogelijk meer aandacht om op te lossen.

Uw tenant-id vinden

U hebt de id van uw tenant nodig om te communiceren met de API's die een token vereisen. Raadpleeg dit artikel voor meer informatie over hoe u de tenant-id krijgt. U kunt ook PowerShell-opdrachten gebruiken om de tenant-id op te halen. In het volgende voorbeeld worden de cmdlets in de AzureAD-module toegepast.

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

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

De tenant-id is de waarde van de eigenschap ObjectId die wordt geretourneerd op basis van Get-AzureADTenantDetail. Mogelijk ziet u deze ook na het inloggen met de Connect-AzureAD-cmdlet in de cmdlet-uitvoer. In dit geval is de naam TenantId.

Verificatie en autorisatie

Voor query's op regels en regelsets hebt u geen OAuth-token nodig, maar voor alle andere API's is het token wel vereist. De API's ondersteunen de detectie van autorisaties door een van de API's aan te roepen waarvoor een token vereist is. De respons is een niet-geautoriseerde HTTP-statuscode 401 met een WWW-Authenticate-header, de autorisatie-URI en de resource-id. U moet ook uw tenant-id opgeven in de x-ms-tenant-id-header. Zie Verificatie en autorisatie met Power Apps-controlefunctie voor meer informatie. Hieronder ziet u een voorbeeld van de header van de respons die wordt geretourneerd door een API-aanvraag:

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

Zodra u deze informatie hebt, kunt u ervoor kiezen om de Microsoft Authentication Library (MSAL) of een ander mechanisme te gebruiken om het token te verkrijgen. Hieronder ziet u een voorbeeld van hoe u dit kunt doen met C # en de MSAL .NET-bibliotheek:

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

Zie het snelstartvoorbeeld van de web-API voor de volledige werkende code.

Zodra u het token hebt ontvangen, wordt u geadviseerd hetzelfde token op te geven voor volgende aanroepen in de aanvraaglevenscyclus. Voor meer aanvragen moet om veiligheidsredenen mogelijk een nieuw token worden verkregen.

Transportbeveiliging

Voor de allerbeste versleuteling ondersteunt de controleservice alleen communicatie via TLS (Transport Layer Security) 1.2 en hoger. Raadpleeg voor richtlijnen over .NET-aanbevolen procedures ten aanzien van TLS het artikel Aanbevolen procedures voor TLS (Transport Layer Security) met het .NET Framework.

Rapportindeling

Het resultaat van de oplossingsanalyse is een zipbestand met een of meer rapporten in een gestandaardiseerde JSON-indeling. De rapportindeling is gebaseerd op statische analyseresultaten die worden aangeduid als SARIF (Static Analysis Results Interchange Format). Er zijn hulpprogramma's beschikbaar om SARIF-documenten te bekijken en ermee te werken. Raadpleeg deze website voor meer informatie. De service maakt gebruik van versie twee van de OASIS-standaard.

Zie ook