Search Console API: thiết kế truy vấn, phân trang và kiểm soát quota ra sao?
Biên soạn: Nguyễn Minh Phương · 14 phút đọc · Cập nhật 24/8/2026
Trả lời nhanh
Search Console API cần request contract, phân trang có điều kiện dừng, quota budget, retry có kiểm soát và reconciliation theo cùng grain; API không bảo đảm trả mọi hàng dữ liệu.
Khung áp dụng
Ba điểm cần kiểm tra trước khi làm
Phù hợp với đội phát triển hoặc phân tích đang tự động hóa báo cáo Search Console qua Search Analytics API.
| STT | Câu hỏi ra quyết định | Hành động hoặc bằng chứng cần có |
|---|---|---|
| 1 | Request đang nhóm theo dimensions nào? | Khóa request contract. |
| 2 | Phân trang và partial-data state được ghi ra sao? | Phân trang có điều kiện dừng. |
| 3 | Job xử lý quota, retry, cache và lỗi thế nào? | Dùng retry/backoff và quota budget. |
Request contract phải khóa property, dates, type, dimensions và filters
Search Analytics query nhận siteUrl, startDate, endDate cùng các lựa chọn như dimensions, dimensionFilterGroups, searchType/type, aggregationType, rowLimit và startRow. Mỗi job cần một contract có mục đích, grain, timezone, dimensions, filters và output schema. Thêm dimension làm thay đổi cách nhóm; dữ liệu trả về được sắp theo clicks giảm dần trừ khi nhóm theo date, nên code không được giả định mọi hàng có thứ tự thời gian.
- Không thêm dimensions chỉ để lấy nhiều chi tiết.
- Không ghép outputs khác grain vào cùng bảng.
- Lưu request body và phiên bản extractor.
Phân trang và giới hạn không được xử lý bằng cách lặp đến khi thấy số mong muốn
API hỗ trợ rowLimit và startRow để lấy các nhóm kết quả theo trang. Extractor dừng khi số dòng trả về nhỏ hơn page size hoặc theo điều kiện đã định, ghi từng request và chống lặp. Google nói API không bảo đảm trả tất cả các hàng dữ liệu mà trả các hàng hàng đầu; vì vậy tổng từ bảng chi tiết không nên được mô tả là toàn bộ truy vấn nếu phạm vi không chứng minh điều đó.
- Không coi page cuối là bằng chứng toàn bộ dữ liệu.
- Không retry vô hạn khi response lỗi.
- Ghi missing/partial status ở output.
Quota, backoff và reconciliation là một phần của chất lượng dữ liệu
Search Console API áp dụng usage limits theo tải và thời gian. Job scheduler nên cache kết quả bất biến, chia phạm vi hợp lý, dùng exponential backoff cho lỗi có thể thử lại và không chạy nhiều truy vấn nặng trùng nhau. Validation so sample với Performance report hoặc bulk export trong cùng filter/grain, đồng thời chấp nhận khác biệt do freshness, aggregation và dữ liệu riêng tư thay vì ép số khớp.
- Không dùng nhiều credentials để né quota.
- Không che lỗi bằng giá trị zero.
- Có owner cho schema và extraction incident.
Tình huống minh họa
Extractor coi 25.000 dòng là toàn bộ truy vấn
Đội ngũ đổi nhãn output thành top rows theo request scope, ghi giới hạn và dùng bulk export khi câu hỏi cần dữ liệu quy mô lớn hơn.
Extraction contract
API extractor đáng tin khi request, pagination, partial state và quota đều có thể truy nguyên
Annotate the request before reading any rows
Request record giữ siteUrl, dates, search type, dimensions, filter groups, aggregation, rowLimit, startRow và intended grain. Search Analytics query documentation nêu response phụ thuộc các lựa chọn này và trả các top rows. Output vì vậy phải mang request metadata; một CSV không có contract không đủ để kiểm chứng.
- Không đổi dimensions giữa pages.
- Không bỏ filter metadata.
- Không mô tả top rows là toàn bộ.
Pagination, retries and quota need explicit terminal states
Extractor tăng startRow theo page size, chống lặp row key và dừng theo response; lỗi có thể thử lại dùng bounded exponential backoff. Usage-limit guidance được dùng để lập quota budget thay vì xoay credentials. Job kết thúc bằng complete, partial hoặc failed; validation so sample với UI/bulk export trong cùng scope và ghi khác biệt do aggregation/freshness.
- Không retry vô hạn.
- Không biến lỗi thành zero.
- Không né quota bằng tài khoản khác.
Checklist triển khai
- Khóa request contract.
- Phân trang có điều kiện dừng.
- Dùng retry/backoff và quota budget.
- Reconcile theo cùng grain/filter.
Tóm tắt
Khóa request contract, phân trang, partial state, bounded retry, quota budget và reconciliation theo cùng grain. API trả dữ liệu theo request và giới hạn sản phẩm; không bảo đảm mọi hàng và không thay bulk export cho mọi use case.
Tài liệu tham khảo
- Google Search Console API — Search Analytics: query
- Google Search Console API — Usage limits
- Google Search Console Help — Performance report
- Google Search Console Help — Query and use bulk export data
Ghi chú biên soạn: nội dung được tổng hợp từ các tài liệu được liệt kê và giới hạn ở góc nhìn quản lý thông tin marketing; bài không bảo đảm vị trí hiển thị trên Google.