Skip to main content

API Reference - Events Ingestion

Truy cập đầy đủ tài liệu API để nhập sự kiện sử dụng và kiểm tra các yêu cầu và phản hồi nhập sự kiện một cách tương tác.

API Reference - Meters Creation

Khám phá toàn bộ tài liệu API để tạo đồng hồ đo và kiểm tra tương tác các yêu cầu và phản hồi tạo đồng hồ đo.

Tạo một đồng hồ đo

Các đồng hồ đo xác định cách các sự kiện sử dụng của bạn được tổng hợp và đo lường cho mục đích thanh toán. Trước khi tạo một đồng hồ đo, hãy lập kế hoạch chiến lược theo dõi mức sử dụng của bạn:
  • Xác định các sự kiện sử dụng mà bạn muốn theo dõi
  • Xác định cách các sự kiện nên được tổng hợp (đếm, tổng, v.v.)
  • Định nghĩa bất kỳ yêu cầu lọc nào cho các trường hợp sử dụng cụ thể

Quy trình tạo đồng hồ đo từng bước

Theo dõi hướng dẫn toàn diện này để thiết lập đồng hồ đo sử dụng của bạn:
1

Configure Basic Information

Thiết lập các thông tin cơ bản cho đồng hồ đo của bạn.
string
bắt buộc
Chọn một tên rõ ràng, dễ hiểu để xác định đồng hồ đo này đang theo dõi điều gì.Ví dụ: “Tokens”, “API Calls”, “Storage Usage”, “Compute Hours”
string
Cung cấp giải thích chi tiết về những gì đồng hồ đo này đang đo lường.Ví dụ: “Đếm mỗi yêu cầu POST /v1/orders do khách hàng thực hiện”
string
bắt buộc
Xác định định danh sự kiện sẽ kích hoạt đồng hồ đo này.Ví dụ: “token”, “api.call”, “storage.usage”, “compute.session”
Tên sự kiện phải khớp chính xác với những gì bạn gửi trong các sự kiện sử dụng của mình. Tên sự kiện phân biệt chữ hoa chữ thường.
2

Configure Aggregation Settings

Xác định cách đồng hồ đo tính toán việc sử dụng từ các sự kiện của bạn.
string
bắt buộc
Chọn cách sự kiện nên được tổng hợp:
Đơn giản là đếm số sự kiện đã nhận.Trường hợp sử dụng: Các cuộc gọi API, lượt xem trang, tải tệpPhép tính: Tổng số sự kiện
string
Tên thuộc tính từ siêu dữ liệu sự kiện để tổng hợp trên đó.
Trường này bắt buộc khi sử dụng các loại tổng hợp Sum, Max hoặc Last.
string
bắt buộc
Xác định nhãn đơn vị để hiển thị trong báo cáo và thanh toán.Ví dụ: “calls”, “GB”, “hours”, “tokens”
3

Configure Event Filtering (Optional)

Thiết lập tiêu chí để kiểm soát sự kiện nào được bao gồm trong đồng hồ đo.
Lọc sự kiện cho phép bạn tạo ra các quy tắc tinh vi quyết định sự kiện nào góp phần vào việc tính toán sử dụng. Điều này hữu ích để loại trừ sự kiện thử nghiệm, lọc theo tầng người dùng hoặc tập trung vào hành động cụ thể.
Kích hoạt lọc sự kiệnBật Kích hoạt lọc sự kiện để kích hoạt xử lý sự kiện có điều kiện.Chọn logic lọcChọn cách nhiều điều kiện được đánh giá:
Tất cả điều kiện phải đúng để một sự kiện được tính. Dùng khi bạn cần sự kiện đáp ứng nhiều tiêu chí nghiêm ngặt cùng lúc.Ví dụ: Đếm các cuộc gọi API nơi user_tier = "premium" AND endpoint = "/api/v2/users"
Thiết lập điều kiện lọc
1

Add Condition

Nhấn Add condition để tạo quy tắc bộ lọc mới.
2

Configure Property Key

Chỉ định tên thuộc tính từ siêu dữ liệu sự kiện của bạn.
3

Select Comparator

Chọn từ các toán tử có sẵn:
  • equals - Khớp chính xác
  • not_equals - Bộ lọc loại trừ
  • greater_than - So sánh số
  • greater_than_or_equals - So sánh số (bao gồm)
  • less_than - So sánh số
  • less_than_or_equals - So sánh số (bao gồm)
  • contains - Chuỗi chứa chuỗi con
  • does_not_contain - Bộ lọc loại trừ chuỗi
