クラウドBOT RESTful API リファレンス (4.3)

Download OpenAPI specification:Download

クラウドBOT RESTful APIのリファレンスです。
APIを利用するには、公開IDの設定とアクセストークンの発行が必要です。
クラウドBOTダッシュボード > 開発者向けページから設定してください。
https://console.c-bot.pro/development

リクエストペイロードおよびレスポンスにマルチバイト文字が含まれる場合はUTF-8として扱います。
リクエストペイロード容量が4MBを超えるリクエストは拒否されます。

契約一覧

API機能が有効な契約の一覧を参照します。
使用するアクセストークンに「参照」権限が付与されている必要があります。

query Parameters

properties

string

Example: properties=plan,owner

追加で取得するプロパティ名集合
以下のプロパティ名を,(カンマ)区切りで列記する
plan: プラン名
owner: 契約オーナー
timezone: タイムゾーン
location: ロケーション
name: 契約名
organization: 組織名(個人名)
postcode: 郵便番号
address: 住所
phone: 電話番号
department: 部署名
username: 担当者名
(public_id, public_pathプロパティは必ず取得します)

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string アクセストークントークン・シークレット認証の場合に必要です。
secret-key	string シークレットキートークン・シークレット認証の場合に必要です。
authorization	string Value: "Bearer {トークン}" OAuthアクセストークン OAuth認証の場合に必要です。値はBearerスキームで記述します。

Responses

Response samples

Content type

application/json

{"code": 200,
"contracts": [{"public_id": "example1",
"public_path": "/example1/",
"plan": "フリー",
"owner": "example1@example.com",
"timezone": "Asia/Tokyo",
"location": "日本",
"name": null,
"organization": null,
"postcode": null,
"address": null,
"phone": null,
"department": null,
"username": null
},
{"public_id": "example2",
"public_path": "/example2/",
"plan": "シングルオフィス",
"owner": "example2@example.com",
"timezone": "Asia/Tokyo",
"location": "日本",
"name": "本社",
"organization": "株式会社クラウドBOT",
"postcode": "000-0000",
"address": "東京都墨田区押上1丁目1−2",
"phone": "000-0000-0000",
"department": "総務部",
"username": "山田 太郎"
}
]
}

BOT一覧

API公開されているBOTの一覧を参照します。
使用するアクセストークンに「参照」権限が付与されている必要があります。

path Parameters

public_id

required

string

APIの公開ID

query Parameters

properties

string

Example: properties=icon,created,last_modified,creator

追加で取得するプロパティ名集合
以下のプロパティ名を,(カンマ)区切りで列記する
icon: アイコン画像
created: 作成日
last_modified: 更新日
creator: 作成者
(id, name, descriptionプロパティは必ず取得します)

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string アクセストークントークン・シークレット認証の場合に必要です。
secret-key	string シークレットキートークン・シークレット認証の場合に必要です。
authorization	string Value: "Bearer {トークン}" OAuthアクセストークン OAuth認証の場合に必要です。値はBearerスキームで記述します。

Responses

Response samples

Content type

application/json

{"code": 200,
"bots": [{"id": "get_items",
"name": "商品取得BOT",
"description": "商品リストを取得するBOTです。",
"icon": "data:image/png;base64,0000000000",
"created": "2020-04-06T14:32:23Z",
"last_modified": "2020-04-07T15:10:02Z",
"creator": "example@example.com"
},
{"id": "add_item",
"name": "商品追加BOT",
"description": "商品を登録するBOTです。",
"icon": "data:image/png;base64,0000000000",
"created": "2020-04-07T06:29:41Z",
"last_modified": "2020-04-07T09:41:44Z",
"creator": "example@example.com"
}
]
}

BOT詳細

BOTの詳細を参照します。
使用するアクセストークンに「参照」権限が付与されている必要があります。

path Parameters

public_id required	string APIの公開ID
bot_id required	string BOT ID

query Parameters

properties

string

Example: properties=icon,created,last_modified,creator,input,output

追加で取得するプロパティ名集合
以下のプロパティ名を,(カンマ)区切りで列記する
icon: アイコン画像
created: 作成日
last_modified: 更新日
creator: 作成者
input: 入力値定義
outout: 出力値定義
(id, name, descriptionプロパティは必ず取得します)

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string アクセストークントークン・シークレット認証の場合に必要です。
secret-key	string シークレットキートークン・シークレット認証の場合に必要です。
authorization	string Value: "Bearer {トークン}" OAuthアクセストークン OAuth認証の場合に必要です。値はBearerスキームで記述します。

