公開API利用ガイド

この記事の内容

    RPA OAPI 利用ガイド

    0. 利用説明

    本ドキュメントは、Dr.Robo RPA OAPI との正式な連携を始める前に、「API 全体がどのように構成されているか、どの場面でどの API を使うか、複数の API をどのように組み合わせるか」を把握していただくためのガイドです。

    本ドキュメントに記載している API の具体的な入力パラメータと出力パラメータについては、各 API の詳細ドキュメントを参照してください。

    1. 全体モデル

    API を呼び出す前に、以下の主要な概念の関係を確認しておくことをお勧めします。

    概要として、アカウントは「誰が使うか」、ロボットは「何を実行するか」、ロボット端末は「どのマシンで実行するか」に対応します。Job は最小の実行単位であり、一般タスク は RPA ロボットとロボット端末の実行構成をまとめたものです。

    OAPI 全体は 6 つの主要モジュールに分かれています。以下の順序で理解し、連携を進めることをお勧めします(実際に企業コンソールと連携する際の順序に沿って並べています)。

    モジュール 解決する課題 主な利用場面
    アカウント管理 企業内のログインアカウントを管理します 新入社員のアカウント作成、退職者のアカウント処理、パスワード管理
    RPA ロボット管理 ロボット資産、バージョンを管理します 利用可能なロボットの確認
    ロボット端末とスケジュール実行 ロボットを実際に実行し、実行結果を取得します ワンクリックでの単発実行、一括実行、結果の追跡
    ワークキュー管理 標準の業務作業依頼キューを提供します 高度なスケジュールタスクと組み合わせた、非同期で大量のデータを処理する場面
    データ API 元の実行データを提供します 運用レポートの作成、ユーザー別/ロボット別/全体集計での統計分析

    3. アカウント管理

    主要な概念:企業アカウントには basic(基本アカウント)と senior(上級アカウント)の 2 種類があります。ロールには e_admin(管理者)と e_user(一般社員)の 2 種類があります(公開 API で作成/変更できるのはこの 2 種類のロールのみです。企業のスーパー管理者など、より高い権限を持つロールは OAPI では管理しません)。

    関連 API:

    •         POST /oapi/rpa/user/v1/create — 企業ユーザーを作成します

    •         POST /oapi/rpa/user/v1/delete — 企業ユーザーを削除します

    •         GET /oapi/rpa/user/v1/list — 企業ユーザー一覧を取得します

    •         POST /oapi/rpa/user/v1/modify — 企業ユーザーを変更します

    •         POST /oapi/useracl/v1/rest/pwd — パスワードをリセットします

    注意事項:

    1.       v1 の delete API には receiveAccount を渡す必要があります。アカウントを削除すると、そのアカウントが所有するロボットなどの資産は receiveAccount に移管されます。両方のアカウントが同じ企業に属している必要があり、そうでない場合はエラーになります。

    2.       list API の size の上限は 100 です。

    3.       /oapi/useracl/v1/rest/pwd はユーザー自身によるパスワード変更用 APIです(検証のために oldPwd として古いパスワードを指定する必要があります)。管理者がパスワードを強制的にリセットするための API ではありません。

    4. RPA ロボット管理

    主要な概念:ロボットの種類を表す appType には app(ロボット)と activity(コマンド)があります。各ロボットには「開発バージョン」と「公開済みバージョン(online)」の区別があり、両方のバージョンが共存できます。ただし、オンラインで実行されるのは公開済みバージョンです。この区別は、どの照会 API を呼び出すべきかに直接影響します(下記の注意事項を参照してください)。ロボットマーケットは「共有グループ」の一種です。企業は複数のマーケットを作成し、ユーザーをマーケットに追加して、ロボットをマーケットで共有できます。他のマーケットメンバーは、共有されたロボットを閲覧/利用できます。

    関連 API:

    •         POST /oapi/app/open/query/list — ロボット一覧を照会します

    •         GET /oapi/app/open/query/appOnlineDetailWithParam — ロボットの公開済みバージョンの詳細とパラメータを照会します

    •         GET /oapi/app/open/query/appVersionDetail — ロボットの現在の開発バージョンの詳細を照会します

    •         POST /oapi/app/open/historyVersionList — バージョン履歴一覧を取得します

    •         GET /oapi/app/open/queryVersionFlowList — サブフロー/コマンドセット一覧を取得します

    •         POST /oapi/app/open/translate/owner — ロボットの owner を移管します

    注意事項:

    1.       appOnlineDetailWithParam と appVersionDetail は用途が異なり、混同しやすいため注意してください。appVersionDetail は「現在の開発バージョン」を照会します(公開済みバージョンがない場合は、開発バージョンの表示にフォールバックします)。ロボットの概要を把握するのに適しています。appOnlineDetailWithParam は実行を開始する前のパラメータ照会専用で、ロボットの online バージョンが公開済みであることが必須です。公開されていない場合は、「应用未上线」(ロボットが公開されていません)というエラーが返されます。「先にパラメータ定義を照会し、その後スケジュール API を呼び出してロボットを実行する」必要がある場合は、appOnlineDetailWithParam を使用し、ロボットが公開済みであることを確認してください。

    5. ロボット端末とスケジュール実行(重要)

    ここは OAPI 全体で最も中心的であり、使い方を誤りやすい部分でもあります。スケジュール API には 2 つの系統があります。

    •         1 つは単一実行単位の API です。1 回のリクエストで「どのロボットを、どのロボット端末/端末グループで実行するか」を直接指定します。サーバー側は事前設定に一切依存しません。こちらが推奨の方法です。

    •         もう 1 つは一般タスクの API です。ロボット端末、実行時刻のルール、失敗時のポリシーなどを、あらかじめコンソールで 1 つの「スケジュールタスク」として設定し、その後 API で実行を開始します。この方法は特定の場面でのみお勧めします。関連する設定は API の呼び出し側からは表示されず、変更もできないため、理解や問題調査に比較的多くの手間がかかります。設定が複雑なため、一般タスクを作成する API は公開していません。

    以下では、まず両者の関係と違いを説明し、その後それぞれを詳しく紹介します。

    5.1 2 系統の API の主な違い

    観点 単一実行スケジュール(推奨) 一般タスク
    「何を、どこで実行するか」の設定方法 1 回の API リクエストですべて指定します コンソールで事前に設定し、API は実行開始にのみ使用します
    リクエストだけで設定が完結するか はい。ロボット端末、パラメータ、タイムアウト、コールバックをすべて今回のリクエストで指定します いいえ。ロボット端末一覧と実行ポリシーは、事前設定された一般タスクから取得します
    1 回の呼び出しに対応する実際の実行回数 常に 1 回です(1 個の Job) 複数回に分岐する場合があります(1 個の Task に N 個の Job が属します)
    実行状態の確認方法 該当する Job の状態を直接確認します Task の集約状態を確認し、jobDataList を展開してロボット端末ごとに確認する必要があります
    コールバックの単位 Job ごとに個別に 1 回コールバックします Task 全体の完了後に、集約したコールバックを 1 回送信します(すべての Job の結果を含みます)
    実行対象を追加できるか できます。リクエストで任意の対象を指定できます できません。Schedule に設定済みのロボット端末に対する設定のみ上書きできます
    適した場面 API を中心とする大半の連携場面 複雑な複数端末の実行構成/Cron による定時実行の要件がすでにあり、その設定をコンソールで管理する場合

    5.2 概念の関係図

    どちらの経路も呼び出し側から開始します。単一実行スケジュールでは、1 回のリクエストから直接 1 個の Job が作成され、サーバー側は事前設定に一切依存しません。一般タスクでは、企業管理者があらかじめコンソールで設定した一般タスク(ロボット端末/グループ、cron、再試行ポリシー)に依存します。呼び出し側ができるのは実行開始(task/start)と照会のみです。実行開始後、Task は一般タスクに事前設定されたロボット端末一覧に従い、1 個または複数の Job に分岐します。

    5.3 ロボット端末管理

    スケジュール API を呼び出す前に、通常は利用可能なロボット端末を確認する必要があります。

    •         POST /oapi/dispatch/v2/client/list — ロボット端末一覧を取得します

    •         POST /oapi/dispatch/v2/client/query — ロボット端末の詳細を取得します(現在タスクを実行中かどうかを含みます)

    •         POST /oapi/dispatch/v2/client/group/list — ロボット端末グループ一覧を取得します

    •         POST /oapi/dispatch/v2/client/getLastHeartTime — ロボット端末の最終ハートビート日時を照会します

    実行対象の指定には、併用できない 2 つの方法があります。accountName を使用して 1 台のロボット端末を厳密に指定するか、robotClientGroupUuid + executeScope(任意の 1 台/すべて)を使用してロボット端末グループを指定します。

    5.4 【推奨】指定した RPA ロボットを指定したロボット端末で実行する(単一実行スケジュール)

    •         POST /oapi/dispatch/v2/job/start — 1 回の実行を開始します

    •         POST /oapi/dispatch/v2/job/query — Job の詳細を照会します

    •         POST /oapi/dispatch/v2/job/list — Job 一覧を照会します

    •         POST /oapi/dispatch/v2/job/stop — 実行を停止します

    •         POST /oapi/dispatch/v2/job/retry — 実行を再試行します

    job/start の主要パラメータ(1 回のリクエストで設定が完了し、コンソールでの事前操作は一切不要です):

    パラメータ 説明
    accountName / robotClientGroupUuid + executeScope いずれか一方を選び、1 台のロボット端末または 1 つのグループを指定します
    robotUuid 実行するロボットです
    priority タスクの優先度です
    params ロボットの実行パラメータです(name/value/type/direction/description)
    runTimeout 実行タイムアウトです。指定可能な範囲は 60 秒 ~ 950500 秒(約 11 日)で、超過すると失敗と判定されます
    idempotentUuid 冪等性識別子です。36 文字以内で、同一テナント内で一意である必要があります
    callbackUrl 実行終了後のコールバック先アドレスです
    waitTimeout / enableWaitTimeout キューでの待機タイムアウトに関する設定です
    enableCloudLog / enableCloudScreenRecord クラウド上にログ/画面録画を保存するかどうかを指定します
    summary 備考です。128 文字以内で指定します

    状態遷移:created → waiting → running →(stopping → stopped)| error | finish | skipped | cancel。このうち stopped、error、finish、skipped、cancel が終了状態です。error、skipped、cancel、stopped の終了状態では、job/retry を呼び出して再試行できます。

    冪等性の仕組み:idempotentUuid を渡した後、同一テナント内で同じ値を使用して job/start を繰り返し呼び出しても、新しい実行記録は作成されません。代わりに既存の jobUuid がそのまま返され、レスポンスの idempotentFlag が true に設定されます。これにより、「ネットワーク異常後の安全な再試行」を実現できます。

    コールバックの仕組み:各 Job の終了後に個別に 1 回コールバックが発生し、POST で callbackUrl に送信されます。内容には jobUuid、最終状態、出力パラメータ、ロボット端末情報、開始/終了日時、スクリーンショットのアドレスなどが含まれます。リクエストの query パラメータには、送信元の検証に使用する bodyMd5/timestamp/sign が含まれます。コールバック先が一時的に応答できない場合(2xx 以外)は、システムが自動的に再送を試みます(デフォルトでは 24 時間以内は継続して再試行します)。

    5.5 実行ログ

    •         POST /oapi/dispatch/v2/job/log/notify — ログ照会リクエストを送信し、requestId を取得します

    •         GET /oapi/dispatch/v2/job/log/query — requestId を使用してログの結果をポーリングします

    •         POST /oapi/dispatch/v2/job/log/search — ログを同期的に照会します

    ログの量が少なく、すぐに結果を取得する必要がある場合は search(同期)をお勧めします。ログの量が多く、API のタイムアウトが懸念される場合は、notify + query による非同期ポーリングをお勧めします。現在、この 3 つのログ API は「プラットフォームレベル」のクライアントにのみ公開されています。呼び出し時に権限に関するエラーが返された場合は、まず認証情報の種類が要件を満たしているか確認してください。

    5.6 ファイルをアップロード

    •         POST /oapi/dispatch/v2/file/upload — ファイルをアップロードします

    job/start の「ファイルタイプ」の入力パラメータにファイルの内容を指定するために使用します。先にアップロードして fileKey を取得し、その後 fileKey を該当するパラメータの値として job/start に渡します。

    5.7 一般タスク:

    •         POST /oapi/dispatch/v2/schedule/list — 一般タスク一覧を取得します

    •         POST /oapi/dispatch/v2/schedule/detail — 一般タスクの詳細を取得します

    •         POST /oapi/dispatch/v2/task/start — 実行を開始します

    •         POST /oapi/dispatch/v2/task/stop — タスクを停止します

    •         POST /oapi/dispatch/v2/task/list / newest/list — 実行記録一覧を取得します

    •         POST /oapi/dispatch/v2/task/query — タスク全体の詳細を照会します

    •         POST /oapi/dispatch/v2/task/process/detail — 特定のロボット端末における特定のタスクの実行詳細を照会します

    このモードが比較的複雑である主な理由は、次のとおりです。

    1.       一般タスクの作成/変更はコンソールでのみ行えます。API が提供するのは list/detail による読み取り専用機能のみです。ロボット端末の選択方法(単一端末/グループ/すべて)、Cron 式、失敗時の再試行ポリシーなど、実際の実行動作を決定する主要な設定は、API の呼び出し側から参照できますが(detail を使用)、変更はできません。コンソールの操作権限を持つ担当者に協力を依頼する必要があります。

    2.       task/start に渡す scheduleRelaParams で上書きできるのは、Schedule に設定済みのロボット端末のパラメータ/タイムアウト設定のみです。この API を使って実行用のロボット端末を追加することはできません。

    3.       1 回の task/start が複数の Job に分岐する場合があります。一般タスクにロボット端末グループまたは複数のロボット端末が設定されている場合、タスクを 1 回開始すると、それらのロボット端末にそれぞれ 1 個の Job が作成されます。task/query が返す最上位の status は、Task レベルの集約状態です(Job の状態とは異なる独立した状態の列挙値を使用します)。各ロボット端末の実際の実行状態を確認するには、レスポンス本文の jobDataList を展開する必要があります。最上位の状態だけを確認すると、誤った判断につながる可能性があります(例えば、あるロボット端末では実行が失敗していても、最上位の状態にはまだ「実行中」と表示される場合があります)。

    4.       コールバックは Job 単位ではなく、Task 単位で集約して送信されます。タスク全体が終了した後に初めて 1 回のコールバックを受信し、そこには今回分岐したすべての Job の結果が含まれます。特定のロボット端末での実行完了後すぐに結果を知りたい場合、この API では対応できません。呼び出し側で task/query または task/process/detail をポーリングする必要があります。

    5.       task/stop は Task 全体を停止するため、その配下にある未終了の Job もすべて停止します。特定の 1 台のロボット端末だけを停止することはできません。

    適した場面:複雑な定時実行/複数端末の実行構成をすでにコンソールで管理しており(例えば、毎日未明に 5 台のロボット端末で同じ一連のロボットを実行する場合)、自社システムに Cron スケジューラを改めて実装せず、その設定を再利用したい場合は、この API 群を使って既存の一般タスクを「開始 + 照会」する方が効率的です。それ以外の場合は、5.4 の単一実行スケジュール API を優先して使用することをお勧めします。

    5.8 スケジュール実行の利用例

    例 1:指定したロボット端末でロボットを 1 回実行し、結果を取得する(単一実行スケジュール、推奨の手順)

    プレーンテキスト
    1. GET  client/list                          → 待機状態のロボット端末を 1 台探します
    2. GET  app/open/query/appOnlineDetailWithParam?appId=xxx
                                                  → ロボットが公開済みであることを確認し、渡す必要のあるパラメータの定義を取得します
    3. POST dispatch/v2/job/start
            { accountName, robotUuid, params, idempotentUuid, callbackUrl, runTimeout }
                                                  → jobUuid を取得します
    4a. 受信方式:システムから callbackUrl への POST を待機し、sign を検証した後、最終状態と出力パラメータを読み取ります
    4b. 照会方式:status が終了状態になるまで、POST dispatch/v2/job/query { jobUuid } をポーリングします
    5. ログを確認する場合:POST job/log/notify → requestId を取得します → GET job/log/query をポーリングします
    6. 実行が失敗し、再試行が必要な場合:POST dispatch/v2/job/retry { jobUuid }

    例 2:コンソールで設定済みの一般タスクを開始し、複数のロボット端末での実行結果を追跡する(Task モード)

    プレーンテキスト
    0. 【コンソール操作、API なし】管理者がコンソールで「一般タスク」を作成し、ロボット端末グループ、Cron、失敗時のポリシーを設定します
    1. POST dispatch/v2/schedule/detail { scheduleUuid }
                                                  → 事前設定されたロボット端末(robotList)を確認します
    2. POST dispatch/v2/task/start
            { scheduleUuid, scheduleRelaParams: [{ robotUuid, params, runTimeout }, ...] }
                                                  → schedule に設定済みのロボット端末のパラメータのみ上書きでき、taskUuid を取得します
    3. POST dispatch/v2/task/query { taskUuid } をポーリングします
                                                  → jobDataList を展開し、ロボット端末ごとの実際の状態を確認します。
                                                    最上位の task の集約 status だけを根拠に判断することはお勧めしません
    4. 特定のロボット端末の実行詳細を確認する場合:
            POST dispatch/v2/task/process/detail { taskUuid, robotClientUuid }
    5. 全体を中止する場合:POST dispatch/v2/task/stop { taskUuid }
                                                  → 該当する task 配下の未終了の job がすべて停止します

    6. ワークキュー管理

    主要な概念:ワークキューは、非同期処理や大量のデータを扱う場面で使用します。実際には高度なスケジュールタスクと組み合わせて使用することが多く、高度なスケジュールタスクで、ワークキューを通じてスケジュール実行を開始する方法を設定して連携させます。

    関連 API:

    •         GET /oapi/tool/queue/v1/queues — キュー一覧を照会します

    •         GET /oapi/tool/queue/v1/queues/{queueUuid}/queueItems — キュー項目をページ単位で照会します

    •         POST /oapi/tool/queue/v1/queues/{queueUuid}/enqueue — キューに追加します

    •         PATCH /oapi/tool/queue/v1/queues/{queueUuid}/dequeue — キューから取り出します

    •         PATCH /oapi/tool/queue/v1/queueitems/{itemUuid}/reenqueue — キューに再登録します

    •         PATCH /oapi/tool/queue/v1/queueitems/{itemUuid} — キュー項目を変更します

    •         PATCH /oapi/tool/queue/v1/{queueUuid}/batchModifyQueueItemStatus — 状態を一括変更します

    •         GET /oapi/tool/queue/v1/queues/{queueUuid}/count — 件数を取得します(監視に使用できます)

    •         GET /oapi/tool/queue/v1/status — ある状態から遷移できる状態を照会します

    キュー項目の状態遷移:

    modifyQueueItem/batchModifyQueueItemStatus を呼び出してキュー項目の状態を変更する前に、queryChangeableStatus を呼び出して変更先の状態が有効かどうかを確認することをお勧めします。これにより、リクエストが即座に拒否されることを避けられます。

    注意事項:

    1.       priority(優先度)には、0(高)、100(中)、200(低)の 3 つの値のみ指定できます。他の値を渡すと拒否されます。数値が小さいほど優先度が高くなります。

    2.       effectiveTime は expireTime 以前である必要があります。そうでない場合はキューへの追加が失敗します。expireTime を渡さない場合は、キューに設定されたデフォルトの有効期間を使用して算出します。そのキューにデフォルトの有効期間が設定されていない場合、キューへの追加は即座に失敗します。

    3.       dequeue は、取り出せる項目がない場合に空の結果を返します。エラーではありません。呼び出し側は例外として捕捉するのではなく、「現在利用できる項目がない」として処理してください。

    4.       PROCESSING(処理中)状態から遷移できるのは、PROCESSED(処理済み)または EXCEPTION(異常)のみです。途中でキュー待機状態や保留状態に戻すことはできないため、modifyQueueItem でも、この 2 つの状態への変更のみ許可されます。

    7. データ API

    主要な概念:この API は、詳細な実行記録を取得するために使用します。実行記録に基づき、RPA ロボット別、ユーザー別、企業全体の集計など、さまざまな観点でデータを集計できます。企業のデータダッシュボードの作成に使用できます。

    •         POST /oapi/app/open/query/pageRunRecordData — ロボットの実行記録をページ単位で照会します

    注意事項:

    1.       minTime/maxTime はどちらも必須で、指定する期間は 7 日を超えてはなりません。超過すると即座にエラーになります。より長い期間のデータを照会する場合は、呼び出し側で期間を分割し、複数回呼び出してください。

    2.       startModelList(実行方法による絞り込み)で選択可能な値には、schedule(スケジュール)、Trigger(トリガー)、Manual(手動実行)、Autorun(自動実行)、Assistant(スケジュール実行)、emailtrigger、filetrigger、hotkeytrigger があります。実行が手動で開始されたのか、何らかのトリガー/スケジュールによって自動的に開始されたのかを区別できます。

    OpenAPIの記事一覧ページの先頭へ ↑