Overview

このドキュメントは、AUTORO のREST APIエンドポイントとその使い方をまとめています。

ここではコマンドラインでの利用で記述していますので、各プログラミング言語でも同様にできますので、適宜読み替えを行なってください。

Base URL

ここで紹介する API のエンドポイントのドメインは、次のものです。

https://api.roboticcrowd.com/

全てのエンドポイントはこのドメイン以下に設定されています。

Authorization

cURL での認証情報の送信

curl --location --request GET "https://api.roboticcrowd.com/v1/path/to/endpoint" \
  --header "Authorization: Bearer [your_jwt_token]"

*path/to/endpoint と [your_jwt_token] は、正しいエンドポイントに置き換えてください。

例えば具体的には、次のようになります。

curl --location --request POST "https://api.roboticcrowd.com/v1/session_queues" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwczovL2FwaS5yb2JvdGljY3Jvd2QuY29tLyIsImlzcyI6ImNvbnNvbGUucm9ib3RpY2Nyb3dkLmNvbSIsInN1YiI6Iklqb2lJaXdpWjNKaGJuUnpJanA3SW0iLCJuYmYiOjE0NTA0NzExNDcsImV4cCI6MTQ1MDQ3Mzc0Nywic2NvcGVzIjpbInNlc3Npb25fcXVldWUud3JpdGUiLCJzZXNzaW9uX3F1ZXVlLnJlYWQiLCJ0b2tlbiJdfQ.fpJ-Ho1IvdRdDdBD-ncp7Xkbijj6UmcboUODi_XtMJk" \
  --header "content-type: application/json" \
  --data "{
  \"workflow_id\": 6391
}"

*path/to/endpoint と [your_jwt_token] は、正しいエンドポイントに置き換えてください。

AUTORO では、API の認証にJWTを使っています。JWTは、プロジェクト内で作成した API Key のaccess_key_id と secret_access_key から作成することができます。API Key は、プロジェクトオーナー権限をもつユーザーがプロジェクト管理画面から作成する事ができます。 API Key の作成については、こちらの記事を参照してください。

クライアント側で JWT を作成する事を想定していますが、JWT トークンを取得するためのエンドポイントも用意しています。

JWT は、3つの部分、すなわちヘッダー、ペイロード、および署名からなる、エンコードされたJSONオブジェクトです。

API の認証は、ヘッダーに以下のように JWT を設定することで可能になります。

Authorization: Bearer [your_jwt_token]

具体的には、次のような形式になります。

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwczovL2FwaS5yb2JvdGljY3Jvd2QuY29tLyIsImlzcyI6ImNvbnNvbGUucm9ib3RpY2Nyb3dkLmNvbSIsInN1YiI6Iklqb2lJaXdpWjNKaGJuUnpJanA3SW0iLCJuYmYiOjE0NTA0NzExNDcsImV4cCI6MTQ1MDQ3Mzc0Nywic2NvcGVzIjpbInNlc3Npb25fcXVldWUud3JpdGUiLCJzZXNzaW9uX3F1ZXVlLnJlYWQiLCJ0b2tlbiJdfQ.fpJ-Ho1IvdRdDdBD-ncp7Xkbijj6UmcboUODi_XtMJk

JWT の形式

JWT の具体例

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwczovL2FwaS5yb2JvdGljY3Jvd2QuY29tLyIsImlzcyI6ImNvbnNvbGUucm9ib3RpY2Nyb3dkLmNvbSIsInN1YiI6Iklqb2lJaXdpWjNKaGJuUnpJanA3SW0iLCJuYmYiOjE0NTA0NzExNDcsImV4cCI6MTQ1MDQ3Mzc0Nywic2NvcGVzIjpbInNlc3Npb25fcXVldWUud3JpdGUiLCJzZXNzaW9uX3F1ZXVlLnJlYWQiLCJ0b2tlbiJdfQ.fpJ-Ho1IvdRdDdBD-ncp7Xkbijj6UmcboUODi_XtMJk

