Webhook を使用して通知を設定する

Apigee Edge のドキュメントを表示しています。
Apigee X のドキュメントに移動。 情報

Webhook とは何ですか？

Webhook は、イベントによってトリガーされる HTTP コールバック ハンドラを定義します。通知テンプレートを使用して通知を設定するで説明されているように、収益化通知テンプレートの代わりに、webhook を作成してイベント通知を処理するように構成することもできます。

Webhook を使用して通知を設定するには、Edge 管理 UI または Management and Monetization API を使用して次の手順を完了します。

  1. UI または API を使用して、通知イベントのコールバック ハンドラを定義する Webhook を追加します。
  2. コールバック ハンドラを設定する。
  3. UI または API を使用して、調整可能な料金プランの通知を設定します。

Webhook の管理

UI または API を使用して、通知イベントのコールバック ハンドラを定義する Webhook を追加、管理します。

UI を使用した Webhook の管理

次のセクションで説明するように、UI を使用して通知イベントのコールバック ハンドラを定義する Webhook を追加、管理します。

[Webhooks] ページの詳細

次の手順に沿って [Webhooks] ページにアクセスします。

Edge

Edge UI を使用して [Webhooks] ページにアクセスするには:

  1. apigee.com/edge にログインします。
  2. 左側のナビゲーション バーで [Publish] > [Monetization] > [Webhooks] を選択します。

[Webhooks] ページが表示されます。

図でハイライト表示されているように、[Webhooks] ページでは次のことができます。

Classic Edge（プライベート クラウド）

Classic Edge UI を使用して [Webhooks] ページにアクセスするには:

  1. http://ms-ip:9000 にログインします。ms-ip は Management Server ノードの IP アドレスまたは DNS 名です。

  2. [Admin] > [Webhooks] を選択します。

[Webhooks] ページが表示されます。

[Webhooks] ページでは、次のことができます。

UI を使用して Webhook を追加する

UI を使用して Webhook を追加するには:

  1. [Webhooks] ページにアクセスします。
  2. [+ Webhook] をクリックします。
  3. 次の情報を入力します（すべての項目にご記入ください）。
    フィールド 説明
    名前 Webhook の名前。
    URL イベント通知がトリガーされたときに呼び出されるコールバック ハンドラの URL。コールバック ハンドラの設定をご覧ください。
  4. [保存] をクリックします。

Webhook がリストに追加され、デフォルトで有効になります。

UI を使用して Webhook を編集する

UI を使用して Webhook を編集するには:

  1. [Webhooks] ページにアクセスします。
  2. 編集する Webhook にカーソルを合わせて、操作メニューの をクリックします。
  3. 必要に応じて Webhook フィールドを編集します。
  4. [Webhook の更新] をクリックします。

UI を使用して Webhook を有効または無効にする

UI を使用して Webhook を有効または無効にするには:

  1. [Webhooks] ページにアクセスします。
  2. Webhook にカーソルを合わせ、ステータス スイッチを切り替えて有効または無効にします。

UI を使用して Webhook を削除する

UI を使用して Webhook を削除するには:

  1. [Webhooks] ページにアクセスします。
  2. 削除する Webhook にカーソルを合わせて、 をクリックします。

Webhook が削除され、リストから除外されます。

API を使用した Webhook の管理

以降のセクションで説明するように、API を使用して Webhook を追加、管理します。

API を使用したすべての Webhook の表示

/mint/organizations/{org_name}/webhooks に GET リクエストを送信して、すべての Webhook を表示します。例:

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks" \
  -H "Content-Type: application/json " \
  -u email:password

返されるレスポンスの例を次に示します。

{
  "totalRecords": 2,
  "webhooks": [
    {
      "created": 1460162656342,
      "enabled": false,
      "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
      "name": "webhook1",
      "postUrl": "http://mycompany.com/callbackhandler1",
      "updated": 1460162656342,
      "updatedBy": "joe@example.com"
    },
        {
      "created": 1460138724352,
      "createdBy": "joe@example.com",
      "enabled": true,
      "id": "a39ca777-1861-49cf-a397-c9e92ab3c09f",
      "name": "webhook2",
      "postUrl": "http://mycompany.com/callbackhandler2",
      "updated": 1460138724352,
      "updatedBy": "joe@example.com"
    }

  ]
}

API を使用した Webhook の表示

/mint/organizations/{org_name}/webhooks/{webhook_id} に GET リクエストを発行して、1 つの Webhook を表示します。

例:

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" \
  -H "Content-Type: application/json " \
  -u email:password

レスポンスの例を次に示します。

{
   "created": 1460162656342,
   "enabled": false,
   "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
   "name": "webhook1",
   "postUrl": "http://mycompany.com/callbackhandler1",
   "updated": 1460162656342,
   "updatedBy": "joe@example.com"
 }

API を使用して Webhook を追加する

