ロボット実行コールバック
この記事の内容
api.example.com、console.example.com、files.example.comは説明用のアドレスです。実際の環境で指定された API、管理画面、ファイル配布先の URL に置き換えてください。
事前操作
- 管理者アカウントでDr.Roboコンソールにログインし、API設定画面でコールバックインターフェースを設定します。
- インターフェースが正常に使用できることを確認します。
- 自社のサーバー環境を確認します。ファイアウォールがある場合は、テクニカルサポートに連絡し、Dr.Roboの本番環境のIPアドレスを許可リストに追加する必要があります。
- 先にロボットを起動インターフェースを呼び出し、jobUuidを取得する必要があります。
説明1:ロボットの実行状態が終了状態(正常終了、異常終了、停止済み)になると、Dr.Roboサービスは、自社で設定したコールバックインターフェースを通じてjobの実行結果データを自動的に返します。データを速やかに取得できるように、コールバック方式で結果データを取得することをお勧めします。
説明2:自社のコールバックインターフェースが2xxステータスコードを返すと、Dr.Roboは相手側がデータを正常に受信して処理したと判断し、定期的な再送を行いません。自社側が2xx以外のステータスコードを返す場合、Dr.Roboは毎正時に1回再送し、成功するか、24回に達すると定期的な再送を終了します。jobの状態に関するコールバックを24時間以上受信していない場合は、ロボット実行結果を照会を呼び出すことをお勧めします。
コールバック連携方針
- Dr.Roboにはコールバックの再試行機能があります。ロボットの実行が終了し、コールバックが失敗すると、Dr.Roboは24時間以内に毎正時に再試行し、成功するまで繰り返します。そのため、連携先は業務処理のレベルで冪等性を保証する必要があります(startJob時にロボットと実行ロボットを指定するモードか、タスクを指定するモードかに応じて、jobUuidまたはtaskUuidを使用して冪等性を保証できます)。
- Dr.Roboでは、コールバックインターフェースに非同期方式を採用することをお勧めします。まずDr.Roboのコールバックデータを受信して成功を返し、その後で非同期処理を行います(スレッドプールに投入して非同期処理を行います)。
- コールバックデータの確実な到達を保証するには、コールバックとポーリングを併用することをお勧めします。startJobの実行後は、2分間隔で1回ポーリングすることをお勧めします(実行時間が30分の場合は2分ごとに1回、1時間の場合は4分ごとに1回とし、以降も同様に間隔を延ばします。30分未満の場合は1分間隔をお勧めします)。コールバックが成功したらポーリングを停止します。
ベストプラクティス
job/startが成功したら、jobUuidに基づいて業務テーブルa(具体的な名前は連携先が定義します)に記録します。業務テーブルにはjobUuidの一意インデックスを追加する必要があります。業務テーブルaには、少なくともjobUuid、ロボットの実行状態、有効期限を含める必要があります(期限に達した場合はデフォルトで成功とみなし、ポーリングを行いません。有効期限はjob/startの25時間後に設定することをお勧めします)。
定期タスクでこのテーブルをポーリングします。上記の間隔でポーリングし、実行状態が終了状態になった場合、または25時間が経過した場合は、ポーリングを終了することをお勧めします。
コールバックまたはポーリングで、ロボットの実行状態が終了状態であることを受信したら(ロボット実行状態の列挙値の説明を参照)、業務テーブルaの状態をコールバック成功に更新します。
実行ロボット情報の照会インターフェースをポーリングします(実行ロボットによるロボットの実行時間に応じて、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ステータスコードを受信すると、再試行と定期的な再送を停止します。
レスポンスボディ
なし
レスポンスボディの例
なし
エラーが発生した場合は、ステータスコードの説明を参照してください。