计量器

计量器用于定义和跟踪基于信用点的计费使用情况。它们代表您计费的特定功能或资源，例如 API 调用、数据存储或计算时间。每个计量器都会聚合发送给它的使用事件。

创建计量器后，您可以使用计量器事件来报告其使用情况。这是实现基于信用点的计费模型的核心组件。

计量器对象#

计量器对象包含有关特定使用情况跟踪器的所有信息。

Attribute

Type

Description

id

string

计量器的唯一标识符。

name

string

计量器的显示名称。

event_name

string

此计量器跟踪的事件的唯一名称。在报告使用情况时使用。

aggregation_method

string

用于聚合使用情况的方法。目前仅支持 sum。

unit

string

使用情况的计量单位（例如，“requests”、“gb”、“credits”）。

status

string

计量器的当前状态。可以是 active 或 inactive。非活动状态的计量器不接受新事件。

livemode

boolean

如果计量器是在生产模式下创建的，则为 true，测试模式则为 false。

currency_id

string

与此计量器关联的支付货币的 ID。

description

string

计量器的可选描述。

metadata

object

可以附加到对象的一组键值对。用于存储附加信息。

paymentCurrency

object

与计量器关联的展开的支付货币对象。

paymentCurrency 对象属性

Attribute

Type

Description

id

string

货币的唯一标识符。

name

string

货币的名称（例如，“API Credits”）。

symbol

string

货币的符号（例如，“AC”）。

decimal

number

货币的小数位数。

type

string

货币的类型。

创建计量器#

创建一个新的计量器来跟踪特定功能的使用情况。

参数

Attribute

Type

Description

name

string

必需。 计量器的显示名称。最多 64 个字符。

event_name

string

必需。 此计量器跟踪的事件的唯一名称。在报告使用情况时使用。最多 64 个字符。

unit

string

必需。 使用情况的计量单位（例如，“requests”、“gb”、“credits”）。最多 32 个字符。

aggregation_method

string

可选。聚合使用情况的方法。默认为 sum。目前，这是唯一支持的值。

currency_id

string

可选。要与此计量器关联的支付货币的 ID。如果未提供，将自动创建一个新的信用点货币。

description

string

可选。关于此计量器跟踪内容的描述。最多 255 个字符。

metadata

object

可选。用于存储有关计量器的附加信息的一组键值对。

返回

返回新创建的 Meter 对象。

创建一个计量器

import payment from '@blocklet/payment-js';

async function createMeter() {
  try {
    const meter = await payment.meters.create({
      name: 'API Calls',
      event_name: 'api.calls.v1',
      unit: 'requests',
      description: 'Tracks the number of API calls made.',
    });
    console.log('计量器已创建:', meter);
  } catch (error) {
    console.error('创建计量器时出错:', error.message);
  }
}

createMeter();

响应示例

{
  "id": "mtr_1J7kL2jQ6F9o3vXbY9t8rGcE",
  "name": "API Calls",
  "event_name": "api.calls.v1",
  "aggregation_method": "sum",
  "unit": "requests",
  "status": "active",
  "livemode": false,
  "currency_id": "pc_1J7kL2jQ6F9o3vXbY9t8rGcF",
  "description": "Tracks the number of API calls made.",
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "paymentCurrency": {
    "id": "pc_1J7kL2jQ6F9o3vXbY9t8rGcF",
    "name": "API Calls Credit",
    "symbol": "ACC",
    "decimal": 0,
    "type": "credit"
  }
}

检索计量器#

检索现有计量器的详细信息。您可以通过其唯一 ID 或 event_name 检索计量器。

参数

Attribute

Type

Description

id

string

必需。 要检索的计量器的 ID 或 event_name。

返回

如果找到，则返回 Meter 对象。

检索一个计量器

import payment from '@blocklet/payment-js';

async function retrieveMeter(meterId) {
  try {
    const meter = await payment.meters.retrieve(meterId);
    console.log('已检索计量器:', meter);
  } catch (error) {
    console.error('检索计量器时出错:', error.message);
  }
}

retrieveMeter('mtr_1J7kL2jQ6F9o3vXbY9t8rGcE');

响应示例

{
  "id": "mtr_1J7kL2jQ6F9o3vXbY9t8rGcE",
  "name": "API Calls",
  "event_name": "api.calls.v1",
  "aggregation_method": "sum",
  "unit": "requests",
  "status": "active",
  "livemode": false,
  "currency_id": "pc_1J7kL2jQ6F9o3vXbY9t8rGcF",
  "description": "Tracks the number of API calls made.",
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "paymentCurrency": {
    "id": "pc_1J7kL2jQ6F9o3vXbY9t8rGcF",
    "name": "API Calls Credit",
    "symbol": "ACC",
    "decimal": 0,
    "type": "credit"
  }
}

