omni-admin

Omni 管理

Omni インスタンスを管理します — 接続、ユーザー、グループ、ユーザー属性、権限、スケジュール、スキーマの更新。

ヒント：ほとんどの管理エンドポイントでは、個人用アクセストークンではなく組織 API キーが必要です。

前提条件

# 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 ルールを参照してください。

CLI プロファイルがなく、環境に認証情報が設定されている場合は、明示的に渡してください。

omni <command> --base-url "$OMNI_BASE_URL" --token "$OMNI_API_TOKEN"

コマンドの確認

omni scim --help             # User and group management
omni schedules --help        # Schedule operations
omni connections --help      # Connection management
omni documents --help        # Document permissions
omni folders --help          # Folder permissions
omni ip-allowlist --help     # Organization IP allowlist (CLI ≥ 1.5.0)
omni scim users-create --schema   # Print a command's args, flags, body schema + example, and response shape (no token)

ヒント：プログラムで解析するために構造化出力を強制するには -o json を、読みやすい表形式で出力するには -o human を使用してください。デフォルトは auto です（TTY では人間向け、パイプに渡す場合は JSON）。

管理操作の安全なデフォルト

• 作成操作では、まず依頼された作成を試してください。リソースがすでに存在するために API が競合を返した場合は、そのリソースを検索し、依頼された状態と完全に一致することを確認してから成功を報告してください。
• 書き込み後の確認では、成功ステータスのレスポンスだけでなく、作成または変更した特定のリソースを調べてください。
• コンテンツへのアクセスを更新する際は、Omni の権限 API が返すロール名（VIEWER、EXPLORER、EDITOR、MANAGER）を使用してください。

接続

# List connections
omni connections list

# Schema refresh schedules
omni connections schedules-list <connectionId>

# Connection environments (create, update <id>, delete <id>)
omni connections connection-environments-create --schema

コミット署名キーのローテーション（CLI ≥ 1.1.2）

ローテーションすると以前のキーは無効になります。実行前にユーザーに確認し、以前のキーが信頼されていた場所すべてに新しい公開鍵を再登録してください。

# Rotate a connection's dbt commit signing key
omni connections dbt-rotate-signing-key <connectionId>

# Rotate a model's git commit signing key
omni models git-rotate-signing-key <modelId>

ユーザー管理（SCIM 2.0）

以下の --body ブロックは使用例です。フィールドの正確な一覧（型、必須項目、列挙値）を確認するには、これらの形式が網羅的だと想定せず、omni scim users-create --schema のようにコマンドに --schema を付けて実行してください。

# List users
omni scim users-list

# Find by email
omni scim users-list --filter 'userName eq "[email protected]"'

# Create user
omni scim users-create --body '{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "[email protected]",
  "displayName": "New User",
  "active": true,
  "emails": [{ "primary": true, "value": "[email protected]" }]
}'

# Deactivate user
omni scim users-update <userId> --body '{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "Operations": [{ "op": "replace", "path": "active", "value": false }]
}'

# Delete user
omni scim users-delete <userId>

グループ管理（SCIM 2.0）

# List groups
omni scim groups-list

# Create group
omni scim groups-create --body '{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "Analytics Team",
  "members": [{ "value": "user-uuid-1" }]
}'

# Add members
omni scim groups-update <groupId> --body '{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "Operations": [{ "op": "add", "path": "members", "value": [{ "value": "new-user-uuid" }] }]
}'

ユーザー属性

# List attributes (system + custom)
omni user-attributes list

# Create a custom attribute definition (CLI ≥ 1.4.0)
omni user-attributes create --body '{
  "name": "region",
  "label": "Region",
  "type": "String",
  "description": "User region for row-level security filtering",
  "default_value": "us-east"
}'

omni user-attributes update <id> --body '{ "default_value": "us-west" }'
omni user-attributes delete <id>

# Find the user by email before setting an attribute
omni scim users-list --filter 'userName eq "[email protected]"'

# Set attribute on user (via SCIM)
omni scim users-update <userId> --body '{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "Operations": [{
    "op": "replace",
    "path": "urn:omni:params:1.0:UserAttribute:region",
    "value": "West Coast"
  }]
}'

ユーザー属性は、行レベルセキュリティのためにトピック内の access_filters と連携します。 SCIM で値を設定できるのは、すでに存在する属性定義のみです。値を設定する前に omni user-attributes list を使って、依頼された属性定義が存在することを確認してください。ただし、これを特定のユーザーの値が変更された証拠として使用しないでください。定義がない場合は、omni user-attributes create（CLI ≥ 1.4.0）で作成し、値を割り当てる前に作成を確認してください。SCIM パスを繰り返し試したり、空の User attributes set: {} レスポンスを根拠に値が設定されたと主張したりしないでください。

