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 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 を参照。

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

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

核心原則: 接続参照（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"}
      }
  }

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

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

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

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

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

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 テーブル操作・接続参照作成

接続は環境内に事前作成が必要

❌ API で接続の自動作成はできない
✅ Power Automate UI で事前に接続を作成 → API ではその接続 ID を参照するのみ
   https://make.powerautomate.com/connections

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 + msdyn_PredictByReference
     → InvalidOpenApiFlow で作成自体が失敗する

Teams PostMessageToConversation の注意

★ チャネル投稿（Channel）:
  ❌ body/subject パラメータを指定しない
     → PostMessageToConversation の operationSchema に body/subject は存在しない
     → 指定するとフロー有効化時に InvalidOpenApiFlow (0x80060467) が発生
     → エラーメッセージに具体的なパラメータ名が出ないため原因特定が困難
  ✅ 使用可能なパラメータ:
     poster, location, body/recipient/groupId, body/recipient/channelId, body/messageBody

★ 1:1 チャット（Chat with Flow bot）:
  ✅ location は "Chat with Flow bot"
  ✅ body/recipient にメールアドレス（文字列）を指定
  ✅ host.connection キーを使用（connectionName ではない）
  ❌ body/recipient/to は存在しない → ExtraParameter で InvalidOpenApiFlow
  ❌ Dataverse workflows テーブルへの直接 INSERT → 接続認証不良で Runtime エラー
  ✅ デプロイは Flow API 経由を推奨

  詳細は trigger-action-patterns.md の
  「Teams 1:1 チャット投稿 — Chat with Flow bot」セクション参照

Power Apps V2 トリガー・応答のパラメータ形式（★ 重要）

Power Automate UI で手動追加したパラメータと API でデプロイしたパラメータは
形式が異なるとフローが正しく動作しない。必ず UI 形式に合わせる。

★ 正しい形式（トリガー・応答共通）:
  ✅ "x-ms-content-hint": "TEXT"
  ✅ "x-ms-dynamically-added": true

❌ 間違った形式（API デプロイ時にありがちなミス）:
  ❌ "x-ms-powerflows-param-ispartial": false
  ❌ "isPartial": false

応答（Response）固有:
  ✅ schema に "additionalProperties": {} を含める（UI が自動付与）
  ✅ title と body のキー名を一致させる

詳細: references/trigger-action-patterns.md の
「Power Apps V2 トリガー」「PowerApp 応答アクション」セクションを参照

PowerApps API 接続検索のタイムアウト対策

PowerApps API（api.powerapps.com）での接続検索は 504 GatewayTimeout が頻発する。

# ✅ リトライ + timeout=120 パターン
for attempt in range(3):
    try:
        r = requests.get(
            f"https://api.powerapps.com/providers/Microsoft.PowerApps"
            f"/apis/{connector}/connections",
            headers={"Authorization": f"Bearer {token}"},
            params={"api-version": "2016-11-01", "$filter": f"environment eq '{env_id}'"},
            timeout=120,
        )
    except requests.exceptions.Timeout:
        wait = 15 * (attempt + 1)
        time.sleep(wait)
        continue
    if r.status_code == 504:
        wait = 15 * (attempt + 1)
        time.slee

---

*Content truncated.*