跳到主要內容

計量表

計量表用於定義和追蹤基於點數計費的使用量。它們代表您計費的特定功能或資源，例如 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 created:', meter);
  } catch (error) {
    console.error('Error creating meter:', 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('Retrieved meter:', meter);
  } catch (error) {
    console.error('Error retrieving meter:', 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 updated:', meter);
  } catch (error) {
    console.error('Error updating meter:', 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(`Found ${result.count} meters.`);
    console.log('Meters on this page:', result.list);
  } catch (error) {
    console.error('Error listing meters:', 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 ${meter.id} is now ${meter.status}.`);
  } catch (error) {
    console.error('Error activating meter:', 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 ${meter.id} is now ${meter.status}.`);
  } catch (error) {
    console.error('Error deactivating meter:', error.message);
  }
}

deactivateMeter('mtr_1J7kL2jQ6F9o3vXbY9t8rGcE');

建立和設定計量表後，下一步是報告使用量。請參閱 計量事件 文件以了解如何操作。