Oracle Cloud Infrastructureドキュメント

非同期作業リクエスト

このトピックでは、Oracle Cloud Infrastructureサービスに対する長期実行操作の非同期作業リクエストについて説明します。 また、リクエスト・ステータスを取得し、影響を受けるリソースのフィルタリングを有効にするためのリクエスト・レスポンスを検査するためのガイダンスも提供します。

概要

Oracle Cloud InfrastructureサービスへのAPI呼び出しは、レスポンスが返される前にクライアント・リクエストを完了しない長時間実行される操作を開始できます。 このような場合、サービスにより、長時間実行の非同期操作の進行状況を可視化できる「非同期作業リクエスト」が生成されます。 REST API呼び出しへのレスポンスには、opc-work-request-idヘッダーに作業リクエストIDが含まれています。これにより、進行状況とステータスをモニターできます。 作業リクエスト自体は、操作が完了するまでキューに残ります。

GetWorkRequestを呼び出して作業リクエストIDを渡すことにより、いつでも作業リクエストのステータスをモニターできます。

ノート

Oracle Cloud Infrastructureでは、コンピュートKubernetesのコンテナ・エンジンロード・バランシングおよびオブジェクト・ストレージのサービスに対する作業リクエストがサポートされます。
これらの各サービスは、WorkRequestの詳細を取得するための独自のGetWorkRequest APIを公開しています。

リクエスト・レスポンスの2つの特徴は特殊な関心です: 作業リクエストのステータス、および作業リクエストの影響を受けるリソースのリスト。 非同期作業リクエストは、操作が完了した時点、実行中の時点、または完全に失敗したかどうかを知る必要があるため、ステータスは重要です。

作業リクエストの失敗またはエラーに関する情報を取得するために、各サービスは、エラーおよびログに関する情報を取得するためのAPIを提供します。 各サービスのAPIリファレンス・ドキュメントへのリンクについては、セクション「詳細については」を参照してください。

作業リクエスト操作がいくつかのリソースに影響を与える場合にも重要です。作業リクエストが影響を与えるリソースのリストと、entityTypeおよびactionTypeの各属性があります。

作業リクエスト・ステータス

非同期作業リクエストを使用すると、WorkRequestオブジェクトにステータス属性を提供することによって、進行状況をモニターできます。 サポートされている各サービスは、次のセクションで示すように、ステータスを取得するための独自のAPIを提供します。

ノート

forWorkRequestメソッドを使用してコールバックを作成できるContainerEngineWaitersクラスがあります。
このAPIを使用して、IN_PROGRESSからCOMPLETEDなど、操作ステータスが変更されたときに通知を転送します。

次の表に、各サービスのWorkRequestオブジェクトでサポートされているステータス属性を示します。

サービス ステータス属性
コンピュート
  • ACCEPTED
  • IN_PROGRESS
  • FAILED
  • SUCCEEDED
  • CANCELING
  • CANCELED
Container Engine for Kubernetes
  • ACCEPTED
  • IN_PROGRESS
  • FAILED
  • SUCCEEDED
  • CANCELING
  • CANCELED
ロード・バランシング
  • CREATING
  • FAILED
  • ACTIVE
  • DELETING
  • DELETED
オブジェクト・ストレージ
  • ACCEPTED
  • IN_PROGRESS
  • FAILED
  • COMPLETED
  • CANCELING
  • CANCELED

リクエスト・レスポンスのフィルタリング

特定の非同期作業リクエストの影響を受けるリソースを知る必要がある場合があります。 リクエスト・レスポンスに1つまたは2つの影響を受けるリソースが含まれている場合は、おそらくリクエスト・レスポンスの本文で十分です。 ただし、リクエスト・レスポンスが膨大な数のリソースに影響を及ぼす場合は、レスポンスをフィルタリングして、関心のあるリソースを識別する必要があります。

作業リクエスト・レスポンスにリストされたリソースのフィルタリングは、WorkRequestResourceタイプの2つの属性に依存しています: entityTypeおよびactionType

  • entityType: 作業リクエストが影響を及ぼすリソースのタイプを表します。 これはオプションの属性ですが、各リソースは1つのentityTypeのみを持つことができます。
  • actionType: 指定されたリソースが作業リクエストに関連付けられた操作によってどのように影響されるかを表します。 各サービスは、許容されるactionType 値の固定リストを指定します(以下のセクションで示されています)。

作業リクエストに関するリソース情報を取得するには、GetWorkRequestを呼び出して作業リクエストIDを渡します。 この呼び出しは、JSON形式のレスポンスを返します。 次に、「オブジェクト・ストレージ」サービスでGetWorkRequestをコールする例を示します。

{
    operationType: "COPY_OBJECT",
    status: "IN_PROGRESS",
    id: "f54527d6-029b-4221-9046-a811b7686202",
    resources: [
        {
            entityType: "object",
            actionType: "READ",
            entityUri: "/n/mynamespace/b/backups/o/myobject"
        },
        {
            entityType: "object",
            actionType: "WRITTEN",
            entityUri: "/n/mynamespace/b/backups/o/copyofmyobject"
        },
    ],
    timeAccepted: 2017-10-13T17:23:46.000Z,
    timeStarted: 2017-10-13T17:23:52.198Z,
    percentComplete: 10.0
}

