Verwenden der Power Apps-Überprüfungs-Web-APIUse the Power Apps checker web API

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 Common Data Service-Plattform.The Power Apps checker web API provides a mechanism to run static analysis checks against customizations and extensions to the Common Data Service platform. Sie ist für Ersteller und Entwickler verfügbar, um umfangreiche Prüfungen der statischen Analyse auf Ihren Lösungen für einen Satz von Regeln der bewährten Methode ausführen, um problematische Muster schnell zu ermitteln.It is available for makers and developers to perform rich static analysis checks on their solutions against a set of best practice rules to quickly identify problematic patterns. 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.The service provides the logic for the solution checker feature in the Power Apps maker portal and is included as part of the automation for applications submitted to AppSource. Das direkte Interagieren mit dem Service auf diese Weise ermöglicht eine Analyse von Lösungen, die in den lokalen (alle unterstützten Versionen) und Online-Umgebungen enthalten sind.Interacting with the service directly in this manner allows for analysis of solutions that are included as part of on-premise (all supported versions) and online environments.

Alternative AnsätzeAlternative approaches

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 nutzen.Before reading through the details of how to interact at the lowest level with the web APIs, consider leveraging our PowerShell module, Microsoft.PowerApps.Checker.PowerShell, instead. Dies ist ein vollständig unterstütztes Tool, das in der PowerShell-Galerie verfügbar ist.It is a fully supported tool that is available in the PowerShell Gallery. Die aktuelle Einschränkung besteht darin, dass Windows PowerShell erforderlich ist.The current restriction is that it does require Windows PowerShell. Wenn Sie diese Bedingung nicht erfüllen können, ist wahrscheinlich eine direkte Interaktion mit den APIs die beste Methode.If unable to meet this requirement, then interacting with the APIs directly will likely be the best approach.

Erste SchritteGetting started

Beachten Sie unbedingt, dass eine Lösungsanalyse zu einem langen Prozess führen kann.It is important to note that a solution analysis can result in a long running process. Es kann normalerweise sechzig Sekunden bis zu fünf Minuten dauern, abhängig von vielen Faktoren, wie der Zahl, Größe und Komplexität von Anpassungen und Code.It can typically take sixty seconds to upwards of five minutes depending on a variety of factors, such as number, size, and complexity of customizations and 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.The analysis flow is multi-step and asynchronous beginning with initiating an analysis job with the status API being used to query for job completion. Ein Beispielfluss für eine Analyse lautet wie folgt:An example flow for an analysis is as follows:

  1. OAuth-Token besorgenObtain an OAuth token
  2. Anrufupload (parallel für jede Datei)Call upload (for each file in parallel)
  3. Anrufanalyse (führt den Analyseauftrag ein)Call analyze (initiates the analysis job)
  4. Anrufstatus bis zum Abschluss (Schleife mit einer Pause zwischen Anrufen bis zum Ende signalisiert wird oder Schwellenwerte erfüllt werden)Call status until finished (looping with a pause in between calls until the end is signaled or thresholds are met)
  5. Laden Sie die Ergebnisse der bereitgestellten SAS-URI herunter.Download the result(s) from the provided SAS URI

Einige Variationen sind:A few variations are:

  • Schließen einer Suche des Regelsatzes oder der Regeln als Vorschritt ein.Include a lookup of the ruleset or rules as a pre-step. Allerdings kann es etwas schneller sein, eine Weiterleitung an eine konfigurierte oder hartcodierte Regelsatz-ID durchzuführen.However, it would be slightly faster to pass in a configured or hard coded ruleset ID. Es wird empfohlen, einen Regelsatz zu verwenden, der Ihre Anforderungen erfüllt.It is recommended that you use a ruleset that meets your needs.
  • Sie können entscheiden, den Uploadmechanismus nicht zu verwenden (siehe Upload für Beschränkungen).You can opt to not use the upload mechanism (see the upload for limitations).

Sie müssen die Folgenden bestimmen:You will need to determine the following:

In den folgenden Themen finden Sie Dokumentationen zu den einzelnen APIs:Refer to the following topics for documentation on the individual APIs:

Abrufen der Regelsatz-ListeRetrieve the list of rulesets
Abrufen der Regel-ListeRetrieve the list of rules
Hochladen einer DateiUpload a file
Analyse aufrufenInvoke analysis
Überprüfen des AnalysestatusCheck for analysis status

Geografie bestimmenDetermine a geography

