【完全ガイド】Dify APIでGASを使って簡単にスプレッドシートからAIチャットボットを呼び出す方法
皆さん、Difyは使っていますか？
これまでDifyの様々な機能を紹介してきましたが、チャットボットやエージェント・ワークフローなどを他のアプリでも利用出来たらいいのにと思うことはありませんか？
今回はDifyのAPIの利用方法と注意するポイント、そして実際にGASのコードから接続してスプレッドシートの関数としてチャットボット(エージェント)を利用する方法を解説します。
そもそもAPIって何？なにを確認すればいい？
APIとは？
API（Application Programming Interface）は、異なるソフトウェアシステム間でデータやサービスを交換するための仕組みです。
Web APIは、インターネットを通じてこの機能を提供し、クライアント（例：ウェブブラウザやモバイルアプリ）がサーバーと通信することを可能にします。
APIを使用する際の重要な確認ポイント
APIを利用するときは、まずどのように利用するか、何を送信して何が返ってくるかなどのルールが書かれているドキュメントを確認します。
DifyのAPIは現状1ページでチャットボット周りの情報がまとまっているので、まとめてAIに渡すことでコードを生成することが可能です。
しかし、修正したいときやエラーが出た時に改善するためには前提知識が必要になってくるのでポイントを抑えておきましょう。
エンドポイント：APIにアクセスするための特定のURLやパス
HTTPメソッド：GET, POST, PUT, DELETE などの操作タイプ
リクエストパラメータ：APIに送信する必要がある情報
認証方法：APIにアクセスするための認証情報（APIキーなど）
レスポンス形式：通常はJSON形式で返されるデータの構造。何がどんな形で返ってくるか。
エラーハンドリング：エラー時のレスポンスコード。原因と対処方法。
レート制限：APIの使用回数などの制限。
エンドポイント
APIリクエストを送信する際は、以下の例のようにパスをベースURLに追加します。
例：https://api.dify.ai/v1/chat-messages
リクエストボディの説明の前に、用語の説明をします。
文字列(string)：受け付けるデータは文字列形式のみ
オプション(option)：これがついているパラメータは無くても動作します。ない場合、もしくは必須(required)の場合は必ずそのパラメータを送信しないといけません。
オブジェクト(object)：複数のキーと値のペアを含む構造化されたデータ
配列(array)：複数の値をリスト形式で保持するデータ構造
ブール値(boolean)：trueまたはfalseの2つの値のみを取るデータ型
HTTP メソッド
GET：リソースの取得に使用。データを変更せずに読み取るだけの操作。
POST：新しいリソースの作成や、サーバーにデータを送信する操作に使用。
PUT：既存のリソースを更新するために使用。
DELETE：指定されたリソースを削除するために使用。
リクエストパラメータ
APIにデータを送信する際に使用するパラメータは、主に以下の2つの方法で送信されます：
クエリパラメータ： URLの末尾に`?`を付けて追加します。複数のパラメータがある場合は`&`で区切ります。
例：`https://api.example.com/users?id=123&name=John`リクエストボディ： POSTやPUTリクエストの場合、データをリクエストボディに含めて送信します。通常はJSON形式で送信します。 例：
{
"name": "John Doe",
"email": "john@example.com"
}認証方法
APIの認証方法には様々な種類がありますが、一般的なものは以下の通りです：
APIキー： リクエストヘッダーやクエリパラメータにAPIキーを含めて送信します。
OAuth： アクセストークンを使用して認証を行います。
Basic認証： ユーザー名とパスワードを Base64 エンコードしてヘッダーに含めます。
DifyのAPIでは、APIキーを使用して認証を行います。
レスポンス形式
多くのAPIはJSON形式でデータを返します。レスポンスの例：
{
"id": 123,
"name": "John Doe",
"email": "john@example.com",
"created_at": "2023-07-21T10:30:00Z"
}レスポンスの構造を理解することで、必要なデータを適切に取り出すことができます。
エラーハンドリング
APIがエラーを返す場合、通常は以下の情報が含まれます：
HTTPステータスコード： 400番台はクライアントエラー、500番台はサーバーエラーを示します。
エラーメッセージ： エラーの詳細な説明。
エラーコード： エラーを特定するための一意の識別子。
エラーレスポンスの例：
{
"error": {
"code": "invalid_parameter",
"message": "The 'name' parameter is required."
}
}レート制限
APIの過剰な使用を防ぐため、多くのAPIはレート制限を設けています。一般的な制限方法には以下があります：
時間あたりのリクエスト数制限： 例えば、1時間に1000リクエストまで。
同時接続数の制限： 一度に処理できるリクエスト数の制限。
日次または月次のクォータ： 1日または1ヶ月あたりの総リクエスト数の制限。
レート制限に達した場合、通常は429 (Too Many Requests) エラーが返されます。
APIを確認しよう
まずはチャットボット(エージェント)のAPIを見てみましょう。
チャットボット→基本を選択して作成するをクリックしてください。
作成したら、左のメニューバーのAPIアクセスをクリックしてください。
このように英語のページが表示されます。
このページの内容をAIに渡しても仕様に合わせてコードを書いてくれますが、今回は特に重要な箇所を抜粋して解説していきます。
Authentication(認証)
右上のAPIキーのボタンからAPIキーを発行することができます。
各ボット毎にAPIキーを発行でき、APIキーでどのボットか判別するので複数のボットを扱う場合は注意してください。
また、APIキーが流出すると勝手にLLMを利用されてしまう可能性もあるので管理にも十分注意して下さい。
チャットメッセージ送信