JWT は、base64 エンコードされた、 JSON 形式の header と payload また、その両者を繋げて、ハッシュ化した signature のパートからなり、全部を . で繋げた文字列になります。

[header].[payload].[signature]

具体例を右側（小さい画面では下側）に表示しています。この形でエンコードされた文字列が JWT になります。

jwt.io でトークンを検証する事ができます。

header

{
  "alg": "HS256",
  "typ": "JWT"
}

ヘッダーに使われる JSON は、次のようになります。

alg

alg は、署名を生成するアルゴリズムを指定しています。 HS256 となっている必要があります。

typ

typ は、 JWT となっている必要があります。

ペイロード payload

payload

{
  "iss": "console.roboticcrowd.com",
  "sub": "IjoiIiwiZ3JhbnRzIjp7Im",
  "aud": "https://api.roboticcrowd.com/",
  "nbf": 1450471147,
  "exp": 1450473747,
  "scopes": "session_queue.write session_queue.read access_token.create"
}

各項目について説明していきます。

iss

iss は、トークンの発行者を示すデータです。console.roboticcrowd.com を設定してください。

sub

sub は、API Key を作成した時に決定される AUTORO 内で一意の ID です。利用する API Key の access_key_id をセットしてください。 AUTORO は、sub を一人のユーザーとして認識します。

aud

aud は、トークンを受け取るURLです。https://api.roboticcrowd.com/ である必要があります。

nbf

nbf は、not before の略で、指定した unix 時間以降にトークンが初めて有効になります。通常は、現在時刻を指定しておけば問題ないでしょう。

exp

exp は、expire の略で、指定した unix 時間以降にトークンが無効になります。

scopes

scopes は、このトークンで許容された API の利用権限を入力します。

この権限は、API Key を作成する時にも設定できますが、個別のトークンにもスコープを設定できます。両方で許容された権限のみが利用できるようになります。

スコープの詳細

スコープ	権限
session_queue.write	実行キューを作成できます
session_queue.read	実行キューの取得、ワークフロー一覧の取得ができます
session_queue.delete	実行キューをキャンセルできます
access_token.create	トークンの作成ができます

署名

signature

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  "your_secret_access_key"
)

*your_secret_access_key は、正しいアクセスキーで置き換えてください。

コマンドラインでの署名は、次の節の JWT を生成するを参照してください。

署名は、トークンの信頼性を担保するパートになっています。署名は、 header と payload をそれぞれ base64 エンコードした文字列を . で接続し、 secret_access_key でハッシュ値を計算したものになります。ですので、 secret_access_key が安全に保存されている事は非常に重要になります。

AUTORO では、 secret_access_key は、暗号化されデータベースに保存されています。生の secret_access_key は、API Key を生成したタイミングで一度だけ表示されます。そして2度とやりとりされることはありません。

署名を検証することにより、ペイロードが改ざんされていないことを確認する事ができます。

JWT を生成する

headerを生成する

echo -n '{"alg":"HS256","typ":"JWT"}' | base64
# eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

payloadを生成する

echo -n '{"iss": "console.roboticcrowd.com","sub": "IjoiIiwiZ3JhbnRzIjp7Im","aud": "https://api.roboticcrowd.com/","nbf": 1450471147,"exp": 1450473747,"scopes": "session_queue.write session_queue.read access_token.create"}' | \
base64 | \
tr -d '='

# eyJpc3MiOiAiY29uc29sZS5yb2JvdGljY3Jvd2QuY29tIiwic3ViIjogIklqb2lJaXdpWjNKaGJuUnpJanA3SW0iLCJhdWQiOiAiaHR0cHM6Ly9hcGkucm9ib3RpY2Nyb3dkLmNvbS8iLCJuYmYiOiAxNDUwNDcxMTQ3LCJleHAiOiAxNDUwNDczNzQ3LCJzY29wZXMiOiAic2Vzc2lvbl9xdWV1ZS53cml0ZSBzZXNzaW9uX3F1ZXVlLnJlYWQgYWNjZXNzX3Rva2VuLmNyZWF0ZSJ9

