Criação e uso de uma integração de acesso externo¶

Criação de uma regra de rede para representar o local da rede externa¶

Você pode usar o comando CREATE NETWORK RULE para criar uma regra de rede que represente a localização da rede externa e as restrições de acesso. Por exemplo, uma regra de rede especifica identificadores de rede, como um nome de host e a direção da comunicação com a rede (entrada ou saída).

Para oferecer suporte ao acesso a uma rede externa, um administrador incluirá a regra ao criar uma integração de acesso externo. Cada regra incluída na integração especifica um local de rede externo que a função ou procedimento tem permissão para acessar.

Ao criar uma regra de rede para uso em uma integração de acesso externo, você especifica o seguinte:

• EGRESS como o valor do parâmetro MODE.

• HOST_PORT como o valor do parâmetro TYPE.

• O ponto de extremidade do local externo no parâmetro VALUE_LIST.

• (Opcional) Um número de porta com o nome do ponto de extremidade do local externo. Se você omitir um número de porta, o Snowflake usará o número de porta padrão para acesso externo, 443.

  Por exemplo, se o ponto de extremidade exigir a porta 80, o parâmetro VALUE_LIST poderá ser o seguinte:

  VALUE_LIST = ('example.com:80')
  

  Copy

CREATE OR REPLACE NETWORK RULE google_apis_network_rule
  MODE = EGRESS
  TYPE = HOST_PORT
  VALUE_LIST = ('translation.googleapis.com');

Criação de um segredo para representar credenciais¶

Você pode usar CREATE SECRET para criar um segredo que representa as credenciais necessárias para autenticação no local de rede externo. Por exemplo, o segredo pode conter credenciais como nome de usuário e senha.

Para acessar um local de rede externo compatível com OAuth, uma prática recomendada é fazer com que seu segredo contenha uma referência a uma integração de segurança que contenha valores necessários para o fluxo de OAuth, como um ID do cliente, segredo do cliente, ponto de extremidade do token e assim por diante.

O segredo será usado das seguintes maneiras:

• Por um administrador ao criar a integração de acesso externo.

  Ao criar a integração, o administrador especificará os segredos que os desenvolvedores podem usar no código do manipulador ao criar uma função ou procedimento que utilize a integração.

• Por um desenvolvedor ao criar um manipulador de procedimento ou UDF.

  O desenvolvedor especificará o segredo permitido que contém as credenciais que o código do manipulador pode usar para autenticar ao fazer uma solicitação ao local externo. Ao escrever um manipulador, um desenvolvedor pode usar uma API Snowflake para recuperar credenciais contidas no segredo em vez de incluir as credenciais como valores literais no código do manipulador.

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

CREATE OR REPLACE SECRET bp_maps_api
  TYPE = GENERIC_STRING
  SECRET_STRING = 'replace-with-your-api-key';

Criação de uma integração de acesso externo¶

Você pode usar o comando CREATE EXTERNAL ACCESS INTEGRATION para criar uma integração de acesso externo que agregue regras de rede permitidas (representando locais de rede externos) e segredos permitidos (representando credenciais para autenticação) para uso com UDFs e procedimentos.

Em particular, a integração de acesso externo especifica as regras e segredos de rede que as UDFs e os procedimentos que fazem referência à integração podem usar.

A integração de acesso externo será usada por um administrador para gerenciar o acesso a locais de rede externos de UDFs e procedimentos. A integração especifica apenas os locais e credenciais permitidos para uso por UDFs e os procedimentos que fazem referência à integração. Um administrador também pode ativar ou desativar a integração para gerenciar o acesso a locais externos.

CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION google_apis_access_integration
  ALLOWED_NETWORK_RULES = (google_apis_network_rule)
  ALLOWED_AUTHENTICATION_SECRETS = (oauth_token)
  ENABLED = true;

Uso da integração de acesso externo em uma função ou procedimento¶

Ao usar o comando CREATE FUNCTION ou CREATE PROCEDURE para criar uma UDF ou procedimento, você pode ativar o acesso a locais de rede externos da seguinte forma:

• Inclua o parâmetro EXTERNAL_ACCESS_INTEGRATIONS, definindo seu valor para uma ou mais integrações.

  Cada integração especificada permite acesso aos locais de rede externos e aos segredos especificados pela integração.

• Inclua o parâmetro SECRETS, definindo seu valor como um ou mais segredos e os nomes que você usará para acessá-los no código do manipulador.

  Os segredos especificados como valores também devem ser especificados na integração de acesso externo.

• No código do manipulador, acesse o segredo para recuperar credenciais para autenticação no local de rede externo.

O Snowflake limita o número total de conexões que podem ser feitas a partir de uma UDF específica. Para evitar problemas de esgotamento de recursos, reutilize as conexões tanto quanto possível. Você pode conseguir isso criando o cliente ou a sessão TCP uma vez durante a inicialização da UDF e, em seguida, usando-o no manipulador da UDF para o restante da consulta.

CREATE OR REPLACE FUNCTION google_translate_python(sentence STRING, language STRING)
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = 3.8
HANDLER = 'get_translation'
EXTERNAL_ACCESS_INTEGRATIONS = (google_apis_access_integration)
PACKAGES = ('snowflake-snowpark-python','requests')
SECRETS = ('cred' = oauth_token )
AS
$$
import _snowflake
import requests
import json
session = requests.Session()
def get_translation(sentence, language):
  token = _snowflake.get_oauth_access_token('cred')
  url = "https://translation.googleapis.com/language/translate/v2"
  data = {'q': sentence,'target': language}
  response = session.post(url, json = data, headers = {"Authorization": "Bearer " + token})
  return response.json()['data']['translations'][0]['translatedText']
$$;