dataflows-save-as-authoring-cli

更新の確認 — セッションごとに1回（必須） このスキルをセッションで初めて使用する際は、続行する前にcheck-updatesスキルを実行してください。

• GitHub Copilot CLI / VS Code：check-updatesスキルを呼び出します。
• Claude Code / Cowork / Cursor / Windsurf / Codex：ローカルとリモートのpackage.jsonのバージョンを比較します。
• このセッション中にすでに確認済みの場合はスキップします。

重要な注意事項

1. ワークスペース名から詳細（IDを含む）を調べるには、すべてのワークスペースを一覧表示してから、JMESPathでフィルタリングします。
2. ワークスペースID、アイテムの種類、アイテム名からアイテムの詳細（IDを含む）を調べるには、そのワークスペース内の該当する種類のアイテムをすべて一覧表示してから、JMESPathでフィルタリングします。

生成境界 — 必ず停止（必須） このスキルで実行できるsave-asは、Gen1からGen2.1への場合のみです。ソースがGen2である、またはソースの世代が特定されていない実行リクエストについては、 公開されているsave-asまたはインプレースアップグレードのエンドポイントは利用できないと伝え、API呼び出しの前に停止してください。この制限は、Gen1の候補を見つけて分類することを目的とした読み取り専用の準備状況スキャンには適用されません。 「最も近いエンドポイントを選んで続行する」を、定義をエクスポートしてコピーを作成する許可と解釈してはなりません。作成スキルを自動的に呼び出したり、何かを変更したりしないでください。ユーザーに意図する結果を確認し、別途文書化された代替手段については明示的な承認を求めてください。

dataflows-save-as-authoring-cli — Dataflow Save-As Gen1 → Gen2.1 CI/CD via CLI

Power BI Gen1 データフローから、準備状況の評価と安全策を設けた実行を通じて、アップグレード済みのGen2.1コピーを作成するためのsave-as補助ツールです。

現在、データフローをインプレースで移行することはできません。元のGen1データフローを保持したまま、save-asを使用してアップグレード済みのGen2.1コピーを作成できます。

目次

タスク	リファレンス	備考
Fabric のワークスペースとアイテムを見つける	COMMON-CLI.md § Finding Workspaces and Items	必須 — 最初にリンクを読むこと
Fabric のトポロジと主要な概念	COMMON-CORE.md § Fabric Topology
環境 URL	COMMON-CORE.md § Environment URLs
認証とトークンの取得	COMMON-CORE.md § Authentication	対象が誤っていると 401
コア制御プレーン REST API	COMMON-CORE.md § Core REST APIs	ページネーション、LRO ポーリング、レート制限
ツール選択の理由	COMMON-CLI.md § Tool Selection
認証の手順	COMMON-CLI.md § Auth Recipes	az login のフローとトークン取得
az rest による Fabric 制御プレーン API	COMMON-CLI.md § az rest	必ず --resource を指定すること
よくある問題とトラブルシューティング（CLI）	COMMON-CLI.md § Gotchas	az rest のオーディエンス、シェルでのエスケープ
クイックリファレンス	COMMON-CLI.md § Quick Ref	トークンのオーディエンス／ツールの一覧
Dataflow 定義の構造	DATAFLOWS-AUTHORING-CORE.md § Definition	Gen2 CI/CD 用の 3 部構成形式
消費機能の対応表	DATAFLOWS-CONSUMPTION-CORE.md § Capabilities	読み取り専用の検出パターン
Upgrade CLI クイックリファレンス	upgrade-cli-quickref.md	スキャンと別名保存に使う az rest のワンライナーすべて
リスク評価ガイド	risk-assessment-guide.md	リスクシグナルの検出ロジックと API 呼び出し

---

ツールスタック

ツール	役割	インストール
az CLI	主な用途：Fabric API と Power BI API の両方に対する認証（az login）と REST API 呼び出し（az rest）。	多くの開発環境にプリインストール済み
jq	JSON レスポンス（dataflow リスト、リスクシグナルの抽出）の解析とフィルタリング。	プリインストール済み、または簡単にインストール可能
base64	dataflow 定義をデコードして確認。	bash に組み込み済み／PowerShell の [Convert]::ToBase64String()