定義の管理には Manage User Attributes 権限が必要です。命名規則と型のルールは --help に記載されており、違反すると明示的にエラーになります。ただし、次の 2 つの動作は明示されません。

• delete <id> は定義以外にも影響しますが、レスポンスにはその旨が示されません。 すべてのユーザー値も削除されます。その名前を使っている埋め込み SSO ログインは完全に失敗し（埋め込み環境から締め出されます）、これを参照するモデル SQL は壊れ、その名前で環境を選択する接続は警告なくデフォルトの接続にフォールバックします。モデル内でその名前を検索し、事前にユーザーに確認してください。
• Number の値は文字列として保存されます。また、2^53 - 1 を超える JSON 数値は入力時に警告なく丸められます。たとえば、9007199254740993 の default_value は "9007199254740992" として保存され、返されます。大きな数値は文字列として送信してください。

ユーザーがユーザー属性の設定または更新を明示的に依頼した場合、最初のユーザー検索で依頼された値がすでに表示されていても、SCIM 更新でユーザーレコードを依頼内容に一致させてください。これにより、依頼された管理操作を実行しつつ、操作を冪等に保てます。

切り替え可能な属性値（CLI ≥ 1.5.0）

属性をプロビジョニングすると、ユーザーまたはグループは、実行時に指定された値のリストから切り替えられるようになります（動的な共有拡張機能、アクセスフィルター、接続環境のルーティング）。呼び出し元が選択した値は、割り当て済みの値と同様にこれらの機能を制御するため、プロビジョニングによって、ユーザーがすでに持っているアクセス権を超えるアクセス権が付与されることはありません。

# Admin: list / set the values a user or group may switch to.
# GET uses --user-id or --group-id flags; the PUT body carries user_id or group_id (not both).
omni user-attributes user-attribute-selectable-values-get <attributeId> --user-id <membershipId>
omni user-attributes user-attribute-selectable-values-update <attributeId> --body '{
  "user_id": "<membershipId>",
  "values": ["us-east", "us-west"],
  "allow_any_value": false
}'

# Caller self-service: list switchable attributes, switch one, or clear the switch
omni user-attributes user-attribute-selections-list
omni user-attributes user-attribute-selection-update --body '{ "user_attribute_id": "<attributeId>", "values": ["us-west"] }'
omni user-attributes user-attribute-selection-delete --user-attribute-id <attributeId>

user-attribute-selection-update / -delete で変更されるのは、呼び出し元自身の切り替え設定です。組織 API キーは作成者として動作するため、管理者がこれらを使って別のユーザーの値を切り替えることはできません。コマンドは成功し、管理者自身の値が変更されます。

allow_any_value: false のときに空の values 配列を送信すると、プロビジョニングが完全に削除されます。その結果、ユーザーがすでに設定した切り替えも適用されなくなります。行レベルセキュリティのために切り替え後の値を利用しているユーザーのプロビジョニングを解除する前に、依頼者に確認してください。

モデルのロールと呼び出し元のアクセス権

モデルやコンテンツの変更先を決める前に、omni whoami whoami --model-id <modelId> を実行し、rolesByModel[<id>].permissions の権限に基づいて判断してください。ロールはカスタム名または内部コードで表示される場合があります。QUERY_FULL_MODEL は呼び出し元がブランチを作成できることを示し、UPDATE は共有モデルにマージできることを示します（この権限がない場合は、PR を作成するかマージを依頼してください）。USE_WORKBOOKS はコンテンツを作成できることを示します。USE_WORKBOOKS はあるが QUERY_FULL_MODEL がない呼び出し元（Restricted Querier）は、ドキュメントのワークブックモデルにある既存のビューのみを変更でき、すべてのタイルをトピック上に作成する必要があります。そのため、このユーザー向けにトピック、結合、アクセス権付与の変更を計画しないでください。権限の完全な一覧、判断基準、ロール割り当てコマンド（メンバーシップ ID で指定し、本文のキーには roleName を使用）は、references/model-roles.md に記載されています。

ドキュメントの権限

# Check effective permissions for a user (userId required)
omni documents get-permissions <documentId> --user-id <userId>

# List document access principals
omni documents access-list <documentId>

# Add direct access for a group
omni documents add-permits <documentId> --body '{
  "permissions": [{ "type": "group", "id": "group-uuid", "access": "view" }]
}'

# Add direct access for a user
omni documents add-permits <documentId> --body '{
  "userIds": ["user-uuid"],
  "role": "EDITOR"
}'

role は NO_ACCESS、VIEWER、EDITOR、MANAGER のいずれかです。

アクセスブースト