4

Set Comparison Value

Đặt giá trị mục tiêu để so sánh.
5

Add Groups

Dùng Add Group để tạo nhóm điều kiện bổ sung cho logic phức tạp.
Các thuộc tính được lọc phải có trong siêu dữ liệu sự kiện để các điều kiện hoạt động chính xác. Các sự kiện thiếu thuộc tính bắt buộc sẽ bị loại khỏi việc tính toán.
4

Create Meter

Xem lại cấu hình đồng hồ đo và nhấn Create Meter.
Đồng hồ đo của bạn giờ đã sẵn sàng nhận và tổng hợp các sự kiện sử dụng.

Liên kết đồng hồ đo trong một sản phẩm

Khi bạn đã tạo đồng hồ đo của mình, bạn cần liên kết nó với một sản phẩm để kích hoạt thanh toán dựa trên mức sử dụng. Quy trình này kết nối dữ liệu sử dụng của đồng hồ đo với các quy tắc định giá cho việc thanh toán của khách hàng. Liên kết các đồng hồ đo với các sản phẩm thiết lập kết nối giữa theo dõi mức sử dụng và thanh toán:
  • Các sản phẩm xác định các quy tắc định giá và hành vi thanh toán
  • Các đồng hồ đo cung cấp dữ liệu sử dụng cho các phép tính thanh toán
  • Nhiều đồng hồ đo có thể được liên kết với một sản phẩm duy nhất cho các kịch bản thanh toán phức tạp

Quy trình cấu hình sản phẩm

Biến dữ liệu sử dụng của bạn thành các khoản phí có thể tính bằng cách cấu hình đúng cài đặt sản phẩm của bạn:
1

Choose Usage-Based Billing Product Type

Đi tới trang tạo hoặc chỉnh sửa sản phẩm của bạn và chọn Usage-Based làm loại sản phẩm.
2

Select Associated Meter

Nhấn vào Associated Meter để mở bảng chọn đồng hồ đo từ bên cạnh.Bảng này cho phép bạn cấu hình những đồng hồ đo sẽ theo dõi việc sử dụng cho sản phẩm này.
3

Add Your Meter

Trong bảng chọn đồng hồ đo:
  1. Nhấp vào Thêm đồng hồ đo để xem các đồng hồ đo có sẵn
  2. Chọn đồng hồ đo bạn đã tạo từ danh sách thả xuống
  3. Đồng hồ đo đã chọn sẽ xuất hiện trong cấu hình sản phẩm của bạn
4

Configure Price Per Unit

Đặt giá cho mỗi đơn vị sử dụng được đồng hồ đo ghi nhận.
number
bắt buộc
Xác định mức phí cho mỗi đơn vị mà đồng hồ đo đo được.Ví dụ: Thiết lập $0.50 cho mỗi đơn vị có nghĩa là:
  • 1.000 đơn vị tiêu thụ = 1.000 × $0.50 = 500.00 được tính phí
  • 500 đơn vị tiêu thụ = 500 × $0.50 = 250.00 được tính phí
  • 100 đơn vị tiêu thụ = 100 × $0.50 = 50.00 được tính phí
5

Set Free Threshold (Optional)

Cấu hình mức sử dụng miễn phí trước khi bắt đầu tính phí.
number
Số đơn vị mà khách hàng có thể sử dụng miễn phí trước khi bắt đầu tính phí theo sử dụng trả tiền.Cách hoạt động:
  • Ngưỡng miễn phí: 100 đơn vị
  • Giá mỗi đơn vị: $0.50
  • Khách hàng sử dụng: 250 đơn vị
  • Phép tính: (250 - 100) × 0.50=0.50 = **75.00** được tính phí
Ngưỡng miễn phí lý tưởng cho mô hình freemium, thời gian dùng thử hoặc cung cấp một mức cho phép cơ bản trong gói của khách hàng.
Ngưỡng miễn phí áp dụng cho mỗi chu kỳ thanh toán, mang đến cho khách hàng hạn mức mới hàng tháng hoặc theo lịch trình thanh toán của bạn.
6

Save Configuration

