チュートリアル: Snowflake Native SDK for Connectors のJavaコネクタの例¶

前提条件¶

開始する前に、次の要件を満たしていることを確認してください。

• Javaの基礎知識

• Snowflake Native Appsの基礎知識

• Streamlit UI の基礎知識

• ACCOUNTADMIN ロールを持つ Snowflake アカウントへのアクセス

• GitHub アカウントで、 GitHub アプリ を作成できます。

• MacOS または Linux マシンでプロジェクトをビルドし、デプロイスクリプトを実行します。

Javaのインストール¶

Snowflake Native SDK for Connectors Java LTS (Long-Term Support) バージョン11以上が必要です。お使いのマシンにJavaの最低必要バージョンがインストールされていない場合は、Oracle Javaまたは OpenJDK のいずれかをインストールする必要があります。

リポジトリのクローニング¶

connectors-native-sdk リポジトリをあなたのマシンにクローンします。

Snowflake CLI の構成¶

コネクタのビルド、デプロイ、インストールには、 Snowflake CLI ツールが必要です。お使いのマシンに Snowflake CLI がインストールされていない場合は、 こちら の指示に従ってインストールしてください。

ツールのインストール後、 構成ファイル で Snowflake への接続を構成する必要があります。

接続が構成されていない場合は、 native_sdk_connection という名前の接続を新規に作成してください。 deployment/snowflake.toml ファイルに接続例があります。

すでに接続が構成されていて、それをコネクタで使用したい場合は、このチュートリアルでこの接続を使用するときは、 native_sdk_connection の代わりにその名前を使用してください。

コネクタ ネイティブ SDK Java¶

connectors-native-sdk-java ディレクトリには、 Snowflake Native SDK for Connectors のすべての Java コードと、 SDK コンポーネントのユニットテストと統合テストが含まれています。Snowflake上のNative Appsの性質上、Javaコードだけでなく、動作するアプリケーションを作成するために必要な SQL コードも含まれます。データベースオブジェクトの定義は src/main/resources ディレクトリにあります。これらのファイルは、アプリケーションを作成する際に、アプリケーション内でどのオブジェクトを可用性にするかをカスタマイズするために使用されます。コネクタの例では、 all.sql ファイルを使用します。 ファイルでは、すべての可用性のオブジェクトが作成されます。このファイルはアプリケーションインスタンスのインストールプロセス中に実行されます。

コネクタ ネイティブ SDK Test Java¶

connectors-native-sdk-test-java ディレクトリには、ユニットテストで使用するヘルパーライブラリのソースコードが格納されています。 たとえば、特定のコンポーネントをモックするためのオブジェクトや、 カスタムアサーションなどです。これらのファイルはコネクタアプリケーションの一部ではありません。

Java GitHub コネクタの例¶

実際のサンプルコネクタは examples/connectors-native-sdk-example-java-github-connector ディレクトリにあります。 app/ ディレクトリには、Native Apps の実行に必要なすべてのファイルが含まれています。

• app/streamlit/ ディレクトリには、コネクタの Streamlit UI を実行するために必要なソースファイルが含まれています。

• setup.sql ファイルはアプリケーションのインストール中に実行され、必要なデータベースオブジェクトを作成します。このファイルは、前述の all.sql ファイルと、いくつかのカスタムSQLコードを実行します。

• manifest.yml ファイルは Native Apps のマニフェストです。アプリケーション・パッケージを作成し、次にアプリケーション・インスタンス自体を作成する必要があります。このファイルはアプリケーションのプロパティと、アプリケーションが必要とするパーミッションを指定します。

さらに、 examples/connectors-native-sdk-example-java-github-connector ディレクトリには、 src/ サブディレクトリが含まれています。このサブディレクトリには、必要なクラスの実装やデフォルトの SDK コンポーネントのカスタマイズなどのカスタム コネクタ ロジックが含まれています。

コネクタ ネイティブ SDK Template¶

Snowflake Native SDK for Connectors を依存関係として使用し、新しいコネクタを素早くビルドするのに役立つ Gradle Java プロジェクトのテンプレートです。詳しくは チュートリアル: Snowflake Native SDK for Connectors のJavaコネクタテンプレート をご覧ください。

