activator-consumption-cli

更新チェック — セッションごとに1回（必須） このスキルをセッション内で初めて使用するときは、先に進む前に check-updates スキルを実行してください。

• GitHub Copilot CLI / VS Code：check-updates スキルを呼び出します（例：/fabric-skills:check-updates）。
• Claude Code / Cowork / Cursor / Windsurf / Codex：ローカルの package.json のバージョンを読み取り、git fetch origin main --quiet && git show origin/main:package.json（または GitHub API）を使ってリモートのバージョンと比較します。リモートのバージョンのほうが新しい場合は、変更履歴と更新手順を表示します。
• このセッション内ですでにチェックを実施している場合はスキップします。

重要な注意事項

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

activator-consumption-cli — CLI による読み取り専用の Activator 調査

目次

タスク	参照先	備考
Fabric のワークスペースとアイテムの検索	COMMON-CLI.md § Fabric のワークスペースとアイテムの検索	必須 — 先にリンクを読む [ワークスペース／アイテム ID の解決に必要]
Fabric のトポロジと主要な概念	COMMON-CORE.md § Fabric のトポロジと主要な概念
認証とトークンの取得	COMMON-CORE.md § 認証とトークンの取得	audience が間違っていると 401
コアのコントロールプレーン REST API	COMMON-CORE.md § コアのコントロールプレーン REST API
長時間実行操作（LRO）	COMMON-CORE.md § 長時間実行操作（LRO）	getDefinition が 202 を返す場合があります
レート制限とスロットリング	COMMON-CORE.md § レート制限とスロットリング
Fabric アイテムの定義	ITEM-DEFINITIONS-CORE.md § 定義のエンベロープ	Base64 ペイロードの構造
認証の手順	COMMON-CLI.md § 認証の手順	az login のフロー
az rest による Fabric コントロールプレーン API	COMMON-CLI.md § az rest による Fabric コントロールプレーン API	必ず --resource https://api.fabric.microsoft.com を渡してください
LRO パターン	COMMON-CLI.md § 長時間実行操作（LRO）のパターン
ページネーションのパターン	COMMON-CLI.md § ページネーションのパターン
ツールスタック	SKILL.md § ツールスタック
接続	SKILL.md § 接続
Activator アイテムの一覧表示	SKILL.md § Activator アイテムの一覧表示
単一の Activator の調査	SKILL.md § 単一の Activator の調査
定義の読み取り	SKILL.md § 定義の読み取り
ルール、ソース、アクションの調査	SKILL.md § ルール、ソース、アクションの調査
Power BI ソースの調査	SKILL.md § Power BI ソースの調査	powerBiSource-v1、保存されたクエリ JSON、metricDefinition、レポート／モデルのリネージ
必須／推奨／回避	SKILL.md § 必須／推奨／回避
例	SKILL.md § 例

---

ツールスタック

ツール	用途	インストール
az cli	Activator のアイテムと定義を読み取るための Fabric REST API 呼び出し	winget install Microsoft.AzureCLI
jq	JSON 処理、Base64 デコード、定義の確認	winget install jqlang.jq

---

接続

COMMON-CLI.md § Authentication Recipes の共通認証ガイダンスを使用してください。COMMON-CLI.md § Finding Workspaces and Items in Fabric に従って、ワークスペース ID とアイテム ID を解決してください。以下の例では、WS_ID と REFLEX_ID がすでに解決されていることを前提としています。

---

Activator アイテムの一覧表示

ワークスペース内のすべての Activator を一覧表示する

az rest --method GET \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/reflexes" \
  --resource "https://api.fabric.microsoft.com" \
  | jq '.value[] | {id, displayName, description}'

必要なスコープ：Workspace.Read.All または Workspace.ReadWrite.All

ページ分割された一覧表示

アイテムが多数あるワークスペースでは、各レスポンスで返される continuationUri をたどってください。

NEXT_URL="https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/reflexes"
while [ -n "$NEXT_URL" ]; do
  RESPONSE=$(az rest --method GET \
    --url "$NEXT_URL" \
    --resource "https://api.fabric.microsoft.com")
  echo "$RESPONSE" | jq '.value[] | {id, displayName, description}'
  NEXT_URL=$(echo "$RESPONSE" | jq -r '.continuationUri // empty')
done

フォルダーで絞り込む

az rest --method GET \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/reflexes?recursive=true&rootFolderId=${FOLDER_ID}" \
  --resource "https://api.fabric.microsoft.com" \
  | jq '.value[] | {id, displayName}'

