Tutoriel : Exemple de connecteur Java Snowflake Native SDK for Connectors¶

Conditions préalables¶

Avant de commencer, assurez-vous que vous remplissez les conditions suivantes :

• Connaissance de base de Java

• Connaissances de base de Snowflake Native Apps

• Connaissance de base de l’UIStreamlit

• Accès à un compte Snowflake avec un rôle ACCOUNTADMIN

• Compte GitHub, qui permet de créer des applications GitHub

• MacOS ou Linux pour créer le projet et exécuter les scripts de déploiement

Installation de Java¶

Snowflake Native SDK for Connectors exige la version 11 ou supérieure de Java LTS (Long-Term Support). Si la version minimale requise de Java n’est pas installée sur votre machine, vous devez installer soit Oracle Java, soit OpenJDK.

Clonage du référentiel¶

Clonez le référentiel connectors-native-sdk sur votre machine.

Configuration de la CLI Snowflake¶

L’outil de la CLI Snowflake est une exigence pour concevoir, déployer et installer le connecteur. Si vous n’avez pas la CLI Snowflake sur votre machine - installez-la selon les instructions disponibles ici.

Une fois l’outil installé, vous devez configurer une connexion à Snowflake dans votre fichier de configuration.

Si aucune connexion n’est configurée, créez-en une nouvelle nommée native_sdk_connection. Vous trouverez un exemple de connexion dans le fichier deployment/snowflake.toml.

Si vous avez déjà configuré une connexion et que vous souhaitez l’utiliser avec le connecteur - utilisez son nom au lieu de native_sdk_connection chaque fois que cette connexion est utilisée dans ce tutoriel.

Connectors Native SDK Java¶

Le répertoire connectors-native-sdk-java contient tout le code Java de Snowflake Native SDK for Connectors, ainsi que des tests d’unité et d’intégration pour les composants SDK. En raison de la nature des Native Apps à l’intérieur de Snowflake, cela signifie non seulement du code Java, mais aussi du code SQL, qui est nécessaire pour créer une application fonctionnelle. Les définitions des objets de la base de données se trouvent dans le répertoire src/main/resources. Ces fichiers sont utilisés lors de la création d’une application pour personnaliser les objets qui seront disponibles dans l’application. Dans l’exemple du connecteur, nous utilisons le fichier all.sql, qui crée des objets pour toutes les fonctions disponibles. Ce fichier sera exécuté au cours du processus d’installation de l’instance d’application.

Connectors Native SDK Test Java¶

Le répertoire connectors-native-sdk-test-java contient le code source d’une bibliothèque d’aide utilisée dans les tests unitaires, par exemple des objets utilisés pour simuler des composants particuliers, des assertions personnalisées, etc. Ces fichiers ne font pas partie de l’application du connecteur.

Exemple de connecteur Java GitHub¶

L’exemple de connecteur proprement dit se trouve dans le répertoire examples/connectors-native-sdk-example-java-github-connector. Le répertoire app/ contient tous les fichiers nécessaires à l’exécution de la Native App :

• Le répertoire app/streamlit/ contient les fichiers sources nécessaires à l’exécution de la version Streamlit UI du connecteur.

• Le fichier setup.sql est exécuté lors de l’installation de l’application et est chargé de créer les objets nécessaires à la base de données. Ce fichier exécutera le fichier all.sql mentionné plus haut, ainsi que du code SQL personnalisé.

• Le fichier manifest.yml est le manifeste de la Native App. Il est exigé pour créer un paquet d’application, puis l’instance d’application elle-même. Ce fichier spécifie les propriétés de l’application, ainsi que les autorisations nécessaires à l’application.

En outre, le répertoire examples/connectors-native-sdk-example-java-github-connector contient le sous-répertoire src/, qui contient la logique du connecteur personnalisé, telle que l’implémentation des classes requises et les personnalisations des composants par défaut de SDK.

Modèle du Connectors Native SDK¶

Un projet Java Gradle modèle qui utilise Snowflake Native SDK for Connectors comme dépendance pour vous aider à créer rapidement un nouveau connecteur. Pour en savoir plus, consultez Tutoriel : Modèle de connecteur Java Snowflake Native SDK for Connectors.

Créer le connecteur¶

La conception d’un connecteur créé à l’aide de Snowflake Native SDK for Connectors est un peu différente de celle d’une application Java classique. Il y a d’autres choses à faire que de concevoir les archives .jar à partir des sources. La conception de l’application comprend les étapes suivantes :

