Oracle Cloud Infrastructureドキュメント

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

長時間実行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タスク出力として使用できないことに注意してください。

式を追加するには:

  1. 「REST API詳細の構成」ページの「完了基準の指定」ステップで、「待機なしRESTコールのポーリングおよび終了条件を構成します」チェック・ボックスを選択します。
  2. 「式」セクションを展開し、「式の追加」をクリックします。
  3. 「式の追加」パネルの「式情報」セクションで、次を行います:
    1. 式の名前を「識別子」フィールドに入力します。
    2. 「データ型」メニューから、この式の型を選択します。
    3. 選択したデータ型のプロパティ・フィールドに入力します。たとえば、STRINGデータ型の「長さ」に入力します。
  4. 「式ビルダー」セクションでは、視覚的に式を構築できます。受信レスポンス出力、パラメータまたは関数をダブルクリックまたはドラッグしてエディタに追加します。または、式を自ら手動で記述できます。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)
  5. 「追加」をクリックします。
ポーリングの式の編集または削除

ポーリングに作成した式を編集および削除できます。

式を編集または削除するには:

  1. 「REST API詳細の構成」ページの「完了基準の指定」ステップで、「式」セクションを展開します。
  2. 「式」表で、編集または削除する式を見つけます。
  3. 式のアクション・メニュー(アクション・メニュー)から、「編集」または「削除」を選択します。
    • 「式の編集」パネルで変更を行い、「保存」をクリックします。
    • 「式の削除」ダイアログ・ボックスで、名前付きの式が削除する式であることを確認し、「削除」をクリックします。
ポーリングHTTPメソッドおよびURLの構成

長時間実行API操作で、RESTコールのステータスをポーリングするHTTPメソッドおよびURLを定義します。

実行ステップのREST URLと同様に、構文${parameter_name}を使用してポーリングURLにパラメータを含めることができます。

また、構文#{expression_name}を使用して名前付きの式を含めることができます。ポーリングURLを構成する前に必要な式を作成します。

ポーリング・メソッドおよびURLを構成するには:

  1. 「REST API詳細の構成」ページの「完了基準の指定」ステップで、「待機なしRESTコールのポーリングおよび終了条件を構成します」チェック・ボックスを選択します。
  2. 「ポーリング」タブで、ポーリングURLに使用するHTTPメソッドを選択します。
  3. 「URL」フィールドに完全なURLを入力し、[Enter]を押します。

    URLの一部に${}パラメータ構文を使用すると、それらの部分はRESTタスクのURLパラメータに変換されます。

    「URLパラメータ」タブの「URL」フィールドの下にある表が、パラメータ化された部分を含むように更新されます。各URLパラメータのデフォルトのデータ型はStringです。

    パラメータ構文を追加または削除してURLを編集すると、いつでもそれに応じてURLパラメータ表が更新されます。

  4. パラメータにデフォルト値を割り当てるには、URLパラメータの構成を参照してください。
  5. 構成したパラメータのデフォルト値を使用するポーリングURLを表示または非表示にするには、「プレビューURLの表示」または「プレビューURLの非表示」をクリックします。
  6. ヘッダーを追加するには、「ヘッダーの追加および管理」を参照してください。
  7. リクエスト本文が必要な場合は、リクエスト本文の指定を参照してください。
ポーリング条件の指定

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

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

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

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

  1. 「REST API詳細の構成」ページの「完了基準の指定」ステップで、「待機なしRESTコールのポーリングおよび終了条件を構成します」チェック・ボックスを選択します。
  2. 「ポーリング」タブの「条件」セクションで、次を行います:
    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'

  3. 「Conditions」セクションの「Polling condition」の下に値を入力し、「Polling interval」および「Polling timeout」の単位を選択します。
    • ポーリング・タイムアウト: 指定された間隔でポーリングを繰り返すことができる最長時間。タイムアウト値は、120秒以上、30日以下にする必要があります。
    • ポーリング間隔: 次のポーリング・リクエストを送信するまでに待機する時間の長さです。間隔値は、60秒以上で、指定したタイムアウト値未満にする必要があります。
  4. タスク・パラメータを条件に割り当てるには、「パラメータの割当て」をクリックします。ポーリング条件のパラメータ化を参照してください。