エージェントによる確認 — 最初の操作の前に確認します：

az --version 2>/dev/null || echo "INSTALL: https://aka.ms/install-azure-cli"
jq --version 2>/dev/null || echo "INSTALL: apt-get install jq OR brew install jq"

---

認証と API のオーディエンス

このスキルでは、2 つの異なる API オーディエンスを使用します。誤ったオーディエンスを使用すると 401 が返されます。

API	オーディエンス（--resource）	用途
Fabric Items API	https://api.fabric.microsoft.com	Gen2 dataflow の一覧表示（Fabric ネイティブ）、ワークスペースの検出
Power BI REST API	https://analysis.windows.net/powerbi/api	Gen1 dataflow の検出、saveAsNativeArtifact、データソース、上流の dataflow、Admin API のスキャン

# Fabric Items API — list Gen2 dataflows in a workspace
az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/dataflows"

# Power BI REST API — list all dataflows (Gen1 + Gen2) in a workspace
az rest --method get \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "https://api.powerbi.com/v1.0/myorg/groups/$WS_ID/dataflows"

# Power BI Admin API — list all dataflows tenant-wide (requires admin role)
az rest --method get \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "https://api.powerbi.com/v1.0/myorg/admin/dataflows"

---

フェーズ 1 — 状況把握と準備状況

目標：「別名保存を使うべきか。また、Gen2.1 のコピーを作成すると何が起こるか？」

エージェント型ワークフロー：検出 → 評価 → 分類 → 報告

別名保存の準備状況を評価する際は、毎回次の手順に従います。

1. 検出 — ワークスペースをスキャンしてすべての dataflow を一覧化し、Gen1 と Gen2 を識別します
2. 評価 — 各 Gen1 dataflow について、7 つのリスクシグナルを確認します
3. 分類 — 準備状況のカテゴリを割り当てます：✅ 安全／⚠️ 手動でのフォローアップが必要／❌ ブロック
4. 報告 — 別名保存の準備状況スナップショットを出力します（Markdown テーブル＋JSON）

ステップ 1：検出 — Gen1 データフローを特定する

Power BI REST API は、各データフローに generation プロパティ（値は 1 または 2）を返します。これは推奨される検出方法で、ワークスペースごとに API を 1 回呼び出すだけです。

非管理者向けの方法（ワークスペースごと）

WS_ID="<workspaceId>"
RESOURCE_PBI="https://analysis.windows.net/powerbi/api"

# List all dataflows — the `generation` property distinguishes Gen1 from Gen2
ALL_DATAFLOWS=$(az rest --method get \
  --resource "$RESOURCE_PBI" \
  --url "https://api.powerbi.com/v1.0/myorg/groups/$WS_ID/dataflows" \
  --query "value[].{id:objectId, name:name, generation:generation, modelUrl:modelUrl, configuredBy:configuredBy}" -o json)

# Filter Gen1 dataflows
echo "$ALL_DATAFLOWS" | jq '[.[] | select(.generation == 1)]'

# Filter Gen2 dataflows
echo "$ALL_DATAFLOWS" | jq '[.[] | select(.generation == 2)]'

ヒント：dfs.core.windows.net を指す modelUrl は、BYOSA（顧客管理ストレージ）も示します。これは保存コピーを妨げる要因です。

管理者向けの方法（テナント全体）

Fabric 管理者ロール、または Tenant.Read.All スコープを持つサービスプリンシパルが必要です。レート制限は 1 時間あたり 200 リクエストです。

RESOURCE_PBI="https://analysis.windows.net/powerbi/api"

# List ALL dataflows in the tenant
ADMIN_DATAFLOWS=$(az rest --method get \
  --resource "$RESOURCE_PBI" \
  --url "https://api.powerbi.com/v1.0/myorg/admin/dataflows" \
  --query "value[].{id:objectId, name:name, workspaceId:workspaceId, modelUrl:modelUrl, configuredBy:configuredBy}" \
  -o json)

