Premiers pas avec Snowflake Native SDK for Connectors

Snowflake Native SDK for Connectors est une bibliothèque qui fournit des composants universels pouvant être utilisés pour construire une application native Snowflake qui ingère les données d’une source de données externe dans Snowflake. Les composants fournis définissent le flux recommandé de l’application du connecteur, permettent la personnalisation et fournissent des éléments de base pour construire la logique d’ingestion.

Le Snowflake Native SDK for Connectors est distribué sous la forme d’un code à extraire et à construire localement. Vous trouverez ci-dessous quelques informations qui vous permettront de vous familiariser avec la structure du SDK, comment l’utiliser dans votre projet, comment déployer et installer une application et comment l’utiliser pendant le développement.

Structure du projet

Le Snowflake Native SDK for Connectors se compose de plusieurs parties, qui sont décrites ci-dessous.

  • connectors-native-sdk

Ce répertoire contient le code source et les tests réels de Snowflake Native SDK for Connectors. En raison de la nature de l’application native à l’intérieur de Snowflake, le code source n’est pas seulement du code Java, mais aussi du code SQL regroupé avec des définitions d’objets de base de données.

Le code Java se trouve dans le répertoire src/main, comme pour toute bibliothèque Java ordinaire. Il en va de même pour les tests unitaires situés à l’intérieur de src/test. En outre, à l’intérieur du répertoire src/, vous trouverez les répertoires intTest et appTest. Il s’agit respectivement des tests d’intégration et des tests d’application. Ces deux types de tests nécessitent une connexion à un compte Snowflake. Les premiers testent les composants de SDK en utilisant des objets de base de données autonomes, tandis que les seconds déploient une application réelle et exécutent des tests en l’utilisant.

Les fichiers sources SQL sont contenus dans le répertoire src/main/resources. Ils sont inclus dans l’archive jar lors de la construction de Snowflake Native SDK for Connectors. Pour les utiliser, il faut les extraire de l’archive et les placer dans un répertoire cible qui sera copié dans la zone de préparation de Snowflake à l’intérieur du paquet d’application.

  • connectors-native-sdk-test

Ce répertoire contient une bibliothèque d’aide conçue pour faciliter les tests unitaires du connecteur basé sur le Snowflake Native SDK for Connectors. Il fournit des implémentations fictives pour certains objets de la base de données, des constructeurs de tests spécialement conçus qui permettent d’écraser les parties du code non disponibles pour la personnalisation et quelques assertions personnalisées basées sur la bibliothèque AssertJ.

Installation et utilisation de SDK

Actuellement, l’installation et l’utilisation du Snowflake Native SDK for Connectors nécessitent que le développeur effectue certaines actions manuelles.

La bibliothèque Snowflake Native SDK for Connectors est disponible 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'
}

Pour accéder aux fichiers SQL fournis, il faut les extraire dans le répertoire cible de l’application native. Pour ce faire, utilisez la définition de tâche gradle suivante (pour l’instant, elle doit être copiée manuellement dans le fichier 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

Pour exécuter ensuite cette tâche :

./gradlew copySdkComponents
Copy

Les fichiers SQL extraits peuvent ensuite être exécutés pendant l’exécution de setup.sql pour l’application native.

Déploiement et installation

Le Snowflake Native SDK for Connectors est conçu pour être utilisé avec le Snowflake Native App Framework. Cela signifie que le déploiement et l’installation se déroulent de la même manière que pour n’importe quelle autre application native. Cela signifie que le Paquet d’application doit d’abord être créé et que tous les fichiers doivent être téléchargés dans la zone de préparation. Il est recommandé de créer la zone de préparation dans le paquet d’application. Si le script d’exemple ci-dessus a été utilisé, tous les fichiers requis à partir de Snowflake Native SDK for Connectors devraient être déjà présents dans le répertoire de compilation cible du connecteur. Cela signifie qu’il incombe au développeur de s’assurer que le code personnalisé du connecteur et tous les fichiers Streamlit sont également présents. Pour plus d’informations, consultez Créer un paquet d’application.

Une fois que le paquet d’application est créé et que les fichiers sont téléchargés dans une zone de préparation, une version de l’application peut être créée. Cette étape est facultative pendant le développement, car l’instance d’application peut être créée directement à partir des fichiers dans la zone de préparation au lieu d’utiliser la version enregistrée. Pour plus d’informations, consultez Créer un objet d’application.

Développement

Le Snowflake Native SDK for Connectors fournit des objets et des procédures qui traitent les cas d’utilisation courants pour chaque application Connector. Cela comprend des éléments tels que la configuration, le cycle de vie, la définition de l’ingestion, etc. Pour consulter la liste complète des fonctions, reportez-vous à la référence du SDK. Certaines parties des fonctions prédéfinies peuvent être personnalisées. Pour plus d’informations à ce sujet, consultez la rubrique Personnalisation des procédures stockées et des gestionnaires (handlers).

Test

Comme indiqué précédemment, le SDK Connectors Native contient différents types de tests. Il s’agit de tests unitaires, de tests d’intégration et de tests d’application. Les tests unitaires utilisent les fonctions fournies dans le connectors-native-sdk-test susmentionné. Quant aux tests d’intégration et d’application, ils nécessitent une connexion à Snowflake. Les détails de la connexion peuvent être définis à l’aide du fichier .env/snowflake_credentials. Le répertoire des tests d’application contient également une application de connecteur vide dans la ressource. Cette application est déployée pendant l’exécution de la suite de tests

Ressources supplémentaires :

Pour une expérience pratique de la mise en œuvre de votre propre connecteur, essayez Tutoriel : SDK natif pour les modèles Java pour les connecteurs.

Langage: Français