Xem lại cấu hình đồng hồ đo và định giá, sau đó nhấn Save Changes để hoàn tất thiết lập.
Sản phẩm của bạn giờ đã được cấu hình cho thanh toán theo mức sử dụng và sẽ tự động tính phí khách hàng dựa trên mức tiêu thụ thực tế.
Điều gì sẽ xảy ra tiếp theo:
  • Các sự kiện sử dụng gửi tới đồng hồ đo sẽ được theo dõi và tổng hợp
  • Các phép tính thanh toán sẽ tự động áp dụng quy tắc định giá của bạn
  • Khách hàng sẽ bị tính phí dựa trên mức tiêu thụ thực tế trong mỗi chu kỳ thanh toán
Hãy nhớ rằng bạn có thể thêm tối đa 10 đồng hồ đo cho mỗi sản phẩm, cho phép theo dõi sử dụng tinh vi trên nhiều chiều như cuộc gọi API, lưu trữ, thời gian tính toán và các chỉ số tùy chỉnh.

Gửi sự kiện sử dụng

Khi đồng hồ đo của bạn đã được cấu hình, bạn có thể bắt đầu gửi các sự kiện sử dụng từ ứng dụng của mình để theo dõi mức sử dụng của khách hàng.

Cấu trúc sự kiện

Mỗi sự kiện sử dụng phải bao gồm các trường bắt buộc sau:
string
bắt buộc
Định danh duy nhất cho sự kiện cụ thể này. Phải là duy nhất trên tất cả các sự kiện.
string
bắt buộc
ID khách hàng Dodo Payments mà việc sử dụng này thuộc về.
string
bắt buộc
Tên sự kiện trùng với cấu hình đồng hồ đo của bạn. Tên sự kiện kích hoạt đồng hồ đo tương ứng.
string
Dấu thời gian ISO 8601 khi sự kiện xảy ra. Mặc định là thời gian hiện tại nếu không cung cấp.
object
Các thuộc tính bổ sung để lọc và tổng hợp. Bao gồm mọi giá trị được tham chiếu trong thiết lập “Over Property” hoặc các điều kiện lọc của đồng hồ đo của bạn.

Ví dụ API sự kiện sử dụng

Gửi các sự kiện sử dụng đến các đồng hồ đo đã cấu hình của bạn bằng cách sử dụng API Sự kiện:

Những điều quan trọng cần biết để thu thập dữ liệu đáng tin cậy

Hãy tuân thủ các phương pháp này để việc theo dõi mức sử dụng luôn chính xác và ổn định trong môi trường production.
Sử dụng các event_id mang tính xác định và idempotent. event_id phải là duy nhất trên tất cả các event và đóng vai trò là idempotency key — event_id được sử dụng lại sẽ bị xem là bản trùng lặp và không được tính lại, vì vậy việc retry sẽ không dẫn đến tính phí hai lần. Hãy suy ra ID từ action thay vì sử dụng giá trị ngẫu nhiên, ví dụ `${customer_id}_${action}_${timestamp}`.
Gộp các event, tối đa 1.000 event trong mỗi request. Endpoint /events/ingest áp dụng giới hạn cứng là 1.000 event cho mỗi lần gọi; các batch lớn hơn sẽ bị từ chối, vì vậy hãy chia khối lượng lớn thành nhiều lần gọi. Đối với workload có lưu lượng lớn, hãy lưu tạm các event và gửi theo batch thay vì gửi một request cho mỗi event.
Retry 5xx429, không retry 4xx. Hãy retry khi xảy ra lỗi server (5xx) và giới hạn tốc độ (429), sử dụng exponential backoff. Không retry các lỗi validation 400/422 — payload bị sai định dạng và sẽ luôn thất bại; hãy sửa payload rồi gửi lại. Đưa các event vẫn thất bại sau khi retry vào queue để không event nào bị mất.
Thiết lập timestamps một cách có chủ đích. Bỏ qua timestamp đối với các event real-time; giá trị này sẽ mặc định là thời điểm ingestion. Hãy đặt giá trị này một cách rõ ràng (ISO 8601) khi backfill hoặc gửi các event bị trì hoãn/theo batch để mức sử dụng được ghi nhận vào đúng kỳ billing.
Gửi metadata được aggregate dưới dạng số, không phải chuỗi. Bất kỳ property nào được tham chiếu bởi Over Property của meter (Sum, Max, Last) đều phải có kiểu dữ liệu số — { "tokens": 150 }, không phải { "tokens": "150" }. Các giá trị chuỗi sẽ không được aggregate.

