メインコンテンツにスキップ

Octoparse AgentTools APIでスクレイピングワークフローを実行する

エンドポイントの完全な仕様については、AgentTools APIリファレンスを参照してください。

Octoparse AgentTools APIを使って、対応テンプレートを検索し、クラウド抽出タスクを作成し、進行状況を監視し、結果をエクスポートする方法を説明します。

AgentTools APIは、データ収集のリクエストを実行可能なOctoparseのクラウドタスクに変換する必要がある、AIエージェントや自動化ワークフロー向けに設計されています。

低レベルAPIを使ってタスクを手動で作成・設定する代わりに、AgentTools APIはテンプレートの検索、パラメータの検証、タスクの実行、データのエクスポートという流れでワークフローを導きます。

始める前に

以下が必要です。

  • Octoparse APIキー

  • タスクの作成・検索に使用する外部ユーザーID（external user ID）

  • 対応するクラウド実行可能テンプレートへのアクセス権

以下のベースURLを使用します：

https://openapi.octoparse.com

AgentToolsのリクエストでは、APIキーをリクエストヘッダーで送信します:

x-api-key: YOUR_API_KEY

executeTask と searchTasks の各エンドポイントでは、さらに以下が必要です:

x-external-user-id: YOUR_EXTERNAL_USER_ID

ワークフローの概要

新しいスクレイピングリクエストでは、次の順序で実行します:

searchTemplates
→ executeTask
→ exportData

既存のOctoparseタスクの場合は、次の順序で実行します:

searchTasks
→ startOrStopTask
→ exportData

executeTask は、どのテンプレートを使用するか、およびそのテンプレートがどのパラメータを必要とするかを把握する前に呼び出さないでください。

例：Amazonの商品リストを収集する

この例では、対応するAmazon商品テンプレートを検索し、ワイヤレスイヤホンを対象としたタスクを作成し、エクスポートファイルを待ちます。

ステップ1：テンプレートを検索する

searchTemplates を使用して、収集したいWebサイトとデータにマッチするテンプレートをＦ検索します。

curl -sS \
  "https://openapi.octoparse.com/api/agentTools/searchTemplates?keyword=amazon%20product&page=1&limit=10" \
  -H "x-api-key: YOUR_API_KEY"

レスポンスにはテンプレートの一覧が含まれ、推奨テンプレート名が含まれる場合もあります。

確認すべき項目：

  • recommendedTemplateName

  • templates[].slug

  • templates[].executionMode

  • templates[].inputSchema

  • templates[].sourceTree

  • templates[].outputSchema

クラウド実行可能なテンプレートを使用してください。ローカル専用のテンプレートは executeTask から開始できません。

ステップ2：入力スキーマを確認する

タスクを作成する前に、選択したテンプレートの inputSchema を確認します。

各フィールドは、テンプレートが受け付けるパラメータを表します。リクエストを組み立てる際は、inputSchema[].field をパラメータのキーとして使用します。

例えば、あるテンプレートでは次のような入力が必要になる場合があります。:

{
  "search_keyword": ["wireless earbuds"],
  "site": "US"
}

重要なルール：

  • parameters は、JSONオブジェクトを文字列にシリアライズして送信する必要があります。

  • パラメータのキーには inputSchema[].field を使用します。

  • 複数値を取るフィールドでは、値が1つの場合でも配列で送信します。

  • ソースに基づくフィールドでは、表示されるラベルではなくオプションの key を送信します。

  • あるフィールドが別のフィールドに依存する場合は、先に親となるオプションを選択します。

ステップ3：クラウドタスクを作成して開始する

選択したテンプレートとパラメータを指定して executeTask を呼び出します。

curl -sS -X POST \
  "https://openapi.octoparse.com/api/agentTools/executeTask" \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-external-user-id: YOUR_EXTERNAL_USER_ID" \
  -d '{
    "templateName": "amazon_product_search",
    "taskName": "Amazon wireless earbuds",
    "parameters": "{\"search_keyword\":[\"wireless earbuds\"],\"site\":\"US\"}",
    "targetMaxRows": 100
  }'

正常なレスポンスでは、タスクIDが返され、通常は次のステータスになります:

{
  "data": {
    "success": true,
    "status": "accepted",
    "taskId": "task_abc",
    "retryGuidance": {
      "tool": "export_data",
      "waitSecondsMin": 60
    }
  }
}

accepted は、Octoparseがタスクを作成し、クラウド抽出の開始を要求したことを意味します。エクスポートファイルが準備できたという意味ではありません。

返された taskId を保存してください。次のステップで使用します。

ステップ4：検証エラーとソース選択の問題に対処する

executeTask が status: "invalid" を返した場合は、再試行する前にレスポンスを確認します。