# Filter Gen1 dataflows — those with a modelUrl indicate CDM/Gen1 storage
# Note: Admin API may not expose the `generation` property; use modelUrl as fallback
echo "$ADMIN_DATAFLOWS" | jq '[.[] | select(.modelUrl != null and .modelUrl != "")]'

注：Admin API では、大規模なテナントのページネーションに $filter、$top、$skip を使用できます。

ステップ 2：評価 — リスクの兆候を確認する

検出した Gen1 データフローごとに、7 つのリスクの兆候を評価します。API 呼び出しの詳細については、risk-assessment-guide.md を参照してください。

#	リスクの兆候	検出方法	影響
1	増分更新	データフロー定義で増分更新ポリシーの設定を確認します	⚠️ スケジュールは無効な状態で移行されるため、再度有効にして検証する必要があります
2	BYOSA / カスタム ADLS Gen2 ストレージ	modelUrl を確認します。顧客のストレージアカウント（Power BI 管理ではない）を指している場合が該当します	❌ データは以前のストレージに残ります。Gen2 CI/CD では Fabric 管理のストレージが使用されます
3	Power Automate / API トリガー	Gen1 データフロー ID を参照している外部オーケストレーションがないか確認します	⚠️ すべての統合で、新しい Gen2 アーティファクト ID への更新が必要です
4	下流のパイプライン依存関係	データフロー アクティビティへの参照が Fabric パイプラインにないか確認します	⚠️ パイプライン アクティビティはデータフローを ID で参照するため、再バインドが必要です
5	リンク済み / 計算済みエンティティ	データフロー定義を調べ、他のデータフローへのエンティティ参照を確認します	⚠️/❌ ソースデータフローを先に保存しないと、データフロー間の参照が機能しなくなる場合があります
6	DirectQuery 接続	定義内のデータソースの種類を調べます	❌ Gen2 CI/CD データフローでは DirectQuery がサポートされていません
7	呼び出し元が所有者ではない / ロールが不十分	configuredBy を az account show --query user.name -o tsv と比較するか、呼び出しを試して DataflowUnauthorizedError を捕捉します	❌ saveAsNativeArtifact を実行するには、呼び出し元がデータフローの所有者であるか、ソースワークスペースで Contributor/Admin のロールを持っている必要があります。所有者ではない Viewer/Member は保存コピーを実行できません

ステップ 3：分類 — 準備状況のカテゴリ

カテゴリ	条件	対応
✅ 安全	リスクの兆候が検出されない	saveAsNativeArtifact で Gen2.1 の保存コピーを作成します
⚠️ 手動でのフォローアップが必要	リスクの兆候 1、3、4、または 5（ブロッキング要因ではない）	保存コピーを実行してから、指摘された問題に対処します
❌ ブロック	リスクの兆候 2、6、または 7（ブロッキング要因）	ブロッキング要因を解消するまで、保存コピーを実行できません

ヒント — 保存コピーの前に所有者を確認する：データフロー一覧の応答にある configuredBy フィールドには、所有者のメールアドレスが含まれます。現在ログイン中のユーザー（az account show --query user.name -o tsv）と比較します。一致せず、ワークスペースのロールが Contributor より低い場合は、そのデータフローを ❌ ブロック（シグナル 7）として報告し、所有者にエスカレーションします。

ステップ 4：報告 — 保存コピーの準備状況スナップショット

Markdown 出力（ターミナル）

## Save-As Readiness Snapshot
| Workspace | Dataflow | Type | Readiness | Risk Signals | Recommendation |
|---|---|---|---|---|---|
| Sales Analytics | SalesETL | Gen1 | ✅ Safe | None | Save as Gen2.1 copy now |
| Sales Analytics | CustomerLoad | Gen1 | ⚠️ Manual | Incremental refresh, Pipeline dep | Save as Gen2.1 copy, then re-enable schedule & update pipeline |
| Finance | FinanceDaily | Gen1 | ❌ Blocked | BYOSA storage | Resolve storage dependency first |

JSON 出力（自動化）

