カスタムデータソースコネクタの設定
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 Connector
- SQL コネクタ
- NoSQL コネクタ
コネクタがこれらのタイプのいずれかに適合する場合は、対応するベースクラスにコネクタを拡張します。 それ以外の場合は、コネクタインターフェイスを実装してゼロから作成します。
Config インターフェイス 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– 指定された形式のテンプレートのリストを返します。