signatureを生成する

# echo -n "header.payload" | openssl dgst -binary -sha256 -hmac "secret_access_key" | base64 | sed "s/+/-/g;s/\//_/g;s/=//g"

echo -n "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiAiY29uc29sZS5yb2JvdGljY3Jvd2QuY29tIiwic3ViIjogIklqb2lJaXdpWjNKaGJuUnpJanA3SW0iLCJhdWQiOiAiaHR0cHM6Ly9hcGkucm9ib3RpY2Nyb3dkLmNvbS8iLCJuYmYiOiAxNDUwNDcxMTQ3LCJleHAiOiAxNDUwNDczNzQ3LCJzY29wZXMiOiAic2Vzc2lvbl9xdWV1ZS53cml0ZSBzZXNzaW9uX3F1ZXVlLnJlYWQgYWNjZXNzX3Rva2VuLmNyZWF0ZSJ9" | \
openssl dgst -binary -sha256 -hmac "523463041EF9FFA2950D8450FEB34C88BC8692C40C9CF3C99DCDF75E270229E2" | \
base64 | sed "s/+/-/g;s/\//_/g;s/=//g"

# 45ervId5_CudT4hya5Tbx30OrO08KCewFQlgxU7mfew

生成されたJWT

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiAiY29uc29sZS5yb2JvdGljY3Jvd2QuY29tIiwic3ViIjogIklqb2lJaXdpWjNKaGJuUnpJanA3SW0iLCJhdWQiOiAiaHR0cHM6Ly9hcGkucm9ib3RpY2Nyb3dkLmNvbS8iLCJuYmYiOiAxNDUwNDcxMTQ3LCJleHAiOiAxNDUwNDczNzQ3LCJzY29wZXMiOiAic2Vzc2lvbl9xdWV1ZS53cml0ZSBzZXNzaW9uX3F1ZXVlLnJlYWQgYWNjZXNzX3Rva2VuLmNyZWF0ZSJ9.45ervId5_CudT4hya5Tbx30OrO08KCewFQlgxU7mfew

JWT を生成するには、URL-safe な base64 文字列に変換する必要があります。command line で base64 エンコードするのは、簡単のようで簡単ではありません。各OSによって微妙に仕様が異なっています。

ここでは、macOSの例を示しています。JWT は、URL-Safe な文字列である必要があるため、+ を - に、 / を _ に置き換えています。さらに、base64 では、 = がパディングとして利用されており、これは JWT に必要がないので、削除するコマンドも含めています。

まず、ヘッダーを生成します。これは全てのユーザーで同一になるはずで、生成しなくとも、以下のものをそのまま使えます。

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

次に、ペイロードを生成します。ペイロードで設定すべきは、 exp と scopes でしょう。これをできる限り必要最小限のものにすればより安全なトークンを生成できます。

それから、署名を行います。ヘッダーとペイロードを secret_access_key を用いて HMACSHA256 で署名します。

最後に、これらの出力を全てドット . で接続して JWT の完成です。

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiAiY29uc29sZS5yb2JvdGljY3Jvd2QuY29tIiwic3ViIjogIklqb2lJaXdpWjNKaGJuUnpJanA3SW0iLCJhdWQiOiAiaHR0cHM6Ly9hcGkucm9ib3RpY2Nyb3dkLmNvbS8iLCJuYmYiOiAxNDUwNDcxMTQ3LCJleHAiOiAxNDUwNDczNzQ3LCJzY29wZXMiOiAic2Vzc2lvbl9xdWV1ZS53cml0ZSBzZXNzaW9uX3F1ZXVlLnJlYWQgYWNjZXNzX3Rva2VuLmNyZWF0ZSJ9.45ervId5_CudT4hya5Tbx30OrO08KCewFQlgxU7mfew

出来上がった JWT を jwt.io で検証してみましょう。Encoded のテキストエリアに JWT をペーストとします。その下に、 Invalid Signature と表示されたのではないでしょうか。これは署名が検証できなかったという事です。