Phân tích Billing dựa trên mức sử dụng

Theo dõi và phân tích dữ liệu billing dựa trên mức sử dụng với dashboard analytics toàn diện. Theo dõi các mô hình tiêu thụ của khách hàng, hiệu suất của meter và xu hướng billing để tối ưu hóa chiến lược định giá cũng như hiểu rõ hành vi sử dụng.

Analytics tổng quan

Tab Overview cung cấp chế độ xem toàn diện về hiệu suất billing dựa trên mức sử dụng:

Các chỉ số hoạt động

Theo dõi các thống kê mức sử dụng chính trong những khoảng thời gian khác nhau:
metric
Hiển thị hoạt động sử dụng trong kỳ billing hiện tại, giúp bạn hiểu các mô hình tiêu thụ hàng tháng.
metric
Hiển thị các thống kê sử dụng tích lũy kể từ khi bạn bắt đầu theo dõi, cung cấp thông tin chi tiết về tăng trưởng dài hạn.
Sử dụng bộ chọn khoảng thời gian để so sánh mức sử dụng giữa các tháng khác nhau và xác định xu hướng theo mùa hoặc mô hình tăng trưởng.

Biểu đồ số lượng meter

Biểu đồ số lượng meter hiển thị xu hướng sử dụng theo thời gian với hình ảnh trực quan gradient màu tím
Biểu đồ số lượng meter trực quan hóa xu hướng sử dụng theo thời gian với các tính năng sau:
  • Trực quan hóa chuỗi thời gian: Theo dõi các mô hình sử dụng theo ngày, tuần hoặc tháng
  • Hỗ trợ nhiều meter: Xem dữ liệu từ nhiều meter cùng lúc
  • Phân tích xu hướng: Xác định các đột biến, mô hình và quỹ đạo tăng trưởng của mức sử dụng
Biểu đồ tự động điều chỉnh tỷ lệ dựa trên khối lượng sử dụng và phạm vi thời gian đã chọn, giúp hiển thị rõ cả những dao động nhỏ lẫn các thay đổi lớn về mức sử dụng.

Analytics về event

Bảng event hiển thị tên event, ID và các control phân trang để phân tích event chi tiết
Tab Events cung cấp khả năng quan sát chi tiết đối với từng event sử dụng:

Hiển thị thông tin event

Bảng event cung cấp chế độ xem rõ ràng về từng event sử dụng với các cột sau:
  • Tên event: Action hoặc trigger cụ thể tạo ra event sử dụng
  • Event ID: Mã định danh duy nhất cho mỗi instance của event
  • Customer ID: Khách hàng liên kết với event
  • Timestamp: Thời điểm event xảy ra
Chế độ xem này cho phép bạn theo dõi và giám sát từng event sử dụng trong toàn bộ customer base, mang lại tính minh bạch cho việc tính toán billing và các mô hình sử dụng.

Analytics về khách hàng

Tab Customers cung cấp chế độ xem dạng bảng chi tiết về dữ liệu sử dụng của khách hàng với các thông tin sau:

Các cột dữ liệu khả dụng

string
Địa chỉ email của khách hàng để nhận diện.
string
Mã định danh duy nhất của subscription của khách hàng.
number
Số lượng unit miễn phí có trong plan của khách hàng trước khi bắt đầu tính phí.
currency
Chi phí trên mỗi unit đối với mức sử dụng vượt quá ngưỡng miễn phí.
timestamp
Timestamp của event sử dụng gần đây nhất của khách hàng.
currency
Tổng số tiền tính phí khách hàng cho billing dựa trên mức sử dụng.
number
Tổng số unit khách hàng đã sử dụng.
number
Số lượng unit vượt quá ngưỡng miễn phí và đang bị tính phí.

Tính năng của bảng

  • Lọc cột: Sử dụng tính năng “Edit Columns” để hiển thị/ẩn các cột dữ liệu cụ thể
  • Cập nhật theo thời gian thực: Dữ liệu sử dụng phản ánh các chỉ số tiêu thụ mới nhất

Ví dụ về aggregation

Sau đây là các ví dụ thực tế về cách hoạt động của những kiểu aggregation khác nhau:

Tìm hiểu các kiểu aggregation

Các kiểu aggregation khác nhau phục vụ những kịch bản billing khác nhau. Hãy chọn kiểu phù hợp dựa trên cách bạn muốn đo lường và tính phí cho mức sử dụng.