ノート

異なるサービスは、わずかに異なるレスポンスを提供します。
詳細については、各サービス作業リクエストAPIのリファレンス・ドキュメントを参照してください。 それぞれへのリンクは、「詳細については」セクションに表示されます。

 

次の表に、Oracle Cloud Infrastructureサービスでサポートされるエンティティ・タイプおよびアクション・タイプを示します。

サービス名 操作 entityType actionType
Container Engine for Kubernetes

CreateCluster

DeleteCluster

UpdateCluster

CreateNodePool

DeleteNodePool

UpdateNodePool

cluster

nodepool

ACCEPTED

IN_PROGRESS

FAILED

SUCCEEDED

CANCELING

CANCELED

ロード・バランシング

CreateLoadBalancer

UpdateLoadBalancer

DeleteLoadBalancer

LoadBalancer

ACCEPTED

IN_PROGRESS

FAILED

SUCCEEDED

オブジェクト・ストレージ CopyObject object READ

WRITTEN

リクエスト/レスポンスのサンプル

次に、共通の長期実行操作である、クラスタを作成する一連のREST API呼び出しを示します。 コール元は、初期POSTコールへのレスポンスから作業リクエストIDを取得し、WorkRequestを定期的にポーリングして操作のステータスを判断します。 次のリクエスト/レスポンス・シーケンスは、このワークフローを示しています:

  1. ユーザーはCreateCluster API呼び出しを発行します。
  2. サービスは、リクエストが受け入れられたことを示すステータス・コード202で応答し、Opc-Work-Request-Idヘッダーに作業リクエストIDを返します。
  3. 次に、作業リクエストのステータスを取得するために、作業リクエストIDでGETコールを発行します。
  4. サービスは、レスポンス本文で、CLUSTER_CREATE操作のステータスがACCEPTEDであることを示すステータス・コード200で応答します。
  5. ポーリングを続けると、作業リクエストの別のGET呼び出しが表示されます。
  6. サービスはステータス・コード200で応答します。 レスポンス本文は、操作SUCCEEDEDを報告します。

ステップ1 CLUSTER_CREATE操作を開始するための初期API呼び出し。

POST https://containerengine.eu-frankfurt-1.oraclecloud.com/20180222/clusters
Accept: application/json
authorization: <Redacted>
content-length: 480
Content-Type: application/json
date: Mon, 02 Jul 2018 18:20:03 GMT
host: containerengine.eu-frankfurt-1.oraclecloud.com
opc-client-info: Oracle-JavaSDK/1.2.42-preview1-SNAPSHOT
opc-request-id: D7A390ED909C47038C438BA3629FB612
User-Agent: Oracle-JavaSDK/1.2.42-preview1-SNAPSHOT (Mac OS X/10.13.5; Java/1.8.0_172; Java HotSpot(TM) 64-Bit Server VM/25.172-b11)
x-content-sha256: S8U8OKQHyTLNViAzgexkjxvF4ctncJJHTjuRfXn0ya4={
   "name":"JavaSDK.CRUD",
   "compartmentId":"ocid1.compartment.oc1..<unique_ID>",
   "vcnId":"ocid1.vcn.oc1.eu-frankfurt-1.<unique_ID>",
   "kubernetesVersion":"v1.10.3",
   "options":{"serviceLbSubnetIds":["ocid1.subnet.oc1.eu-frankfurt-1.<unique_ID>",
   "ocid1.subnet.oc1.eu-frankfurt-1.<unique_ID>"]}}

ステップ2 Opc-Work-Request-Id headerの作業リクエストIDを含む初期API呼び出しに対するレスポンス。

202
Access-Control-Allow-Methods: DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: opc-work-request-id
Content-Length: 0
Date: Mon, 02 Jul 2018 18:20:04 GMT
Opc-Request-Id: D7A390ED909C47038C438BA3629FB612/33EEDCAAB2E84508B34AA75CD0FD86F4/8261D1CC89814E9BB934440A1F43DA09
Opc-Work-Request-Id: ocid1.clustersworkrequest.oc1.eu-frankfurt-1.exampleuniqueID
Uri: /20180222/clusters
Vary: Accept-Encoding
X-Rate-Limit-Duration: 1
X-Rate-Limit-Limit: 16.70
X-Rate-Limit-Request-Forwarded-For: 10.237.10.0, 10.237.9.51
X-Rate-Limit-Request-Remote-Addr: 10.237.9.51:53077

ステップ3 長時間実行されている操作であるため、ユーザーはGETコールを使用して作業リクエストを定期的にポーリングし、ステータスを判断します。

