タスク実行コールバック

この記事の内容
  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回に達すると定期的な再送を終了します。タスクの状態について24時間を超えてもコールバックを受信できない場合は、次のインターフェースの呼び出しを推奨します:タスク実行結果の照会。

コールバック連携方針

  1. Dr.Roboにはコールバックの再試行機能があります。ロボットの実行が終了し、コールバックに失敗すると、連続して3回再試行します。また、Dr.Roboは24時間以内、再試行が成功するまで1時間ごとに再試行します。そのため、連携先では業務ロジックのレベルで冪等性を保証する必要があります(taskUuidに基づいて冪等性を保証できます)。
  2. Dr.Roboでは、コールバックインターフェースに非同期処理を採用することを推奨しています。まずDr.Roboのコールバックデータを受信して成功を返し、その後に非同期処理を行います(スレッドプールに投入して非同期処理を行います)。
  3. コールバックデータの確実な到達を保証するには、コールバックとポーリングの併用を推奨します。task/startを呼び出した後は、30秒間隔で1回ポーリングすることを推奨します(30分では30秒に1回、1時間では1分に1回というように、順次間隔を延ばします)。コールバックが成功したら、ポーリングを停止します。

ベストプラクティス

  1. startTaskが成功したら、taskUuidに基づいて業務テーブルa(具体的な名前は連携先で定義します)に記録します。業務テーブルにはtaskUuidの一意インデックスを追加する必要があります。業務テーブルaには、少なくともtaskUuid(冪等性を保証するフィールド)、実行状態の最終状態(参照:タスク実行状態の列挙値の説明)、有効期限(期限に達したらデフォルトで成功とみなし、ポーリングを行いません。有効期限はtask/startの25時間後を推奨します)を含める必要があります。
  2. 定期タスクでこのテーブルをポーリングします。上記の時間間隔でポーリングし、実行状態が最終状態になった場合、または25時間が経過した場合は、ポーリングを終了することを推奨します。
  3. コールバックまたはポーリングでタスクの実行状態が最終状態であることを受信したら(参照:タスク実行状態の列挙値の説明)、業務テーブルaの状態をコールバック成功に更新します。
  4. ロボットクライアント情報の照会インターフェースをポーリングします(ロボットクライアントでのロボットの実行時間に応じて、30秒に1回のポーリングを推奨します)。ロボットクライアントがアイドル状態になったら、task/startインターフェースを呼び出せます。ロボットクライアントが多数ある場合は、すべてを同時にポーリングせず、タイミングをずらしてポーリングすることを推奨します。

例:ロボットクライアントが100台ある場合は、100回に分けてポーリングすることを推奨します。各ロボットクライアントへのポーリングを1秒間隔で開始し、タイミングを分散させます。

テンプレート

postManテンプレート

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

Javaテンプレート

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

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

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

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

リクエスト

なし

リクエストヘッダー

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

リクエストボディ

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

コールバックの例

{
  "dataType": "task", //データタイプです。jobはロボット実行のコールバック(APIでロボットのrobotUuidを指定して呼び出す方法)、taskはタスク実行のコールバック(APIでタスクのscheduleUuidを指定して呼び出す方法)を示します。
  "startTime": 1,//空にできます。最初のロボットの実行開始日時です。
  "endTime": 1642837962000, //最後のロボットの実行終了日時です。
  "jobList": [
    {
      "dataType": "job",
      "jobUuid": "6de893bb-8224-4f60-9bff-b8597b8ed8fc",
      "msg": "",
      "robotClientUuid": "cfcc5904-2e82-4295-911c-0ce65c9099f2",
      "robotClientName": "ceshi1@csqy1", //ロボットクライアントの名称です。
      "startTime":"2021-02-03 11:11:11", //このロボットの実行開始日時です。
      "endTime": "2021-03-03 12:12:12", //このロボットの実行終了日時です。
      "robotName": "注文一覧を出力", //ロボットの名称です。
      "robotUuid": "xxxxx", //ロボットのuuidです。
      "status": "finish",
      "idempotentUuid":"xxxx", //冪等性を保証するidです。
      "screenshotUrl":"xxxx", //異常時のスクリーンショットです。
      "result": [ //出力パラメータがあります。
                {
                    "name": "姓",
                    "value": "王",
                    "type": "str"  //ロボット実行パラメータの列挙値の説明を参照してください。
                },
                {
                    "name": "名",
                    "value": "5",
                    "type": "str"  //ロボット実行パラメータの列挙値の説明を参照してください。
                },
                {
                    "name": "上传文件",
                    "value": "https://files.example.com/document/temp/request.txt",
                    "type": "file"  //ロボット実行パラメータの列挙値の説明を参照してください。
                }
            ]
    }
  ],
  "msg": "运行结束", //タスク実行の備考です。
  "status": "finish", // タスクの実行状態です。
  "taskUuid": "ea947f83-82fb-4afb-8412-4021255fd7cd"
}

レスポンス

2xxのHTTPステータスコードを返せば十分です。200を推奨します。Dr.Roboは2xxのステータスコードを受信すると、再試行および定期的な再送を行いません。

レスポンスボディ

なし

レスポンスボディの例

なし

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

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