powerbi-report-management

遥测 — 强制要求。 每次调用 api.fabric.microsoft.com 都必须携带 x-ms-fabric-skill: powerbi-report-management（az rest：--headers "x-ms-fabric-skill=powerbi-report-management"）， 包括每次 LRO 轮询、fabric_lro 和重试。代码片段中省略了此项，但仍须添加。

重要说明

1. 要根据工作区名称查找工作区详细信息（包括其 ID）：列出所有工作区，然后使用 JMESPath 进行筛选
2. 要根据工作区 ID、项类型和项名称查找项的详细信息（包括其 ID）：列出该工作区中该类型的所有项，然后使用 JMESPath 进行筛选

Power BI 报表管理

使用 az rest 调用 Fabric REST API，管理 Microsoft Fabric 工作区中的 Power BI 报表。此技能涵盖报表项及其 PBIR 定义的完整 CRUD 生命周期。

范围：仅涉及报表项的 CRUD 和定义管理。若要创作报表布局（页面、视觉对象、筛选器、格式），请使用 powerbi-report-authoring。

边界：此技能负责在 Fabric 与本地之间传输 PBIR 定义。PBIR 内容创作仍由 powerbi-report-authoring 负责。

配套技能

此技能是划分 Power BI 创作范畴的三项技能之一。每项技能只负责一个方面；请将任务交由合适的技能处理。

技能	负责内容	适用场景
powerbi-report-authoring	报表内容（PBIR JSON 创作）	页面、视觉对象、筛选器、格式、主题、表达式、definition.pbir、version.json、report.json
powerbi-report-management（此技能）	与 Fabric 之间的报表传输	列出、创建、获取、更新、删除报表项；下载/上传 PBIR 定义
语义模型创作技能	语义模型创作与部署	创建/编辑度量值/表/关系、TMDL、将语义模型部署到 Fabric

将本地 .pbip 发布到 Fabric 时，此技能是入口点。如果用户希望将本地语义模型与报表一同发布，此技能会将模型部署工作交由可用的语义模型创作技能处理，然后解析生成的 semanticModelId 并将报表绑定到该模型。请参阅发布本地 .pbip工作流。

工具栈

工具	用途	安装
az CLI	主要工具：使用 az rest 调用 Fabric REST API，使用 az login 进行身份验证	大多数开发环境中已预装
jq	解析和构造 JSON 负载	标准 CLI 工具 — 请参阅 COMMON-CLI.md § 工具选择依据
base64	对定义负载中的 PBIR 文件内容进行编码/解码	Linux/macOS 内置 · Windows：使用 PowerShell [Convert]::ToBase64String() / FromBase64String()

Agent 检查 — 首次操作前请验证：

az version 2>/dev/null || echo "INSTALL: https://learn.microsoft.com/cli/azure/install-azure-cli"

身份验证

所有调用都使用 Fabric API 的受众。使用错误的受众会返回 401。

API	受众（--resource）
Fabric 报表项 API	https://api.fabric.microsoft.com

有关共享身份验证模型、令牌受众和身份类型，请参阅 COMMON-CORE.md § 身份验证与令牌获取。

有关完整的身份验证方案（交互式、设备代码、服务主体、托管标识）， 请参阅 COMMON-CLI.md § 身份验证方案。

查找工作区和报表

共享模式 — 工作区和项解析、分页以及 LRO 轮询 已在通用技能库中说明。 使用以下 CRUD 操作之前，请阅读 COMMON-CLI.md § 在 Fabric 中查找工作区和项。

按名称解析报表 ID

获取工作区 ID 后（参阅 COMMON-CLI.md），解析报表：