コネクタの作成¶

Snowflake Native SDK for Connectors を使用して作成されたコネクタの構築は、一般的な Java アプリケーションの構築とは少し異なります。ソースから.jarアーカイブをビルドするだけでなく、やらなければならないことがいくつかあります。アプリケーションの構築は以下の手順で行います。

1. カスタム内部コンポーネントのビルドディレクトリへのコピー

2. コンポーネントのビルドディレクトリへ SDK をコピーする

コネクタの展開¶

Native Appsをデプロイするには、Snowflake内でアプリケーションパッケージを作成する必要があります。その後、 sf_build ディレクトリのすべてのファイルを Snowflake にアップロードする必要があります。

アプリケーションインスタンスはステージングされたファイルから直接作成できます。このアプローチでは、バージョンとアプリケーションのインスタンスを再作成することなく、ほとんどのコネクタファイルの変更を確認できます。

以下の演算子を行います。

1. アプリケーションパッケージがまだ存在しない場合は、新しいアプリケーションパッケージを作成します。

2. パッケージ内にスキーマとステージングされたファイルを作成します。

3. sf_build ディレクトリからステージにファイルをアップロードします（このステップには時間がかかる場合があります）。

コネクタをデプロイするには、コマンドを実行します： snow app deploy --connection=native_sdk_connection.

snow app deploy コマンドの詳細については、 snow app deploy をご参照ください。

作成されたアプリケーションパッケージは、アカウントの Snowflake UI の App packages タブの Data products カテゴリに表示されます。

コネクタをインストールする¶

アプリケーションのインストールはプロセスの最後のステップです。先に作成したアプリケーションパッケージからアプリケーションを作成します。

コネクタをインストールするには、コマンドを実行します： snow app run --connection=native_sdk_connection.

snow app run コマンドの詳細については、 snow app run をご参照ください。

インストールされたアプリケーションは、アカウントの Snowflake UI の Data products カテゴリにある Installed apps タブに表示されます。

コネクタファイルの更新¶

コネクタファイルを変更したい場合は、変更したファイルをアプリケーションパッケージのステージに簡単にアップロードできます。アップロードコマンドは、どのファイルが更新されたかに依存します。

アップデートコマンドを実行する前に、 sf_build ディレクトリにコネクタの新しいファイルをコピーする必要があります。 ./gradlew copyInternalComponents

権限¶

アプリケーションの操作には、 CREATE DATABASE と EXECUTE TASK の2つのアカウントレベルの権限が必要です。

最初の権限は、インジェストされたデータの保存先データベースを作成するために必要です。アプリケーションをアンインストールしても、取り込んだデータをそのまま残すことができるように、このデータベースはアプリケーションの外部に作成する必要があります。しかし、この例ではこの機能をサポートしておらず、常に新しいデータベースが作成されます。

2つ目の権限は、 GitHub からデータを取得し、保存先データベースに保存するタスクを定期的にスケジュールするために必要です。

これらの権限を付与するには、セキュリティ・タブを使用するか、コネクタ構成画面で Grant privileges ボタンを押します。後者は画面にポップアップが表示されます。

ウェアハウス リファレンス¶

コネクタは、インジェスチョン タスクを実行しスケジュールするウェアハウスを必要とします。アプリケーションは リファレンス を通してウェアハウスを使用します。ウェアハウスのリファレンスは 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

リファレンスは、上記の権限と同じセキュリティタブを使うか、 Choose warehouse ボタンを押すことでセットできます。

デスティネーション・データベースとスキーマ¶

前述したように、コネクタは取り込んだデータを保存するデータベースを必要とします。このデータベースは、後のステップでユーザーが指定したスキーマで作成されます。提供されたデータベースが既に存在しない限り、データベースの名前はユーザー次第です。

コネクタの構成が完了すると、このような画面になります。

パーミッション SDK セットアップ¶

