公開とAPI連携

1. 公開方法の種類

2. Webアプリ公開の設定

2.1 アクセス制御

• 公開範囲: 公開（誰でもアクセス可能）または限定公開（パスワード保護）などが選択可能です。

• 運用推奨: 社外公開前は関係者のみに限定公開し、検証完了後に一般公開へ切り替える運用を推奨します。

2.2 UIカスタマイズ

• アイコン、アプリ名、説明文、テーマカラーを設定し、ブランドイメージに合わせます。

• 必要に応じてフッターの著作権表示（Powered by Dify）のオン/オフを調整します（プランによる）。

3. API連携の実装

3.1 認証とエンドポイント

• Base URLの例:
• Cloud版: https://api.dify.ai/v1
• OSS版: http://{your-domain}/v1

• API Key:
• アプリ管理画面の「APIアクセス」からAPIキーを発行します。
• リクエストヘッダーに Authorization: Bearer {API_KEY} を含めて認証します。

3.2 主要なAPIエンドポイント

4. リクエストパラメータの詳細

• query (必須): ユーザーからの入力テキスト。

• user (必須): ユーザー識別子。エンドユーザーを一意に特定するID（例: user-123）。ログ分析やレート制限の基準になります。

• inputs (任意): アプリ内で定義した変数（Variables）に値を渡すためのオブジェクト。
• 例: プロンプト内に{{topic}}という変数がある場合、"inputs": {"topic": "科学"} のように指定します。
• 変数がない場合でも、空のオブジェクト{}が推奨されることがあります。

• response_mode (必須):
• streaming: ストリーミング形式（SSE）で逐次レスポンスを受け取る（推奨）。
• blocking: 処理完了後にJSONを一括で受け取る。

• conversation_id (任意): 会話を継続する場合に指定します。初回リクエスト時は空にし、レスポンスに含まれるIDを2回目以降にセットします。

• files (任意): 画像などを送信する場合に使用します（マルチモーダル対応モデルが必要）。

5. ストリーミングと会話管理

5.1 ストリーミング (SSE) の活用

• Server-Sent Events (SSE) 形式でデータがチャンク（断片）ごとに届きます。

• テキスト生成と並行して音声合成（TTS）やリップシンク処理を開始することで、待機時間を大幅に短縮できます。

5.2 会話の継続（セッション）

1. 初回: conversation_id なしでリクエスト。

2. 応答: レスポンスJSON内の conversation_id を保存。

3. 継続: 次のリクエストのbodyに conversation_id を含めることで、Difyが文脈（コンテキスト）を維持しながら、会話を継続できます。

6. 運用とセキュリティのベストプラクティス

6.1 APIキーの保護

• APIキーはサーバーサイド（Backend）で管理してください。フロントエンド（ブラウザやアプリ内）に埋め込むと、キーが漏洩し不正利用されるリスクがあります。

6.2 エラーハンドリングとレート制限

• 429 Too Many Requests: プランごとのリクエスト上限に達した場合に発生します。バックオフ（待機時間）を入れたリトライ処理を実装してください。

• タイムアウト設定は長め（数十秒〜）に確保するか、ストリーミング受信でタイムアウトを防ぐ設計にします。

• APIレスポンスのanswer部分をデジタルヒューマンの発話テキストとして利用します。

6.3 監視

• Dify管理画面の「ログ」機能でユーザーの会話履歴を確認できます。

• API利用量やエラー率は定期的にモニタリングし、必要に応じてプランのアップグレードやキーのローテーションを行ってください。