1. Copier des composants internes personnalisés dans le répertoire de conception

2. Copier des composants SDK dans le répertoire de conception

Déployer le connecteur¶

Pour déployer une Native App, un paquet d’application doit être créé dans Snowflake. Ensuite, tous les fichiers du répertoire sf_build doivent être téléchargés vers Snowflake.

Veuillez noter qu’à des fins de développement, la création de versions est facultative. Une instance d’application peut être créée directement à partir de fichiers en zone de préparation. Cette approche vous permet de voir les modifications apportées à la plupart des fichiers du connecteur sans avoir à recréer la version et l’instance de l’application.

Les opérations suivantes seront effectuées :

1. Créer un nouveau paquet d’application, s’il n’existe pas déjà

2. Créer un schéma et une zone de préparation des fichiers à l’intérieur du paquet

3. Télécharger les fichiers du répertoire sf_build vers la zone de préparation (cette étape peut prendre un certain temps)

Pour déployer le connecteur, exécutez la commande : snow app deploy --connection=native_sdk_connection.

Pour plus d’informations sur la commande snow app deploy, consultez snow app deploy.

Le paquet d’application créé sera désormais visible dans l’onglet App packages, dans la catégorie Data products, dans le compte Snowflake UI de votre compte.

Installer le connecteur¶

L’installation de l’application est la dernière étape du processus. Il crée une application à partir du paquet d’application créé précédemment.

Pour installer le connecteur, exécutez la commande : snow app run --connection=native_sdk_connection.

Pour plus d’informations sur la commande snow app run, consultez snow app run.

L’application installée sera désormais visible dans l’onglet Installed apps, dans la catégorie Data products, dans le compte Snowflake UI de votre compte.

Mettre à jour les fichiers des connecteurs¶

Si, à un moment donné, vous souhaitez modifier l’un des fichiers du connecteur, vous pouvez facilement télécharger les fichiers modifiés dans la zone de préparation du paquet d’application. La commande de téléchargement dépend des fichiers qui ont été mis à jour.

Avant d’exécuter les commandes de mise à jour, vous devez copier les nouveaux fichiers de votre connecteur dans le répertoire sf_build en exécutant la commande : ./gradlew copyInternalComponents

Privilèges¶

L’opération de l’application nécessite deux autorisations au niveau du compte : CREATE DATABASE et EXECUTE TASK.

Le premier privilège est nécessaire pour créer une base de données de destination pour les données ingérées. Cette base de données doit être créée en dehors de l’application, de manière à ce que les données ingérées restent intactes en cas de désinstallation de l’application. Cependant, cet exemple ne prend pas en charge cette fonction, une nouvelle base de données est toujours créée.

Le second privilège est nécessaire pour planifier les tâches périodiques qui récupèrent les données sur GitHub et les enregistrent dans la base de données de destination.

Ces privilèges peuvent être accordés via l’onglet sécurité ou en appuyant sur le bouton Grant privileges dans l’écran de configuration du connecteur. Ce dernier fera apparaître une fenêtre contextuelle sur l’écran.

Référence de l’entrepôt¶

Le connecteur nécessite un entrepôt pour exécuter et planifier les tâches d’ingestion. L’application utilisera l’entrepôt par l’intermédiaire d’une référence. La référence de l’entrepôt est définie dans le fichier 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

La référence peut être définie en utilisant l’onglet sécurité, de la même manière que pour les privilèges ci-dessus, ou en appuyant sur le bouton Choose warehouse.

Base de données et schéma de destination¶

Comme indiqué précédemment, le connecteur a besoin d’une base de données pour stocker les données ingérées. Cette base de données sera créée, lors d’une étape ultérieure, avec le schéma spécifié par l’utilisateur. Le nom de la base de données est laissé à l’appréciation de l’utilisateur, à condition que la base de données fournie n’existe pas déjà.

L’écran de configuration du connecteur, une fois rempli, ressemble à celui-ci :

Configuration d’autorisation SDK¶

L’authentification OAuth2 nécessite la création d’une intégration de sécurité, d’un secret et d’une intégration d’accès externe dans le compte de l’utilisateur. Notre connecteur utilise l’autorisation Native Apps SDK pour requérir la création de ces objets.

