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:

No menu de navegação, selecione Projects » Notebooks.
Abra seu notebook.
Selecione o ícone no canto superior direito do notebook.
Selecione Notebook settings e depois selecione External access.
Ative as EAIs que você deseja habilitar para o notebook.

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.