使用 Webhook 設定通知

您正在查看 Apigee Edge 說明文件。
前往 Apigee X 說明文件。info

什麼是 webhook？

Webhook 會定義由事件觸發的 HTTP 回呼處理常式。您可以建立 webhook，並將其設為處理事件通知，這可取代使用營利通知範本，如「使用通知範本設定通知」一文所述。

如要使用 webhook 設定通知，請使用 Edge Management UI 或 Management and Monetization API 完成下列步驟：

  1. 使用 UI 或 API 新增 webhook，定義通知事件的回呼處理常式。
  2. 設定回呼處理常式。
  3. 使用 UI 或 API 為可調整的費率方案設定通知。

管理 Webhook

使用UI 或 API 新增及管理 webhook，定義通知事件的回呼處理常式。

使用 UI 管理 Webhook

新增及管理 webhook，以便使用 UI 定義通知事件的回呼處理常式，如以下各節所述。

探索 Webhook 頁面

請按照下方說明存取 Webhooks 頁面。

Edge

如要使用 Edge UI 存取 Webhook 頁面，請按照下列步驟操作：

  1. 登入 apigee.com/edge。
  2. 在左側導覽列中，依序選取「發布」>「營利」>「Webhook」。

畫面上會顯示「Webhooks」頁面。

如圖中所示，Webhook 頁面可讓您：

Classic Edge (Private Cloud)

如要使用 Edge 傳統版 UI 存取「Webhooks」頁面，請按照下列步驟操作：

  1. 登入 http://ms-ip:9000，其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。

  2. 依序選取「管理」>「Webhook」。

系統隨即顯示 Webhooks 頁面。

您可以在「Webhooks」頁面中執行下列操作：

使用 UI 新增 Webhook

如何使用 UI 新增 webhook：

  1. 前往「Webhook」頁面。
  2. 按一下「+ Webhook」。
  3. 輸入下列資訊 (所有欄位皆為必填)。
    欄位 說明
    名稱 Webhook 名稱。
    網址 事件通知觸發時會呼叫的回呼處理常式網址。請參閱「設定回呼處理常式」。
  4. 按一下 [儲存]。

系統會將 webhook 新增至清單，並預設為啟用。

使用 UI 編輯 webhook

如何使用 UI 編輯 Webhook：

  1. 前往 Webhook 頁面。
  2. 將游標懸停在要編輯的 webhook 上，然後點選操作選單中的 。
  3. 視需要編輯 webhook 欄位。
  4. 按一下「更新 Webhook」。

使用 UI 啟用或停用 webhook

如何使用 UI 啟用或停用 webhook：

  1. 前往「Webhook」頁面。
  2. 將滑鼠游標移至 webhook，然後切換狀態切換鈕，即可啟用或停用 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

向 /mint/organizations/{org_name}/webhooks/{webhook_id} 發出 GET 要求，即可查看單一 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 的名稱和觸發事件通知時要呼叫的回呼處理常式網址。

例如，下列程式碼會建立名為 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 時一樣，向 /mint/organizations/{org_name}/webhooks/{webhook_id} 發出 POST 要求，並分別將要求主體中的 enabled 屬性設為 true 或 false，即可啟用或停用 Webhook。如果停用 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

向 /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

設定回呼處理常式

以下是 JSON 要求的格式，當事件通知觸發時，系統會將這項要求傳送至 Webhook 定義的回呼處理常式。您必須確保回呼處理常式能妥善處理要求。

{
        "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. 按一下「+通知」。

    畫面上會顯示「通知」對話方塊。

    注意：費率方案必須先發布，「+ 通知」動作才會顯示。

Classic Edge (Private Cloud)

如要存取「通知」頁面，請按照下列步驟操作：

  1. 建立可調整的通知費率方案，如「指定可調整的通知費率方案詳細資料」一節所述。
  2. 選取「發布」>「套裝方案」，即可查看費率方案。
  3. 按一下費率方案「動作」欄中的「+通知」。

    畫面上會顯示「通知」對話方塊。

使用 UI 為可調整費率方案新增通知

如何在 UI 中為可調整費率方案新增通知：

  1. 開啟「通知」對話方塊。
  2. 指定您希望觸發通知的目標交易次數百分比，以設定「通知間隔」下方的通知條件。具體問題如下：
    • 如要設定確切百分比，請在「At/From %」欄位中輸入百分比，並將「To %」欄位留空。
    • 如要設定百分比範圍，請分別在「At/From %」和「To %」欄位中輸入開始和結束百分比，並在「Step %」欄位中輸入遞增值。根據預設，系統會在指定範圍內以 10% 的間隔傳送通知。

    Notify At 欄位會更新，反映會觸發事件的目標次數百分比。

  3. 如要設定其他通知條件，請按一下「+ 新增」，然後重複執行步驟 4。
  4. 選取一或多個 Webhook 來管理通知觸發時的回呼處理方式，藉此設定「Webhook」下方的通知動作。
  5. 按一下「建立通知」。

使用 UI 編輯可調整費率方案的通知

如何在使用者介面中編輯可調整費率方案的通知：

  1. 存取通知對話方塊。
  2. 按一下費率方案「動作」欄中的「+通知」。
  3. 按一下 [編輯]。
  4. 視需要修改值。
  5. 按一下「儲存通知」。

使用 UI 刪除可調整費率方案的通知

如何刪除通知條件和動作：

  1. 開啟「通知」對話方塊。
  2. 按一下費率方案「動作」欄中的「+通知」。
  3. 按一下「刪除通知」。

使用 API 設定可調整費率方案的通知

如要使用 API 為可調整費率方案設定通知，請按照「使用 API 管理通知條件和動作」一節所述程序操作，並使用本節所述的屬性。

如要設定通知條件 (notificationCondition)，請使用下列屬性值。詳情請參閱「通知條件設定屬性」。

屬性 值
RATEPLAN 可調整的通知費率方案 ID。
PUBLISHED TRUE，表示必須發布可調整的通知費率方案。
UsageTarget 您希望觸發通知的交易目標數量百分比。

這個屬性可讓您通知開發人員，當他們購買可調整通知費率的卡片方案，且交易次數已接近或達到目標時，系統會通知他們。舉例來說，如果開發人員購買了可調整的通知費率方案，且開發人員的目標交易次數設為 1,000 筆，那麼您可以在達成 800 筆交易 (目標交易次數的 80%)、交易次數 (100%) 或 1500 筆交易 (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 分鐘的間隔內最多重試要求三次。

注意： Webhook 要求的讀取和連線逾時時間限制為 3 秒，因此可能導致要求失敗。
Other response 要求失敗。系統不會再次嘗試提出要求。