使用 Webhook 設定通知

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。 資訊

什麼是 Webhook？

Webhook 會定義由事件觸發的 HTTP 回呼處理常式。你可以 除了使用 營利通知範本，請參閱這篇文章： 通知範本

如要使用 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 為以下應用程式) Management Server 節點的 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 (應用程式介面)

向 /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 要求到 /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 (應用程式介面)

向 /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，請發出 PUT 要求： /mint/organizations/{org_name}/webhooks/{webhook_id}。接著，將更新傳送至 請求。

舉例來說，下列指令會更新與 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

向以下位置發出 POST 要求，藉此啟用或停用 Webhook： /mint/organizations/{org_name}/webhooks/{webhook_id} 就像更新 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 (應用程式介面)

向以下位置發出 DELETE 要求，以刪除 Webhook： /mint/organizations/{org_name}/webhooks/{webhook_id}。

指定是否要強制刪除 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}"
}

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

使用 Webhook 為可調整的費率方案設定通知 UI 或 API：

透過 UI 設定可調整費率方案的通知

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

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

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

Edge

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

  1. 按照指定 可調整的通知方案詳細資料。
  2. 如要前往「費率方案」頁面，請依序選取「發布」>「發布」營利 >費率方案。
  3. 只要將遊標移到已發布的可調整通知率方案上，系統就會顯示動作。
  4. 按一下「+通知」。

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

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

傳統版 Edge (Private Cloud)

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

  1. 按照指定 可調整的通知方案詳細資料。
  2. 選取「發布」>「發布」套裝內容可查看費率方案。
  3. 在費率方案的「動作」欄中，按一下「+通知」。

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

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

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

  1. 存取通知對話方塊。
  2. 在「Notification Intervals」(通知間隔) 下方設定通知條件： 並指定要在何時 要觸發的通知詳細說明：
    • 如要設定確切百分比，請在「At/From %」欄位中輸入百分比 並將 [To %] 欄位留空。
    • 如要設定百分比範圍，請在 分別為 At/From % 和 To % 欄位，並遞增 值。預設會以 10% 的比例傳送通知 遞增。

    Notify At 欄位會更新，反映目標數量的每個百分比 觸發事件的交易

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

透過 UI 編輯可調整費率方案的通知

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

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

透過 UI 刪除可調整費率方案的通知

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

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

使用 API (應用程式介面)

如要使用 API 為可調整費率方案設定通知，請參閱 中所述的管理 通知條件及動作，並使用本節所述的屬性。

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

屬性 值
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%。

如要設定通知動作，請在 actions 下方設定下列值。適用對象 如需詳細資訊，請參閱設定 通知動作的屬性

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

以下範例說明如何建立可觸發 當目標次數達到 80%、90%、100%、110%、 120%

{
    "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 回應代碼及其解讀方式 有些人會將 Cloud Storage 視為檔案系統 但實際上不是

回應代碼 說明
2xx 成功
5xx

要求失敗。系統會在 5 分鐘內重試要求最多三次 間隔。

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