Power Apps チェッカー Web API を使用する

Power Apps チェッカー Web API には、Microsoft Dataverse プラットフォームへのカスタマイズと拡張機能に対して静的分析チェックを実行するメカニズムが用意されています。 作成者や開発者は一連のベスト プラクティス ルールに対してソリューションで機能豊富なスタティック分析チェックを実行し、これらの問題となるパターンを識別できます。 このサービスは、Power Apps maker portal のソリューション チェッカー機能のロジックを提供し、Marketplace アプリケーションの自動化の一部として含まれています。 この方式でサービスと直接やり取りすることで、設置型 (すべてのサポートされているバージョン) と Online 環境の一部として含まれているソリューションの分析をおこなうことができます。

PowerShell コードからのチェッカー サービスの使用に関する詳細については、PowerShell を使用したソリューションに関する作業 を参照してください。

代替アプローチ

Web API で下位レベルで対話する方法の詳細に関して読見勧める前に、PowerShell モジュール、Microsoft.PowerApps.Checker.PowerShell を代わりに使用することを検討してください。 PowerShell ギャラリーで使用できる完全にサポートされているツールです。 現在の制限として、Windows PowerShellが必要です。 この要件に合わない場合は、API と直接やり取りすることが最善の方法です。

開始する

ソリューション分析は、プロセスが長くなる可能性があることに注意することが重要です。 カスタマイズとコードの数値、サイズ、複雑性など、さまざまな要因によって、通常 60秒 から 5 分強がかかる場合があります。 分析フローはジョブを完了するために使用されるステータス API でジョブ分析の起動を開始する複数かつ非同期のマルチステップです。 分析のためのフロー例は次のとおりです:

1. OAuth トークンの取得
2. アップロードの呼び出し (各ファイル同時に)
3. 分析の呼び出し (分析ジョブの起動)
4. 完了するまでの呼び出し状況 (完了が通知される、またはしきい値が満たされるまで、呼び出し間に一時停止を繰り返す)
5. 提供された SAS URL から結果をダウンロードします。

いくつかの種類は次のとおりです:

• 前手順とししてのルールセットまたはルールの参照を含みます。 しかし、構成された、またはコーディングされたルールセット ID では、渡すのが若干速くなります。 ニーズに合ったルールセットを使用することをお勧めします。
• アップロードメカニズムを使用しないことを選択できます (制限についてはアップロードを参照してください)。

次の要件を決定する必要があります:

• どの地域ですか
• どのバージョンですか
• どのルールセットとルールですか
• テナント ID は何ですか。

個々の API に関するドキュメントについては、以下の記事を参照してください:

ルールセットの一覧の取得
ルールの一覧の取得
ファイルのアップロード
分析の呼び出し
分析状態の確認

地域条件の決定

Power Apps チェッカー サービスを操作すると、生成されたレポートと共にファイルがAzureに一時的に格納されます。 地域固有の API を使用して、データをのどこに保存する方法を制御できます。 地域エンドポイントへのリクエストは、最高のパフォーマンス (リクエスターへのレイテンシー) に基づいてリージョナル インスタンスにルーティングされます。 リクエストがリージョナル サービス インスタンスに入ると、すべての処理データと永続データはその特定のリージョン内に残ります。 特定の API 応答は、分析ジョブが特定のリージョンにルーティングされると、後続のリクエストに対してリージョン インスタンスの URL を返します。 各地域では、特定の時点で異なるバージョンのサービスが展開されている可能性があります。 異なるサービス バージョンの使用は、完全なバージョンの互換性を保証するマルチステージの安全な展開プロセスによるものです。 したがって、分析ライフサイクルの各 API 呼び出しに同じ地域を使用する必要があり、データがネットワーク上を移動する必要がないため、全体的な実行時間が短縮される可能性があります。 使用可能な地域は次のとおりです:

バージョン管理

必須ではない場合、目的の API バージョンに api-version クエリ文字列パラメーターを含めることをお勧めします。 現在の API バージョンは、ルールセットとルールについては 2.0、その他すべての要求については 1.0 です。 たとえば、次のルールセットは、2.0 API バージョンの使用を指定する HTTP 要求です:

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

