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. [Update Webhook] をクリックします。

UI を使用した Webhook の有効化または無効化

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

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

UI を使用した Webhook の削除

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

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

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

API を使用した Webhook の管理

以下のセクションでは、API を使用して Webhook を追加、管理する方法について説明します。

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

GET リクエストを /mint/organizations/{org_name}/webhooks に発行して、すべての 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 の表示

GET リクエストを /mint/organizations/{org_name}/webhooks/{webhook_id} に発行して、単一の 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 の追加

Webhook を追加するには、POST リクエストを /mint/organizations/{org_name}/webhooks に発行します。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 を無効にすると、イベントが発生しても 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 の削除

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

進行中のプロセスがある場合に 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. [料金プラン] ページにアクセスするには、左側のナビゲーション バーで [公開] > [収益化] > [料金プラン] を選択します。
  3. 公開されている調整可能な通知料金プランにカーソルを合わせて、アクションを表示します。
  4. [+Notify] をクリックします。

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

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

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

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

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

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

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

調整可能な料金プランの通知を追加するには、UI で次の操作を行います。

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

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

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

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

調整可能な料金プランの通知を編集するには、UI で次の操作を行います。

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

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 リクエストに失敗しました。システムはリクエストを再試行しません。