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 precisa criar uma regra de rede e uma integração de acesso externo. Uma integração de acesso externo 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 integração de acesso externo:

• Usar a concessão automatizada de privilégios para solicitar privilégios do consumidor para criar uma integração de acesso externo.

• Adicionar uma integração de acesso externo 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 aplicativos para integrações de acesso externo¶

O fluxo de trabalho geral para configurar um aplicativo para usar uma integração de acesso externo é o seguinte:

1. Os provedores configuram a concessão automatizada de privilégios para o aplicativo. Isso permite que os consumidores deem permissão a um aplicativo para criar a integração de acesso externo.

   Nota

   As especificações de aplicativo exigem que manifest_version = 2 seja definido no arquivo de manifesto.

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, conforme necessário:

   • 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. Ao configurar o aplicativo, os consumidores aprovam as portas do host e outros serviços externos. Para mais informações sobre como os consumidores visualizam e aprovam especificações de aplicativos, consulte Aprovar conexões com recursos externos usando especificações de aplicativo.

Definição de especificação de aplicativo para integrações de acesso externo¶

Para uma integração de acesso externo, a definição de especificação de aplicativo 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¶

Para habilitar a concessão automatizada de privilégios para um aplicativo, defina a versão no início do arquivo de manifesto, conforme mostrado no exemplo a seguir:

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 external access integration to connect to an external service."
...

Usando manifest_version: 2, quando o aplicativo é instalado ou atualizado, o Snowflake concede automaticamente o privilégio CREATE EXTERNAL ACCESS INTEGRATION para o aplicativo.

Adicionar uma regra de rede e integração de acesso externo ao script de configuração¶

Integrações de acesso externo são os objetos Snowflake que permitem o acesso a locais de rede externos específicos. As integrações de acesso externo 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;

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, um consumidor concederá permissão para o aplicativo usar esses domínios ou portas.

Criação de uma integração de acesso externo¶

Para criar uma integração de acesso externo para um aplicativo, adicione o comando CREATE EXTERNAL ACCESS INTEGRATION ao script de configuração, como 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;

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

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

O exemplo a seguir mostra uma função definida pelo usuário que usa a integração de acesso externo 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;

Essa função define o valor de EXTERNAL_ACCESS_INTEGRATIONS para a integração de acesso externo criada anteriormente.

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

Criar uma especificação de aplicativo para uma integração de acesso externo¶

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

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 configura o aplicativo para criar a regra de rede, a integração de acesso externo e a especificação do aplicativo, os consumidores podem visualizar a especificação e aprová-la ou rejeitá-la conforme necessário no momento de configuração do aplicativo. Para obter mais informações, consulte Aprovar conexões com recursos externos usando especificações de aplicativo.