非同期呼び出しの概要

同期呼び出し

デフォルトでは、クラウド API に対する呼び出しは、同期呼び出しです。呼び出し元アプリケーションは、要求を送信し、応答を待機します。これについては、次の図で説明します。


同期呼び出しのフロー

  1. 呼び出し元アプリケーションは、クラウド API に要求を送信します。この図では、要求は someResource という名前のリソースの POST です。要求には、一連の要求ヘッダーがあり、ペイロードが含まれる場合もあります。
  2. クラウド API は要求を同期処理します。
  3. 要求が成功した場合、クラウド API は応答を生成します。応答には、一連の応答ヘッダーも含まれており、ペイロードが含まれる場合もあります。

非同期呼び出し

一部の呼び出しでは、同期応答の待機が問題になる可能性があります。たとえば、大口の法人保険契約の見積作成には数分間かかるため、見積が完了して呼び出し元に返される前に、API ゲートウェイがタイムアウトする場合があります。

このような状況に対応するため、クラウド API 呼び出しを非同期で実行できます。一般に、非同期呼び出しには 3 つのフェーズがあります。実際、これは 3 つ前後の呼び出しで発生する可能性があります。

呼び出しの送信

非同期呼び出しの場合、要求は同期呼び出しとほぼ同じです。唯一の相違点は、要求オブジェクトに、非同期応答を希望することを示す追加の Prefer 要求ヘッダーが含まれていることです。

呼び出しの形式が正しい場合は、クラウド API は最初の応答を送信します。

  • 応答のステータスは「202 Accepted」で、要求が受理済みであることを示します。
  • 応答本文は空です。
  • 応答には、GW-Async-Location ヘッダーが含まれています。ヘッダーの値は非同期 API エンドポイントのパスです。呼び出し元はこれを使用して元の要求に関する情報を取得できます。

これについては、次の図で説明します。



  1. 呼び出し元アプリケーションは、クラウド API に要求を送信します。要求オブジェクトには、呼び出しを非同期処理するよう指示する要求ヘッダーが含まれています。
  2. クラウド API が要求を受理します。ただし、これを即座に処理することはしません。
  3. クラウド API が応答を送信します。応答には、以下の取得に使用できる非同期 API /requests パスが指定されたヘッダーが含まれています。
    1. 最初の要求に関する情報。
    2. 最初の要求に対する応答（使用可能な場合）。

呼び出しが処理された時期の判断

呼び出しが送信されると、呼び出し元アプリケーションでは、最初の応答の非同期 API /requests パスを使用して、元の要求の情報を取得します。このパスの形式は、/async/v1/requests/<asyncRequestId> です。

/requests 呼び出しに対する応答には、常に次の情報が含まれています。

  • 元の要求の requestMethod と requestPath
  • 元の要求の status。これは次のように設定できます。
    • Accepted - 要求は今もなお処理を待機しています。
    • InProgress - 要求は処理中ですが、処理はまだ完了していません。
    • Complete - 要求は処理されました。
  • 元の要求の startTime

元の要求が完了している場合は、次の情報も含まれています。

  • 元の要求の completionTime
  • responseStatus と responseHeaders
  • 応答の形式が application/json である場合は、応答自体が responseBodyJson フィールドに含まれる

完了していない呼び出しの応答例

以下に、まだ完了していない非同期呼び出しの /requests 応答の一部を示します。

{
    "data": {
        "attributes": {
            "requestMethod": "POST",
            "requestPath": "/admin/v1/users",
            "responseStatus": 202,
            "startTime": "2022-07-12T16:53:12.365Z",
            "status": {
                "code": "Accepted",
                "name": "Accepted"
            }
        }
    }
}
Java

完了している呼び出しの応答例

以下に、完了している非同期呼び出しの /requests 応答の一部を示します。

