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

ここに表示されているのは Apigee Edge のドキュメントです。
Go to the Apigee X のドキュメントに移動します。 info

Webhook とは

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

Webhook を使用して通知を設定するには、Edge 管理 UI、Management API、収益化 API を使用して次の手順を行います。

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

Webhook の管理

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

UI を使用して Webhook を管理する

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

[Webhook] ページを確認する

以下の手順で [Webhook] ページにアクセスします。

エッジ

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

  1. apigee.com/edge にログインします。
  2. 左側のナビゲーション バーで、[公開] > [収益化] > [Webhook] を選択します。

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

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

Classic Edge（Private Cloud）

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

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

  2. [管理者] > [Webhook] を選択します。

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

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

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. [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 を表示する

に GET リクエストを発行して、単一の Webhook を表示します。/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 を編集する

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

たとえば、次のコマンドは 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 を更新したときと同様に、 /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 を使用して通知を設定します。

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

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

エッジ

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

  1. 調整可能な通知料金プランを作成して公開します。調整可能な通知プランの詳細を指定するをご覧ください。
  2. 左側のナビゲーション バーで [公開] > [収益化] > [料金プラン] を選択して、[料金プラン] ページにアクセスします。
  3. 公開された調整可能な通知料金プランにカーソルを合わせて、操作メニューを表示します。
  4. [\+ 通知] をクリックします。

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

    [注] : [+\ 通知] 操作を表示するには、料金プランを公開する必要があります。

Classic Edge（Private Cloud）

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

  1. 調整可能な通知料金プランを作成します。調整可能な通知プランの詳細を指定するをご覧ください。
  2. [公開] > [パッケージ] を選択して、料金プランを表示します。
  3. 料金プランの [操作] 列で [\+ 通知] をクリックします。

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

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

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

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

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

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

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