omni-content-explorer

Omni 内容浏览器

通过 Omni CLI 查找、浏览和整理 Omni 内容——仪表板、工作簿和文件夹。

前提条件

# Verify the Omni CLI is installed — if not, ask the user to install it
# See: https://github.com/exploreomni/cli#readme
command -v omni >/dev/null || echo "ERROR: Omni CLI is not installed."

# Show available profiles and select the appropriate one
omni config show
# If multiple profiles exist, ask the user which to use, then switch:
omni config use <profile-name>

# Confirm the active profile is authenticated and inspect your permissions:
omni whoami whoami

身份验证：配置文件通过 API key 或 OAuth 进行身份验证。如果 whoami（或任何调用）返回 401，请交由用户处理——让用户运行 ! omni config login <profile>（OAuth 2.1 浏览器流程；在浏览器中会阻塞约 2 分钟）。在无头/CI 会话中不要自行运行 config login（没有浏览器会超时）；在本地交互式机器上则可以运行。有关配置文件设置（omni config init --auth oauth）以及如何使用 --schema 探索命令和请求正文结构，请参阅 **omni-api-conventions** 规则。

发现命令

omni content --help     # Content operations
omni documents --help   # Document operations
omni folders --help     # Folder operations

提示：使用 -o json 强制输出结构化数据，以便通过程序解析；使用 -o human 输出易读的表格。默认值为 auto（在 TTY 中输出人类可读格式，通过管道传递时输出 JSON）。

已知问题与安全默认值

• omni content list --labels <name>[,<name>] 按标签筛选 仪表板和应用（CLI ≥ 1.5.0）。如果不指定 --scope，只会返回组织内容，因此不会发出警告就遗漏带有该标签的受限内容；请使用 --scope restricted 再运行一次，以获取完整列表。对于仅工作簿文档（content list 不会返回这些文档），请改用 omni documents list --include labels -o json，并在客户端按 labels 数组筛选。
• 某些仪表板导出可能在创建任务前失败，例如出现 Cannot use 'in' operator to search for 'query_id' in ...。如果 omni dashboards download 返回错误且没有任务 ID，请勿调用 download-status，也不要声称导出已完成。请报告仪表板标识符、确切的 API 错误，以及未创建可供下载的任务。

搜索内容

对于“查找与 X 相关的仪表板”这类需求，优先使用全文搜索（CLI ≥ 1.1.2）：

omni content search --q "revenue" --limit 25

--q 关键词会与名称、描述、查询名称、文件夹名称、标签和创建者名称进行匹配。--limit 将结果数量限制在 1–25 条。每条结果都包含 identifier、name、description、folderPath、tileNames、verified 和现成的 url——直接将链接提供给用户。搜索范围包括 仪表板和应用（CLI ≥ 1.5.0）；每条结果的 type 为 dashboard 或 app，且只有仪表板结果可以安排计划。此处不会显示仅工作簿文档，因此如果目标可能没有仪表板，请改用 omni content list / omni documents list 进行筛选。

浏览内容

列出所有内容

omni content list

显示数量和标签

omni content list --include '_count,labels'

筛选与排序

# By label (CLI ≥ 1.5.0) — comma-separated label names.
# Covers dashboards and apps; workbook-only documents are not returned by content list,
# so for those fall back to `omni documents list --include labels -o json` + client-side filter.
omni content list --labels "Weekly Digest,Finance"
omni content list --labels "Weekly Digest,Finance" --scope restricted   # the default scope is organization only

# By scope
omni content list --scope organization

# Sort by popularity or recency
omni content list --sort-field favorites

omni content list --sort-field updatedAt

分页

响应中包含基于游标分页的 pageInfo。获取下一页：

omni content list --cursor <nextCursor>

处理文档

列出文档

omni documents list

# Filter by creator
omni documents list --creator-id <userId>

每个文档都包含：identifier、name、type、scope、owner、folder、labels、updatedAt、hasDashboard。

重要：API 调用始终使用 identifier 字段，而不是 id。工作簿类型文档的 id 字段为 null，会导致调用无提示地失败。

获取文档查询

获取为仪表板图块提供支持的查询定义：

omni documents get-queries <identifier>

这有助于了解仪表板的计算内容，并通过 omni-query 重新运行查询。

