Solicitação de integrações de acesso externo (EAIs) com especificações do aplicativo¶

Acesso a pontos de extremidade externos a partir de um aplicativo¶

Para acessar um ponto de extremidade externo, um aplicativo deve criar uma regra de rede e uma EAI, que usa regras de rede para restringir o acesso a locais de rede externos específicos. As regras de rede definem os pontos de extremidade externos que um aplicativo pode acessar.

Para configurar um aplicativo para usar uma EAI, siga estas etapas:

• Para solicitar privilégios do consumidor para criar uma EAI, use a concessão automática de privilégios.

• Adicione uma EAI a um aplicativo.

• Usar especificações de aplicativo para solicitar permissões do consumidor para se conectar a um ponto de extremidade externo.

Fluxo de trabalho de especificação de aplicativo para uma EAI¶

1. Os provedores configuram a concessão automatizada de privilégios para o aplicativo. Isso permite que os consumidores concedam permissão a um aplicativo para criar a EAI.

   Nota

   App specifications require that manifest_version: 2 be set in the manifest file.

2. Os provedores adicionam o privilégio CREATE EXTERNAL ACCESS INTEGRATION ao arquivo de manifesto.

3. Os provedores adicionam instruções SQL ao script de configuração para criar os seguintes objetos:

   • Regra de rede

   • Integração de acesso externo

   • Especificação de aplicativo

   O script de configuração cria a especificação de aplicativo e outros objetos quando o aplicativo é instalado ou atualizado ou está no tempo de execução.

4. When configuring the app, consumers review and approve the host ports and external services. For more information on how consumers view and approve app specifications, see Approve app specifications.

Definição da especificação do aplicativo para uma EAI¶

A definição da especificação do aplicativo para uma EAI contém as seguintes entradas:

• HOST_PORTS: uma lista de portas host definidas na regra de rede que o aplicativo requer.

• PRIVATE_HOST_PORTS: uma lista de portas de host que permitem se conectar a recursos fora do Snowflake de forma privada.

Definição da versão do arquivo de manifesto¶

To enable automated granting of privileges for an app, set the version at the beginning of the manifest file as shown in the following example:

manifest_version: 2

Adicionar o privilégio CREATE EXTERNAL ACCESS INTEGRATION ao arquivo de manifesto¶

O privilégio CREATE EXTERNAL ACCESS INTEGRATION permite que o aplicativo crie uma integração de acesso externo durante a instalação ou atualização.

• Para configurar um aplicativo para solicitar o privilégio CREATE EXTERNAL ACCESS INTEGRATION, adicione o seguinte código à seção privileges do arquivo de manifesto:

  manifest_version: 2
  ...
  privileges:
    - CREATE EXTERNAL ACCESS INTEGRATION:
        description: "Allows the app to create an EAI to connect to an external service."
  ...
  

  Copy

Se você definir manifest_version como 2 no arquivo de manifesto, o Snowflake concederá automaticamente o privilégio CREATE EXTERNAL ACCESS INTEGRATION ao aplicativo durante a instalação ou atualização.

Adicione uma regra de rede e uma EAI ao script de configuração¶

EAIs são os objetos do Snowflake que permitem o acesso a locais de rede externos específicos e contêm uma lista de regras de rede que especificam os locais externos que um aplicativo pode acessar.

• Para criar uma regra de rede para um aplicativo, adicione o comando CREATE NETWORK RULE ao script de configuração, como mostrado no exemplo a seguir:

  CREATE OR REPLACE NETWORK RULE setup.my_network_rule
  TYPE = HOST_PORT
  VALUE_LIST = ( 'example.com' )
  MODE = EGRESS;
  

  Copy

As propriedades HOST_PORT e VALUE_LIST indicam que a regra de rede deve apontar para um domínio, porta ou intervalo de portas válido. Quando um aplicativo é instalado ou atualizado, os consumidores concedem permissão para que o aplicativo use esses domínios ou portas.

Criar uma EAI¶

• Para criar uma EAI para um aplicativo, adicione o comando CREATE EXTERNAL ACCESS INTEGRATION ao script de configuração, conforme mostrado no exemplo a seguir:

  CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION my_app_prefix_eai_rule
    ALLOWED_NETWORK_RULES = (setup.my_network_rule)
    ENABLED = TRUE;
  

  Copy

Criação de uma função definida pelo usuário para acessar o ponto de extremidade externo¶

Após a criação da EAI, o script de configuração pode criar funções definidas pelo usuário e procedimentos armazenados que o utilizam para se conectar aos pontos de extremidade definidos na regra de rede.

O exemplo a seguir mostra uma função definida pelo usuário que utiliza a EAI my_app_prefix_eai_rule:

CREATE OR REPLACE FUNCTION setup.EXTERNAL_ACCESS_UDF(hostname STRING)
  RETURNS STRING
  LANGUAGE JAVA
  HANDLER='TestHostNameLookup.compute'
  EXTERNAL_ACCESS_INTEGRATIONS = (my_app_prefix_eai_rule)
  AS
  '
      import java.net.InetAddress;
      import java.net.UnknownHostException;
      class TestHostNameLookup {{
          public static String compute(String hostname) throws Exception {{
              InetAddress addr = null;
              try {
                  addr = InetAddress.getByName(hostname);
              } catch(UnknownHostException ex) {
                  return "Hostname lookup failed";
              }
              return "Hostname lookup successful";
          }
      }
';
GRANT USAGE ON FUNCTION setup.EXTERNAL_ACCESS_UDF(STRING)
  TO APPLICATION ROLE app_public;

Esta função define o valor de EXTERNAL_ACCESS_INTEGRATIONS para a EAI criada anteriormente.

Essa função utiliza o pacote Java InetAddress para pesquisar o nome de host passado para o procedimento. O nome do host fornecido deve corresponder a um dos valores fornecidos na propriedade VALUE_LIST das regras de rede usadas pela EAI.

Criação de uma especificação de aplicativo para uma EAI¶

O exemplo a seguir mostra como criar uma especificação de aplicativo para uma EAI:

ALTER APPLICATION SET SPECIFICATION eai_app_spec
  TYPE = EXTERNAL_ACCESS
  LABEL = 'Connection to an external API'
  DESCRIPTION = 'Access an API that exists outside Snowflake'
  HOST_PORTS = ('example.com')

Esse comando cria uma especificação de aplicativo chamada eai_app_spec.

Aprovação da especificação do aplicativo na conta do consumidor¶

Depois que o provedor configurar o aplicativo para criar a regra de rede, a EAI e a especificação do aplicativo, os consumidores poderão visualizar a especificação do aplicativo e aprová-la ou não conforme apropriado ao configurar o aplicativo. Para obter mais informações, consulte Approve app specifications.