Responses

Response samples

Content type

application/json

{"code": 200,
"id": "add_item",
"name": "商品追加BOT",
"description": "商品を登録するBOTです。",
"icon": "data:image/png;base64,0000000000",
"created": "2020-04-07T06:29:41Z",
"last_modified": "2020-04-07T09:41:44Z",
"creator": "example@example.com",
"input": {"data": {"ログインID": {"type": "string"
},
"パスワード": {"type": "string"
},
"商品": {"type": "group",
"data": {"商品名": {"type": "string"
},
"価格": {"type": "string"
},
"画像": {"type": "files"
},
"タグ": {"type": "string[]"
}
}
}
}
},
"output": {"data": {"商品": {"type": "group",
"data": {"商品ID": {"type": "string"
}
}
}
}
}
}

BOT実行

任意のBOTを実行します。
使用するアクセストークンに「実行」権限が付与されている必要があります。

path Parameters

public_id required	string APIの公開ID
bot_id required	string BOT ID

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string アクセストークントークン・シークレット認証の場合に必要です。
secret-key	string シークレットキートークン・シークレット認証の場合に必要です。
authorization	string Value: "Bearer {トークン}" OAuthアクセストークン OAuth認証の場合に必要です。値はBearerスキームで記述します。

Request Body schema: application/json

timeout	integer [ 0 .. 25000 ] BOT実行の終了を待機するミリ秒数(未指定の場合は0) リクエストによってBOTが実行を開始した後、このミリ秒数を経過すると実行が終了していなくてもレスポンスを返します(レスポンスコード202)
callback_endpoint	string <uri> BOT実行完了時に、このエンドポイント宛に実行結果がPOSTされます。(未指定の場合はコールバック無し) エンドポイントは、必ずhttps://から始まる必要があります。エンドポイントの実装要件は「クラウドBOT RESTful API Callback Endpoint 実装要件」を参照してください。
callback_tries	integer [ 0 .. 5 ] コールバックPOSTの試行回数です。callback_endpointが200系以外のステータスコードをレスポンスした場合またはレスポンスヘッダに正しいアクセストークンが設定されていなかった場合に、指定回数まで試行します。0を指定した場合はコールバックPOSTは行われません。
	object (datalist_input) 入力値を表すオブジェクトです。(未指定の場合はBOTのデフォルト値が使用されます) 入力値を指定したいデータ名,グループ名を任意数設定します。

Responses

Request samples

Payload

Content type

application/json

Example

example-1

{"timeout": 20000,
"input": {"検索ワード": "クラウドBOT"
}
}

Response samples

Content type

application/json

{"code": 201,
"job_id": "00000000-0000-0000-0000-000000000000",
"bot_id": "get_items",
"bot_name": "商品取得BOT",
"status": 0,
"start_time": "2019-12-02T05:30:13Z",
"elapsed_time": 6,
"output": {"件数": "2",
"商品": [{"商品名": "チーズケーキ",
"価格": "500",
"画像": {"type": "files",
"files": [{"ref": "jobs/00000000-0000-0000-0000-000000000000/files/00000000-0000-0000-0000-000000000000",
"meta": {"name": "0001.jpg",
"size": 603956,
"timestamp": 1513657350000
}
}
]
},
"タグ": ["ケーキ",
"チーズ"
]
},
{"商品名": "ガトーショコラ",
"価格": "600",
"画像": {"type": "files",
"files": [{"ref": "jobs/00000000-0000-0000-0000-000000000000/files/00000000-0000-0000-0000-000000000001",
"meta": {"name": "0002.jpg",
"size": 694475,
"timestamp": 1651024763990
}
}
]
},
"タグ": ["ケーキ",
"チョコレート"
]
}
]
}
}

BOTジョブ一覧

BOTのジョブ一覧を参照します。
使用するアクセストークンに「参照」権限が付与されている必要があります。

レスポンスサイズが4MBを超える場合は400エラーをレスポンスします。

path Parameters

public_id required	string APIの公開ID
bot_id required	string BOT ID

query Parameters