Beim Interagieren mit dem Power Apps-Überprüfungsservice werden Dateien zusammen mit den generierten Berichten vorübergehend in Azure gespeichert.When interacting with the Power Apps checker service, files are temporarily stored in Azure along with the reports that are generated. Wenn Sie eine spezielle API für die Geografie verwenden, können Sie steuern, wo die Daten gespeichert werden.By using a geography specific API, you can control where the data is stored. Es wird empfohlen, dieselbe Geografie für jeden API-Aufruf im Analyselebenszyklus zu verwenden.It is suggested to use the same geography for each API call in the analysis lifecycle. Jede Geografie kann aufgrund unseres mehrstufigen sicheren Bereitstellungsansatzes zu einem bestimmten Zeitpunkt eine andere Version haben. So können wir eine vollständige Versionskompatibilität sicherstellen.Each geography may have a different version at any given point in time due to our multi-stage safe deployment approach and doing this ensures full version compatibility. Außerdem kann dies die Ausführungszeit verringern, da die Daten in einigen Fällen einen kürzeren Weg haben.It also may reduce execution time as the data will not have to travel as far of a distance in some cases. Im Folgenden finden Sie die verfügbaren Geografien:The following are the available geographies:

Azure-RechenzentrumAzure datacenter NameName GeografieGeography Basis-URIBase URI
ÖffentlichPublic VorschauPreview Vereinigte StaatenUnited States unitedstatesfirstrelease.api.advisor.powerapps.comunitedstatesfirstrelease.api.advisor.powerapps.com
ÖffentlichPublic ProduktionProduction Vereinigte StaatenUnited States unitedstates.api.advisor.powerapps.comunitedstates.api.advisor.powerapps.com
ÖffentlichPublic ProduktionProduction EuropaEurope europe.api.advisor.powerapps.comeurope.api.advisor.powerapps.com
ÖffentlichPublic ProduktionProduction AsienAsia asia.api.advisor.powerapps.comasia.api.advisor.powerapps.com
ÖffentlichPublic ProduktionProduction AustralienAustralia australia.api.advisor.powerapps.comaustralia.api.advisor.powerapps.com
ÖffentlichPublic ProduktionProduction JapanJapan japan.api.advisor.powerapps.comjapan.api.advisor.powerapps.com
ÖffentlichPublic ProduktionProduction IndienIndia india.api.advisor.powerapps.comindia.api.advisor.powerapps.com
ÖffentlichPublic ProduktionProduction KanadaCanada canada.api.advisor.powerapps.comcanada.api.advisor.powerapps.com
ÖffentlichPublic ProduktionProduction SüdamerikaSouth America southamerica.api.advisor.powerapps.comsouthamerica.api.advisor.powerapps.com
ÖffentlichPublic ProduktionProduction Vereinigtes KönigreichUnited Kingdom unitedkingdom.api.advisor.powerapps.comunitedkingdom.api.advisor.powerapps.com

Hinweis

Sie können auswählen, ob Sie die Vorschaugeographie verwenden möchten, um die neuesten Funktionen und Änderungen früher nutzen zu können.You may choose to use the preview geography to incorporate the latest features and changes earlier. Beachten Sie jedoch, dass für die Vorschau nur Azure-Regionen in den USA verwendet werden.However, note that the preview uses United States Azure regions only.

VersionsverwaltungVersioning

Dies ist zwar nicht erforderlich, es wird jedoch empfohlen, den API-Versionsabfragezeichenfolgen-Parameter mit der gewünschten API-Version zu verwenden.While not required, it is recommended to include the api-version query string parameter with the desired API version. Die aktuelle API-Version ist 1.0.The current API version is 1.0. Beispielsweise finden Sie eine Regelsatz-HTTP-Abfrage, in der angegeben wird, dass die API-Version 1.0 verwendet werden soll:For example, below is a ruleset HTTP request specifying to use the 1.0 API version:

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

Wenn dies nicht angegeben wird, wird die aktuelle API-Version standardmäßig verwendet.If not provided, the latest API version will be used by default. Die Verwendung einer expliziten Versionsnummer wird empfohlen, da die Version entsprechend inkrementiert wird, wenn wichtige Änderungen eingeführt werden.Using an explicit version number is recommended as the version will be incremented if breaking changes are introduced. Wenn die Versionsnummer in einer Abfrage angegeben wird, wird die Abwärtskompatibilitätsunterstützung in späteren (numerisch größeren) Versionen beibehalten.If the version number is specified in a request, backward compatibility support in later (numerically greater) versions will be maintained.

Regelsätze und RegelnRulesets and rules

