Verwenden der Power Apps-Überprüfungs-Web-API

  • Artikel

Die Power Apps-Überprüfungs-Web-API bietet einen Mechanismus für das Ausführen statischer Analyseprüfungen hinsichtlich Anpassungen und Erweiterungen für die Microsoft Dataverse-Plattform. Es steht Erstellern und Entwicklern zur Verfügung, damit sie ihre Lösungen anhand einer Reihe von Regeln für bewährte Verfahren einer umfassenden statischen Analyse unterziehen können, um problematische Muster schnell zu erkennen. Der Service bietet die Logik für die Lösungsprüferfunktion im Power Apps-Ersteller-Portal und ist als Teil der Automatisierung für Anwendungen enthalten, die über AppSource eingereicht werden. Das direkte Interagieren mit dem Service auf diese Weise ermöglicht eine Analyse von Lösungen, die in lokalen (alle unterstützten Versionen) und Online-Umgebungen enthalten sind.

Informationen über die Verwendung des Überprüfungsdiensts aus PowerShell-Code finden Sie unter Arbeiten mit Lösungen mit PowerShell.

Anmerkung

  • Die Verwendung der Power Apps-Überprüfung garantiert nicht, dass ein Lösungsimport erfolgreich ist. Die für die Lösung durchgeführten statischen Analyseprüfungen kennen den konfigurierten Status der Zielumgebung nicht, und der Erfolg des Imports kann von anderen Lösungen oder Konfigurationen in der Umgebung abhängen.

Alternative Ansätze

Bevor Sie sich die Details dazu ansehen, wie Sie auf der untersten Ebene mit Web-APIs interagieren, sollten Sie sich überlegen, stattdessen unser PowerShell-Modul Microsoft.PowerApps.Checker.PowerShell zu verwenden. Dies ist ein vollständig unterstütztes Tool, das in der PowerShell-Galerie verfügbar ist. Die aktuelle Einschränkung besteht darin, dass Windows PowerShell erforderlich ist. Wenn Sie diese Bedingung nicht erfüllen können, ist eine direkte Interaktion mit den APIs die beste Methode.

Erste Schritte

Beachten Sie unbedingt, dass eine Lösungsanalyse zu einem zeitintensiven Prozess führen kann. Es kann normalerweise sechzig Sekunden (60) bis zu fünf (5) Minuten dauern, abhängig von verschiedenen Faktoren, wie der Zahl, Größe und Komplexität von Anpassungen und Code. Der Analysefluss ist asynchron und besteht aus mehreren Schritten, beginnend mit der Initiierung eines Analyseauftrags mit dem Status „API”, der verwendet wird, um den Auftragsabschluss abzufragen. Ein Beispielfluss für eine Analyse lautet wie folgt:

  1. OAuth-Token besorgen
  2. Anrufupload (parallel für jede Datei)
  3. Anrufanalyse (führt den Analyseauftrag ein)
  4. Anrufstatus bis zum Abschluss (Schleife mit einer Pause zwischen Anrufen bis zum Ende signalisiert wird oder Schwellenwerte erfüllt werden)
  5. Laden Sie die Ergebnisse der bereitgestellten SAS-URI herunter.

Einige Variationen sind:

  • Schließen einer Suche des Regelsatzes oder der Regeln als Vorschritt ein. Allerdings kann es etwas schneller sein, eine Weiterleitung an eine konfigurierte oder hartcodierte Regelsatz-ID durchzuführen. Es wird empfohlen, einen Regelsatz zu verwenden, der Ihre Anforderungen erfüllt.
  • Sie können entscheiden, den Uploadmechanismus nicht zu verwenden (siehe Upload für Beschränkungen).

Sie müssen die folgenden Anforderungen bestimmen:

In den folgenden Artikeln finden Sie Dokumentationen zu den einzelnen APIs:

Abrufen der Regelsatz-Liste
Abrufen der Regel-Liste
Hochladen einer Datei
Analyse aufrufen
Überprüfen des Analysestatus

Geografie bestimmen

Beim Interagieren mit dem Power Apps-Überprüfungsservice werden Dateien zusammen mit den generierten Berichten vorübergehend in Azure gespeichert. Wenn Sie eine spezielle API für die Geografie verwenden, können Sie steuern, wo die Daten gespeichert werden. Anforderungen an einem geografischen Endpunkt werden basierend auf der besten Leistung (Latenz an den Anforderer) an eine regionale Instanz weitergeleitet. Sobald eine Anforderung in eine regionale Dienstinstanz eingeht, verbleiben alle verarbeitenden und persistierten Daten in dieser bestimmten Region. Bestimmte API-Antworten geben regionale Instanz-URLs für nachfolgende Anforderungen zurück, sobald ein Analyseauftrag an eine bestimmte Region weitergeleitet wird. In jeder Region kann zu einem bestimmten Zeitpunkt eine andere Version des Dienstes bereitgestellt werden. Die Nutzung verschiedener Serviceversionen ist auf den mehrstufigen sicheren Bereitstellungsprozess zurückzuführen, der eine vollständige Versionskompatibilität gewährleistet. Daher sollte für jeden API-Aufruf im Analyselebenszyklus dieselbe Geografie verwendet werden. Dies kann die Gesamtausführungszeit verkürzen, da die Daten möglicherweise nicht so weit über die Leitung übertragen werden müssen. Im Folgenden finden Sie die verfügbaren Geografien:

Azure-Rechenzentrum Name Geografie Basis-URI
Öffentlich Vorschau Vereinigte Staaten unitedstatesfirstrelease.api.advisor.powerapps.com
Öffentlich Produktion Vereinigte Staaten unitedstates.api.advisor.powerapps.com
Öffentlich Produktion Europa europe.api.advisor.powerapps.com
Öffentlich Produktion Asien asia.api.advisor.powerapps.com
Öffentlich Produktion Australien australia.api.advisor.powerapps.com
Öffentlich Produktion Japan japan.api.advisor.powerapps.com
Öffentlich Produktion Indien india.api.advisor.powerapps.com
Öffentlich Produktion Kanada canada.api.advisor.powerapps.com
Öffentlich Produktion Südamerika southamerica.api.advisor.powerapps.com
Öffentlich Produktion Vereinigtes Königreich unitedkingdom.api.advisor.powerapps.com
Öffentlich Produktion Frankreich france.api.advisor.powerapps.com
Public Produktion Deutschland germany.api.advisor.powerapps.com
Public Produktion Vereinigte Arabische Emirate unitedarabemirates.api.advisor.powerapps.com
Public Produktion Schweiz switzerland.api.advisor.powerapps.com
Public Produktion Südafrika southafrica.api.advisor.powerapps.com
Public Produktion Südkorea korea.api.advisor.powerapps.com
Public Produktion Norwegen norway.api.advisor.powerapps.com
Public Produktion Singapur singapore.api.advisor.powerapps.com
Public Produktion US-Regierung gov.api.advisor.powerapps.us
Öffentlich Produktion US-Regierungsbehörden L4 high.api.advisor.powerapps.us
Öffentlich Produktion US-Regierungsbehörden L5 (DOD) mil.api.advisor.appsplatform.us
Öffentlich Produktion China betrieben von 21Vianet china.api.advisor.powerapps.cn

Notiz

Sie können auswählen, ob Sie die Vorschaugeographie verwenden möchten, um die neuesten Funktionen und Änderungen früher nutzen zu können. Beachten Sie jedoch, dass für die Vorschau nur Azure-Regionen in den USA verwendet werden.

Versionsverwaltung

Dies ist zwar nicht erforderlich, es wird jedoch empfohlen, den API-Versionsabfragezeichenfolgen-Parameter mit der gewünschten API-Version zu verwenden. Die aktuelle API-Version ist 2.0 für Regelsätze und Regeln und 1.0 für alle anderen Anforderungen. Beispielsweise ist der folgende Regelsatz eine HTTP-Anforderung, in der angegeben wird, dass die API-Version 2.0 verwendet werden soll:

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

Wenn dies nicht angegeben wird, wird die aktuelle API-Version standardmäßig verwendet. Die Verwendung einer expliziten Versionsnummer wird empfohlen, da die Version erhöht wird, wenn wichtige Änderungen eingeführt werden. Wenn die Versionsnummer in einer Abfrage angegeben wird, wird die Abwärtskompatibilitätsunterstützung in späteren (numerisch größeren) Versionen beibehalten.

Regelsätze und Regeln

Die Power Apps-Überprüfung erfordert bei der Ausführung eine Liste mit Regeln. Diese Regeln können im Formular der einzelnen Regeln oder einer Gruppierung von Regeln bereitgestellt werden, auch als Regelsatz bezeichnet. Ein Regelsatz ist eine bequeme Möglichkeit, eine Gruppe von Regeln anzugeben, statt jede Regeln einzeln anzugeben. Beispielsweise verwendet die Lösungsüberprüfungsfunktion einen Regelsatz namens Lösungsprüfung. Wenn neue Regeln hinzugefügt oder entfernt werden, berücksichtigt der Service diese Änderungen automatisch, ohne dass eine Änderung durch die nutzende Anwendung erforderlich wird. Wenn Sie angeben, dass die Liste mit Regeln nicht wie oben beschrieben automatisch geändert werden darf. Dann können die Regeln einzeln angegeben werden. Regelsätze können eine oder mehrere Regeln haben, es gibt keine Beschränkung. Eine Regel kann in keinem Regelsatz oder in mehreren Regelsätzen enthalten sein. Sie können eine Liste aller Regelsätze abrufen, indem Sie die API wie folgt aufrufen: [Geographical URL]/api/ruleset. Dieser Endpunkt erfordert nun eine Authentifizierung.