OAuth2 認証コードには、セキュリティ統合、シークレット、外部アクセス統合をユーザーアカウントに作成する必要があります。当社のコネクタは、 Native Apps Permission SDK を使用して、これらのオブジェクトの作成をリクエストします。

コネクタが必要とする外部アクセス統合とシークレットのリファレンスは、 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

さらに、 setup.sql ファイルに特別なプロシージャを追加する必要があります。上記で紹介した各リファレンスの configuration_callback プロパティで参照されています。

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;

外部アクセス統合のリファレンスについては、プロシージャが提供します。

• host_ports - インジェスト時にアクセスする外部データソースのホスト名。

• secret_references - OAuth シークレットへのリファレンスの名前の配列。

• allowed_secrets - LIST、 secret_references フィールドで指定されたシークレットを使用するよう、Permission SDK に伝える。

シークレットのリファレンスについては、プロシージャが提供します。

• シークレットの大文字と小文字の場合の type - OAUTH2

• security_integration - 作成されたセキュリティ統合のプロパティ

  • oauth_scopes - コネクターがリクエストする OAuth スコープのリスト（GitHub アプリを使用する場合、このフィールドはオプションです。）

  • oauth_token_endpoint - リフレッシュとアクセストークンの取得元エンドポイント

  • oauth_authorization_endpoint - 認可リクエストを送信するエンドポイント。

GitHub アプリ設定¶

次のステップは、ユーザーアカウントに GitHub アプリのセットアップです。このアプリは、データを取り込むことができるように、アカウントへの限定的なアクセスを許可するために使用されます。

最初のステップは、コネクタ UI の Request access ボタンを押すことです。

最初の画面では、外部接続を許可するエンドポイントを確認できます。

Next を押すと、2つ目の画面が表示されます。 OAuth2 を選択して新しい統合とシークレットを作成し、提供されたリダイレクト URL をコピーします。リダイレクトには組織名とアカウントのリージョンが含まれます。

次に、 GitHub のアカウント設定ページに行き、 Developer settings > GitHub Apps に入り、 New GitHub App ボタンを押してください。

1. アプリの名前とホームページ URL を入力してください。

2. コピーしたリダイレクト URL を Callback URL フィールドに貼り付けます。

3. Expire user authorization tokens オプションが選択されていることを確認してください。

4. Request user authorization (OAuth) during installation が選択されていないことを確認してください。

5. 不要な場合は、 Webhook セクションの Active オプションの選択を解除してください。

6. コネクタの動作に必要な権限を選択します。

   1. Read-only アクセスで Repository permissions > Issues

   2. Read-only アクセスで Repository permissions > Metadata

7. このコネクタの例では、アプリを自分だけが使用する場合、インストールアクセスセクションで Only on this account を選択するのが最適です。

アプリケーションが作成されたら、左サイドバーの Install app オプションを押し、アプリケーションをアカウントにインストールしてください。アプリ（ひいてはコネクタ）がアクセスできるリポジトリを選択できます。このインストールを行わないと、コネクタはパブリック・リポジトリにしかアクセスできません。

OAuth 統合セットアップ¶

インストール後、 GitHub アプリに戻り、新しいクライアントシークレットを生成します。二度と表示されませんので、すぐにコピーしてください。コネクタの OAuth 構成ポップアップにクライアント・シークレットを貼り付けます。最後に、アプリケーションのクライアント ID （app ID ではなく）をコピーし、コネクタの OAuth 構成ポップアップにも貼り付けます。

Connect を押すと、 GitHub ウィンドウがポップアップし、 GitHub アカウントでアプリの認証を求められます。認証後、自動的にコネクタ UI にリダイレクトされます。認証に成功すると（認証が完了し、ポップアップが閉じるまで数秒かかる場合があります）、ページに外部アクセス統合の IDs、シークレットリファレンスが入力されます。

Connect ボタンを押すと、コネクタ内部の TEST_CONNECTION プロシージャがトリガーされます。このプロシージャでは、 GitHub API octocat エンドポイント へのアクセスを試み、外部接続が正しく構成され、 OAuth アクセストークンが正しく取得されたかどうかをチェックします。

テストが成功すると、アプリケーションは最終化ステップに進みます。