properties	string Example: properties=output 追加で取得するプロパティ名集合以下のプロパティ名を,(カンマ)区切りで列記する output: 出力値オブジェクト (job_id,bot_id,bot_name,status,start_time,elapsed_timeプロパティは必ず取得します)
limit	integer >= 0 Example: limit=10 アイテムの取得件数上限
datetime_from	string <date-time> Example: datetime_from=2019-01-01T00:00:00Z 指定した日時(ISO 8601)以降に開始したジョブに限定する
datetime_to	string <date-time> Example: datetime_to=2019-01-01T00:00:00Z 指定した日時(ISO 8601)以前に開始したジョブに限定する
id_from	string Example: id_from=00000000-0000-0000-0000-000000000000 指定したジョブID以降に開始したジョブに限定する
id_to	string Example: id_to=00000000-0000-0000-0000-000000000000 指定したジョブID以前に開始したジョブに限定する
statuses	integer Example: statuses=1 指定したステータスのジョブに限定する。ステータス(0:正常終了 1:エラー 2:実行中) ,(カンマ)区切りで複数指定可能(statuses=0,1)
sort_order	string Default: "desc" Enum: "asc" "desc" Example: sort_order=asc ソート順

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string アクセストークントークン・シークレット認証の場合に必要です。
secret-key	string シークレットキートークン・シークレット認証の場合に必要です。
authorization	string Value: "Bearer {トークン}" OAuthアクセストークン OAuth認証の場合に必要です。値はBearerスキームで記述します。

Responses

Response samples

Content type

application/json

{"code": 200,
"jobs": [{"job_id": "00000000-0000-0000-0000-000000000001",
"bot_id": "get_items",
"bot_name": "商品取得BOT",
"status": 2,
"start_time": "2019-12-02T06:10:56Z",
"cast_url": "https://console.c-bot.pro/cast_url_sample"
},
{"job_id": "00000000-0000-0000-0000-000000000000",
"bot_id": "get_items",
"bot_name": "商品取得BOT",
"status": 0,
"start_time": "2019-12-02T06:04:21Z",
"elapsed_time": 6,
"output": {"件数": "2",
"商品": [{"商品名": "チーズケーキ",
"価格": "500",
"画像": {"type": "files",
"files": [{"ref": "jobs/00000000-0000-0000-0000-000000000000/files/00000000-0000-0000-0000-000000000000",
"meta": {"name": "0001.jpg",
"size": 603956,
"timestamp": 1513657350000
}
}
]
},
"タグ": ["ケーキ",
"チーズ"
]
},
{"商品名": "ガトーショコラ",
"価格": "600",
"画像": {"type": "files",
"files": [{"ref": "jobs/00000000-0000-0000-0000-000000000000/files/00000000-0000-0000-0000-000000000001",
"meta": {"name": "0002.jpg",
"size": 694475,
"timestamp": 1651024763990
}
}
]
},
"タグ": ["ケーキ",
"チョコレート"
]
}
]
}
}
]
}

ジョブ参照

任意のジョブの結果を参照します。
使用するアクセストークンに「参照」権限が付与されている必要があります。

path Parameters

public_id required	string APIの公開ID
job_id required	string ジョブID

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string アクセストークントークン・シークレット認証の場合に必要です。
secret-key	string シークレットキートークン・シークレット認証の場合に必要です。
authorization	string Value: "Bearer {トークン}" OAuthアクセストークン OAuth認証の場合に必要です。値はBearerスキームで記述します。

Responses

Response samples

Content type

application/json

Example

example-1

{"code": 200,
"job_id": "00000000-0000-0000-0000-000000000000",
"bot_id": "get_items",
"bot_name": "商品取得BOT",
"status": 0,
"start_time": "2019-12-02T06:04:21Z",
"elapsed_time": 6,
"output": {"件数": "2",
"商品": [{"商品名": "チーズケーキ",
"価格": "500",
"画像": {"type": "files",
"files": [{"ref": "jobs/00000000-0000-0000-0000-000000000000/files/00000000-0000-0000-0000-000000000000",
"meta": {"name": "0001.jpg",
"size": 603956,
"timestamp": 1513657350000
}
}
]
},
"タグ": ["ケーキ",
"チーズ"
]
},
{"商品名": "ガトーショコラ",
"価格": "600",
"画像": {"type": "files",
"files": [{"ref": "jobs/00000000-0000-0000-0000-000000000000/files/00000000-0000-0000-0000-000000000001",
"meta": {"name": "0002.jpg",
"size": 694475,
"timestamp": 1651024763990
}
}
]
},
"タグ": ["ケーキ",
"チョコレート"
]
}
]
}
}

