Tutorial: Snowflake Native SDK for Connectors Beispiel Java-Konnektor¶

Voraussetzungen¶

Bevor Sie beginnen, müssen Sie sicherstellen, dass Sie folgende Voraussetzungen erfüllen:

• Grundkenntnisse in Java

• Grundkenntnisse zu Snowflake Native Apps

• Grundkenntnisse zur Streamlit-UI

• Zugriff auf ein Snowflake Konto mit einer ACCOUNTADMIN-Rolle

• GitHub-Konto mit dem Sie GitHub Apps erstellen können

• MacOS- oder Linux-Computer, um das Projekt zu erstellen und die Bereitstellungsskripte auszuführen

Java-Installation¶

Snowflake Native SDK for Connectors erfordert Java LTS (Long-Term Support) Version 11 oder höher. Wenn die minimal erforderliche Version von Java nicht auf Ihrem Rechner installiert ist, müssen Sie entweder Oracle Java oder OpenJDK installieren.

Klonen von Repositorys¶

Klonen Sie das Repository connectors-native-sdk auf Ihren Rechner.

Snowflake-CLI-Konfiguration¶

Das Tool Snowflake CLI ist erforderlich, um den Konnektor zu erstellen, bereitzustellen und zu installieren. Wenn Sie Snowflake CLI nicht auf Ihrem Computer haben, installieren Sie es gemäß den Anweisungen, die Sie hier https://docs.snowflake.com/en/developer-guide/snowflake-cli/installation/installation finden.

Nachdem das Tool installiert ist, müssen Sie in Ihrer Konfigurationsdatei eine Verbindung zu Snowflake konfigurieren.

Wenn Sie noch keine Verbindung konfiguriert haben, erstellen Sie eine neue mit dem Namen native_sdk_connection. Eine Beispielverbindung finden Sie in der Datei deployment/snowflake.toml.

Wenn Sie bereits eine Verbindung konfiguriert haben und diese mit dem Konnektor verwenden möchten, verwenden Sie den Namen der Verbindung anstelle von native_sdk_connection, wenn diese in diesem Tutorial verwendet wird.

Natives SDK für Java-Konnektoren¶

Das Verzeichnis connectors-native-sdk-java enthält den gesamten Java-Code von Snowflake Native SDK for Connectors, mit Unit- und Integrationstests für die SDK-Komponenten. Aufgrund der Natur von Native Apps in Snowflake bedeutet dies nicht nur Java-Code, sondern auch SQL-Code, der zur Erstellung einer funktionierenden Anwendung erforderlich ist. Die Definitionen der Datenbankobjekte finden Sie im Verzeichnis src/main/resources. Diese Dateien werden beim Erstellen einer Anwendung verwendet, um festzulegen, welche Objekte in der Anwendung verfügbar sein sollen. In dem Beispielkonnektor verwenden wir die Datei all.sql, die Objekte für alle verfügbaren Features erstellt. Diese Datei wird während des Installationsprozesses der Anwendungsinstanz ausgeführt.

Test des nativen Konnektor-SDK in Java¶

Das Verzeichnis connectors-native-sdk-test-java enthält den Quellcode einer Hilfsbibliothek, die in Unit-Tests verwendet wird, z. B. Objekte, die zum Nachahmen bestimmter Komponenten verwendet werden, benutzerdefinierte Assertionen usw. Diese Dateien sind nicht Teil der Konnektor-Anwendung.

Beispiel-Java-GitHub-Konnektor¶

Der eigentliche Beispielkonnektor befindet sich im Verzeichnis examples/connectors-native-sdk-example-java-github-connector. Das Verzeichnis app/ enthält alle Dateien, die zur Ausführung der Native App benötigt werden:

• Das Verzeichnis app/streamlit/ enthält Quelldateien, die zur Ausführung der Streamlit-UI des Konnektors erforderlich sind.

