geekfujiwara/codeappsdevelopmentstandard/power-automate

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

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

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

重要な既知制約（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"}
      }
  }

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

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

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

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

# ❌ 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)
# → 新規作成へ進む

❌ 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）

❌ 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 での編集性が上がる

検証結果（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 で作成自体が失敗する

★ チャネル投稿（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 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 応答アクション」セクションを参照

❌ "kind": "PowerAppV2" / 応答 "kind": "PowerApp"
   → デプロイ・有効化は成功するが Copilot Studio の
     「ツールを追加 → フロー」の一覧にフローが出てこない
 
✅ トリガー: {"type": "Request", "kind": "VirtualAgent"}
✅ 応答:     {"type": "Response", "kind": "VirtualAgent"}
 
応答 schema は PowerApp 応答と形式が違う:
  ✅ プロパティは title + x-ms-dynamically-added のみ
  ❌ x-ms-content-hint は付けない
  ❌ additionalProperties は付けない
 
迷ったら環境内の既存フローの clientdata を走査して kind を実物で確認する。
再デプロイでフロー ID が変わると Copilot Studio 側のツールは無効になるため、
ツール登録済みのフローは削除→再追加が必要。
 
詳細: references/trigger-action-patterns.md の
「Copilot Studio トリガー（VirtualAgent）」セクションを参照