使用范围修饰符缩小 API 范围

作用域修饰符将 API 作用域缩小到其操作的子集。 要添加修饰符,请将其附加在作用域名称后面的冒号后面,例如 clusters:read。 没有修饰符的作用域允许该作用域中的每个操作。

你可以在以下内容中使用作用域修饰符:

有关完整的作用域列表及每个作用域涵盖的 API 操作,请参见 API 作用域。

可用的修饰符

  • :read:只允许作用域的读取操作(GET 及 HEAD 请求)。 例如,clusters:read 允许列出和获取集群,但不能创建、编辑或删除它们。
  • :restricted-query:允许只读SQL查询。 此修饰符仅适用于 sql 作用域。 具有 sql:restricted-query 的令牌可以通过 Statement Execution API 以及 SQL 驱动程序和连接器运行诸如 SELECT 和 DESCRIBE 的查询。 它无法调用其他 SQL API,比如列出 SQL 仓库。 修改对象或数据的语句失败:
    • 创建、修改或删除对象(如 CREATE TABLE 和 DROP TABLE)的语句会因 [OP_NOT_SUPPORTED_READ_ONLY] ... is not supported in read-only session mode. SQLSTATE: 42KD1 而失败。
    • 修改数据的语句,如 INSERT 和 UPDATE,即使是在你拥有的表上也会因 [INSUFFICIENT_PERMISSIONS] Insufficient privileges 而失败。

要组合修饰器,请同时添加两者:sql:read:restricted-query 允许 sql 范围的读取操作,例如列出 SQL 仓库,以及只读查询。

在 UI 中选择访问级别

当您在工作区 UI 中生成个人访问令牌或 OAuth 密钥时,添加作用域后,选择其访问级别。 访问权限设置修饰符:

访问级别 已授予的范围
Read <scope>:read
读取 + 写入 <scope> (无修饰语)
受限查询 (仅限 sql) sql:restricted-query
仅限读取 + 受限查询(sql 仅限) sql:read:restricted-query
读取 + 受限查询 + 写入(仅限 sql) sql (无修饰语)

在个人访问令牌中使用修饰符

使用 Token API,将每个作用域及其修饰符作为 scopes 数组的一个项包含。 个人访问令牌不支持 all-apis:read。 要授予完整工作区访问权限,请使用空 scopes 数组(all-apis 作用域)。 请参阅 作用域内个人访问令牌。

在 OAuth 中使用修饰符

你可以将服务主体应用的 OAuth 机密绑定到带有修饰符的作用域,也可以请求带有修饰符作用域的 OAuth 访问令牌。 访问令牌不能超过其由之生成的密钥的作用域,除非该密钥具有 authentication 作用域。 参见 有作用域的 OAuth 密钥。 OAuth 也接受 all-apis:read,允许对主体被授权访问的每个 API 进行读取操作。

要请求带有修饰符的令牌,请在 scope 令牌请求的参数中列出作用域,并用空格分隔。 在用户到机器流程的授权 URL 中,改为用 + 分隔作用域。

其他资源