ポーリング条件のパラメータ化

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

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

  1. 「REST API詳細の構成」ページで、「完了基準の指定」ステップに移動します。
  2. 「条件」ブロックで、「ポーリング条件」の横にある「パラメータの割当て」をクリックします。
  3. 「パラメータの追加」パネルで、「識別子」フィールドにパラメータの名前を入力するか、デフォルト値を使用します。

    パラメータ名はRESTタスク内で一意である必要があります。タスク内のパラメータの現在のリストを確認する方法は、RESTタスク内のすべてのパラメータの表示を参照してください。

  4. (オプション)他のユーザーにパラメータの目的がわかるように、説明を入力します。
  5. パラメータの「タイプ」は「式」です。変更することはできません。
  6. 条件ビルダーで、このパラメータのデフォルトの条件式を設定します。このデフォルトの条件は、後で(設計時または実行時に)値を変更しないかぎり、実行時に使用されます。

    条件式には、次の要素を含めることができます。

    • 受信: 受信レスポンス出力(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'

  7. 「追加」をクリックします。
    パラメータ名がポーリング条件の横に追加されます。
ポーリング条件パラメータの編集

ポーリング条件のタスク・パラメータの説明およびデフォルト値を変更できます。

パラメータ化されたポーリング条件を編集するには:

  1. 「REST API詳細の構成」ページで、「完了基準の指定」ステップに移動します。
  2. 「条件」ブロックで、「パラメータの編集」をクリックします。
  3. 「パラメータの編集」パネルで、ポーリング条件の説明と式のみを編集できます。識別子(名前)およびデータ型は変更できません。
  4. 「変更の保存」をクリックします。
ポーリング条件パラメータの削除

条件パラメータを削除すると、RESTタスクに指定されたポーリング条件とパラメータとの関連付けのみが削除されます。

ポーリング条件からパラメータの割当てを解除するには:

  1. 「REST API詳細の構成」ページで、「完了基準の指定」ステップに移動します。
  2. 「条件」ブロックで、「パラメータの削除」をクリックします。
  3. 「パラメータの削除」ダイアログ・ボックスで、「削除」をクリックします。

    ポーリング条件からパラメータの割当てが解除されます。パラメータに割り当てられていた条件式が、RESTタスクのデフォルトのポーリング条件になります。

    ノート

    パラメータはRESTタスクから削除されません。パラメータを削除するには、RESTタスク・パラメータの削除を参照してください。
終了HTTPメソッドおよびURLの構成

長時間実行REST API操作を呼び出すRESTタスクについては、長時間実行操作を終了するためのREST APIの詳細を指定できます。

「終了」タブで、HTTPメソッドとRESTコールを終了するURLを定義します。

ポーリングURLと同様に、終了URLにも構文${parameter_name}および#{expression_name}を使用してパラメータと式を含めることができます。終了URLを構成する前に必要な式を作成します。

終了メソッドおよびURLを構成するには:

  1. 「REST API詳細の構成」ページの「完了基準の指定」ステップで、「待機なしRESTコールのポーリングおよび終了条件を構成します」チェック・ボックスを選択します。
  2. 「終了」タブで、終了URLに使用するHTTPメソッドを選択します。
  3. 「URL」フィールドに完全なURLを入力し、[Enter]を押します。

    URLの一部に${}パラメータ構文を使用すると、それらの部分はRESTタスクのURLパラメータに変換されます。

    「URLパラメータ」タブの「URL」フィールドの下にある表が、パラメータ化された部分を含むように更新されます。各URLパラメータのデフォルトのデータ型はStringです。

    パラメータ構文を追加または削除してURLを編集すると、いつでもそれに応じてURLパラメータ表が更新されます。

  4. パラメータにデフォルト値を割り当てるには、URLパラメータの構成を参照してください。
  5. 構成したパラメータのデフォルト値を使用するURLを表示または非表示にするには、「プレビューURLの表示」または「プレビューURLの非表示」をクリックします。
  6. ヘッダーを追加するには、「ヘッダーの追加および管理」を参照してください。
  7. リクエスト本文が必要な場合は、リクエスト本文の指定を参照してください。
完了基準(成功条件)の指定

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

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

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

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

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

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

  1. 「REST API詳細の構成」ページで、「完了基準の指定」ステップに移動します。
  2. REST APIが長時間実行操作を起動する場合は、「待機なしRESTコールのポーリングおよび終了条件を構成します」チェック・ボックスを選択します。
  3. 「条件」ブロックで、「成功条件」の横にある「編集」をクリックします。
  4. 「成功条件の編集」パネルで、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レスポンスを使用する式を作成し、その後、名前を付けた式を組み込んで成功条件を作成できます。

  5. タスク・パラメータを成功条件に割り当てるには、「パラメータの割当て」をクリックします。成功条件のパラメータ化を参照してください。