计量事件

计量事件用于报告按用量计费的使用情况。每个事件代表特定客户和计量器的单次使用实例。然后，这些事件将被处理，从客户的信用余额中扣除。此 API 允许您报告使用事件、检索其历史记录以及获取聚合统计信息。

在报告事件之前，您应定义一个计量器。有关更多信息，请参阅 计量器 API 参考。

计量事件对象#

计量事件对象代表一个已记录的单一使用事件。它包含有关用量、客户及其处理状态的详细信息。

属性	类型	描述
id	string	计量事件的唯一标识符。
event_name	string	事件的名称，与已定义的计量器相对应。
payload	object	包含事件核心详细信息的对象。
payload.customer_id	string	与此使用事件关联的客户 ID。
payload.value	string	要报告的使用量。
payload.subscription_id	string	（可选）此用量关联的订阅 ID。
identifier	string	事件的唯一标识符，用于幂等性。防止重复提交事件。
timestamp	number	事件发生时的 Unix 时间戳。
livemode	boolean	如果事件在生产模式下创建，则为 true；在测试模式下则为 false。
status	string	事件的处理状态。可以是 pending、processing、completed、requires_action、requires_capture 或 canceled。
processed_at	number	（可选）事件成功处理时的 Unix 时间戳。
attempt_count	number	此事件已尝试处理的次数。
next_attempt	number	（可选）下一次计划处理尝试的 Unix 时间戳。
credit_consumed	string	此事件处理后消耗的信用额度。
credit_pending	string	此事件待消耗的信用额度。
metadata	object	（可选）可以附加到事件对象的一组键值对。
created_via	string	事件的创建方式。可以是 api、dashboard、webhook 或 batch。
created_at	Date	事件记录的创建时间戳。
updated_at	Date	事件记录的最后更新时间戳。

创建事件#

向计量器报告一个使用事件。为确保事件不会被重复计算，您必须为每个事件提供一个唯一的 identifier。

参数

参数	类型	描述
event_name	string	您要为其报告用量的计量器的名称。
payload	object	使用事件的详细信息。
payload.customer_id	string	触发事件的客户 ID。
payload.value	string	要报告的使用数量。
payload.subscription_id	string	（可选）此用量应归属的订阅。
identifier	string	用于防止重复事件的唯一字符串。我们建议使用 V4 UUID。
timestamp	number	（可选）表示用量发生时间的 Unix 时间戳（以秒为单位）。如果未提供，则默认为当前时间。
metadata	object	（可选）与事件一起存储的键值数据。

返回

新创建的计量事件对象。

响应示例

检索事件#

通过其唯一 ID 检索现有计量事件的详细信息。

参数

Parameter	Type	Description
id	string	要检索的计量事件的唯一标识符。

返回

计量事件对象。

响应示例

列出事件#

返回计量事件的分页列表，可通过各种参数进行筛选。

参数

Parameter	Type	Description
event_name	string	（可选）按计量器名称筛选事件。
meter_id	string	（可选）按计量器 ID 筛选事件。
customer_id	string	（可选）筛选特定客户的事件。
start	number	（可选）一个 Unix 时间戳，用于筛选在此时间或之后创建的事件。
end	number	（可选）一个 Unix 时间戳，用于筛选在此时间之前创建的事件。
livemode	boolean	（可选）按生产模式或测试模式筛选。
q	string	（可选）用于筛选事件的搜索查询。
page	number	（可选）用于分页的页码，从 1 开始。
pageSize	number	（可选）每页的项目数。默认为 20。

返回

一个分页对象，包含项目总数 count 和计量事件对象列表 list。

响应示例

获取统计信息#

检索特定计量器在给定时间范围内的聚合统计信息。这对于构建仪表盘和报告非常有用。

参数

Parameter	Type	Description
meter_id	string	要检索统计信息的计量器 ID。
start	number	时间范围起点的 Unix 时间戳。
end	number	时间范围终点的 Unix 时间戳。
customer_id	string	（可选）筛选特定客户的统计信息。
granularity	string	（可选）统计信息的粒度。可以是 minute、hour 或 day。默认为 day。

返回

一个分页对象，包含 MeterEventStats 对象列表。列表中的每个对象代表指定粒度的一个数据点。

MeterEventStats 对象

属性	类型	描述
date	string	聚合数据点的日期（例如 '2023-03-15'）。
timestamp	string	该时段开始的 Unix 时间戳。
event_count	number	此期间内的事件总数。
total_value	string	此期间内所有事件 value 的总和。

响应示例

获取待处理金额#

计算给定客户或订阅的待处理计量事件的总价值，按货币分组。

参数

Parameter	Type	Description
subscription_id	string	（可选）用于筛选的订阅 ID。
customer_id	string	（可选）用于筛选的客户 ID。
currency_id	string	（可选）用于计算待处理金额的货币。

返回

一个 PendingAmountSummary 对象。

PendingAmountSummary 对象

属性	类型	描述
currency_id	string	待处理金额的货币。
total_pending	string	所有待处理事件的总价值。
count	number	待处理事件的数量。

响应示例

通过计量事件报告用量后，您可以通过信用额度管理客户如何支付此用量。要了解如何向客户发放信用额度，请参阅 信用额度发放 API 参考。