Introdução ao Snowflake Native SDK for Connectors¶

Estrutura do projeto¶

O Snowflake Native SDK for Connectors consiste em várias partes, que serão descritas abaixo.

• connectors-native-sdk

Este diretório contém o código fonte e testes Snowflake Native SDK for Connectors real. Devido à natureza do aplicativo nativo dentro do código-fonte do Snowflake, não há apenas código Java, mas também um código SQL em pacote com definições de objetos de banco de dados.

O código Java está dentro do diretório src/main como para qualquer biblioteca Java regular. O mesmo vale para os testes unitários localizados dentro de src/test. Além disso, dentro do diretório src/ você pode encontrar os diretórios intTest e appTest. Esses são, respectivamente, testes de integração e de aplicativo. Ambos os tipos de teste exigem conexão a uma conta Snowflake. Os primeiros testam os componentes SDK usando objetos de banco de dados autônomos, enquanto o último implanta um aplicativo real e executa testes usando-o.

Os arquivos de origem SQL origem estão contidos dentro do diretório src/main/resources. Eles são incluídos dentro do arquivo jar ao construir o Snowflake Native SDK for Connectors. Para usá-los, eles precisam ser extraídos do jar e colocados dentro de um diretório de destino de compilação que será copiado para o estágio Snowflake dentro do pacote do aplicativo.

• connectors-native-sdk-test

Este diretório contém uma biblioteca auxiliar projetada para permitir testes de unidade mais fáceis do conector com base no Snowflake Native SDK for Connectors. Ele fornece implementações simuladas para alguns dos objetos de banco de dados, construtores de teste especialmente projetados que permitem a substituição de partes do código não disponíveis para personalização e algumas asserções personalizadas com base na biblioteca AssertJ.

Instalação e uso do SDK¶

Atualmente, a instalação e utilização do Snowflake Native SDK for Connectors exige que o desenvolvedor execute algumas ações manuais.

A biblioteca Snowflake Native SDK for Connectors está disponível via Maven Central

repositories {
    mavenCentral()
}

dependencies {
    compileOnly 'com.snowflake:connectors-native-sdk:2.0.0'
    testImplementation 'com.snowflake:connectors-native-sdk-test:2.0.0'
}

Para acessar os arquivos SQL fornecidos, eles precisam ser extraídos para o diretório de destino do aplicativo nativo. Para conseguir isso, use a seguinte definição de tarefa gradle (por enquanto, ela deve ser copiada manualmente para o arquivo build.gradle).

String defaultBuildDir = './sf_build'
String defaultSrcDir = './app'
String libraryName = 'connectors-native-sdk'

project.tasks.register('copySdkComponents') {
    it.group = 'Snowflake'
    it.description = "Copies .sql files from ${sdkComponentsDirName} directory to the connector build file."
    doLast {
        copySdkComponents(libraryName, defaultBuildDir, sdkComponentsDirName)
    }
}

private void copySdkComponents(String libraryName, String defaultBuildDir, String sdkComponentsDirName) {
    TaskLogger.info("Starting 'copySdkComponents' task...")
    def targetDir = getCommandArgument('targetDir', {defaultBuildDir})

    try {
        project.copy {
            TaskLogger.info("Copying [${sdkComponentsDirName}] directory with .sql files to '${targetDir}'")
            from project.zipTree(project.configurations.compileClasspath.find {
                it.name.startsWith(libraryName)})
            into targetDir
            include "${sdkComponentsDirName}/**"
        }
    } catch (IllegalArgumentException e) {
        Utils.exitWithErrorLog("Unable to find [${libraryName}] in the compile classpath. Make sure that the library is " +
                "published to Maven local repository and the proper dependency is added to the build.gradle file.")
    }
    project.copy {
        TaskLogger.info("Copying [${libraryName}] jar file to [${targetDir}]")
        from configurations.runtimeClasspath.find {
            it.name.startsWith(libraryName)
        }
        into targetDir
        rename ("^.*${libraryName}.*\$", "${libraryName}.jar")
    }
    TaskLogger.success("Copying sdk components finished successfully.")
}

Depois execute esta tarefa:

./gradlew copySdkComponents

Os arquivos SQL extraídos podem ser executados durante a execução do setup.sql para o aplicativo nativo.

Implantação e instalação¶

O Snowflake Native SDK for Connectors foi projetado para ser usado com o Snowflake Native App Framework. Isso significa que a implantação e a instalação acontecem da mesma forma que para qualquer outro aplicativo nativo. Isso significa que primeiro o pacote do aplicativo precisa ser criado e todos os arquivos precisam ser carregados no estágio. A recomendação é criar o estágio dentro do pacote do aplicativo. Se o script de exemplo acima foi usado, todos os arquivos necessários do Snowflake Native SDK for Connectors já devem estar presentes no diretório de compilação de destino do conector. Isso significa que cabe ao desenvolvedor garantir que o código personalizado do conector e quaisquer arquivos Streamlit também estejam lá. Para mais informações, consulte Criação de um pacote de aplicativo.

Depois que o pacote do aplicativo for criado e os arquivos forem carregados no estágio, uma version do aplicativo pode ser criada. Esta etapa é opcional durante o desenvolvimento, porque a instância do aplicativo pode ser criada diretamente dos arquivos no estágio, em vez de usar a versão registrada. Para mais informações, consulte Criação de um objeto de aplicativo.

Desenvolvimento¶

O Snowflake Native SDK for Connectors fornece objetos e procedimentos que lidam com casos de uso comuns para cada aplicativo do conector. Isso inclui coisas como configuração, ciclo de vida, definição de ingestão e assim por diante. Para rever a lista completa de recursos, consulte a referência do SDK. Algumas partes dos recursos predefinidos podem ser personalizadas. Para mais informações, consulte Personalização de procedimentos armazenados e manipuladores.

Testes¶

Como mencionado anteriormente, Connectors Native SDK contém diferentes tipos de testes. Isso inclui testes de unidade, testes de integração e os chamados testes de aplicativo. Os testes de unidade utilizam recursos fornecidos no connectors-native-sdk-test mencionado. Quanto aos testes de integração e aplicativo, eles exigem conexão com o Snowflake. Os detalhes da conexão podem ser definidos usando o arquivo .env/snowflake_credentials. O diretório de testes de do aplicativo também contém um aplicativo de conector vazio no recurso. Esse aplicativo é implantado durante a execução da suíte de testes

Recursos adicionais:

• Referência do Snowflake Native SDK for Connectors Java API

• Referência do Snowflake Native SDK for Connectors Java API TEST

• Guia de início rápido do Snowflake Native SDK para conectores

Para uma experiência prática na implementação do seu próprio conector, experimente o Tutorial: SDK nativo para conectores de modelo Java.

• Tutorial: SDK nativo para conectores de modelo Java