使用网络钩子设置通知

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。信息

什么是 webhook？

Webhook 用于定义由事件触发的 HTTP 回调处理程序。您可以创建 webhook 并将其配置为处理事件通知，这是一种替代使用创收通知模板的方法，如使用通知模板设置通知中所述。

如需使用 webhook 设置通知，请使用 Edge Management 界面或 Management and Monetization API 完成以下步骤：

  1. 使用界面或 API 添加用于定义通知事件回调处理程序的 webhook。
  2. 设置回调处理程序。
  3. 使用界面或 API 设置可调整费率方案的通知。

管理 webhook

添加和管理使用界面或 API 为通知事件定义回调处理程序的网络钩子。

使用界面管理 webhook

使用界面添加和管理用于定义通知事件的回调处理脚本的 webhook，如以下部分所述。

探索网络钩子页面

访问“Webhook”页面，如下所述。

Edge

如需使用 Edge 界面访问网络钩子页面，请执行以下操作：

  1. 登录 apigee.com/edge。
  2. 在左侧导航栏中，依次选择发布 > 创收 > 网络钩子。

此时将显示 Webhook 页面。

如图所示，您可以通过“Webhook”页面执行以下操作：

传统边缘（私有云）

如需使用传统 Edge 界面访问网络钩子页面，请执行以下操作：

  1. 登录 http://ms-ip:9000，其中 ms-ip 是管理服务器节点的 IP 地址或 DNS 名称。

  2. 依次选择管理 > 网络钩子。

系统会显示“Webhook”页面。

通过 Webhook 页面，您可以：

使用界面添加 webhook

如需使用界面添加 webhook，请执行以下操作：

  1. 访问“Webhook”页面。
  2. 点击 + 网络钩子。
  3. 请输入以下信息（所有字段均为必填字段）。
    字段 说明
    名称 webhook 的名称。
    网址 在触发事件通知时要调用的回调处理程序的网址。请参阅设置回调处理脚本。
  4. 点击保存。

该 webhook 会添加到列表中，并默认处于启用状态。

使用界面修改 Webhook

如需使用界面修改 webhook，请执行以下操作：

  1. 访问“Webhook”页面。
  2. 将光标置于要修改的 Webhook 上，然后点击操作菜单中的 。
  3. 根据需要修改 webhook 字段。
  4. 点击更新 Webhook。

使用界面启用或停用 webhook

如需使用界面启用或停用某个 webhook，请执行以下操作：

  1. 访问 Webhook 页面。
  2. 将光标放在网络钩子上，切换状态开关即可启用或停用网络钩子。

使用界面删除 webhook

如需使用界面删除某个 webhook，请执行以下操作：

  1. 访问“Webhook”页面。
  2. 将光标放在要删除的网络钩子上，然后点击 。

该 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 请求来查看单个网络钩子。

例如：

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

向 /mint/organizations/{org_name}/webhooks/{webhook_id} 发出 PUT 请求，以修改 webhook。在请求正文中传递更新。

例如，以下代码会更新与 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 请求来启用或停用网络钩子，然后将请求正文中的已启用属性分别设置为 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

设置回调处理程序

以下示例展示了在触发事件通知时发送到 webhook 定义的回调处理程序的 JSON 请求的格式。您必须确保回调处理程序正确处理请求。

{
        "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}"
}

为可调价方案设置通知

使用界面或 API 为可调整费率方案使用 webhook 设置通知。

使用界面为可调整费率方案设置通知

使用界面为可调整费率方案使用网络钩子设置通知，如下所述。

访问可调价方案的“通知”对话框

访问可调整费率方案的“通知”对话框，如下所述。

Edge

如需使用 Edge 界面访问通知对话框，请执行以下操作：

  1. 按照指定可调整的通知计划详细信息中所述，创建并发布可调整的通知频率方案。
  2. 在左侧导航栏中依次选择发布 > 创收 > 费率方案，访问“费率方案”页面。
  3. 将光标悬停在已发布的可调节通知费率方案上，以显示操作。
  4. 点击 +通知。

    系统会显示“通知”对话框。

    注意：您必须先发布费率方案，系统才会显示“+ 通知”操作。

传统边缘（私有云）

如需访问“通知”页面，请执行以下操作：

  1. 创建可调节的通知费率方案，如指定可调节的通知方案详情中所述。
  2. 依次选择发布 > 文件包以查看费率方案。
  3. 点击费率方案“操作”列中的 + 通知。

    系统会显示“通知”对话框。

使用界面为可调整费率方案添加通知

如需在界面中为可调整费率方案添加通知，请执行以下操作：

  1. 访问“通知”对话框。
  2. 在通知间隔时间下方设置通知条件，通过指定触发通知时目标交易量的百分比来设置条件。具体而言：
    • 如需设置确切百分比，请在 At/From % 字段中输入百分比，并将 To % 字段留空。
    • 要设置百分比范围，请分别在开始时间/开始百分比和结束百分比字段中输入开始百分比和结束百分比，并在步骤 % 字段中输入增量值。默认情况下，在指定范围内以 10% 为增量发送通知。

    系统会更新 Notify At 字段，以反映将触发事件的目标交易数量的各个百分比。

  3. 如需设置其他通知条件，请点击 + 添加，然后重复第 4 步。
  4. 在 Webhook 下设置通知操作，选择一个或多个 Webhook 以管理在触发通知时如何处理回调。
  5. 点击创建通知。

使用界面修改可调整费率方案的通知

如需在界面中修改可调整费率方案的通知，请执行以下操作：

  1. 访问“通知”对话框。
  2. 点击相应费率方案的“操作”列中的 +Notify（通知）。
  3. 点击修改。
  4. 根据需要修改值。
  5. 点击保存通知。

使用界面删除可调整费率方案的通知

要删除通知条件和操作，请执行以下操作：

  1. 访问“通知”对话框。
  2. 点击费率方案“操作”列中的 + 通知。
  3. 点击删除通知。

使用 API 为可调整费率方案设置通知

如需使用 API 为可调整费率方案设置通知，请使用使用 API 管理通知条件和操作中所述的流程，并使用本部分中所述的属性。

如需设置通知条件 (notificationCondition)，请使用以下属性值。如需了解详情，请参阅通知条件的配置属性。

属性 值
RATEPLAN 可调整通知费率方案的 ID。
PUBLISHED TRUE，用于指示必须发布可调整的通知频率方案。
UsageTarget 您希望触发通知时达到的目标交易次数的百分比。

借助此属性，您可以通知开发者，当他们购买的可调节通知率卡券方案的目标交易量即将达到或已达到时。例如，如果开发者购买了可调整的通知速率方案，并且开发者的目标交易量已设为 1,000 笔，那么当开发者的交易量达到 800 笔（目标交易量的 80%）、1,000 笔（100%）或 1,500 笔（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",
        }]
  }

如需了解如何查看、更新和删除通知条件和操作，请参阅：

网络钩子响应代码

以下是网络钩子响应代码及其由系统解读的方式的摘要。

响应代码 说明
2xx 成功
5xx

请求失败。系统每隔 5 分钟最多会重试三次请求。

注意 ：webhook 请求的读取和连接超时时间为 3 秒，这可能会导致请求失败。
Other response 请求失败。系统不会重试该请求。