Używanie internetowego interfejsu API narzędzia do sprawdzania usługi Power Apps

Artykuł
02/07/2024

Interfejs API sieci Web Power Apps umożliwia uruchamianie na platformie testów analizy statycznej względem dostosowań i rozszerzeń platformy Microsoft Dataverse. Dzięki funkcji sprawdzania rozwiązania twórcy i deweloperzy rozwiązań mogą przeprowadzać bogate analizy statyczne na swoich rozwiązaniach zestawu reguł wedle najlepszych metod postępowania i szybko określać problematyczne wzorce. Usługa udostępnia logikę funkcji sprawdzania rozwiązań w usłudze Power Apps, w portalu twórców i wchodzi w skład automatyzacji aplikacji przesyłanych do usługi AppSource. Bezpośrednia interakcja z usługą umożliwia analizę rozwiązań zawartych w środowiskach lokalnych (wszystkich obsługiwanych wersji) i środowiskach online.

Aby uzyskać informacje na temat używania usługi sprawdzania z kodu programu PowerShell, zobacz Praca z rozwiązaniami przy użyciu programu PowerShell.

Uwaga

Użycie Narzędzia sprawdzania Power Apps nie jest gwarancją, że importowanie rozwiązania powiedzie się. Kontrole statyczne wykonane przy użyciu rozwiązania nie wiedzą o stanie skonfigurowanym w środowisku docelowym i pomyślne zaimportowanie może być zależne od innych rozwiązań lub konfiguracji w środowisku.

Podejścia alternatywne

Przed przeczytaniem szczegółów dotyczących sposobu pracy na najniższym poziomie z interfejsami API sieci Web należy rozważyć użycie w zamian modułu PowerShell o nazwie Microsoft.PowerApps.Checker.PowerShell. Jest to w pełni obsługiwane narzędzie dostępne w Galerii programu PowerShell. Bieżące ograniczenie polega na tym, że program Windows PowerShell jest wymagany. Jeśli nie można spełnić tego wymagania, najlepszym rozwiązaniem jest bezpośrednie współdziałanie z interfejsami API.

Rozpoczynanie pracy

Należy zwrócić uwagę, że analiza rozwiązań może powodować długie działanie procesu. Zazwyczaj trwa to od sześćdziesięciu (60) sekund do około pięciu (5) minut, w zależności od różnych czynników, takich jak liczba, rozmiar i złożoność dostosowań i kodu. Przepływ analizy jest wykonywany w wielu krokach i jest asynchroniczny, począwszy od zainicjowania zadania analizy przy użyciu interfejsu API stanu używanego do wykonywania zapytań aż do ukończenia zadania. Oto przykład przepływu analizy:

Uzyskiwanie tokenu OAuth
Przekazywanie wywołania (dla każdego pliku równolegle)
Analiza wywołania (inicjuje zadanie analizy)
Stan wywołania do momentu ukończenia (przerywanie rozmowy między wywołaniami, aż zakończy się sygnał lub zostaną spełnione progi)
Pobieranie wyników z dostarczonego identyfikatora URI SAS

Oto kilka różnych odmian:

Uwzględnij wyszukiwanie zestawu reguł lub reguł jako krok wstępny. Byłoby jednak trochę szybciej przekazać skonfigurowany lub zakodowany identyfikator zestawu reguł. Zaleca się użycie zestawu reguł odpowiadającego potrzebom użytkownika.
Możesz wybrać opcję, aby nie korzystać z mechanizmu przekazywana (zobacz informacje o ograniczeniach przekazywania).

Musisz określić następujące wymagania:

Jaki obszar geograficzny?
Która wersja?
Jakie zestawienia i reguły?
Jaki jest identyfikator dzierżawcy?

Zapoznaj się z następującymi artykułami dokumentacji poszczególnych interfejsów API:

Pobieranie listy zestawów reguł
Pobieranie listy reguł
Przekazywanie pliku
Wywoływanie analizy
Sprawdzanie stanu analizy

Określanie regionu geograficznego

Podczas współpracy z usługą sprawdzania Power Apps pliki są tymczasowo przechowywane na platformie Azure wraz z raportami, które zostały wygenerowane. Korzystając z interfejsu API dla konkretnego regionu geograficznego, można kontrolować miejsce przechowywania danych. żądania skierowane do punkt końcowy geograficznej są routowane na wystąpienie regionu w zależności od optymalnej wydajności (oczekiwanie na zleceniodawcę). Po przejściu żądania do regionalnej instancji usługi wszystkie dane przetwarzania i trwałe pozostają w danym regionie. Po rozesłaniu zadania analizy do określonego regionu niektóre odpowiedzi interfejsu API zwracają adresy URL wystąpień regionalnych dla kolejnych żądań. Każde położenie geograficzne może obejmować inną wersję usługi wdrożonej w dowolnym momencie. Korzystanie z różnych wersji usług wynika z wieloetapowego procesu bezpiecznego wdrażania, który zapewnia pełną zgodność z wersją. W związku z tym ten sam obszar geograficzny powinien być używany dla każdego wywołania interfejsu API w cyklu życia analizy i może skrócić całkowity czas wykonania, ponieważ dane nie będą musiały podróżować tak daleko po sieci. Oto dostępne obszary geograficzne:

Centrum danych platformy Azure	Nazwisko	Obszar geograficzny	Podstawowy identyfikator URI
Sektor publiczny	Wersja Preview	Stany Zjednoczone	unitedstatesfirstrelease.api.advisor.powerapps.com
Sektor publiczny	Wersja produkcyjna	Stany Zjednoczone	unitedstates.api.advisor.powerapps.com
Sektor publiczny	Wersja produkcyjna	Europa	europe.api.advisor.powerapps.com
Sektor publiczny	Wersja produkcyjna	Azja	asia.api.advisor.powerapps.com
Sektor publiczny	Wersja produkcyjna	Australia	australia.api.advisor.powerapps.com
Sektor publiczny	Wersja produkcyjna	Japonia	japan.api.advisor.powerapps.com
Sektor publiczny	Wersja produkcyjna	Indie	india.api.advisor.powerapps.com
Sektor publiczny	Wersja produkcyjna	Kanada	canada.api.advisor.powerapps.com
Sektor publiczny	Wersja produkcyjna	Ameryka Południowa	southamerica.api.advisor.powerapps.com
Sektor publiczny	Wersja produkcyjna	Zjednoczone Królestwo	unitedkingdom.api.advisor.powerapps.com
Sektor publiczny	Wersja produkcyjna	Francja	france.api.advisor.powerapps.com
Publiczna	Produkcja	Niemcy	germany.api.advisor.powerapps.com
Publiczna	Produkcja	Zjednoczone Emiraty Arabskie	unitedarabemirates.api.advisor.powerapps.com
Publiczna	Produkcyjne	Szwajcaria	switzerland.api.advisor.powerapps.com
Publiczna	Produkcyjne	Republika Południowej Afryki	southafrica.api.advisor.powerapps.com
Publiczna	Produkcyjne	Korea Południowa	korea.api.advisor.powerapps.com
Publiczna	Produkcyjne	Norwegia	norway.api.advisor.powerapps.com
Publiczna	Produkcyjne	Singapur	singapore.api.advisor.powerapps.com
Publiczna	Produkcyjne	US Government	gov.api.advisor.powerapps.us
Sektor publiczny	Wersja produkcyjna	US Government L4	high.api.advisor.powerapps.us
Sektor publiczny	Wersja produkcyjna	US Government L5 (DOD)	mil.api.advisor.appsplatform.us
Sektor publiczny	Wersja produkcyjna	Chiny obsługiwane przez 21Vianet	china.api.advisor.powerapps.cn

Uwaga

Możesz użyć obszaru geograficznego w wersji zapoznawczej, aby uwzględnić najnowsze funkcje i zmiany wprowadzone wcześniej. Należy jednak pamiętać, że wersja zapoznawcza używa tylko regionów platformy Azure w Stanach Zjednoczonych.

Wersje

Chociaż nie jest to wymagane, zaleca się dołącznie parametru ciągu zapytania wersji interfejsu API do wymaganej wersji interfejsu API. Bieżąca wersja interfejsu API to 2.0 dla reguł i reguł oraz 1.0 dla wszystkich innych żądań. Na przykład następujący zestaw reguł to żądanie HTTP określające użycie wersji interfejsu API 2.0:

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

Jeśli nie zostanie on podany, domyślnie jest używana najnowsza wersja interfejsu API. Zaleca się użycie jawnego numeru wersji w przypadku wprowadzania zmian powodujących niezgodność. Jeśli numer wersji jest podany w żądaniu, w późniejszych (numerycznie większych) wersjach zostanie zachowana obsługa zgodności z poprzednimi wersjami.

Zestawy reguł i reguły

Uruchomione narzędzie do sprawdzania usługi Power Apps wymaga listy reguł. Te reguły mogą być dostarczane w formie poszczególnych reguł lub grupowania reguł zwanego zestawem reguł. Zestaw reguł to wygodny sposób określania grupy reguł, zamiast samodzielnego definiowania poszczególnych reguł. Na przykład funkcja sprawdzania rozwiązań korzysta z zestawu reguł o nazwie Kontroler rozwiązań. Po dodaniu lub usunięciu nowych reguł usługa automatycznie uwzględnia te zmiany bez konieczności zmiany przez czasochłonne aplikacje. Jeśli jest wymagane, aby lista reguł nie została zmieniona automatycznie w sposób opisany powyżej, reguły mogą być określane pojedynczo. Zestawy reguł mogą mieć jedną lub kilka reguł bez ograniczeń. Reguła może należeć do wielu zestawów reguł lub nie należeć do żadnego. Aby uzyskać listę wszystkich zestawów reguł, należy wywołać interfejs API w następujący sposób: [Geographical URL]/api/ruleset. Ten punkt końcowy wymaga teraz uwierzytelniania.

