logo
Documentation Powered by ReDoc

BizteX cobit API ドキュメント (0.1.0)

Download OpenAPI specification:Download

E-mail: cobit-support@biztex.co.jp Terms of Service

概要

このドキュメントはBizteX cobitのAPIドキュメントです。現在このAPIはベータ版としてリリースしています。

ベースURLは https://api.cobit.biztex.co.jp/v1 です。成功時の結果は特に明記のない場合 JSON (application/json) で返ります。

APIを実行するにはAPIトークンを以下のように Authorization ヘッダに指定してください:

Authorization: Bearer API_TOKEN

APIトークンはcobitに管理者でログインして、「環境設定」にある「APIトークン」から生成できます。生成方法の詳細は こちら を参照してください。

呼び出し回数制限

APIの呼び出し可能回数はひとつの組織につき5分あたり300回までです。制限回数をこえると 429 Too Many Requests 応答を返します。 残りの呼び出し可能な回数やリセットされる時間はレスポンスヘッダから参照できます。

時間あたりのAPIの呼び出し回数や制限の単位は今後変更される可能性があります。

また、呼び出し回数が制限値を大きくこえるような場合はDoS攻撃と判断され、この仕様の範囲外でアクセスが制限される可能性があります。

通常時のレスポンスヘッダの例

利用回数が制限内に収まっている場合は以下のレスポンスヘッダが返ります:

HTTP/1.1 200 OK
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 173
X-RateLimit-Reset: 1535539500

それぞれのヘッダは以下を表しています:

  • X-RateLimit-Limit: 単位時間あたりの最大呼び出し可能回数。
  • X-RateLimit-Remaining: 残りの呼び出し可能回数。
  • X-RateLimit-Reset: 呼び出し可能回数がリセットされる時間（Unix time）。

制限をこえた場合のレスポンスヘッダの例

利用回数が制限回数をこえると以下のレスポンスヘッダが返ります:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1535539500
Retry-After: 78

それぞれのヘッダは以下を表しています:

  • X-RateLimit-Reset: 次に呼び出し可能になる時間（Unix time）。
  • Retry-After: 次に呼び出し可能になるまでの秒数。

Webhook

Webhookを利用するとロボットの実行完了イベントなどを登録したWebhook URLに通知できます。 例えばロボットの実行完了を待つ場合、ポーリングをせずにWebhookを利用するとAPIの呼び出し回数の制限を受けることなく完了の通知を受けとれます。

Webhookは「環境設定」にある「Webhook」で登録できます。 通知されるイベントは「Webhookイベント」を参照してください。

イベント通知は登録したWebhookのURLにPOSTリクエストを送信することによっておこなわれます。イベントを受けとったWebhookは 200 OK 応答を返さなければいけません。

以下のいずれかの場合イベント通知は失敗したとみなされます:

  • 200 OK 以外の応答が返ってきた。
  • 10秒以内に応答が返ってこなかった。
  • 接続に失敗した。

イベント通知に失敗した場合はリトライ間隔を増やしながら10回までリクエストを再送します。

送信されるリクエスト

以下のようなリクエストが送信されます:

POST /webhook HTTP/1.0
Content-Type: application/json; charset=utf-8
X-Cobit-Webhook-Request-Id: d4a6bf2c-1282-4de3-9b13-1ff4caa4e434
X-Cobit-Webhook-Signature: 115556a4de2e7fd7eb6e58894b94b50c8a821781c22d190112ad9c72e7978bba

{
  "event_type":"robo_execution_completed",
  "event_time":"2018-09-09T15:07:45.000Z",
  "event": ...
}

それぞれのヘッダは以下を表しています:

  • X-Cobit-Webhook-Request-Id: 個々のWebhook送信を識別するためのリクエストID。再送された場合リクエストIDは違う値になります。
  • X-Cobit-Webhook-Signature: 「リクエストの署名検証」で使うための署名。「署名鍵」が未設定の場合は存在しません。

リクエストボディはJSON (application/json) で、それぞれの属性は以下を表しています。

  • event_type: イベントの種類。
  • event_time: イベントが発生した日時 (ISO 8601)。
  • event: 発生したイベントの内容。

event の中身は event_type の値によって変わります。event_type と event については「Webhookイベント」のそれぞれのイベントを参照してください。

リクエストの署名検証

Webhook登録時に「署名鍵」が設定されていた場合、送信元がcobitであることを保証するためにリクエストボディの署名が X-Cobit-Webhook-Signature ヘッダで付与されてリクエストが送信されます。 cobit以外からの不正なリクエストを防ぐために、なるべく署名を検証することをおすすめします。

