Tutorial: Exemplo de conector Java Snowflake Native SDK for Connectors¶

Pré-requisitos¶

Antes de começar, certifique-se de que você atende aos seguintes requisitos:

• Conhecimento básico de Java

• Conhecimento básico de Snowflake Native Apps

• Conhecimento básico de Streamlit UI

• Acesso a uma conta Snowflake com uma função ACCOUNTADMIN

• Conta GitHub com a qual é possível criar aplicativos GitHub

• MacOS ou Linux para criar o projeto e executar os scripts de implantação

Instalação do Java¶

Snowflake Native SDK for Connectors requer o Java LTS (Long-Term Support) versão 11 ou superior. Se a versão mínima exigida do Java não estiver instalada em seu computador, você deverá instalar o Oracle Java ou o OpenJDK.

Clonagem de repositório¶

Clone o repositório connectors-native-sdk em seu computador.

Configuração do Snowflake CLI¶

A ferramenta Snowflake CLI é necessária para criar, implantar e instalar o conector. Se você não tiver o Snowflake CLI em seu computador, instale-o conforme as instruções disponíveis aqui.

Após a instalação da ferramenta, você precisa configurar uma conexão com o Snowflake no arquivo de configuração.

Se você não tiver nenhuma conexão configurada, crie uma nova conexão chamada native_sdk_connection. Você pode encontrar um exemplo de conexão no arquivo deployment/snowflake.toml.

Se você já tiver uma conexão configurada e quiser usá-la com o conector, use o nome dela em vez de native_sdk_connection sempre que essa conexão for usada neste tutorial.

Connectors Native SDK Java¶

O diretório connectors-native-sdk-java contém todo o código Java do Snowflake Native SDK for Connectors, com testes de unidade e integração para os componentes do SDK. Devido à natureza dos Native Apps dentro do Snowflake, isso significa não apenas o código Java, mas também o código SQL, que é necessário para criar um aplicativo funcional. As definições dos objetos do banco de dados podem ser encontradas no diretório src/main/resources. Esses arquivos são usados durante a criação de um aplicativo para personalizar os objetos que estarão disponíveis dentro do aplicativo. No conector de exemplo, usamos o arquivo all.sql, que cria objetos para todos os recursos disponíveis. Esse arquivo será executado durante o processo de instalação da instância do aplicativo.

Connectors Native SDK Test Java¶

O diretório connectors-native-sdk-test-java contém o código-fonte de uma biblioteca auxiliar usada em testes de unidade, por exemplo, objetos usados para simular componentes específicos, asserções personalizadas etc. Esses arquivos não fazem parte do aplicativo conector.

Exemplo de conector Java GitHub¶

O conector de exemplo real está localizado no diretório examples/connectors-native-sdk-example-java-github-connector. O diretório app/ contém todos os arquivos necessários para executar o Native App:

• O diretório app/streamlit/ contém os arquivos de origem necessários para executar a Streamlit UI do conector.

• O arquivo setup.sql é executado durante a instalação do aplicativo e é responsável por criar os objetos de banco de dados necessários. Esse arquivo executará o arquivo all.sql mencionado anteriormente, bem como algum código sql personalizado.

• O arquivo manifest.yml é o manifesto do Native App. É necessário criar um pacote de aplicativo e, em seguida, a própria instância do aplicativo. Esse arquivo especifica as propriedades do aplicativo, bem como as permissões necessárias para o aplicativo.

Além disso, o diretório examples/connectors-native-sdk-example-java-github-connector contém o subdiretório src/, que contém a lógica do conector personalizado, como a implementação das classes necessárias e as personalizações dos componentes padrão do SDK.

Modelo de Connectors Native SDK¶

Um modelo de projeto Java do Gradle que usa Snowflake Native SDK for Connectors como uma dependência para ajudá-lo a criar rapidamente um novo conector. Você pode ler mais sobre isso em Tutorial: Modelo de conector Java Snowflake Native SDK for Connectors.

Desenvolvimento do conector¶

O desenvolvimento de um conector criado usando Snowflake Native SDK for Connectors é um pouco diferente do desenvolvimento de um aplicativo Java típico. Há algumas coisas que precisam ser feitas além de apenas criar os arquivos .jar a partir dos códigos-fonte. O desenvolvimento do aplicativo consiste nas seguintes etapas:

1. Cópia de componentes internos personalizados para o diretório de desenvolvimento

2. Cópia dos componentes do SDK para o diretório de desenvolvimento

Implantação do conector¶

Para implantar um Native App, um pacote de aplicativo precisa ser criado dentro do Snowflake. Depois disso, todos os arquivos do diretório sf_build precisam ser carregados no Snowflake.

Observe que, para fins de desenvolvimento, a criação de versões é opcional; uma instância de aplicativo pode ser criada diretamente a partir de arquivos preparados. Essa abordagem permite que você veja as alterações na maioria dos arquivos do conector sem recriar a versão e a instância do aplicativo.

