Integration Functions

はじめに

Integration Functionsを使用すると、Catalyst Functionを他のZohoサービスのバックエンドとしてコーディング・使用し、それらとの統合を確立できます。Java、Node.js、またはPythonプラットフォームで、サポートされているサービスのバックエンド機能のビジネスロジックをCatalystを通じてコーディングできます。

外部サービスでその特定の機能にアクセスすると、HTTP呼び出しを通じてCatalystでコーディングされたIntegration Functionの実行が自動的に呼び出されます。

外部サービス用のIntegration Functionsを作成すると、CatalystでFunctionを保存・管理できるため、Catalyst LogsやApplication Performance Monitoringを通じてFunction実行のログやレポートを表示するなど、さまざまなCatalyst機能やツールにアクセスできます。

Catalystは、統合可能なサービス用の専用の個別SDKパッケージを提供しています。SDKには、アプリケーションに簡単に組み込んでサービス用の強力なバックエンドを構築するためのクラス、オブジェクト、メソッドのコードテンプレートが含まれています。

CLIでIntegration Functionsのテスト用にサンプルペイロードを生成することもできます。詳細については、Event Generateヘルプページを参照してください。

Cliq統合

Catalystは現在、Integration Functionsを通じてZoho Cliqとの統合をサポートしています。Cliqはチームコミュニケーションを促進し、コラボレーション、会話の整理、タスクのスケジュール管理などを可能にします。また、開発者が業務活動を自動化し、他のアプリケーションからチャットウィンドウ内にデータを取り込む内部ツールを構築するためのプラットフォームも提供しています。作成したツールを配布でき、Cliqのエンドユーザーはインストールして機能にアクセスできます。

Catalyst Integration Functionsを使用すると、以下のCliq内部ツールをバンドルできるCliqエクステンションのバックエンドをコーディングできます：

• Bots: タスクを処理したりクエリに応答する会話型インターフェース
• Commands: 組み込みまたはカスタムアクションを実行するスラッシュコマンド
• Message Actions: 個々のメッセージへのレスポンスとして実行されるアクション
• Widgets: Cliqのホーム画面をカスタマイズできます
• Functions: イベントの発生に基づいてタスクを実行できるカスタムFunctions

これらの内部ツールとエクステンションの詳細については、Cliq開発者ドキュメントを参照してください。

メリット

• Cliqがデフォルトでサポートするプログラミング環境であるDelugeではなく、Java、Node.js、またはPythonプラットフォームでバンドルされたエクステンションをコーディングできます
• LogsまたはAPMを通じて、Cliqバックエンドfunctionsの実行ログと詳細なパフォーマンスレポートにアクセスでき、問題領域の特定と即座の修正が可能です
• Cliq統合専用の機能豊富なSDKサポートにより、事前にコーディングされたクラスファイルとコードテンプレートで実行可能なアクションを容易に理解できます
• あらゆるCliqコンポーネント用のカスタムハンドラークラスを作成し、ニーズに基づいてロジックを記述できます

CatalystでのIntegration Functionsの作成

他のFunctionタイプと同様に、コンソールからIntegration Functionを作成するか、CLIから初期化できます。CLIから初期化する場合は、外部IDEを使用してコーディングし、Catalystコンソールにデプロイできます。

コンソールまたはCLIからIntegration Functionを作成する際、functionを作成するサービスを選択するだけです。他のFunctionタイプとは異なり、SDKなしでIntegration Functionを作成するオプションはありません。SDK構造を使用することでCliqコンポーネントをより深く理解できるためです。

Integration Functionの構造を詳しく見てみましょう。

Cliq Integration Functionの構造

Integration Functionパッケージには、他のFunctionタイプとは異なるコンポーネントが含まれています。Catalystのfunctionディレクトリには、一般的にメインファンクションファイルと、Java、Node.js、またはPythonのSDKコンポーネントおよび設定ファイルが含まれています。

他のFunctionタイプと同様に、Integration Functionのボイラープレート構造にも必要なすべてのSDKコンポーネントと設定ファイルが含まれています。ただし、ディレクトリに追加されるJARファイルやNodeモジュールに加えて、Integration FunctionのパッケージにはCatalyst Cliq SDKも含まれています。SDKは、ハンドラークラスの作成とサービス固有のビジネスロジックの開発に必要なインターフェースとオブジェクトを提供します。コードテンプレートには、Cliqエクステンションの各コンポーネント用の個別のハンドラークラスが含まれています。つまり、bots、commands、widgets、functions、message actions用の個別のハンドラークラスファイルがあります。

