Snowflake Native SDK for Connectors 入门

Snowflake Native SDK for Connectors 是提供通用组件的库，这些组件可用于构建 Snowflake 原生应用程序，将外部数据源中的数据引入 Snowflake。提供的组件定义连接器应用程序的推荐流程，支持自定义，并提供用于构建引入逻辑的构建块。

将 Snowflake Native SDK for Connectors 作为代码进行分发，以便在本地提取和构建。您可以从以下内容获取一些信息，帮助您熟悉 SDK 的结构，了解如何在项目中使用它、如何部署和安装应用程序以及如何在开发过程中使用它。

项目结构

Snowflake Native SDK for Connectors 由以下多个部分组成。

  • connectors-native-sdk

此目录包含实际的 Snowflake Native SDK for Connectors 源代码和测试。由于 Snowflake 源代码中的原生应用程序的特性，它不仅是 Java 代码，还是带有数据库对象定义的绑定 SQL 代码。

对于任何常规的 Java 库来说，Java 代码都位于 src/main 目录下。同样，单元测试也位于 src/test 目录下。此外，在 src/ 目录下，您还可以找到 intTest 和 appTest 目录。它们分别是集成测试和应用程序测试。这两种测试类型都需要连接到 Snowflake 账户。集成测试使用独立的数据库对象来测试 SDK 组件，而应用程序测试则部署实际的应用程序并用其运行测试。

SQL 源文件包含在 src/main/resources 目录中。在构建 Snowflake Native SDK for Connectors 时，它们会被包含在 jar 归档文件中。要使用这些文件，需要从 jar 文件中提取它们并放入构建目标目录中，该目录将被复制到应用程序包内的 Snowflake 暂存区。

  • connectors-native-sdk-test

此目录包含辅助函数库，旨在基于 Snowflake Native SDK for Connectors 更轻松地对连接器开展单元测试。它提供了一些数据库对象的模拟实施，以及专门设计的测试生成器，这些生成器允许覆盖那些无法自定义的代码部分，同时提供了基于 AssertJ 库 (https://assertj.github.io/doc/) 的自定义断言。

SDK 安装和使用

目前，安装和使用 Snowflake Native SDK for Connectors 需要开发者进行一些手动操作。

Snowflake Native SDK for Connectors 库可通过 Maven Central 访问

repositories {
    mavenCentral()
}

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

要访问提供的 SQL 文件，需要提取到原生应用程序的目标目录中。为此，请使用以下 gradle 任务定义（目前，必须将其手动复制到 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.")
}
Copy

然后，运行此任务：

./gradlew copySdkComponents
Copy

然后，可以在执行原生应用程序的 setup.sql 时执行提取的 SQL 文件。

部署和安装

Snowflake Native SDK for Connectors 旨在与 Snowflake Native App Framework 配合使用。这意味着其部署和安装的方式与任何其他原生应用程序相同。也就是说，首先需要创建应用程序包，并且所有文件都需要上传到暂存区，建议在应用程序包中创建暂存区。如果使用了上述示例脚本，则 Snowflake Native SDK for Connectors 所需的所有文件应该已经存在于连接器的目标构建目录中。这意味着开发者需要确保连接器的自定义代码和任何 Streamlit 文件也在该目录中。有关更多信息，请查看 创建应用程序包。

创建应用程序包并将文件上传到暂存区后，便可以创建应用程序的 version。在开发过程中，此步骤是可选的，因为可以直接从暂存区的文件创建应用程序实例，而不使用注册版本。有关更多信息，请查看 创建应用程序对象。

开发

Snowflake Native SDK for Connectors 为每个连接器应用提供了处理常见用例的对象和程序，包括配置、生命周期、引入定义等。要查看完整的功能列表，请参阅 SDK 参考。预定义功能的某些部分可以自定义，有关更多信息，请查看存储过程和处理程序自定义。

测试

如前所述，Connectors Native SDK 包含不同类型的测试，包括单元测试、集成测试和所谓的应用程序测试。单元测试使用上述 connectors-native-sdk-test 中提供的功能。而集成和应用程序测试则需要连接到 Snowflake。可以使用 .env/snowflake_credentials 文件定义连接的详细信息。应用程序测试目录在资源中也包含一个空的连接器应用程序。在执行测试套件期间部署该应用程序

其他资源：

有关实施您自己的连接器的实践经验，请尝试 教程：连接器 Java 模板的本机 SDK。

语言: 中文