作用域修饰符将 API 作用域缩小到其操作的子集。 要添加修饰符,请将其附加在作用域名称后面的冒号后面,例如 clusters:read。 没有修饰符的作用域允许该作用域中的每个操作。
你可以在以下内容中使用作用域修饰符:
- 有范围的个人访问令牌
- 服务主体标识的 OAuth 范围限定密钥
-
无论你以用户身份认证、以服务主体身份认证,还是通过工作负载身份联合交换身份提供者令牌,
scope都是 OAuth 令牌请求的参数
有关完整的作用域列表及每个作用域涵盖的 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 中,改为用 + 分隔作用域。