Die Power Apps-Überprüfung erfordert bei der Ausführung eine Liste mit Regeln.Power Apps checker requires a list of rules when run. Diese Regeln können im Formular der einzelnen Regeln oder einer Gruppierung von Regeln bereitgestellt werden, auch als Regelsatz bezeichnet.These rules can be provided in the form of individual rules or a grouping of rules, referred to as a ruleset. Ein Regelsatz ist eine bequeme Möglichkeit, eine Gruppe von Regeln anzugeben, statt jede Regeln einzeln anzugeben.A ruleset is a convenient way to specify a group of rules instead of having to specify each rule individually. Beispielsweise verwendet die Lösungsüberprüfungsfunktion einen Regelsatz namens Lösungsprüfung.For example, the solution checker feature uses a ruleset named Solution Checker. 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.As new rules are added or removed, the service will include these changes automatically without requiring any change by the consuming application. 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.If you require that the list of rules not change automatically as described above, then the rules can be specified individually. Regelsätze können eine oder mehrere Regeln haben, es gibt keine Beschränkung.Rulesets can have one or more rules with no limit. Eine Regel kann in keinem Regelsatz oder in mehreren Regelsätzen enthalten sein.A rule can be in no or multiple rulesets. Sie können eine Liste aller Regelsätze abrufen, indem Sie die API wie folgt aufrufen: [Geographical URL]/api/ruleset.You can get a list of all rulesets by calling the API as follows: [Geographical URL]/api/ruleset. Dieser Endpunkt ist offen und erfordert keine Authentifizierung.This endpoint is open and does not require authentication.

Lösungsprüfer-RegelsatzSolution checker ruleset

Der Lösungsprüfer-Regelsatz enthält eine Reihe von wirksamen Regeln, die Chancen für falsch positive Ergebnisse beinhalten.The solution checker ruleset contains a set of impactful rules that have limited chances for false positives. Wenn Sie eine vorhandene Lösung analysieren, wird empfohlen, mit diesem Regelsatz zu starten.If running analysis against an existing solution, it is recommended that you start with this ruleset. Dieser Regelsatz wird von der Lösungsprüferfunktion verwendet.This is the ruleset used by the solution checker feature.

AppSource-ZertifizierungsregelsatzAppSource certification ruleset

Beim Veröffentlichen von Anwendungen bei AppSource müssen Sie Ihre Anwendungen zertifizieren lassen.When publishing applications on AppSource, you must get your application certified. Bei AppSource veröffentlichte Anwendungen sind erforderlich, um einen qualitativ hochwertigen Standard zu erfüllen.Applications published on AppSource are required to meet a high quality standard. Der AppSource-Zertifizierungsregelsatz enthält die Regeln, die Teil des Lösungsprüfer-Regelsatzes sind, sowie weitere Regeln, um sicherzustellen, dass nur qualitativ hochwertige Anwendungen im Store veröffentlicht werden.The AppSource certification ruleset contains the rules that are part of the solution checker ruleset, plus additional rules to ensure only high quality applications are published on the store. Einige der AppSource-Zertifizierungsregeln sind anfälliger für falsch positive Ergebnisse und erfordern unter Umständen zusätzliche Aufmerksamkeit, um die Fehler zu beheben.Some of AppSource certification rules are more prone to false positives and may require additional attention to resolve.

Suchen der Mandanten-IDFind your tenant ID

Die ID Ihres Mandanten ist erforderlich, um mit den APIs zu interagieren, die ein Token erfordern.The ID of your tenant is needed to interact with the APIs that require a token. In diesem Artikel erhalten Sie Informationen dazu, wie Sie die Mandanten-ID erhalten können.Refer to this article for details on how to obtain the tenant ID. Sie können auch PowerShell-Befehle verwenden, um die Mandanten-ID abzurufen.You can also use PowerShell commands to retrieve the tenant ID. Im folgenden Beispiel werden die Cmdlets im AzureAD-Modul verwendet.The following example leverages the cmdlets in the AzureAD module.

# Login to AAD 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.The tenant ID is the value of the ObjectId property that is returned from Get-AzureADTenantDetail. Sie sehen sie möglicherweise nach dem Anmelden, wenn Sie das Connect-AzureAD-Cmdlet in der Cmdlet-Ausgabe verwenden.You may also see it after logging in using the Connect-AzureAD cmdlet in the cmdlet output. In diesem Fall wird sie TenantId genannt.In this case it will be named TenantId.

Authentifizierung und AutorisierungAuthentication and authorization