As seguintes operações serão realizadas:

1. Criação de um novo pacote de aplicativo, se ele ainda não existir

2. Criação de um esquema e um estágio de arquivo dentro do pacote

3. Carregamento dos arquivos do diretório sf_build para o estágio (essa etapa pode levar algum tempo)

Para implantar o conector, execute o comando: snow app deploy --connection=native_sdk_connection.

Para obter mais informações sobre o comando snow app deploy, consulte snow app deploy.

O pacote de aplicativo criado agora estará visível na guia App packages, na categoria Data products, na Snowflake UI de sua conta.

Instalação do conector¶

A instalação do aplicativo é a última etapa do processo. Ele cria um aplicativo a partir do pacote de aplicativo criado anteriormente.

Para instalar o conector, execute o comando: snow app run --connection=native_sdk_connection.

Para obter mais informações sobre o comando snow app run, consulte snow app run.

O aplicativo instalado agora estará visível na guia Installed apps, na categoria Data products, no Snowflake UI de sua conta.

Atualização dos arquivos do conector¶

Se, em algum momento, você desejar modificar algum dos arquivos do conector, poderá carregar facilmente os arquivos modificados no estágio do pacote do aplicativo. O comando de upload depende de quais arquivos foram atualizados.

Antes de executar qualquer um dos comandos de atualização, você deverá copiar os novos arquivos do seu conector para o diretório sf_build executando: ./gradlew copyInternalComponents

Privilégios¶

O aplicativo requer duas permissões de nível de conta para funcionar: CREATE DATABASE e EXECUTE TASK.

O primeiro privilégio é necessário para criar um banco de dados de destino para os dados ingeridos. Esse banco de dados deve ser criado fora do aplicativo, de modo que os dados ingeridos possam permanecer intactos se o aplicativo for desinstalado. No entanto, este exemplo não oferece suporte a esse recurso, um novo banco de dados é sempre criado.

O segundo privilégio é necessário para agendar tarefas periódicas que buscarão os dados no GitHub e os salvarão no banco de dados de destino.

A concessão desses privilégios pode ser feita usando a guia de segurança ou pressionando o botão Grant privileges na tela de configuração do conector. A última opção resultará na exibição de um pop-up na tela.

Referência do warehouse¶

O conector exige um warehouse para executar e programar tarefas de ingestão. O aplicativo usará o warehouse por meio de uma referência. A referência do warehouse é definida no arquivo manifest.yml:

references:
  - WAREHOUSE_REFERENCE:
      label: "Warehouse used for ingestion"
      description: "Warehouse which will be used to schedule ingestion tasks"
      privileges: [USAGE]
      object_type: WAREHOUSE
      register_callback: PUBLIC.REGISTER_REFERENCE

A referência pode ser definida usando a guia de segurança, da mesma forma que os privilégios acima, ou pressionando o botão Choose warehouse.

Banco de dados e esquema de destino¶

Como mencionado anteriormente, o conector requer um banco de dados para armazenar os dados ingeridos. Esse banco de dados será criado, em uma etapa posterior, com o esquema especificado pelo usuário. O nome do banco de dados fica a critério do usuário, desde que o banco de dados fornecido ainda não exista.

A tela de configuração do conector concluída será semelhante a esta:

Configuração do Permission SDK¶

A autenticação OAuth2 exige que uma integração de segurança, um segredo e uma integração de acesso externo sejam criados na conta do usuário. Nosso conector usa o Native Apps Permission SDK para solicitar a criação desses objetos.

As referências para a integração de acesso externo e o segredo, que são necessários para o conector, são definidos no arquivo manifest.yml:

references:
  - GITHUB_EAI_REFERENCE:
      label: "GitHub API access integration"
      description: "External access integration that will enable connection to the GitHub API using OAuth2"
      privileges: [USAGE]
      object_type: "EXTERNAL ACCESS INTEGRATION"
      register_callback: PUBLIC.REGISTER_REFERENCE
      configuration_callback: PUBLIC.GET_REFERENCE_CONFIG
  - GITHUB_SECRET_REFERENCE:
      label: "GitHub API secret"
      description: "Secret that will enable connection to the GitHub API using OAuth2"
      privileges: [READ]
      object_type: SECRET
      register_callback: PUBLIC.REGISTER_REFERENCE
      configuration_callback: PUBLIC.GET_REFERENCE_CONFIG

Além disso, um procedimento especial precisa ser adicionado ao arquivo setup.sql. Ele é referenciado na propriedade configuration_callback para cada uma das referências apresentadas acima:

CREATE OR REPLACE PROCEDURE PUBLIC.GET_REFERENCE_CONFIG(ref_name STRING)
    RETURNS STRING
    LANGUAGE SQL
    AS
        BEGIN
            CASE (ref_name)
                WHEN 'GITHUB_EAI_REFERENCE' THEN
                    RETURN OBJECT_CONSTRUCT(
                        'type', 'CONFIGURATION',
                        'payload', OBJECT_CONSTRUCT(
                            'host_ports', ARRAY_CONSTRUCT('api.github.com'),
                            'allowed_secrets', 'LIST',
                            'secret_references', ARRAY_CONSTRUCT('GITHUB_SECRET_REFERENCE')
                        )
                    )::STRING;
                WHEN 'GITHUB_SECRET_REFERENCE' THEN
                    RETURN OBJECT_CONSTRUCT(
                        'type', 'CONFIGURATION',
                        'payload', OBJECT_CONSTRUCT(
                            'type', 'OAUTH2',
                            'security_integration', OBJECT_CONSTRUCT(
                                'oauth_scopes', ARRAY_CONSTRUCT('repo'),
                                'oauth_token_endpoint', 'https://github.com/login/oauth/access_token',
                                'oauth_authorization_endpoint', 'https://github.com/login/oauth/authorize'
                            )
                        )
                    )::STRING;
                ELSE
                    RETURN '';
            END CASE;
        END;

Para a referência de integração de acesso externo, o procedimento fornece:

• host_ports - nomes de host da fonte de dados externa, que serão acessados durante a ingestão

• secret_references - matriz de nomes de referências a segredos do OAuth

• allowed_secrets - LIST, informando ao Permission SDK para usar os segredos especificados no campo secret_references

Para a referência de segredo, o procedimento fornece:

• type - OAUTH2 no caso de nosso segredo

• security_integration - propriedades da integração de segurança criada:

  • oauth_scopes - uma lista de escopos OAuth solicitados pelo conector (se estiver usando um aplicativo GitHub, esse campo é opcional)

  • oauth_token_endpoint - ponto de extremidade do qual o token de atualização e acesso será adquirido

  • oauth_authorization_endpoint - ponto de extremidade para o qual a solicitação de autorização será enviada

Configuração do aplicativo GitHub¶

A próxima etapa é a configuração de um aplicativo GitHub na conta do usuário. Esse aplicativo será usado para conceder acesso limitado à conta, de modo que os dados possam ser ingeridos.

A primeira etapa é pressionar o botão Request access na UI do conector.

A primeira tela permite que você revise os pontos de extremidade para os quais a conectividade externa será permitida.

Depois de pressionar Next - você verá uma segunda tela. Selecione OAuth2 para criar uma nova integração e segredo e copie o URL do redirecionamento fornecido - ele conterá o nome de sua organização e a região de sua conta.

Em seguida, vá para a página de configurações da conta GitHub, depois para Developer settings > GitHub Apps e pressione o botão New GitHub App:

1. Digite o nome e o URL da página inicial do seu aplicativo

2. Cole o URL de redirecionamento que você copiou no campo Callback URL

3. Certifique-se de que a opção Expire user authorization tokens esteja selecionada

4. Certifique-se de que o site Request user authorization (OAuth) during installation não esteja selecionado

5. Se você não precisar dele, desmarque a opção Active na seção Webhook

6. Selecione as permissões necessárias para que o conector funcione:

   1. Repository permissions > Issues com o acesso Read-only

   2. Repository permissions > Metadata com o acesso Read-only

7. Se o aplicativo for usado apenas por você, com este exemplo de conector, é melhor selecionar Only on this account na seção de acesso à instalação

Depois que o aplicativo for criado, pressione a opção Install app na barra lateral esquerda e instale o aplicativo em sua conta. Você pode escolher quais repositórios o aplicativo (e, com isso, o conector) poderá acessar. Sem essa instalação, o conector só conseguirá acessar repositórios públicos.

Configuração da integração do OAuth¶

Após a instalação, retorne ao aplicativo GitHub e gere um novo segredo de cliente. Certifique-se de copiá-lo imediatamente, pois ele não será exibido novamente. Cole o segredo do cliente no popup de configuração do OAuth do seu conector. Por fim, copie o ID do cliente (não o ID do aplicativo) do seu aplicativo e cole-o também no pop-up de configuração do OAuth do seu conector.

Depois de pressionar Connect, será exibida uma janela do GitHub solicitando a autorização do aplicativo na sua conta GitHub. Após a autorização, você será automaticamente redirecionado para a UI do conector. Após a autorização bem-sucedida (pode levar alguns segundos para concluir e fechar o pop-up), a página será preenchida com os IDs de integração de acesso externo e referências de segredo.

Pressionar o botão Connect acionará o procedimento TEST_CONNECTION dentro do conector. Este procedimento tentará acessar o ponto de extremidade GitHub API octocat, para verificar se a conectividade externa foi configurada corretamente e se o token de acesso do OAuth foi obtido corretamente.

Se o teste for bem-sucedido, o aplicativo passará para a etapa de finalização.