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] を選択します。

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

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

従来の Edge(Private Cloud)

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 の表示

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

例:

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 の更新時と同様に、/mint/organizations/{org_name}/webhooks/{webhook_id} に POST リクエストを発行して 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 を使用して通知を設定します。

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

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

エッジ

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

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

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

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

従来の Edge(Private Cloud)

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. [通知] ダイアログにアクセスします。
  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 リクエストに失敗しました。システムはリクエストを再試行しません。