对象存储蓝图

跟踪客户上传到 S3、Google Cloud Storage、Azure Blob Storage 或其他对象存储的字节数，并按上传量向客户计费。

Object Storage Blueprint 会在客户每次上传文件时向 Dodo Payments 发送一个 usage event，其中包含上传的字节数。基于 bytes 的 Sum meter 会汇总每位客户的上传量，以便您据此计费。该 blueprint 包含在 @dodopayments/ingestion-blueprints npm package 中，名称为 trackObjectStorage()，并且支持 S3、Google Cloud Storage、Azure Blob Storage 及其他对象存储服务。

​

使用场景

Object Storage Blueprint 适用于以下场景：

File Hosting

根据客户上传文件的总量计费。

Backup Services

跟踪备份数据上传，并根据上传的数据量计费。

Media CDN

监控媒体上传，并根据上传量计费。如需根据传输带宽计费，请使用 Stream Blueprint。

Document Management

按客户跟踪文档上传量，以便进行基于用量的定价。

您可以使用它为文件托管、媒体 CDN 和备份服务按上传量计费。该 blueprint 统计的是上传的字节数，而不是一段时间内存储的字节数。

​

快速开始

要跟踪上传，请安装 package、创建 meter，并在每次成功上传后发送 event。

1. Install the SDK

   安装 Dodo Payments Ingestion Blueprints package：

   npm install @dodopayments/ingestion-blueprints
   
2. Get Your API Keys

   您需要两组 credentials：

   • Dodo Payments API key：在 Dodo Payments dashboard 中进入 Developer → API Keys 创建，并将其存储在 DODO_PAYMENTS_API_KEY 中。构建期间请使用 test mode key。test mode key 只能与 test_mode 搭配使用。
   • Storage provider credentials：您的 storage SDK 使用的 credentials，例如 AWS S3、Google Cloud Storage、Azure Blob Storage 或其他 provider 的 credentials。
3. Create a Meter

   在 Dodo Payments dashboard 中，进入 Products → Meters，然后点击 Create Meter。设置以下字段：

   • Meter Name：描述性名称，例如 Storage Uploads。
   • Event Name：object_storage_upload，或您选择的名称。它必须与代码中的 eventName 完全匹配（区分大小写）。
   • Aggregation Type：选择 Sum，以汇总上传的字节数。
   • Over Property：bytes，以便按上传大小计费。
   • Measurement Unit：发票上显示的单位，例如 bytes。
4. Track Storage Usage

   在 storage call 成功后发送 event。在这些示例中，失败的上传会在 trackObjectStorage() 运行前抛出异常，因此不会计费。

   AWS S3 Upload

   import { Ingestion, trackObjectStorage } from '@dodopayments/ingestion-blueprints';
   import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
   import fs from 'fs';
   
   const ingestion = new Ingestion({
     apiKey: process.env.DODO_PAYMENTS_API_KEY,
     environment: 'test_mode',
     eventName: 'object_storage_upload'
   });
   
   const s3 = new S3Client({ region: 'us-east-1' });
   
   // Read the file (example: from disk or request)
   const fileBuffer = fs.readFileSync('./document.pdf');
   
   // Upload to S3
   const command = new PutObjectCommand({
     Bucket: 'my-bucket',
     Key: 'uploads/document.pdf',
     Body: fileBuffer
   });
   
   await s3.send(command);
   
   // Track the upload
   await trackObjectStorage(ingestion, {
     customerId: 'cus_123',
     bytes: fileBuffer.length
   });
   

​

配置

​

Ingestion 配置

将以下 options 传递给 new Ingestion()：

apiKey · string · 必填

您在 dashboard 中获取的 Dodo Payments API key。

environment · string

Environment mode：test_mode 或 live_mode。默认值为 test_mode。不过，Dodo Payments SDKs 默认使用 live_mode，因此请在 production 中显式设置 live_mode。

eventName · string · 必填

与 meter 的 Event Name 匹配的 event name（区分大小写）。

​

跟踪 Object Storage 选项

将以下 options 传递给 trackObjectStorage()：

customerId · string · 必填

用于为此次上传计费的 Dodo Payments customer ID，例如 cus_123。

bytes · number

上传的字节数。基于字节计费时必须提供。如果省略此项，event 将没有 bytes value，但仍会计入 Count meter。

metadata · object

关于上传的可选 metadata，例如 bucket name 或 content type。每个 value 必须是 string、number 或 boolean。

​

最佳实践

在上传前或上传后跟踪：根据您的错误处理策略，您可以在实际上传前或上传后跟踪 event。

API 没有用于删除已 ingestion event 的 endpoint。如果在上传前发送 event，而上传随后失败，该 event 仍会保留在客户的 usage 中。

处理上传失败：仅跟踪成功的上传，以免为失败的操作计费。