• Die setup.sql-Datei wird während der Installation der Anwendungsinstallation ausgeführt und ist für die Erstellung der erforderlichen Datenbankobjekte verantwortlich. Diese Datei führt die zuvor erwähnte Datei all.sql sowie einen benutzerdefinierten SQL-Code aus.

• Die manifest.yml-Datei ist das Manifest der Native App. Es ist erforderlich, ein Anwendungspaket und dann die Anwendungsinstanz selbst zu erstellen. In dieser Datei werden die Anwendungseigenschaften sowie die von der Anwendung benötigten Berechtigungen festgelegt.

Zusätzlich enthält das Verzeichnis examples/connectors-native-sdk-example-java-github-connector das Unterverzeichnis src/, das die benutzerdefinierte Konnektorlogik enthält, wie z. B. die Implementierung der erforderlichen Klassen und Anpassungen der Standardkomponenten SDK.

Natives SDK für Template Konnektoren¶

Eine Vorlage für ein Gradle-Java-Projekt, das Snowflake Native SDK for Connectors als Abhängigkeit verwendet, damit Sie schnell einen neuen Konnektor erstellen können. Mehr dazu erfahren Sie unter Tutorial: Snowflake Native SDK for Connectors Java-Konnektor-Vorlage.

Erstellen des Konnektors¶

Das Erstellen eines Konnektors, der mit Snowflake Native SDK for Connectors erstellt wurde, unterscheidet sich ein wenig vom Erstellen einer typischen Java-Anwendung. Neben der Erstellung der .jar-Archive aus den Quellen gibt es noch einige andere Dinge, die erledigt werden müssen. Das Erstellen der Anwendung besteht aus den folgenden Schritten:

1. Kopieren benutzerdefinierter interner Komponenten in das Build-Verzeichnis

2. Kopieren der SDK-Komponenten in das Build-Verzeichnis

Konnektor bereitstellen¶

Zur Bereitstellung einer nativen App muss ein Anwendungspaket in Snowflake erstellt werden. Danach müssen alle Dateien aus dem sf_build-Verzeichnis auf Snowflake hochgeladen werden.

Beachten Sie, dass für Entwicklungszwecke die Erstellung von Versionen optional ist. Eine Anwendungsinstanz kann direkt aus Stagingdateien erstellt werden. Auf diese Weise können Sie Änderungen in den meisten Konnektorateien sehen, ohne die Version und die Anwendungsinstanz neu erstellen zu müssen.

Die folgenden Operationen werden durchgeführt:

1. Erstellen eines neuen Anwendungspakets, wenn es noch nicht existiert

2. Erstellen eines Stagingbereichs für Schema und Datei innerhalb des Pakets

3. Hochladen von Dateien aus dem sf_build-Verzeichnis in den Stagingbereich (dieser Schritt kann einige Zeit in Anspruch nehmen)

Um den Konnektor bereitzustellen, führen Sie den Befehl: snow app deploy --connection=native_sdk_connection aus.

Weitere Informationen zum Befehl snow app deploy finden Sie unter snow app deploy.

Das erstellte Anwendungspaket wird nun auf der Registerkarte App packages in der Kategorie Data products in der Snowflake-UI Ihres Kontos angezeigt.

Konnektor installieren¶

Die Installation der Anwendung ist der letzte Schritt des Prozesses. Er erstellt eine Anwendung aus dem zuvor erstellten Anwendungspaket.

Um den Konnektor zu installieren, führen Sie den Befehl: snow app run --connection=native_sdk_connection aus.

Weitere Informationen zum Befehl snow app run finden Sie unter snow app run.

Die installierte Anwendung wird nun auf der Registerkarte Installed apps in der Kategorie Data products in der Snowflake-UI Ihres Kontos angezeigt.

Aktualisieren der Konnektordateien¶

Wenn Sie zu irgendeinem Zeitpunkt eine der Konnektordateien ändern möchten, können Sie die geänderten Dateien einfach in den Stagingbereich des Anwendungspakets hochladen. Der Befehl zum Hochladen hängt davon ab, welche Dateien aktualisiert wurden.

