您目前查看的是 Apigee Edge 說明文件。
參閱 Apigee X說明文件。 資訊
什麼是 Webhook?
Webhook 會定義由事件觸發的 HTTP 回呼處理常式。您可以按照「使用通知範本設定通知」一文的說明,建立並設定 Webhook 來處理事件通知,做為使用營利通知範本的替代方案。
如要使用 Webhook 設定通知,請使用 Edge Management UI 或 Management and Monetization API 完成下列步驟:
管理 Webhook
新增及管理 Webhook,以使用 UI 或 API 定義通知事件的回呼處理常式。
使用 UI 管理 Webhook
新增和管理 Webhook,以使用 UI 定義通知事件的回呼處理常式,如以下各節所述。
探索 Webhook 頁面
按照下文說明存取 Webhook 頁面。
Edge
如要使用 Edge UI 存取 Webhook 頁面,請按照下列步驟操作:
- 登入 apigee.com/edge。
- 在左側導覽列中,依序選取「發布」>「營利」>「Webhook」。
系統隨即會顯示 Webhook 頁面。
如圖中所示,Webhook 頁面可讓您:
- 查看現有 Webhook 的詳細資料。
- 新增 Webhook。
- 啟用或停用、編輯或刪除 Webhook。
- 搜尋 Webhook 清單。
傳統版 Edge (Private Cloud)
如要使用傳統版 Edge UI 存取 Webhook 頁面,請按照下列步驟操作:
- 登入
http://ms-ip:9000
,其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。 依序選取「管理」>「Webhook」。
系統隨即顯示 Webhooks 頁面。
Webhook 頁面可讓您:
- 查看現有 Webhook 的詳細資料。
- 新增 Webhook。
- 啟用或停用、編輯或刪除 Webhook。
- 搜尋 Webhook 清單。
使用 UI 新增 Webhook
如要使用 UI 新增 Webhook,請執行下列操作:
- 前往 Webhook 頁面。
- 按一下「+ Webhook」。
- 輸入下列資訊 (所有欄位皆為必填)。
欄位 說明 名稱 Webhook 的名稱。 網址 觸發事件通知時,所呼叫的回呼處理常式網址。請參閱「設定回呼處理常式」。 - 按一下「儲存」。
Webhook 會加到清單中,並預設為啟用。
在 UI 中編輯 Webhook us
如要使用 UI 編輯 Webhook,請執行以下操作:
- 前往 Webhook 頁面。
- 將滑鼠遊標移到要編輯的 Webhook 上,然後按一下動作選單中的
。
- 視需要編輯 Webhook 欄位。
- 按一下「更新 Webhook」。
透過 UI 啟用或停用 Webhook
如要透過 UI 啟用或停用 Webhook,請執行下列操作:
- 前往 Webhook 頁面。
- 將遊標移到 Webhook 上,然後切換狀態切換按鈕來啟用或停用這項功能。
使用 UI 刪除 Webhook
如要使用 UI 刪除 Webhook,請執行下列操作:
- 前往 Webhook 頁面。
- 將遊標懸停在要刪除的 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 存取通知對話方塊:
- 按照「指定可調整的通知方案詳細資料」一節所述,建立及發布可調整的通知費率方案。
- 前往左側導覽列中的「發布」>「營利」>「費率方案」,前往「費率方案」頁面。
- 只要將遊標移到已發布的可調整通知率方案上,系統就會顯示動作。
- 按一下「+通知」。
畫面上會顯示「通知」對話方塊。
注意:費率方案必須先發布,「+ 通知」動作才會顯示。
傳統版 Edge (Private Cloud)
如要存取「通知」頁面,請按照下列步驟操作:
- 建立可調整的通知率方案,如「指定可調整的通知方案詳細資料」一節中所述。
- 依序選取「發布」>「檔案包」,即可查看費率方案。
- 在費率方案的「動作」欄中,按一下「+通知」。
畫面上會顯示「通知」對話方塊。
透過 UI 新增可調整費率方案的通知
如要在 UI 中新增可調整費率方案的通知,請按照下列步驟操作:
- 存取通知對話方塊。
- 指定您希望觸發通知的目標交易次數百分比,以設定「通知間隔」下方的通知條件。具體情況如下:
- 如要設定確切的百分比,請在「At/From %」欄位中輸入百分比,並將「To %」欄位留空。
- 如要設定百分比範圍,請分別在「At/From %」和「To %」欄位中輸入開始和結束百分比,並在「Step %」欄位中輸入遞增值。根據預設,系統會在指定範圍內傳送 10% 的通知給您。
Notify At
欄位會更新,反映會觸發事件的目標次數百分比。 - 如要設定其他通知條件,請按一下「+Add」,然後重複步驟 4。
- 在「Webhook」下方設定通知動作,請選取一或多個 Webhook,管理通知觸發時的回呼處理方式。
- 按一下「建立通知」。
透過 UI 編輯可調整費率方案的通知
如要在 UI 中編輯可調整費率方案的通知,請按照下列步驟操作:
- 存取通知對話方塊。
- 在費率方案的「動作」欄中,按一下「+通知」。
- 點選「編輯」。
- 視需要修改值。
- 按一下「儲存通知」。
透過 UI 刪除可調整費率方案的通知
如何刪除通知條件和動作:
- 存取通知對話方塊。
- 在費率方案的「動作」欄中,按一下「+通知」。
- 按一下「刪除通知」。
使用 API 設定可調整費率方案的通知
如要使用 API 為可調整費率方案設定通知,請按照使用 API 管理通知條件和動作一文所述的程序,並使用本節所述的屬性。
如要設定通知條件 (notificationCondition
),請使用下列屬性值。詳情請參閱通知條件的設定屬性。
屬性 | 價值 |
---|---|
RATEPLAN |
可調整通知費率方案的 ID。 |
PUBLISHED |
TRUE ,表示必須發布可調整的通知費率方案。 |
UsageTarget |
您希望觸發通知時的目標交易次數百分比。 這項屬性可讓您在開發人員即將達到或已經達到目標交易次數時,通知開發人員他們購買的可調整通知價目表方案。舉例來說,如果開發人員購買了可調整的通知費率方案,且開發人員的目標交易次數設為 1,000 筆,那麼您可以在達成 800 筆交易 (目標交易次數的 80%)、交易次數 (100%) 或 1500 筆交易 (150%) 時通知他們。
|
如要設定通知動作,請在 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 |
要求失敗。系統不會再次嘗試提出要求。 |