メインコンテンツへスキップ
このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、英語版 を参照してください。
カスタム API スキャナーでスキャンするナレッジベースでは、アップロードされたファイルを Dify が自社のスキャンサービスに送信します。その後、サービスが返した判定結果に従って処理します。問題のないファイルは通常どおりインデックス化され、感染したファイルはブロックされます。 エンドポイントが稼働したら、連携 > ファイルセキュリティスキャン > スキャナーを追加 > カスタム API で追加します。ナレッジベースでスキャンを有効にする方法は、アップロードされたファイルのマルウェアスキャン を参照してください。
このスキャナーの種類は、連携 の カスタム API セクションとは別のものです。同セクションは API ベースの拡張機能を管理するもので、リクエストの形式も異なります。

ファイルの受信

Dify は、ファイルを 1 つずつ個別のリクエストで送信します。
任意の秘密の文字列を API キーとして決め、スキャナーの追加時に Dify に入力します。サービス側ではこのキーを検証し、一致しない場合は 401 を返してください。 フォームには、ファイルと 5 つのテキストフィールドが含まれます。
file
スキャン対象のファイルです。
string
このスキャンの ID です。Dify がスキャンを自動で再試行する際は、同じ ID が送信されます。そのため、同じリクエストが再び届いたときは、スキャンし直さずに初回の結果で応答できます。後からナレッジベースでドキュメントを再試行した場合は、新しい ID で新しいスキャンが始まります。
string
report.docx などのファイル名です。
string
バイト単位のファイルサイズを、482113 のような 10 進数の文字列で表したものです。
string
ファイルの MIME タイプです。Dify が判別できない場合は空になります。
string
ファイル内容の SHA3-256 ハッシュを 16 進数で表したものです。空の場合もあります。常にハッシュが必要な場合は、サービス側でファイル内容から計算してください。

判定結果の返却

2xx のいずれかのステータスコードと、JSON オブジェクトを返します。
string
必須
clean、infected、unscannable のいずれかです。
string[]
検出された脅威の名前です。ブロックされたドキュメントのエラーメッセージでユーザーに表示されます。省略した場合、メッセージには unknown が検出されたと表示されます。Dify は最大 20 件の名前を保持し、それぞれ 200 文字を超える部分は切り捨てます。
string
スキャンエンジンの名前またはバージョンです。Dify 上には表示されません。
string
ファイルをスキャンできなかった理由です(最大 500 文字)。Dify 上には表示されません。
サービスが判定できないファイルの扱いは、ナレッジベースの ファイルをスキャンできない場合(暗号化されている、またはサイズが大きすぎる) で決まります。デフォルトではブロックされますが、スキャンせずに受け入れるよう設定することもできます。ブロックされたファイルに表示されるエラーメッセージは、返す内容によって次のように変わります。
  • サイズが大きすぎる場合:413 を返します。エラーメッセージには、ファイルがスキャナーのサイズ上限を超えていると表示されます。
  • 暗号化されている、形式に対応していない、またはその他の理由の場合:unscannable を返します。理由にかかわらず、エラーメッセージには、スキャナーがそのファイルに対応していないと表示されます。

ステータスコードの選び方

Dify は、返されたステータスコードとボディに基づいて、ファイルの扱いを決めます。
一時的な過負荷で、再試行すれば処理できる見込みがある場合は、429 ではなく 503 を返してください。

制限時間内の応答

各リクエストには 2 分以内に応答してください。Docker Compose でデプロイしている場合、Dify のリクエストはプロキシを経由します。このプロキシは、2 分間応答がないリクエストを切断します。 このプロキシを経由しない場合は、Dify 自体のタイムアウトが上限になります。デフォルトは 300 秒で、FILE_SCAN_REQUEST_TIMEOUT_SECONDS で設定します。詳しくは 環境変数 を参照してください。 タイムアウトしたリクエストは再送され、試行回数はデフォルトで最大 3 回です。そのため、エンドポイントの応答が遅いと、ドキュメントが約 6 分(3 × 2 分)待たされることがあります。その後、ナレッジベースの スキャナーが利用できない場合 の設定が適用されます。 時間内に処理を終えられないとわかっている場合は、タイムアウトを待たずに、すぐに 413 または unscannable を返してください。

Dify からエンドポイントへの接続

Dify の エンドポイント URL には、http://scanner.example.internal:8000/scan のように、パスを含む完全な URL を入力します。localhost ではなく、Dify から到達できるアドレスを使用してください。 Docker Compose でデプロイしている場合、Dify のリクエストが経由するプロキシは、デフォルトで内部アドレスへの通信もブロックします。エンドポイントが内部アドレスを使っている場合、そのアドレスを許可するまで、Dify はエンドポイントに接続できず、スキャナーも保存できません。許可するには、次のように設定します。
  • エンドポイント URL に IP アドレスを使う場合:SSRF_PROXY_ALLOW_PRIVATE_IPS にそのアドレスを設定します。
  • エンドポイント URL にホスト名を使う場合:SSRF_PROXY_ALLOW_PRIVATE_DOMAINS にそのホスト名を設定します。
詳しくは 環境変数 を参照してください。 プロキシは、https の通信をポート 443 でのみ許可します。デプロイ環境で HTTP_REQUEST_NODE_SSL_VERIFY が false に設定されていない限り、Dify は https エンドポイントの TLS 証明書を検証します。

保存前のテスト

エンドポイントが動作しているマシンから、Dify と同じ形式のリクエストを送信します。
スキャンロジックを実装したら、このリクエストを 2 回送信します。1 回目は問題のないファイル、2 回目は EICAR テストファイルを使い、それぞれに合わせて file_name、file_size、mime_type を変更します。エンドポイントからは、1 回目に clean、2 回目に infected が返るはずです。
EICAR テストファイルは無害なファイルですが、どのウイルス対策エンジンもマルウェアとして検出します。eicar.org から入手できます。
ナレッジベースでスキャナーを使い始める前に、実際のファイルもいくつか送信して、誤検知がないか確認してください。 Dify は判定結果を保持します。ワークスペース内で同じ内容を同じスキャナーで再度チェックする場合は、エンドポイントを呼び出さずに以前の判定結果を再利用します。
  • infected:無期限に再利用されます。そのため、問題のないファイルをサービスが誤って検出した場合、スキャナーを修正した後もそのファイルはブロックされたままです。
  • clean:デフォルトで 24 時間再利用されます(FILE_SCAN_CLEAN_VERDICT_TTL_HOURS で設定)。その間は、スキャナーを更新して検出できるようにしても、同じファイルはそのまま通過します。
Dify は、スキャナーの保存時と テスト のクリック時に、次のファイルを 1 つ送信して接続を確認します。
  • file:clean-test.txt(text/plain)
  • scan_id:connectivity-check
  • file_hash:空
形式が正しい判定結果であれば、内容にかかわらず確認に合格します。413 も合格です。Dify がスキャナーを保存するのは、確認に合格した場合だけです。 ナレッジベースでスキャナーを使い始めたら、そのナレッジベースに EICAR テストファイルをアップロード して、一連の処理全体を確認してください。

サンプルを基にした実装

次の Flask エンドポイントの my_scanner を、独自のスキャンロジックに置き換えてください。
scanner.py
コードを scanner.py として保存します。次に Flask をインストールし、Dify に入力する API キーを指定してエンドポイントを起動します。
最終更新日 2026年11月18日