使用网络钩子设置通知

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

什么是网络钩子?

网络钩子用于定义由事件触发的 HTTP 回调处理程序。您可以创建网络钩子并配置它们来处理事件通知,作为使用创收通知模板的替代方案,如使用通知模板设置通知中所述。

如需使用网络钩子设置通知,请使用边缘管理界面或 Management and Monetize API 完成以下步骤:

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

管理网络钩子

使用界面API 添加和管理用于为通知事件定义回调处理程序的 webhook。

使用界面管理网络钩子

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

探索“Webhook”页面

访问“网络钩子”页面,如下所述。

Edge

如需使用 Edge 界面访问“网络钩子”页面,请执行以下操作:

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

随即将显示“Webhook”页面。

如图所示,借助 Webhook 页面,您可以执行以下操作:

传统 Edge (Private Cloud)

如需使用传统版 Edge 界面访问“网络钩子”页面,请执行以下操作:

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

此时将显示“Webhook”页面。

通过“Webhook”页面,您可以执行以下操作:

使用界面添加 webhook

如需使用界面添加网络钩子,请执行以下操作:

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

Webhook 已添加到列表中,并且默认处于启用状态。

使用界面修改网络钩子

如需使用界面修改网络钩子,请执行以下操作:

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

使用界面启用或停用网络钩子

如需使用界面启用或停用网络钩子,请执行以下操作:

  1. 访问“网络钩子”页面
  2. 将光标放在该网络钩子上,然后切换状态开关以启用或停用它。

使用界面删除网络钩子

如需使用界面删除 webhook,请执行以下操作:

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

该网络钩子即会从列表中移除。

使用 API 管理 webhook

按照下文所述,使用 API 添加和管理网络钩子。

使用 API 查看所有网络钩子

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

例如,以下代码会创建一个名为 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} 发出 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 启用或停用网络钩子

通过向 /mint/organizations/{org_name}/webhooks/{webhook_id} 发出 POST 请求来启用或停用网络钩子,方法与更新网络钩子时相同,并分别将请求正文中的 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 删除 webhook

通过向 /mint/organizations/{org_name}/webhooks/{webhook_id} 发出 DELETE 请求来删除网络钩子。

如需指定是否在有正在进行的进程时强制删除 webhook,请将 forceDelete 查询参数设置为 truefalseforceDelete 查询参数默认处于启用状态 (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 (Private Cloud)

如需访问“通知”页面,请按以下步骤操作:

  1. 按照指定可调整的通知方案详细信息中的说明,创建可调整的通知费率方案。
  2. 依次选择发布 > 软件包以查看费率方案。
  3. 在该费率方案的“操作”列中点击 +通知

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

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

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

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

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

  3. 要设置其他通知条件,请点击 +添加并重复第 4 步。
  4. 选择一个或多个 webhook,以管理触发通知时的回调处理,从而在 Webhook 下设置通知操作。
  5. 点击创建通知

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

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

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

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

如需删除通知条件和操作,请执行以下操作:

  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% 时触发 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 请求失败。系统不会重试请求。