使用网络钩子设置通知

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

什么是 Webhook？

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

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

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

管理 webhook

使用 UI 或 API 添加和管理用于定义通知事件的回调处理程序的 Webhook。

使用界面管理 Webhook

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

浏览“Webhook”页面

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

Edge

如需使用 Edge 界面访问“Webhook”页面，请执行以下操作：

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

系统会显示“Webhook”页面。

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

经典边缘（私有云）

如需使用经典版 Edge 界面访问“Webhook”页面，请执行以下操作：

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

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

系统会显示“Webhook”页面。

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

使用界面添加网络钩子

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

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

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

使用界面修改网络钩子

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

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

使用界面启用或停用 webhook

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

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

使用界面删除 Webhook

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

  1. 访问“网络钩子”页面。
  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 查看网络钩子

通过向 /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 修改网络钩子

通过向 /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 启用或停用网络钩子

通过向 /mint/organizations/{org_name}/webhooks/{webhook_id} 发出 POST 请求（与更新网络钩子时一样），并根据需要在请求正文中将 enabled 属性设置为 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

如需删除 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}"
}

为浮动利率方案设置通知

使用 UI 或 API 为可调费率方案设置使用 Webhook 的通知。

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

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

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

按照以下说明访问可调费率方案的“通知”对话框。

Edge

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

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

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

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

经典边缘（私有云）

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

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

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

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

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

  1. 访问“通知”对话框。
  2. 在通知间隔下设置通知条件，方法是指定在达到目标交易数量的某个百分比时触发通知。具体而言：
    • 如需设置确切的百分比，请在 At/From %（起始百分比）字段中输入该百分比，并将 To %（结束百分比）字段留空。
    • 如需设置百分比范围，请分别在 At/From % 和 To % 字段中输入起始百分比和结束百分比，并在 Step % 字段中输入增量值。默认情况下，系统会以 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 您希望在达到目标交易数量的百分之多少时触发通知。

此属性可让您在开发者即将达到或已达到其购买的可调整通知费率卡方案的目标交易次数时通知他们。例如，如果某开发者购买了可调整的通知费率方案，并且已将该开发者的目标交易次数设置为 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 以触发网络钩子。
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 请求失败。系统不会重试请求。