Bevor einer der Update-Befehle ausgeführt wird, müssen Sie die neuen Dateien Ihres Konnektors in das Verzeichnis sf_build kopieren, und zwar mit folgende Befehl: ./gradlew copyInternalComponents

Berechtigungen¶

Für die Anwendung sind zwei Kontoberechtigungen erforderlich: CREATE DATABASE und EXECUTE TASK.

Die erste Berechtigung ist erforderlich, um eine Zieldatenbank für die eingelesenen Daten zu erstellen. Diese Datenbank sollte außerhalb der Anwendung erstellt werden, sodass die aufgenommenen Daten intakt bleiben, wenn die Anwendung deinstalliert wird. In diesem Beispiel wird dieses Feature jedoch nicht unterstützt, es wird immer eine neue Datenbank erstellt.

Die zweite Berechtigung wird benötigt, um periodische Aufgaben zu planen, die die Daten von GitHub abrufen und in der Zieldatenbank speichern.

Sie können diese Berechtigungen über die Registerkarte „Sicherheit“ oder über die Schaltfläche Grant privileges im Konfigurationsbildschirm des Konnektors erteilen. Letzteres führt dazu, dass ein Popup auf dem Bildschirm erscheint.

Warehouse-Referenz¶

Der Konnektor benötigt ein Warehouse, um Datenaufnahme-Aufgaben auszuführen und zu planen. Die Anwendung wird das Warehouse über eine Referenz nutzen. Die Warehouse-Referenz wird in der Datei manifest.yml definiert:

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

Die Referenz kann über die Registerkarte „Sicherheit“, wie bei den Berechtigungen oben, oder über die Schaltfläche Choose warehouse festgelegt werden.

Zieldatenbank und -schema¶

Wie bereits erwähnt, benötigt der Konnektor eine Datenbank, um die eingegebenen Daten zu speichern. Diese Datenbank wird in einem späteren Schritt mit dem vom Benutzer angegebenen Schema erstellt. Der Name der Datenbank ist dem Benutzer überlassen, sofern die bereitgestellte Datenbank nicht bereits existiert.

Der Bildschirm der fertigen Konnektorkonfiguration sieht ungefähr so aus:

Einrichten des Berechtigungs-SDK¶

Für die OAuth2-Authentifizierung müssen im Konto des Benutzers eine Sicherheitsintegration, ein Geheimnis und eine Integration für externen Zugriff erstellt werden. Unser Konnektor verwendet die Native Apps Permission SDK, um die Erstellung dieser Objekte anzufordern.

Referenzen für die Integration für externen Zugriff und das Geheimnis, die der Konnektor benötigt, werden in der manifest.yml-Datei definiert:

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

Außerdem muss eine spezielle Prozedur in der Datei setup.sql hinzugefügt werden. Sie wird in der Eigenschaft configuration_callback für jede der oben vorgestellten Referenzen referenziert:

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;

Für die Integration für externen bietet die Prozedur eine Referenz:

• host_ports – Hostnamen der externen Datenquelle, auf die während der Aufnahme zugegriffen werden soll

• secret_references – Array von Namen von Referenzen auf OAuth-Geheimnisse

• allowed_secrets – LIST, die dem Berechtigungs-SDK mitteile, dass es die im Feld secret_references angegebenen Geheimnisse verwenden soll

Für die Geheimnisreferenz bietet das Verfahren:

• type - OAUTH2 im Fall unseres Geheimnisses

• security_integration – Eigenschaften der erstellten Sicherheitsintegration:

  • oauth_scopes – eine Liste der OAuth-Bereiche, die vom Konnektor angefordert werden (bei Verwendung einer GitHub-App ist dieses Feld optional)

  • oauth_token_endpoint – Endpunkt, von dem das Aktualisierungs- und Zugriffstoken bezogen wird

  • oauth_authorization_endpoint – Endpunkt, an den die Autorisierungsanfrage gesendet werden soll

