activator-consumption-cli

更新检查——每个会话仅检查一次（强制） 首次在某个会话中使用此技能时，必须先运行 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	调用 Fabric REST API，以读取 Activator 项和定义	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。以下示例假设已解析 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。请使用 COMMON-CLI.md § Long-Running Operations (LRO) Pattern 中的 fabric_lro 辅助工具，以便在解码前通过 Location 标头轮询 202 响应。

解码完整定义

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 使用 BasicFilter，而不是语义查询的 Version / From / Where 契约。
• 缺少报表、页面、视觉对象或度量值的血缘信息。

---

必须 / 优先 / 避免

必须做到

• 始终在 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 检查
• 动态发现 ID — 通过列出工作区和项并使用 JMESPath 进行筛选
• 对包含大量 Activator 项的工作区进行分页列举
• 报告 Power BI 血缘信息 — 尽可能包含数据集、报表、页面、视觉对象和度量值元数据
• 标记 Power BI 筛选器不一致问题 — 尤其是缺少个性化维度值的情况

避免

• 硬编码工作区或项 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 身份流，且不得硬编码令牌。

调用 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	获取特定规则的激活历史

---

Agent 集成说明

• 此技能使用 Fabric Items API（/reflexes）进行列表查询，并使用 getDefinition 进行检查
• 检查项目/规则无需额外的数据平面协议 — 所有操作均使用面向 Fabric API 的 az rest
• 即使是只读访问，getDefinition 也需要 ReadWrite 作用域 — 这是已知的 API 要求
• 激活历史需要连接 MCP 服务（无法通过公开 REST API 获取）
• 如需创建或修改 Activator 项目和规则，请使用 activator-authoring-cli 技能