使用 Webhook 設定通知

您目前查看的是 Apigee Edge 說明文件。
參閱 Apigee X說明文件。 資訊

什麼是 Webhook？

Webhook 會定義由事件觸發的 HTTP 回呼處理常式。您可以按照「使用通知範本設定通知」一文的說明，建立並設定 Webhook 來處理事件通知，做為使用營利通知範本的替代方案。

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

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

管理 Webhook

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

使用 UI 管理 Webhook

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

探索 Webhook 頁面

按照下文說明存取 Webhook 頁面。

Edge

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

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

系統隨即會顯示 Webhook 頁面。

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

傳統版 Edge (Private Cloud)

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

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

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

系統隨即顯示 Webhooks 頁面。

Webhook 頁面可讓您：

使用 UI 新增 Webhook

如要使用 UI 新增 Webhook，請執行下列操作：

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

Webhook 會加到清單中，並預設為啟用。

在 UI 中編輯 Webhook us

如要使用 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

如要查看單一 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 的名稱和觸發事件通知時要呼叫的回呼處理常式網址。

舉例來說，以下指令建立名為 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

您可以向 /mint/organizations/{org_name}/webhooks/{webhook_id} 發出 POST 要求來啟用或停用 Webhook，方法與更新 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

向 /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 設定可調整費率方案的通知

如下所述，使用 Webhook 為可調整的費率方案設定通知。

調整可調整費率方案的「通知」對話方塊

按照下方所述，存取「通知」對話方塊，調整可調整費率方案。

Edge

如何使用 Edge UI 存取通知對話方塊：

  1. 按照「指定可調整的通知方案詳細資料」一節所述，建立及發布可調整的通知費率方案。
  2. 前往左側導覽列中的「發布」>「營利」>「費率方案」，前往「費率方案」頁面。
  3. 只要將遊標移到已發布的可調整通知率方案上，系統就會顯示動作。
  4. 按一下「+通知」。

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

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

傳統版 Edge (Private Cloud)

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

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

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

透過 UI 新增可調整費率方案的通知

如要在 UI 中新增可調整費率方案的通知，請按照下列步驟操作：

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

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

  3. 如要設定其他通知條件，請按一下「+Add」，然後重複步驟 4。
  4. 在「Webhook」下方設定通知動作，請選取一或多個 Webhook，管理通知觸發時的回呼處理方式。
  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%)、交易次數 (100%) 或 1500 筆交易 (150%) 時通知他們。

  • 如要設定確切的百分比，請輸入 %= n。舉例來說，當目標次數百分比達到 80% 時，%= 80 就會傳送通知。
  • 如要設定百分比範圍，請輸入起始和結束百分比，以及要遞增的值，如下所示：%= start to end by n。例如，值為 %= 80 to 100 by 10 時，系統會在目標次數百分比達到 80%、90% 和 100% 時傳送通知。

如要設定通知動作，請在 actions 下方設定下列值。詳情請參閱通知動作的設定屬性。

屬性 價值
actionAttribute WEBHOOK：觸發 Webhook。
value 您在上一節定義的 Webhook ID：使用 API 建立 Webhook。

以下範例說明如何建立通知條件，在目標數量百分比達到 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 要求失敗。系統不會再次嘗試提出要求。