在 Notebooks in Workspaces 中使用密钥

工作区笔记本中的密钥支持

在 Workspaces 中运行的 Snowflake 笔记本可以结合使用 密钥对象 和外部访问集成 (EAIs)，从而确保凭据不会以字面量形式出现在笔记本代码中。您可以通过 SQL（例如在工作表中）配置密钥和 EAIs；然后将它们附加到 Notebook 服务、排程器或 EXECUTE NOTEBOOK PROJECT 调用中。

先决条件：设置密钥和外部访问

在 Snowflake 笔记本中使用密钥之前，请先配置底层安全对象和网络规则。这些步骤在笔记本外部执行（例如，在 Snowflake 工作表中）。

基本密钥设置

要使用现有密钥，请运行 SHOW SECRETS （例如，SHOW SECRETS IN ACCOUNT;）。要创建新密钥，请使用 CREATE SECRET。

备注

将示例中的 SNOWPUBLIC 和 NOTEBOOKS 替换为您的数据库和模式。

-- Example: creating a GENERIC_STRING secret
CREATE OR REPLACE SECRET SNOWPUBLIC.NOTEBOOKS.MY_SECRET_STRING
  TYPE = GENERIC_STRING
  SECRET_STRING = 'your_api_key_here';

其他常见的密钥类型包括：

  • PASSWORD，这需要同时提供 USERNAME 和 PASSWORD。

  • OAUTH2，用于与外部提供商（例如，GitHub）进行集成。

外部访问集成 (EAI)

要允许笔记本在调用公共互联网时使用密钥，请连接 网络规则 和一个 外部访问集成。

-- 1. Create a network rule to allow egress traffic
CREATE OR REPLACE NETWORK RULE my_api_rule
  MODE = EGRESS
  TYPE = HOST_PORT
  VALUE_LIST = ('api.example.com:443');

-- 2. Create the integration that bridges the rule and the secret
CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION my_api_eai
  ALLOWED_NETWORK_RULES = (my_api_rule)
  ALLOWED_AUTHENTICATION_SECRETS = (SNOWPUBLIC.NOTEBOOKS.MY_SECRET_STRING)
  ENABLED = TRUE;

高级身份验证 (OAuth)

对于基于 OAuth 的提供商，创建 安全集成，并使用 SYSTEM$START_OAUTH_FLOW 完成手动 OAuth 流程（且在同一会话中执行 SYSTEM$FINISH_OAUTH_FLOW）。该流程允许 Snowflake 与外部提供商交换令牌。有关端到端示例，请参阅 外部网络访问示例 和 为 Snowflake Notebooks 设置外部访问。

具有密钥的笔记本服务集成

您可以在笔记本 创建、编辑 和 排程器 对话框中选择密钥。

  1. 在导航菜单中，选择 Projects » Workspaces。

  2. 打开 Notebooks，然后开始 :ui:`Create service`（或编辑现有服务）。

  3. 在 Service settings 中，附加外部访问集成，并从下拉列表中选择一个或多个密钥。您可以附加多个密钥。

  4. 确认服务成功启动，然后使用 Python 单元格，通过 Snowpark 密钥 API 或下方示例中所示的挂载路径来读取密钥。

备注

如果完全限定的密钥名称包含特殊字符（例如 SNOWPUBLIC.NOTEBOOKS."my secret 1"），Snowflake 会对 Python 和容器中使用的路径进行规范化处理。密钥 名称 段中的连字符、空格和类似字符将变为下划线。数据库和模式段不区分大小写。

示例：SNOWPUBLIC.NOTEBOOKS."my secret 1" 在 Python 辅助函数中显示的路径为 :code:`snowpublic/notebooks/my_secret_1`（请根据密钥的存储位置调整数据库和模式）。

密钥文件在 Snowflake 提供的容器内挂载于 /secrets/ 下。例如，通用字符串密钥可能出现在：

/secrets/snowpublic/notebooks/my_secret_1/secret_string

请将 snowpublic 和 notebooks 替换为您存储密钥的数据库和模式。数据库、模式和密钥名称匹配不区分大小写。

Snowpark 库为每种密钥类型提供了不同的辅助函数，如下所示。

从 Python 单元格中调用 GENERIC_STRING 密钥

from snowflake.snowpark.secrets import get_generic_secret_string

secret_1 = get_generic_secret_string('snowpublic/notebooks/my_secret_1')
print(secret_1)

print('Reading from the container mount path:')
print(open('/secrets/snowpublic/notebooks/my_secret_1/secret_string').read())

从 Python 单元格中调用 PASSWORD 密钥

from snowflake.snowpark.secrets import get_username_password

creds = get_username_password('snowpublic/notebooks/my_password_secret')
print('Username: ', creds.username)
print('Password: ', creds.password)

print('Container mount path:')
print(open('/secrets/snowpublic/notebooks/my_password_secret/username').read())
print(open('/secrets/snowpublic/notebooks/my_password_secret/password').read())

从 Python 单元格中调用 OAUTH2 密钥

from snowflake.snowpark.secrets import get_oauth_access_token

token = get_oauth_access_token('_/_/github_secret')
print(token)

print('Reading from the container mount path:')
print(open('/secrets/_/_/github_secret/access_token').read())

请将 _/_/github_secret 替换为您 OAuth2 密钥的规范化路径（数据库/模式/名称），遵循与上文相同的规则。

使用密钥调度笔记本

当您在 Snowsight 中调度笔记本时，请在调度对话框中添加调度任务所需的 EAIs 和密钥，以便“无头运行”模式能够继承与交互式开发相同的外部访问权限和凭据。

使用 EXECUTE NOTEBOOK PROJECT 和密钥进行非交互式运行

当笔记本依赖 EAIs 和密钥时，无头运行必须列出这两者。通过 EXTERNAL_ACCESS_INTEGRATIONS 传递集成，并通过 SECRETS 传递密钥。有关完整语法，请参阅 EXECUTE NOTEBOOK PROJECT。

EXECUTE NOTEBOOK PROJECT "<database_name>"."<schema_name>"."<project_name>"
  MAIN_FILE = 'notebook.ipynb'
  COMPUTE_POOL = '<compute_pool_name>'
  RUNTIME = '<runtime_version>'
  QUERY_WAREHOUSE = '<warehouse_name>'
  ARGUMENTS = '<string>'
  REQUIREMENTS_FILE = '<path/to/requirements.txt>'
  EXTERNAL_ACCESS_INTEGRATIONS = ('integration_name')
  SECRETS = ( <database_name>.<schema_name>.<secret_name> [ , ... ] );

请将占位符替换为笔记本所需的集成和完全限定的密钥。