使用 Snowflake REST APIs 指定 Snowflake 上下文¶

在向 Snowflake REST APIs 发起请求时，您可以指定 Snowflake 上下文的各个方面。

通过请求标头，您可以在 REST API 调用上下文中指定以下内容：

用于通过 X-Snowflake-Role 标头授权请求的 Snowflake 角色。
用于通过 X-Snowflake-Warehouse 标头执行请求的 Snowflake 仓库。

这些标头无需依赖用户的默认设置，即可让每次调用变得明确、独立且可审计。您可以保证每次请求都使用正确的角色和仓库，而无需额外调用 API 来设置上下文。

通过在发起 REST API 请求时指定上下文，您可以完成以下操作：

运行无状态调用。

保证调用使用指定角色，而无需先单独调用 API 来设置会话上下文。
避免修改用户设置。

可根据每次请求安全切换角色，而不是运行 ALTER USER ... SET DEFAULT_ROLE=...，因为那样既慢又会影响该用户的其他所有会话。
启用按需计算能力。

允许没有默认仓库的用户或服务账户，只需提供 X-Snowflake-Warehouse 标头即可运行查询或创建存储过程。
简化用户管理。

使用授予多个角色的一个服务用户。例如，READER 和 WRITER。然后，您的应用程序发送 X-Snowflake-Role 标头，为特定任务选择合适的权限。通过这种方式，您可以避免管理多个单角色用户。

优先级¶

如果提供了标头，其优先级高于用户的默认设置，顺序如下：

使用标头（如果提供）。
否则，使用会话的默认角色或默认仓库。
如果在需要时两者都不可用，则调用失败。

指定在授权请求时使用的角色¶

您可以通过使用 X-Snowflake-Role 标头来指定授权请求时使用的角色。

要求¶

您指定的角色必须存在、已授予给用户，并且该角色必须被正在使用的身份验证方法允许。
如果您使用 :ref:` 编程访问令牌 (PAT) <label-sfrest_authenticating_pat>`，则请求的角色必须在 PAT 的 ROLE_RESTRICTION 范围内。如果您指定的角色权限高于 PAT 所允许的范围，即使用户已被授予该角色，请求也会失败。

示例¶

以下示例演示了如何使用 ACCOUNTADMIN 角色进行授权创建数据库，而不受用户默认角色的影响。

您可以用双引号指定 X-Snowflake-Role 标头的值，也可以不用。

curl -X POST "$API_BASE/database/databases" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Snowflake-Role: ACCOUNTADMIN" \
  -d '{"name": "HDR_DEMO_DB", "comment": "Created via REST with role header"}'

指定语句执行所使用的仓库¶

您可以通过 X-Snowflake-Warehouse 标头指定执行语句时使用的仓库。此类语句包括执行存储过程、创建 Python 函数，以及执行需要计算资源的查询。

要求¶

当前生效的角色必须在该仓库上拥有 USAGE 权限。
如果未设置默认仓库且省略此标头，则依赖仓库的调用将失败。

示例¶

以下示例演示如何创建一个使用 BUILD_WH 仓库的 Python 存储过程。指定的角色必须在该仓库上拥有 USAGE 权限。创建的 PYTHON_WH_TEST 存储过程会返回当前活动仓库的名称。

您可以用双引号指定 X-Snowflake-Warehouse 标头的值，也可以不用。

curl -X POST "$API_BASE/procedure/databases/TEST_DB/schemas/TEST_SCHEMA/procedures" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Snowflake-Role: ACCOUNTADMIN" \
  -H "X-Snowflake-Warehouse: BUILD_WH" \
  -d '{
        "name": "PYTHON_WH_TEST",
        "arguments": [],
        "return_type": {"datatype": "VARIANT", "nullable": true},
        "language_config": {
          "python_function": {
            "handler":"main",
            "runtime_version":"3.11",
            "packages":["snowflake-snowpark-python"]
          }
        },
        "body": "def main(session):\n    return {\"warehouse\": session.get_current_warehouse()}"
      }'