Zestaw reguł kontrolera rozwiązań

Zestaw reguł kontrolera rozwiązań zawiera zestaw istotnych reguł z ograniczonym prawdopodobieństwem wystąpienia wyników fałszywie dodatnich. W przypadku uruchamiania analizy w stosunku do istniejącego rozwiązania zaleca się rozpoczęcie pracy z tym zestawem reguł. Ten zestaw reguł jest używany przez funkcję sprawdzania rozwiązania.

Zestaw reguł certyfikacji usługi AppSource

Podczas publikowania aplikacji w witrynie AppSource musi ona uzyskać certyfikat. Aplikacje opublikowane w usłudze AppSource muszą spełniać rygorystyczne wymagania dotyczące jakości. Zestaw reguł certyfikacji AppSource zawiera reguły, które są częścią zestawu reguł sprawdzania rozwiązania oraz inne reguły zapewniające, że w magazynie są publikowane tylko wysokiej jakości aplikacje. Niektóre reguły certyfikacji AppSource bardziej poddają się fałszywym alarmom i mogą wymagać więcej uwagi, aby je rozwiązać.

Wyszukiwanie identyfikatora dzierżawcy

Identyfikator dzierżawcy jest potrzebny do korzystania z interfejsów API, które wymagają tokenu. Zobacz ten artykuł, aby zapoznać się ze szczegółowymi informacjami o tym, jak uzyskać identyfikator dzierżawcy. Aby pobrać identyfikator dzierżawcy, można również użyć poleceń programu PowerShell. Poniżej przedstawiono przykładowy kod z zastosowanymi poleceniami cmdlet w module AzureAD.

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

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

Identyfikator dzierżawcy to wartość właściwości ObjectId zwracanej przez element Get-AzureADTenantDetail. Może on również pojawić się po zalogowaniu się przy użyciu polecenia cmdlet Connect-AzureAD w danych wyjściowych polecenia cmdlet. W tym przypadku będzie nosić nazwę TenantId.

Uwierzytelnianie i autoryzacja

Zapytanie o reguły i reguły nie wymaga tokenu OAuth, ale wszystkie inne interfejsy API wymagają tokenu. Interfejsy API obsługują odnajdywanie autoryzacji dzięki wywołaniu interfejsów API, które wymagają tokenu. Odpowiedź to nieautoryzowany kod stanu HTTP 401 z nagłówkiem WWW-Authenticate, identyfikatorem URI autoryzacji i identyfikatorem zasobu. Należy również podać identyfikator dzierżawcy w nagłówku x-ms-tenant-id. Aby uzyskać więcej informacji, zobacz Uwierzytelnianie i autoryzacja w narzędziu do sprawdzania usługi Power Apps. Poniżej przedstawiono przykładowy nagłówek odpowiedzi zwrócony z żądania interfejsu API:

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

Po uzyskaniu tych informacji można użyć biblioteki uwierzytelniania Biblioteki uwierzytelniania Microsoft (MSAL) lub innego mechanizmu w celu uzyskania tokenu. Poniżej przedstawiono przykład takiego przepływu pracy przy użyciu języka C# i biblioteki 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();

Aby uzyskać pełny kod roboczy, zobacz przykładowy Szybki start interfejsu API sieci Web.

Po uzyskaniu tokenu zaleca się, aby dla kolejnych wywołań w ramach cyklu życia żądania podawać taki sam token. Jednak ze względów bezpieczeństwa więcej żądań może wymagać nowego tokenu.

Zabezpieczenia transportu

W celu szyfrowania najlepszego w klasie usługa sprawdzania obsługuje tylko komunikację przy użyciu zabezpieczeń Transport Layer Security (TLS) 1.2 lub większej. Wskazówki dotyczące sprawdzonych sposobów postępowania w zakresie architektury TLS znajdują się w artykule Najważniejsze wskazówki dotyczące zabezpieczeń warstwy transportu (TLS) w ramach platformy .NET Framework.

Format raportu

Wynik analizy rozwiązania to plik ZIP zawierający co najmniej jeden raport w standardowym formacie JSON. Format raportu jest tworzony na podstawie wyników analiz statycznych jako format wymiany wyników analizy statycznej (SARIF, Static Analysis Results Interchange Format). Dostępne są narzędzia umożliwiające wyświetlanie i posługiwanie się dokumentami programu SARIF. Więcej informacji można znaleźć w tej witrynie internetowej. W usłudze jest używana druga wersja dwie standardu OASIS.

Zobacz też