GET https://containerengine.eu-frankfurt-1.oraclecloud.com/20180222/workRequests/<clusters_work_request_OCID>
Accept: application/json
authorization: <Redacted>
date: Mon, 02 Jul 2018 18:20:04 GMT
host: containerengine.eu-frankfurt-1.oraclecloud.com
opc-client-info: Oracle-JavaSDK/1.2.42-preview1-SNAPSHOT
opc-request-id: E8F20DAC443346B3B0EA599F367EE294
User-Agent: Oracle-JavaSDK/1.2.42-preview1-SNAPSHOT (Mac OS X/10.13.5; Java/1.8.0_172; Java HotSpot(TM) 64-Bit Server VM/25.172-b11)

ステップ4 GET呼び出しは、レスポンス本文で、CLUSTER_CREATE操作のステータスがACCEPTEDであることを示す次のレスポンスを戻します。

200
Access-Control-Allow-Methods: DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: opc-work-request-id
Content-Length: 717
Content-Type: application/json
Date: Mon, 02 Jul 2018 18:20:05 GMT
Etag: 56a41efaf33d81a54933495ee910c24d7bce7a83adf18810f95e07bdd2055805
Opc-Request-Id: E8F20DAC443346B3B0EA599F367EE294/8B19C9FC3B4442CEA14685D1973D0856/0BA60B0711764DE4A4373071632708C7
Retry-After: 30
Uri: /20180222/workRequests/_id_
Vary: Accept-Encoding
X-Rate-Limit-Duration: 1
X-Rate-Limit-Limit: 16.70
X-Rate-Limit-Request-Forwarded-For: 10.237.10.0, 10.237.9.51
X-Rate-Limit-Request-Remote-Addr: 10.237.9.51:43533
{
  "id": "ocid1.clustersworkrequest.oc1.eu-frankfurt-1.exampleuniqueID",
  "operationType": "CLUSTER_CREATE",
  "status": "ACCEPTED",
  "compartmentId": "ocid1.compartment.oc1..exampleuniqueID",
  "resources": [
    {
      "actionType": "IN_PROGRESS",
      "entityType": "cluster",
      "identifier": "ocid1.cluster.oc1.eu-frankfurt-1.exampleuniqueID",
      "entityUri": "/clusters/ocid1.cluster.oc1.eu-frankfurt-1.exampleuniqueID"
    }
  ],
  "timeAccepted": "2018-07-02T18:20:05Z",
  "timeStarted": null,
  "timeFinished": null
}

ステップ5 操作は続行され、ユーザーはGETメソッドを使用して作業リクエストをポーリングし続けます。

GET https://containerengine.eu-frankfurt-1.oraclecloud.com/20180222/workRequests/<clusters_work_request_OCID>
Accept: application/json
authorization: <Redacted>
date: Mon, 02 Jul 2018 18:24:13 GMT
host: containerengine.eu-frankfurt-1.oraclecloud.com
opc-client-info: Oracle-JavaSDK/1.2.42-preview1-SNAPSHOT
opc-request-id: 64595B97E39A471A886DA29966BB6B1D
User-Agent: Oracle-JavaSDK/1.2.42-preview1-SNAPSHOT (Mac OS X/10.13.5; Java/1.8.0_172; Java HotSpot(TM) 64-Bit Server VM/25.172-b11)

ステップ6 最後のGET呼び出しは、操作が完了したことを示す次のレスポンスを生成しました。 entityTypeが"cluster"であり、actionTypeが"CREATED"であることに注意してください。

200
Access-Control-Allow-Methods: DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: opc-work-request-id
Content-Length: 750
Content-Type: application/json
Date: Mon, 02 Jul 2018 18:24:14 GMT
Etag: 023d2a8ccb6d893fa8c875f64652353f21d22607825f49eeeb15b5394ae24918
Opc-Request-Id: 64595B97E39A471A886DA29966BB6B1D/3A81140991C94794AF365016E31DBE82/6245FBD8C25842B6BDF15187EA6ADB21
Uri: /20180222/workRequests/_id_
Vary: Accept-Encoding
X-Rate-Limit-Duration: 1
X-Rate-Limit-Limit: 16.70
X-Rate-Limit-Request-Forwarded-For: 10.237.3.0, 10.237.40.183
X-Rate-Limit-Request-Remote-Addr: 10.237.40.183:55856

{
  "id": "ocid1.clustersworkrequest.oc1.eu-frankfurt-1.exampleuniqueID",
  "operationType": "CLUSTER_CREATE",
  "status": "SUCCEEDED",
  "compartmentId": "ocid1.compartment.oc1..exampleuniqueID",
  "resources": [
    {
      "actionType": "CREATED",
      "entityType": "cluster",
      "identifier": "ocid1.cluster.oc1.eu-frankfurt-1.exampleuniqueID",
      "entityUri": "/clusters/ocid1.cluster.oc1.eu-frankfurt-1.exampleuniqueID"
    }
  ],
  "timeAccepted": "2018-07-02T18:20:05Z",
  "timeStarted": "2018-07-02T18:20:10Z",
  "timeFinished": "2018-07-02T18:24:01Z"
}

詳細情報