Erste Schritte mit dem Snowflake Native SDK for Connectors

Das Snowflake Native SDK for Connectors ist eine Bibliothek, die universelle Komponenten bereitstellt, mit denen Sie eine native Snowflake-App erstellen können, die Daten aus einer externen Datenquelle in Snowflake erfasst. Die bereitgestellten Komponenten definieren den empfohlenen Ablauf der Konnektor-Anwendung, ermöglichen die Anpassung und bieten Bausteine für den Aufbau der Datenaufnahmelogik.

Das Snowflake Native SDK for Connectors wird als Code verteilt, der lokal abgezogen und erstellt werden soll. Im Folgenden finden Sie einige Informationen, die Sie mit der Struktur von SDK vertraut machen, wie Sie es in Ihrem Projekt verwenden, wie Sie eine Anwendung bereitstellen und installieren und wie Sie es während der Entwicklung einsetzen.

Projektstruktur

Das Snowflake Native SDK for Connectors besteht aus mehreren Teilen, die im Folgenden beschrieben werden.

  • connectors-native-sdk

Dieses Verzeichnis enthält den eigentliche Snowflake Native SDK for Connectors-Quellcode und die Tests. Aufgrund der Natur der nativen Apps innerhalb von Snowflake besteht der Quellcode nicht nur aus Java-Code, sondern auch aus gebündeltem SQL-Code mit Definitionen von Datenbankobjekten.

Der Java-Code befindet sich im Verzeichnis src/main wie bei jeder normalen Java-Bibliothek. Dasselbe gilt für die Unit-Tests, die sich innerhalb von src/test befinden. Außerdem finden Sie im Verzeichnis src/ die Verzeichnisse intTest und appTest. Dabei handelt es sich um Integrations- bzw. Anwendungstests. Beide Testtypen erfordern eine Verbindung zu einem Snowflake-Konto. Erstere testen die SDK-Komponenten unter Verwendung von eigenständigen (standalone) Datenbankobjekten, während letztere eine tatsächliche Anwendung bereitstellen und Tests mit dieser durchführen.

SQL-Quelldateien sind im Verzeichnis src/main/resources enthalten. Sie werden beim Erstellen des Snowflake Native SDK for Connectors in das jar-Archiv aufgenommen. Um sie zu verwenden, müssen sie aus dem jar extrahiert und in ein Build-Zielverzeichnis gelegt werden, das in den Snowflake-Stagingbereich innerhalb des Anwendungspakets kopiert wird.

  • connectors-native-sdk-test

Dieses Verzeichnis enthält eine Hilfsbibliothek, die das Unit-Testen des Konnektors auf Basis des Snowflake Native SDK for Connectors erleichtert. Es bietet Mock-Implementierungen für einige der Datenbankobjekte, speziell entwickelte Testbuilder, die das Überschreiben von Teilen des Codes ermöglichen, die nicht für Anpassungen verfügbar sind, sowie einige kundenspezifische Assertionen, die auf der AssertJ-Bibliothek basieren.

Installation und Nutzung des SDK

Derzeit erfordert die Installation und Nutzung des Snowflake Native SDK for Connectors einige manuelle Eingriffe durch den Entwickler.

Die Snowflake Native SDK for Connectors-Bibliothek ist über Maven Central verfügbar.

repositories {
    mavenCentral()
}

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

Um auf die bereitgestellten SQL-Dateien zugreifen zu können, müssen diese in das Zielverzeichnis der nativen App extrahiert werden. Um dies zu erreichen, verwenden Sie die folgende Gradle-Aufgabendefinition (sie muss derzeit noch manuell in die Datei build.gradle kopiert werden).

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

Führen Sie diese Aufgabe dann wie folgt aus:

./gradlew copySdkComponents
Copy

Die extrahierten SQL-Dateien können dann während der Ausführung von setup.sql für die Native App ausgeführt werden.

Bereitstellung und Installation

Das Snowflake Native SDK for Connectors ist für die Verwendung mit dem Snowflake Native App Framework konzipiert. Das bedeutet, dass Bereitstellung und Installation auf die gleiche Weise erfolgen wie bei jeder anderen nativen App. Das wiederum bedeutet, dass zunächst das Anwendungspaket erstellt und alle Dateien in den Stagingbereich hochgeladen werden müssen. Wir empfehlen, den Stagingbereich innerhalb des Anwendungspakets zu erstellen. Wenn das obige Beispielskript verwendet wurde, sollten alle erforderlichen Dateien des Snowflake Native SDK for Connectors bereits im Verzeichnis des Konnektors vorhanden sein. Das bedeutet, dass der Entwickler dafür sorgen muss, dass der benutzerdefinierte Code des Konnektors und alle Streamlit-Dateien ebenfalls vorhanden sind. Weitere Informationen dazu finden Sie unter Anwendungspaket erstellen.

Sobald das Anwendungspaket erstellt ist und die Dateien in den Stagingbereich hochgeladen wurden, kann eine Version version der Anwendung erstellt werden. Dieser Schritt ist während der Entwicklung optional, da die Anwendungsinstanz direkt aus den Dateien im Stagingbereich erstellt werden kann, anstatt die registrierte Version zu verwenden. Weitere Informationen dazu finden Sie unter Anwendungsobjekt erstellen.

Entwicklung

Snowflake Native SDK for Connectors bietet Objekte und Prozeduren, die für jede Konnektoranwendung gängige Anwendungsfälle behandeln können. Dazu gehören Dinge wie Konfiguration, Lebenszyklus, Datenaufnahmedefinition und so weiter. Die vollständige Liste der Features finden Sie in der SDK-Referenz. Einige Teile der vordefinierten Features können angepasst werden. Weitere Informationen dazu finden Sie unter „Gespeicherte Prozeduren und Handler anpassen“.

Testen

Wie bereits erwähnt, enthält die Native SDK für Konnektoren verschiedene Typen von Tests. Dazu gehören Unit-Tests, Integrationstests und so genannte Anwendungstests. Die Unit-Tests verwenden Features, die in dem oben erwähnten connectors-native-sdk-test-Objekt bereitgestellt werden. Für Integrations- und Anwendungstests benötigen Sie eine Verbindung zu Snowflake. Die Verbindungsdetails können über die Datei .env/snowflake_credentials definiert werden. Das Verzeichnis für Anwendungstests enthält auch eine leere Konnektoranwendung. Diese Anwendung wird während der Ausführung der Testsuite bereitgestellt.

Zusätzliche Ressourcen:

Wenn Sie praktische Erfahrungen bei der Implementierung Ihres eigenen Konnektors sammeln möchten, probieren Sie die das Tutorial: Vorlage für Native SDK for Connectors Java aus.

Sprache: Deutsch