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 キーまたは 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 では human、パイプ経由では 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 呼び出しでは、id ではなく必ず identifier フィールドを使ってください。ワークブックタイプのドキュメントでは 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 キーを使用する場合は、3 つの呼び出しすべてに同じ --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 は、クエリごとに 1 つの CSV を含む ZIP ファイルです）。ユーザーがクエリを実行できないモデルのクエリは、エラーなしでファイルから除外されます。そのため、シートが欠けている場合はジョブの失敗ではなく、アクセス権の問題です。

アラート

アラートとは、既存のダッシュボード上の 1 つのタイルに条件を設定したスケジュールです。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 — ドキュメントとフォルダーの権限を管理します