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.

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