方法: Dataverse アクションまたは関数をコード アプリに追加する

このガイドでは、find-dataverse-api コマンドと add-dataverse-api CLI コマンドを使用して、dataverse 操作 (アクションと関数) を検出してPower Apps コード アプリに追加する方法について説明します。

前提条件

• npx power-apps init で初期化されたPower Apps コード アプリ
• @microsoft/power-apps 1.1.1以降のバージョンpackage.json
• 認証済み CLI セッション (必要に応じてnpx power-apps プロンプト)
• 使用する操作を含む Dataverse 環境へのアクセス

手順 1: 使用可能な操作を検出する

find-dataverse-apiを使用して、環境内の操作を名前で検索します。

npx power-apps find-dataverse-api --search "WhoAmI"

出力には、一致する操作とその種類 (Action または Function)、パラメーター、バインド エンティティ (存在する場合)、戻り値の型が一覧表示されます。

====================================================================================================
Dataverse Operations
====================================================================================================

  WhoAmI  (Function)
  Returns: mscrm.WhoAmIResponse

----------------------------------------------------------------------------------------------------
Total: 1 operation(s)
====================================================================================================

アクションを検索することもできます。 たとえば、 AddToQueue アクションを見つけるには、次のようにします。

npx power-apps find-dataverse-api --search "AddToQueue"

====================================================================================================
Dataverse Operations
====================================================================================================

  AddToQueue  (Action)
  Bound to: mscrm.queue
  Parameters:
    - Target: mscrm.crmbaseentity
    - SourceQueue?: mscrm.queue
    - QueueItemProperties?: mscrm.queueitem
  Returns: mscrm.AddToQueueResponse

----------------------------------------------------------------------------------------------------
Total: 1 operation(s)
====================================================================================================

生の JSON (スクリプトやコーディング エージェントに役立つ) を取得するには、 --json追加します。

npx power-apps find-dataverse-api --search "WhoAmI" --json

検索は、操作名において大文字と小文字を区別せずに部分文字列を一致させる方法です。

手順 2: アプリに操作を追加する

操作名を見つけたら、次のコマンドを実行します。

npx power-apps add-dataverse-api --api-name WhoAmI
# or using the short alias:
npx power-apps add-dataverse-api -n WhoAmI

コマンド:

1. 環境の Dataverse $metadataから操作定義をフェッチします。
2. <schemaPath>/dataverse/WhoAmI.Schema.jsonにスキーマ ファイルを書き込みます。
3. 操作のパラメーターまたは戻り値の型によって参照されるすべての Dataverse エンティティのスキーマ ファイルを保存します (既に存在する場合はスキップします)。
4. 更新 power.config.json:
   • まだ存在しない場合は、 databaseReferences["default.cds"] を追加します。
   • バインドされた操作の場合、バインド エンティティがまだ存在しない場合は、 dataSources に追加します。
5. 新しい操作を含めるようにdataSourcesInfo.tsを再生成します。
6. <codeGenPath>/generated/で TypeScript モデルとサービス クラスを生成します。

成功すると、次の情報が表示されます。

Dataverse API 'WhoAmI' added successfully.
Hint: Run 'npx power-apps run' to test locally, or 'npx power-apps push' to deploy.

手順 3: 生成されたサービスをアプリ コードで使用する

このコマンドは、操作用の専用の <ApiName>Service クラスを生成します。 たとえば、 WhoAmIを追加した後、生成されたサービス ディレクトリから WhoAmIService をインポートします。

import { WhoAmIService } from './generated/services/WhoAmIService';

サービスは、操作にちなんだ型指定された静的メソッドを公開します。 例えば次が挙げられます。

const result = await WhoAmIService.WhoAmI();
// result.value contains: { BusinessUnitId: string, UserId: string, OrganizationId: string }

AddToQueueなどのバインドされたアクションの場合、最初の引数は常に操作するレコードの GUID です。

import { AddToQueueService } from './generated/services/AddToQueueService';

const result = await AddToQueueService.AddToQueue(
  queueId,    // string (GUID of the destination queue)
  target,     // Record<string, unknown> (the activity to add)
  sourceQueue,         // Record<string, unknown> | undefined
  queueItemProperties  // Record<string, unknown> | undefined
);
// result.value contains: { QueueItemId: string }

パラメーターと戻り値の型は、Dataverse スキーマから取得されます。

• GUID パラメーターは、 stringとして型指定されます。
• Dataverse エンティティを参照する参照パラメーターは、 Record<string, unknown>として型指定されます。
• 戻り値を持たない操作では、 Promise<IOperationResult<void>>が生成されます。
• スカラー (たとえば、 boolean、 number) を返す操作は、対応する TypeScript 型で Promise<IOperationResult<T>> を生成します。
• 複合型またはエンティティを返す操作は、 Promise<IOperationResult<Record<string, unknown>>>を生成します。

同じ操作に対して再実行する

同じ--api-nameでadd-dataverse-apiを再実行することは安全で、同じ結果を保証する操作です（冪等性）。

• このコマンドは、Dataverse の最新の定義でスキーマ ファイルを上書きします。
• dataSourcesInfo.tsを再生成します。
• power.config.json内の重複するエントリが削除されます。重複は追加されません。
• 既に存在するエンティティ スキーマ ファイルは上書きされません。

このコマンドを使用して、環境内の更新後に操作の署名に対する変更を取得します。

作成または変更されたファイル

add-dataverse-api コマンドは、プロジェクト内の次のファイルを作成または更新します。

バインドされた操作とバインドされていない操作

バインドされた操作 は特定のエンティティ レコードに対して範囲が設定されています。 生成されたメソッドは、常に最初の引数として id: string パラメーターを受け取ります。これは、操作するレコードの GUID です。

非バインド操作 は環境全体で行われ、レコード ID は必要ありません。 それらのメソッドは、宣言されたパラメーターのみを受け取ります。

どちらの種類も同じコマンドで追加されます。CLI は操作の種類を自動的に検出します。

Troubleshooting

"操作が見つかりません" - 検索は部分文字列ベースであり、大文字と小文字は区別されませんが、操作名にのみ一致します。 短い用語または別の用語を試してみてください。 --jsonを使用して生の応答を確認します。

古い生成ファイル — 操作の名前を変更または削除しても、生成された古いファイルが残っている場合は、手動で削除し、 add-dataverse-api 再実行して再生成します。

pac code add-data-source はアクションまたは関数をスキップします— add-dataverse-api によって生成されたスキーマ ファイルは、PAC CLI で認識されない Microsoft.PowerApps/dataverseOperation 型を使用します。 Dataverse スキーマ フォルダーに操作スキーマ ファイルが存在する場合、 pac code add-data-source は次のようにスキップします。

Skipping unsupported Dataverse operation schema '...AddRecurrence.Schema.json':

この動作は、PAC CLI が Microsoft.PowerApps/dataverseOperation スキーマ型をサポートしていないため、失敗するのではなく、これらのファイルをスキップします。 PAC CLI では、Dataverse エンティティのデータ ソースまたはコネクタを表す他のスキーマ ファイルが引き続きサポートされており、 pac code add-data-sourceを使用して追加できます。

関連資料

Web API アクションの使用
Web API 関数の使用