---

単一の Activator を確認する

az rest --method GET \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/reflexes/${REFLEX_ID}" \
  --resource "https://api.fabric.microsoft.com" \
  | jq '{id, displayName, description, type, workspaceId}'

---

定義を読み取る

getDefinition は POST（GET ではありません）であり、読み取り専用の確認でも ReadWrite スコープ（Reflex.ReadWrite.All または Item.ReadWrite.All）が必要です。また、202 LRO を返す場合があります。202 レスポンスをデコードする前に Location ヘッダー経由でポーリングできるよう、COMMON-CLI.md § Long-Running Operations (LRO) Pattern の fabric_lro ヘルパーを使用してください。

定義全体をデコードする

DEFINITION=$(fabric_lro POST \
  "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/reflexes/${REFLEX_ID}/getDefinition" \
  '{}')

echo "$DEFINITION" \
  | jq '.definition.parts[] | select(.path=="ReflexEntities.json") | .payload' -r \
  | base64 -d | jq .

定義をファイルに保存する

DEFINITION=$(fabric_lro POST \
  "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/reflexes/${REFLEX_ID}/getDefinition" \
  '{}')

echo "$DEFINITION" \
  | jq '.definition.parts[] | select(.path=="ReflexEntities.json") | .payload' -r \
  | base64 -d | jq . > reflex-entities.json

---

ルール、ソース、アクションを確認する

デコード済みの ReflexEntities.json を取得したら、jq を使って特定のコンポーネントを抽出します。

すべてのエンティティ型を一覧表示する

cat reflex-entities.json | jq '[.[] | .type] | sort | group_by(.) | map({type: .[0], count: length})'

データソースを一覧表示する

cat reflex-entities.json | jq '.[] | select(.type | endswith("Source-v1")) | {name: .payload.name, type: .type, id: .uniqueIdentifier}'

ルールを一覧表示する

cat reflex-entities.json | jq '.[] | select(.type == "timeSeriesView-v1" and .payload.definition.type == "Rule") | {name: .payload.name, id: .uniqueIdentifier, shouldRun: .payload.definition.settings.shouldRun}'

オブジェクトとその属性を一覧表示する

# Objects
cat reflex-entities.json | jq '.[] | select(.type == "timeSeriesView-v1" and .payload.definition.type == "Object") | {name: .payload.name, id: .uniqueIdentifier}'

# Attributes for a specific object
OBJECT_ID="<object-guid>"
cat reflex-entities.json | jq --arg oid "$OBJECT_ID" '.[] | select(.type == "timeSeriesView-v1" and .payload.definition.type == "Attribute" and .payload.parentObject.targetUniqueIdentifier == $oid) | {name: .payload.name, id: .uniqueIdentifier}'

ルールの条件を確認する

RULE_ID="<rule-guid>"
cat reflex-entities.json \
  | jq --arg rid "$RULE_ID" '.[] | select(.uniqueIdentifier == $rid) | .payload.definition.instance' -r \
  | jq '.steps[] | {step: .name, rows: [.rows[] | .kind]}'

アクションを一覧表示する（Fabric アイテムのアクション）

cat reflex-entities.json | jq '.[] | select(.type == "fabricItemAction-v1") | {name: .payload.name, itemType: .payload.fabricItem.itemType, itemId: .payload.fabricItem.itemId}'

概要ビュー

Activator の構成の概要を確認します。

cat reflex-entities.json | jq '{
  containers: [.[] | select(.type == "container-v1") | .payload.name],
  sources: [.[] | select(.type | endswith("Source-v1")) | {name: .payload.name, type: .type}],
  objects: [.[] | select(.type == "timeSeriesView-v1" and .payload.definition.type == "Object") | .payload.name],
  rules: [.[] | select(.type == "timeSeriesView-v1" and .payload.definition.type == "Rule") | {name: .payload.name, active: .payload.definition.settings.shouldRun}],
  actions: [.[] | select(.type == "fabricItemAction-v1") | {name: .payload.name, type: .payload.fabricItem.itemType}]
}'

---

Power BI ソースを確認する

Power BI を基盤とする Activator ソースでは、powerBiSource-v1 を使用します。ソースの親である container-v1 は、大文字と小文字を区別する正確な値 payload.type: "pbiMetrics" を使用する必要があります。 ソースの query.queryString は JSON 文字列形式の Power BI ソースクエリペイロードであり、 metricDefinition は同じセマンティックモデルのメトリック、 ディメンション、フィルター、レポートビジュアルのリネージを記述します。Activator API は query.queryString 内のセマンティックモデルクエリテキストを受け付けません。

