1. 概要

Octoparse アドバンスド API を使用する前に、少なくとも 1 つの実行可能なタスクが設定されてください。なお、プロフェッショナルプランのアカウントが必要です。(アカウントをお持ちでない方は、 こちらから登録してください。) Octoparse API に接続することで、抽出されたデータやタスク情報、さらにはタスクのコントロール (アドバンスド API) まで簡単に取得することができ、ご自身のアプリケーションとの連携による効率的なデータ抽出を実現できます。

1.1. ドキュメントのバージョン

現在のバージョン: V1.0

1.2. 連絡先

連絡先: Octoparse support team

Email: support@octoparse.jp

1.3. URL 標準

すべてのリクエストは以下のベース URL でエンコードされた URL であります。

https://advancedapi.octoparse.com/

例として、「オフセットによるデータを取得する」のリクエストは、次のようになります:GET http://advancedapi.octoparse.com/api/alldata/GetDataOfTaskByOffset?taskId={taskId}&offset={offset}&size={size}

注:このドキュメントの{xxxx}はプレースホルダを表しており、ユーザーはこれを実際の値に置き換える必要があります。例として、タスク ID が abc、オフセットが 1、サイズが 10 の場合、URL は https://advancedapi.octoparse.com/api/alldata/GetDataOfTaskByOffset?taskId=abc&offset=1&size=10 となります。

1.4. OAuth2.0 アクセストークンを取得する

Octoparse API にアクセスする前に、OAuth2.0 に基づく Access Token を取得する必要があります。

1.4.1. 新アクセストークンを取得する

新しいアクセストークンを取得するには、ユーザー名とパスワードが必要です。

リクエスト

POST https://advancedapi.octoparse.com/token

パラメーター

username={userName}&password={password}&grant_type=password

リクエストのContent-Type

application/x-www-form-urlencoded

レスポンス

Access Token

レスポンスのContent-Type

application/json, text/json

レスポンスの例
{
    "access_token": "ABCD1234",      //アクセストークン
    "token_type": "bearer",		     //トークンタイプ
    "expires_in": 86399,		     //アクセストークンの有効期限(秒)(有効期限内に同じトークンを繰り返し使用することをお勧めします) 
    "refresh_token": "refresh_token" //認可コード(アクセストークンを更新する際に使用します)
}

API メソッドを呼び出す際には、「Access_Token」が必要です。以下の形式で HTTP ヘッダに追加してください。

HeaderName: Authorization
Value: bearer {access_token}

注:「bearer」と「access_token」の間にはスペースがある。例として、Access Token が AA11BB22...CC33 の場合、ヘッダは「Authorization: bearer AA11BB22...CC33」とします。 Access Token には有効期限がありますので、有効期限内に同じトークンを繰り返し使用することをお勧めします。

1.4.2. アクセストークンを更新する

アクセストークンの有効期限が切れると、ユーザーは「refresh_token」でアクセストークンを更新することができます。「Refresh Token」は、ユーザー名とパスワードに通じて新トークンを取得の方がより安全です。

注: 各「refresh_token」は一度しか使用できません。現在のリクエストから返された新「Refresh Token」は、次のリクエストに使用されるべきです。

リクエスト

POST https://advancedapi.octoparse.com/token

パラメーター

refresh_token={refresh_token}&grant_type=refresh_token

リクエストのContent-Type

application/x-www-form-urlencoded

レスポンス

Access Token

注: レスポンス HTTP ステータスコードは「200」でなければなりません。そうでない場合は、HTTP ステータスコードを参照して問題を解決してください。

2. 手順

Octoparse は API の使用を 20 リクエスト / 秒に制限されています。ステータスコード「429」を受信した場合は、アクセス頻度を下げてください。

注: Octoparse は、API アクセス頻度を制限するためにリーキーバケットアルゴリズムを使用します。リクエストの最大数は、任意の 5 秒間の時間間隔内で、100 になります。

異常なHTTPステータスコード

レスポンス HTTP ステータスコードは「200」でなければなりません。そうでない場合は、HTTP ステータスコードを参照して問題を解決してください。

2.1. タスクグループ情報を取得する

2.1.1.すべてのタスクグループの情報をリストアップする

リクエスト

GET api/TaskGroup

レスポンス

タスクグループ情報とリクエストステータスを含む JSON 形式のテキスト。