Ví dụ triển khai thực tế

Các ví dụ này minh họa những ứng dụng thực tế của từng kiểu aggregation với các event mẫu và kết quả mong đợi.
Kịch bản: Theo dõi tổng số request APICấu hình meter:
  • Tên event: api.call
  • Kiểu aggregation: Count
  • Đơn vị đo lường: calls
Event mẫu:
Kết quả: 3 cuộc gọi được tính phí cho khách hàng
Kịch bản: Tính phí dựa trên tổng số byte đã truyềnCấu hình meter:
  • Tên event: data.transfer
  • Kiểu aggregation: Sum
  • Over Property: bytes
  • Đơn vị đo lường: GB
Event mẫu:
Kết quả: Tổng dung lượng truyền 1,5 GB được tính phí cho khách hàng
Kịch bản: Tính phí dựa trên số lượng user đồng thời cao nhấtCấu hình meter:
  • Tên event: concurrent.users
  • Kiểu aggregation: Max
  • Over Property: count
  • Đơn vị đo lường: users
Event mẫu:
Kết quả: 23 user đồng thời ở mức đỉnh được tính phí cho khách hàng

Ví dụ về lọc event

Chỉ đếm các API call đến những endpoint cụ thể:Cấu hình filter:
  • Property: endpoint
  • Comparator: equals
  • Value: /v1/orders
Event mẫu:
Kết quả: Các event khớp với tiêu chí filter sẽ được đếm. Các event có endpoint khác sẽ bị bỏ qua.

Khắc phục sự cố

Giải quyết các vấn đề phổ biến khi triển khai billing dựa trên mức sử dụng và đảm bảo việc theo dõi cũng như tính phí chính xác.

Các vấn đề phổ biến

Hầu hết các vấn đề về billing dựa trên mức sử dụng thuộc những nhóm sau:
  • Vấn đề phân phối và xử lý event
  • Vấn đề cấu hình meter
  • Lỗi kiểu dữ liệu và định dạng
  • Vấn đề về Customer ID và authentication

Các bước debug

Khi khắc phục sự cố billing dựa trên mức sử dụng:
  1. Xác minh việc phân phối event trong tab Events analytics
  2. Kiểm tra cấu hình meter có khớp với cấu trúc event hay không
  3. Validate Customer ID và API authentication
  4. Xem lại các điều kiện filtering và cài đặt aggregation

Giải pháp và cách khắc phục

Các nguyên nhân phổ biến:
  • Tên event không khớp chính xác với cấu hình meter
  • Các điều kiện filtering event đang loại trừ event của bạn
  • Customer ID không tồn tại trong tài khoản Dodo Payments của bạn
  • Timestamp của event nằm ngoài kỳ billing hiện tại
Giải pháp:
  • Xác minh chính tả tên event và phân biệt chữ hoa chữ thường
  • Xem lại và kiểm thử các điều kiện filtering
  • Xác nhận Customer ID hợp lệ và đang hoạt động
  • Kiểm tra timestamp của event là timestamp gần đây và được định dạng chính xác
Các nguyên nhân phổ biến:
  • Tên Over Property không khớp với các key metadata của event
  • Giá trị metadata có kiểu dữ liệu sai (string thay vì number)
  • Thiếu các property metadata bắt buộc
Giải pháp:
  • Đảm bảo các key metadata khớp chính xác với cài đặt Over Property
  • Chuyển các số dạng string thành số thực trong event
  • Bao gồm tất cả property bắt buộc trong mỗi event
Các nguyên nhân phổ biến:
  • Tên property của filter không khớp với metadata của event
  • Comparator không phù hợp với kiểu dữ liệu (string thay vì number)
  • Phân biệt chữ hoa chữ thường trong các phép so sánh string
Giải pháp:
  • Kiểm tra kỹ để tên property khớp hoàn toàn
  • Sử dụng comparator phù hợp với kiểu dữ liệu
  • Lưu ý vấn đề phân biệt chữ hoa chữ thường khi filtering string

Tài liệu tham chiếu API liên quan

Create Meter

Tài liệu tham chiếu API để tạo và cấu hình usage meter nhằm theo dõi mức tiêu thụ của khách hàng

Ingest Usage Events

Tài liệu tham chiếu API để gửi usage event đến các meter đã cấu hình nhằm phục vụ việc tính toán billing
Lần sửa đổi cuối 31 tháng 7, 2026