CREATE EXTERNAL ACCESS INTEGRATION¶

Cria uma integração de acesso externo para acesso a locais de rede externos a partir de uma UDF ou manipulador de procedimento.

Consulte também:: ALTER EXTERNAL ACCESS INTEGRATION , DROP INTEGRATION , SHOW INTEGRATIONS , DESCRIBE INTEGRATION

Sintaxe¶

CREATE [ OR REPLACE ] EXTERNAL ACCESS INTEGRATION <name>
  ALLOWED_NETWORK_RULES = ( <rule_name_1> [, <rule_name_2>, ... ] )
  [ ALLOWED_API_AUTHENTICATION_INTEGRATIONS = ( <integration_name_1> [, <integration_name_2>, ... ] ) ]
  [ ALLOWED_AUTHENTICATION_SECRETS = ( <secret_name_1> [, <secret_name_2>, ... ] ) ]
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]

Copy

Parâmetros obrigatórios¶

name

Identificador para integração de acesso externo.

O valor do identificador deve começar com um caractere alfabético e não pode conter espaços ou caracteres especiais, a menos que toda a cadeia de caracteres do identificador esteja entre aspas duplas (por exemplo, "My object"). Os identificadores delimitados por aspas duplas diferenciam letras maiúsculas de minúsculas.

Para obter mais detalhes, consulte Requisitos para identificadores.

ALLOWED_NETWORK_RULES = (rule_name [ , rule_name ... ])

Especifica as regras de rede permitidas. Somente regras de saída podem ser especificadas.

Para obter informações de referência sobre regras de rede, consulte CREATE NETWORK RULE.

ENABLED = { TRUE | FALSE }

Especifica se esta integração está habilitada ou desabilitada. Se a integração estiver desabilitada, qualquer código do manipulador que dependa dela não conseguirá alcançar o local da rede externa.

O valor não diferencia maiúsculas e minúsculas.

O padrão é TRUE.

Parâmetros opcionais¶

ALLOWED_API_AUTHENTICATION_INTEGRATIONS = ( integration_name_1 [, integration_name_2, ... ] )

Especifica as integrações de segurança cujo servidor de autorização OAuth emitiu o segredo usado pela UDF ou procedimento. A integração de segurança deve ser do tipo usado para integração de API externa.

Para obter informações de referência sobre integrações de segurança, consulte CREATE SECURITY INTEGRATION (Autenticação de API externa).

ALLOWED_AUTHENTICATION_SECRETS = (secret_name [ , secret_name ... ])

Especifica os segredos que uma UDF ou procedimento pode usar ao se referir a esta integração.

Para obter informações de referência sobre segredos, consulte CREATE SECRET.

COMMENT = 'string_literal'

Especifica um comentário para a integração de acesso externo.

Padrão: sem valor

Requisitos de controle de acesso¶

Uma função usada para executar este comando SQL deve ter os seguintes privilégios no mínimo:

Privilégio	Objeto	Notas
CREATE INTEGRATION	Conta	Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.
USAGE	Segredo	Obrigatório para todos os segredos referenciados pela integração.
USAGE	Esquema	Obrigatório para todos os esquemas que contêm segredos referenciados pela integração.

Para instruções sobre como criar uma função personalizada com um conjunto específico de privilégios, consulte Criação de funções personalizadas.

Para informações gerais sobre concessões de funções e privilégios para executar ações de SQL em objetos protegíveis, consulte Visão geral do controle de acesso.

Notas de uso¶

Em relação aos metadados:

Atenção

Os clientes devem garantir que nenhum dado pessoal (exceto para um objeto do usuário), dados sensíveis, dados controlados por exportação ou outros dados regulamentados sejam inseridos como metadados ao usar o serviço Snowflake. Para obter mais informações, consulte Campos de metadados no Snowflake.

Exemplos¶

Crie uma integração de acesso externo que forneça acesso ao Google Translation API.

Para um exemplo mais completo, consulte Criação e uso de uma integração de acesso externo.

Crie um segredo representando credenciais.

Para criar um segredo, você deve ter recebido uma função com o privilégio CREATE SECRET no esquema atual. Para outros tipos de segredo suportados por este comando, consulte CREATE SECRET. Neste exemplo, google_translate_oauth refere-se a uma integração de segurança. Para obter mais informações, consulte CREATE SECURITY INTEGRATION (Autenticação de API externa).
```
CREATE OR REPLACE SECRET oauth_token
  TYPE = OAUTH2
  API_AUTHENTICATION = google_translate_oauth
  OAUTH_REFRESH_TOKEN = 'my-refresh-token';
```
Copy
Conceda privilégios READ no segredo à função developer para que os desenvolvedores da UDF possam usá-la.

Crie a função que será necessária para os desenvolvedores que precisam usar o segredo.
```
USE ROLE USERADMIN;
CREATE OR REPLACE ROLE developer;
```
Copy
Conceda o privilégio READ à função developer.
```
USE ROLE SECURITYADMIN;
GRANT READ ON SECRET oauth_token TO ROLE developer;
```
Copy

Crie uma regra de rede representando o local da rede externa. Use uma função com os privilégios descritos em CREATE NETWORK RULE.

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

Copy

Crie uma integração de acesso externo usando o segredo e a regra de rede.

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

Copy

Conceda privilégios USAGE na integração à função developer para que os desenvolvedores da UDF possam usá-la.
```
GRANT USAGE ON INTEGRATION google_apis_access_integration TO ROLE developer;
```
Copy

Crie uma UDF google_translate_python que traduza o texto especificado em uma frase no idioma especificado. Para obter mais informações, consulte Uso da integração de acesso externo em uma função ou procedimento.

USE ROLE developer;

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']
$$;

Copy

Conceda o privilégio USAGE na função google_translate_python para que aqueles com a função de usuário possam chamá-la.
```
GRANT USAGE ON FUNCTION google_translate_python(string, string) TO ROLE user;
```
Copy

Execute a função google_translate_python para traduzir uma frase.

USE ROLE user;
SELECT google_translate_python('Happy Thursday!', 'zh-CN');

Copy

Isso gera a seguinte saída.

-------------------------------------------------------
| GOOGLE_TRANSLATE_PYTHON('HAPPY THURSDAY!', 'ZH-CN') |
-------------------------------------------------------
| 快乐星期四！                                          |
-------------------------------------------------------