現在のパブリック API の制限： Power BI を基盤とする Activator 定義は、 現時点ではパブリック ALM の読み戻しを確実に行えません。PBI ALM エクスポートが無効になっている場合、 正常にインポートされた成果物でも getDefinition が拒否されることがあります。レスポンスとリクエスト／相関 ID をそのまま保存し、 確認できないことを説明してください。定義をエクスポートできないことだけを理由に、永続化に失敗した、 またはソースが存在しないと主張しないでください。

親コンテナーがない場合、またはコンテナーの型が pbiMetrics 以外の場合は、その旨を示してください。 特に、powerBiQueries は無効です。

保存されたクエリとメトリック定義を解析する

jq -r '.[] | select(.type == "powerBiSource-v1")
  | .payload.query.queryString' reflex-entities.json | jq .

metricDefinition は JSON 文字列またはオブジェクトの場合があります。メトリックについて説明する前に、どちらの形式も解析してください。

import json
from pathlib import Path

entities = json.loads(Path("reflex-entities.json").read_text(encoding="utf-8"))
for entity in entities:
    if entity.get("type") != "powerBiSource-v1":
        continue
    payload = entity["payload"]
    metric = payload.get("metricDefinition")
    if isinstance(metric, str):
        metric = json.loads(metric)
    print(json.dumps({
        "sourceName": payload.get("name"),
        "datasetId": payload.get("datasetId") or payload.get("metadata", {}).get("datasetId"),
        "reportId": payload.get("reportId") or payload.get("metadata", {}).get("reportId"),
        "pageId": payload.get("pageId") or payload.get("metadata", {}).get("pageId"),
        "visualId": payload.get("visualId") or payload.get("metadata", {}).get("visualId"),
        "measureName": payload.get("measureName") or payload.get("metadata", {}).get("measureName"),
        "dimensionValue": payload.get("dimensionValue"),
        "metricDefinition": metric,
    }, indent=2))

永続化された Power BI ソースクエリには top を含めないでください。

一貫性チェック

以下の問題があれば報告してください。

• PBI ALM エクスポートが無効になっているため、getDefinition がブロックされています。ソースの詳細を捏造せず、この制限を報告してください。
• query.queryString または metricDefinition を JSON として解析できません。
• 親コンテナーが存在しないか、pbiMetrics と完全に一致しません。
• metricDefinition.type が DatasetMetric ではありません。
• ソースの datasetId、クエリの provider.datasetId、metricDefinition.definition.datasetId が一致しません。
• 永続化されたクエリに top が含まれています。
• パーソナライズされたソースに dimensionValue があるものの、同じ値がクエリフィルターまたは metricDefinition.definition.filter にありません。
• metricDefinition.definition.filter で、セマンティッククエリの Version／From／Where コントラクトではなく、BasicFilter が使用されています。
• レポート、ページ、ビジュアル、またはメジャーのリネージがありません。

---

必須／推奨／回避

必ず行うこと

• az rest では必ず --resource https://api.fabric.microsoft.com を使用してください
• getDefinition では必ず --body '{}' を指定してください。これは POST であり、本文を省略すると 411 エラーが発生する場合があります。
• LRO レスポンスを処理してください。getDefinition は 202 を返す場合があります。その場合は Location ヘッダーをポーリングしてください。
• 確認前に ReflexEntities.json のペイロードを Base64 デコードしてください。API レスポンスでは Base64 エンコードされています。
• ルールエンティティの definition.instance フィールドをJSON として解析してください。これはネストされたオブジェクトではなく、JSON エンコードされた文字列です。
• Power BI ソースの場合、メトリック、ディメンション、またはフィルターを説明する前に、query.queryString と metricDefinition の両方をJSON として解析してください。

推奨事項

• まず概要を表示してください。個々のエンティティに踏み込む前に、ユーザーに大まかな概要を示してください。
• 定義が大きい場合はファイルに保存してください。一度デコードしてから、ローカルで jq を使って調査してください。
• ワークスペースとアイテムの一覧表示に JMESPath フィルターを適用して、IDを動的に特定してください。
• Activator アイテムが多数あるワークスペースでは、ページネーションを使用してください。
• Power BI のリネージを報告してください。利用可能な場合は、データセット、レポート、ページ、ビジュアル、メジャーのメタデータを含めてください。
• Power BI フィルターの不整合、特にパーソナライズされたディメンション値の欠落にフラグを立ててください。