アクセスブーストを使うと、Viewer および Restricted Querier ロールのユーザーが、ダッシュボード上でトピックを使用していないタイル（生の SQL またはベースビューへの直接クエリ）を表示できます。ワークブックのアクセス制限はそのまま維持されます。アクセス制御が緩和されるため、依頼者に意図を確認し、対象のユーザーまたはグループとタイルで公開される内容を明示してください。また、organizationAccessBoost より特定のユーザーまたはグループを優先してください。 組織側の前提条件、コマンド、アクセス権付与との併用方法については、references/access-boost.md を参照してください。

フォルダーの権限

# Get
omni folders get-permissions <folderId>

# Set
omni folders add-permissions <folderId> --body '{
  "userGroupIds": ["group-uuid"],
  "role": "VIEWER"
}'

スケジュール

# List schedules
omni schedules list

# Create schedule (default entity is "dashboard", so omitting it delivers the dashboard)
omni schedules create --body '{
  "identifier": "dashboard-identifier",
  "name": "Weekly Dashboard - Monday 9am PT",
  "schedule": "0 9 ? * MON *",
  "timezone": "America/Los_Angeles",
  "destinationType": "email",
  "format": "pdf",
  "subject": "Weekly dashboard",
  "recipients": ["[email protected]"]
}'

# Deliver a workbook tab instead of the dashboard (CLI ≥ 1.5.0).
# Set entity: "workbook" and pass the tab via queryIdentifierMapKey; default stays entity: "dashboard".
# `schedules update` does not take entity, so changing what a schedule delivers means creating a new one.
# filterConfig, containerPages and singleColumnLayout apply to dashboard deliveries only.
# Find these later with: omni schedules list --content-type "workbook tab"
omni schedules create --body '{
  "identifier": "document-identifier",
  "name": "Weekly Pipeline Tab",
  "schedule": "0 9 ? * MON *",
  "timezone": "America/Los_Angeles",
  "destinationType": "email",
  "entity": "workbook",
  "queryIdentifierMapKey": "<tabKey>",
  "format": "xlsx",
  "subject": "Pipeline tab",
  "recipients": ["[email protected]"]
}'

# Manage recipients for an existing schedule
omni schedules recipients-get <scheduleId>

omni schedules add-recipients <scheduleId> --body '{ "recipients": ["[email protected]"] }'

schedules update はパッチではなく、全項目の置き換えです。いずれの場合も "success": true が返されます。指定しなかったオプションのプロパティはデフォルトにリセットされます。フィルター値は消去され、アラート条件は削除され、maxRowLimit と表示フラグはデフォルトに戻ります。リセットされるすべてのプロパティは --help に記載されています。

schedules get の出力をそのまま再送信することはできません。 読み取り時と書き込み時で形式が異なります。GET では表示オプションが metadata の下にネストされ、宛先は destinations[] の下にありますが、更新本文では subject、maxRowLimit、recipients、destinationType をフラットに指定します。GET の出力をそのまま戻すと、destinationType に関する 400 エラーになります。omni schedules update --schema をもとに本文を作成し、保持する値をすべて引き継いでください。

メール専用ユーザーとは、配信の受信のみを目的として登録された宛先です。omni users list-email-only / create-email-only / create-email-only-bulk と delete-email-only-bulk を使用します（CLI ≥ 1.4.0）。一括削除は設計上、一部のみ成功する場合があります。200 のレスポンスには deleted[] と notFound: {emails: [], userIds: []} の両方が含まれるため、完了を報告する前にステータスではなく、この2つの配列を確認してください。

AI クレジット

omni ai credit-controls-* コマンドは、組織、ユーザー、エンティティグループの AI クレジット制御を読み取り、更新します。omni ai credit-usage-* コマンドは現在の請求期間の使用状況を読み取り、credit-usage-users-read にはメンバーシップ ID を指定します。必要な権限、CLI のバージョン、機能フラグ、使用例については、references/ai-credits.md を参照してください。

カラーパレット

omni color-palettes は、組織のカスタムチャートパレットを管理します（CLI ≥ 1.3.1）。書き込みには Manage Config 権限が必要です。更新すると、そのパレットを使用するすべてのチャートの色が変わります。削除すると、それらのチャートは組織のデフォルトパレットに戻ります。どちらの場合も、変更されたチャートは報告されません。使用例と命名規則については、references/color-palettes.md を参照してください。

アップロード

