Guides
Start typing to search…

Custom Actionの利用

このチャプターのゴール

  • Custom Actionの概要と利用方法が理解できている
  • JavaScriptを使用して独自の機能を実装する方法が理解できている

※本チャプターでは、JavaScriptプログラミングの基礎知識が必要になります。

Custom Actionとは？

Custom Actionとは、miiboのエージェントに独自の機能を追加するための仕組みです。JavaScriptを使用して実装した機能を、Webhookと連携させることで、エージェントの応答をカスタマイズしたり、様々なActionを実装することができます。

Custom Actionを利用することで、以下のような機能を実現できます：

  • 外部APIとの連携による情報取得や更新
  • データの加工や変換処理
  • 独自のビジネスロジックの実装
  • 複雑な条件分岐や計算処理

Custom Actionは「外部サービス連携」の一覧からご利用いただけます。

miibo JSについて

Custom ActionのJavaScriptコードは「miibo JS」という独自の実行環境で動作します。miibo JSは特殊な実行環境のため、一般的なJavaScript環境とは異なる制約や仕様があります。

具体的なコーディング規約やルール、制約事項については、後続の「miibo JSの実装」チャプターをご参照ください。

https://miibo.readme.io/docs/miibo-js%E3%81%AE%E5%AE%9F%E8%A3%85-1

そちらでmiibo JS特有の実行環境や、推奨される実装パターンについて詳しく解説しています。

Custom Actionの構成要素

Custom Actionは以下の要素で構成されています：

  1. 基本情報

    • 名前（必須）
    • 説明
    • サムネイルURL

  2. miibo JSコード（必須）

    • 処理内容をJavaScriptで記述
    • 処理結果は戻り値として返却

  3. 入力パラメータ（Input Parameters）

    • 名前
    • データ型（String、Number、Boolean、Object）
    • デフォルト値
    • 必須/任意の指定
    • 説明

  4. 環境変数

    • キー
    • 値
    • シークレット指定（機密情報の場合）

コードの実装例

const result = {
    success: false,
    error: null
};

try {
    // 外部API呼び出しの例
    const response = fetch('https://api.example.com/data', {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${env.API_TOKEN}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            param: input.value
        })
    });
    
    if (response.status !== 200) {
        throw new Error(`API request failed: HTTP ${response.status}`);
    }

    result.success = true;
} catch (err) {
    result.error = err.message;
}

return result;

変数とパラメータの参照方法

  1. 入力パラメータの参照

    • input.パラメータ名 の形式で参照
    • 例：input.value、input.userId

  2. 環境変数の参照

    • env.変数名 の形式で参照
    • 例：env.API_TOKEN、env.SECRET_KEY

特殊関数

GoogleのサービスアカウントからAccessTokenを取得する

Google Cloud Platforの提供するサービスアカウントのJsonを利用し、認証を行うことができます。
環境変数にJSONの値を登録し、下記のように呼び出すことでtokenを取得できます。


const tokenInfo = getGoogleAccessToken(env.GOOGLE_APPLICATION_CREDENTIALS_JSON);

下記はBigQueryのAPIを呼び出す例です。

