本頁面由 Cloud Translation API 翻譯而成。

使用 Webhook 設定通知

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。資訊

什麼是 Webhook？

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

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

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

管理 Webhook

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

使用 UI 管理 Webhook

請按照下列各節所述，新增及管理 Webhook，以便使用 UI 為通知事件定義回呼處理常式。

探索 Webhook 頁面
使用 UI 新增 Webhook
使用 UI 編輯 Webhook
使用 UI 刪除 Webhook

探索 Webhook 頁面

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

Edge

如何使用 Edge UI 存取 Webhook 頁面：

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

系統隨即會顯示「Webhooks」頁面。

如圖所示，Webhook 頁面可讓您進行以下作業：

查看現有 Webhook 的詳細資料。
新增 Webhook。
啟用或停用、編輯或刪除 Webhook。
搜尋 Webhook 清單。

傳統邊緣 (Private Cloud)

如何使用傳統版 Edge UI 存取 Webhook 頁面：

登入 http://ms-ip:9000，其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。
依序選取「Admin」>「Webhooks」。

系統隨即會顯示「Webhooks」頁面。

您可以透過 Webhook 頁面執行下列操作：

查看現有 Webhook 的詳細資料。
新增 Webhook。
啟用或停用、編輯或刪除 Webhook。
搜尋 Webhook 清單。

使用 UI 新增 Webhook

如何使用 UI 新增 Webhook：

前往 Webhook 頁面。
按一下「+ Webhook」。

輸入下列資訊 (所有欄位均為必填)。

欄位	說明
名稱	Webhook 的名稱。
網址	觸發事件通知時要呼叫的回呼處理常式網址。請參閱「設定回呼處理常式」。

點按「儲存」。

Webhook 就會加入清單並預設為啟用。

在使用者介面中編輯 Webhook

如何透過 UI 編輯 Webhook：

前往 Webhook 頁面。
將滑鼠遊標移到要編輯的 Webhook 上，然後按一下動作選單中的。
視需要編輯 Webhook 欄位。
按一下「更新 Webhook」。

透過 UI 啟用或停用 Webhook

如要透過 UI 啟用或停用 Webhook，請按照下列步驟操作：

前往 Webhook 頁面。
將遊標移到 Webhook 上，然後切換狀態切換按鈕來啟用或停用這項功能。

使用 UI 刪除 Webhook

如何使用使用者介面刪除 Webhook：

前往 Webhook 頁面。
將遊標移到要刪除的 Webhook 上，然後按一下「」。

系統會刪除 Webhook 並從清單中移除。

使用 API 管理 Webhook

請按照下列各節所述，使用 API 新增及管理 Webhook。

使用 API 查看所有 Webhook
使用 API 查看 Webhook
使用 API 新增 Webhook
使用 API 編輯 Webhook
使用 API 刪除 Webhook

使用 API 查看所有 Webhook

如要查看所有 Webhook，請向 /mint/organizations/{org_name}/webhooks 發出 GET 要求。例如：

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} 發出 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

向 /mint/organizations/{org_name}/webhooks/{webhook_id} 發出 POST 要求來啟用或停用 Webhook，方法與更新 Webhook 相同，並將要求主體中的已啟用屬性分別設為 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

設定回呼處理常式

下方顯示 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 為可調整費率方案設定通知，方法如下所述。

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

查看可調整費率方案的「通知」對話方塊，如下所述。

Edge

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

按照「指定可調整的通知方案詳細資料」一節所述，建立及發布可調整通知費率方案。
如要存取「費率方案」頁面，請在左側導覽列中依序選取「發布」>「營利」>「費率方案」。
將滑鼠遊標移到已發布的可調整通知費率方案上，即可顯示動作。
按一下「+通知」。

系統隨即會顯示「通知」對話方塊。
注意：您必須發布費率方案，「+ 通知」動作才會顯示。

傳統邊緣 (Private Cloud)

