Използване уеб API на инструмента за проверка на Power Apps

Статия
05/01/2024

Уеб API на инструмент за проверка на Power Apps предоставя механизъм за стартиране на проверки за статичен анализ спрямо персонализации и разширения на платформата Microsoft Dataverse. Налично е за създатели и разработчици за изпълнение на проверка с богат статичен анализ на решенията си срещу набор от правила за най-добри практики и бързо да разпознаете тези проблематични модели. Услугата предоставя логиката за функция за проверка на решение в портал на създателите на Power Apps и е включена като част от автоматизацията за заявления, изпратени до AppSource. Взаимодействието с услугата директно по този начин позволява анализ на решения, които са включени като част от локален (всички поддържани версии) и онлайн среди.

За информация относно използването на услугата за проверка от кода на PowerShell вижте Работа с решения с помощта на PowerShell.

Бележка

Използване на инструмента за проверка на Power Apps не гарантира, че импортирането на решение ще бъде успешно. Проверките на статичния анализ, извършени спрямо решението, не знаят конфигурираното състояние на средата на местоназначението и успехът на импортирането може да зависи от други решения или конфигурации в средата.

Алтернативни подходи

Преди да прочетете подробностите за това как да взаимодействате на най-ниското ниво с уеб API, помислете за използването на нашия модул PowerShell, Microsoft.PowerApps. Checker.PowerShell, вместо това. Това е напълно поддържан инструмент, който е наличен в галерията на PowerShell. Настоящото ограничение е, че изисква Windows PowerShell. Ако не можете да изпълните това изискване, тогава взаимодействието с API директно е най-добрият подход.

Първи стъпки

Важно е да се отбележи, че анализът на решението може да доведе до дълъг процес. Обикновено може да отнеме шестдесет (60) секунди до повече от пет (5) минути в зависимост от различни фактори, като брой, размер и сложност на персонализациите и кода. Потокът на анализа е многостъпален и асинхронен, започващ с иницииране на задача за анализ с API на състоянието, използван за заявка за завършване на заданието. Примерен поток за анализ е следният:

Получете маркер OAuth
Качване на обаждане (за всеки файл паралелно)
Анализ на повиквания (инициира задачата за анализ)
Състояние на обаждането до завършване (циклично с пауза между разговорите, докато не се сигнализира края или се спазват праговете)
Изтеглете резултатите от предоставения SAS URI

Няколко варианта са:

Включете търсене на набор от правила или правила като предварителна стъпка. Въпреки това, ще бъде малко по-бързо да се премине в конфигуриран или твърдо кодиран набор от правила за правила. Препоръчва се да използвате набор от правила, който отговаря на вашите нужди.
Можете да изберете да не използвате механизма за качване (вижте качването за ограничения).

Трябва да определите следните изисквания:

Коя география?
Коя версия?
Кои набори от правила и правила?
Какъв е идентификационният ви номер на клиента?

Вижте следните статии за документация относно отделните API:

Извличане на списъка с набори от правила
Извличане на списъка с правила
Качване на файл
Извикване на анализ
Проверка на състоянието на анализ

Определете география

Когато взаимодействате с Power Apps услугата за проверка, файловете се съхраняват временно в Azure заедно с генерираните отчети. Използвайки специфичен API за география, можете да контролирате къде се съхраняват данните. Заявките до географска крайна точка се насочват към регионален екземпляр въз основа на най-добрата производителност (латентност към заявителя). След като заявката влезе в регионален екземпляр на услугата, цялата обработка и постоянните данни остават в конкретния регион. Някои отговори на API връщат URL адреси на регионални екземпляри за последващи искания, след като задачата за анализ бъде пренасочена към конкретен регион. Всяка география може да има различна версия на услугата, разположена във всеки един момент. Използването на различни версии на услугата се дължи на многоетапния процес на безопасно внедряване, който осигурява пълна съвместимост на версиите. По този начин, една и съща география трябва да се използва за всяко API извикване в жизнения цикъл на анализа и може да намали общото време за изпълнение, тъй като данните може да не трябва да се движат толкова далеч над проводника. По-долу са посочени наличните географии:

Център за данни на Azure	Име	География	Основен URI
Публична	Преглеждане	САЩ	unitedstatesfirstrelease.api.advisor.powerapps.com
Публична	Производствен	САЩ	unitedstates.api.advisor.powerapps.com
Публична	Производствен	Европа	europe.api.advisor.powerapps.com
Публична	Производствен	Азия	asia.api.advisor.powerapps.com
Публична	Производствен	Австралия	australia.api.advisor.powerapps.com
Публична	Производствен	Япония	japan.api.advisor.powerapps.com
Публична	Производствен	Индия	india.api.advisor.powerapps.com
Публична	Производствен	Канада	canada.api.advisor.powerapps.com
Публична	Производствен	Южна Америка	southamerica.api.advisor.powerapps.com
Публична	Производствен	Обединеното кралство	unitedkingdom.api.advisor.powerapps.com
Публична	Производствен	Франция	france.api.advisor.powerapps.com
Публична	Продукция	Германия	germany.api.advisor.powerapps.com
Публична	Продукция	Обединени Арабски Емирства	unitedarabemirates.api.advisor.powerapps.com
Публична	Продукция	Швейцария	switzerland.api.advisor.powerapps.com
Публична	Продукция	Южна Африка	southafrica.api.advisor.powerapps.com
Публична	Продукция	Южна Корея	korea.api.advisor.powerapps.com
Публична	Продукция	Норвегия	norway.api.advisor.powerapps.com
Публична	Продукция	Сингапур	singapore.api.advisor.powerapps.com
Публична	Продукция	Швеция	sweden.api.advisor.powerapps.com
Публична	Продукция	US Government	gov.api.advisor.powerapps.us
Публична	Производствен	US Government L4	high.api.advisor.powerapps.us
Публична	Производствен	US Government L5 (DOD)	mil.api.advisor.appsplatform.us
Публична	Производствен	Управлявано в Китай от 21Vianet	china.api.advisor.powerapps.cn

