ロボット実行コールバック

この記事の内容
  1. 事前操作
  2. コールバック連携方針
  3. ベストプラクティス
  4. テンプレート
  5. postManテンプレート
  6. javaテンプレート
  7. リクエスト
  8. リクエストヘッダー
  9. リクエストボディ
  10. コールバックの例
  11. レスポンス
  12. レスポンスボディ
  13. レスポンスボディの例

api.example.com、console.example.com、files.example.com は説明用のアドレスです。実際の環境で指定された API、管理画面、ファイル配布先の URL に置き換えてください。

事前操作

  1. 管理者アカウントでDr.Roboコンソールにログインし、API設定画面でコールバックインターフェースを設定します。
  2. インターフェースが正常に使用できることを確認します。
  3. 自社のサーバー環境を確認します。ファイアウォールがある場合は、テクニカルサポートに連絡し、Dr.Roboの本番環境のIPアドレスを許可リストに追加する必要があります。
  4. 先にロボットを起動インターフェースを呼び出し、jobUuidを取得する必要があります。

説明1:ロボットの実行状態が終了状態(正常終了、異常終了、停止済み)になると、Dr.Roboサービスは、自社で設定したコールバックインターフェースを通じてjobの実行結果データを自動的に返します。データを速やかに取得できるように、コールバック方式で結果データを取得することをお勧めします。

説明2:自社のコールバックインターフェースが2xxステータスコードを返すと、Dr.Roboは相手側がデータを正常に受信して処理したと判断し、定期的な再送を行いません。自社側が2xx以外のステータスコードを返す場合、Dr.Roboは毎正時に1回再送し、成功するか、24回に達すると定期的な再送を終了します。jobの状態に関するコールバックを24時間以上受信していない場合は、ロボット実行結果を照会を呼び出すことをお勧めします。

コールバック連携方針

  1. Dr.Roboにはコールバックの再試行機能があります。ロボットの実行が終了し、コールバックが失敗すると、Dr.Roboは24時間以内に毎正時に再試行し、成功するまで繰り返します。そのため、連携先は業務処理のレベルで冪等性を保証する必要があります(startJob時にロボットと実行ロボットを指定するモードか、タスクを指定するモードかに応じて、jobUuidまたはtaskUuidを使用して冪等性を保証できます)。
  2. Dr.Roboでは、コールバックインターフェースに非同期方式を採用することをお勧めします。まずDr.Roboのコールバックデータを受信して成功を返し、その後で非同期処理を行います(スレッドプールに投入して非同期処理を行います)。
  3. コールバックデータの確実な到達を保証するには、コールバックとポーリングを併用することをお勧めします。startJobの実行後は、2分間隔で1回ポーリングすることをお勧めします(実行時間が30分の場合は2分ごとに1回、1時間の場合は4分ごとに1回とし、以降も同様に間隔を延ばします。30分未満の場合は1分間隔をお勧めします)。コールバックが成功したらポーリングを停止します。

ベストプラクティス

  1. job/startが成功したら、jobUuidに基づいて業務テーブルa(具体的な名前は連携先が定義します)に記録します。業務テーブルにはjobUuidの一意インデックスを追加する必要があります。業務テーブルaには、少なくともjobUuid、ロボットの実行状態、有効期限を含める必要があります(期限に達した場合はデフォルトで成功とみなし、ポーリングを行いません。有効期限はjob/startの25時間後に設定することをお勧めします)。

  2. 定期タスクでこのテーブルをポーリングします。上記の間隔でポーリングし、実行状態が終了状態になった場合、または25時間が経過した場合は、ポーリングを終了することをお勧めします。

  3. コールバックまたはポーリングで、ロボットの実行状態が終了状態であることを受信したら(ロボット実行状態の列挙値の説明を参照)、業務テーブルaの状態をコールバック成功に更新します。

  4. 実行ロボット情報の照会インターフェースをポーリングします(実行ロボットによるロボットの実行時間に応じて、30分以内の場合は30秒ごとに1回、60分以内の場合は1分ごとに1回ポーリングします)。実行ロボットがアイドル状態になったら、タスクのjob/startを実行できます。実行ロボットの数が多い場合は、すべての実行ロボットを同時にポーリングせず、タイミングをずらしてポーリングすることをお勧めします。

    例:実行ロボットが100台ある場合は、100回に分けてポーリングすることをお勧めします。各実行ロボットへのポーリングを1秒間隔で開始し、集中を避けます。

