コンテンツにスキップ

コールバック

OpenAPI 3 の仕様では、**コールバック**を定義できます。これは、特定のイベントに応答してサービスが他のサービスに送信する非同期のアウトオブバンドのリクエストです。これにより、API がクライアントに提供するワークフローを改善できます。コールバックの典型的な例は、サブスクリプション機能です。ユーザーはサービスの特定のイベントを購読し、そのイベントが発生したときに通知を受け取ります。たとえば、電子ショップは購入ごとにマネージャーに通知を送信できます。これらの通知は「アウトオブバンド」であり、訪問者が作業する接続とは異なる接続を介して行われ、通常の要求-応答フロー外であるため非同期です。OpenAPI 3 では、「サブスクリプション」操作の形式、コールバックメッセージの形式、およびこれらのメッセージへの期待される応答を定義できます。この説明は、異なるサーバー間の通信を簡素化し、API での Webhook の使用を標準化するのに役立ちます。

コールバックの例

シンプルな Webhook 通知のコールバック定義を作成しましょう。API がリクエストボディにコールバック URL を期待する POST /subscribe 操作を提供すると仮定します。

1
POST /subscribe
2
Host: my.example.com
3
Content-Type: application/json
4


5
{
6
  "callbackUrl": "https://myserver.com/send/callback/here"
7
}

API はサブスクリプションを承認します —

1
HTTP/1.1 201 Created

— その後、特定のイベントに関する通知を送信します。

1
POST /send/callback/here
2
Host: myserver.com
3
Content-Type: application/json
4


5
{
6
  "message": "Something happened"
7
}

次に、/subscribe 操作を定義しましょう。

1
openapi: 3.0.4
2
info:
3
  version: 0.0.0
4
  title: test
5


6
paths:
7
  /subscribe:
8
    post:
9
      summary: Subscribe to a webhook
10
      requestBody:
11
        required: true
12
        content:
13
          application/json:
14
            schema:
15
              type: object
16
              properties:
17
                callbackUrl: # Callback URL
18
                  type: string
19
                  format: uri
20
                  example: https://myserver.com/send/callback/here
21
              required:
22
                - callbackUrl
23
      responses:
24
        "201":
25
          description: Webhook created

次に、この操作にコールバックキーワードを追加してコールバックを定義します。

1
paths:
2
  /subscribe:
3
    post:
4
      summary: Subscribe to a webhook
5
      requestBody: …
6
      callbacks: # Callback definition
7
        myEvent: # Event name
8
          "{$request.body#/callbackUrl}": # The callback URL,
9
            # Refers to the passed URL
10
            post:
11
              requestBody: # Contents of the callback message
12
                required: true
13
                content:
14
                  application/json:
15
                    schema:
16
                      type: object
17
                      properties:
18
                        message:
19
                          type: string
20
                          example: Some event happened
21
                      required:
22
                        - message
23
              responses: # Expected responses to the callback message
24
                "200":
25
                  description: Your server returns this code if it accepts the callback

この定義を一行ずつ見ていきましょう。

  • callbacks は、関連する操作 (たとえば、post、put など) の中に定義されます (パス自体の下ではありません)。この例では、/subscribe パスの post メソッドの下にあります。
1
paths:
2
  /subscribe:
3
    post:
4
      …
5
      callbacks:
6
        …

これは、この操作が機能している場合にのみ API がコールバックを送信するという意味ではありません。API は、サービスビジネスロジックが必要なときにコールバックリクエストを送信します。キーワードの階層は、/subscribe 操作のパラメーターを使用してコールバックリクエストを設定できるだけです (下記参照)。

  • callbacks の内部で、1 つ以上のコールバックメッセージを定義します。この例では、1 つのメッセージのみです。複数のコールバックの例は後述します。各コールバックの定義は、イベント名 (_myEvent_ の例では) で始まります。
