为 Snowflake Notebooks 设置外部访问¶

使用笔记本时，您可能需要调用外部服务，这通常需要 API 密钥等敏感凭据。为保护敏感信息，您可以使用在 Snowflake 中管理的密钥，而不是将凭据硬编码到笔记本中。

外部访问集成 (EAIs) 使用网络规则配置，可以选择使用 Snowflake 密钥进行身份验证。

默认情况下，Snowflake 限制来自外部端点的网络流量。要访问外部端点，请执行以下步骤：

创建网络规则。
创建使用该规则的外部网络访问集成。
创建用于身份验证的密钥（如需要）。通用字符串密钥还需要 EAI。
将密钥与 EAI 相关联。
将 EAI 和密钥与笔记本相关联。

备注

EAIs 和网络规则必须由组织管理员创建。有关所需权限，请参阅访问控制要求。

使用外部访问权限和密钥配置笔记本¶

此端到端示例展示了如何配置笔记本以使用通用字符串密钥访问 OpenAI API。

-- Step 1: Create a secret
CREATE SECRET openai_key
  TYPE = GENERIC_STRING
  SECRET_STRING = '<your-api-key>';

-- Step 2: Create a network rule
CREATE OR REPLACE NETWORK RULE openai_rule
  MODE = EGRESS
  TYPE = HOST_PORT
  VALUE_LIST = ('api.openai.com');

-- Step 3: Create an external access integration that uses the network rule and secret
CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION openai_integration
  ALLOWED_NETWORK_RULES = (openai_rule)
  ALLOWED_AUTHENTICATION_SECRETS = (openai_key)
  ENABLED = true;

-- Step 4: Associate the integration and secret with the notebook
ALTER NOTEBOOK my_notebook
  SET EXTERNAL_ACCESS_INTEGRATIONS = (openai_integration),
    SECRETS = ('openai_key' = openai_key);

备注

密钥必须与外部访问集成 (EAI) 和笔记本相关联。如果密钥仅与两者之一相关联，则无法通过笔记本代码访问该密钥。

在笔记本内访问密钥¶

将密钥与笔记本关联后，要在笔记本代码内访问其值，请使用 st.secrets 对象：

import streamlit as st
api_key = st.secrets['openai_key']

其他 EAI 示例¶

这些示例展示了如何为常见的数据科学和机器学习网站设置外部访问：

适用于 PyPI 的 EAI¶

CREATE OR REPLACE NETWORK RULE pypi_network_rule
MODE = EGRESS
TYPE = HOST_PORT
VALUE_LIST = ('pypi.org', 'pypi.python.org', 'pythonhosted.org', 'files.pythonhosted.org');

CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION pypi_access_integration
ALLOWED_NETWORK_RULES = (pypi_network_rule)
ENABLED = true;

适用于 Hugging Face 的 EAI¶

CREATE OR REPLACE NETWORK RULE hf_network_rule
MODE = EGRESS
TYPE = HOST_PORT
VALUE_LIST = ('huggingface.co', 'cdn-lfs.huggingface.co');

CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION hf_access_integration
ALLOWED_NETWORK_RULES = (hf_network_rule)
ENABLED = true;

授予使用外部访问集成所需的 USAGE 权限¶

创建 EAIs 之后，将集成的 USAGE 权限授予将要使用它们的角色：
```
GRANT USAGE ON INTEGRATION openai_integration TO ROLE my_notebook_role;
```

用于创建笔记本的角色必须具备 EAI 的 USAGE 权限。授予 PUBLIC 角色的 USAGE 权限将不起作用。

在 Snowsight 中启用外部访问集成¶

创建和配置 EAIs 后，重新启动笔记本会话，以便在 External Access 窗格中看到您创建的访问集成。

使用 Snowsight 启用集成的步骤如下：

In the navigation menu, select Projects » Notebooks.
打开您的笔记本。
选择笔记本右上角的图标。
选择 Notebook settings，然后选择 External access。
开启您要为笔记本启用的 EAIs。

其他身份验证示例¶

OAuth 访问令牌¶

CREATE OR REPLACE SECRET oauth_token
    TYPE = OAUTH2
    API_AUTHENTICATION = google_translate_oauth
    OAUTH_REFRESH_TOKEN = 'my-refresh-token';

# Using the secret as part of an EAI
  ALTER NOTEBOOK google_translate_test
    SET EXTERNAL_ACCESS_INTEGRATIONS=(google_translate_integration)
      SECRETS = ('cred' = oauth_token);

密钥类型：GENERIC_STRING¶

使用 GENERIC_STRING 密钥存储单个值，例如 API 密钥或令牌。

创建密钥：

CREATE SECRET sf_openai_key
  TYPE = GENERIC_STRING
  SECRET_STRING = '<string_literal>';

-- SQL: Associate the secret and EAI with the notebook
ALTER NOTEBOOK openai_test
  SET EXTERNAL_ACCESS_INTEGRATIONS = (openai_access_int),
    SECRETS = ('openai_key' = sf_openai_key);

对于 GENERIC_STRING 密钥，请通过字典或属性样式访问它们：

import streamlit as st

# Access the string value directly
my_openai_key = st.secrets['openai_key']
# or using attribute access
my_openai_key = st.secrets.openai_key

密钥类型：PASSWORD（示例：GitHub 基本身份验证）¶

使用 PASSWORD 密钥来存储用户名和密码对。这些通常是外部 APIs 基本身份验证所必需的。

在此示例中，笔记本使用 PASSWORD 密钥和外部访问集成来访问 GitHub REST API。

创建密钥：

CREATE SECRET password_secret
  TYPE = PASSWORD
  USERNAME = 'my_user_name'
  PASSWORD = 'my_password';

将密钥用作 EAI 的一部分：

ALTER NOTEBOOK github_user_info
SET EXTERNAL_ACCESS_INTEGRATIONS = (github_access_int),
    SECRETS = ('cred' = password_secret);

在代码中访问密钥：

import streamlit as st
import requests
from requests.auth import HTTPBasicAuth

# Access credentials from the secret
username = st.secrets.cred.username
password = st.secrets.cred.password

# Make an authenticated request
response = requests.get(
    'https://api.github.com/user',
    auth=HTTPBasicAuth(username, password)
)

print(response.status_code)
print(response.json())

其他资源¶

有关详细语法，请参阅外部网络访问概述。
有关使用 CREATE SECRET 的详细信息，请参阅创建表示凭据的密钥。
有关 EAIs 的其他示例，请参阅外部网络访问示例或在 Github 上为 Snowflake Notebooks 设置外部访问 (https://github.com/Snowflake-Labs/snowflake-demo-notebooks/blob/main/Access%20External%20Endpoints/Access%20External%20Endpoints.ipynb)。