Использование веб-API Power Apps Checker

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

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

Замечание

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

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

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

центр обработки данных Azure Имя География Базовый универсальный код ресурса (URI)
Публика Preview США unitedstatesfirstrelease.api.advisor.powerapps.com
Публика Рабочий США unitedstates.api.advisor.powerapps.com
Публика Рабочий Европа europe.api.advisor.powerapps.com
Публика Рабочий Азия asia.api.advisor.powerapps.com
Публика Рабочий Australia australia.api.advisor.powerapps.com
Публика Рабочий Япония japan.api.advisor.powerapps.com
Публика Рабочий India india.api.advisor.powerapps.com
Публика Рабочий Canada 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
Публика Рабочий Польша poland.api.advisor.powerapps.com
Публика Рабочий Италия italy.api.advisor.powerapps.com
Публика Рабочий Правительство США gov.api.advisor.powerapps.us
Публика Рабочий Правительство США 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. Для этой конечной точки требуется проверка подлинности.

Набор правил средства проверки решений

Набор правил средства проверки решений содержит набор эффективных правил, которые имеют ограниченные шансы на ложные срабатывания. Если анализ выполняется с существующим решением, рекомендуется начать с этого набора правил. Этот набор правил используется функцией средства проверки решений.

Набор правил сертификации Marketplace

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

Найдите идентификатор арендатора

Идентификатор вашего клиента необходим для взаимодействия с 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();

Полный рабочий код см. в веб-API Быстрое начало: пример.

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

Безопасность транспорта

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

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

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

См. также

Получение списка наборов правил
Получение списка правил
Отправка файла
Вызов задания анализа
Проверка состояния задания анализа

  • Last updated on