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 UI を使用して [Webhooks] ページにアクセスするには:

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

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

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

Classic Edge（Private Cloud）

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

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

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

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

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

UI を使用した Webhook の追加

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

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

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

UI を使用した Webhook の編集

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

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

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

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

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

UI を使用した Webhook の削除

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

  1. [Webhook] ページにアクセスします。
  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 の表示

単一の Webhook を表示するには、GET リクエストを /mint/organizations/{org_name}/webhooks/{webhook_id} に送信します。

例:

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} に POST リクエストを発行します。リクエストの本文で更新を渡します。

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

curl -X POST "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 を有効または無効にするには、Webhook の更新時と同様に、POST リクエストを /mint/organizations/{org_name}/webhooks/{webhook_id} に発行し、リクエスト本文の 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 の削除

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

進行中のプロセスがある場合に 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 を使用して通知を設定します。

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

以下で説明するように、調整可能な料金プランについては、[Notifications] ダイアログにアクセスします。

エッジ

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

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

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

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

Classic Edge（Private Cloud）

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

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

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

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

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

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

    Notify At フィールドが更新され、イベントをトリガーするトランザクションの目標数に対する各パーセンテージが反映されます。

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

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

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

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

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

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

  1. [Notifications] ダイアログにアクセスします。
  2. 料金プランの [Actions] 列の [+Notify] をクリックします。
  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 リクエストに失敗しました。システムはリクエストを再試行しません。