カスタムデータソースコネクタの設定
Experience Manager Guidesでは、要件に応じてコネクタをカスタマイズし、様々なデータソースで使用できます。 コネクタをカスタマイズするには、コネクタインターフェイスとその重要な機能を実装してから、インターフェイスを設定する必要があります。 また、リソースとカスタムコネクタを提供することもできます。
Experience Manager Guides用コネクタのカスタマイズ customize-connector
事前定義済みのインターフェイスと抽象クラスを使用して、データソースのコネクタをカスタマイズまたは設定できます。 ソースコード全体は、https://github.com/adobe/guides-data-source-connectors/tree/main/konnect-definitions で入手できます。
konnect-definitions については、
コネクタインターフェイスの実装 implement-interface
必要に応じて、次の手順を実行してインターフェイスとその機能を実装します。
- コネクタをシステムと統合するための標準化された方法を定義します。これにより、クエリの実行、接続の検証、メタデータの取得が可能になります。
- テンプレート、ロゴ、クエリなどの設定を行うデフォルトの方法を提供することで、UI の統合を容易にします。
- コネクタが正しく検証され、データソースを操作する際にエラー（
KonnectException）を処理できることを確認します。
このインターフェイスは、様々なタイプのデータコネクタを実装するためのブループリントとして機能し、より大きなソフトウェアエコシステム内の特定の統合および運用要件をコネクタが満たすようにします。
重要な関数 important-functions
次の重要な関数を実装します。
-
このメソッドは、コネクタのロゴとして使用される URL を返します。
-
デフォルトでは、空の文字列を返します。これは、上書きされない限り、ロゴ URL が提供されないことを示します。
の他の注 :- ロゴ URL とロゴクラス名の両方を指定する場合、ロゴ URL は、ユーザーインターフェイスにロゴを表示するために使用されます。
- 構成設定を使用してロゴ URL を指定した場合は、メソッド実装で設定された URL が上書きされます。
- このメソッドを使用して、コネクタがデータ ソースへの接続を確立できるかどうかを検証します。
- これは、
ConfigDtoオブジェクトをパラメーターとして受け取ります。このパラメーターには、接続資格情報やエンドポイント URL などの設定が含まれています。 - メソッドは、検証（接続テスト）が成功した場合、コネクタがデータソースに接続できることを示す true を返します。
- このメソッドを使用して、コネクタに対して 1 つのクエリを実行し、データソースとやり取りします。
- この操作をサポートするコネクタは、クエリの実行を処理し、応答を解析し、必要に応じて JSON 文字列に変換します。
- このメソッドで実行するクエリを、クエリ文字列やパラメーターなどの詳細を含む
QueryInfoDtoオブジェクト内にカプセル化します。 - このメソッドは、クエリの実行からの応答を表す JSON 文字列を返します。
の他のメモ : - このメソッドの実装は、特定のコネクタと、データソースとのインタラクションによって異なります。
KonnectExceptionを使用して、実行またはデータソースへの接続中に発生した例外またはエラーを処理します。
- この方法は
execute()と同じ目的で使用しますが、通常は UI コンポーネントでプレビューを表示するために、制限クエリを適用する追加機能とともに使用します。 - この操作をサポートするコネクタは、クエリの実行を処理し、応答を解析し、必要に応じて JSON 文字列に変換します。
- 前のメソッドと同様に、このメソッドで実行するクエリを
QueryInfoDtoオブジェクト内にカプセル化します。
の他のメモ :QueryResultDtoは、クエリとその実行ステータスに関するメタデータなど、クエリ実行の結果をカプセル化するカスタムクラスまたはデータ転送オブジェクトです。
- このメソッドは、UI （例：ユーザーがクエリを挿入または編集できるダイアログ）に表示できるサンプルクエリ文字列を返します。
- デフォルトでは、空の文字列を返します。これは、上書きされない限り、サンプルクエリが提供されないことを示します。
の他のメモ :- サンプルクエリを定義せずにメソッドが空の文字列を返した場合、UI のクエリの挿入ダイアログにサンプルクエリが表示されません。
- このメソッドは、コネクタに関連付けられたテンプレートのリストを返します。
- デフォルトでは、空のリストが返され、上書きされない限りテンプレートは提供されないことが示されます。
-
このメソッドは、クラス名をコネクタのロゴとして返します。 デフォルトでは、空の文字列を返します。これは、上書きされない限り、ロゴクラス名が提供されないことを示します。
の他のメモ :- ロゴ URL とロゴクラス名の両方を指定する場合、ロゴ URL は、ユーザーインターフェイスにロゴを表示するために使用されます。
- 構成設定でロゴクラス名を指定した場合は、メソッド実装で設定されたクラス名が上書きされます。
- このメソッドは、
connectorが有効かどうかを確認します。 - デフォルトでは、このメソッドは false を返します。つまり、このメソッドを実装するクラスによって上書きされない限り、コネクタは有効になりません。
- このメソッドを使用して、UI に表示できる説明文字列を返します。
- デフォルトでは、このプロパティは空の文字列を返します。これは、上書きされない限り、説明が提供されないことを示します。
- このメソッドは、コネクタを作成した作成者またはコネクタを担当する作成者の名前を取得する方法を提供します。
- これは通常、システムやフレームワーク内のコネクタの作成者またはメンテナーを特定し、認識するのに役立ちます。
- このメソッドは、コネクタに割り当てられた一意の名前を取得する方法を提供します。
- 返される名前は、特にコネクタの設定で名前が明示的に指定されていない場合に、ユーザーインターフェイス（UI）コンテキスト内でコネクタを識別するために重要です。
- この名前は、様々な UI コンポーネントで使用され、使いやすい方法でコネクタを表示または管理します。
- このメソッドは、コネクタに関連付けられたグループ名を取得する方法を提供します。
- グループ名は、通常、機能、目的、またはタイプに基づいて、コネクタを論理グループに整理または分類するために使用されます。
- これにより、設定 UI 内でのコネクタの管理と表示が容易になります。
- このメソッドは、このコネクタに関連付けられたテンプレートのデフォルトパスを返します。
- デフォルトでは、空の文字列を返します。これは、上書きされない限りデフォルトパスが設定されないことを示します。
- コネクタのロゴのSVG表現を返すには、このメソッドを使用します。
- デフォルトでは、このメソッドは空の文字列を返します。これは、上書きされない限り、SVGデータが提供されないことを示します。
- このメソッドは、UI プレビューでクエリまたは表示される最大行数を返します。
- デフォルトでは、DEFAULT_LIMIT_PREVIEW の値を返します。これは、プレビュー行のデフォルトの制限を表す定数です。
- このメソッドは、Config インターフェイスを実装し、このコネクタでサポートされているクラスに関する情報を提供します。
- これにより、アプリケーションまたはフレームワークは、コネクタと互換性のある設定を動的に検出し、操作できます。
デフォルトコネクタ実装のタイプ default-connectors
konnect-definitions ライブラリは、抽象コネクタの実装と、クエリを実行するための事前定義済みの関数を含んでいます。 これらのコネクタ実装は、テンプレートとして機能し、そのまま直接拡張して使用できます。 カスタム実装が必要な場合は、その関数をオーバーライドできます。
デフォルトのコネクタを実装する以外に、次のデフォルトの抽象クラスのいずれかを実装することもできます。
- Rest コネクタ
- ファイルコネクタ
- GraphQL コネクタ
- SQL コネクタ
- NoSQL コネクタ
コネクタがこれらのタイプのいずれかに適合する場合は、コネクタを対応する基本クラスに拡張します。 それ以外の場合は、コネクタインターフェイスを実装して、最初から作成します。
設定インターフェイス config-interface
Config インターフェイスは、特定の認証方法でデータソースを設定するように設計されているので、接続の作成方法を正確に制御できます。
Config インターフェイスでは、認証の詳細を柔軟に処理および実装できます。 実装が異なれば、データソースを認証するための様々な方法が提供されます。 コネクタは、Config インスタンスを使用して、データソースに対するクエリを実行および検証し、完全なワークフローを形成します。
コネクタは、Config インスタンスを使用して、データソースに対するクエリを実行および検証し、完全なワークフローを形成します。
設定実装は、データソースに接続するための認証の処理方法を定義します。 その後、この設定はコネクタ実装によってデータソースとやり取りされ、クエリが正しく実行および検証されるようにします。
全体として、Config インターフェイスは、特に認証設定に焦点を当てた、データソースに接続するためのワークフローの重要な部分です。
デフォルト設定実装のタイプ default-config-types
認証用のデフォルトの抽象設定実装には、次の 3 種類があります。
- RestConfig
- SqlConfig
- NoSqlConfig
設定がこれらのタイプのいずれかに適合する場合は、対応する基本クラスを拡張できます。 それ以外の場合は、Config インターフェイスを実装することでゼロから作成できます。
具体的な設定実装 concrete-config-implementation
konnect-definitions ライブラリには、広く使用されている認証設定の Config インターフェイスの事前定義済み実装が付属しています。 これらの設定は、コネクタで直接使用することも、Config インターフェイスを使用して新しく定義することもできます。 これらの実装には、次のものが含まれます。
- API キー認証設定
- 基本認証トークンベースの設定
- 基本的な認証設定
- ベアラートークン設定
- SQL 用のユーザー名パスワード設定
- NoSQL の接続文字列認証設定
その他のリソース resources
また、Experience Manager Guidesでは、ロゴやテンプレートのカスタムリソースを実装と共に提供できます。 これらのリソースは resources フォルダーに保存できます。
コネクタで使用できるようにするには、次のコネクタ関数を実装する必要があります。
-
getLogoSvg- ロゴのSVGを文字列として返します。 -
getTemplates– 指定された形式のテンプレートのリストを返します。