try {
    // サービスアカウントJSONからGoogle OAuth2トークンを取得
    const tokenInfo = getGoogleAccessToken(env.GOOGLE_APPLICATION_CREDENTIALS_JSON);
    
    // BigQuery APIへのリクエスト
    const response = fetch(`${env.BIGQUERY_API_URL}/projects/${env.BIGQUERY_PROJECT_ID}/queries`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${tokenInfo.access_token}`
        },
        body: JSON.stringify({
            query: input.query,
            useLegacySql: false
        })
    });
    
    if (response.status !== 200) {
        throw new Error(`BigQuery API request failed: ${response.status}`);
    }
    
    result.success = true;
    result.messages = ['Query executed successfully', response.body];
} catch (err) {
    result.error = err.message;
}

Webhookとの連携

Custom ActionはWebhook機能と連携することで、以下のようなケースで利用できます：

  1. ユーザーの発話をトリガーとした実行
  2. エージェントの応答をトリガーとした実行
  3. Function Callingによる条件付き実行

Webhook連携の設定手順

  1. Webhooks画面でWebhookを新規作成
  2. 連携タイプで「Custom Actionと連携」を選択
  3. 使用するCustom Actionを選択
  4. パラメータの設定
  5. トリガー条件の設定

テンプレートの利用

Custom Actionには、一般的な用途向けにテンプレートが用意されています。テンプレートを利用することで、基本的な機能をすぐに実装できます。

テンプレートの種類

各テンプレートには以下の情報が含まれています：

  • テンプレート名
  • 機能の説明
  • サンプルコード
  • 必要な環境変数の定義
  • 入力パラメータの定義

テンプレートの利用手順

  1. テンプレート選択画面の表示

    • Custom Action一覧画面で「テンプレートを利用する」ボタンをクリック
    • 利用可能なテンプレート一覧が表示されます

  2. テンプレートの選択

    • テンプレートの説明を確認
    • 目的の機能に合ったテンプレートの「インポート」ボタンをクリック

  3. 環境変数の設定

    • テンプレートで定義された環境変数の入力画面が表示されます
    • 必須の環境変数を入力（例：API KEY、エンドポイントURLなど）
    • シークレット情報は「シークレット」としてマークされます

  4. カスタマイズと保存

    • テンプレートのコードをニーズに合わせて修正
    • 必要に応じて入力パラメータを追加・変更
    • 名前や説明を編集
    • 「保存」ボタンをクリックして完了

テンプレート利用のベストプラクティス

  1. 環境変数の管理

    • APIキーなどの認証情報は必ずシークレットとして設定
    • 環境変数の名前は用途が分かりやすいものに変更可能

  2. コードのカスタマイズ

    • テンプレートコードは自由にカスタマイズ可能
    • 必要な機能の追加や不要な機能の削除を検討
    • コメントを適切に追加して可読性を向上

  3. テスト

    • カスタマイズ後は動作確認を実施
    • Webhook連携での動作も確認

  4. ドキュメント

    • カスタマイズした内容を説明に反映
    • パラメータの説明を明確に記載

セキュリティと注意点

  1. APIキーの管理

    • APIキーは適切に管理し、漏洩に注意
    • 必要に応じて定期的に再発行

  2. 環境変数の管理

    • 機密情報はシークレットとして設定
    • 本番環境の認証情報は慎重に管理

  3. エラーハンドリング

    • try-catchによる適切なエラー処理
    • エラーメッセージの適切な返却

  4. リソース使用

    • 実行時間は適切な範囲に収める
    • メモリ使用量に注意

トラブルシューティング

  1. コードが動作しない場合

    • シンタックスエラーがないか確認
    • 環境変数が正しく設定されているか確認
    • 実行環境の制限事項に抵触していないか確認
    • Curlを利用してエラーが起きていないかを確認

  2. Webhook連携で期待通りに動作しない場合

    • トリガー条件が適切か確認
    • パラメータが正しく設定されているか確認
    • エラーレスポンスを確認

  3. 外部API連携で問題が発生する場合

    • API認証情報が正しいか確認
    • ネットワーク接続に問題がないか確認
    • ログ画面でAPIのレスポンスステータスを確認

重要な注意事項

外部APIの利用について

  • 各種サービスのAPIキーやトークンの取得方法は、それぞれのサービスの公式ドキュメントをご確認ください
  • APIの利用制限や料金体系は各サービスによって異なります
  • 新しいAPIを利用する際は、該当サービスの最新のドキュメントを必ず確認してください
  • 各APIの利用規約を必ず確認し、遵守してください

コードの管理とメンテナンスについて

  • Custom Actionで実装したコードは、実装者の責任の下でメンテナンスしてください
  • 外部APIの仕様変更やアップデートへの対応は適宜必要です
  • 実装したコードのバグ修正や機能改善は自己責任で行ってください
  • 重要なコードは別途バックアップを取ることを推奨します

セキュリティ上の注意点

  • APIキーなどの認証情報は適切に管理し、第三者に漏洩しないよう注意してください
  • 認証情報が漏洩した場合は、速やかに該当サービスで無効化・再発行などの対応を行ってください
  • 個人情報や機密情報を扱う場合は、各種法令やガイドラインに従って適切に処理してください

Updated 1 day ago

Did this page help you?