存取「通知」頁面：

按照「指定可調整的通知方案詳細資料」一節所述，建立可調整通知費率方案。
依序選取「發布」>「套裝方案」，查看房價方案。
在費率方案的「動作」欄中，按一下「+ 通知」。

系統隨即會顯示「通知」對話方塊。

透過使用者介面為可調整費率方案新增通知

如何在使用者介面為可調整費率方案新增通知：

存取通知對話方塊。
在「通知間隔」下方設定通知條件，方法是指定要觸發通知的交易目標交易數量百分比。具體違規事項如下：
- 如要設定確切的百分比，請在「At/From %」欄位中輸入百分比，並將「To %」欄位留空。
- 如要設定百分比範圍，請在「At/From %」和「To %」欄位中分別輸入開始和結束百分比，並在「Step %」欄位中填入增量值。根據預設，通知會在指定範圍內以 10% 的增量傳送。
系統會更新 Notify At 欄位，以反映觸發事件的目標交易數量百分比。
如要設定其他通知條件，請按一下「+Add」(+新增)，然後重複步驟 4。
選取一或多個 Webhook，在觸發通知時管理回呼處理方式，即可在「Webhook」下方設定通知動作。
按一下「建立通知」。

透過使用者介面編輯可調整費率方案的通知

如要編輯可調整費率方案的通知，請在使用者介面中執行以下操作：

存取通知對話方塊。
在費率方案的「動作」欄中，按一下「+ 通知」。
按一下「編輯」。
視需要修改值。
按一下「儲存通知」。

透過使用者介面刪除可調整費率方案的通知

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

存取通知對話方塊。
在費率方案的「動作」欄中，按一下「+ 通知」。
按一下「刪除通知」。

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

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

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

屬性值

RATEPLAN 可調整通知費率方案的 ID。

PUBLISHED TRUE：表示必須發布可調整通知費率方案。

屬性	值
`RATEPLAN`	可調整通知費率方案的 ID。
`PUBLISHED`	`TRUE`：表示必須發布可調整通知費率方案。
`UsageTarget`	指定觸發通知的交易數量目標百分比。對於已購買的可調整通知價目表方案，如果開發人員接近或已達到交易目標次數，您可以利用這項屬性通知他們。舉例來說，如果開發人員購買了可調整通知費率方案，且開發人員的目標交易次數設為 1000，您就可以在他們交易量達 800 筆 (目標交易次數的 80%)、1000 筆交易 (100%) 或 1500 筆交易 (150%) 時通知他們。如要設定確切的百分比，請輸入 `%= n`。舉例來說，`%= 80` 會在交易目標數量達到 80% 時傳送通知。如要設定百分比範圍，請輸入開始和結束百分比，以及要遞增的值，如下所示：`%= start to end by n`。舉例來說，值 `%= 80 to 100 by 10` 會在目標交易次數的百分比達到 80%、90% 和 100% 時傳送通知。

UsageTarget

指定觸發通知的交易數量目標百分比。

對於已購買的可調整通知價目表方案，如果開發人員接近或已達到交易目標次數，您可以利用這項屬性通知他們。舉例來說，如果開發人員購買了可調整通知費率方案，且開發人員的目標交易次數設為 1000，您就可以在他們交易量達 800 筆 (目標交易次數的 80%)、1000 筆交易 (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 成功

回應代碼	說明
`2xx`	成功
`5xx`	要求失敗。系統會以 5 分鐘的時間間隔最多重試該要求三次。注意： Webhook 要求的讀取和連線逾時均為 3 秒，這可能會導致要求失敗。
`Other response`	要求失敗。系統不會重試要求。

5xx

要求失敗。系統會以 5 分鐘的時間間隔最多重試該要求三次。

注意： Webhook 要求的讀取和連線逾時均為 3 秒，這可能會導致要求失敗。

Other response 要求失敗。系統不會重試要求。