API Reference — Events Ingestion
使用量イベントを取り込み、イベント取り込みリクエストとレスポンスをインタラクティブにテストするための、完全なAPIドキュメントにアクセスできます。
API Reference — Meters Creation
メーターを作成するための完全なAPIドキュメントを確認し、メーター作成リクエストとレスポンスをインタラクティブにテストできます。
メーターの作成
メーターは、課金目的で使用量イベントを集計・測定する方法を定義します。 メーターを作成する前に、使用量の追跡戦略を計画します。- 追跡する使用量イベントを特定する
- イベントの集計方法(count、sum など)を決定する
- 特定のユースケースに必要なフィルタリング要件を定義する
メーター作成の手順
このガイドに従って使用量メーターを設定します:1
Configure Basic Information
メーターの基本的な詳細を設定します。
string
必須
このメーターが追跡する対象を識別できる、明確で説明的な名前。例: “Tokens”、“API Calls”、“Storage Usage”、“Compute Hours”
string
このメーターが測定する内容の詳細な説明。例: “顧客が実行した各 POST /v1/orders リクエストをカウント”
string
必須
このメーターをトリガーするイベント識別子。例: “token”、“api.call”、“storage.usage”、“compute.session”
イベント名は、使用量イベントで送信する値と完全に一致する必要があります。イベント名では大文字と小文字が区別されます。
2
3
Configure Event Filtering (Optional)
メーターに含めるイベントを制御する条件を設定します。イベントフィルタリングを有効にするイベントフィルタリングを有効にするを切り替えて、条件付きイベント処理を有効にします。フィルターロジックを選択する複数の条件を評価する方法を選択します。フィルター条件を設定する
イベントフィルタリングを使用すると、使用量の計算に含めるイベントを決定する高度なルールを作成できます。テストイベントの除外、ユーザー tier によるフィルタリング、特定のアクションへの絞り込みなどに便利です。
- AND Logic
- OR Logic
イベントをカウントするには、すべての条件が true である必要があります。複数の厳密な条件を同時に満たすイベントが必要な場合に使用します。例:
user_tier = "premium" AND endpoint = "/api/v2/users" を満たす API 呼び出しをカウント1
Add Condition
Add conditionをクリックして、新しいフィルタールールを作成します。
2
Configure Property Key
イベントメタデータのプロパティ名を指定します。
3
Select Comparator
使用可能な演算子から選択します:
equals— 完全一致not_equals— 除外フィルターgreater_than— 数値比較greater_than_or_equals— 数値比較(包括)less_than— 数値比較less_than_or_equals— 数値比較(包括)contains— 文字列に部分文字列が含まれるかを確認does_not_contain— 文字列除外フィルター
4
Set Comparison Value
比較対象の値を設定します。
5
Add Groups
Add Groupを使用して、複雑なロジック用の追加の条件グループを作成します。
4
Create Meter
メーター設定を確認し、Create Meterをクリックします。
これでメーターは使用量イベントを受信して集計できる状態になりました。
ProductでのMeterのリンク
メーターを作成したら、従量課金を有効にするためにProductへリンクする必要があります。このプロセスにより、メーターの使用量データと顧客への請求に使用する料金ルールが関連付けられます。 メーターをProductにリンクすると、使用量の追跡と請求が連携されます:- Productは料金ルールと請求動作を定義します
- Meterは請求計算に使用する使用量データを提供します
- 複雑な請求シナリオでは、1つのProductに複数のMeterをリンクできます
Product設定のプロセス
Product設定を適切に構成して、使用量データを請求可能な料金に変換します:1
Choose Usage-Based Billing Product Type
Productの作成または編集ページに移動し、料金タイプとしてUsage Based Billingを選択します。
2
Select Associated Meter
Associated Metersをクリックして、メーター選択パネルを開きます。このパネルでは、このProductの使用量を追跡するMeterを設定できます。
3
Add Your Meter
メーター選択パネルで:
- Add Metersをクリックして使用可能なメーターを表示します
- ドロップダウンリストから作成したメーターを選択します
- 選択したメーターがProduct設定に表示されます
4
Configure Price Per Unit
メーターが追跡する使用量の各単位に対する料金を設定します。
number
必須
メーターで測定する各単位に対して請求する金額を定義します。例:1単位あたり$0.50に設定した場合:
- 1,000単位を消費 = 1,000 × $0.50 = $500.00を請求
- 500単位を消費 = 500 × $0.50 = $250.00を請求
- 100単位を消費 = 100 × $0.50 = $50.00を請求
5
Set Free Threshold (Optional)
請求を開始する前に、無料使用量の上限を設定します。
number
有料使用量の計算が始まる前に、顧客が無料で消費できる単位数。仕組み:
- 無料しきい値:100単位
- 単位あたりの料金:$0.50
- 顧客の使用量:250単位
- 計算:(250 - 100) × $0.50 = $75.00を請求
無料しきい値は、フリーミアムモデル、トライアル期間、またはプランに含まれる基本利用枠を顧客に提供する場合に適しています。
無料しきい値は各請求サイクルに適用されるため、顧客には毎月、または設定した請求スケジュールに応じて新しい利用枠が付与されます。
6
Save Configuration
メーターと料金設定を確認し、Save Changesをクリックして設定を確定します。次に行われること:
これでProductは従量課金用に設定され、測定した消費量に基づいて顧客に自動請求されます。
- メーターに送信された使用量イベントが追跡・集計されます
- 料金ルールが請求計算に自動適用されます
- 各請求サイクル中の実際の消費量に基づいて顧客に請求されます
1つのProductあたり最大50個のMeterを追加できるため、API呼び出し、ストレージ、コンピューティング時間、カスタムメトリクスなど、複数の観点にわたる高度な使用量追跡が可能です。
使用量イベントの送信
メーターを設定したら、アプリケーションから使用量イベントを送信して顧客の使用量を追跡できます。イベント構造
各使用量イベントには、次の必須フィールドを含める必要があります:string
必須
このイベントを一意に識別する識別子。すべてのイベント間で一意である必要があります。
string
必須
この使用量の帰属先となるDodo Paymentsの顧客ID。
string
必須
メーター設定と一致するイベント名。イベント名によって適切なメーターがトリガーされます。
string
イベント発生時刻のISO 8601タイムスタンプ。指定しない場合は現在のUTCタイムスタンプがデフォルトになります。過去1時間以内かつ未来5分以内である必要があり、この範囲外のタイムスタンプは拒否されます。
object
フィルタリングと集計に使用する追加プロパティ。メーターの「Over Property」またはフィルタリング条件で参照される値を含めます。
使用量イベントAPIの例
Events APIを使用して、設定済みのメーターに使用量イベントを送信します:信頼性の高い取り込みのために知っておくべき重要事項
本番環境で使用量追跡を正確かつ堅牢に維持するため、次の方法に従ってください。タイムスタンプを意図的に設定します。 リアルタイムイベントでは
timestampを省略すると、現在のUTCタイムスタンプがデフォルトで使用されます。遅延イベントやバッチイベントでは、正しい請求期間に使用量が反映されるよう、ISO 8601形式で明示的に設定します。許容範囲は狭く、1時間を超えて過去のイベント、または5分を超えて未来のイベントは拒否されます。過去データのバックフィルには対応していないため、バッファリングしたイベントは1時間以内にフラッシュしてください。従量課金の分析
包括的な分析ダッシュボードで従量課金データを監視・分析できます。顧客の消費パターン、メーターのパフォーマンス、請求の傾向を追跡して、料金戦略を最適化し、使用状況を把握します。概要分析
Overviewタブでは、従量課金のパフォーマンスを包括的に確認できます:アクティビティメトリクス
さまざまな期間にわたる主要な使用量統計を追跡します:metric
現在の請求期間の使用状況を表示し、月ごとの消費パターンを把握できます。
metric
追跡を開始してからの累積使用量統計を表示し、長期的な成長を把握できます。
メーター数量チャート

