作業リクエスト

このトピックでは、作業リクエストAPIに記載されている作業リクエスト機能について説明します。

ノート

一部のOracle Cloud Infrastructureサービスには、このトピックで説明する作業リクエストAPIではなく、サービスAPIでサポートされている作業リクエストが用意されています。これらのサービスの作業リクエストの詳細は、次のリストを参照してください。

独自の作業リクエストAPIがあるサービス

作業リクエストの開始

作業リクエストを使用すると、データベース・バックアップやコンピュート・インスタンスのプロビジョニングなど、長時間実行されている操作をモニターできます。このような操作を開始すると、サービスは作業リクエストを生成します。作業リクエストは、操作の進行状況の各ステップをトラッキングできるアクティビティ・ログです。各作業リクエストには、プログラムで操作して自動化に使用できるOCIDがあります。

作業リクエストは次のようなシナリオで役立ちます:

  • 操作が失敗した場合、作業リクエストは、プロセスのどのステップにエラーがあったかの判断に役立ちます。作業リクエストでは、非同期検証の失敗が取得されます。
  • 一部の操作は複数のリソースに影響を与えます。たとえば、インスタンス・プールの作成は、インスタンスとインスタンス構成にも影響します。作業リクエストによって、操作が影響するリソースのリストが提供されます。
  • 順次操作を必要とするワークフローの場合は、各操作の作業リクエストをモニターして、次の操作に進む前に操作が完了していることを確認できます。たとえば、自動スケーリングが有効なインスタンス・プールを作成するとします。これを行うには、まずインスタンス・プールを作成し、その後、自動スケーリングを構成する必要があります。インスタンス・プールを作成する作業リクエストをモニターして、ワークフローが完了するタイミングを判断し、完了後に自動スケーリングを構成できます。

作業リクエストは12時間保持されます。

必要なIAMポリシー

Oracle Cloud Infrastructureを使用するには、管理者によってポリシーでセキュリティ・アクセス権が付与されている必要があります。このアクセス権は、コンソール、あるいはSDK、CLIまたはその他のツールを使用したREST APIのいずれを使用している場合でも必要です。権限がない、または認可されていないというメッセージが表示された場合は、自分がどのタイプのアクセス権を持っているか、およびどのコンパートメントで作業するかを管理者に確認してください。

管理者の場合: 作業リクエストは、作業リクエストを生成する操作の権限を継承します。操作の作業リクエスト、ログおよびエラー・メッセージをユーザーが表示できるようにするには、操作を実行する権限をユーザーに付与するポリシーを記述します。たとえば、起動中のインスタンスに関連付けられている作業リクエストをユーザーが表示できるようにするには、ユーザーがインスタンスを起動できるようにするポリシーを記述します。

ユーザーがテナンシのすべての作業リクエストをリストできるようにするには、次のポリシーを使用します:

Allow group SupportTeam to inspect work-requests in tenancy

ポリシーを初めて使用する場合は、ポリシーの開始共通ポリシーを参照してください。

作業リクエストの状態

ノート: 一部のサービスまたは操作に対する作業リクエストでは、次のステータスのサブセットのみがサポートされます。

ACCEPTED
リクエストは処理対象の作業リクエスト・キューにあります。
IN_PROGRESS
指定したリクエストには作業リクエスト・レコードが存在しますが、関連するWORK_COMPLETEDレコードがありません。
SUCCEEDED
このリクエストには作業リクエスト・レコードが存在し、関連するWORK_COMPLETEDレコードの状態は「成功」です。
FAILED
このリクエストには作業リクエスト・レコードが存在し、関連するWORK_COMPLETEDレコードの状態は「失敗」です。
CANCELING
作業リクエストは、取消しの処理中です。
CANCELED
作業リクエストは取り消されました。

検証エラーのトラブルシューティング

