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>' ]
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';
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;
Conceda o privilégio READ à função
developer
.USE ROLE SECURITYADMIN; GRANT READ ON SECRET oauth_token TO ROLE developer;
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');
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;
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;
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'] $$;
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;
Execute a função
google_translate_python
para traduzir uma frase.USE ROLE user; SELECT google_translate_python('Happy Thursday!', 'zh-CN');
Isso gera a seguinte saída.
------------------------------------------------------- | GOOGLE_TRANSLATE_PYTHON('HAPPY THURSDAY!', 'ZH-CN') | ------------------------------------------------------- | 快乐星期四! | -------------------------------------------------------