指定しない場合、最新バージョンの API が既定で使用されます。 破壊的変更が加えられた場合、バージョンが増えることから、明示的なバージョン番号を使用することをお勧めします。 バージョン番号が要求に指定されている場合は、最新 (数字が大きい方) のバージョンで下位互換性サポートが維持されます。

ルールセットとルール

Power Apps チェッカーでは、実行時にルールの一覧が必要です。 このルールでは、個々のルールまたは [ルールセット]と呼ばれるグループ化形式で設定できます。 ルールセットは各ルールをここに指定する代わりに、グループ化されたルールを指定する便利な方法です。 たとえば、ソリューションのチェッカー機能は、いう [ソリューションのチェッカー]のrulesetを使用します。 新しいルールが追加または削除されると、サービスはこれらの変更を消費アプリケーションで変更することなく自動的に含めます。 ルールの一覧を上記のように自動的に変更しないことが必要な場合は、ルールは個別に指定できます。 ルールセットは制限なしで1つ以上のルールを持つことができます。 ルールには、ルールセットなしや複数のルールセットにすることができます。 API を呼び出すことですべてのルールセットの一覧を次のように取得できます: 。 このエンドポイントには認証が必要になりました。

ソリューション チェッカー ルールセット

ソリューション チェッカー ルールセットには偽陽性の制限された可能性を持つ一連のインパクトが強いルールが含まれています。 既存のソリューションに対して分析を実行している場合、このルールセットから開始することをお勧めします。 このルールセットは ソリューション チェッカー機能 によって使用されます。

Marketplace 認定ルールセット

Marketplace でアプリケーションを発行する場合は、アプリケーションの認定を受ける必要があります。 Marketplace で公開されるアプリケーション は、高品質の標準を満たす必要があります。 Marketplace 認定ルールセットには、ソリューション チェッカールールセットの一部であるルールと、高品質のアプリケーションのみがストアに公開されるようにするためのその他のルールが含まれています。 一部の Marketplace 認定規則では、誤検知が発生しやすく、解決にさらに注意が必要になる場合があります。

テナント ID を検索します

テナントの ID が、トークンを必要とする API と対話するために必要です。 テナントIDを取得する方法の詳細については、この記事 を参照してください。 テナント ID を取得するために PowerShell コマンドを使用することもできます。 次の例では、AzureAD モジュール のコマンドレットを適用します。

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

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

テナント ID は、 から返される プロパティの値です。 コマンドレット出力の Connect-AzureAD コマンドレットを使用してログインした後、表示されるばあいもあります。 この場合は と名づけられます。

認証および承認

ルールおよびルールセットのクエリは、OAuth トークンを必要としませんが、他のすべての API は、トークンが必要です。 API はトークンが必要ないかなる API の呼び出しによる認証検出をサポートします。 応答は、WWW-Authenticate ヘッダー、認証 URI、およびリソース ID を持つ 401 の非認証 HTTP ステータス コードになります。 また、 ヘッダーでのテナント 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 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();

完全な作業コードについては Web API QuickStart のサンプル を参照してください。

一度トークンを取得すれば、要求ライフサイクルで以降の呼び出しをするために同じトークンを提供することが推奨されています。 ただし、より多くの要求は、セキュリティ上の理由から新しいトークンを取得することを必要とする場合があります。

トランスポート セキュリティ

クラス最高レベルの暗号化では、チェッカー サービスは Transport Layer Security (TLS) 1.2 以降を使用した通信のみをサポートします。 TLS に関するベスト プラクティス.NETガイダンスについては、.NET Framework での Transport Layer Security (TLS) のベスト プラクティスを参照してください。

レポートの形式

ソリューション分析の結果は、標準化された JSON 形式で 1 つ以上のレポートを含む zip ファイルです。 レポート形式は、スタティック分析結果相互交換形式 (SARIF) として参照されるスタティック分析結果に基づいています。 SARIF 文書の表示とやり取りに使用可能なツールがあります。 詳細はこの Webサイト を参照します。 サービスは OASIS の標準 のバージョン 2 を使用します。

関連項目

ルールセットの一覧の取得
ルールの一覧の取得
ファイルのアップロード
分析の呼び出し
分析状態の確認