omni uploads は、ユーザーがウェアハウスデータとともにクエリするためにアップロードした CSV ファイルとスプレッドシートを一覧表示、作成、置換、削除します。create と replace-data では、ファイルパスを --file で指定します。replace-data はアップロード ID を維持するため、モデルやドキュメントを変更しなくても、ビューとドキュメントタブで新しいデータが提供されます。列名が変更または削除されると、それらの列を使うコンテンツが動作しなくなる可能性があるため、先にヘッダーを比較してください。フラグ、--body 形式、使用例については、references/uploads.md を参照してください。

変更後の検証

管理操作は、失敗や部分的な適用があっても通知されないことがあります。書き込み後は必ず状態を読み戻し、変更が反映されたことを確認してください。

ユーザー操作後

# After creating or updating a user, verify they exist with correct state
omni scim users-list --filter 'userName eq "[email protected]"'

次の点を確認してください。active が設定した値と一致していること、displayName が正しいこと、ユーザー ID が返されており、エラーではないこと。

グループ操作後

# After creating a group or modifying members, verify membership
omni scim groups-list

次の点を確認してください。グループが期待する displayName で存在し、members 配列に期待するユーザー UUID が含まれていること。

権限変更後

# After setting document permissions, verify the principal and role
omni documents access-list <documentId>

# For a specific user, also check effective permissions
omni documents get-permissions <documentId> --user-id <userId>

# After setting folder permissions, verify
omni folders get-permissions <folderId>

次の点を確認してください。プリンシパルが一覧にあり、role が設定した値（VIEWER、EDITOR など）と一致していること。

ユーザー属性の変更後

# Verify the user's assigned attribute value was set
omni scim users-list --filter 'userName eq "[email protected]"'

次の点を確認してください。応答に対象ユーザーが含まれており、そのユーザーの urn:omni:params:1.0:UserAttribute オブジェクトに要求した属性名が含まれ、 値が設定した値と完全に一致していること。

属性定義を変更した後（user-attributes create ／ update ／ delete）は、 omni user-attributes list で読み戻してください。Number のデフォルト値は 文字列として返されるため、文字列として比較してください。

属性が行レベルセキュリティ（access_filters）に使われている場合は、対象ユーザーとしてクエリを実行してテストしてください。

omni query run --body '{ "query": { ... }, "userId": "<target-user-uuid>" }'

結果が正しくフィルタリングされていることを確認してください。ユーザーには、自分の属性値に一致する行だけが表示されるはずです。

スケジュール操作後

# Verify schedule was created with correct settings
omni schedules list -o json

# Verify recipients were added
omni schedules recipients-get <scheduleId>

次の点を確認してください。作成したスケジュール ID が一覧に表示され、返されたフィールドが要求した schedule cron、timezone、destinationType、entity、format、およびドキュメントの identifier と一致していること。一覧または取得の応答形式を解析できない場合、解析結果が空であることを成功として黙って扱わず、スケジュール設定の検証は決定的でなかったと報告してください。受信者は必ず recipients-get で確認してください。

IP 許可リスト（CLI ≥ 1.5.0）

omni ip-allowlist get ／ update は、組織の IP 許可リスト（適用の有無、サポートと SCIM のバイパス、メモ付きの許可アドレス）を読み取り、書き込みます。組織管理者のアクセス権が必要です。許可リストが有効でエントリがない状態になる場合、または許可リストが有効で呼び出し元自身のアドレスをブロックする場合、更新は拒否されます。ロックアウトされた組織は API では修復できません。

omni ip-allowlist get
# Every field is optional; `entries` replaces the whole list.
omni ip-allowlist update --body '{
  "enabled": true,
  "entries": [
    { "address": "203.0.113.0/24", "note": "office" },
    { "address": "198.51.100.42",  "note": "VPN exit" }
  ]
}'

update の前に get で現在の状態を確認し、報告時には追加または削除するアドレスを明記してください。不適切なエントリによって、サポート以外のすべてのユーザーがロックアウトされる可能性があります。また、サーバーはユーザーを締め出す書き込みも受け付けます。

キャッシュと検証

omni models cache-reset はモデルのキャッシュポリシーをリセットし、omni models content-validator-get はダッシュボードとタイル全体で壊れたフィールド参照を見つけます（--branch-id を指定すると、ブランチの変更によってどの項目に問題が生じるかを表示します）。また、omni models git-get はモデルの Git 設定を返します。使用例と完全検証フラグについては、references/cache-and-validation.md を参照してください。

ドキュメントリファレンス

各管理領域に対応する Omni のドキュメントページについては、references/docs-links.md を参照してください。

関連スキル

• omni-model-builder — アクセス制御の適用対象となるモデルを編集します
• omni-content-explorer — 権限を設定する前にドキュメントを探します
• omni-content-builder — 配信をスケジュールする前にダッシュボードを作成します
• omni-embed — 埋め込みダッシュボード用の埋め込みユーザーとユーザー属性を管理します