更新计量器#

通过设置传入参数的值来更新现有计量器。

参数

Attribute

Type

Description

id

string

必需。 要更新的计量器的 ID。

name

string

可选。计量器的新显示名称。

description

string

可选。计量器的更新描述。

status

string

可选。新状态。可以是 active 或 inactive。

unit

string

可选。使用情况的新计量单位。

metadata

object

可选。要在计量器上更新的一组键值对。

返回

返回更新后的 Meter 对象。

更新一个计量器

import payment from '@blocklet/payment-js';

async function updateMeter(meterId) {
  try {
    const meter = await payment.meters.update(meterId, {
      name: 'API Calls (V2)',
      description: 'Tracks V2 API calls.',
    });
    console.log('计量器已更新:', meter);
  } catch (error) {
    console.error('更新计量器时出错:', error.message);
  }
}

updateMeter('mtr_1J7kL2jQ6F9o3vXbY9t8rGcE');

响应示例

{
  "id": "mtr_1J7kL2jQ6F9o3vXbY9t8rGcE",
  "name": "API Calls (V2)",
  "event_name": "api.calls.v1",
  "aggregation_method": "sum",
  "unit": "requests",
  "status": "active",
  "livemode": false,
  "currency_id": "pc_1J7kL2jQ6F9o3vXbY9t8rGcF",
  "description": "Tracks V2 API calls.",
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:01:00.000Z",
  "paymentCurrency": {
    "id": "pc_1J7kL2jQ6F9o3vXbY9t8rGcF",
    "name": "API Calls Credit",
    "symbol": "ACC",
    "decimal": 0,
    "type": "credit"
  }
}

列出所有计量器#

返回计量器的分页列表。您可以根据各种条件筛选列表。

参数

Attribute

Type

Description

page

number

可选。用于分页的页码，从 1 开始。默认为 1。

pageSize

number

可选。每页返回的项目数。默认为 20。

event_name

string

可选。按特定事件名称筛选计量器。

livemode

boolean

可选。按生产模式状态筛选计量器。

q

string

可选。一个搜索查询字符串，根据匹配的 name 或 description 筛选结果。

返回

返回一个包含 Meter 对象列表的分页对象。

Attribute

Type

Description

count

number

与查询匹配的计量器总数。

list

array

当前页的 Meter 对象数组。

paging

object

包含分页信息的对象（page、pageSize）。

列出所有计量器

import payment from '@blocklet/payment-js';

async function listMeters() {
  try {
    const result = await payment.meters.list({
      pageSize: 5,
      livemode: false,
    });
    console.log(`找到 ${result.count} 个计量器。`);
    console.log('此页上的计量器:', result.list);
  } catch (error) {
    console.error('列出计量器时出错:', error.message);
  }
}

listMeters();

响应示例

{
  "count": 20,
  "list": [
    {
      "id": "mtr_1J7kL2jQ6F9o3vXbY9t8rGcE",
      "name": "API Calls",
      "event_name": "api.calls.v1",
      "status": "active",
      "livemode": false
    },
    {
      "id": "mtr_2K8mN3kR7G0p4wYcZ0u9sHdF",
      "name": "Data Storage",
      "event_name": "data.storage.gb",
      "status": "active",
      "livemode": false
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}

激活计量器#

激活一个非活动状态的计量器。激活后，该计量器将开始接受使用情况事件。

参数

Attribute

Type

Description

id

string

必需。 要激活的计量器的 ID。

返回

返回已激活的 Meter 对象。

激活一个计量器

import payment from '@blocklet/payment-js';

async function activateMeter(meterId) {
  try {
    const meter = await payment.meters.activate(meterId);
    console.log(`计量器 ${meter.id} 现在是 ${meter.status}。`);
  } catch (error) {
    console.error('激活计量器时出错:', error.message);
  }
}

activateMeter('mtr_some_inactive_meter_id');

停用计量器#

停用一个计量器。该计量器将停止接受新的使用情况事件，直到被重新激活。

参数

Attribute

Type

Description

id

string

必需。 要停用的计量器的 ID。

返回

返回已停用的 Meter 对象。

停用一个计量器

import payment from '@blocklet/payment-js';

async function deactivateMeter(meterId) {
  try {
    const meter = await payment.meters.deactivate(meterId);
    console.log(`计量器 ${meter.id} 现在是 ${meter.status}。`);
  } catch (error) {
    console.error('停用计量器时出错:', error.message);
  }
}

deactivateMeter('mtr_1J7kL2jQ6F9o3vXbY9t8rGcE');

创建和配置计量器后，下一步是报告使用情况。要了解如何操作，请参阅计量器事件文档。

Meter 事件
支付货币