DataOps Peach

Lakehouse Engineering · Ingestion: lấy dữ liệu ra khỏi nguồn · Bài 3/4

Nạp từ API

Đọc API theo trang bằng con trỏ thay vì offset, chờ backoff khi bị giới hạn tần suất, lưu con trỏ để chạy lại đi tiếp chứ không làm lại - và vẫn MERGE theo khoá ở cuối.

Học tương tác →

Ba câu hỏi, áp cho API

Như mọi nguồn (bài 3.1): API cho biết cái gì mới thế nào (tham số since, con trỏ)? Có cho biết cái gì bị xoá không (thường là không, hoặc có endpoint riêng)? Chạy lại có trùng không (tuỳ cách bạn lưu tiến độ và ghi)?

Offset hay con trỏ

Cách Hỏi gì Vấn đề
Offset ?offset=100&limit=100 (dòng 101–200) Có bản ghi mới chèn vào đầu giữa hai lần gọi thì mọi thứ dịch đi: trang 2 lặp lại vài bản ghi cuối của trang 1, hoặc sót nếu có bản ghi bị xoá
Con trỏ (cursor) ?cursor=<c>&limit=100 (các bản ghi sau bản ghi c) Con trỏ trỏ vào một bản ghi cụ thể theo khoá bất biến, nên chèn hay xoá ở chỗ khác không làm lệch trang

Mock API của bài trả mỗi trang kèm next_cursor (order_id cuối trang, mã hoá base64) và has_more. Trang 1 (limit=2) kết thúc ở ORD-000041; hỏi tiếp với con trỏ đó nhận ORD-000097, ORD-000104... không lặp, không sót. Giới hạn của ví dụ: con trỏ theo order_id nên đơn cũ được cập nhật sau đó không quay lại; API thật cho phép cập nhật thường phân trang theo (updated_at, id).

Giới hạn tần suất và backoff

API thật giới hạn số request (rate limit) và trả HTTP 429 Too Many Requests khi vượt (thường kèm Retry-After: số giây phải chờ, script tôn trọng nếu lớn hơn backoff). Mock API của bài cứ 4 request lại trả 429.

Phản ứng đúng là exponential backoff + jitter: chờ base × 2^lần_thử (0.2s, 0.4s, 0.8s...) cộng một khoảng ngẫu nhiên nhỏ, rồi thử lại, có giới hạn số lần. Retry ngay lập tức dồn dập chỉ làm API giới hạn lâu hơn; jitter để nhiều client không cùng thử lại một lúc. Lỗi 4xx khác (400, 401, 404) thì không retry: thử lại cũng sai y như cũ.

Lưu tiến độ ở đâu

ingest_api.py ghi mỗi trang thành một file JSON và lưu con trỏ sau mỗi trang (api_out/_cursor.txt). Chết ở trang 4 thì chạy lại đi tiếp từ trang 5. Chạy lại khi không có gì mới: hỏi "sau con trỏ cuối", nhận trang rỗng, 0 đơn mới. Trong pipeline thật, con trỏ lưu ở chỗ bền và chung (một bảng nhỏ, hay file trong volume), không phải trên máy chạy job. Muốn làm lại từ đầu: rm -rf api_out (xoá cả trang lẫn con trỏ).

Lưu con trỏ sau khi ghi trang chứ không phải trước: chết giữa hai việc thì lần sau đọc lại trang đó (trùng), chứ không bỏ qua nó (mất). Vì vậy bước cuối vẫn là MERGE theo khoá vào bronze/silver, như mọi nguồn khác.

flowchart LR
  A[mock API · 550 đơn] -->|trang + next_cursor| I[ingest_api.py]
  I -->|429 → backoff, thử lại| A
  I --> O[api_out/ · 6 trang JSON]
  I --> C[_cursor.txt]
  O -->|fs cp + MERGE theo order_id| B[bronze]

Ví dụ: trang 2 lặp trang 1

Tình huống giả định: một pipeline đọc API đơn hàng theo offset, 100 đơn mỗi trang, sắp mới nhất trước. Trong lúc đọc trang 1, có 3 đơn mới được tạo. Trang 2 (offset=100) giờ bắt đầu từ đơn thứ 98 cũ, nên 3 đơn cuối của trang 1 xuất hiện lần nữa. Nếu ghi bằng append, bảng có đơn trùng mỗi ngày mà không ai hiểu vì sao.

Lệnh hay dùng

Lệnh Để làm gì
curl -s "<url>?limit=100" xem một trang và con trỏ
curl -s "<url>?limit=100&cursor=<c>" trang sau con trỏ
python3 ingest_api.py --limit 100 nạp hết, retry backoff, lưu con trỏ
databricks fs cp -r api_out dbfs:/Volumes/workspace/de/raw/api/ đưa các trang lên volume để MERGE

Lỗi hay gặp

Học tương tác →