> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 基于使用量的计费集成指南
> 了解如何设置计量器并发送使用事件，以便通过 Dodo Payments 实现准确的基于使用量的计费。
访问完整的 API 文档，用于摄取使用事件，并以互动方式测试事件摄取请求和响应。
浏览创建计量器的完整 API 文档，并以互动方式测试计量器创建请求和响应。
## 创建计量器
计量器定义了您的使用事件如何被聚合和测量以用于计费。
在创建计量器之前，请规划您的使用跟踪策略：
* 确定您想跟踪哪些使用事件
* 决定事件如何聚合（计数、求和等）
* 为特定用例定义任何过滤要求
### 逐步创建计量器
请遵循此综合指南以设置您的使用计量器：
设置计量器的基本信息。
选择一个清晰、描述性名称，以标识此计量器跟踪什么。
示例：“代币”、“API 调用”、“存储使用量”、“计算小时”
提供一个详细的说明，说明此计量器测量的内容。
示例：“计算每个客户发出的 POST /v1/orders 请求数”
指定将触发此计量器的事件标识符。
示例：“token”、“api.call”、“storage.usage”、“compute.session”
事件名称必须与您在使用事件中发送的内容完全匹配。事件名称区分大小写。
定义计量器如何从您的事件计算使用量。
选择事件应如何聚合：
仅计算接收到的事件数量。
使用案例：API 调用、页面浏览、文件上传
计算：事件总数
从事件中的一个特定属性汇总值。
使用案例：数据传输、存储消耗、处理时间
计算：所有属性值的总和
在计费期间记录一个特定属性的最高值。
使用案例：峰值并发用户、最大存储使用量、最高带宽
计算：观察到的最大属性值
使用一个特定属性的最新值。
使用案例：当前计划级别、最新配置设置
计算：最后记录的属性值
事件元数据中用于聚合的属性名称。
当使用 Sum、Max 或 Last 聚合类型时，该字段为必填字段。
定义用于报告和计费显示的单位标签。
示例：“calls”、“GB”、“hours”、“tokens”
设置标准以控制哪些事件包含在计量器中。
事件过滤允许您创建复杂规则，以确定哪些事件有助于您的使用计算。这对于排除测试事件，根据用户等级进行过滤或专注于特定操作非常有用。
**启用事件过滤**
切换 **启用事件过滤** 以激活条件事件处理。
**选择过滤逻辑**
选择如何评估多个条件：
所有条件必须为真才能计入事件。当您需要事件同时满足多个严格条件时使用此选项。
**示例：** 计算 API 调用，其中 `user_tier = "premium"` AND `endpoint = "/api/v2/users"`
至少一个条件必须为真才能计入事件。当您希望包括满足任何多个条件的事件时使用此选项。
**示例：** 计算事件，其中 `method = "POST"` OR `method = "PUT"` OR `method = "DELETE"`
**设置过滤条件**
点击 **添加条件** 来创建新过滤规则。
指定来自事件元数据的属性名称。
选择可用的操作符：
* `equals` - 精确匹配
* `not_equals` - 排除过滤器
* `greater_than` - 数字比较
* `greater_than_or_equals` - 数字比较（包含）
* `less_than` - 数字比较
* `less_than_or_equals` - 数字比较（包含）
* `contains` - 字符串包含子字符串
* `does_not_contain` - 字符串排除过滤器
设置比较的目标值。
使用 **添加组** 创建附加条件组，以实现复杂逻辑。
过滤属性必须包含在事件元数据中，以便条件正常工作。缺少所需属性的事件将被排除在计算之外。
检查您的计量器配置并点击 **创建计量器**。
您的计量器现已准备好接收和聚合使用事件。
## 链接计量器到产品
一旦您创建了计量器，您需要将其链接到产品以启用基于使用量的计费。此过程将计量器的使用数据与客户计费的定价规则连接起来。
将计量器链接到产品建立了使用跟踪和计费之间的连接：
* 产品定义定价规则和计费行为
* 计量器提供用于计费计算的使用数据
* 多个计量器可以链接到单个产品以实现复杂的计费场景
### 产品配置过程
通过正确配置产品设置将您的使用数据转换为可计费费用：
导航到您的产品创建或编辑页面并选择 **基于使用量** 作为产品类型。
点击 **关联计量器** 以从侧面打开计量器选择面板。
此面板允许您配置哪些计量器将跟踪此产品的使用情况。
在计量器选择面板中：
1. 点击 **添加计量器** 以查看可用计量器
2. 从下拉列表中选择您创建的计量器
3. 已选择的计量器将出现在您的产品配置中
为您的计量器跟踪的每个使用单位设置定价。
定义为您的计量器测量的每个单位收费多少。
**示例**：设置 `$0.50` 每单位意味着：
* 消费 1,000 单位 = 1,000 × \$0.50 = 500.00 收取
* 消费 500 单位 = 500 × \$0.50 = 250.00 收取
* 消费 100 单位 = 100 × \$0.50 = 50.00 收取
配置免费使用额度后才开始计费。
在开始计算付费使用之前，消费者可以免费消费的单元数。
**工作原理**：
* 免费阈值：100 个单位
* 每单位价格：\$0.50
* 客户使用量：250 单位
* **计算**： (250 - 100) × $0.50 = **$75.00\*\* 收取
免费阈值非常适合于免费增值模式、试用期或为客户提供计划中包含的基本津贴。
免费阈值适用于每个计费周期，每月或根据您的计费计划为客户提供新的津贴。
检查您的计量器和定价配置，然后点击 **保存更改** 以完成设置。
您的产品现已配置为基于使用量的计费，并将根据客户的实际消耗量自动收费。
**接下来会发生什么**：
* 发送到您的计量器的使用事件将被跟踪和聚合
* 计费计算将自动应用您的定价规则
* 客户将根据每个计费周期的实际消费量进行收费
请记住，每个产品最多可以添加 10 个计量器，从而实现复杂的使用跟踪跨多个维度，如 API 调用、存储、计算时间和自定义指标。
## 发送使用事件
配置计量器后，您可以开始从您的应用程序发送使用事件，以跟踪客户使用情况。
### 事件结构
每个使用事件必须包含以下必填字段：
此特定事件的唯一标识符。必须在所有事件中唯一。
该使用量应归属的 Dodo Payments 客户 ID。
与您的计量器配置匹配的事件名称。事件名称触发适当的计量器。
事件发生时间的 ISO 8601 时间戳。如果未提供，默认为当前时间。
用于过滤和聚合的附加属性。包括计量器中 "Over Property" 或过滤条件中引用的任何值。
### 使用事件 API 示例
使用事件 API 将使用事件发送到已配置的计量器：
```javascript Node.js theme={null}
const response = await fetch('https://test.dodopayments.com/events/ingest', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
events: [
{
event_id: "api_call_1234",
customer_id: "cus_atXa1lklCRRzMicTqfiw2",
event_name: "api.call",
timestamp: new Date().toISOString(),
metadata: {
endpoint: "/v1/orders",
method: "POST",
response_size: 1024
}
}
]
})
});
```
```python Python theme={null}
import requests
from datetime import datetime
response = requests.post(
'https://test.dodopayments.com/events/ingest',
headers={
'Authorization': f'Bearer {api_key}',
'Content-Type': 'application/json'
},
json={
'events': [
{
'event_id': 'api_call_1234',
'customer_id': 'cus_atXa1lklCRRzMicTqfiw2',
'event_name': 'api.call',
'timestamp': datetime.now().isoformat(),
'metadata': {
'endpoint': '/v1/orders',
'method': 'POST',
'response_size': 1024
}
}
]
}
)
```
```curl cURL theme={null}
curl -X POST 'https://test.dodopayments.com/events/ingest' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"events": [
{
"event_id": "api_call_1234",
"customer_id": "cus_atXa1lklCRRzMicTqfiw2",
"event_name": "api.call",
"timestamp": "2024-01-15T10:30:00Z",
"metadata": {
"endpoint": "/v1/orders",
"method": "POST",
"response_size": 1024
}
}
]
}'
```
## 基于使用量的计费分析
使用全面的分析仪表板监控和分析您的基于使用量的计费数据。跟踪客户消耗模式、计量器表现和计费趋势，以优化您的定价策略并理解使用行为。
### 概述分析
概述标签提供了您基于使用量的计费绩效的全面视图：
#### 活动指标
跟踪不同时间段的关键使用统计数据：
显示当前计费周期的使用活动，帮助您理解月度消耗模式。
展示自开始跟踪以来的累计使用统计数据，提供长期增长见解。
使用时间段选择器比较不同月份的使用情况，识别季节性趋势或增长模式。
#### 计量器数量图表
计量器数量图表以以下功能可视化时间的使用趋势：
* **时间序列可视化**：跟踪每天、每周或每月的使用模式
* **多计量器支持**：同时查看不同计量器的数据
* **趋势分析**：识别使用高峰、模式和增长轨迹
图表根据您的使用量和所选时间范围自动缩放，为细微波动和重大使用变化提供清晰的可见性。
### 事件分析
事件标签提供了个别使用事件的详细可见性：
#### 事件信息显示
事件表提供个体使用事件的清晰视图，具有以下列：
* **事件名称**：生成使用事件的具体动作或触发器
* **事件 ID**：每个事件实例的唯一标识符
* **客户 ID**：与事件关联的客户
* **时间戳**：事件发生的时间
此视图允许您跟踪和监控整个客户群的个体使用事件，为计费计算和使用模式提供透明度。
### 客户分析
客户标签提供详细的客户使用数据表视图，具有以下信息：
#### 可用数据列
客户用于标识的电子邮件地址。
客户订阅的唯一标识符。
在开始收费之前，客户计划中包含的免费单元数。
超出免费阈值的使用每单位成本。
客户最近一次使用事件的时间戳。
基于使用量计费向客户收取的总金额。
客户已消费的总单元数。
已超出免费阈值并被收费的单元数。
#### 表格功能
* **列过滤**：使用“编辑列”功能显示/隐藏特定数据列
* **实时更新**：使用数据反映最当前的消费指标
## 聚合示例
以下是不同聚合类型如何工作的实际示例：
### 理解聚合类型
不同的聚合类型适用于不同的计费场景。根据您想如何度量和收取使用量来选择合适的类型。
### 实际实施示例
这些示例展示了每种聚合类型的实际应用场景，包含样本事件和预期结果。
场景：跟踪 API 请求的总数
计量器配置：
* 事件名称：`api.call`
* 聚合类型：计数
* 测量单位：`calls`
**样本事件**：
```json theme={null}
{
"events": [
{"event_id": "call_1", "customer_id": "cus_123", "event_name": "api.call"},
{"event_id": "call_2", "customer_id": "cus_123", "event_name": "api.call"},
{"event_id": "call_3", "customer_id": "cus_123", "event_name": "api.call"}
]
}
```
结果：向客户计费 3 次调用
场景：基于传输的字节总数进行计费
计量器配置：
* 事件名称：`data.transfer`
* 聚合类型：求和
* 选择属性：`bytes`
* 测量单位：`GB`
**样本事件**：
```json theme={null}
{
"events": [
{
"event_id": "transfer_1",
"customer_id": "cus_123",
"event_name": "data.transfer",
"metadata": {"bytes": 1073741824}
},
{
"event_id": "transfer_2",
"customer_id": "cus_123",
"event_name": "data.transfer",
"metadata": {"bytes": 536870912}
}
]
}
```
结果：向客户计费 1.5 GB 总传输
场景：基于最高并发用户数进行计费
计量器配置：
* 事件名称：`concurrent.users`
* 聚合类型：最大
* 选择属性：`count`
* 测量单位：`users`
**样本事件**：
```json theme={null}
{
"events": [
{
"event_id": "peak_1",
"customer_id": "cus_123",
"event_name": "concurrent.users",
"metadata": {"count": 15}
},
{
"event_id": "peak_2",
"customer_id": "cus_123",
"event_name": "concurrent.users",
"metadata": {"count": 23}
},
{
"event_id": "peak_3",
"customer_id": "cus_123",
"event_name": "concurrent.users",
"metadata": {"count": 18}
}
]
}
```
结果：向客户计费 23 个峰值并发用户
### 事件过滤示例
仅计算特定端点的 API 调用：
过滤配置：
* 属性：`endpoint`
* 比较符：`equals`
* 值：`/v1/orders`
样本事件：
```json theme={null}
{
"event_id": "call_1",
"customer_id": "cus_123",
"event_name": "api.call",
"metadata": {
"endpoint": "/v1/orders",
"method": "POST"
}
}
```
结果：符合过滤条件的事件将被计算。具有不同端点的事件将被忽略。
仅计算大文件上传：
过滤配置：
* 属性：`file_size`
* 比较符：`greater_than`
* 值：`1048576` (1MB 的字节数)
样本事件：
```json theme={null}
{
"event_id": "upload_1",
"customer_id": "cus_123",
"event_name": "file.upload",
"metadata": {
"file_size": 5242880,
"file_type": "image"
}
}
```
结果：大于 1MB 的文件将被计算。较小的文件将被忽略。
仅计算营业时间的高级 API 调用：
过滤配置（使用 AND 逻辑）：
* 属性：`plan_type`, 比较符：`equals`, 值：`premium`
* 属性：`hour`, 比较符：`greater_than_or_equals`, 值：`9`
* 属性：`hour`, 比较符：`less_than`, 值：`17`
样本事件：
```json theme={null}
{
"event_id": "call_1",
"customer_id": "cus_123",
"event_name": "api.call",
"metadata": {
"plan_type": "premium",
"hour": 14,
"endpoint": "/v1/analytics"
}
}
```
结果：将计算营业时间内的高级 API 调用（上午 9 点 - 下午 5 点）。
## 故障排除
解决基于使用量的计费实施中的常见问题，确保准确跟踪和计费。
### 常见问题
大多数基于使用量的计费问题可以归为以下几类：
* 事件交付和处理问题
* 计量器配置问题
* 数据类型和格式错误
* 客户 ID 和认证问题
### 调试步骤
在对基于使用量的计费进行故障排除时：
1. 确认事件在事件分析标签中交付
2. 检查计量器配置与您的事件结构是否匹配
3. 验证客户 ID 和 API 认证
4. 审查过滤条件和聚合设置
### 解决方案和修复
常见原因：
* 事件名称与计量器配置不完全匹配
* 事件过滤条件排除了您的事件
* 客户 ID 不存在于您的 Dodo Payments 账户中
* 事件时间戳不在当前计费期间内
解决方案：
* 验证事件名称的拼写和大小写敏感性
* 审查并测试您的过滤条件
* 确认客户 ID 有效且活动
* 检查事件时间戳是否近期并正确格式化
常见原因：
* 选择属性名称与事件元数据键不匹配
* 元数据值的数据类型错误（字符串 vs 数字）
* 缺少必需的元数据属性
解决方案：
* 确保元数据键与您的选择属性设置完全匹配
* 将字符串数字转换为实际数字
* 包含每个事件的所有必需属性
常见原因：
* 过滤属性名称与事件元数据不匹配
* 错误的数据类型比较符（字符串 vs 数字）
* 字符串比较中的大小写敏感性
解决方案：
* 仔细检查属性名称是否完全匹配
* 使用适当的数据类型比较符
* 在过滤字符串时考虑大小写敏感性
## 相关 API 参考
用于创建和配置使用计量器以跟踪客户消耗的 API 参考
用于将使用事件发送到已配置的计量器以进行计费计算的 API 参考