ハンドラークラスについて説明する前に、まずJava、Node.js、Python Functionのサンプル構造を確認しましょう。

Java

Javaのファイル構造には、メインJavaファイル、ハンドラークラス、Catalyst Java SDKのJARファイル、設定ファイルが含まれています。

Cliq Java SDKは、CLIからfunctionを初期化するか、コンソールで作成すると自動的に含まれます。また、Cliq Java SDKをこちらから取得することもできます。

Node.js

Node.jsのファイル構造にも、メインfunction、ハンドラークラス、Catalyst Node.js SDKのNodeモジュールファイル、設定ファイルが含まれています。

Cliq Java SDKと同様に、Cliq Node.js SDKもCLIからfunctionを初期化するか、コンソールで作成すると自動的に含まれます。

手動でインストールするには、ターミナルを使用してNode.js functionのディレクトリから以下のコマンドを実行する必要があります：

npm install zcatalyst-integ-cliq

Python

Python Integration Functionを作成すると、functionsディレクトリに追加されるPythonモジュールに加えて、Cliq Python SDKと呼ばれるIntegration Functionのパッケージも含まれます。SDKは、ハンドラークラスの作成とサービス固有のビジネスロジックの開発に必要なインターフェースとオブジェクトを提供します。コードテンプレートには、Cliqエクステンションの各コンポーネント用の個別のハンドラークラスが含まれています。つまり、bots、commands、widgets、functions、message actions用の個別のハンドラークラスファイルがあります。

pip install zcatalyst-cliq

Catalyst Cliq SDKパッケージには、Cliqアプリケーションの内部ツールに固有の以下のサブパッケージが含まれています。これらのツールの詳細については、こちらのセクションを参照してください。

Cliqハンドラークラス

Cliqハンドラーには、Cliqコンポーネントの特定のアクションに対するビジネスロジックの定義が含まれています。各コンポーネントには、特定のアクションやイベントを処理するための複数のハンドラーが含まれています。

例えば、Cliq botのハンドラーには以下のようなものがあります：

• Welcomeハンドラー: ユーザーがbotにサブスクライブした際のカスタムメッセージを定義します
• Messageハンドラー: botがメッセージを受信した際にトリガーされます
• Mentionハンドラー: botがチャットでメンションされた際にレスポンスをレンダリングします

同様に、Catalystがサポートする各Cliqコンポーネント（Commands、Message Actions、Widgets、Functions）にも個別のハンドラーがあります。

各コンポーネントでサポートされるすべてのハンドラーの詳細については、Cliqヘルプページを参照してください。

Catalystは、各ハンドラークラスでエクステンションの構築に役立つ必要なオブジェクトとメソッドのテンプレートを提供しています。Cliq呼び出しの解析、適切な実装へのルーティング、必要なレスポンスの構築など、さまざまなアクションの処理方法を理解するのに役立ちます。

例えば、BotClass.java、bot-handler.js、またはmain.pyには、botハンドラークラスの各個別ハンドラーのサンプルコードテンプレートが含まれています。

これらの定義を参照し、これらのメソッドを使用してエクステンションの独自のロジックをカスタマイズできます。要件に基づいてハンドラークラスを変更し、必要なもののみを含めることができます。ユーザーはこのSDKを使用して、Cliq呼び出しの解析、対応する実装への呼び出しのルーティング、出力レスポンスの形成を行うことができます。

ハンドラークラスファイルのマッピング

JavaおよびNode.js Functionsのcatalyst-config.jsonでのマッピング

すべてのハンドラークラスファイルは、functionのcatalyst-config.json設定ファイルにマッピングされます。設定ファイルには通常、Catalyst Functionの基本的な実行およびデプロイの詳細のみが含まれています。ただし、Integration Functionの場合、このファイルにはfunctionで使用されるハンドラークラスのマッピングも含まれています。

このマッピングにより、Functionが呼び出されたときにCatalystが適切なアクションセットを実行できます。

Cliqコンポーネント用の新しいハンドラークラスファイルを作成し、独自のロジックを定義することもできます。ただし、ハンドラークラスファイルをcatalyst-config.jsonファイルに手動でマッピングする必要があります。マッピングのキーの記述形式が同じであることを確認してください。