ジョブ中断

任意の実行中ジョブを中断します。
使用するアクセストークンに「中断」権限が付与されている必要があります。

path Parameters

public_id required	string APIの公開ID
job_id required	string ジョブID

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string アクセストークントークン・シークレット認証の場合に必要です。
secret-key	string シークレットキートークン・シークレット認証の場合に必要です。
authorization	string Value: "Bearer {トークン}" OAuthアクセストークン OAuth認証の場合に必要です。値はBearerスキームで記述します。

Responses

Response samples

Content type

application/json

{"code": 200,
"job_id": "00000000-0000-0000-0000-000000000000",
"bot_id": "get_items",
"bot_name": "商品取得BOT",
"status": 1,
"start_time": "2019-12-02T06:15:33Z",
"elapsed_time": 3
}

BOT購読一覧 (REST Hooks)

BOT購読の一覧を参照します。
使用するアクセストークンに「参照」権限が付与されている必要があります。

path Parameters

public_id required	string APIの公開ID
bot_id required	string BOT ID

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string アクセストークントークン・シークレット認証の場合に必要です。
secret-key	string シークレットキートークン・シークレット認証の場合に必要です。
authorization	string Value: "Bearer {トークン}" OAuthアクセストークン OAuth認証の場合に必要です。値はBearerスキームで記述します。

Responses

Response samples

Content type

application/json

{"code": 200,
"subscriptions": [{"subscribe_id": 1000000,
"language": "ja",
"event": "onended",
"callback_type": "webhook",
"callback_endpoint": "https://example.com/callback_endpoint",
"disabled": false,
"unsubscribe_endpoint": "https://api.c-bot.pro/example1/bots/get_items/subscriptions/1000000"
},
{"subscribe_id": 1000001,
"language": "en",
"event": "onsucceeded",
"callback_type": "mailhook",
"callback_emails": {"member_emails": ["sample1@example.com",
"sample2@example.com"
],
"guest_emails": ["sample3@example.com",
"sample4@example.com"
]
},
"disabled": false,
"unsubscribe_endpoint": "https://api.c-bot.pro/example1/bots/get_items/subscriptions/1000001"
}
]
}

BOT購読 (REST Hooks)

BOTの購読を開始します。
購読を開始すると、BOT操作に連動してWebhookやMailhookを受けることができるようになります。
使用するアクセストークンに「参照」権限が付与されている必要があります。

path Parameters

public_id required	string APIの公開ID
bot_id required	string BOT ID

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string アクセストークントークン・シークレット認証の場合に必要です。
secret-key	string シークレットキートークン・シークレット認証の場合に必要です。
authorization	string Value: "Bearer {トークン}" OAuthアクセストークン OAuth認証の場合に必要です。値はBearerスキームで記述します。

Request Body schema: application/json

event required	string Enum: "onended" "onsucceeded" "onfailed" "oncannotexecute" 購読するイベント onended: BOT実行終了 onsucceeded: BOT実行成功 onfailed: BOT実行失敗 oncannotexecute: BOT起動失敗
callback_type	string Default: "webhook" Enum: "webhook" "mailhook" コールバックタイプ webhook: イベントが発生すると、callback_endpoint宛にBOT実行結果がPOSTされます。 mailhook: イベントが発生すると、callback_emails宛にBOT実行結果が通知されます。
callback_endpoint	string <uri> callback_typeが「webhook」の場合に指定します。エンドポイントは、必ずhttps://から始まる必要があります。エンドポイントの実装要件は「クラウドBOT RESTful API Callback Endpoint 実装要件」を参照してください。
	object callback_typeが「mailhook」の場合に指定します。検証済みメールアドレスのみ指定できます。

Responses

Request samples

Payload

Content type

application/json

Example

example-1

{"event": "onended",
"callback_type": "webhook",
"callback_endpoint": "https://example.com/callback_endpoint"
}

Response samples

Content type

application/json

{"code": 200,
"subscribe_id": 1000000,
"unsubscribe_endpoint": "https://api.c-bot.pro/example1/bots/get_items/subscriptions/1000000"
}

BOT購読解除 (REST Hooks)

