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 块是示例。有关权威字段列表（类型、必填项、枚举值），请使用 --schema 运行命令，例如 omni scim users-create --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，违反规则时会明确报错。但有两种情况不会：

• delete <id> 会删除定义之外的内容，且响应不会说明这一点。 所有用户值都会随之删除，仍通过名称传递该属性的嵌入式 SSO 登录会 直接失败（导致嵌入式登录被锁定），引用该属性的模型 SQL 会出错， 而按该名称选择环境的连接会悄然回退到默认连接。请在模型中搜索该名称， 并先征得用户确认。
• Number 值会以字符串形式存储，而大于 2^53 - 1 的 JSON 数字 在传入时会被静默舍入 — default_value 为 9007199254740993 时， 存储并返回的值会是 "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 密钥以其创建者的身份操作，因此管理员无法用这些命令切换其他用户的值；命令会成功，但更改的是管理员自己的值。

发送一个空的 values 数组并设置 allow_any_value: false，会完全移除该属性配置，同时也会停止遵循用户已设置的切换值。如果用户依赖切换值实现行级安全，请在清除该用户的属性配置前先与请求者确认。

模型角色与调用者访问权限

在决定模型或内容变更应如何处理之前，运行 omni whoami whoami --model-id <modelId>，并根据 rolesByModel[<id>].permissions 中的权限作出判断，因为角色可能显示为自定义名称或内部代码：QUERY_FULL_MODEL 表示调用者可以创建分支，UPDATE 表示调用者可以将其合并到共享模型（没有此权限时，应创建 PR 或请求合并），而 USE_WORKBOOKS 表示调用者可以创建内容。拥有 USE_WORKBOOKS 但没有 QUERY_FULL_MODEL 的调用者（受限查询者）只能更改文档工作簿模型中已有的视图，并且必须基于主题构建每个图块，因此不要为其规划主题、联接或访问授权变更。完整权限表、决策规则以及角色分配命令（以成员资格 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 和受限查询者在仪表板上查看该仪表板中非主题图块（原始 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: []}，因此报告完成前请检查这两个数组，而不是只看状态码。

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 相符。如果列表或 get 响应的结构无法解析，请报告日程设置验证结果不明确，不要悄悄地将空解析结果视为成功。务必使用 recipients-get 验证收件人。

IP 允许列表（CLI ≥ 1.5.0）

omni ip-allowlist get / update 用于读取和写入组织的 IP 允许列表，包括是否启用强制执行、支持和 SCIM 绕过设置，以及带备注的允许地址。需要 organization admin 访问权限。如果更新会导致允许列表在启用状态下没有任何条目，或启用状态下的列表会屏蔽调用者自己的地址，则更新会被拒绝——无法通过 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" }
  ]
}'

更新前请使用 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 — 管理嵌入式仪表板的嵌入用户和用户属性