避けること

• ワークスペース ID やアイテム ID をハードコードしないでください。必ず動的に解決してください。
• getDefinition に GET を使用しないでください。これは POST エンドポイントです。GET では 405 が返されます。
• 暗号化された秘密度ラベルが付いたアイテムの定義を読み取ろうとしないでください。ブロックされます。
• データを変更しないでください。このスキルは読み取り専用です。書き込み操作には activator-authoring-cli を使用してください。
• Power BI ソースクエリをセマンティックモデルのクエリテキストとして扱わないでください。これらは JSON 文字列として保存されたソースペイロードです。

---

例

すべての Activator を一覧表示してルールを確認する

# Step 1: List activators
az rest --method GET \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/reflexes" \
  --resource "https://api.fabric.microsoft.com" \
  | jq '.value[] | {id, displayName}'

# Step 2: For a specific activator, get and decode its definition
az rest --method POST \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/reflexes/${REFLEX_ID}/getDefinition" \
  --resource "https://api.fabric.microsoft.com" \
  --headers "Content-Type=application/json" \
  --body '{}' \
  | jq '.definition.parts[] | select(.path=="ReflexEntities.json") | .payload' -r \
  | base64 -d \
  | jq '.[] | select(.type == "timeSeriesView-v1" and .payload.definition.type == "Rule") | {name: .payload.name, active: .payload.definition.settings.shouldRun}'

特定のルールの完全な構成を調べる

# Decode definition and extract rule details
az rest --method POST \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/reflexes/${REFLEX_ID}/getDefinition" \
  --resource "https://api.fabric.microsoft.com" \
  --headers "Content-Type=application/json" \
  --body '{}' \
  | jq '.definition.parts[] | select(.path=="ReflexEntities.json") | .payload' -r \
  | base64 -d \
  | jq '.[] | select(.payload.name == "Too hot for medicine") | .payload.definition.instance' -r \
  | jq '.steps[] | {step: .name, details: .rows}'

---

アクティベーション履歴のクエリ

ルールが発火した際のアクティベーション履歴は、公開 REST API では取得できません。Activator MCP サーバーの get_activations_for_rule ツールからアクセスできます。

前提条件

Activator MCP エンドポイントに接続する前に、COMMON-CLI.md § Authentication Recipes の共通認証ガイダンスを使用してください。

pip install mcp httpx azure-identity aiohttp

ワークフロー

1. 公開 API を使用してルールを一覧表示し（getDefinition → デコード → Rule エンティティでフィルタリング）、ルールの uniqueIdentifier を取得します。
2. Activator MCP サーバーに接続し、ルール ID を指定して get_activations_for_rule を呼び出します。

MCP サーバーへの接続

Activator MCP エンドポイントは次のとおりです。

https://api.fabric.microsoft.com/v1/mcp/workspaces/{workspaceId}/reflexes/{activatorId}

COMMON-CORE.md § Authentication & Token Acquisition の共通 Fabric API 認証ガイダンスを使用してください。MCP クライアントは標準の Azure ID フローを使用し、トークンをハードコードしてはなりません。

get_activations_for_rule の呼び出し

MCP の streamable_http_client を使用して接続し、ツールを呼び出します。

from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

# After connecting and initializing the session:
result = await session.call_tool(
    "get_activations_for_rule",
    {
        "getActivationsParams": {
            "workspaceId": "<workspace-id>",
            "artifactId": "<activator-id>",
            "ruleId": "<rule-uniqueIdentifier>",
        }
    },
)

レスポンスには totalCount と、ルールが発火した各時点の詳細を含む activations 配列が含まれます。

利用可能な MCP ツール

ツール	用途
list_rules	Activator 内のルールを一覧表示します（公開 API のデコードの代替）
get_activations_for_rule	特定のルールのアクティベーション履歴を取得します

---

エージェント統合に関する注意事項

• このスキルでは、一覧表示に Fabric Items API（/reflexes）を使用し、検査には getDefinition を使用します
• 項目／ルールの検査に追加のデータプレーンプロトコルは必要ありません。すべて Fabric API audience を指定した az rest を使用します
• getDefinition には読み取り専用アクセスの場合でも ReadWrite スコープが必要です。これは既知の API 要件です
• アクティベーション履歴には MCP サーバーへの接続が必要です（公開 REST API では利用できません）
• Activator の項目やルールを作成または変更するには、activator-authoring-cli スキルを使用してください