ポーリングを使用した完了基準の指定

長時間実行REST API操作を呼び出すRESTタスクの場合、「完了基準の指定」ステップで、「待機なしRESTコールのポーリングおよび終了条件を構成します」チェック・ボックスを選択して、REST呼出しの完了を識別するためのポーリング構成を指定します。

成功条件に加え、ポーリング構成には、ポーリングのREST URLと条件、およびポーリング間隔とポーリング・タイムアウトの値が含まれます。

オプションで、長時間実行API操作を取り消すための終了構成を指定できます。

実行ステップのAPIレスポンスをポーリング構成または終了構成で使用するには、式を作成し、ポーリングURLおよび終了URLに、名前を付けた式とポーリング条件および成功条件を含めます。

ポーリングまたは終了を構成する前に、必要なAPIレスポンス値をフェッチするための式を作成します。

長時間実行操作のポーリングも参照してください。

ポーリングで使用する式の追加

式を使用すると、完了基準のステップを構成する際に使用できる変数に値または式を割り当てることができます。

REST実行ステップのAPIレスポンスを使用する式を作成します。これを作成するときに式の名前を指定します。ポーリングURLか終了URLまたはポーリング条件か成功条件に名前付き式を含めるには、構文#{expression_name}を使用します。

たとえば、RESTタスクが呼び出すAPI操作が特定のプロジェクト名を使用してプロジェクトを作成する場合、ポーリング・リクエストでプロジェクト・キーをチェックして、ポーリングを続行するか停止するかを決定できます。ポーリングURLでプロジェクト・キーを変数として使用するには、APIペイロード・レスポンスからキーを抽出してデータ型文字列またはJSON_TEXTの値に変換する式を作成します。

ここで作成する式は、タスクからのダウンストリームである他の演算子でRESTタスク出力として使用できないことに注意してください。

式を追加するには:

「REST API詳細の構成」ページの「完了基準の指定」ステップで、「待機なしRESTコールのポーリングおよび終了条件を構成します」チェック・ボックスを選択します。
「Expressions」セクションを展開し、「Add expression」をクリックします。
「式の追加」パネルの「式情報セクションで、次を行います:
1. 式の名前を入力します。
2. 「データ型」メニューから、この式の型を選択します。
3. 選択したデータ型のプロパティ・フィールドに入力します。たとえば、STRINGデータ型の「長さ」に入力します。
「式ビルダー」セクションでは、受信レスポンス出力、パラメータまたは関数をダブルクリックまたはドラッグしてエディタに追加することで、視覚的に式を作成できます。または、式を自ら手動で記述できます。RESTリクエストのレスポンスの出力を使用する式を作成します。
- 受信: システム出力SYS.RESPONSE_PAYLOAD_JSON、SYS.RESPONSE_HEADERS_JSONおよびSYS.RESPONSE_STATUSを使用できます。
- パラメータ: このRESTタスクのスコープに定義されている任意のパラメータを使用できます。RESTタスクのパラメータの表示および管理を参照してください。
- 関数: データ統合の基本的な文字列関数と演算子関数を使用できます。
式を作成する際にすべての関数がサポートされるわけではありません。こちらのサポート対象リストを参照してください。

APIレスポンス本文からJSONプロパティ値を抽出するには、受信したレスポンス出力SYS.RESPONSE_PAYLOADに対して文字列関数json_pathを使用します。例:
```
CAST(json_path(SYS.RESPONSE_PAYLOAD_JSON, '$.key') AS String)
```
```
CAST(json_path(SYS.RESPONSE_PAYLOAD_JSON, '$.emp.ID') AS JSON_TEXT)
```
「追加」をクリックします

ポーリングの式の編集または削除

ポーリングHTTPメソッドおよびURLの構成

ポーリング条件の指定

ポーリング構成には、ポーリング条件およびポーリング間隔とポーリング・タイムアウトの値が含まれます。

ポーリング条件は、ポーリングを停止するか続行するかを決定する式です。式がfalseを返すと、ポーリングは停止します。

データ統合は、指定されたポーリング間隔でポーリング・コールを繰り返し発行し、指定されたポーリング・タイムアウトの値に達するか、ポーリング条件がfalseを返すか、どちらかが先に発生するまで続けます。

ポーリング条件を構成するには:

「REST API詳細の構成」ページの「完了基準の指定」ステップで、「待機なしRESTコールのポーリングおよび終了条件を構成します」チェック・ボックスを選択します。
「ポーリング」タブの「条件」セクションで、次を行います:
1. 「ポーリング条件」の横にある「作成」をクリックします。
2. 「ポーリング条件の作成」パネルで、RESTリクエストからの出力を使用する式を入力します。
  条件式には次の要素を含めることができます。
  - 受信: 受信レスポンス出力(SYS.RESPONSE_PAYLOAD_JSON、SYS.RESPONSE_HEADERS_JSON、SYS.RESPONSE_STATUSなど)。
  - パラメータ: このRESTタスクの範囲で定義されているパラメータ。RESTタスクのパラメータの表示および管理を参照してください。
  - 関数: 基本文字列および演算子データ統合関数。文字列に含まれるjson_path関数を使用すると、JSONPath構文要素を使用して、json_path(json_string, json_filter_path)の形式でプロパティ値をレスポンスから抽出できます。
  例: CAST(json_path(SYS.RESPONSE_PAYLOAD, '$.name') AS String) != 'My_Project'
