power-automate

Power Automate クラウドフロー構築スキル

クラウドフロー開発は Flow agent MCP SERVER（FlowAgent）を第一選択とする。 MCP が利用できない環境では Dataverse Web API（workflow テーブル）経由のフォールバックを使う。

推奨: Flow agent MCP SERVER を使う（第一選択）

FlowAgent MCP SERVER を使うと、VS Code の GitHub Copilot Chat（エージェントモード）からフローを自然言語で構築・編集・デバッグできる。

★ FlowAgent MCP サーバー本体（server/mcp.mjs）は Claude Code / GitHub Copilot CLI 用の プラグインマーケットプレイス（microsoft/power-platform-skills）で配布されているが、 VS Code の GitHub Copilot Chat は /plugin marketplace add コマンドや Claude 形式の .mcp.json（mcpServers キー）を解釈できない。VS Code は独自の MCP クライアントを持ち、 ワークスペース直下の .vscode/mcp.json（servers キー + type: "stdio"）を読む。 そのため本スキルでは microsoft/power-platform-skills リポジトリを git スパースチェックアウトで 直接取得し、VS Code 形式で登録する（プラグインマーケットプレイスは経由しない）。

1. 前提

• Node.js 20+（FlowAgent v3.0.0 以降は MCP SDK v2 のため Node.js 18 では起動できない）
• git（microsoft/power-platform-skills の plugins/power-automate を取得するために使用）
• Azure CLI（az login — MCP サーバー自身の認証に必要。auth_helper.py とは別の資格情報ストア）

2. 認証 + .vscode/mcp.json 生成（auth_helper を使用）

.env に DATAVERSE_URL / SOLUTION_NAME を設定してからスクリプトを実行する。 スクリプトが行うこと:

python .github/skills/power-automate/scripts/setup_flow_mcp.py

内容確認だけしたい場合:

python .github/skills/power-automate/scripts/setup_flow_mcp.py --dry-run

