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

[アーティクル]
10/16/2024

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

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

注意

Power Apps チェッカーの使用は、ソリューションのインポートが成功することを保証しません。ソリューションに対して実行される静的分析チェックは、宛先環境の構成済み状態を認識しておらず、インポートの成功は、環境内の他のソリューションまたは構成に依存している可能性があります。

代替アプローチ

Web APIを最も低いレベルで操作する方法の詳細を読む前に、代わりにPowerShellモジュール Microsoft.PowerApps.Checker.PowerShellを使用することを検討してください。これは PowerShell Gallery で完全にサポートされているツールです。現在の制限では、 Windows PowerShell を必要とします。この要件に合わない場合は、API と直接やり取りすることが最善の方法です。

開始する

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

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

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

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

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

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

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

ルールセットのリストを取得する
 ルールのリストを取得する
 ファイルをアップロードする
 分析を呼び出す
 分析ステータスを確認する

地域条件の決定

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

Azure Datacenter	Name	地域	基本 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
Public	運用	ドイツ	germany.api.advisor.powerapps.com
Public	運用	アラブ首長国連邦	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
パブリック	運用	米国政府	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

Note

最新機能と変更を組み込む先にプレビュー、地域条件を使用することを選択できます。ただし、プレビューの米国 Azure 領域のみを使用して、入力します。

バージョン管理

必須ではない場合、目的の 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 を呼び出すことですべてのルールセットの一覧を次のように取得できます: [Geographical URL]/api/ruleset。このエンドポイントには認証が必要になりました。

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

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

AppSource 認証のルールセット

AppSource 上でアプリケーションを公開する場合は、アプリケーションは認証を取得する必要があります。 AppSource に公開されるアプリケーションは、高い品質基準を満たす必要があります。 AppSource 認証ルールセットには、ソリューションチェッカールールセットの一部であるルールに加え、高品質のアプリケーションのみがストアで公開されることを保証するその他のルールセットが含まれます。 AppSource 認証ルールの一部には、誤検知を起こしやすく、解決にさらに注意が必要な場合があります。

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

認証および承認

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

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

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

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

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

レポートの形式

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

参照

ルールセットのリストを取得する
 ルールのリストを取得する
 ファイルをアップロードする
 分析を呼び出す
 分析ステータスを確認する

次の方法で共有

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

代替アプローチ

開始する

地域条件の決定

バージョン管理

ルールセットとルール

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

AppSource 認証のルールセット

テナント ID を検索します

認証および承認

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

レポートの形式

参照

フィードバック

その他のリソース

次の方法で共有

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

代替アプローチ

開始する

地域条件の決定

バージョン管理

ルールセットとルール

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

AppSource 認証のルールセット

テナント ID を検索します

認証および承認

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

レポートの形式

参照

フィードバック

その他のリソース

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

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