API参照

BotManager Java AgentはページリクエストとAPIリクエストを検出するメソッドを提供します。

ページリクエスト検出適用

HTTPリクエスト時にマクロ活動を検出するにはBotManager.detectPage()を呼び出します。

コード例：

import com.stclab.botmanager.agent.BotManager;
import java.util.HashMap;
import java.util.Map;

public class ExamplePageHandler {
    public void handleRequest(Object request, Object response) {
        Map<String, String> params = new HashMap<>();
        // customIdを渡す場合
        params.put("customId", "exampleCustomId"); // 場合によって選択的に適用可能
        boolean isAllowed = BotManager.detectPage(request, response, params);
        if (!isAllowed) {
            // 検出された場合追加処理不要（自動Redirect）
            return;
        }
        // 一般リクエスト処理
    }
}

APIリクエスト検出適用

REST APIリクエスト時にマクロ検出を適用するにはBotManager.detectApi()を呼び出します。

コード例：

import com.stclab.botmanager.agent.BotManager;
import java.util.HashMap;
import java.util.Map;

public class ExampleApiHandler {
    public void handleApiRequest(Object request, Object response) {
        Map<String, String> params = new HashMap<>();
        // customIdを渡す場合
        params.put("customId", "exampleCustomId"); // 場合によって選択的に適用可能
        boolean isAllowed = BotManager.detectApi(request, response, params);
        if (!isAllowed) {
            // 検出された場合追加処理不要（自動Redirect）
            return;
        }
        // 一般リクエスト処理
    }
}

Interceptorに適用

サーバーリクエストを処理するミドルウェアに以下のようにロジックを追加します。以下はInterceptorを使用した例です。

コード例：

import com.stclab.botmanager.agent.BotManager;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;

import java.util.HashMap;
import java.util.Map;

@Component
public class ApiInterceptorWithParams implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        Map<String, String> params = new HashMap<>();
        // 以下の項目は初期化設定値を特定状況に異なる値で渡す時に使用
        params.put("tenantId", "exampleTenantId"); // 場合によって選択的に適用可能
        params.put("domainName", "example.com"); // 場合によって選択的に適用可能
        params.put("customId", "exampleCustomId"); // 場合によって選択的に適用可能

        boolean isAllowed = BotManager.detectApi(request, response, params);
        if (!isAllowed) {
            // 検出された場合追加処理不要（BotManagerがリダイレクト処理）
            return false; // リクエスト中断
        }
        return true; // リクエストを継続処理
    }
}

メソッド種類

detectPageメソッド

detectPageはブラウザでページ単位のリクエストを処理する時に使用されます。

説明：

• 検出されたリクエストに対してサーバーはHTTP応答ヘッダーのLocationフィールドを通じてリダイレクトを実行し、これはHTTP標準リダイレクト方式で全てのブラウザでサポートされます。
• この方式はページ遷移が発生するため一般的なブラウザリクエスト処理フローに合わせて設計されました。

特徴：

• 主にページロード時に動作し、ブラウザがサーバーから返されたLocation値を確認して自動でリダイレクトを実行します。
• 追加的に、クライアント側の設定なしで検出が動作するため簡単に適用できます。

メソッドシグネチャ：

// RequestとResponseのみ使用
boolean isAllowed = BotManager.detectPage(request, response);

// 追加パラメータ渡し可能
boolean isAllowed = BotManager.detectPage(request, response, params);

パラメータ：

• request：クライアントリクエストオブジェクト（HttpServletRequest）
• response：サーバー応答オブジェクト（HttpServletResponse）
• params：検出に必要な追加情報（Map<String, String>形式）
  • 例：{ "tenantId": "exampleTenant", "domainName": "example.com", "customId": "user123" }

戻り値：

• true：検出通過、リクエストを継続処理できる
• false：検出ブロック、自動でリダイレクトが実行される

detectApiメソッド

detectApiはブラウザで非同期API呼び出し（例：XMLHttpRequest、fetch）を処理する時に使用されます。

説明：

• 検出されたリクエストに対してサーバーは応答ヘッダーに約束されたキーX-BotManager-Locationを追加してリダイレクト情報を伝達します。
• detectApiはブラウザが非同期でAPIを呼び出した状況でも適切に動作するように設計されました。

重要事項：

• 非同期API呼び出しの場合ブラウザはLocationヘッダーを通じたリダイレクトを自動で処理しないため、クライアント側でこれを手動で処理する必要があります。
• このために必ず**botmanager-browser-agent**がブラウザに適用されている必要があります。
  • botmanager-browser-agentはブラウザで非同期呼び出し（xhr、fetch）をフッキング（hooking）してX-BotManager-Locationヘッダーを検出しクライアント側で適切なリダイレクトを実行します。
• botmanager-browser-agentが適用されていない環境ではdetectApiが正常に動作しない場合があります。

メソッドシグネチャ：

// RequestとResponseのみ使用
boolean isAllowed = BotManager.detectApi(request, response);

// 追加パラメータ渡し可能
boolean isAllowed = BotManager.detectApi(request, response, params);

パラメータ：

• request：クライアントリクエストオブジェクト（HttpServletRequest）
• response：サーバー応答オブジェクト（HttpServletResponse）
• params：検出に必要な追加情報（Map<String, String>形式）
  • 例：{ "tenantId": "exampleTenant", "domainName": "example.com", "customId": "user123" }

戻り値：

• true：検出通過、リクエストを継続処理できる
• false：検出ブロック、X-BotManager-Locationヘッダーが応答に追加される（Browser Agentが処理）