使用网络钩子设置通知

您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 信息

什么是网络钩子？

webhook 定义由事件触发的 HTTP 回调处理程序。除了使用创收通知模板之外，您还可以按照使用通知模板设置通知中的说明，创建网络钩子并配置网络钩子来处理事件通知。

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

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

管理 webhook

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

使用界面管理 webhook

添加和管理使用界面为通知事件的回调处理程序定义回调处理程序的网络钩子，如以下部分所述。

探索网络钩子页面

访问 Webhook 页面，如下所述。

Edge

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

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

此时将显示 Webhook 页面。

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

传统 Edge（私有云）

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

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

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

此时将显示 Webhook 页面。

通过 Webhook 页面，您可以：

使用界面添加 webhook

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

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

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

使用界面修改网络钩子

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

  1. 访问 Webhook 页面。
  2. 将光标悬停在要修改的网络钩子上，然后点击操作菜单中的 。
  3. 根据需要修改 webhook 字段。
  4. 点击更新 Webhook。

使用界面启用或停用 webhook

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

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

使用界面删除 webhook

如需使用 theUI 删除 webhook，请执行以下操作：

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

系统即会删除该 webhook，并将其从列表中移除。

使用 API 管理 webhook

按照以下部分所述，使用 API 添加和管理网络钩子。

使用 API 查看所有 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 请求来查看单个网络钩子。

例如：

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。您必须传递网络钩子的名称以及触发事件通知时调用的回调处理程序的网址。

例如，以下命令会创建一个名为 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。如果停用网络钩子，则事件发生时将不会触发网络钩子。

例如，以下命令会启用 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，请将 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，使用网络钩子设置可调整费率方案的通知。

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

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

访问“通知”对话框，查看可调整的价格方案

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

Edge

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

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

    此时会显示“通知”对话框。

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

传统 Edge（私有云）

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

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

    此时会显示“通知”对话框。

使用界面添加关于可调整费率方案的通知

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

  1. 访问“通知”对话框。
  2. 在通知间隔下设置通知条件，只需指定您希望触发通知时目标事务数的百分比。具体而言：
    • 要设置精确百分比，请在以/从 % 字段中输入百分比，并将到 % 字段留空。
    • 要设置百分比范围，请分别在开始/从 % 和到 % 字段中输入开始百分比和结束百分比，并在步骤 % 字段中输入增量值。默认情况下，在指定范围内以 10% 为增量发送通知。

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

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

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

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

  1. 访问“通知”对话框。
  2. 点击费率方案“操作”列中的 + 通知。
  3. 点击修改。
  4. 根据需要修改值。
  5. 点击 Save Notification。

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

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

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

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

要使用 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，用于触发网络钩子。
value 您在上一部分（使用 API 创建 webhook）中定义的 webhook 的 ID。

以下示例展示了如何创建通知条件，以在目标事务数的百分比达到 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",
        }]
  }

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

网络钩子响应代码

下文总结了网络钩子响应代码以及系统如何解读这些代码。

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

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

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