Die Abfrage von Regeln und Regelsätzen erfordert kein OAuth-Token, aber bei allen anderen APIs wird das Token benötigt.Querying for rules and rulesets do not require an OAuth token, but all of the other APIs do require the token. Die APIs unterstützen die Autorisierungsermittlung, indem alle der APIs aufgerufen werden, die ein Token erfordern.The APIs do support authorization discovery by calling any of the APIs that require a token. Die Antwort ist ein nicht autorisierter HTTP-Statuscode von 401 mit einer WWW-Authentifizierungskopfzeile, der Autorisierungs-URI und der Ressourcen-ID.The response will be an unauthorized HTTP status code of 401 with a WWW-Authenticate header, the authorization URI, and the resource ID. Sie sollten auch Ihre Mandanten-ID in der x-ms-tenant-id-Kopfzeile angeben.You should also provide your tenant ID in the x-ms-tenant-id header. Unter Power Apps-Prüfungsauthentifizierung und -autorisierung erhalten Sie weitere Informationen.Refer to Power Apps Checker authentication and authorization for more information. Unten finden Sie ein Beispiel für eine Antwortkopfzeile, die von einer API-Abfrage zurückgegeben wird:Below is an example of the response header returned from an API request:

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 Azure Active Directory-Authentifizierungsbibliothek (ADAL) oder einige andere Mechanismen verwenden, um das Token abzurufen.Once you have this information, you can choose to use the Azure Active Directory Authentication Library (ADAL) or some other mechanism to acquire the token. Unten finden Sie ein Beispiel, wie Sie dies mithilfe von C# und der ADAL-Bibliothek, Version 4.5.1 erledigen können:Below is an example of how this can be done using C# and the ADAL library, version 4.5.1:

// Call the status URI as it is the most appropriate to use with a GET.
// The GUID here is just random, but needs to be there.
Uri queryUri = new Uri($"{targetServiceUrl}/api/status/4799049A-E623-4B2A-818A-3A674E106DE5");
AuthenticationParameters authParams = null;

using (var client = new HttpClient())
{
    var request = new HttpRequestMessage(HttpMethod.Get, queryUri);
    request.Headers.Add("x-ms-tenant-id", tenantId.ToString());

    // NOTE - It is highly recommended to use async/await
    using (var response = client.SendAsync(request).GetAwaiter().GetResult())
    {
        if (response.StatusCode == System.Net.HttpStatusCode.Unauthorized)
        {
            // NOTE - It is highly recommended to use async/await
            authParams = AuthenticationParameters.CreateFromUnauthorizedResponseAsync(response).GetAwaiter().GetResult();
        }
        else
        {
            throw new Exception($"Unable to connect to the service for authorization information. {response.ReasonPhrase}");
        }
    }
}

Sobald Sie das Token abgerufen haben, wird es empfohlen, dass Sie dasselbe Token für nachfolgende Aufrufe im Abfragelebenszyklus angeben.Once you have acquired the token, it is advised that you provide the same token to subsequent calls in the request lifecycle. Bei zusätzlichen Abfragen ist wahrscheinlich der Abruf eines neuen Tokens aus Sicherheitsgründen gerechtfertigt.However, additional requests will likely warrant a new token be acquired for security reasons.

TransportsicherheitTransport security

Um die beste Verschlüsselung sicherzustellen, unterstützt der Prüfservice nur die Kommunikation mithilfe der Transport Layer Security (TLS) 1.2 und höher.For best-in-class encryption, the checker service only supports communications using Transport Layer Security (TLS) 1.2 and above. Bewährte Verfahren zu .NET und TLS finden Sie unter Bewährte Verfahren zu Transport Layer Security (TLS) mit dem .NET-Framework.For guidance on .NET best practices around TLS, refer to Transport Layer Security (TLS) best practices with the .NET Framework.

BerichtsformatReport format

Das Ergebnis der Lösungsanalyse ist eine ZIP-Datei, die einen oder mehrere Berichte in einem standardisierten JSON-Format enthält.The result of the solution analysis is a zip file containing one or more reports in a standardized JSON format. Das Berichtsformat basiert auf statischen Analyseergebnissen, die im Static Analysis Results Interchange Format (SARIF) vorliegen.The report format is based on static analysis results referred to as Static Analysis Results Interchange Format (SARIF). Es gibt Tools, mit denen SARIF-Dokumente abgerufen werden können und damit interagiert werden kann.There are tools available to view and interact with SARIF documents. Auf dieser Website finden Sie weitere Details.Refer to this web site for details. Der Service nutzt Versionen zwei des OASIS-Standards.The service leverages version two of the OASIS standard.

Siehe auchSee also

Abrufen der Regelsatz-ListeRetrieve the list of rulesets
Abrufen der Regel-ListeRetrieve the list of rules
Hochladen einer DateiUpload a file
Analyse aufrufenInvoke analysis
Überprüfen des AnalysestatusCheck for analysis status