REPORT_NAME="Sales Report"
REPORT_ID=$(az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports" \
  --query "value[?displayName=='$REPORT_NAME'] | [0].id" \
  --output tsv)

示例：CRUD 操作

列出报表

返回工作区中的所有报表。

• 权限：工作区查看者角色
• 范围：Workspace.Read.All 或 Workspace.ReadWrite.All

az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports" \
  --query "value[].{name:displayName, id:id, description:description}" \
  --output table

支持通过 continuationToken 查询参数进行分页。

获取报表（属性）

返回特定报表的属性（名称、说明、ID、工作区、敏感度标签）。

• 权限：对报表具有读取权限
• 范围：Report.Read.All 或 Report.ReadWrite.All

az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports/$REPORT_ID"

获取报表定义

下载完整的 PBIR 定义。这是 POST 请求（不是 GET），并支持 LRO。

• 权限：对报表具有读写权限
• 范围：Report.ReadWrite.All 或 Item.ReadWrite.All
• 限制：带有加密敏感度标签的报表会被阻止

始终请求 format=PBIR——如果不带此参数，较旧的报表可能会返回 PBIR-Legacy 格式（单个 report.json 数据块），此技能不支持该格式。

RESPONSE=$(az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports/$REPORT_ID/getDefinition?format=PBIR" \
  --verbose 2>&1)

# If 202 Accepted, extract operation ID and poll the LRO (see Long-Running Operations section)
# If 200 OK, the response contains the definition parts

格式检查：获取定义后，验证 definition.format == "PBIR"。如果值为 "PBIR-Legacy"，则此技能不支持该格式。

将定义部分解码为本地文件

注意：getDefinition 通常会返回 202 Accepted（LRO）。请查看“长时间运行的操作”部分，提取操作 ID 并轮询结果，然后再进行解码。

# After retrieving the definition (from 200 response or LRO result):
echo "$DEFINITION_JSON" | jq -r '.definition.parts[] | "\(.path)\t\(.payload)"' | \
  while IFS=$'\t' read -r path payload; do
    mkdir -p "$(dirname "./report-definition/$path")"
    echo "$payload" | base64 -d > "./report-definition/$path"
  done

创建报表（含定义）

使用 PBIR 定义创建新报表。支持 LRO。

• 权限：工作区参与者角色
• 范围：Report.ReadWrite.All 或 Item.ReadWrite.All

# Walk ./report-definition/ and build the parts[] array — every file under the
# directory is encoded and uploaded. Includes definition.pbir, report.json,
# version.json, pages/pages.json, every pages/<page>/page.json, and every
# pages/<page>/visuals/<visual>/visual.json.
PARTS=$(find ./report-definition -type f -not -name '.*' -not -name 'Thumbs.db' | while read -r file; do
  rel="${file#./report-definition/}"
  payload=$(base64 < "$file" | tr -d '\n')
  jq -nc --arg p "$rel" --arg b "$payload" \
    '{path:$p, payload:$b, payloadType:"InlineBase64"}'
done | jq -sc '.')

jq -n \
  --arg name "My New Report" \
  --arg desc "Created via Fabric API" \
  --argjson parts "$PARTS" \
  '{displayName:$name, description:$desc, definition:{parts:$parts}}' \
  > create-report.json

az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports" \
  --headers "Content-Type=application/json" \
  --body @create-report.json \
  --verbose 2>&1

PowerShell——使用 Get-ChildItem -Recurse -File 遍历目录，并使用 [Convert]::ToBase64String([System.IO.File]::ReadAllBytes($_.FullName)) 对每个文件进行编码（而不是使用 base64 | tr -d '\n'）。

重要：始终需要 definition.pbir。上面的目录遍历会自动包含 ./report-definition/ 下的所有文件——编码前，请确保本地目录镜像了完整的 PBIR 布局（顶层文件，以及所有 pages/<page>/page.json 和 pages/<page>/visuals/<visual>/visual.json 文件）。

更新报表定义

覆盖整个定义。这是 POST 请求，并支持 LRO。

• 权限：对报表具有读写权限
• 范围：Report.ReadWrite.All 或 Item.ReadWrite.All

# Rebuild parts[] from ./report-definition/ after edits (same walk as Create).
PARTS=$(find ./report-definition -type f -not -name '.*' -not -name 'Thumbs.db' | while read -r file; do
  rel="${file#./report-definition/}"
  payload=$(base64 < "$file" | tr -d '\n')
  jq -nc --arg p "$rel" --arg b "$payload" \
    '{path:$p, payload:$b, payloadType:"InlineBase64"}'
done | jq -sc '.')

jq -n --argjson parts "$PARTS" \
  '{definition:{parts:$parts}}' \
  > update-definition.json

az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports/$REPORT_ID/updateDefinition" \
  --headers "Content-Type=application/json" \
  --body @update-definition.json \
  --verbose 2>&1

关键：updateDefinition 会替换整个定义。请包含所有部分，无论是否修改。省略部分会导致其被删除。

可选查询参数 ?updateMetadata=true 会根据包含的 .platform 文件更新项目元数据。

更新报表（属性）

仅更新显示名称和/或说明（不更新定义）。

• 权限：对报表具有读写权限
• 范围：Report.ReadWrite.All 或 Item.ReadWrite.All

cat > update-report.json << 'EOF'
{
  "displayName": "Renamed Report",
  "description": "Updated description"
}
EOF

az rest --method patch \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports/$REPORT_ID" \
  --headers "Content-Type=application/json" \
  --body @update-report.json

删除报表

删除报表。支持软删除（默认）和硬删除。

• 权限：对报表具有写入权限
• 范围：Report.ReadWrite.All 或 Item.ReadWrite.All

# Soft delete (recoverable)
az rest --method delete \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports/$REPORT_ID"

# Hard delete (permanent)
az rest --method delete \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports/$REPORT_ID?hardDelete=true"

长时间运行操作（LRO）

Create Report、Get Report Definition 和 Update Report Definition 可能会返回 202 Accepted，而不是立即返回结果。请从详细输出中捕获 x-ms-operation-id，并按照 COMMON-CLI.md § 长时间运行操作 轮询，直到操作进入终止状态。

发生冲突时，以下管理专用防护措施优先于通用模式。

⚠️ 收到 202 后，绝不要重试创建 POST。 202 Accepted 响应意味着操作已被接受，并且可能正在服务器端处理。重试 POST 有可能导致创建重复项。

始终将 --verbose 输出写入文件，以便可靠地捕获每次尝试中的 x-ms-operation-id 标头——这是跟踪操作的唯一可靠方式。从内存字符串中使用正则表达式提取内容在不同 Shell 和平台上都不可靠。捕获后，像处理其他 LRO 调用一样轮询操作，直到完成。

# PowerShell — 可靠地捕获操作 ID
az rest --method post ... --verbose 2>&1 | Out-File "$env:TEMP\lro-response.txt" -Encoding utf8
$opId = (Select-String -Path "$env:TEMP\lro-response.txt" -Pattern "x-ms-operation-id.*?'([a-f0-9-]+)'" | Select-Object -First 1).Matches.Groups[1].Value

如果尽管已写入文件，操作 ID 仍然丢失，最后的补救办法是在工作区中列出报表，以找到已创建的报表——但这不应作为常规做法。

有关详细信息，请参阅长时间运行操作。

PBIR 定义结构

报表使用 PBIR 格式——由多个 JSON 文件组成的文件夹：

Report/
├── definition.pbir                              # Semantic model reference (required)
├── definition/
│   ├── report.json                              # Report-level settings (required)
│   ├── version.json                             # Format version (required)
│   ├── pages/
│   │   ├── pages.json                           # Page listing (required)
│   │   ├── <pageId>/
│   │   │   ├── page.json                        # Page layout
│   │   │   ├── visuals/
│   │   │   │   ├── <visualId>/
│   │   │   │   │   ├── visual.json              # Visual config
│   │   │   │   │   ├── mobile.json              # Mobile layout (optional)
│   ├── bookmarks/                               # Bookmarks (optional)
├── StaticResources/                             # Custom themes, images (optional)

API 载荷中的所有部分都使用 "payloadType": "InlineBase64" 进行 Base64 编码。

definition.pbir — 语义模型引用

对于 Fabric API，请使用 byConnection（而非 byPath）：

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/2.0.0/schema.json",
  "version": "4.0",
  "datasetReference": {
    "byConnection": {
      "connectionString": "semanticmodelid=<SemanticModelId>"
    }
  }
}

必须／优先／避免

MUST

• 所有 PBIR 内容都必须通过 powerbi-report-authoring 技能完成——这是最重要的一条规则。无论是创建全新报表还是修改现有报表，每个 PBIR 文件（definition.pbir、report.json、version.json、pages.json、页面配置、视觉对象、筛选器、格式设置、主题、表达式）都必须使用 powerbi-report-authoring 编写。遵循该技能的指导，确保 PBIR 结构、架构和字段值正确。使用其 CLI 工具进行验证。绝不能凭记忆或猜测编写任何 PBIR JSON——即使是 definition.pbir 或 version.json 这类“简单”文件也不行。此技能严格用于 API 传输（下载、编码、上传），不会编写 PBIR 内容。
• 对 az rest 始终传入 --resource "https://api.fabric.microsoft.com"——省略该参数会导致静默身份验证失败。
• 对 getDefinition 始终传入 ?format=PBIR——不传此参数时，较旧的报表会返回 PBIR-Legacy 格式，而此技能不支持该格式。
• 只使用 PBIR 格式——如果定义返回的 "format": "PBIR-Legacy"，请停止操作并告知用户不支持 PBIR-Legacy。
• 在 updateDefinition 中包含所有定义部分，包括已修改和未修改的部分。API 会替换整个定义；省略某些部分会将其删除。
• 对所有部分的载荷进行 Base64 编码——每个 payload 值都必须经过 Base64 编码。
• 在 definition.pbir 中为 Fabric API 使用 byConnection——byPath 仅用于本地/Git 场景。
• 轮询 LRO 直至完成——Create、getDefinition 和 updateDefinition 会返回 202 Accepted。请持续轮询，直到状态进入终态。
• 对 LRO 操作始终使用 --verbose——az rest 默认不会公开响应标头。不使用 --verbose，就无法获取轮询所需的 x-ms-operation-id 标头，而且事后也没有其他方式可以检索它。
• 清理临时文件——操作完成后，删除工作流中创建的所有本地临时目录和文件（已解码的定义、JSON 载荷）。这些文件可能很大，会不断占用用户的计算机空间。
• 解析目标模型后，验证语义模型绑定——确定报表的目标语义模型后（无论是通过可用的语义模型编写技能重新部署，还是选择现有工作区模型），都要下载其 TMDL，并将所有 PBIR 绑定（Entity、queryRef、nativeQueryRef、筛选器 Source/Entity 引用）与模型的表名、列名和度量值名称进行比对。此要求适用于两个分支：即使是移交部署，模型也可能在发布时被重命名或转换，因此差异比对不可省略。如果名称不同，但模型在结构上等价（列/度量值相同），则通过 powerbi-report-authoring 重新映射所有限定了表名的绑定。如果模型在结构上不等价，则在尝试重新编写前先询问用户——说明哪些表/列/度量值不匹配，并询问是否继续。
• 默认仅在本地进行编辑——用户要求修改本地 .pbip 报表时，只修改本地文件。除非用户明确要求发布、上传或推送报表，否则不要发布到 Fabric。即使报表之前已发布到 Fabric，在用户另行指示前，后续编辑也一律视为仅限本地。用户要求发布本地 .pbip 时，请遵循发布本地 .pbip工作流：(a) 一开始就确认目标工作区；(b) 询问是发布本地模型还是连接到现有工作区模型；(c) 若选择发布模型，检查当前会话中是否提供语义模型编写技能，并在没有该技能时妥善处理；(d) 确认报表本身是新建还是更新现有报表。

PREFER

• 优先软删除而非硬删除，以便恢复。
• 使用带有 JMESPath --query 的 az rest 进行筛选——内置 JSON 解析，无需额外工具。

避免

• 手动编写或直接构造 PBIR JSON——无论是创建新文件还是修改现有文件，所有 PBIR 内容（definition.pbir、report.json、version.json、页面、视觉对象、筛选器、格式设置、主题、表达式）都必须通过 powerbi-report-authoring 技能处理。切勿凭记忆或猜测构造任何 PBIR JSON，即使是“简单”的结构文件也不行。没有例外。
• PBIR-Legacy 格式——不要创建、读取或更新 PBIR-Legacy 定义。仅支持现代 PBIR 格式。
• 在 updateDefinition 中仅发送已修改的部分——该 API 会替换整个定义；缺失的部分会被删除。
• 在 definition.pbir 中使用 byPath 作为 API 负载——这仅适用于本地/Git 场景。
• 硬编码工作区/报表 ID——通过 List API 动态解析。
• 跳过 LRO 轮询——定义操作可能是异步的；务必检查是否返回 202。
• 在 getDefinition 中省略 ?format=PBIR——可能会返回无法使用的 PBIR-Legacy 格式。
• 收到 202 后重试创建 POST——可能会创建重复项。正确的恢复模式请参阅 LRO 部分。

Agent 工作流

发布本地 .pbip

当用户的磁盘上有本地 .pbip（报表及其同级 .SemanticModel），并要求将报表发布、上传、推送或部署到 Fabric 工作区时，这是首选入口。

1. 检测源是否为本地 .pbip。 以下任一情况均符合：

• 工作目录中或其上级目录中有 <Name>.pbip 文件。
• 有一个 <Name>.Report 文件夹，且其同级有 <Name>.SemanticModel 文件夹。
• 报表的 definition.pbir 使用 byPath（本地/Git 格式），而不是 byConnection（API 格式）。
• 存在 .pbi/ 缓存文件夹。

如果源不是本地 .pbip（例如，报表已从 Fabric 下载，且只有 .Report 文件夹，其中的 definition.pbir 使用 byConnection），则改用在 Fabric 中修改现有报表工作流。

2. 确认一次目标工作区。 按名称解析并保存工作区 ID（参见 COMMON-CLI.md）。 同一个工作区将用于模型部署（如适用）和报表发布——切勿将两者拆分到不同工作区。

3. 询问用户有关语义模型的问题。 明确提问，不要默默自行选择：

“您希望我也将本地语义模型发布到此工作区，还是将此报表连接到工作区中已有的语义模型？”

4a. 分支：“发布本地模型”。

• 检查当前会话中是否有可用的语义模型创作技能。
  • 可用 → 将任务交给该工作流来创建或更新语义模型。传递：目标工作区 ID、本地 .SemanticModel 文件夹路径（TMDL 源）以及所需的模型显示名称。等待该技能的工作流成功结束后再继续。
  • 不可用 → 告知用户当前会话未加载语义模型创作技能，因此无法在没有该技能的情况下发布本地模型。然后转到分支 4b（连接到现有模型），并再次询问要将报表绑定到哪个工作区模型。

4b. 分支：“连接到工作区中已有的模型”。

• 列出目标工作区中的语义模型，并与用户确认目标模型。按名称解析 semanticModelId。

5. 解析 semanticModelId。 无论走哪个分支，报表都需要一个具体的模型 ID 来绑定：

• 4a 之后：列出目标工作区中的语义模型，并按名称找到刚刚部署的模型（模型技能会通过列出工作区项进行验证，但不会返回 ID）。
• 4b 之后：此步骤已完成。 6. 根据已解析的模型验证绑定（通用，适用于两个分支）。 下载模型 TMDL，并按照 MUST 在解析目标模型后验证语义模型绑定 执行绑定差异检查。即使走发布本地模型的分支，模型技能也可能在部署期间重命名表或应用转换，因此此差异检查不可省略。通过 powerbi-report-authoring 技能重新映射任何偏差；如果结构差异较大，则在重新创作前征求用户意见。

7. 将 definition.pbir 从 byPath 重新绑定为 byConnection。 使用 powerbi-report-authoring 设置：

"datasetReference": {
  "byConnection": {
    "connectionString": "semanticmodelid=<resolved-id>"
  }
}

Fabric API 会拒绝 byPath；每次发布本地源时都必须进行此替换。

8. 决定为报表新建还是更新。 默认将报表的 displayName 设为 .pbip 文件名（不含扩展名），例如 SalesDashboard.pbip → "SalesDashboard"。向用户展示此默认值，以便他们进行修改。

• 列出目标工作区中的报表，并查找所选的 displayName。
  • 未找到 → 创建。按照 创建报表（含定义） 操作。
  • 已找到 → 向用户确认：覆盖现有报表（updateDefinition）、使用其他名称发布，还是取消。 覆盖时，按照更新报表定义操作。

9. 编码并上传。 运行现有传输流程 — 对所有 PBIR 部分进行 base64 编码（使用正斜杠路径！）、构建 parts 载荷、执行 POST、捕获 x-ms-operation-id（使用 --verbose 并将输出写入文件），并轮询 LRO，直至成功终止。

10. 清理流程中创建的所有临时文件。

关于报表端验证的说明：发布后，没有可靠的编程方式可以确认报表是否正确呈现 — 报表位于 Fabric 服务 URL，视觉呈现需要浏览器会话。向用户提供工作区/报表 URL，以便他们在浏览器中验证。

修改 Fabric 中的现有报表

1. 进行身份验证 → 参见 COMMON-CLI.md § 身份验证方案
2. 查找工作区 → 按名称解析工作区 ID
3. 列出/查找报表 → 按名称解析报表 ID
4. 下载定义 → getDefinition?format=PBIR → 轮询 LRO → 将各部分解码为本地文件
5. 创作 PBIR 内容 → 所有更改都使用 powerbi-report-authoring 技能。这涵盖所有文件：definition.pbir、report.json、version.json、pages.json、页面配置、视觉对象、筛选器、格式设置、主题和表达式。遵循其指南，确保结构、架构和字段值正确。使用其 CLI 工具进行验证。切勿凭记忆或猜测构造任何 PBIR JSON。
6. 上传更改 → 将所有本地文件重新编码为 base64 → 使用所有部分（已修改和未修改）执行 updateDefinition
7. 清理 → 删除工作流中创建的所有临时本地文件和目录

在 Fabric 中创建新报表

1. 进行身份验证 → 请参阅 COMMON-CLI.md § 身份验证方案
2. 查找工作区 → 按名称解析工作区 ID
3. 解析语义模型 → 查找语义模型 ID 和工作区名称，用于 definition.pbir 连接字符串
4. 验证语义模型绑定 → 下载目标语义模型定义（TMDL），并将所有 PBIR Entity、queryRef、nativeQueryRef 和筛选器引用与目标表/列名称进行比较。如果名称不同但结构匹配，则重新映射所有带表限定符的绑定。如果模型在结构上不同，则在继续之前征求用户意见——说明不匹配之处，并询问是否要重新编写受影响的绑定
5. 编写 PBIR 内容 → 使用 powerbi-report-authoring 技能从头生成完整的 PBIR 定义——definition.pbir、report.json、version.json、pages.json、页面配置和所有视觉对象。切勿凭记忆或猜测构造任何 PBIR JSON。
6. 上传 → 将所有文件编码为 base64 → 使用 displayName 和所有定义部分执行 POST /reports
7. 清理 → 删除临时本地文件

故障排查

错误	原因	修复方法
401 Unauthorized	--resource 受众错误或缺失	始终传入 --resource "https://api.fabric.microsoft.com"
403 Forbidden	权限不足	检查工作区角色（写入操作需 Contributor 或更高权限）
404 Not Found	工作区或报表 ID 错误	通过 List API 重新解析 ID
CorruptedPayload	base64 格式错误或 PBIR JSON 无效	重新编码文件；编码前验证 JSON
202 但没有结果	LRO 未轮询至完成	实现 LRO 轮询模式
OperationNotSupportedForItem	报表带有加密的敏感度标签	无法获取加密报表的定义
ItemDisplayNameAlreadyInUse	工作区中存在重名项	使用唯一的显示名称
format: "PBIR-Legacy"	报表创建于 PBIR 成为默认格式之前	此技能不支持 PBIR-Legacy
发布后视觉对象为空／没有数据	PBIR 实体名称与工作区语义模型表名称不匹配（例如，本地 CSV 表名称与工作区表名称不同）	下载目标语义模型 TMDL，比较表名称，并更新所有 Entity、queryRef、nativeQueryRef 和筛选器引用以使其匹配
创建／更新时出现 MissingDefinitionParts，即使已包含所有文件	定义部分路径使用反斜杠（definition\report.json）——Fabric API 要求使用正斜杠。在 Windows 上，path.join() 默认会生成反斜杠。	上传前将负载中的所有 path 值规范化为使用正斜杠（例如，在 Node.js 中使用 .replace(/\\\\/g, '/')，或在 PowerShell 中使用 .Replace('\\', '/')）。
创建后工作区中出现重复报表	收到 202 Accepted 响应后重试了创建 POST。每次重试都可能创建新报表。	收到 202 后，绝不要重试创建 POST。有关可靠的操作 ID 捕获和恢复步骤，请参阅 LRO 部分。使用 Delete Report API 删除重复项。
通过模型交接发布本地 .pbip 后视觉对象为空	语义模型创作技能可能会在部署期间重命名或转换表／列，因此新部署模型的 TMDL 与报表的 PBIR 绑定不再匹配。	针对已部署模型重新运行 TMDL 差异验证（按照 MUST 语义模型解析完成后验证绑定），并通过 powerbi-report-authoring 技能重新映射发生偏移的绑定。
发布后视觉对象为空，尽管 TMDL 差异检查无误	definition.pbir 中的 byConnection 仍指向过期的模型 ID（例如来自 .pbi/ 缓存或之前发布的模型），而非新解析的模型 ID。	重新执行发布本地 .pbip的第 7 步，将 byConnection 设置为实际解析出的 semanticModelId，然后重新发布。
用户要发布本地模型，但无法使用语义模型创作技能	当前会话中未加载语义模型创作技能。	告知用户，并退回到连接现有模型的分支——重新询问要将报表绑定到哪个工作区模型。不要静默地继续执行。
模型发布到一个工作区，报表却 POST 到另一个工作区	未提前确认工作区，或模型部署和报表发布使用了两个不同的工作区。	严格遵守单一工作区规则（发布本地 .pbip的第 2 步）。恢复方法：将报表重新发布到模型所在的工作区，或移动模型。