「Conditions」セクションの「Polling condition」の下に値を入力し、「Polling interval」および「Polling timeout」の単位を選択します。
- ポーリング・タイムアウト: 指定した間隔でポーリングを繰り返すことができる最長時間。タイムアウト値は、120秒以上、30日以下にする必要があります。
- ポーリング間隔: 次のポーリング・リクエストを送信する待機時間の長さです。間隔値は、60秒以上で、指定したタイムアウト値未満にする必要があります。
タスク・パラメータを条件に割り当てるには、「パラメータの割当て」をクリックします。ポーリング条件のパラメータ化を参照してください。

ポーリング条件のパラメータ化

ポーリング条件を追加した後、タスク・パラメータを条件に割り当てることができます。

RESTタスクのポーリング条件をパラメータ化するには:

「REST API詳細の構成」ページで、「完了基準の指定」ステップに移動します。
「Conditions」ブロックで、「Polling condition」の横にある「Assign parameter」をクリックします。
「パラメータの追加」パネルで、「識別子」フィールドにパラメータの名前を入力します。または、デフォルト値を使用します。

パラメータ名はRESTタスク内で一意である必要があります。タスク内のパラメータの現在のリストを確認する方法は、RESTタスク内のすべてのパラメータの表示を参照してください。
(オプション)他のユーザーにパラメータの目的がわかるように、説明を入力します。
パラメータの「タイプ」は「式」です。変更することはできません。
条件ビルダーで、このパラメータのデフォルトの条件式を設定します。このデフォルトの条件は、後で(設計時または実行時に)値を変更しないかぎり、実行時に使用されます。
条件式には次の要素を含めることができます。
- 受信: 受信レスポンス出力(SYS.RESPONSE_PAYLOAD_JSON、SYS.RESPONSE_HEADERS_JSON、SYS.RESPONSE_STATUSなど)。
- パラメータ: このRESTタスクの範囲で定義されているパラメータ。RESTタスクのパラメータの表示および管理を参照してください。
- 関数: 基本文字列および演算子データ統合関数。文字列に含まれるjson_path関数を使用すると、JSONPath構文要素を使用して、json_path(json_string, json_filter_path)の形式でプロパティ値をレスポンスから抽出できます。
例: CAST(json_path(SYS.RESPONSE_PAYLOAD, '$.name') AS String) != 'My_Project'
「追加」をクリックします
パラメータ名がポーリング条件の横に追加されます。

RESTタスクの成功条件は、REST APIコールの正常完了を決定する式です。成功条件が満たされるとポーリングが停止します。

デフォルトでは、データ統合によってRESTタスクの成功条件が提供されます。デフォルトの成功条件は、200以上300未満のHTTPステータス・コードです。次の式で記述されます:

SYS.RESPONSE_STATUS >= 200 AND SYS.RESPONSE_STATUS < 300

成功条件の式は、実行ステップで定義されたRESTリクエストから受信したJSONレスポンスの出力を参照します。

デフォルトの成功条件を使用できます。または、システム出力またはレスポンスから抽出されたJSONプロパティ値を使用して条件式を記述できます。

成功条件を編集するには:

「REST API詳細の構成」ページで、「完了基準の指定」ステップに移動します。
REST APIが長時間実行操作を起動する場合は、「待機なしRESTコールのポーリングおよび終了条件を構成します」チェック・ボックスを選択します。
「Conditions」ブロックで、「Success」条件の横にある「Edit」をクリックします。
「成功条件の編集」パネルで、RESTリクエストのレスポンスの出力を使用する式を入力します。

条件式には次の要素を含めることができます。
- 受信: 受信レスポンス出力(SYS.RESPONSE_PAYLOAD_JSON、SYS.RESPONSE_HEADERS_JSON、SYS.RESPONSE_STATUSなど)を使用できます。
- パラメータ: このRESTタスクのスコープに定義されている任意のパラメータを使用できます。RESTタスクのパラメータの表示および管理を参照してください。
- 関数: データ統合の基本的な文字列関数と演算子関数を使用できます。文字列に含まれるjson_path関数を使用すると、JSONPath構文要素を使用して、json_path(json_string, json_filter_path)の形式でプロパティ値をレスポンスから抽出できます。
  
  例: json_path(SYS.RESPONSE_PAYLOAD, '$.@STATUS')
成功条件式ではすべての関数がサポートされるわけではありません。こちらのサポート対象リストを参照してください。

(長時間操作の場合)「非待機RESTコールのポーリングおよび終了条件を構成します」チェック・ボックスを選択した場合、ポーリング・リクエストのレスポンスに書き込まれる式が成功条件になります。実行ステップのAPIレスポンスを使用する式を作成し、その後、名前を付けた式を組み込んで成功条件を作成できます。
タスク・パラメータを成功条件に割り当てるには、「パラメータの割当て」をクリックします。成功条件のパラメータ化を参照してください。

Oracle Cloud Infrastructureドキュメント

ポーリングを使用した完了基準の指定