メインコンテンツへスキップ

メーター

メーターは、クレジットベースの請求のための使用量を定義し、追跡するために使用されます。APIコール、データストレージ、計算時間など、課金対象となる特定の機能やリソースを表します。各メーターは、送信された使用量イベントを集計します。

メーターを作成すると、メーターイベントを使用して使用量を報告できます。これは、クレジットベースの請求モデルを実装するためのコアコンポーネントです。

Meterオブジェクト

Meterオブジェクトには、特定の利用状況トラッカーに関するすべての情報が含まれています。

属性タイプ説明
idstringメーターの一意の識別子。
namestringメーターの表示名。
event_namestringこのメーターが追跡するイベントの一意の名前。使用量を報告する際に使用されます。
aggregation_methodstring使用量を集計するために使用されるメソッド。現在、sumのみがサポートされています。
unitstring使用量の測定単位（例：'requests'、'gb'、'credits'）。
statusstringメーターの現在のステータス。active または inactive にすることができます。非アクティブなメーターは新しいイベントを受け付けません。
livemodebooleanメーターがライブモードで作成された場合は true、テストモードの場合は false。
currency_idstringこのメーターに関連付けられている支払い通貨のID。
descriptionstringメーターのオプションの説明。
metadataobjectオブジェクトに添付できるキーと値のペアのセット。追加情報を保存するのに便利です。
paymentCurrencyobjectメーターに関連付けられている展開された支払い通貨オブジェクト。

paymentCurrency オブジェクトのプロパティ

属性タイプ説明
idstring通貨の一意の識別子。
namestring通貨の名前（例：'API Credits'）。
symbolstring通貨のシンボル（例：'AC'）。
decimalnumber通貨の小数点以下の桁数。
typestring通貨のタイプ。

メーターの作成

特定の機能の使用量を追跡するための新しいメーターを作成します。

パラメータ

属性タイプ説明
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 で取得できます。

パラメータ

属性タイプ説明
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"
  }
}

メーターの更新

渡されたパラメータの値を設定して、既存のメーターを更新します。

パラメータ

属性タイプ説明
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"
  }
}

すべてのメーターを一覧表示

メーターのページ分割されたリストを返します。さまざまな基準に基づいてリストをフィルタリングできます。

パラメータ

属性タイプ説明
pagenumber任意。ページネーションのためのページ番号。1から始まります。デフォルトは1です。
pageSizenumber任意。ページごとに返すアイテムの数。デフォルトは20です。
event_namestring任意。特定のイベント名でメーターをフィルタリングします。
livemodeboolean任意。ライブモードのステータスでメーターをフィルタリングします。
qstring任意。name または description に一致する結果をフィルタリングする検索クエリ文字列。

戻り値

Meter オブジェクトのリストを含むページ分割されたオブジェクトを返します。

属性タイプ説明
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
  }
}

メーターのアクティブ化

非アクティブなメーターをアクティブ化します。アクティブ化されると、メーターは使用量イベントの受け入れを開始します。

パラメータ

属性タイプ説明
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');

メーターの非アクティブ化

メーターを非アクティブ化します。メーターは再アクティブ化されるまで、新しい使用量イベントの受け入れを停止します。

パラメータ

属性タイプ説明
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');

メーターを作成して設定した後の次のステップは、使用量を報告することです。詳細については、メーターイベントのドキュメントを参照してください。