CREATE EXTERNAL ACCESS 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>, ... ] | none } ) ]
  [ ALLOWED_AUTHENTICATION_SECRETS = ( { <secret_name_1> [, <secret_name_2>, ... ] | all | none } ) ]
  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.

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, ... ] | none )

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.

O valor desse parâmetro deve ser um dos seguintes:

• Um ou mais nomes de integração de segurança do Snowflake para permitir qualquer uma das integrações listadas.

• none para não permitir integrações.

Integrações de segurança especificadas por este parâmetro — bem como segredos especificados pelo parâmetro ALLOWED_AUTHENTICATION_SECRETS – são maneiras de permitir que segredos sejam usados em uma UDF ou procedimento que utiliza essa integração de acesso externo. Para obter mais informações, consulte Notas de uso.

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 ... ] | all | none )

Especifica os segredos que a UDF ou o código do manipulador de procedimentos pode usar ao acessar os locais de rede externos referenciados nas regras de rede permitidas.

O valor desse parâmetro deve ser um dos seguintes:

• Um ou mais nomes secretos do Snowflake para permitir qualquer um dos segredos listados.

• all para permitir qualquer segredo.

• none para não permitir segredos.

O parâmetro ALLOWED_API_AUTHENTICATION_INTEGRATIONS também pode especificar segredos permitidos. Para obter mais informações, consulte Notas de uso.

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¶

A função usada para executar essa operação deve ter, no mínimo, os seguintes privilégios:

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¶

• Você pode permitir que segredos sejam usados por uma UDF ou procedimento usando dois parâmetros de integração de acesso externo, conforme descrito abaixo.

  • Com o parâmetro ALLOWED_AUTHENTICATION_SECRETS. Você pode especificar segredos como valores de parâmetros ou definir o valor do parâmetro como all, permitindo que o código do manipulador use qualquer segredo.

  • Com o parâmetro ALLOWED_API_AUTHENTICATION_INTEGRATIONS. Um segredo é permitido para uso quando o próprio segredo especifica uma integração de segurança cujo nome também é especificado por este parâmetro. O segredo especifica a integração de segurança com seu parâmetro API_AUTHENTICATION. Em outras palavras, quando tanto o segredo quanto a integração de acesso externo especificam a integração de segurança, o segredo é permitido para uso em funções e procedimentos que especificam a integração de acesso externo.

  Observe que essas duas alternativas funcionam independentemente uma da outra. Um segredo é permitido se um (ou ambos) os parâmetros o permitirem, independentemente do valor especificado para o outro parâmetro. Por exemplo, definir um dos parâmetros como none não impede que um segredo especificado pelo outro parâmetro seja usado no código do manipulador.

• Embora você possa especificar regras de rede usando um nome de host, o Snowflake aplica as regras ao nível de granularidade do IP. O Snowflake não inspecionará o tráfego do seu aplicativo, portanto, é sua responsabilidade garantir que o host do local externo tenha o serviço autêntico e que não seja possível se conectar a outros serviços no mesmo host. Sempre que possível, você deve usar protocolos seguros como HTTPS e TLS ao se comunicar com terminais da Internet.

• 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.

• Instruções CREATE OR REPLACE <object> são atômicas. Ou seja, quando um objeto é substituído, o objeto antigo é excluído e o novo objeto é criado em uma única transação.

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.

1. 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

2. 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

3. 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

4. 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

5. 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

6. 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.10
   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

7. 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

8. 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') |
   -------------------------------------------------------
   | 快乐星期四！                                          |
   -------------------------------------------------------