文件夹

# List
omni folders list

# List only the caller's favorited folders (CLI ≥ 1.5.0; org-scoped keys must also pass --user-id)
omni folders list --include onlyFavorites

# Get a single folder (CLI ≥ 1.5.0). Returns the fields the API can set;
# owner and access still come from `omni folders get-permissions <folderId>`.
# 404 means the folder does not exist *or* the caller cannot view it.
omni folders get <folderId>

# Create
omni folders create "Q1 Reports" --scope organization

标签

# List labels
omni labels list

# Find documents with a label
omni documents list --include labels -o json

# Add label to document
omni documents add-label <identifier> <labelName>

# Remove label
omni documents remove-label <identifier> <labelName>

# Add/remove labels on a folder in one atomic call (CLI ≥ 1.1.2).
# Labels must already exist in the organization.
omni folders bulk-update-labels <folderId> --body '{ "add": ["Q1"], "remove": ["Draft"] }'

收藏夹

# Favorite a document
omni documents add-favorite <identifier>

# Unfavorite a document
omni documents remove-favorite <identifier>

# Favorite a folder (CLI ≥ 1.5.0). Both calls are idempotent.
omni folders add-favorite <folderId>
omni folders remove-favorite <folderId>

仪表板和应用下载

# Start download (async)
omni dashboards download <identifier> --body '{ "format": "pdf" }'

# Poll job status only after the start command returns a job ID
omni dashboards download-status <identifier> <jobId>

格式：pdf、png

应用需单独下载（CLI ≥ 1.5.0）。omni dashboards download 用于渲染仪表板；已发布的应用则使用对应的 omni apps 系列命令。异步流程同样是 download → download-status → download-file，请求体结构也与 dashboards download 相同；任务仅对以其身份运行的用户可见，因此使用组织范围的 API 密钥时，三次调用都要传入相同的 --user-id。

omni apps download <identifier> --body '{ "format": "pdf" }'
omni apps download-status <identifier> <jobId>
omni apps download-file <identifier> <jobId>

格式：pdf、png、xlsx、csv（完整应用的 csv 是一个 ZIP 文件，其中每个查询对应一个 CSV）。用户无权查询的模型上的查询会从文件中排除，且不会报错，因此文件缺少工作表是权限问题，而不是任务失败。

警报

警报是在现有仪表板的某个图块上设置条件的日程安排：它按 cron 计划运行，且仅在条件成立时发送。任何有权为该仪表板安排日程的用户都可以创建警报，无需管理员权限。在 schedules create 请求体中添加 conditionType（RESULTS_PRESENT、RESULTS_MISSING、RESULTS_CHANGED、RESULTS_UNCHANGED）和 conditionQueryMapKey（被监视图块在 queryPresentations.data 中的键）；两者缺一不可。请先使用 omni schedules create --schema 确认字段名称。

• 警报会向他人发送消息。 创建前，请与用户确认收件人。
• 图块决定警报是否有用。 图块的设计属于构建工作：omni-content-builder → 警报可监视的图块。

条件表、创建示例和 cron 计时说明见：references/alerts.md。有关普通的定时发送和收件人，请参阅 omni-admin → 日程安排；要构建或更改被监视的图块，请参阅 omni-content-builder。

URL 模式

构建内容的直接链接：

Dashboard: {OMNI_BASE_URL}/dashboards/{identifier}
Workbook:  {OMNI_BASE_URL}/w/{identifier}

identifier 来自 API 响应中文档的 identifier 字段。找到内容后，始终向用户提供可点击的链接。

搜索模式

扫描所有文档以查找字段引用（例如进行影响分析）时，请使用游标分页，并为每份文档调用 omni documents get-queries <identifier>。并行发起多个获取查询的调用可提高效率。进行字段影响分析时，优先采用 omni-model-explorer 中的内容验证方法。

文档参考

• 内容 API · 文档 API · 文件夹 API · 标签 API · 仪表板下载 · 日程 API

相关技能

• omni-query — 运行已找到的仪表板背后的查询
• omni-content-builder — 创建或更新仪表板
• omni-embed — 在外部应用中嵌入已找到的仪表板
• omni-admin — 管理文档和文件夹的权限