Использование веб-API средства проверки Power Apps

Статья
01/25/2024

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

Для получения информации об использовании службы средства проверки из кода PowerShell см. раздел Работа с решениями с помощью PowerShell.

Заметка

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

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

Прежде чем читать подробности о том, как на самом низком уровне взаимодействовать с веб-API, рассмотрите возможность использования вместо этого нашего модуля Microsoft.PowerApps.Checker.PowerShell. Это полностью поддерживаемый инструмент, который доступен в Галерее PowerShell. Текущее ограничение заключается в том, что для этого требуется Windows PowerShell. Если вы не в состоянии удовлетворить это требование, то взаимодействие с API-интерфейсом напрямую является лучшим подходом.

Начало работы

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

Получение токена OAuth
Отправка вызова (для каждого файла параллельно)
Анализ вызовов (инициирует задание анализа)
Состояние вызова до завершения (цикл с паузой между вызовами до сигнала окончания или достижения пороговых значений)
Загрузка результатов с предоставленного URI-адреса SAS

Несколько вариаций:

Включите подстановку набора правил или правил в качестве предварительного шага. Однако было бы немного быстрее передать настроенный или заданный в коде идентификатор набора правил. Рекомендуется использовать набор правил, который соответствует вашим потребностям.
Вы можете отказаться от использования механизма отправки (см. ограничения на отправку).

Вам нужно будет определить следующие требования:

Какая география?
Какая версия?
Какие наборы правил и правила?
Какой ваш идентификатор клиента?

См. следующие статьи с документацией по отдельным 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
Открытая	Производственный экземпляр	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-version в желаемую версию API-интерфейса. Текущая версия API — версия 2.0 для наборов правил и правил и 1.0 для всех остальных запросов. Например, следующий набор правил – это HTTP-запрос, указывающий на использование версии 2.0 API-интерфейса:

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/"

Когда у вас есть эта информация, вы можете использовать библиотеку проверки подлинности Майкрософт (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 Быстрое начало: пример.

После получения токена рекомендуется предоставлять этот же токен для последующих вызовов в жизненном цикле запроса. Однако другие запросы, вероятно, потребуют получения нового токена по соображениям безопасности.

Транспортная безопасность

Для лучшего в своем классе шифрования служба средства проверки поддерживает связь только с использованием протокола Transport Layer Security (TLS) 1.2 и выше. Руководство по рекомендациям .NET в отношении TLS см. в разделе Рекомендации по использованию протокола Transport Layer Security (TLS) с платформой .NET Framework.

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

Результатом анализа решения является ZIP-файл, содержащий один или несколько отчетов в стандартном формате JSON. Формат отчета основан на результатах статического анализа, называемого форматом обмена результатами статического анализа (Static Analysis Results Interchange Format, SARIF). Есть инструменты, доступные для просмотра и взаимодействия с документами SARIF. Подробнее см. на этом веб-сайте. Служба использует вторую версию стандарта OASIS.