{
    "data": {
        "attributes": {
            "completionTime": "2022-07-12T16:53:16.073Z",
            "requestMethod": "POST",
            "requestPath": "/admin/v1/users",
            "responseBodyJson": {
                "data": {
                    "attributes": {
                        ...
                        "username": "asyncUser99",
                        "vacationStatus": {
                            "code": "atwork",
                            "name": "At work"
                        }
                    },
                    "checksum": "321dff263827cbbd772c26676398d8ae",
                    "links": {
                    ...
                    }
                }
            },
            "responseHeaders": {
                "Cache-Control": [
                    "must-revalidate",
                    "post-check=0",
                    "pre-check=0",
                    "max-age=0",
                    "no-store",
                    "no-cache"
                ],
                "Content-Type": [
                    "application/json;charset=UTF-8"
                ],
                "GW-Checksum": [
                    "321dff263827cbbd772c26676398d8ae"
                ],
                "Location": [
                    "/admin/v1/users/pc:ScaA3kB5cImBkuh7bxjNn"
                ],
                "X-Correlation-ID": [
                    "d516344d-5769-4964-adb7-79eaca41e4a2"
                ],
                ...
            },
            "responseStatus": 201,
            "startTime": "2022-07-12T16:53:12.365Z",
            "status": {
                "code": "Complete",
                "name": "Complete"
            }
        }
        ...
    }
}
Java

元の要求が完了するまでのポーリング

呼び出し元アプリケーションは、ステータスが完了の応答を受け取るまで、クラウド API を定期的にポーリングします。これについては、次の図で説明します。



  1. 呼び出し元アプリケーションが GET /async/v1/requests/{asyncRequestId} 要求をクラウド API に送信します。このパスは最初の応答のヘッダーから取得できます。
  2. クラウド API 応答には、元の要求に関する情報が含まれます。ステータスが受理済みまたは進行中の場合は、呼び出し元アプリケーションは適切な間隔を置いて GET を再送信する必要があります。

応答に完了ステータスが含まれる場合は、呼び出し元は元の要求に対する応答を取得できます。複数の取得方法があります。

/requests/{asyncRequestId} を使用した応答の取得

/requests エンドポイントは、AsyncRequest リソースを返します。このリソースには、responseBodyJson 属性が含まれています。元の要求のステータスが完了で、応答のタイプが application/json である場合、この属性には最初の応答の応答ペイロードが含まれます。

これについては、次の図で説明します。



4.呼び出し元アプリケーションが GET /async/v1/requests/{asyncRequestId} 要求をクラウド API に送信します。acyncRequestId は最初の応答のヘッダーのものです。

5.クラウド API 応答には、元の要求に関する情報が含まれます。応答のタイプが application/json である場合、ステータスが完了であると、応答には元の要求の応答が含まれます。

GET /async/v1/requests/{asyncRequestId} 要求は、応答の初回送信時またはその後の送信時に、ステータスが完了の応答を返す可能性があることに注意してください。

/requests/{asyncRequestId}/response からの応答の取得

/requests/{asyncRequestId}/response エンドポイントもあります。完了した要求については、呼び出しが同期で実行されたかのように、このエンドポイントが元の応答を返します。このエンドポイントは次の場合に有用です。

  • 応答タイプが application/json でないため、GET /async/v1/requests/{asyncRequestId} 応答に含まれない場合。
  • 呼び出し元アプリケーションが、大規模なデータエンベロープの responseBodyJson 属性内から抽出せずに、通常生成される応答を使用したい場合。

これについては、次の図で説明します。



6.呼び出し元アプリケーションが GET /async/v1/requests/{asyncRequestId}/response 要求をクラウド API に送信します。

7.要求が同期で実行されたかのように、クラウド API 応答には元の応答が含まれます。

元の呼び出しが完了すると、GET /async/v1/requests/{asyncRequestId}/response に対する応答には、呼び出し元が元の要求に対する同期応答を取得したかのように、同じステータスコード、応答本文（ある場合）、および応答ヘッダーが含まれます。

たとえば、元の要求が新しいアクティビティを作成する POST である場合は、応答を取得するための GET 要求は応答コード 201 を返し、Location ヘッダーを含みます。検証エラーのために元の要求が失敗した場合は、応答を取得するための GET 要求には、ステータスコード 400 と、エラーの詳細を記載した応答本文が含まれます。