右側の Decoded の VERIFY SIGNATURE というセクションにシークレットキーを入力するところがありますので、この例のシークレットキー 523463041EF9FFA2950D8450FEB34C88BC8692C40C9CF3C99DCDF75E270229E2 を入力してみてください。

Signature Verified になりましたでしょうか？よかったです。これで JWT が検証され有効なトークンが生成できました。

Token

トークンを生成する

tokenを取得する

curl --location --request POST "https://api.roboticcrowd.com/v1/token" \
  --header "content-type: application/json" \
  --data "{
  \"access_key_id\": \"your_access_key_id\",
  \"secret_access_key\": \"your_secret_access_key\",
  \"expires\": 3600
}"

*your_access_key_id と your_secret_access_key は、API Key から正しい値に置き換えてください。

このエンドポイントは、JWTトークンをサーバーサイドで生成して返却します。他のエンドポイントと認証が異なっており、 access_key_id と secret_access_key を直接送信してもらうことにより認証しています。

HTTP Request

POST https://api.roboticcrowd.com/v1/token

パラメーター

access_key_id

初期値

無し、必須

説明

アクセスキーIDです。プロジェクトの API Key より確認できます。

secret_access_key

初期値

無し、必須

説明

シークレットアクセスキーです。プロジェクトの API Key を生成した時にのみ確認できます。紛失した場合は、該当する API Key を削除し新たに作成してください。

expires

初期値

600

説明

トークンの有効期間（秒）です。初期値は、10分です。

Session Queue

Session Queue とは、実行キューのことです。実行が要求されると直ちに作成されます。 Session Queue が作成された時に実行可能なロボットがあれば、ただちに実行が試みられます。実行が試みられると同時にロボットが割り当てられ、Session が作成されます。 params 内のオブジェクトとして設定した key と value は、ワークフロー内で定義した変数の初期値を定義します。

実行キューを作成する

POST /v1/session_queues

curl --location --request POST "https://api.roboticcrowd.com/v1/session_queues" \
  --header "Authorization: Bearer [jwt_token]" \
  --header "content-type: application/json" \
  --data "{
  \"workflow_id\": [workflow_id],
  \"params\": {
    \"var1\": \"this is string\",
    \"var2\": [\"this\", \"is\", \"array\"]
  }
}"

Response

{
  "id": 123123123,
  "project_id": 123123123123,
  "started_at": "2019-07-09T10:02:57.000Z",
  "ended_at": "2019-07-09T10:04:01.000Z",
  "status": "running",
  "created_at": "2019-07-09T10:02:57.000Z",
  "workflow": {
    "id": 12341234,
    "name": "Awesome Workflow."
  },
  "params": {
    "var1": "this is string",
    "var2": ["this", "is", "array"]
  },
  "robot": {
    "id": 12341234,
    "name": "standard-1"
  }
}

このエンドポイントは、実行するワークフローの ID を指定して、実行キューを作成します。指定できるワークフロー ID は、API Key が作成されたプロジェクト内に限ります。

HTTP Request

POST https://api.roboticcrowd.com/v1/session_queues

パラメーター

workflow_id

初期値

無し、必須

説明

ワークフローを指定する ID です。ワークフロー ID は、AUTORO のプロジェクト画面から確認できます。

params

初期値

無し、任意

説明

ワークフロー内で使用される変数の初期値を定義します。ワークフロー内で未定義の変数を使用することにより実行時に変数を定義することができるようになります。現在のところ、ここで指定したパラメーター内に、文字列として変数リテラル ${...} が使われていると意図しない挙動をするか例外となります。例： { var1: "this is ${var1}"}

応答

Session Queue Schema のJSONオブジェクトを返却します。

実行キューの一覧を取得する

GET /v1/session_queues

curl --location --request GET "https://api.roboticcrowd.com/v1/session_queues?page=1&per_page=3&query=before:2019-10-11%20after:2019-07-01" \
  --header "Authorization: Bearer [your_jwt]"

Response