レスポンスのContent-Type

application/json, text/json

レスポンスの例
{
  "data": [
    {
      "taskGroupId": 1,
      "taskGroupName": "Example Task Group 1"
    },
    {
      "taskGroupId": 2,
      "taskGroupName": "Example Task Group 2"
    }
  ],
  "error": "success",
  "error_Description": "Action Success"
}

2.2. タスクを管理する

2.2.1.グループ内のタスク一覧を表示する

リクエスト

GET api/Task?taskGroupId={taskGroupId}
パラメーター
パラメーター 説明 備考
taskGroupId

タスクグループ ID

リクエスト URL にパラメーターを定義してください。

レスポンス

タスク ID(taskId)、タスク名(taskName)、ユーザー ID とリクエストステータスを含む JSON 形式のテキスト。

レスポンスのContent-Type

application/json, text/json

レスポンスの例
{
  "data": [
    {
      "taskId": "337fd7d7-aded-4081-9104-2b551161ccc8",
      "taskName": "Example Task 1",
      "creationUserId": "5d1e4b3c-645c-44ab-ac0e-bfa9ad600ece"
    },
    {
      "taskId": "4adf489b-f883-43fa-b958-0cfde945ddb7",
      "taskName": "Example Task 2",
      "creationUserId": "5d1e4b3c-645c-44ab-ac0e-bfa9ad600ece"
    }
  ],
  "error": "success",
  "error_Description": "Action Success"
}

2.2.2.タスクステータスを取得する

タスクのステータスを一括取得ことができます。

リクエスト

POST api/task/GetTaskStatusByIdList
パラメーター
パラメーター 説明 備考
taskIdList

タスク ID リストを含む JSON 形式のテキスト。

request body にパラメーターを定義してください。

レスポンスのContent-Type

application/json, text/json

レスポンスの例
{
  "taskIdList": [
    "337fd7d7-aded-4081-9104-2b551161ccc8",
    "4adf489b-f883-43fa-b958-0cfde945ddb7"
  ]
}

レスポンス

タスクステータスコード: 0 = 実行中, 1 = 停止中, 2 = 実行完了, 3 = 実行待ち, 5 = 準備完了

レスポンスのContent-Type

application/json, text/json

レスポンスの例
{
  "data": [
    {
      "taskId": "337fd7d7-aded-4081-9104-2b551161ccc8",
      "taskName": "Example Task 1",
      "status": 1
    },
    {
      "taskId": "4adf489b-f883-43fa-b958-0cfde945ddb7",
      "taskName": "Example Task 2",
      "status": 2
    }
  ],
  "error": "success",
  "error_Description": "Action Success"
}

2.2.3.タスクパラメーターを取得する

これは特定のタスクのパラメーターを取得することができます。例として、「Webページを開く」アクションからのURL、「テキストを入力」アクションからのテキスト値、「ループアイテム」アクションからのテキストリスト / URL リストなどです。

リクエスト

POST api/task/GetTaskRulePropertyByName?taskId={taskId}&name={name}
パラメーター
パラメーター 説明 備考
taskId

タスク ID

リクエスト URL にパラメーターを定義してください。

name

設定したパラメーター名 (navigateAction1.Url,loopAction1.UrlList,loopAction1.TextList など)

リクエスト URL にパラメーターを定義してください。

レスポンス

タスクのパラメーターの値(または値の配列)とリクエストステータス。

レスポンスのContent-Type

application/json, text/json

レスポンスの例
{
  "data": [
    "http://www.octoparse.jp/",
    "http://www.skieer.com/"
  ],
  "error": "success",
  "error_Description": "Action Success"
}

2.2.4.タスクパラメーターを更新する

このメソッドを使用して、タスクパラメーターを更新します(現在は「Webページを開く」アクションからのURL、「テキストを入力」アクションからのテキスト値、「ループアイテム」アクションからのテキストリスト / URL リストの更新にのみ使用可能です)。

注:URL とテキスト値の場合は、文字列型を直接使用してください: "value":"navigateAction1.Url" 。N 個のテキストリスト / URL リストの値を更新する場合は、"value":['text1', 'text2', 'text3', 'textN'] を使用してください。

リクエスト

POST api/task/UpdateTaskRule
パラメーター
パラメーター 説明 備考
ruleParaInfo