よく含まれるフィールド：

  • missingParamNames

  • blockingIssues

  • invalidSourceSelections

  • inputSchema

  • recoverySuggestion

例えば、レスポンスで site が必須だと示された場合は、それをパラメータに追加して executeTask を再度呼び出します。

レスポンスが次を返した場合：

awaiting_source_selection

テンプレートに、ソースに基づく値の追加が必要です。テンプレートをIDまたはslugで再度クエリし、sourceTree を確認して正しいオプションのkeyを選択し、リクエストを再試行します。

requiresUserAction が true の場合は、無制限に再試行しないでください。

ステップ5：エクスポートの進行状況をポーリングする

executeTask が accepted を返したら、retryGuidance で指定された時間だけ待機します。

その後、exportData を呼び出します：

curl -sS \
  "https://openapi.octoparse.com/api/agentTools/exportData?taskId=task_abc&exportFileType=JSON&previewRows=5" \
  -H "x-api-key: YOUR_API_KEY"

APIは、次のいずれかのステータスを返す場合があります:

ステータス

意味

対処

collecting

タスクがまだ実行中です。

推奨された間隔だけ待機し、再試行します。

exporting

エクスポートファイルを生成中です。

推奨された間隔だけ待機し、再試行します。

exported

ファイルの準備ができました。

エクスポートURLを表示し、データをプレビューします。

no_data

タスクは完了しましたが、行が返されませんでした。

テンプレート、パラメータ、または対象サイトを確認します。

failed

タスクまたはエクスポートが失敗しました。

error、recoverable、retryGuidance を確認します。

invalid

リクエストが無効です。

taskId、エクスポートタイプ、プレビュー行数を確認します。

レスポンスに retryGuidance、suggestedNextCall、workflow の各フィールドが含まれる場合は、必ずそれに従ってください。APIからのガイダンスが一切ない場合を除き、ポーリング間隔をハードコードしないでください。

ステップ6：エクスポートしたデータを利用する

エクスポートの準備が整うと、レスポンスは次のようになります:

{
  "data": {
    "success": true,
    "status": "exported",
    "taskId": "task_abc",
    "exportFileType": "JSON",
    "dataTotal": 100,
    "exportFileUrl": "https://...",
    "sampleData": [
      {
        "title": "Product A",
        "price": "$19.99"
      }
    ]
  }
}

status が exported の場合：

  1. ユーザーに exportFileUrl を表示します。

  2. sampleData が利用可能な場合は、プレビューとして表示します。

  3. 収集された行数を報告するには dataTotal を使用します。

エクスポートされたファイルを確認・分析するようユーザーから明示的に求められた場合を除き、exportFileUrl を自動的にダウンロードまたは解析しないでください。

既存のタスクを管理する

タスクがすでに存在する場合は、次のワークフローを使用します:

searchTasks
→ startOrStopTask
→ exportData

タスクを検索する

curl -sS \
  "https://openapi.octoparse.com/api/agentTools/searchTasks?page=1&size=10&keyword=amazon" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-external-user-id: YOUR_EXTERNAL_USER_ID"

レスポンスには、タスクID、タスク名、タスクのステータスが含まれます。

タスクを開始または停止する

タスクを開始するには：

curl -sS -X POST \
  "https://openapi.octoparse.com/api/agentTools/startOrStopTask" \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "taskId": "task_abc",
    "action": "start"
  }'

タスクを停止するには、action を次の値に変更します:

{
  "taskId": "task_abc",
  "action": "stop"
}

返される可能性のあるステータスには、次のものがあります:

  • start_requested

  • stop_requested

  • already_running

  • already_stopped

  • start_rejected

  • stop_rejected

  • invalid

開始リクエストが成功したら、exportData を使用して収集とエクスポートの進行状況を監視します。

よくある実装ミス

parameters をオブジェクトのまま送信する

誤り:

{
  "parameters": {
    "search_keyword": ["wireless earbuds"]
  }
}

正しい例:

{
  "parameters": "{\"search_keyword\":[\"wireless earbuds\"]}"
}

accepted を完了と見なす

accepted は、タスクの作成とクラウド開始リクエストが受理されたことを確認するだけです。ステータスが exported になるまで exportData を続けてください。

ソースオプションのkeyの代わりにラベルを渡す

ソースに基づくテンプレートフィールドでは、ユーザー向けのラベルではなく、sourceTree が返すオプションの key を使用します。

リトライガイダンスを無視する

APIが retryGuidance、suggestedNextCall、workflow を返した場合は、それらのフィールドを使って次の呼び出しと待機時間を判断します。

次のステップ

リクエストとレスポンスの完全なスキーマについては、以下を参照してください。

関連記事
こちらの回答で解決しましたか？