BOTの購読を解除します
使用するアクセストークンに「参照」権限が付与されている必要があります。

path Parameters

public_id required	string APIの公開ID
bot_id required	string BOT ID
subscribe_id required	string 購読ID

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string アクセストークントークン・シークレット認証の場合に必要です。
secret-key	string シークレットキートークン・シークレット認証の場合に必要です。
authorization	string Value: "Bearer {トークン}" OAuthアクセストークン OAuth認証の場合に必要です。値はBearerスキームで記述します。

Responses

Response samples

Content type

application/json

{"code": 200
}

ファイルダウンロード

ファイルをダウンロードします。
WSトークンが必要です。

path Parameters

key

required

string

Example: jobs/00000000-0000-0000-0000-000000000000/files/00000000-0000-0000-0000-000000000000

ダウンロード対象ファイルのref値
使用するWSトークンのkeysにこの値が含まれている必要があります。

query Parameters

ws_token

required

string

Example: ws_token=00000000-0000-0000-0000-000000000000

WSトークン
WSトークン発行時に指定されたexpireとtriesの有効期限内において複数回のダウンロードが可能です。

Responses

Response samples

200
404

Content type

application/octet-stream

File Data

ファイルアップロード

ファイルをアップロードします。
WSトークンが必要です。

アップロードしたファイルは契約の一時領域に格納され、ストレージ使用量に加算されます。
ファイルは6時間後に自動的に削除され、ストレージ使用量から減算されます。

query Parameters

ws_token

required

string

Example: ws_token=00000000-0000-0000-0000-000000000000

WSトークン
1つのWSトークンで複数回アップロードすることはできません。

header Parameters

content-type required	string Value: "text/plain"
x-cbot-encoding	string Default: plain Enum: "plain" "base64" ファイルデータのエンコードタイプ
x-cbot-filename required	string <= 64 characters ファイル名(拡張子含む)
x-cbot-timestamp	string ファイルの最終更新時刻(Unixタイムスタンプをミリ秒数で) 未指定の場合は現在時刻で記録されます。

Request Body schema: text/plain

ファイルデータ文字列
x-cbot-encodingリクエストヘッダがbase64の場合は、base64エンコードした文字列にします。

string

Responses

Request samples

Payload

Content type

text/plain

SGVsbG8sIHdvcmxkLg==

Response samples

Content type

application/json

{"code": 200,
"ref": "temp/00000000-0000-0000-0000-000000000000"
}

WSトークン発行

WSトークンを発行します。
このトークンはファイルアップロード/ファイルダウンロードAPIを使用する際に必要です。
使用するアクセストークンに「参照」権限が付与されている必要があります。

path Parameters

public_id

required

string

APIの公開ID

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string アクセストークントークン・シークレット認証の場合に必要です。
secret-key	string シークレットキートークン・シークレット認証の場合に必要です。
authorization	string Value: "Bearer {トークン}" OAuthアクセストークン OAuth認証の場合に必要です。値はBearerスキームで記述します。

Request Body schema: application/json

scopes required	Array of strings Items Enum: "upload" "download" このトークンで許可する操作名を配列で指定します。ファイルダウンロード: download ファイルアップロード: upload
keys required	Array of strings ファイルダウンロードを行う場合は、ダウンロード対象ファイルのref値を配列で指定します。ファイルアップロードを行う場合は、次の配列を指定します。 ["temp/"]
expire	integer [ 0 .. 86400 ] Default: 60 トークンの有効期限(秒)を指定します。この指定はscopesに"download"を指定した場合のみ有効です。 scopesに"upload"を指定した場合は常に60秒です。
tries	integer [ 0 .. 1000 ] Default: 1 keysに指定した各リソースへのアクセス可能回数を指定します。この指定はscopesに"download"を指定した場合のみ有効です。0を指定した場合は無制限です。 scopesに"upload"を指定した場合は常に1です。

Responses

Request samples

Payload

Content type

application/json

Example

example-1

{"scopes": ["download"
],
"keys": ["jobs/00000000-0000-0000-0000-000000000000/files/00000000-0000-0000-0000-000000000000",
"temp/00000000-0000-0000-0000-000000000000"
],
"expire": 120,
"tries": 3
}

Response samples

Content type

application/json

{"code": 200,
"ws_token": "00000000-0000-0000-0000-000000000000"
}