跳到主要内容

计量器

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

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

计量器对象

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

AttributeTypeDescription
idstring计量器的唯一标识符。
namestring计量器的显示名称。
event_namestring此计量器跟踪的事件的唯一名称。在报告使用情况时使用。
aggregation_methodstring用于聚合使用情况的方法。目前仅支持 sum。
unitstring使用情况的计量单位（例如，“requests”、“gb”、“credits”）。
statusstring计量器的当前状态。可以是 active 或 inactive。非活动状态的计量器不接受新事件。
livemodeboolean如果计量器是在生产模式下创建的，则为 true，测试模式则为 false。
currency_idstring与此计量器关联的支付货币的 ID。
descriptionstring计量器的可选描述。
metadataobject可以附加到对象的一组键值对。用于存储附加信息。
paymentCurrencyobject与计量器关联的展开的支付货币对象。

paymentCurrency 对象属性

AttributeTypeDescription
idstring货币的唯一标识符。
namestring货币的名称（例如，“API Credits”）。
symbolstring货币的符号（例如，“AC”）。
decimalnumber货币的小数位数。
typestring货币的类型。

创建计量器

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

参数

AttributeTypeDescription
namestring必需。 计量器的显示名称。最多 64 个字符。
event_namestring必需。 此计量器跟踪的事件的唯一名称。在报告使用情况时使用。最多 64 个字符。
unitstring必需。 使用情况的计量单位（例如，“requests”、“gb”、“credits”）。最多 32 个字符。
aggregation_methodstring可选。聚合使用情况的方法。默认为 sum。目前，这是唯一支持的值。
currency_idstring可选。要与此计量器关联的支付货币的 ID。如果未提供，将自动创建一个新的信用点货币。
descriptionstring可选。关于此计量器跟踪内容的描述。最多 255 个字符。
metadataobject可选。用于存储有关计量器的附加信息的一组键值对。

返回

返回新创建的 Meter 对象。

创建一个计量器

javascript
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();

响应示例

json
{
  "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 检索计量器。

参数

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

返回

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

检索一个计量器

javascript
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');

响应示例

json
{
  "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"
  }
}

更新计量器

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

参数

AttributeTypeDescription
idstring必需。 要更新的计量器的 ID。
namestring可选。计量器的新显示名称。
descriptionstring可选。计量器的更新描述。
statusstring可选。新状态。可以是 active 或 inactive。
unitstring可选。使用情况的新计量单位。
metadataobject可选。要在计量器上更新的一组键值对。

返回

返回更新后的 Meter 对象。

更新一个计量器

javascript
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');

响应示例

json
{
  "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"
  }
}

列出所有计量器

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

参数

AttributeTypeDescription
pagenumber可选。用于分页的页码，从 1 开始。默认为 1。
pageSizenumber可选。每页返回的项目数。默认为 20。
event_namestring可选。按特定事件名称筛选计量器。
livemodeboolean可选。按生产模式状态筛选计量器。
qstring可选。一个搜索查询字符串，根据匹配的 name 或 description 筛选结果。

返回

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

AttributeTypeDescription
countnumber与查询匹配的计量器总数。
listarray当前页的 Meter 对象数组。
pagingobject包含分页信息的对象（page、pageSize）。

列出所有计量器

javascript
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();

响应示例

json
{
  "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
  }
}

激活计量器

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

参数

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

返回

返回已激活的 Meter 对象。

激活一个计量器

javascript
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');

停用计量器

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

参数

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

返回

返回已停用的 Meter 对象。

停用一个计量器

javascript
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');

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