Lösungsprüfer-Regelsatz

Der Lösungsprüfer-Regelsatz enthält eine Reihe von wirksamen Regeln, die Chancen für falsch positive Ergebnisse beinhalten. Wenn Sie eine vorhandene Lösung analysieren, wird empfohlen, mit diesem Regelsatz zu starten. Dieser Regelsatz wird von der Lösungsüberprüfungsfunktion verwendet.

AppSource-Zertifizierungsregelsatz

Beim Veröffentlichen von Anwendungen bei AppSource müssen Sie Ihre Anwendungen zertifizieren lassen. Bei AppSource veröffentlichte Anwendungen sind erforderlich, um einen qualitativ hochwertigen Standard zu erfüllen. Der AppSource-Zertifizierungsregelsatz enthält die Regeln, die Teil des Lösungsüberprüfungs-Regelsatzes sind, sowie andere Regeln, um sicherzustellen, dass nur qualitativ hochwertige Anwendungen im Store veröffentlicht werden. Einige der AppSource-Zertifizierungsregeln sind anfälliger für falsch positive Ergebnisse und erfordern unter Umständen mehr Aufmerksamkeit, um die Fehler zu beheben.

Suchen der Mandanten-ID

Die ID Ihres Mandanten ist erforderlich, um mit den APIs zu interagieren, die ein Token erfordern. In diesem Artikel erhalten Sie Informationen dazu, wie Sie die Mandanten-ID erhalten können. Sie können auch PowerShell-Befehle verwenden, um die Mandanten-ID abzurufen. Im folgenden Beispiel werden die Cmdlets im AzureAD-Modul angewendet.

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

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

Die Mandanten-ID ist der Wert der ObjectId-Eigenschaft, der von Get-AzureADTenantDetail zurückgegeben wird. Sie sehen sie möglicherweise nach dem Anmelden, wenn Sie das Connect-AzureAD-Cmdlet in der Cmdlet-Ausgabe verwenden. In diesem Fall wird sie TenantId genannt.

Authentifizierung und Autorisierung

Die Abfrage von Regeln und Regelsätzen erfordert kein OAuth-Token, aber bei allen anderen APIs wird das Token benötigt. Die APIs unterstützen die Autorisierungsermittlung, indem alle der APIs aufgerufen werden, die ein Token erfordern. Die Antwort ist ein nicht autorisierter HTTP-Statuscode von 401 mit einer WWW-Authentifizierungskopfzeile, der Autorisierungs-URI und der Ressourcen-ID. Sie sollten auch Ihre Mandanten-ID in der x-ms-tenant-id-Kopfzeile angeben. Unter Power Apps-Prüfungsauthentifizierung und -autorisierung erhalten Sie weitere Informationen. Nachfolgend finden Sie ein Beispiel für eine Antwortkopfzeile, die von einer API-Anforderung zurückgegeben wird:

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

Sobald Sie diese Informationen haben, können Sie die Microsoft-Authentifizierungsbibliothek (MSAL) oder einige andere Mechanismen verwenden, um das Token abzurufen. Nachfolgend finden Sie ein Beispiel, wie Sie dies mithilfe von C# und der MSAL .NET-Bibliothek erledigen können:

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

Den vollständigen funktionsfähigen Code finden im Schnellstartbeispiel der Web-API.

Sobald Sie das Token abgerufen haben, wird es empfohlen, dass Sie dasselbe Token für nachfolgende Aufrufe im Anforderungslebenszyklus angeben. Bei mehr Anforderungen ist möglicherweise der Abruf eines neuen Tokens aus Sicherheitsgründen gerechtfertigt.

Transportsicherheit

Um die beste Verschlüsselung sicherzustellen, unterstützt der Überprüfungsdienst nur die Kommunikation mithilfe von Transport Layer Security (TLS) 1.2 und höher. Bewährte Verfahren zu .NET und TLS finden Sie unter Bewährte Verfahren zu Transport Layer Security (TLS) mit dem .NET-Framework.

Berichtsformat

Das Ergebnis der Lösungsanalyse ist eine ZIP-Datei, die einen oder mehrere Berichte in einem standardisierten JSON-Format enthält. Das Berichtsformat basiert auf statischen Analyseergebnissen, die im Static Analysis Results Interchange Format (SARIF) vorliegen. Es gibt Tools, mit denen SARIF-Dokumente abgerufen werden können und damit interagiert werden kann. Auf dieser Website finden Sie weitere Details. Der Service verwendet Version zwei des OASIS-Standards.

Siehe auch

Abrufen der Regelsatz-Liste
Abrufen der Regel-Liste
Hochladen einer Datei
Analyse aufrufen
Überprüfen des Analysestatus