操作が失敗した場合、作業リクエストは、プロセスのどこでエラーが発生したかの特定に役立ちます。作業リクエストでは、非同期検証の失敗が取得されます。同期エラーは、サービスAPIへの最初のコールで発生し、サービスAPIによって返されます。非同期エラーは、最初のAPIコールの後に実行されるワークフローで発生します。HTTP 200レスポンスを返すサービスAPIへの正常なコールの後に、作業リクエストAPIによって取得された非同期エラーが発生する場合があります。

たとえば、コンピュート・インスタンスを作成すると、コンピュートAPIに対してAPIコールが作成されます。この時点で、同期検証が実行されます。コールが成功すると、HTTP 200レスポンスがユーザーに返されます。失敗すると、HTTP 4xxレスポンスが返されます。REST APIコールに対するレスポンスでは、opc-work-request-idヘッダーに作業リクエストのOCIDが含まれます。OCIDは作業リクエストIDで、作業リクエストAPIから、関連するワークフローのステータスやエラー情報、ログ・ファイルを取得するのに使用できます。

インスタンスの作成ワークフローの続行中に、非同期作業リクエストが生成され、追加の検証とエラー・チェックが実行されます。非同期作業リクエストにより、長時間実行されている非同期操作の進捗状況を確認できるようになります。作業リクエスト自体は、操作が完了するまでキューに残ります。

作業リクエストのステータスは、作業リクエストAPIGetWorkRequestをコールし、opc-work-request-idヘッダーにある作業リクエストIDを渡すことで、いつでもモニターできます。ワークフロー中にエラーが発生した場合は、作業リクエストAPIでListWorkRequestErrorsをコールし、作業リクエストIDを渡してエラーのリストを取得できます。

リクエスト・レスポンス、およびサンプル・リクエストとレスポンスをフィルタする方法など、非同期作業リクエストの詳細は、非同期作業リクエストを参照してください。

作業リクエスト検証ワークフローの例

次の図は、同期検証が成功し、非同期検証が失敗したインスタンスの作成ワークフローの例を示しています。

  1. コンピュートAPIでLaunchInstanceエンドポイントをコールします。
  2. 同期検証が実行され、コンピュートAPIからHTTP 2xxレスポンスを受信しますが、これにはopc-work-request-idヘッダーにある作業リクエストのOCIDが含まれています。
  3. インスタンス作成ワークフローが開始されると、ワークフロー全体で非同期検証が行われます。エラーが発生すると、検証が失敗します。
  4. コンピュートAPIにより作業リクエスト・エラーが移入され、作業リクエストが失敗とマークされます。
  5. 作業リクエストをモニターするには、作業リクエストAPIでGetWorkRequestをコールし、opc-work-request-idヘッダーにある作業リクエストIDを渡します。
  6. 作業リクエストが失敗したら、作業リクエストAPIでListWorkRequestErrorsをコールし、作業リクエストIDを渡してエラーのリストを取得します。
  7. 作業リクエストAPIは、失敗原因の特定に使用できるエラーのリストを返します。
同期検証と非同期検証を示すインスタンス作成ワークフローの概要。

コンソールを使用した作業リクエストの表示

コンソールを使用して、特定の作業リクエストに関連付けられているログ・メッセージ、エラー・メッセージおよびリソースを表示できます。作業リクエストを表示するステップは、作業リクエストをサポートするOracle Cloud Infrastructureサービスの場合と同様です。

  1. 作業リクエストの表示対象のリソースに移動します。

    For example, to see the work requests for a compute instance: Open the navigation menu and click Compute. Under Compute, click Instances.

  2. リソースがリスト・ビューに表示される場合は、リソース名をクリックしてリソースの詳細を表示します。
  3. 「リソース」で、「作業リクエスト」をクリックします。すべての作業リクエストのステータスがこのページに表示されます。
  4. 特定の作業リクエストに関連付けられているログ・メッセージ、エラー・メッセージおよびリソースを表示するには、操作名をクリックします。次に、「詳細」セクションでオプションを選択します。

    関連付けられているリソースについて、リソースのOCIDをコピーするリソースの横にある「アクション」メニューをクリックします。