例:実行ロボットが100台ある場合は、100回に分けてポーリングすることをお勧めします。各実行ロボットへのポーリングを1秒間隔で開始し、集中を避けます。

テンプレート

postManテンプレート

apiロボット実行コールバック模擬インターフェース.json(右ボタンでクリックして「名前を付けて保存」)

javaテンプレート

コールバックのモックインターフェース:
FakeCallbackController.java(右ボタンでクリックして「名前を付けて保存」)

コールバックデータモデル:
DataTypeResult.java(右ボタンでクリックして「名前を付けて保存」)
JobResult.java(右ボタンでクリックして「名前を付けて保存」)

ロボット実行パラメータモデル:
RobotParam.java(右ボタンでクリックして「名前を付けて保存」)

列挙型:
DataTypeEnum.java(右ボタンでクリックして「名前を付けて保存」)
JobStatusEnum.java(右ボタンでクリックして「名前を付けて保存」)

リクエスト

なし

リクエストヘッダー

基本 パラメータ値 説明
Content-Type application/json

リクエストボディ

名称 タイプ 必須かどうか 説明
jobUuid string はい ロボット実行のuuid
dataType string はい コールバックタイプです。呼び出し元は、このフィールドに基づいて各コールバックタイプのデータを解析する必要があります。例:dataTypeがjobに等しい場合は、job/startインターフェースによってコールバックがトリガーされたことを示します。dataTypeがtaskに等しい場合は、task/startインターフェースによってコールバックがトリガーされたことを示します。コールバックデータタイプの列挙値の説明を参照してください。
status string はい ロボットの実行状態です。ロボット実行状態の列挙値の説明を参照してください。
msg string いいえ ロボットの実行情報です。ロボットの実行時に異常が発生した場合は空ではありません。
startTime string はい ロボット実行の開始日時
endTime string はい ロボット実行の終了日時
robotClientUuid string はい 実行ロボットのuuid
robotClientName string はい 実行ロボットの名称
robotName string はい ロボットの名称
idempotentUuid string はい 今回のリクエストの冪等性を保証するuuidです。渡されなかった場合はランダムに生成されます。
result array いいえ ロボット実行の出力パラメータ
∟ name string いいえ パラメータ名
∟ value string いいえ パラメータ値
∟ type string いいえ パラメータタイプです。ロボット実行パラメータの列挙値の説明を参照してください。

コールバックの例

{
	"jobUuid": "42c2e0ce-499b-47aa-8642-3a1125b4759a",
	"dataType": "job",
	"status": "finish",
	"msg": "执行结束",
	"robotClientUuid": "bfd28e42-e530-41eb-bf46-796a86ff7ec3",
	"robotClientName": "ceshi1@csqy1",
	"startTime": "2021-02-03 11:11:11",
	"endTime": "2021-03-03 12:12:12",
	"robotName": "注文一覧を出力",
	"robotUuid": "xxxxx",
  	"idempotentUuid":"xxxx",
	"result": [
		{
			"name": "姓",
			"value": "王",
			"type": "str"
		},
		{
			"name": "名",
			"value": "5",
			"type": "str"
		},
		{
			"name": "上传文件",
			"value": "https://files.example.com/document/temp/request.txt",
			"type": "file"
		}
	]
}

レスポンス

2xxのHTTPステータスコードを返すだけで構いません。200を返すことをお勧めします。Dr.Roboサーバーは2xxステータスコードを受信すると、再試行と定期的な再送を停止します。

レスポンスボディ

なし

レスポンスボディの例

なし

エラーが発生した場合は、ステータスコードの説明を参照してください。

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