Використання веб-API засобу перевірки Power Apps

Засіб перевірки веб-API Power Apps надає механізм для виконання статичного аналізу настроювань і розширень платформи Microsoft Dataverse. Розробники можуть використовувати його, щоб виконувати широкий спектр перевірок статичного аналізу своїх рішень та швидко визначати проблемні схеми, маючи для цього набір кращих рекомендацій. Ця служба містить логіку для функції перевірки рішення на порталі розробника Power Apps і включається як частина автоматизації для програм, надісланих до AppSource. Безпосередня взаємодія зі службою таким чином дає змогу аналізувати рішення, які входять до складу локального (усі підтримувані версії) та онлайн-середовищ.

Для отримання відомостей про використання служби перевірки з коду PowerShell зверніться до розділу Робота з рішеннями за допомогою PowerShell.

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

Перш ніж читати подробиці про те, як взаємодіяти на найнижчому рівні з веб-API, розгляньте можливість використання нашого модуля PowerShell, Microsoft.PowerApps Checker.PowerShell, натомість. Це повністю підтримуваний інструмент, доступний у Галереї PowerShell. Поточне обмеження полягає в тому, що для нього потрібна програма Windows PowerShell. Якщо ви не можете виконати цю вимогу, то найкращим підходом є безпосередня взаємодія з API.

Початок роботи

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

1. Отримати OAuth токен
2. Передавання виклику (для кожного файлу паралельно)
3. Аналіз викликів (запуск завдання аналізу)
4. Стан виклику до завершення (циклічно, з паузою між викликами до сповіщення про завершення або досягнення порогового значення)
5. Завантаження результатів з наданого URI SAS

Кілька варіантів наведено нижче.

• Додайте підстановку набору правил або правила як попереднього кроку. Але буде трохи швидше передати ідентифікатор налаштованого або жорстко кодованого набору правил. Рекомендовано використовувати набір правил, який відповідає вашим потребам.
• Можна не використовувати механізм передавання (див. розділ про передавання, щоб дізнатися про обмеження).

Потрібно визначити такі вимоги:

• Яка географія?
• Яка версія?
• Які норми і правила?
• Який у вас ідентифікатор орендаря?

Зверніться до наступних статей для отримання документації щодо окремих API:

Отримання списку наборів правил
Отримайте список правил
Завантажити файл
Аналіз виклику
Перевірка статусу аналізу

Визначення географічного регіону

Коли ви взаємодієте зі службою Power Apps перевірки, файли тимчасово зберігаються в Azure разом із створеними звітами. За допомогою API для певного географічного регіону можна керувати тим, де зберігаються дані. Запити щодо кінцевої географічної точки спрямовуються до регіональної інсталяції, виходячи з критерію найкращої продуктивності (затримки для запитувача). Після надходження запиту до регіональної інсталяції служби вся обробка та збережені дані залишаються в цьому конкретному регіоні. Деякі відповіді API повертають URL-адреси регіональних екземплярів для наступних запитів, як тільки завдання аналізу спрямовується до певного регіону. У кожному регіоні може бути розгорнута різна версія служби в будь-який момент часу. Використання різних версій сервісу обумовлено багатоетапним процесом безпечного розгортання, що забезпечує повну сумісність версій. Отже, для кожного виклику API в життєвому циклі аналізу має використовуватися одне й те саме географічне розташування. Окрім цього, це може скоротити загальний час виконання, оскільки це може запобігти пересиланню даних на далекі відстані дротовими з’єднаннями. Нижче наведено доступні географічні регіони.

Керування версіями

Хоча це не обов’язково, рекомендується включити параметр рядка запиту api-version із бажаною версією 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 Автентифікація та авторизація Checker для отримання додаткової інформації. Нижче наведено приклад заголовка відповіді, що повертається із запиту API:

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

Отримавши ці відомості, ви можете використовувати бібліотеку Microsoft Authentication Library (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();

Повний робочий код можна знайти у зразку QuickStart для веб-API.

Після того, як ви придбали токен, рекомендується надати той самий токен наступним дзвінкам протягом життєвого циклу запиту. Однак більша кількість запитів може вимагати придбання нового токена з міркувань безпеки.

Безпека транспортування

Для найкращого у своєму класі шифрування служба перевірки підтримує зв’язок лише з використанням Transport Layer Security (TLS) 1.2 або вище. Для рекомендацій з використання кращих методів .NET з TLS див. Рекомендації з використання протоколу Transport Layer Security (TLS) з .NET Framework.

Формат звіту

Результатом аналізу рішення є ZIP-файл, що містить один або кілька звітів у стандартизованому форматі JSON. Формат звіту базується на результатах статичного аналізу, який називається форматом Static Analysis Results Interchange Format (SARIF). Існують інструменти, доступні для перегляду та взаємодії з документами SARIF. Додаткові відомості див. на цьому веб-сайті. У сервісі використовується друга версія стандарту OASIS.

Див. також

Отримання списку наборів правил
Отримайте список правил
Завантажити файл
Аналіз виклику
Перевірка статусу аналізу