API 参考

计量器

计量器用于跟踪基于积分计费的用量事件。您可以创建计量器来表示特定的计费操作或资源，然后记录这些计量器的事件。这使您能够实现基于用量的定价模型，即根据客户的消耗量进行计费。
有关实施积分计费的实践指南，请参阅积分计费指南。
Meter 对象#一个 Meter 对象包含有关特定用量计量器的所有信息。
属性
类型
描述
id
string
计量器的唯一标识符。
object
string
对象类型，始终为 "meter"。
name
string
计量器的名称，会向用户显示。
event_name
string
此计量器所跟踪事件的唯一名称。上报用量时使用。
aggregation_method
string
指定如何聚合用量事件。可以是 sum（求和）、count（计数）或 last（取最新值）。
status
string
计量器的当前状态。可以是 active（激活）或 inactive（非激活）。
unit
string
用量的计量单位（例如，requests、gb_hours）。
description
string
计量器的可选描述。
livemode
boolean
如果计量器处于生产模式，则为 true；如果处于测试模式，则为 false。
currency_id
string
与此计量器关联的货币 ID（如果适用）。
metadata
object
一组可以附加到对象的键值对。
created_at
date
计量器创建时的时间戳。
updated_at
date
计量器上次更新时的时间戳。
paymentCurrency
object
一个包含关联货币详细信息的扩展对象。仅在设置了 currency_id 时存在。
paymentCurrency 对象#属性
类型
描述
id
string
货币的唯一标识符。
name
string
货币的全名（例如，“US Dollar”）。
symbol
string
货币的符号（例如，“$”）。
decimal
number
货币的小数位数。
type
string
货币的类型。
创建计量器#创建一个新的计量器来跟踪特定类型的用量。
参数
名称
类型
描述
name
string
必需。 计量器的显示名称。
event_name
string
必需。 所跟踪事件的唯一机器可读名称。
unit
string
必需。 用量的计量单位。
aggregation_method
'sum' | 'count' | 'last'
聚合用量数据的方法。默认为 sum。
currency_id
string
要与此计量器关联的现有货币的 ID。
description
string
计量器的可选描述。
metadata
Record<string, any>
用于提供附加信息的可选键值对集合。
返回
返回新创建的 Meter 对象。
示例
async function createMeter() {
  try {
    const meter = await payment.meters.create({
      name: 'API Calls',
      event_name: 'api.calls.count',
      unit: 'call',
      aggregation_method: 'count',
      description: 'Counts the number of API calls made.'
    });
    console.log('已创建计量器：', meter);
  } catch (error) {
    console.error('创建计量器时出错：', error);
  }
}

createMeter();响应示例
{
  "id": "mtr_1234567890",
  "object": "meter",
  "name": "API Calls",
  "event_name": "api.calls.count",
  "aggregation_method": "count",
  "status": "active",
  "unit": "call",
  "description": "Counts the number of API calls made.",
  "livemode": false,
  "metadata": {},
  "currency_id": null,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}检索计量器#通过其唯一 ID 检索现有计量器的详细信息。
参数
名称
类型
描述
id
string
必需。 要检索的计量器的 ID。
返回
如果找到，则返回 Meter 对象。
示例
async function retrieveMeter(meterId) {
  try {
    const meter = await payment.meters.retrieve(meterId);
    console.log('已检索计量器：', meter);
  } catch (error) {
    console.error('检索计量器时出错：', error);
  }
}

retrieveMeter('mtr_1234567890');响应示例
{
  "id": "mtr_1234567890",
  "object": "meter",
  "name": "API Calls",
  "event_name": "api.calls.count",
  "aggregation_method": "count",
  "status": "active",
  "unit": "call",
  "description": "Counts the number of API calls made.",
  "livemode": false,
  "metadata": {},
  "currency_id": null,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}更新计量器#更新现有计量器的信息。
参数
名称
类型
描述
id
string
必需。 要更新的计量器的 ID。
data
object
必需。 包含要更新字段的对象。
data.name
string
计量器的新名称。
data.description
string
计量器的新描述。
data.status
'active' | 'inactive'
计量器的新状态。
data.metadata
Record<string, any>
要更新的键值对集合。
返回
返回更新后的 Meter 对象。
示例
async function updateMeter(meterId) {
  try {
    const meter = await payment.meters.update(meterId, {
      description: 'Total number of API calls made by a customer.',
      metadata: { 'version': '2.0' }
    });
    console.log('已更新计量器：', meter);
  } catch (error) {
    console.error('更新计量器时出错：', error);
  }
}

updateMeter('mtr_1234567890');响应示例
{
  "id": "mtr_1234567890",
  "object": "meter",
  "name": "API Calls",
  "event_name": "api.calls.count",
  "aggregation_method": "count",
  "status": "active",
  "unit": "call",
  "description": "Total number of API calls made by a customer.",
  "livemode": false,
  "metadata": {
    "version": "2.0"
  },
  "currency_id": null,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:05:00.000Z"
}列出所有计量器#返回所有计量器的分页列表。您可以使用提供的参数筛选列表。
参数
名称
类型
描述
event_name
string
按特定事件名称筛选计量器。
livemode
boolean
按生产模式状态筛选计量器。
q
string
用于在 name 和 description 等计量器字段中搜索的查询字符串。
page
number
用于分页的页码。
pageSize
number
每页返回的项目数。默认为 20。
order
string | string[]
结果的排序顺序。示例：['created_at', 'DESC']。
返回
返回一个分页对象，其中包含一个 Meter 对象列表和计量器总数。
示例
async function listMeters() {
  try {
    const meters = await payment.meters.list({ pageSize: 5 });
    console.log(`找到 ${meters.count} 个计量器。`);
    console.log('第一页计量器：', meters.list);
  } catch (error) {
    console.error('列出计量器时出错：', error);
  }
}