/mint/organizations/{org_name}/webhooks に POST リクエストを発行して、Webhook を追加します。Webhook の名前と、イベント通知がトリガーされたときに呼び出されるコールバック ハンドラの URL を渡す必要があります。

たとえば、次のコマンドは webhook3 という名前の Webhook を作成し、callbackhandler3 を Webhook に割り当てます。

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks"
  -H "Content-Type: application/json "
  -d '{
    "name": "webhook3",
    "postURL": "http://mycompany.com/callbackhandler3"
    }' \
    -u email:password

レスポンスの例を次に示します。

{
  "created": 1460385534555,
  "createdBy": "joe@example.com",
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler3",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

API を使用した Webhook の編集

Webhook を編集するには、/mint/organizations/{org_name}/webhooks/{webhook_id} に PUT リクエストを発行します。更新内容をリクエストの本文で渡します。

たとえば、次のコマンドは webhook1 に関連付けられたコールバック ハンドラを更新します。

curl -X PUT "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" \
  -H "Content-Type: application/json " \
  -d '{
    "postURL": "http://mycompany.com/callbackhandler4"
  }' \
  -u email:password

レスポンスの例を次に示します。

{
  "created": 1460385534555,
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

API を使用して Webhook を有効または無効にする

Webhook の更新時と同様に、POST リクエストを /mint/organizations/{org_name}/webhooks/{webhook_id} に発行して Webhook を有効または無効にするとともに、リクエスト本文の enabled 属性をそれぞれ true または false に設定します。Webhook を無効にすると、イベントが発生してもトリガーされなくなります。

たとえば、次のようにすると webhook3 が有効になります。

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" \
  -H "Content-Type: application/json " \
  -d '{
    "enabled": "true"
  }' \
  -u email:password

レスポンスの例を次に示します。