.vscode/mcp.json は環境依存パスを含むためコミットしない（.vscode/* は標準 .gitignore で除外済み）。

3. VS Code に認識させる

1. コマンドパレット → MCP: List Servers で FlowAgent が表示されるか確認（表示されない場合はウィンドウをリロード）
2. FlowAgent を Start
3. GitHub Copilot Chat（エージェントモード）で自然言語で指示する

4. フローを開発する

5. ソリューションへの追加・有効化

MCP で作成したフローをソリューションに追加するには manage-flows スキルで solutionUniqueName を指定するか、以下のスクリプトで補完する。 第 1 引数にフロー ID を直接渡す（--workflow-id のようなオプション形式ではない）。

python .github/skills/power-automate/scripts/add_flow_to_solution.py <flow-id>

ソリューションに追加した直後の publish_flow（有効化）が CannotStartUnpublishedSolutionFlow で失敗することがある。この場合の原因切り分けと 解消手順、および run_flow によるテスト実行時の制約は references/flow-agent-mcp.md の該当節を参照。

詳細な設定・トラブルシュートは references/flow-agent-mcp.md を参照。

コネクター接続は 接続作成標準 に従う。 Power Apps API で Connected 接続を先に検索し、存在しない場合だけ VS Code 統合ブラウザで 接続パラメーターを自動入力する。ユーザー操作は OAuth のアカウント選択・同意に限定し、 Connected 確認後の接続参照・フロー作成・有効化・テストは API で行う。 OAuth 完了後は子ページを自動で閉じる。自動クローズできない場合は Connected を API で確認してから、 その画面を閉じてよいことをユーザーへ明示する。

HTTP with Microsoft Entra ID の内部 API、要求本文、権限の実測値は 非公開接続 API の実測結果 を参照する。

API アプローチ（Flow agent MCP が使えない場合）

以下は MCP サーバーが利用できない環境向けの フォールバック手順。 Python スクリプトで Dataverse Web API を直接操作する。

定義を送信する前に scripts/validate_flow_definition.py の assert_base64_content_contract() と assert_flat_dataverse_item_parameters() を必ず実行する。 Dataverse の CreateRecord / UpdateRecord は列値を item/<列名> のフラットなキーで渡し、 item オブジェクトへ入れ子にしない。JSON の contentBase64 に実行時の本文を渡す場合は @base64(...) で明示的にエンコードし、コネクタ出力型の違いによる実行時失敗をデプロイ前に止める。 Dataverse アクションを含む場合は、参照列をメタデータ API で取得し、 assert_required_dataverse_columns() で列の存在を確認してから既存フローを変更する。 Lookup を @odata.bind で書き込む場合は ManyToOneRelationships から ReferencingEntityNavigationPropertyName を取得し、require_navigation_property() で検証する。 Lookup属性の論理名や表示名からナビゲーションプロパティ名を推測しない。

核心原則: 接続参照（Connection Reference）が有効化成功の鍵

重要な既知制約（2026-05 検証済み）

フロー有効化で AzureResourceManagerRequestFailed が出る根本原因:
  → 接続参照なしで接続 ID を直接埋め込んだ場合、authenticatedUserObjectId が不足する

解決策: 接続参照テーブルに正しい接続を紐づけてから、フロー定義で参照する
  → 100% API 有効化に成功する

❌ 旧パターン（接続 ID 直接指定 → 有効化失敗のリスクあり）:
  "connectionReferences": {
      "shared_commondataserviceforapps": {
          "connectionName": "some-connection-id",
          "source": "Embedded",
          ...
      }
  }

✅ 新パターン（接続参照経由 → 100% 有効化成功）:
  "connectionReferences": {
      "shared_commondataserviceforapps": {
          "runtimeSource": "embedded",
          "connection": {
              "connectionReferenceLogicalName": "prefix_connref_logical_name"
          },
          "api": {"name": "shared_commondataserviceforapps"}
      }
  }

前提: 設計フェーズ完了後にデプロイに入る（必須）

フローをデプロイする前に、フロー設計をユーザーに提示し承認を得ていること。

設計提示時に含める内容:

事前確認（会話の最初に 1 回だけ）

本スキルの利用が確定したら、standard の共通契約に加え、 1 回の AskUserQuestion で次をまとめて確認する。

接続所有者の個人アカウント依存を避け、可能ならサービス主体または運用用アカウントを使う。 ライセンス、connection reference、書き込み対象の権限が未確認ならフローを有効化しない。

フロー: 設計提示 → ユーザー承認 → デプロイスクリプト実行

大前提: 一つのソリューション内に開発

Dataverse テーブル・Code Apps・Power Automate フロー・Copilot Studio エージェントは すべて同一のソリューション内 に含める。

SOLUTION_NAME=ProjectName  ← .env で定義。全フェーズで同じ値を使用
PUBLISHER_PREFIX=prefix    ← ソリューション発行者の prefix

• フロー作成時は MSCRM.SolutionUniqueName ヘッダー必須
• 接続参照もソリューション内に作成（MSCRM.SolutionUniqueName ヘッダー）

認証: Python スクリプトの認証は standard スキルの auth_helper.py を使用。 from auth_helper import get_token, get_session, api_get, api_post, api_patch, api_delete, retry_metadata, DATAVERSE_URL で利用する。

• ソリューション外のフローは「マイフロー」に入り、ALM 管理できない

必須要件

認証スコープが異なる【必須】

Flow API:      https://service.flow.microsoft.com/.default   ← 環境 ID 解決・/start
PowerApps API: https://service.powerapps.com/.default        ← 接続検索用
Graph API:     https://graph.microsoft.com/.default          ← ユーザー情報用
Dataverse API: https://{org}.crm7.dynamics.com/.default      ← workflow テーブル操作・接続参照作成

接続は Connected 状態で環境内に必要

1. Power Apps API で Connected 接続を自動検索する
2. 見つからない場合だけ、VS Code 統合ブラウザで接続を仮作成する
3. ユーザーは OAuth のアカウント選択・同意だけを行う
4. Connected を API で検証し、接続 ID を接続参照へ設定する

auth_helper の既定クライアントには Connectivity.Connections.Write がないため、 新規接続の仮作成はメーカーポータル自身の認証済み API 呼び出しを利用する。 Microsoft Dataverse も OAuth 接続では同意フローを使用する。詳細は 接続作成標準 を参照する。

f-string と式の二重ブレース問題

# ❌ f-string 内の Power Automate 式（{} エスケープが複雑でバグの原因）
body = f"@{{triggerOutputs()?['body/{PREFIX}_name']}}"

# ✅ f-string を使わない部分は通常文字列で構築
body_template = "@{triggerOutputs()?['body/{prefix}_name']}"
body = body_template.replace("{prefix}", PREFIX)

# ✅ または変数だけ f-string で、式部分は連結
body = f"<td>@{{triggerOutputs()?['body/{PREFIX}_name']}}</td>"
# ↑ 正しく動くが読みにくい。1箇所だけならOK、複数箇所は避ける

べき等デプロイパターン

# 既存フロー検索 → 無効化 → 削除 → 再作成
existing = api_get(f"workflows?$filter=name eq '{FLOW_NAME}' and category eq 5&$select=workflowid,statecode")
for f in existing.get("value", []):
    wf_id = f["workflowid"]
    if f["statecode"] == 1:  # Active → Draft
        api_patch(f"workflows({wf_id})", {"statecode": 0, "statuscode": 1})
        time.sleep(2)
    api_delete(f"workflows({wf_id})")
    time.sleep(3)
# → 新規作成へ進む

Dataverse Webhook トリガーのフローは /start 必須（★ 検証済み教訓）

❌ statecode=1 だけで終わる
   → Dataverse Create/Update トリガー（webhook 型）で webhook 登録が完了せず発火しない

✅ statecode=1 + statuscode=2 の後に /start を明示的に呼ぶ:
   POST .../providers/Microsoft.ProcessSimple/environments/{env-id}/flows/{workflow-id}/start?api-version=2016-11-01
   （Flow API スコープ: https://service.flow.microsoft.com/.default）

GrantAccess / RevokeAccess は PerformUnboundAction で呼ぶ（★ 検証済み教訓）

❌ PerformBoundAction + GrantAccess / RevokeAccess
   → "Bound action 'GrantAccess' is not found" (BadRequest)

✅ PerformUnboundAction + actionName + Target パラメータ
   → Draft 作成・有効化に成功（2026-05-02 検証済み）

補足:
  - @odata.type をそのまま書くと式として解釈されるため @@odata.type でエスケープが必要
  - connectionReferences は runtimeSource: "embedded" + connectionReferenceLogicalName で渡す
  - payload（Target / PrincipalAccess / Revokee）は Compose アクションに分離すると
    Power Automate UI での編集性が上がる

AI Builder アクションは API で Draft 作成・有効化ともに可能

検証結果（operationId: aibuilderpredict_customprompt）:
  ✅ フロー作成（Draft） — AI Builder アクション含む定義の POST は成功
  ✅ フロー有効化（Activate） — statecode=1 の PATCH も成功

推奨パターン:
  ✅ aibuilderpredict_customprompt を使用（PerformBoundAction は不可）
  ✅ connectionReferences に AI Builder 用 Dataverse 接続参照を別キーで登録
     CN_DV_AI = "shared_commondataserviceforapps_1"
  ✅ runtimeSource: "embedded" + connectionReferenceLogicalName でソリューション対応
  ✅ parameters: recordId（AI Model ID）, item/requestv2/... で入力を渡す
  ✅ AI 出力パス: body/responsev2/predictionOutput/text

NG パターン:
  ❌ PerformBoundAction / PerformUnboundAction + 

---

*Content truncated.*