Power Apps チェッカー Web API を使用する
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 では、渡すのが若干速くなります。 ニーズに合ったルールセットを使用することをお勧めします。
- アップロードメカニズムを使用しないことを選択できます (制限についてはアップロードを参照してください)。
次の要件を決定する必要があります:
個々の 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 と名づけられます。
認証および承認
ルールおよびルールセットのクエリは、OAuth トークンを必要としませんが、他のすべての API は、トークンが必要です。 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 を使用します。
参照
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示