{
  "snapshotDate": "2025-04-13T10:00:00Z",
  "summary": { "total": 3, "safe": 1, "manual": 1, "blocked": 1 },
  "dataflows": [
    {
      "workspaceName": "Sales Analytics",
      "workspaceId": "...",
      "dataflowName": "SalesETL",
      "dataflowId": "...",
      "type": "Gen1",
      "readiness": "safe",
      "riskSignals": [],
      "recommendation": "Save as Gen2.1 copy now",
      "saveAsPath": "saveAsNativeArtifact"
    }
  ]
}

JSON をファイルに保存するには、jq '.' > readiness-snapshot.json にパイプで渡します。

---

ガードレールに沿って実行する

目標：保存コピーを呼び出し、安全に結果を記録します。

Gen1 → Gen2.1 CI/CD：saveAsNativeArtifact API

POST https://api.powerbi.com/v1.0/myorg/groups/{groupId}/dataflows/{gen1DataflowId}/saveAsNativeArtifact

これはプレビュー APIです。元の Gen1 データフローを保持したまま、新しい Gen2.1 CI/CD アーティファクトのコピーを作成します。

WS_ID="<workspaceId>"
GEN1_ID="<gen1DataflowId>"

# Write body to a temp file — az rest wraps inline --body in an envelope
# on some platforms, causing "saveAsRequest is a required parameter" errors.
cat > /tmp/save-as-body.json <<'EOF'
{
  "displayName": "MyDataflow_Gen2CICD",
  "description": "Saved as Gen2.1 copy from Gen1",
  "includeSchedule": true,
  "targetWorkspaceId": "<targetWorkspaceId>"
}
EOF

az rest --method post \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "https://api.powerbi.com/v1.0/myorg/groups/$WS_ID/dataflows/$GEN1_ID/saveAsNativeArtifact" \
  --headers "Content-Type=application/json" \
  --body @/tmp/save-as-body.json

注意 — インラインのリクエストボディ：--body '{...}' で JSON をインラインで渡すと、az rest がペイロードを余分なエンベロープでラップし、"saveAsRequest is a required parameter" エラーが発生することがあります。このエンドポイントでは、必ずファイルベースのリクエストボディ（--body @file.json）を使用してください。

注意 — Windows の az.cmd：Windows では、saveAsNativeArtifact の呼び出しで -o json を省略してください。このフラグを az.cmd 経由で使用すると、"A value that is not valid (json) was specified for the outputFormat parameter" が発生します。-o json を付けずに出力を取得し、PowerShell の ConvertFrom-Json で解析するか、bash で jq にパイプしてください。

注意 — 冪等ではありません（再試行時にアーティファクトが重複します）：saveAsNativeArtifact は、呼び出すたびに新しいアーティファクトを作成します。バッチが中断されて再実行されると、ターゲットワークスペースに複数のコピーが作成されます。安全に再試行できるようにするには、（1）呼び出し前に、指定した名前の Gen2 アーティファクトがすでに存在するか確認するか、（2）displayName にタイムスタンプを含め、実行ごとに別のアーティファクトとして扱ってください。

注意 — 所有者のアクセス許可：saveAsNativeArtifact を呼び出すには、データフローの所有者であるか、ソースワークスペースで共同作成者／管理者である必要があります。データフローを所有していない閲覧者またはワークスペースメンバーの場合、API は DataflowUnauthorizedError を返します。そのようなデータフローの保存操作は、データフローの所有者またはワークスペース管理者に依頼してください。

リクエストパラメーター：

パラメーター	型	必須	説明
displayName	string (max 200)	いいえ	新しいアーティファクトの名前です。省略すると、_copy1 のサフィックスが付いた名前が自動生成されます
description	string (max 4000)	いいえ	説明です。省略すると、ソースからコピーされます
includeSchedule	boolean	いいえ	更新スケジュールを無効状態でコピーします
targetWorkspaceId	string (uuid)	いいえ	ターゲットワークスペースです。省略すると同じワークスペースになります

レスポンス：SaveAsNativeDataflowResponse を伴う 200 OK：