Einrichten der GitHub-App¶

Der nächste Schritt ist die Einrichtung einer GitHub-App im Konto des Benutzers. Diese App wird verwendet, um beschränkten Zugriff auf das Konto zu gewähren, sodass Daten aufgenommen werden können.

Drücken Sie zunächst die Schaltfläche Request access in der Konnektor-UI.

Auf dem ersten Bildschirm können Sie die Endpunkte überprüfen, für die eine externe Konnektivität zugelassen wird.

Nachdem Sie Next gedrückt haben, sehen Sie einen zweiten Bildschirm. Wählen Sie OAuth2, um eine neue Integration und ein neues Geheimnis zu erstellen, und kopieren Sie die bereitgestellte Weiterleitungs-URL. Sie enthält den Namen Ihrer Organisation und die Region Ihres Kontos.

Gehen Sie dann auf die Seite mit den Einstellungen Ihres GitHub-Kontos, dann auf Developer settings > GitHub Apps und klicken Sie auf die Schaltfläche New GitHub App:

1. Geben Sie den Namen und die Homepage-URL Ihrer App ein

2. Fügen Sie die von Ihnen kopierte Weiterleitungs-URL in das Feld Callback URL ein

3. Stellen Sie sicher, dass die Option Expire user authorization tokens ausgewählt ist

4. Stellen Sie sicher, dass Request user authorization (OAuth) during installation nicht ausgewählt ist

5. Wenn Sie sie nicht benötigen, deaktivieren Sie die Option Active im Bereich Webhook

6. Wählen Sie die Berechtigungen aus, die für die Funktion des Konnektors erforderlich sind:

   1. Repository permissions > Issues mit dem Read-only-Zugriff

   2. Repository permissions > Metadata mit dem Read-only-Zugriff

7. Wenn die App mit diesem Beispielkonnektor nur von Ihnen verwendet werden soll, wählen Sie am besten Only on this account im Abschnitt „Installationszugriff“.

Nachdem die App erstellt wurde, klicken Sie auf die Option Install app in der linken Seitenleiste und installieren Sie die Anwendung in Ihrem Konto. Sie können wählen, auf welche Repositorys die App (und damit auch der Konnektor) zugreifen kann. Ohne diese Installation ist der Konnektor nur in der Lage, auf öffentliche Repositorys zuzugreifen.

OAuth-Integration¶

Kehren Sie nach der Installation zu Ihrer GitHub-App zurück und erstellen Sie ein neues Client-Geheimnis. Achten Sie darauf, dass Sie es sofort kopieren, da es nicht wieder angezeigt wird. Fügen Sie das Client-Geheimnis in das OAuth-Konfigurations-Popup Ihres Konnektors ein. Kopieren Sie schließlich die Client-ID (nicht App-ID) Ihrer Anwendung und fügen Sie sie ebenfalls in das OAuth-Konfigurations-Popup Ihres Konnektors ein.

Nachdem Sie auf Connect geklickt haben, erscheint ein GitHub-Fenster, in dem Sie um die Autorisierung der App für Ihr GitHub-Konto gebeten werden. Nach der Autorisierung werden Sie automatisch zur Konnektor-UI zurückgeleitet. Nach erfolgreicher Autorisierung (es kann ein paar Sekunden dauern, bis das Popup-Fenster geschlossen ist) wird die Seite mit den IDs der Integration für externen Zugriff und der Geheimnisreferenzen ausgefüllt.

Wenn Sie auf die Schaltfläche Connect klicken, wird die Prozedur TEST_CONNECTION im Konnektor ausgelöst. Bei dieser Prozedur wird versucht, auf den GitHub API Octocat-Endpunkt zuzugreifen, um zu prüfen, ob die externe Konnektivität korrekt konfiguriert wurde und das OAuth-Zugriffstoken korrekt erhalten wurde.

Wenn der Test erfolgreich war, wird die Anwendung mit dem Finalisierungsschritt fortgesetzt.