- 時系列の可視化:日、週、月ごとの使用パターンを追跡
- 複数メーターのサポート:異なるメーターのデータを同時に表示
- 傾向分析:使用量の急増、パターン、成長の軌跡を特定
チャートは使用量と選択した期間に基づいて自動的にスケールされるため、小さな変動から大きな使用量の変化まで明確に確認できます。
イベント分析

イベント情報の表示
イベントテーブルには、個々の使用量イベントについて次の列が表示されます:- Event Name:使用量イベントを生成した具体的なアクションまたはトリガー
- Event ID:各イベントインスタンスの一意の識別子
- Customer ID:イベントに関連付けられた顧客
- Timestamp:イベントが発生した時刻
このビューでは顧客全体の個々の使用量イベントを追跡・監視でき、請求計算と使用パターンを透明性のある形で確認できます。
顧客分析
Customersタブでは、次の情報を含む顧客使用量データの詳細なテーブルビューを確認できます:利用可能なデータ列
string
識別に使用する顧客のメールアドレス。
string
顧客のサブスクリプションの一意の識別子。
number
請求が適用される前に顧客のプランに含まれる無料単位数。
currency
無料しきい値を超えた使用量に対する単位あたりの料金。
timestamp
顧客の直近の使用量イベントのタイムスタンプ。
currency
従量課金で顧客に請求された合計金額。
number
顧客が消費した単位の合計数。
number
無料しきい値を超え、請求対象となる単位数。
テーブルの機能
- 列のフィルタリング:「Edit Columns」機能を使用して、特定のデータ列を表示または非表示にします
- リアルタイム更新:使用量データには最新の消費メトリクスが反映されます
集計の例
さまざまな集計タイプの動作を示す実用的な例を紹介します:集計タイプについて
集計タイプごとに適した請求シナリオが異なります。使用量をどのように測定し、請求するかに基づいて適切なタイプを選択してください。実装例
これらの例では、サンプルイベントと期待される結果を使用して、各集計タイプの実際の用途を説明します:Count Aggregation — API Calls
Count Aggregation — API Calls
シナリオ:APIリクエストの合計数を追跡するメーター設定:結果:3回の呼び出しを顧客に請求
- イベント名:
api.call - 集計タイプ:Count
- 測定単位:
calls
Sum Aggregation — Data Transfer
Sum Aggregation — Data Transfer
シナリオ:転送された合計バイト数に基づいて請求するメーター設定:結果:合計1.5 GBの転送を顧客に請求
- イベント名:
data.transfer - 集計タイプ:Sum
- Over Property:
bytes - 測定単位:
GB
Max Aggregation — Peak Concurrent Users
Max Aggregation — Peak Concurrent Users
シナリオ:同時接続ユーザー数の最大値に基づいて請求するメーター設定:結果:ピーク時の同時接続ユーザー23人を顧客に請求
- イベント名:
concurrent.users - 集計タイプ:Max
- Over Property:
count - 測定単位:
users
イベントフィルタリングの例
- Filter by API Endpoint
- Filter by Value Range
- Complex Multi-Condition Filters
特定のエンドポイントへのAPI呼び出しのみをカウントする:フィルター設定:結果:フィルター条件に一致するイベントがカウントされます。異なるエンドポイントのイベントは無視されます。
- プロパティ:
endpoint - 比較演算子:
equals - 値:
/v1/orders
トラブルシューティング
従量課金の実装に関する一般的な問題を解決し、正確な追跡と請求を実現します。一般的な問題
従量課金に関する問題の多くは、次のカテゴリに分類されます:- イベントの配信および処理の問題
- メーター設定の問題
- データ型と形式のエラー
- 顧客IDと認証の問題
デバッグ手順
従量課金のトラブルシューティングを行う場合:- Events分析タブでイベントの配信を確認します
- メーター設定がイベント構造と一致していることを確認します
- 顧客IDとAPI認証を検証します
- フィルタリング条件と集計設定を確認します
解決策と修正方法
Events not showing in meter
Events not showing in meter
一般的な原因:
- イベント名がメーター設定と完全には一致していない
- イベントフィルタリング条件によってイベントが除外されている
- 顧客IDがDodo Paymentsアカウントに存在しない
- イベントのタイムスタンプが現在の請求期間外である
- イベント名の綴りと大文字・小文字を確認します
- フィルタリング条件を見直してテストします
- 顧客IDが有効でアクティブであることを確認します
- イベントのタイムスタンプが新しく、適切な形式であることを確認します
Aggregation not working as expected
Aggregation not working as expected
一般的な原因:
- Over Property名がイベントメタデータのキーと一致していない
- メタデータの値のデータ型が間違っている(文字列と数値)
- 必須メタデータプロパティが不足している
- メタデータキーがOver Property設定と完全に一致していることを確認します
- イベント内の文字列形式の数値を実際の数値に変換します
- すべてのイベントに必須プロパティを含めます
Filtering not working
Filtering not working
一般的な原因:
- フィルタープロパティ名がイベントメタデータと一致していない
- データ型に対して比較演算子が間違っている(文字列と数値)
- 文字列比較で大文字と小文字が区別されている
- プロパティ名が完全に一致していることを再確認します
- データ型に適した比較演算子を使用します
- 文字列をフィルタリングする際は大文字と小文字の区別を考慮します
関連APIリファレンス
Create Meter
顧客の消費量を追跡するための使用量メーターの作成と設定に関するAPIリファレンス。
Ingest Usage Events
請求計算のために設定済みのメーターへ使用量イベントを送信するためのAPIリファレンス。