Configurar acesso externo para o Snowflake Notebooks¶
Ao trabalhar com notebooks, talvez você precise chamar serviços externos, que geralmente exigem credenciais confidenciais, como as chaves de API. Para manter as informações confidenciais seguras, você pode usar segredos gerenciados no Snowflake em vez de codificar as credenciais no notebook.
Integrações de acesso externo (EAIs) são configuradas usando regras de rede e podem, opcionalmente, usar segredos do Snowflake para autenticação.
Por padrão, o Snowflake restringe o tráfego de rede de pontos de extremidade externos. Para acessar ponto de extremidade externos, siga estas etapas:
Crie uma regra de rede.
Crie uma integração de acesso à rede externa que use a regra.
Crie um segredo para autenticação (se necessário). Os segredos de uma cadeia de caracteres genérica também exigem uma EAI.
Associe o segredo à EAI.
Associe a EAI e o segredo ao notebook.
Nota
EAIs e as regras de rede devem ser criadas por um administrador da organização. Para obter os privilégios necessários, consulte Requisitos de controle de acesso.
Configurar um notebook com acesso externo e segredos¶
Este exemplo de ponta a ponta mostra como configurar um notebook para acessar a OpenAI API usando uma cadeia de caracteres secreta genérica.
-- 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);
Nota
Os segredos devem ser associados tanto à integração de acesso externo (EAI) quanto ao notebook. Se um segredo estiver associado a apenas um, ele não poderá ser acessado pelo código do notebook.
Acessar o segredo dentro de um notebook¶
Depois de associar o segredo ao notebook, para acessar seu valor no código do notebook, use o objeto
st.secrets
:
import streamlit as st
api_key = st.secrets['openai_key']
Exemplos de EAI adicionais¶
Esses exemplos mostram como definir o acesso externo para sites comuns de ciência de dados e machine learning.
EAI para PyPI¶
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;
EAI para Hugging Face¶
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;
Conceder privilégios USAGE para usar integrações de acesso externo¶
Depois que você criar EAIs, conceda o privilégio USAGE na integração às funções que as utilizarão:
GRANT USAGE ON INTEGRATION openai_integration TO ROLE my_notebook_role;
A função usada para criar o notebook deve ter USAGE na EAI. Conceder USAGE à função PUBLIC não funcionará.
Habilitar as integrações de acesso externo na Snowsight¶
Após criar e provisionar EAIs, reinicie a sessão do notebook para ver as integrações de acesso que você criou no painel External Access.
Para habilitar as integrações usando a Snowsight:
Exemplos adicionais de autenticação¶
Token de acesso 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);
Tipo de segredo: GENERIC_STRING¶
Use um segredo GENERIC_STRING
para armazenar um único valor, como uma chave ou token de API.
Crie o segredo:
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);
Para segredos GENERIC_STRING, acesse-os por dicionário ou estilo de atributo:
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
Tipo de segredo: PASSWORD (exemplo: autorização básica do GitHub)¶
Use um segredo PASSWORD
para armazenar um par de nome de usuário e senha. Eles geralmente são necessários para a autenticação básica com APIs externas.
Nesse exemplo, o notebook acessa a GitHub REST API usando um segredo PASSWORD
e uma integração de acesso externo.
Crie o segredo:
CREATE SECRET password_secret
TYPE = PASSWORD
USERNAME = 'my_user_name'
PASSWORD = 'my_password';
Use o segredo como parte de uma EAI:
ALTER NOTEBOOK github_user_info
SET EXTERNAL_ACCESS_INTEGRATIONS = (github_access_int),
SECRETS = ('cred' = password_secret);
Acesse o segredo em seu código:
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())
Recursos adicionais¶
Para obter a sintaxe detalhada, consulte Visão geral do acesso à rede externa.
Para obter detalhes sobre o uso de CREATE SECRET, consulte Criação de um segredo para representar credenciais.
Para obter exemplos adicionais de EAIs, consulte Exemplos de acesso à rede externa ou Configuração de acesso externo para o Snowflake Notebooks no Github.