Les références pour l’intégration de l’accès externe et le secret, qui sont nécessaires au connecteur, sont définies dans le fichier 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

En outre, une procédure spéciale doit être ajoutée dans le fichier setup.sql. Elle est référencée dans la propriété configuration_callback pour chacune des références présentées ci-dessus :

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;

Pour la référence d’intégration de l’accès externe, la procédure prévoit :

• host_ports - les noms d’hôte de la source de données externe à laquelle il sera accédé lors de l’ingestion

• secret_references - tableau de noms de références aux secrets OAuth

• allowed_secrets - LIST qui indique à l’autorisation SDK d’utiliser les secrets spécifiés dans le champ secret_references

Pour la référence du secret, la procédure prévoit :

• type - OAUTH2 dans le cas de notre secret

• security_integration - les propriétés de l’intégration de sécurité créée :

  • oauth_scopes - une liste des champs d’application OAuth requis par le connecteur (si vous utilisez une application GitHub - ce champ est facultatif)

  • oauth_token_endpoint - point de terminaison à partir duquel le jeton d’actualisation et d’accès sera acquis

  • oauth_authorization_endpoint - point de terminaison auquel la requête d’autorisation sera envoyée

Configuration de l’application GitHub¶

L’étape suivante consiste à configurer une application GitHub dans le compte de l’utilisateur. Cette application sera utilisée pour accorder un accès limité au compte, afin que les données puissent être ingérées.

La première étape consiste à appuyer sur le bouton Request access du connecteur UI.

Le premier écran vous permet de passer en revue les points de terminaison pour lesquels la connectivité externe sera autorisée.

Après avoir appuyé sur Next - vous verrez un deuxième écran. Sélectionnez OAuth2 pour créer une intégration et un secret, et copiez l’URL de redirection fournie - elle contiendra le nom de votre organisation et la région de votre compte.

Allez ensuite sur la page des paramètres de votre compte GitHub, puis dans Developer settings > GitHub Apps et appuyez sur le bouton New GitHub App :

1. Saisissez le nom et l’URL de la page d’accueil de votre application

2. Collez l’URL de redirection que vous avez copiée dans le champ Callback URL

3. Assurez-vous que l’option Expire user authorization tokens est sélectionnée

4. Assurez-vous que l’adresse Request user authorization (OAuth) during installation n’est pas sélectionnée

5. Si vous n’en avez pas besoin - désélectionnez l’option Active dans la section Webhook

6. Sélectionnez les autorisations nécessaires au fonctionnement du connecteur :

   1. Repository permissions > Issues avec l’accès Read-only

   2. Repository permissions > Metadata avec l’accès Read-only

7. Si l’application ne sera utilisée que par vous, avec cet exemple de connecteur - il est préférable de sélectionner Only on this account dans la section d’accès de l’installation

Une fois l’application créée, cliquez sur l’option Install app dans la barre latérale gauche et installez l’application dans votre compte. Vous pouvez choisir les référentiels auxquels l’application (et par extension le connecteur) pourra accéder. Sans cette installation, le connecteur ne pourra accéder qu’aux référentiels publics.

Configuration de l’intégration OAuth¶

Après l’installation, retournez à votre application GitHub et générez un nouveau secret client. Veillez à le copier immédiatement, car il ne s’affichera plus. Collez le secret du client dans la fenêtre contextuelle de configuration OAuth de votre connecteur. Enfin, copiez l’ID client (et non l’ID de l’application) de votre application et collez-le également dans la fenêtre contextuelle de configuration OAuth de votre connecteur.

Après avoir appuyé sur Connect, une fenêtre GitHub s’ouvre, vous demandant l’autorisation d’utiliser l’application sur votre compte GitHub. Après autorisation - vous serez automatiquement redirigé vers le connecteur UI. Une fois l’autorisation réussie (cela peut prendre quelques secondes pour terminer et fermer la fenêtre contextuelle), la page sera remplie avec les IDs de l’intégration de l’accès externe et des références secrètes.

En appuyant sur le bouton Connect, vous déclencherez la procédure TEST_CONNECTION à l’intérieur du connecteur. Cette procédure tente d’accéder au point de terminaison octocat de l”APIGitHub, afin de vérifier si la connectivité externe a été configurée correctement et si le jeton d’accès OAuth a été obtenu correctement.

Lorsque le test est réussi, l’application passe à l’étape de finalisation.