Бележка

Можете да изберете да използвате географията на визуализацията, за да включите най-новите функции и промени по-рано. Имайте предвид обаче, че визуализацията използва само региони на Azure на САЩ.

Създаване на версии

Въпреки че не е задължително, препоръчително е да включите параметъра на низ на заявката за api-версия с желаната версия на API. Текущата версия на API е 2.0 за правила и правила и 1.0 за всички други заявки. Например, следният набор от правила е HTTP заявка, указваща да се използва версията на API 2.0:

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

Ако не е предоставена, най-новата версия на API се използва по подразбиране. Препоръчва се използването на изричен номер на версията, тъй като версията се увеличава, ако се въведат промени за прекъсване. Ако номерът на версията е посочен в заявка, ще се поддържа поддръжка за съвместимост с по-късна (по-голяма) версия.

Набори от правила и правила

Инструментът за проверка на Power Apps изисква списък с правила при изпълнение. Тези правила могат да бъдат предоставени под формата на индивидуални правила или групи от правила, посочени като набор от правила. Набор от правила е удобен начин да се определи група от правила, вместо да се налага да се определят всяко правило поотделно. Например функцията за проверка на решения използва набор от правила с име Инструмент за проверка на решения. Тъй като се добавят или премахват нови правила, услугата включва тези промени автоматично, без да изисква промяна от консумиращото приложение. Ако искате списъкът с правила да не се променя автоматично, както е описано по-горе, тогава правилата могат да бъдат определени индивидуално. Наборите от правила могат да имат едно или повече правила без ограничение. Правилото може да бъде в никой или в множество набори от правила. Можете да получите списък с всички набори от правила, като се обадите на API както следва: [Geographical URL]/api/ruleset. Тази крайна точка сега изисква удостоверяване.

Набор от правила за инструмента за проверка на решение

Наборът от правила за проверка на решения съдържа набор от въздействащи правила, които имат ограничени шансове за фалшиви положителни резултати. Ако изпълнявате анализ спрямо съществуващо решение, препоръчително е да започнете с този набор от правила. Този набор от правила се използва от функцията за проверка на решения. ...

Набор от правила за сертифициране на AppSource

При публикуване на приложения на AppSource, трябва да получите сертификата си за кандидатстване. Приложения, публикувани на AppSource трябва да отговарят на висок стандарт за качество. Наборът AppSource от правила за сертифициране съдържа правилата, които са част от набора правила за проверка на решения, плюс други правила, за да се гарантира, че в магазина се публикуват само висококачествени приложения. Някои от правилата за сертифициране са по-податливи на AppSource фалшиви положителни резултати и може да изискват повече внимание за разрешаване.

Намерете идентификационния си номер на клиента

Идентификационният номер на вашия клиент е необходим за взаимодействие с API-тата, които изискват означение. Вижте тази статия за подробности как да получите идентификационния номер на клиента. Можете също да използвате командите PowerShell за извличане на идентификатора на клиента. Следващият пример прилага кратките команди в модула AzureAD.

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

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

Идентификационният номер на клиента е стойността на свойството ObjectId, която е върната от Get-AzureADTenantDetail. Можете да го видите и след като влезете с помощта на командлета Connect-AzureAD в изхода на командлета. В този случай тя ще бъде назована TenantId.

Удостоверяване и упълномощаване

Заявките за правила и набори от правила не изискват маркер OAuth, но всички други API изискват маркера. API-ите поддържат откриване на авторизация, като се обаждат на някой от API, които изискват означение. Отговорът е неупълномощен HTTP код на състоянието на 401 с WWW-Authenticate заглавка, URI за упълномощаване и ИД на ресурса. Трябва също да предоставите идентификационния си номер на клиента в заглавката x-ms-tenant-id. Вижте Проверка на Power Apps удостоверяването и упълномощаването за повече информация. По-долу е даден пример за заглавката на отговора, върната от искане за API:

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

След като разполагате с тази информация, можете да изберете да използвате библиотеката за удостоверяване на Microsoft (MSAL) или някакъв друг механизъм за придобиване на маркера. По-долу е даден пример за това как това може да се направи с помощта на C# и 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();

За пълния работен код вижте примера за бърз старт на уеб API.

След като сте придобили маркера, препоръчително е да предоставите същия маркер на следващите повиквания в жизнения цикъл на заявката. Въпреки това, повече искания могат да гарантират придобиването на нов токен от съображения за сигурност.

Транспортна сигурност

За най-доброто в класа шифроване услугата за проверка поддържа само комуникации, използващи защита на транспортния слой (TLS) 1.2 и по-нова. За ръководство относно.NET най-добрите практики около TLS, вижте Най-добрите практики за сигурност на транспортния слой (TLS) с .NET Framework.

Формат на отчет

Резултатът от анализа на решението е zip файл, съдържащ един или повече доклади в стандартизиран JSON формат. Форматът на отчета се основава на резултатите от статичния анализ, наричани формат за обмен на резултати от статичен анализ (SARIF). Има инструменти за преглед и взаимодействие с документи на SARIF. Вижте този уеб сайт за подробности. Услугата използва версия две на стандарта OASIS.

Споделяне чрез