署名検証の手順は以下の通りです:

  1. Webhookに通知されたリクエストボディを文字コード変換等をしないそのままの文字列 (バイト列) で取得します。
  2. リクエストボディと署名鍵を使って、HMAC-SHA256アルゴリズムによりダイジェスト値を取得します。
  3. ダイジェスト値を小文字のHex表現にした文字列が、X-Cobit-Webhook-Signature ヘッダで付与された署名と一致することを確認します。

ロボット

ロボットの実行

指定されたロボットを実行します。実行が受理されるとロボット実行情報を返します。

以下を指定することでロボットの設定を実行時に上書きできます:

  • settings_overrides.variables: 変数。ロボットの設定の「開始時のテキスト」で設定したものを指定してください。
path Parameters
id
required
integer

ロボットID。

Request Body schema: application/json
object (RoboSettingsOverrides)

ロボット設定の上書き情報。

Responses

Request samples

Content type
application/json
{
  • "settings_overrides": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "status": "WAITING_TO_START",
  • "created_at": "2017-07-20 13:00:00.000000000 Z",
  • "started_at": "2017-07-20 13:00:00.000000000 Z",
  • "completed_at": "2017-07-20 13:00:00.000000000 Z",
  • "robo": {
    }
}

ロボット実行情報

ロボット実行情報の取得

指定されたロボット実行情報を取得します。結果には実行結果の変数と実行時に上書きした設定も含まれます。

path Parameters
id
required
integer

ロボット実行情報ID。

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "status": "WAITING_TO_START",
  • "created_at": "2017-07-20 13:00:00.000000000 Z",
  • "started_at": "2017-07-20 13:00:00.000000000 Z",
  • "completed_at": "2017-07-20 13:00:00.000000000 Z",
  • "robo": {
    },
  • "output_resources": [
    ],
  • "downloaded_files": [
    ],
  • "screenshots": [
    ],
  • "result_variable_map": {
    },
  • "settings_overrides": {
    }
}

出力ファイル情報の取得

指定されたロボット実行結果に含まれる出力ファイル情報を取得します。

path Parameters
robo_execution_id
required
integer

ロボット実行情報ID。

id
required
integer

出力ファイルID。

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "filename": "example.xlsx",
  • "filetype": "EXCEL",
  • "google_spreadsheet_id": null
}

出力ファイルのダウンロード

指定されたロボット実行結果に含まれる出力ファイルのダウンロードリンクへリダイレクトする 302 Found 応答を返します。 このダウンロードリンクは短期間 (数分) のみ有効で、Authorization ヘッダーを必要としません。

このAPIは指定された出力ファイル情報の filetype が CSV, EXCEL の場合のみ利用できます。

path Parameters
robo_execution_id
required
integer

ロボット実行情報ID。

id
required
integer

出力ファイルID。

Responses

Response samples

Content type
application/json
{}

ダウンロードファイル情報の取得

指定されたロボット実行結果に含まれるダウンロードファイル情報を取得します。

path Parameters
robo_execution_id
required
integer

ロボット実行情報ID。

id
required
integer

ダウンロードファイルID。

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "filename": "example.png"
}

ダウンロードファイルのダウンロード

指定されたロボット実行結果に含まれるダウンロードファイルのダウンロードリンクへリダイレクトする 302 Found 応答を返します。 このダウンロードリンクは短期間 (数分) のみ有効で、Authorization ヘッダーを必要としません。

path Parameters
robo_execution_id
required
integer

ロボット実行情報ID。

id
required
integer

ダウンロードファイルID。

Responses

Response samples

Content type
application/json
{}

スクリーンショット情報の取得

指定されたロボット実行結果に含まれるスクリーンショット情報を取得します。

path Parameters
robo_execution_id
required
integer

ロボット実行情報ID。

id
required
integer

スクリーンショットID。

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "filename": "example.png"
}

スクリーンショットのダウンロード

指定されたロボット実行結果に含まれるスクリーンショットのダウンロードリンクへリダイレクトする 302 Found 応答を返します。 このダウンロードリンクは短期間 (数分) のみ有効で、Authorization ヘッダーを必要としません。

path Parameters
robo_execution_id
required
integer

ロボット実行情報ID。

id
required
integer

スクリーンショットID。

Responses

Response samples

Content type
application/json
{}

Webhookイベント

Webhookに送信されるイベントの定義です。

ここで定義されているものはcobit APIに送信するものではないことに注意してください。

ロボット実行完了

ロボットの実行が完了したときに送信されるイベントです。

Request Body schema: application/json
event_type
required
string
Value: "robo_execution_completed"

イベントの種類。

event_time
required
string <date-time>

イベントが発生した日時。

required
object

イベント情報。

Responses

Request samples

Content type
application/json
{
  • "event_type": "robo_execution_completed",
  • "event_time": "2019-08-24T14:15:22Z",
  • "event": {
    }
}

ワークファイル

ロボットがファイルを操作するための、独自のファイル表現です。