Catalyst Cliq SDKの一部として作成されるデフォルトのハンドラーファイルは、コンソールまたはCLIからfunctionを作成した時点ですでにマッピングされています。

Python Functionsのmain.pyでのマッピング

Integration Functionを作成すると、Cliq Python SDKが現在のプロジェクトのfunctionディレクトリ内に自動的にインストールされます。Pythonの場合、すべてのハンドラークラスファイルはfunctionのmain.pyファイルにマッピングされます。このマッピングにより、Functionが呼び出されたときにCatalystが適切なアクションセットを実行できます。

Cliqコンポーネント用の新しいハンドラークラスファイルを作成し、独自のロジックを定義することもできます。ただし、ハンドラークラスファイルをmain.pyファイルに手動でマッピングする必要があります。マッピングのキーの記述形式が同じであることを確認してください。

Cliq Python SDKの一部として作成されるデフォルトのハンドラーファイルは、CLIからfunctionを作成した時点ですでにマッピングされています。

import zcatalyst-cliq
# ここにCliqハンドラーファイルのマッピングを指定してください
config = {
    "ZohoCliq": {
        "handlers": {
            "bot_handler": "handlers/bot_handler.py",
            "function_handler": "handlers/function_handler.py",
            "installation_validator": "handlers/installation_validator.py",
            "command_handler": "handlers/command_handler.py",
            "widget_handler": "handlers/widget_handler.py",
            "messageaction_handler": "handlers/message_action_handler.py",
            "installation_handler": "handlers/installation_handler.py"
        }
    },
}
def handler(request, response):
    handler_resp = zcatalyst_cliq.execute(request, config)
    response.set_content_type('application/json')
    response.send(handler_resp)

IntegrationRequest型のrequestオブジェクトはexecute()メソッドの引数として渡され、Cliqの内部ツールの名前やそのツールで実行される操作などの情報で解析されます。configプロパティにはハンドラークラスファイルと各ハンドラーのマッピングが含まれており、メソッドの別の引数として渡されます。パラメータに基づいて、execute()メソッドはリクエストを各ハンドラークラスで処理する操作を進め、レスポンスを返します。

CatalystでIntegration Functionを作成した後、Cliqでfunctionを呼び出すエクステンションを作成できます。Cliqでのエクステンション作成については、こちらのセクションを参照してください。

CliqでのExtensionの設定

Cliqエクステンションのバックエンドを開発した後、Cliqでエクステンションを設定する際にfunctionを追加する必要があります。これはCliq Extension - Catalyst Integration Functionの一意のマッピングとなります。

そのエクステンションのコンポーネントがCliqを通じて呼び出されるたびに、マッピングされたCatalyst Functionがトリガーされます。そのリクエストに対して定義された適切なアクションがハンドラークラスを通じてトリガーされます。

例えば、バックエンドがCatalystで定義されているbotにCliqのエンドユーザーがメッセージを送信すると、認証後にリクエストがCatalystに渡されます。コンポーネント、ユーザー、チャットの詳細がHTTPリクエストのリクエストボディに添付されます。

CatalystはBotClass.java、bot-handler.js、またはmain.pyファイルで定義されたメッセージハンドラーを呼び出し、適切なアクションを実行します。CatalystはレスポンスをCliqに返し、Cliqコンポーネントのフロントエンドでレンダリングされます。

Cliqでのエクステンション作成

Cliqでエクステンションを作成し、Cliqの開発者コンソールからbots、widgets、commandsなどのコンポーネントをバンドルするように設定できます。

CliqエクステンションでCatalyst Integration Functionを設定するには、Cliqでエクステンションを作成する際に実行タイプとして「Catalyst Function」を選択する必要があります。

次に、ドロップダウンリストからCatalystプロジェクトを選択する必要があります。Catalystアカウントのすべてのプロジェクトがここにリストされます。Create Projectをクリックして、Catalystにリダイレクトし新しいプロジェクトを作成することもできます。

次に、このエクステンションに関連付けられるIntegration Functionをドロップダウンリストから選択する必要があります。エクステンションの他の詳細とコンポーネントを設定した後、Create Extensionをクリックします。

これによりCatalystとの統合が作成され、コンポーネントにアクセスするたびにIntegration Functionが実行されるようになります。

Cliq用のCatalystエクステンション開発の詳細については、Catalystタイプエクステンションヘルプドキュメントを参照してください。