接続構成

接続構成は、コネクタ構成の直後に実行されるウィザードステップです。このステップでは、ユーザーはソースシステムとの接続を確立してSnowflakeへのデータの取り込みを開始するために必要なプロパティを指定できます。 PUBLIC.SET_CONNECTION_CONFIGURATION(connection_configuration VARIANT) と呼ばれるプロシージャは、このウィザードフェーズを担当するエントリポイントです。このプロシージャは、 UI またはワークシートから呼び出すことができます。カスタムロジックで上書きする場合は、このプロシージャを置き換えて、カスタムJavaハンドラーを指定する必要があります。

このプロシージャを呼び出すには、ユーザーに ADMIN アプリケーションロールが割り当てられている必要があります。

接続構成ステップは、内部的にいくつかのフェーズで構成されています。一部は完全にカスタマイズ可能で、デフォルトでは何も実行されません。フェーズは次のとおりです。

  1. ステータスの検証

  2. 入力の検証

  3. 設定の更新

  4. 内部コールバック

  5. 接続の検証

  6. ステータスの更新

要件

接続構成では、ネイティブアプリのインストール中に少なくとも次の SQL ファイルを実行する必要があります。

さらに、 SDK ユーザーに応じて次の要件があります。

  • PUBLIC.TEST_CONNECTION() プロシージャのカスタム実装

ステータスの検証

接続構成を実行するには、コネクタの内部ステータスが CONFIGURING であり、構成ステータスが CONFIGURED または CONNECTED である必要があります。最初の構成ステータスはコネクタ構成ステップの直後に設定され、後者のステータスは、何らかの理由で後のステップで接続構成を更新する必要がある場合に設定されます。

この検証は、 ConnectionConfigurationHandlerBuilder を使用しても、ストアドプロシージャを上書きしても上書きできません。ただし、この種の検証を実行しないカスタムハンドラーを実装することはできます。

入力の検証

入力はプロパティのマップを含む variant である必要がありますが、これはすべてのケースで機能するとは限りません。そのため、 SDK は、 PUBLIC.SET_CONNECTION_CONFIG_VALIDATE(config VARIANT) という内部ストアドプロシージャを提供しています。デフォルトでは、このプロシージャは 'responseCode': 'OK' を返すだけですが、これを上書きすると、検証中に提供された構成を更新できます。この機能によりカスタムロジックが有効になります。たとえば、入力をトリミングしたり、大文字/小文字に変換したりします。何らかの方法で変換された構成を返すには、応答 Variant に追加の "config" プロパティを含める必要があり、このプロパティには更新された構成を Variant として含める必要があります。このプロシージャは、 SQL を使用して上書きするか、 ConnectionConfigurationHandlerBuilder を使用して、 ConnectionConfigurationInputValidator インターフェイスのカスタム実装を提供することでカスタマイズできます。

以下は、変換を伴うカスタム実装からの有効な応答です。

{
    "response_code" : "OK",
    "config": {
        "key1": "value1",
        "key2": "value2"
    }
}
Copy

設定の更新

検証が正常に完了すると、構成は内部の APP_CONFIG テーブルに保存されます。これを担当するサービスは、提供された Variant を connection_configuration キーの下に保存します。この構成は、保存時に追加の要件に従うことはなく、提供されるプロパティのセットはユーザー次第です。

内部コールバック

内部コールバックは、もう1つのカスタマイズ可能なステップです。デフォルトでは、 PUBLIC.SET_CONNECTION_CONFIGURATION_INTERNAL(connection_configuration VARIANT) を呼び出し、 'response_code': 'OK' を返します。たとえば、外部アクセス統合を許可することで、他のプロシージャを変更するために使用できます。SQL スクリプトを通じて上書きすることも、 ConnectionConfigurationHandlerBuilder を使用して ConnectionConfigurationCallback インターフェイスのカスタム実装を提供することもできます。

接続の検証

このステップは PUBLIC.TEST_CONNECTION プロシージャをトリガーします。このプロシージャは、ソースシステムに対してデータをクエリしようとします。このプロシージャはデフォルトでは実装されていないため、 SDK ユーザーが提供する必要があります。さらに、このフェーズをカスタマイズするために、 ConnectionValidator インターフェイス実装を ConnectionConfigurationHandlerBuilder に提供することもできます。この場合、ストアドプロシージャを実装する必要はありません。このプロシージャでは、最小限の接続チェックのみを実行して、Snowflakeの外部アクセス機能が正しく構成され、コネクタにそれらの機能を使用するために必要なすべての権限があることを確認することをお勧めします。

ステータスの更新

上記のすべてのフェーズが正常に完了すると、コネクタの内部ステータスが次のように更新されます。

{
    "status": "CONFIGURING",
    "configurationStatus": "CONNECTED"
}
Copy

状態遷移の全体図については、 コネクタフロー をご参照ください。

構成の表示

ADMIN および VIEWER ユーザーが内部テーブルから現在の接続構成を返す PUBLIC.GET_CONNECTION_CONFIGURATION() プロシージャを使用できます。

応答

正常な応答

プロシージャが正常に終了すると、 TEST_CONNECTION プロシージャからの応答が返されます。次の形式を使用することをお勧めします。

{
  "response_code": "OK"
}
Copy

エラーの応答

エラーが発生した場合、応答は以下の形式になります。

{
  "response_code": "<ERROR_CODE>",
  "message": "<error message>"
}
Copy

考えられるエラーコードは次のとおりです。

  • INVALID_CONNECTOR_STATUS - コネクタのステータスが無効です。期待されるステータス: [CONFIGURING]

  • INVALID_CONNECTOR_CONFIGURATION_STATUS - コネクタの構成ステータスが無効です。期待されるステータス: CONFIGURED

  • INTERNAL_ERROR - 内部で問題が発生しました。メッセージには説明が必要です

  • PROCEDURE_NOT_FOUND - 呼び出されたプロシージャが存在しません。この場合、主に TEST_CONNECTION プロシージャに関するものです。

  • UNKNOWN_SQL_ERROR - このエラーは、内部プロシージャを呼び出すときに予期しない事態が発生したときに発生します

  • INVALID_RESPONSE - このエラーは、内部プロシージャから受信した応答に response_code が含まれていない場合、またはエラーの応答に message が含まれていないが、 response_code が含まれている場合に発生します。

  • UNKNOWN_ERROR - 予期しない問題が発生したことを意味します - スローされた例外のメッセージが転送されます

  • TEST_CONNECTION() プロシージャから受信したカスタムエラーコード - コネクタ開発者によって定義されます

  • SET_CONNECTION_CONFIGURATION_INTERNAL() プロシージャから受信したカスタムエラーコード - コネクタ開発者によって定義されます

言語: 日本語