• artifactMetadata — 新しい Gen2 CI/CD アーティファクトの完全なメタデータ（objectId、provisionState を含む）
• errors[] — 致命的ではない警告コード（これらが発生しても保存操作は成功します）：
  • FailedToCopySchedule — スケジュールをコピーできませんでした
  • SetDataflowOriginFailed — オリジン追跡を設定できませんでした
  • ConnectionsUpdateFailed — 接続文字列を Fabric 形式に更新できませんでした

Gen2 → Gen2 CI/CD：インプレースアップグレード

まだ利用できません — この API は現在のパブリックサーフェスでは利用できません。このスキルはエンドポイントの公開後に更新されます。存在しないエンドポイントを呼び出そうとしないでください。

保存後の検証チェックリスト

Gen1 のクリーンアップを行う前に、保存後に次のチェックを実行してください。

• artifactMetadata.provisionState が Active になることを確認します。
• SaveAsNativeDataflowResponse の errors[] を確認し、警告ごとにフォローアップタスクを作成します。
• 新しいアーティファクトがターゲットワークスペースに存在し、想定した名前と説明になっていることを確認します。
• 依存するオーケストレーション（パイプライン、フロー、API 呼び出し元）が新しいアーティファクト ID に更新されていることを確認します。
• ユーザーが明示的に承認した場合に限り、更新を実行します。

---

必須／推奨／回避

必ず行うこと

• az rest には必ず --resource を渡してください。上記の API テーブルに従って、適切なオーディエンスを指定してください。オーディエンスが間違っていると、401 エラーが通知されずに発生します。
• Power BI REST API への POST 呼び出しには、必ず --headers "Content-Type=application/json" を含めてください。
• saveAsNativeArtifact にはファイルベースのボディを使用してください。インライン JSON ではなく、--body @file.json を渡してください。インラインの --body '{...}' を使用すると、az rest がペイロードを余分なエンベロープでラップすることがあり、その結果 "saveAsRequest is a required parameter" エラーが発生します。
• Windows では、saveAsNativeArtifact 呼び出しに -o json を指定しないでください。代わりに、PowerShell の ConvertFrom-Json を使用するか、jq にパイプしてください。az.cmd 経由で実行すると、-o json フラグは "A value that is not valid (json)" エラーで失敗します。
• 保存前に、自分がデータフローの所有者または Contributor であることを確認してください。Workspace Member または Viewer にすぎない非所有者が saveAsNativeArtifact を実行すると、DataflowUnauthorizedError が返されます。
• 再試行する前に、既存の Gen2 アーティファクトを確認してください。saveAsNativeArtifact は冪等ではありません。中断されたバッチ実行を再試行すると、コピーが重複して作成されます。呼び出し前にターゲット名が存在しないことを確認するか、実行ごとに一意のタイムスタンプ付き displayName を使用してください。
• 保存前にスキャンしてください。実行前に必ず準備状況スキャンを実行してください。
• ユーザーの明示的な同意なしに更新しないでください。Gen2 CI/CD アーティファクトのスケジュールは、安全のため無効状態で作成されます。
• saveAsNativeArtifact の応答にある errors[] を確認してください。保存が致命的でない警告を伴って成功する場合があります。
• 保存後に provisionState が Active であることを確認してください。終端状態になるまでアーティファクトのメタデータをポーリングしてください。
• 元の Gen1 データフローを保持してください。saveAsNativeArtifact を実行しても Gen1 はそのまま残ります。保存後の検証に合格するまで削除しないでください。

優先すること

• テナント全体のスキャンには Admin API を使用してください。大規模なテナントでは、ワークスペースごとにスキャンするより効率的です。
• 自動化には JSON 出力を使用してください。Markdown は人によるレビュー用、JSON はスクリプトや CI/CD 統合用です。
• トポロジカル順に保存してください。下流のコンシューマーより先に、上流のデータフロー（リンクされたエンティティを含む）を保存してください。
• 準備状況の確認を優先して実行してください。保存前の準備状況評価を省略しないでください。
• Gen1 の検出には generation プロパティを使用してください。Power BI REST API は、各データフローに generation: 1 または generation: 2 を返します。API をまたいで比較する方法ではなく、この 1 回の API 呼び出しで判定する方法を使用してください。
• 補助的な判定には modelUrl を確認してください。modelUrl が dfs.core.windows.net を指すデータフローは、顧客ストレージを使用する Gen1 です（BYOSA の阻害要因）。

