RESTタスクの処理
RESTタスクを使用すると、REST APIエンドポイントをコールして操作を実行できます。
RESTタスクでAPIエンドポイントを認証するためにOracle Cloud Infrastructureリソース・プリンシパルを使用するには、認証を参照してください。
RESTタスクの一部で説明されているように、RESTタスクを正常に起動するために満たす必要があるRESTリクエスト(HTTPメソッド、URLおよびリクエスト・ヘッダー)および完了基準(成功条件)を定義して、データ統合でRESTタスクを作成します。
RESTリクエストの送信後、データ統合は、デフォルトではコールがレスポンスを返すのを待機してから、他のタスクに進みます(同期APIモード)。REST呼出しが完了するのは、RESTリクエストのレスポンスが受信されるときです。現在、APIレスポンスでサポートされているコンテンツ・タイプはJSONです。
RESTリクエストがコールする操作が長い場合は、ポーリング条件とオプションの終了構成を指定して、REST呼出しの完了を定義します。ポーリングが構成されている場合、データ統合は、他のタスクに進む前に、RESTコールからレスポンスが返されるのを待機しません(非同期APIモード)。詳細は、長時間実行操作のポーリングおよび長時間実行操作の終了を参照してください。
RESTタスクから返されるレスポンスのサポートされる最大サイズは512Kです。これよりも大きいレスポンスは切り捨てられます。
次のページでは、RESTタスクを作成、編集および削除する方法について説明します。
次のページでは、RESTタスクの作成後に実行できるその他の管理タスクについて説明します。
RESTタスクの要素
REST APIエンドポイントを呼び出すには、RESTリクエストを実行して完了するための情報をRESTタスクに指定します。
RESTタスクの作成には、次の主なステップが含まれます:
実行詳細の定義: RESTリクエストの実行詳細(HTTPメソッド、URL、リクエスト・ヘッダーなど)を定義します。
URLは、接続先のRESTサーバーと、リクエストでアクセスするリソースの相対パスです。例:
http://myserver.com:8081/workspaces/finance1234/dataAssetsPOSTまたはPUTメソッドの場合は、リクエスト本文も指定します。現在、リクエスト本文でサポートされている形式はJSONのみです。
データ統合での実行詳細の定義は、実行時間が短いAPI操作でも実行時間が長いAPI操作でも同じです。
完了基準の指定: RESTタスクが正常に完了したと見なすために満たす必要がある、成功条件の基準を指定します。
実行ステップのRESTコールのレスポンスを使用して、trueまたはfalseに評価される条件を記述します。条件がtrueを返す場合、RESTタスクの結果は成功です。falseの場合、RESTタスクの結果は失敗です。
データ統合にはデフォルトの成功条件が用意されており、これを使用することも編集することもできます。
長時間のAPI操作の完了条件を指定するには、polling条件およびその他のポーリング値を追加する必要があります。terminationリクエストの追加はオプションです。
RESTタスクのパラメータ、およびRESTタスクでAPIエンドポイントを認証するためにOracle Cloud Infrastructureリソース・プリンシパルを使用する前に設定する必要があるものも参照してください。
長時間実行操作のポーリング
長時間実行REST API操作では、成功条件に加えて、ポーリングURLと条件およびポーリング間隔とタイムアウト値を指定して、REST呼出しの完了を識別する必要があります。
ポーリング構成は、実行ステップで呼び出されるRESTコールのステータスを定期的にポーリングするために使用されます。
ポーリングでは、成功条件は式としてポーリング・リクエストのレスポンスに書き込まれます。ポーリング・コールがポーリング条件を評価して、ポーリングを停止するか続行するかを決定します。データ統合は、指定されたポーリング間隔でポーリング・コールを繰り返し発行し、指定されたポーリング・タイムアウトの値に達するか、ポーリング条件がfalseを返すか、どちらかが先に発生するまで続けます。
ポーリング間隔は、次のポーリング・リクエストを送信するまでに待機する時間の長さです。ポーリング・タイムアウトは、指定された間隔でポーリングを繰り返すことができる最長時間。間隔値は、タイムアウト値より小さくする必要があります。
ポーリング・タイムアウトが24時間、ポーリング間隔が1時間であるとします。実行ステップでRESTリクエストが呼び出された後、ポーリングRESTリクエストが1時間間隔で送信されますが、最大で24時間間、またはポーリング条件がfalseを返すまでです。
成功条件に指定された基準が満たされた場合、RESTコールは正常に完了し、RESTタスク実行が成功と見なされます。成功条件がfalseを返すと、RESTタスク実行の結果は失敗と見なされます。
たとえば、ポーリング構成が、レスポンスのステータスを評価してタスク実行の進行状況をポーリングするとします:
cast(json_path(SYS.RESPONSE_PAYLOAD_JSON, '$.status') as String) != 'SUCCESS' or cast(json_path(SYS.RESPONSE_PAYLOAD_JSON, '$.status') as String) != 'ERROR'成功条件が満たされると、ポーリングが停止します。
cast(json_path(SYS.RESPONSE_PAYLOAD_JSON, '$.status') as String) == 'SUCCESS'長時間実行操作の終了
RESTコールを終了するためのHTTPメソッドとREST URLの構成は、長時間実行API操作ではオプションです。
データ統合でのREST終了リクエストの詳細の定義は、実行ステップでのRESTリクエストの定義と似ています。ただし、REST実行ステップからのAPIレスポンスを使用する式を終了URLに含めることができます。
ユーザーがRESTタスク実行を終了するとき、終了構成がそのRESTタスクに指定されていない場合、データ統合は:
- RESTタスク実行を停止します
- RESTタスクによって呼び出された基礎となるAPI操作は停止しません
終了構成が指定されている場合、データ統合は、RESTタスク実行と基礎となるAPI操作を停止します。
認証
RESTタスクでREST APIエンドポイントを呼び出すための認証を指定します。
現在、Oracle Cloud Infrastructure APIエンドポイントを認証する方式としてOracle Cloud Infrastructureリソース・プリンシパルを使用できます。ワークスペースまたはアプリケーションのリソース・プリンシパルを使用できます。
リソース・プリンシパル認証
Oracle Cloud Infrastructureリソース・プリンシパルは、RESTタスクでOracle Cloud Infrastructure APIエンドポイントを実行するための認証方法として指定できます。
リソース・プリンシパルを使用して、リソースがプリンシパル・アクターとして認可され、サービス・リソースに対してアクションを実行できるようになります。Oracle Cloud Infrastructureリソース・プリンシパル認証メソッドは、認証のための一時的なリソース・プロバイダ・セッション・トークン(RPST)です。認可は、アイデンティティ・ドメインを持つOracle Cloud Infrastructure Identity and Access Management (IAM)のポリシーを介して確立されます。
IAMでは、動的グループの一部であるリソース・プリンシパルのポリシーを記述できます。OCIリソース・プリンシパルを使用してRESTタスクでOCI APIエンドポイントを認証する前に、動的グループを作成し、データ統合ワークスペースまたはアプリケーション、およびネットワーク・リソースに対する権限を付与します。
次に、使用できるポリシーの例を示します。
-
動的グループに属するリソースを定義するために、動的グループに次の照合ルールを作成します:
ALL{resource.type = 'disworkspace', resource.compartment.id = <compartment-ocid>} -
動的グループがネットワーク・リソースにアクセスできるように、次のポリシー・ステートメントを追加します。
allow dynamic-group <dynamic-group-name> to use virtual-network-family in tenancy -
Oracle Cloud Infrastructureアプリケーション・リソース・プリンシパルを使用して、RESTタスクでAPIエンドポイントを認証するには:
allow any-user to use ai-service-language-family in tenancy where ALL {request.principal.type = 'disapplication', request.principal.id = '<disapplication-ocid>'}
-
このトピックで説明するポリシー・ステートメントは例にすぎません。独自の要件を満たすポリシーを作成してください。
-
IAMコンポーネント(動的グループやポリシー・ステートメントなど)を追加した後は、関連付けられたタスクをすぐに実行しないでください。新しいIAMポリシーを有効にするには、約5分から10分かかります。
パラメータ
RESTタスクにパラメータを含めることができるため、様々なランタイム状況でタスクを再利用できます。
RESTタスクでRESTリクエストの次の部分にパラメータを使用できます:
- RESTの実行URL、ポーリングURLまたは終了URLの1つ以上のセクション。データ統合では、URLのパラメータ化された変数セクションはURLパラメータと呼ばれます。「HTTPメソッド、URLおよびURLパラメータの構成」を参照してください。
- リクエストのヘッダーの値。ヘッダー値のパラメータ化を参照してください。
- POSTまたはPUTリクエストのリクエスト本文全体。リクエスト本文のパラメータ化を参照してください。
- RESTコールの正常完了の基準を決定する成功条件。成功条件のパラメータ化を参照してください。
- ポーリングを停止するか続行するかを決定するポーリング条件(ポーリング・リクエストから返されるレスポンスに対して記述される)。ポーリング条件のパラメータ化を参照してください。