listMeters();响应示例
{
  "count": 15,
  "list": [
    {
      "id": "mtr_1234567890",
      "object": "meter",
      "name": "API Calls",
      "event_name": "api.calls.count",
      "aggregation_method": "count",
      "status": "active",
      "unit": "call",
      "description": "Total number of API calls made by a customer.",
      "livemode": false,
      "metadata": {
        "version": "2.0"
      },
      "currency_id": null,
      "created_at": "2023-10-27T10:00:00.000Z",
      "updated_at": "2023-10-27T10:05:00.000Z"
    }
  ]
}激活计量器#将计量器的状态设置为 active。激活的计量器可用于记录用量事件。
参数
名称
类型
描述
id
string
必需。 要激活的计量器的 ID。
返回
返回状态更新为 active 的 Meter 对象。
示例
async function activateMeter(meterId) {
  try {
    const meter = await payment.meters.activate(meterId);
    console.log('计量器已激活：', meter.status);
  } catch (error) {
    console.error('激活计量器时出错：', error);
  }
}

activateMeter('mtr_0987654321');响应示例
{
  "id": "mtr_0987654321",
  "object": "meter",
  "name": "Data Storage",
  "event_name": "data.storage.gb",
  "aggregation_method": "last",
  "status": "active",
  "unit": "gb",
  "livemode": false,
  // ... other attributes
}停用计量器#将计量器的状态设置为 inactive。非激活的计量器不能用于记录新的用量事件。
参数
名称
类型
描述
id
string
必需。 要停用的计量器的 ID。
返回
返回状态更新为 inactive 的 Meter 对象。
示例
async function deactivateMeter(meterId) {
  try {
    const meter = await payment.meters.deactivate(meterId);
    console.log('计量器已停用：', meter.status);
  } catch (error) {
    console.error('停用计量器时出错：', error);
  }
}

deactivateMeter('mtr_1234567890');响应示例
{
  "id": "mtr_1234567890",
  "object": "meter",
  "name": "API Calls",
  "event_name": "api.calls.count",
  "aggregation_method": "count",
  "status": "inactive",
  "unit": "call",
  "livemode": false,
  // ... other attributes
}
现在您已了解如何管理计量器，下一步是上报其用量。请继续阅读 计量事件 API 参考，了解具体操作方法。

属性	类型	描述
`id`	`string`	计量器的唯一标识符。
`object`	`string`	对象类型，始终为 `"meter"`。
`name`	`string`	计量器的名称，会向用户显示。
`event_name`	`string`	此计量器所跟踪事件的唯一名称。上报用量时使用。
`aggregation_method`	`string`	指定如何聚合用量事件。可以是 `sum`（求和）、`count`（计数）或 `last`（取最新值）。
`status`	`string`	计量器的当前状态。可以是 `active`（激活）或 `inactive`（非激活）。
`unit`	`string`	用量的计量单位（例如，`requests`、`gb_hours`）。
`description`	`string`	计量器的可选描述。
`livemode`	`boolean`	如果计量器处于生产模式，则为 `true`；如果处于测试模式，则为 `false`。
`currency_id`	`string`	与此计量器关联的货币 ID（如果适用）。
`metadata`	`object`	一组可以附加到对象的键值对。
`created_at`	`date`	计量器创建时的时间戳。
`updated_at`	`date`	计量器上次更新时的时间戳。
`paymentCurrency`	`object`	一个包含关联货币详细信息的扩展对象。仅在设置了 `currency_id` 时存在。

属性	类型	描述
`id`	`string`	货币的唯一标识符。
`name`	`string`	货币的全名（例如，“US Dollar”）。
`symbol`	`string`	货币的符号（例如，“$”）。
`decimal`	`number`	货币的小数位数。
`type`	`string`	货币的类型。

名称	类型	描述
`name`	`string`	必需。计量器的显示名称。
`event_name`	`string`	必需。所跟踪事件的唯一机器可读名称。
`unit`	`string`	必需。用量的计量单位。
`aggregation_method`	`'sum' \| 'count' \| 'last'`	聚合用量数据的方法。默认为 `sum`。
`currency_id`	`string`	要与此计量器关联的现有货币的 ID。
`description`	`string`	计量器的可选描述。
`metadata`	`Record<string, any>`	用于提供附加信息的可选键值对集合。

名称	类型	描述
`id`	`string`	必需。要更新的计量器的 ID。
`data`	`object`	必需。包含要更新字段的对象。
`data.name`	`string`	计量器的新名称。
`data.description`	`string`	计量器的新描述。
`data.status`	`'active' \| 'inactive'`	计量器的新状态。
`data.metadata`	`Record<string, any>`	要更新的键值对集合。

名称	类型	描述
`event_name`	`string`	按特定事件名称筛选计量器。
`livemode`	`boolean`	按生产模式状态筛选计量器。
`q`	`string`	用于在 `name` 和 `description` 等计量器字段中搜索的查询字符串。
`page`	`number`	用于分页的页码。
`pageSize`	`number`	每页返回的项目数。默认为 20。
`order`	`string \| string[]`	结果的排序顺序。示例：`['created_at', 'DESC']`。

概述

快速入门

核心概念

使用指南

API 参考

TypeScript 支持

计量器

Meter 对象#

paymentCurrency 对象#

创建计量器#

检索计量器#

更新计量器#

列出所有计量器#

激活计量器#

停用计量器#

设置

计量事件