1
callbacks:
2
  myEvent: # Event name
  • イベント名の下に、サービスがコールバックメッセージを送信する URL を定義します。この例では、URL は {$request.body#/callbackUrl} 式を使用して指定されています。
1
callbacks:
2
  myEvent:
3
    "{$request.body#/callbackUrl}": # The callback URL, refers to the URL passed in the request body

この式は、コールバックURLが /subscribe 操作のパラメーターに基づいて決定されることを示しています。これらの式については、後ほど詳しく説明します。

  • URL の下には、コールバックメッセージのメソッドを指定し、メッセージ形式と期待される応答を定義します。これらの定義は、通常の要求と応答の定義に似ています。
1
callbacks:
2
  myEvent:
3
    "{$request.body#/callbackUrl}":
4
      post: # Method
5
        requestBody: # Contents of the callback message
6
          …
7
        responses: # Expected responses
8
          …

コールバックを定義するときは、API の仕様を定義していることに注意してください。コールバック機能の実際の実装は、サーバーコードで行われます。

ランタイム式を使用してリクエストフィールドを参照する

ご覧のとおり、この例では {$request.body#/callbackUrl} 式を使用しています。これは、POST /subscribe リクエストのどのデータがコールバックで使用されるかを設定するランタイム式です。*ランタイム*とは、API エンドポイントとは異なり、この URL は事前にわかっておらず、API クライアントによって提供されたデータに基づいて実行時に評価されることを意味します。この値はクライアントによって異なります。たとえば、POST /subscribe リクエストは次のようになります。

1
POST /subscribe?p1=query-param-value HTTP/1.1
2
Host: my.example.com
3
Content-Type: application/json
4
Content-Length: 187
5


6
{
7
  "callbackUrl" : "http://my.client.com/callback"
8
}
9


10
201 Created
11
Location: http://my.example.com?id=123

そのデータを参照するには、以下の式を使用できます。

式例説明
{$url}/subscribe親操作の URL。
{$method}POSTコールバックリクエストのメソッド。
{$request.path.eventType}myEventイベント名。
{$request.query.param-name}query-param-value ( p1 クエリパラメータ)指定されたクエリパラメータの値。
{$request.header.header-name}application/json (Content-Type ヘッダー)「サブスクリプション」リクエストの指定されたヘッダー。
{$request.body#/field-name}callbackUrlリクエストボディ内のフィールド。フィールドが配列の場合は、{$request.body#/arrayField/2} のような構文を使用します。
{$response.header.header-name}http://my.example.com?id=123 (Location ヘッダー)指定されたレスポンスヘッダーの値 (「サブスクリプション」リクエストへのレスポンス)。

コールバック定義では、ランタイム式と静的データを組み合わせることができます。たとえば、次のようにコールバック URL を定義できます。

1
{$request.body#callbackUrl}/data:
2
– or –
3
{$request.body#/callbackUrl}/{$request.query.eventType}:

式を使用してクエリパラメータを指定できます。

1
{$request.body#/callbackUrl}/data?p1={$request.query.eventType}

文字列にランタイム式と静的テキストの両方が含まれている場合は、ランタイム式を中括弧で囲む必要があります。文字列全体がランタイム式である場合は、中括弧を省略できます。

複数のコールバック

上記のように、1つの「サブスクリプション」操作を使用して複数のコールバックを定義できます。

1
/subscribe:
2
  post:
3
    requestBody:
4
      content:
5
        application/json:
6
          schema:
7
            type: object
8
            properties:
9
              inProgressUrl:
10
                type: string
11
              failedUrl:
12
                type: string
13
              successUrl:
14
                type: string
15
    responses:
16
      "200":
17
        description: OK
18
    callbacks:
19
      inProgress:
20
        "{$request.body#/inProgressUrl}":
21
          post:
22
            requestBody:
23
              $ref: "#/components/requestBodies/callbackMessage1"
24
            responses:
25
              "200":
26
                description: OK
27
        "{$request.body#/failedUrl}":
28
          post:
29
            requestBody:
30
              $ref: "#/components/requestBodies/callbackMessage2"
31
            responses:
32
              "200":
33
                description: OK
34
        "{$request.body#/successUrl}":
35
          post:
36
            requestBody:
37
              $ref: "#/components/requestBodies/callbackMessage3"
38
            responses:
39
              "200":
40
                description: OK

コールバックの解除

サブスクライブ解除メカニズムの実装方法はあなた次第です。たとえば、受信サーバーはコールバックメッセージに応答して特定のコードを返し、コールバックに興味がないことを示すことができます。この場合、クライアントはコールバックリクエストに応答してのみサブスクライブ解除できます。クライアントがいつでもサブスクライブ解除できるように、API は特別な「サブスクライブ解除」操作を提供できます。これはかなり一般的なアプローチです。この場合、サービスは各サブスクライバーの ID またはトークンを生成し、「サブスクリプション」リクエストへの応答としてこの ID またはトークンを返すことができます。サブスクライブ解除するには、クライアントはこの ID を「サブスクライブ解除」操作に渡して、削除するサブスクライバーを指定できます。以下の例は、この動作を仕様で定義する方法を示しています。

1
paths:
2
/subscribe:
3
  description: Add a subscriber
4
  post:
5
    parameters:
6
      - name: callbackUrl
7
        in: query
8
        required: true
9
        schema:
10
          type: string
11
          format: uri
12
      - name: event
13
        in: query
14
        required: true
15
        schema:
16
          type: string
17
    responses:
18
      '201':
19
        description: Added
20
        content:
21
          application/json:
22
            type: object
23
            properties:
24
              subscriberId:
25
                type: string
26
                example: AAA-123-BBB-456
27
    links:  # Link the returned id with the unsubscribe operation
28
      unsubscribeOp:
29
        operationId: unsubscribeOperation
30
            parameters:
31
              Id: $response.body#/subscriberId
32
    callbacks:
33
      myEvent:
34
        '{$request.query.callbackUrl}?event={$request.query.event}':
35
          post:
36
            requestBody:
37
              content:
38
                application/json:
39
                  example:
40
                    message: Some event
41
            responses:
42
              '200':
43
                description: OK
44


45
/unsubscribe:
46
  post:
47
    operationId: unsubscribeOperation
48
    parameters:
49
      - name: Id
50
        in: query
51
        required: true
52
        schema:
53
          type: string

お探しのものが見つかりませんでしたか？ コミュニティに質問する
間違いを見つけましたか？ お知らせください