避けること

• ブロックされている（❌）データフローを保存すること。まず BYOSA ストレージと DirectQuery の問題を解決してください。
• レビューなしで一括保存すること。複数のデータフローを保存する前に、必ず準備状況のスナップショットを確認してください。
• ワークスペース ID／データフロー ID をハードコードすること。REST API 経由で動的に解決してください。
• 致命的でないエラーを無視すること。FailedToCopySchedule、ConnectionsUpdateFailed などは手動での対応が必要です。
• Gen2→Gen2 の CI/CD インプレース保存 API を呼び出すこと。その API はまだ存在しません。エンドポイントを捏造しないでください。
• ユーザーの明示的な同意なしに Gen1 アーティファクトを削除すること。保存後の検証でデータ整合性が確認された後でも、ユーザーが削除を明示的に承認しない限り、Gen1 データフローを削除しないでください。
• Windows で saveAsNativeArtifact に -o json を使用すること。このフラグは省略し、生の出力を取得して明示的に解析してください。
• 冪等性チェックなしで一括保存スクリプトを再実行すること。ワークスペース内でコピーが重複するのを避けるため、ターゲットのアーティファクトがすでに存在しないことを必ず確認してください。

---

例

例 1：フェーズ 1 全体 — 単一ワークスペースの準備状況スキャン

プロンプト：「Sales ワークスペースで Gen1 データフローをスキャンし、準備状況のスナップショットを表示してください」

エージェントの応答：

# Step 1 — Resolve workspace ID
WS_ID=$(az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces" \
  --query "value[?displayName=='Sales'].id" -o tsv)

# Step 2 — List all dataflows with generation property
ALL_DFS=$(az rest --method get \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "https://api.powerbi.com/v1.0/myorg/groups/$WS_ID/dataflows" -o json)

# Step 3 — Filter Gen1 dataflows by generation property
GEN1_DFS=$(echo "$ALL_DFS" | jq '[.value[] | select(.generation == 1) |
  {id: .objectId, name: .name, generation: .generation, modelUrl: .modelUrl}]')

echo "Gen1 dataflows found: $(echo $GEN1_DFS | jq length)"
echo "$GEN1_DFS" | jq '.'

例 2：Gen1 データフローを Gen2.1 に保存

プロンプト：「Sales ワークスペースの SalesETL Gen1 データフローを移行またはアップグレードしてください」

エージェントの応答：

WS_ID="<workspaceId>"
GEN1_ID="<gen1DataflowId>"

# Write body to file (avoids az rest envelope wrapping)
cat > /tmp/save-as-body.json <<'EOF'
{"displayName": "SalesETL_Gen2CICD", "includeSchedule": true}
EOF

# Execute save-as
RESPONSE=$(az rest --method post \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "https://api.powerbi.com/v1.0/myorg/groups/$WS_ID/dataflows/$GEN1_ID/saveAsNativeArtifact" \
  --headers "Content-Type=application/json" \
  --body @/tmp/save-as-body.json)

# Check result
echo "$RESPONSE" | jq '{
  newId: .artifactMetadata.objectId,
  state: .artifactMetadata.provisionState,
  errors: .errors
}'

例 3：テナント全体の管理者スキャン

プロンプト：「テナント全体のすべての Gen1 データフローを表示してください」

エージェントの応答：

# Requires Fabric administrator role
ALL_DFS=$(az rest --method get \
  --resource "https://analysis.windows.net/powerbi/api" \
  --url "https://api.powerbi.com/v1.0/myorg/admin/dataflows" -o json)

# Gen1 dataflows have a modelUrl
echo "$ALL_DFS" | jq '[.value[] | select(.modelUrl != null and .modelUrl != "") |
  {id: .objectId, name: .name, workspace: .workspaceId, 
   owner: .configuredBy, storage: .modelUrl}]'