{
  "session_queues": [
    {
      "id": 341559,
      "project_id": 226,
      "started_at": "2019-07-09T10:02:57.000Z",
      "ended_at": "2019-07-09T10:04:01.000Z",
      "status": "success",
      "created_at": "2019-07-09T10:02:57.000Z",
      "workflow": {
        "id": 123123,
        "name": "test"
      },
      "params": {
        "var1": "this is string",
        "var2": ["this", "is", "array"]
      },
      "robot": {
        "id": 12341234,
        "name": "sunaba-1"
      }
    },
    {
      "id": 341558,
      "project_id": 226,
      "started_at": "2019-07-09T10:01:44.000Z",
      "ended_at": "2019-07-09T10:03:31.000Z",
      "status": "error",
      "created_at": "2019-07-09T10:01:44.000Z",
      "workflow": {
        "id": 12341234,
        "name": "test"
      },
      "params": {
        "var1": "this is string",
        "var2": ["this", "is", "array"]
      },
      "robot": {
        "id": 12341234,
        "name": "sunaba-2"
      }
    },
    {
      "id": 341557,
      "project_id": 226,
      "started_at": "2019-07-09T10:00:38.000Z",
      "ended_at": "2019-07-09T10:01:23.000Z",
      "status": "success",
      "created_at": "2019-07-09T10:00:38.000Z",
      "workflow": {
        "id": 12341234,
        "name": "test"
      },
      "params": {
        "var1": "this is string",
        "var2": ["this", "is", "array"]
      },
      "robot": {
        "id": 12341234,
        "name": "sunaba-1"
      }
    }
  ],
  "total_count": 1581
}

このエンドポイントは、API Key が作成されたプロジェクトの Session Queue の一覧を取得します。パラメーターとして、検索条件、ページ数、ページあたりの件数を設定できます。

HTTP Request

GET https://api.roboticcrowd.com/v1/session_queues?page=1&per_page=10&query=

クエリパラメーター

query

初期値

無し

説明

検索条件を文字列で指定します。検索条件については、こちらに詳細があります。

per_page

初期値

説明

取得するページあたりの件数です。 1ページあたりの最大数は50件です。

page

初期値

説明

取得するページです。

organization_id

初期値

無し

説明

query に workflow_id を指定するとき、組織 ID（organization_id）かプロジェクト ID（project_id）を指定する必要があります。

project_id

初期値

無し

説明

query に workflow_id を指定するとき、組織 ID（organization_id）かプロジェクト ID（project_id）を指定する必要があります。

応答

JSON オブジェクトを返却します。

session_queues

Session Queue Schema の JSON オブジェクトの配列が格納されています。

total_count

Session Queue Schema のトータル件数が格納されています。

実行キューをキャンセルする

DELETE /v1/session_queues/{session_queue_id}/cancel

curl --location --request DELETE "https://api.roboticcrowd.com/v1/session_queues/{session_queue_id}/cancel" \
  --header "Authorization: Bearer [jwt_token]" \
  --header "content-type: application/json"

このエンドポイントは、実行キューの ID を指定して、実行中のワークフローの実行をキャンセル、または実行待ちのキューの削除を行います。指定できる実行キュー ID は、API Key が作成されたプロジェクト内に限ります。

HTTP Request

DELETE https://api.roboticcrowd.com/v1/session_queues/{session_queue_id}/cancel

session_queue_id（実行キューID）の確認方法

プロジェクトのセッション画面の ID により確認できます。

Session Queue Schema

Session Queue のオブジェクトの返却は、

id

作成された実行キュー（Session Queue）のIDです。

project_id

プロジェクト ID です。

started_at

直ちに実行されれば、実行が開始された日時が文字列として入っています。実行されていなければ null となります。

ended_at

実行が終了していれば、実行が終了した日時が文字列として入っています。終了していなければ null となります。

status

ステータスは、

queued: 実行まち
running: 実行中
success: 成功
error: 失敗（異常終了）

のいずれかになります。

created_at

実行キューがデータベースに登録された日時が文字列として入っています。

workflow