{
  "created": 1460385534555,
  "enabled": true,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

API を使用して Webhook を削除する

/mint/organizations/{org_name}/webhooks/{webhook_id} に DELETE リクエストを発行して Webhook を削除します。

進行中のプロセスがある場合に Webhook を強制的に削除するかどうかを指定するには、forceDelete クエリ パラメータを true または false に設定します。forceDelete クエリ パラメータはデフォルトで有効になっています（true）。

たとえば、次のコマンドは webhook3 を削除します。

curl -X DELETE "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" \
  -H "Content-Type: application/json " \
  -u email:password

コールバック ハンドラの設定

以下は、イベント通知がトリガーされたときに Webhook で定義されたコールバック ハンドラに送信される JSON リクエストの形式を示しています。コールバック ハンドラがリクエストを適切に処理できるようにする必要があります。

{
        "orgName": "{org_id}",
        "developerEmail": "{dev_email}",
        "developerFirstName": "{first_name}",
        "developerLastName": "{last_name}",
        "companyName": "{company_name}",
        "applicationName": "{app_name}",
        "packageName": "{api_package_name}",
        "packageId": "{api_package_id}",
        "ratePlanId": "{rateplan_id}",
        "ratePlanName": "{rateplan_name}",
        "ratePlanType": "{rateplan_type}",
        "developerRatePlanQuotaTarget": {quota_target},
        "quotaPercentUsed": {percentage_quota_used},
        "ratePlanStartDate": {rateplan_startdate}, 
        "ratePlanEndDate": {rateplan_enddate},
        "nextBillingCycleStartDate": {next_billing_cycle_startdate},
        "products": ["{api_product_name}","{api_product_name}"],
        "developerCustomAttributes": [],
        "triggerTime": {trigger_time},
        "triggerReason": "{trigger_reason}",
        "developerQuotaResetDate": "{devquota_resetdate}"
}

調整可能な料金プランの通知を設定する

UI または API を使用して、調整可能な料金プランの Webhook を使用して通知を設定します。

UI を使用して調整可能な料金プランの通知を設定する

以下で説明するように、UI を使用して調整可能な料金プランの Webhook を使用して通知を設定します。

調整可能な料金プランの [通知] ダイアログにアクセスする

下記の手順に沿って、調整可能な料金プランの [通知] ダイアログにアクセスします。

Edge

Edge UI を使用して通知ダイアログにアクセスするには:

  1. 調整可能な通知プランの詳細を指定するの説明に沿って、調整可能な通知料金プランを作成して公開します。
  2. 左側のナビゲーション バーで [Publish] > [Monetization] > [Rate Plans] を選択して、[Rate Plans] ページにアクセスします。
  3. 公開済みの調整可能な通知料金プランにカーソルを合わせて、操作を表示します。
  4. [+通知] をクリックします。

    [通知] ダイアログが表示されます。

    注: +Notify アクションを表示するには、料金プランが公開されている必要があります。

Classic Edge（Private Cloud）

[通知] ページにアクセスするには:

  1. 調整可能な通知プランの詳細を指定するの説明に沿って、調整可能な通知料金プランを作成します。
  2. [Publish] > [Packages] を選択して、料金プランを表示します。
  3. 料金プランの [アクション] 列で [+通知] をクリックします。

    [通知] ダイアログが表示されます。

UI を使用して調整可能な料金プランの通知を追加する

UI で調整可能な料金プランの通知を追加するには:

  1. [通知] ダイアログにアクセスします。
  2. 通知条件を [通知間隔] で設定します。通知をトリガーするターゲット トランザクション数の割合を指定します。詳細は以下のとおりです。
    • 正確な割合を設定するには、[At/From %] フィールドに割合を入力し、[To %] フィールドは空白のままにします。
    • 割合の範囲を設定するには、[At/From %] フィールドと [To %] フィールドに開始割合と終了割合をそれぞれ入力し、[Step %] フィールドに増分値を入力します。デフォルトでは、通知は指定された範囲内で 10% 単位で送信されます。

    Notify At フィールドが更新され、イベントをトリガーするターゲット トランザクション数の各割合が反映されます。

  3. 通知の追加条件を設定するには、[+ 追加] をクリックして手順 4 を繰り返します。
  4. [Webhooks] で通知アクションを設定し、通知がトリガーされたときのコールバック処理を管理する webhook を 1 つ以上選択します。
  5. [Create Notification] をクリックします。

UI を使用して調整可能な料金プランの通知を編集する

UI で調整可能な料金プランの通知を編集するには:

  1. [通知ダイアログ] にアクセスします。
  2. 料金プランの [アクション] 列で [+ 通知] をクリックします。
  3. [編集] をクリックします。
  4. 必要に応じて値を変更します。
  5. [通知を保存] をクリックします。

UI を使用して調整可能な料金プランの通知を削除する

通知の条件とアクションを削除するには:

  1. [通知ダイアログ] にアクセスします。
  2. 料金プランの [アクション] 列で [+通知] をクリックします。
  3. [通知を削除] をクリックします。

API を使用して調整可能な料金プランの通知を設定する

API を使用して調整可能な料金プランの通知を設定するには、API を使用して通知の条件とアクションを管理するで説明されている手順を使用し、このセクションで説明する属性を使用します。

通知条件（notificationCondition）を設定するには、次の属性値を使用します。詳細については、通知条件の構成プロパティをご覧ください。

属性 値
RATEPLAN 調整可能な通知料金プランの ID。
PUBLISHED TRUE: 調整可能な通知料金プランを公開する必要があることを示します。
UsageTarget 通知をトリガーする取引数の目標数に対する割合。

この属性を使用すると、購入した調整可能な通知料金プランのトランザクション目標数が近づいたか、達したときにデベロッパーに通知できます。たとえば、デベロッパーが調整可能な通知料金プランを購入していて、デベロッパーのトランザクションの目標数が 1,000 に設定されている場合、800 件（トランザクションの目標数の 80%）、1,000 件（100%）、1,500 件（150%）に達したときに通知できます。

  • 正確な割合を設定するには、%= n を入力します。たとえば、%= 80 は、トランザクションのターゲット数の割合が 80% に達したときに通知を送信します。
  • 割合の範囲を設定するには、開始割合と終了割合、および増分値を入力します（例: %= start to end by n）。たとえば、値を %= 80 to 100 by 10 にすると、トランザクションのターゲット数の割合が 80%、90%、100% に達したときに通知が送信されます。

通知アクションを設定するには、actions で次の値を設定します。詳細については、通知アクションの構成プロパティをご覧ください。

属性 値
actionAttribute WEBHOOK: Webhook をトリガーします。
value 前のセクションの API を使用した Webhook の作成で定義した Webhook の ID。

次の例は、ターゲット トランザクション数の割合が 80%、90%、100%、110%、120% に達したときに Webhook をトリガーする通知条件を作成する方法を示しています。

{
    "notificationCondition": [
      {
        "attribute": "RATEPLAN",
        "value": "123456"
      },
      {
        "attribute": "PUBLISHED",
        "value": "TRUE"
      },
      {
        "attribute": "UsageTarget",
        "value": "%= 80 to 120 by 10"
      }
    } 
    ],
   "actions": [{
          "actionAttribute": "WEBHOOK",
          "value": "b0d77596-142e-4606-ae2d-f55c3c6bfebe",
        }]
  }

通知条件と通知アクションの表示、更新、削除については、以下をご覧ください。

Webhook レスポンス コード

Webhook レスポンス コードと、システムによるその解釈方法を以下にまとめます。

レスポンス コード 説明
2xx 成功
5xx

リクエストに失敗しました。システムは、5 分間隔で最大 3 回リクエストを再試行します。

注: Webhook リクエストの読み取りタイムアウトと接続タイムアウトはそれぞれ 3 秒であるため、リクエストが失敗する可能性があります。
Other response リクエストに失敗しました。リクエストは再試行されません。