タスクパラメーター (navigateAction1.Url,loopAction1.UrlList,loopAction1.TextList)

request body にパラメーターを定義してください。

リクエストのContent-Type

application/json, text/json

リクエストの例
{
  "taskId": "337fd7d7-aded-4081-9104-2b551161ccc8",
  "name": "loopAction2.TextList",
  "value": [
    "Octparse",
    "Skieer Infomation"
  ]
}

レスポンス

タスクパラメーターが正常に更新されたかどうかを表示されます。

レスポンスのContent-Type

application/json, text/json

レスポンスの例
{
  "error": "success",
  "error_Description": "Action Success"
}

2.2.5.タスクループリストに URL / テキストを追加する

このメソッドを使用して、既存のループに新しい URL / テキストを追加します。

注:N 個のテキストリスト / URL リストの値 (value) を更新する場合は、"value":['text1', 'text2', 'text3', 'textN'] を使用してください。

リクエスト

POST api/task/AddUrlOrTextToTask
パラメーター
パラメーター 説明 備考
ruleParaInfo

既存のループのパラメーター

request body にパラメーターを定義してください。

リクエストのContent-Type

application/json, text/json

リクエストの例
{
  "taskId": "4adf489b-f883-43fa-b958-0cfde945ddb7",
  "name": "loopAction1.UrlList",
  "value": [
    "http://www.octoparse.jp/",
    "http://www.skieer.com/"
  ]
}

レスポンス

新パラメーター値が正常に追加されたかどうかを表示されます。

レスポンスのContent-Type

application/json, text/json

レスポンスの例
{
  "error": "success",
  "error_Description": "Action Success"
}

2.2.6.タスクの実行を開始する

リクエスト

POST api/task/StartTask?taskId={taskId}
パラメーター
パラメーター 説明 備考
taskId

タスク ID

リクエスト URL にパラメーターを定義してください。

レスポンス

ステータスコード (レスポンス内容の「data」パラメーター):1 = 起動成功, 2 = タスク実行中, 5 = タスク設定エラー, 6 = アクセス拒否, 100 = その他のエラー

レスポンスのContent-Type

application/json, text/json

レスポンスの例
{
  "data": 1,
  "error": "success",
  "error_Description": "Action Success"
}

2.2.7.タスクの実行を停止する

リクエスト

POST api/task/StopTask?taskId={taskId}
パラメーター
パラメーター 説明 備考
taskId

タスク ID

リクエスト URL にパラメーターを定義してください。

レスポンス

タスクが正常に停止するかどうかを表示されます。

レスポンスのContent-Type

application/json, text/json

レスポンスの例
{
  "error": "success",
  "error_Description": "Action Success"
}

2.2.8.データをクリアする

リクエスト

POST api/task/RemoveDataByTaskId?taskId={taskId}
パラメーター
パラメーター 説明 備考
taskId

タスク ID

リクエスト URL にパラメーターを定義してください。

レスポンス

データが正常にクリアされたかどうかを表示されます。

レスポンスのContent-Type

application/json, text/json

レスポンスの例
{
  "error": "success",
  "error_Description": "Action Success"
}

2.3. データを抽出する

2.3.1.データをエクスポートする

エクスポートされていないデータをエクスポートします。データは、エクスポート後に(status=exported ではなく)status=exporting とタグ付けされます。この方法では、同じデータセットをこの方法で複数回エクスポートすることができます。データが正常に取得されていることを確認した後、データのステータスを「exported」に更新したい場合は、2.3.2 の手順でステータスの更新を行ってください。

注:エクスポートが中断された場合(ネットワークの接続中断など)、この方法を使用して再度データをエクスポートしてください。

リクエスト

GET api/notexportdata/gettop?taskId={taskId}&size={size}
パラメーター
パラメーター 説明 備考
taskId

タスク ID

リクエスト URL にパラメーターを定義してください。

size

データ行数(1 ~ 1000行)

リクエスト URL にパラメーターを定義してください。

レスポンス

データとリクエスト状態

レスポンスのContent-Type

application/json, text/json

レスポンスの例
{
  "data": {
    "total": 100000,
    "currentTotal": 4,
    "dataList": [
      {
        "State": "Texas",
        "City": "Plano"
      },
      {
        "State": "Texas",
        "City": "Houston"
      },
      {
        "State": "Texas",
        "City": "Austin"
      },
      {
        "State": "Texas",
        "City": "Arlington"
      }
    ]
  },
  "error": "success",
  "error_Description": "Action Success"
}

