Transformer（トランスフォーマー）

Cognigy/Transformers

Reference to Cognigy repository on GitHub

Transformers Overview

Cognigy HelpCenter article

説明

Endpoint Transformers を使用すると、Endpoint の動作を変更できます。

次のような用途に使用できます：

• Flowに送信される前に、Endpointからのリクエストペイロードを変更する。
• ユーザーに送信される前に、Flowからの出力を変更する。
• カスタムビルドのエンドポイントを使用して、追加の統合を作成する。
• Webchatの出力をWhatsApp互換の出力に変換するなどの、チャネルの出力を別のチャネルで動作するように変換する
• カスタムサービスからのWebhookイベントを処理する。
• ユーザーからのメッセージを Flow の言語に変換する。

TransformerはTypeScriptに完全に対応しているため、変数やNPMモジュールが型付けされ、Transformerにカスタムインタフェースを記述することができます。ただし、TypeScriptの知識は必須ではなく、ごく一般的なJavaScriptを使用することもできます。

Technical video "Endpoint Transformers"

Watch this Episode of Cognigy Sessions for a technical deep dive

Transformer関数

以下のリストは、利用可能なすべてのTransformer関数の概要を示しています。それぞれのTransformer関数には、さらに詳しく説明するチャプターがあります。

Transformerの作成

Endpoint にTransformerを作成するには、Endpointの [Transformer Functions(トランスフォーマー関数)] タブを開きます。ここでは、設定可能なさまざまな Transformer 設定と Transformer コードエディタを紹介します。

Transformerコードエディターには、新しいEndpointsのデフォルト値があり、各Transformer関数がどのように使用されるべきかを簡単に説明しています。特定のTransformerが有効になると、対応するTransformer関数のコードが実行されます。

Transformer設定

特定の Transformer関数を使用するには、[Transformer Settings(トランスフォーマー設定)]セクションで有効にする必要があります。各Transformer関数を有効にするためのトグルがあります。Transformer関数は、コードを削除することなく、一時的に無効にすることもできます。

Transformerにおけるエラー処理

Transformerのデフォルトのエラー処理は、ログページにエラーを記録し、通常の実行を続けるというものです。つまり、Transformer 関数で何かが失敗しても、メッセージは Transformer 関数が存在しないかのように処理されます。

Transformerがパイプラインの重要な部分である場合、例えばカスタムEndpoint統合を構築する場合、エラー時に基礎となるEndpointを実行することはあまり意味がありません。[Abort On Error]という設定があり、これをオンにすると、Transformerのエラーを発生した後に実行を完全に停止することができます。

Transformerの実行停止

すべてのTransformer関数は特定の戻り値を予期し、その戻り値は特定のTransformer関数によって異なる方法で使用されます。Flowからの出力がすでに別のプラットフォームに転送されている場合など、実行を完全に停止したい場合があります。これを実現するために、Transformer関数は、nullやvoidなどの偽の値を返すことができます。

利用可能なモジュール

NPM モジュール

Transformerでは以下のNPMモジュールを使用できます：

Text Cleaner クラス

Code Nodes と同様に、Transformer も getTextCleaner 関数を使って、テキストをクリーニングする関数を公開している Text Cleaner クラスのインスタンスを取得できます。

ロギング

Transformers で、公開されているモジュール console.log、console.info、console.error を使用することができます。これにより、ログはそれぞれデバッグログ、情報ログ、エラーログとしてプロジェクトログページに表示されます。

HTTPリクエストの送信

Transformer 内から外部サービスに HTTP リクエストを送信することができます。すべての Transformer 関数はこの目的のために httpRequest モジュールにアクセスできます。このモジュールは引数として1つの構成オブジェクトを取る関数として呼び出されます。このオブジェクトは NPM モジュール Request の options オブジェクトと同じ形式です。例：

HTTP リクエスト

handleInput: async () => {
  const result = await httpRequest({
    uri: "some-uri",
    method: "POST",
    body: {},
    json: true
  });

  console.log(result);
  return result;
}

セッションストレージ

セッションストレージは、すべての Transformer 関数で利用可能なストレージオブジェクトで、セッション中常に利用可能です。これは、後で他の Transformer 関数で使用する変数を保存したり、トークの状態を保存したりするために使用できます。Transformer関数には、userIdとsessionIdを引数に取るgetSessionStorageという関数があります。これは通常のオブジェクトとして操作できる sessionStorage オブジェクトで解決される Promise を返します。例：

セッションストレージ

const handleOutput: async ({ userId, sessionId }) => {
    const sessionStorage = await getSessionStorage(userId, sessionId);

    sessionStorage.test = "test";

  // Muting complex objects
  // Instead of changing the objects directly inside sessionStorage
  // change them locally and then assign them to the sessionStorage
  let tempArr = sessionStorage.arr || [];
  tempArr.push(1);
  tempArr.push(2);
  sessionStorage.arr = tempArr;
}

さまざまなベースのTransformerタイプ

Transformer には 3 つのタイプがあり、各 Endpoint はそのうちの 1 つを実装します。各 Transformer タイプは、特定の Transformer 関数を処理する方法が若干異なります。

以下のセクションでは、異なる Transformer タイプの概要を簡単に説明します。Transformerの種類によって、Transformer関数の動作がどのように異なるかは、それぞれのTransformer関数のサブチャプターで説明します。

REST Transformer

REST Transformerは、RESTベースのすべてのEndpointに対して実装されます。つまり、ユーザーから1つのメッセージを受け取り、1つの応答を送り返します。これらのEndpointでは、Flow内に複数のSay Nodeを持つことが可能ですが、すべての出力は1つの出力に連結され、ユーザーに送信されます。

RESTベースのEndpointは以下のとおりです：

Webhook Transformer

Webhook Transformerは、WebhookベースのすべてのEndpointに対して実装されています。これは、ユーザーから1つのメッセージを受信しますが、Webhook URLを介してユーザーに複数回返信できることを意味します。

Webhook ベースの Transformer は以下のとおりです：

Socket Transformer

Socket Transformerは、通信にソケットを使用するすべてのEndpointに対して実装されています。これらのEndpoint は以下の通りです：

カスタム Endpointの作成

カスタムチャネルとの統合を作成する最初のステップは、カスタムチャネルがどのタイプのEndpointであるかを把握することです。カスタム統合がAPIベースのRESTを使用するのか、Webhook APIを使用するのか、ソケットベースなのかが分かれば、対応するEndpointをCognigy.AIで作成することができます。

カスタム統合の例がExampleリポジトリにあります。（下記参照）

新しいGitHubリポジトリでは、様々なトランスフォーマーの実装例を見ることができます：

https://github.com/Cognigy/TransformersSamples

Transformer Samples

Reference to Cognigy repository on GitHub