ワークフローの詳細が記述されている JSON オブジェクトです。返却される項目は、ID とワークフロー名 (name) だけです。

params

実行キュー作成時に渡された変数が記述されている JSON オブジェクトです。

robot

ロボットの詳細が記述されている JSON オブジェクトです。返却される項目は、ID とロボット名 (name) だけです。

Workflow

Workflow とは、自動化設定そのものです。外部からワークフローを指定してSession Queue に登録する際に Workflow の ID が必要になりますが、一覧取得のエンドポイントによりIDを確認し指定することができるようになります。

ワークフロー一覧を取得する。

このエンドポイントは、API Key が作成されたプロジェクトの Workflow の一覧を取得します。パラメーターとして、ページ数、ページあたりの件数を設定できます。パラメーターの指定がない時は、ページあたりの件数は、300件、ページは1ページ目になります。ページあたりの件数は最大で、1000まで指定できます。

GET /v1/workflows

curl --location --request GET "https://api.roboticcrowd.com/v1/workflows?page=1&per_page=10" \
  --header "Authorization: Bearer [your_jwt]"

Response

{
  "workflows": [
    {
      "id": 123123122,
      "name": "workflow name1",
      "description": "this is tutorail user's workflow",
      "vpn_option_id": null,
      "debug_mode": true,
      "robot_type": "singleruntime",
      "single_process_mode": true,
      "error_handler_workflow_id": null,
      "color": "#000000",
      "receiver_infos": "",
      "workflow_robots": []
    },
    {
      "id": 123123123,
      "name": "workflow name2",
      "description": "this is tutorials user's workflow",
      "vpn_option_id": null,
      "debug_mode": true,
      "robot_type": "singleruntime",
      "single_process_mode": true,
      "error_handler_workflow_id": null,
      "color": "#000000",
      "receiver_infos": "",
      "workflow_robots": []
    }
 ],
 "total_count": 102
}

HTTP Request

GET https://api.roboticcrowd.com/v1/workflows?page=1&per_page=10

クエリパラメーター

per_page

初期値 300

説明

取得するページあたりの件数です。 1ページあたりの最大数は1000件です。

page

初期値 1

説明

取得するページです。

応答

JSON オブジェクトを返却します。

workflows

Workflow Schema の JSON オブジェクトの配列が格納されています。

total_count

トータル件数が格納されています。

Quota

APIリクエストの制限は、各組織で契約しているロボット数に応じて決定されています。ロボット一台の契約につき、 1分ごとに60リクエストを上限としています。

Errors

AUTORO が返却する API のエラーコードです。

Code	Description
400	Bad Request -- リクエストが無効です。
401	Unauthorized -- JWT が無効です。
403	Forbidden -- 禁止されたリクエストです。
404	Not Found -- リクエスト対象のリソースが発見できませんでした。これには権限が理由になり発見できなかった場合も含みます。
406	Not Acceptable -- リクエストのフォーマットが異なっています。
429	Too Many Requests -- リクエストのクオータ上限値に達しました。
500	Internal Server Error -- サーバー内で何かしらのエラーが発生しました。
503	Service Unavailable -- サーバーに障害が発生し応答ができません。

Overview

Base URL

Authorization

ヘッダー header

alg

typ

ペイロード payload

iss

sub

aud

nbf

exp

scopes

署名

JWT を生成する

Token

トークンを生成する

HTTP Request

パラメーター

access_key_id

secret_access_key

expires

Session Queue

実行キューを作成する

HTTP Request

パラメーター

workflow_id

params

応答

実行キューの一覧を取得する

HTTP Request

クエリパラメーター

query

per_page

page

organization_id

project_id

応答

session_queues

total_count

実行キューをキャンセルする

HTTP Request

session_queue_id（実行キューID）の確認方法

Session Queue Schema

id

project_id

started_at

ended_at

status

created_at

workflow

params

robot

Workflow

ワークフロー一覧を取得する。

HTTP Request

クエリパラメーター

per_page

説明

page

説明

応答

workflows

total_count

Quota

Errors