2.3.2.データの状態を更新する

これにより、データの状態が「exporting(抽出中)」から「exported(抽出完了)」に更新されます。

注:API「タスクデータのエクスポート」(api/notexportdata/gettop)からエクスポートされたデータが正常に取得されていることを確認した上で、この方法を使用してください。

リクエスト

POST api/notexportdata/update?taskId={taskId}
パラメーター
パラメーター 説明 備考
taskId

タスク Id

リクエスト URL にパラメーターを定義してください。

レスポンス

タスクの状態が正常に変更されたかどうかを表示されます。

レスポンスのContent-Type

application/json, text/json

レスポンスの例
{
  "error": "success",
  "error_Description": "Action Success"
}

2.4. データを取得する

2.4.1.オフセットによるデータを取得する

このメソッドには、リクエストにはオフセット、サイズ、タスク ID などのパラメーターが必要です。 オフセットのデフォルト値は 0 (offset=0)、サイズは size∈[1,1000] とします。返されたオフセット(offset > 0)は、次のリクエストに使用されます。 例として、タスクは 1000 行のデータがある場合、パラメーター:offset = 0, size = 100 を使用すると、最初の 100 行のデータとオフセット x(x は必ずしも 100 とは限らない)が返されます。 2 回目のリクエストを行う場合、最初のリクエストから返されたオフセット、offset = X, size = 100 を使用して、 次の 100 行のデータ(101 行目から 200 行目まで)を取得し、次のオフセット offset=x1 も返されました。x1 を次の開始オフセットとして使用する、というようにしています。

注:この方法はデータを取得するためだけに使用されますが、データの状態には影響しません。(エクスポートされていないデータはエクスポートされていない状態のままになります)

リクエスト

GET api/alldata/GetDataOfTaskByOffset?taskId={taskId}&offset={offset}&size={size}
パラメーター
パラメーター 説明 備考
taskId

タスク ID

リクエスト URL にパラメーターを定義してください。

offset

オフセットが 0 以下の場合は、最初の行からデータが返されます。

リクエスト URL にパラメーターを定義してください。

size

取得データ量(1~1000の範囲)

リクエスト URL にパラメーターを定義してください。

レスポンス

データとリクエスト状態

レスポンスのContent-Type

application/json, text/json

レスポンスの例
{
  "data": {
    "offset": 4,
    "total": 100000,
    "restTotal": 99996,
    "dataList": [
      {
        "State": "Texas",
        "City": "Plano"
      },
      {
        "State": "Texas",
        "City": "Houston"
      },
      {
        "State": "Texas",
        "City": "Austin"
      },
      {
        "State": "Texas",
        "City": "Arlington"
      }
    ]
  },
  "error": "success",
  "error_Description": "Action Success"
}

3. 参照

3.1. HTTP ステータスコード

エラーコードが返ってきた場合は、以下のステータスコード表を参照して問題を解決してください。

HTTP ステータスコード Inner ステータスコード 説明

200

ok

操作は成功しました。

400

invalid_grant

ユーザー名またはパスワードが間違っています。

400

unsupported_grant_type

POST形式が正しくありません。正しいフォーマットは、username={username}&password={password}&grant_type=passwordです。

401

unauthorized

アクセストークンの有効期限が切れているか、不正のため無効です。新アクセストークンを取得してください。

403

user_not_allowed

許可が拒否されました。データ API をご利用になる場合はスタンダードプランへ、アドバンスド API をご利用になる場合はプロフェッショナルプランへアップグレードしてください。

404

not_found

HTTP リクエストが認識されません。正しい URL でリクエストしてください。

405

method_not_allowed

HTTP メソッドはサポートされていません。インターフェースでサポートされている方法を使用してください。

429

quota_exceeded

リクエスト回数が制限値を超えています。アクセス頻度を 20 回/秒以下にしてください。

503

service_unavailable

サービスは一時的に利用できません。あとでもう一度お試しください。

3.2. サンプルコード

サンプルコード:

C#: ApiSamples/Code/CSharp/

Python: ApiSamples/Code/Python/

(他の言語も近日中にリリース予定です。)

3.3. 利用規約

利用規約