Vnstock Logo

Xử lý lỗi và chính sách

Mở rộng

Mục lục

Khi xây dựng các ứng dụng phân tích dữ liệu, việc xử lý ngoại lệ chu đáo sẽ giúp chương trình của bạn hoạt động ổn định và dễ dàng quản lý. Trong vnstock_news, toàn bộ các tình huống ngoại lệ đều thuộc về lớp NewsError.

Đối tượng NewsError giúp bạn kiểm soát lỗi thế nào

Mỗi khi phát sinh sự cố, NewsError cung cấp sẵn các thuộc tính để bạn đưa ra quyết định xử lý phù hợp:

  • error.code: Mã lỗi định danh dạng chữ in hoa (ví dụ: NEWS_TIER_REQUIRED, UNKNOWN_SITE). Bạn có thể dùng mã này để viết câu lệnh rẽ nhánh trong Python.
  • error.retryable: Báo cho bạn biết có nên thử lại hay không. Nếu là True (như kết nối mạng gián đoạn nhẹ), bạn có thể cho chương trình chờ ít giây rồi thử lại. Nếu là False (như gõ sai mã nguồn tin), việc thử lại sẽ vô ích và bạn nên kiểm tra lại tham số truyền vào.
  • error.action: Lời khuyên hoặc câu lệnh cụ thể bằng tiếng Việt hướng dẫn bạn cách khắc phục sự cố ngay lập tức.

Hướng dẫn xử lý các tình huống thường gặp

1. Phân quyền và tài khoản

Tình huốngMã lỗi (code)Nguyên nhân và cách bạn xử lý
Chưa đủ cấp tài khoảnNEWS_TIER_REQUIREDBạn chưa đăng nhập khoá API, hoặc tài khoản đang ở cấp Khách, Cộng đồng, Bronze. Hãy chạy vnstock register để nhập khoá của tài khoản từ cấp Silver trở lên, hoặc xem các gói tài trợ từ cấp Silver tại trang tài khoản.

2. Tham số gọi hàm

Tình huốngMã lỗi (code)Nguyên nhân và cách bạn xử lý
Gõ sai mã nguồn tinUNKNOWN_SITETên mã truyền vào site_name không đúng. Chạy vnstock_news.list_supported_sites() để xem lại mã chính xác.
Thiếu thông tin nguồnMISSING_SOURCEBạn chưa truyền nguồn nào. fetch_feeder() cần site_name hoặc sources; fetch_articles() cần thêm một trong urls hoặc config có nguồn cấp tin hay sơ đồ trang nếu không dùng hai tham số trên.
Cấu hình tự khai sai cấu trúcINVALID_SITE_CONFIGTừ điển truyền vào config không đúng dạng: mỗi bộ chọn phải là một từ điển (không phải danh sách nhiều từ điển) và nằm trong khoá "config". Xem Tuỳ biến Sitemap và RSS.
Sai định dạng thời gianINVALID_TIME_FRAMETham số within bị gõ nhầm (ví dụ "12x" thay vì "12h"). Hãy dùng số đi kèm chữ cái: m (phút), h (giờ), d (ngày).

3. Cập nhật phiên bản

Tình huốngMã lỗi (code)Nguyên nhân và cách bạn xử lý
Bản cài đã hết hạnVNSTOCK_RELEASE_EXPIREDBản phần mềm bạn đang dùng đã phát hành hơn 365 ngày. Bạn chỉ cần chạy lại lệnh nâng cấp: pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock-news.

4. Kết nối tới website nguồn

Tình huốngMã lỗi (code)Nguyên nhân và cách bạn xử lý
Đường dẫn giới hạn trong robots.txtROBOTS_DISALLOWEDWebsite nguồn không mở đường dẫn này theo quy định công bố trong robots.txt. Thư viện tôn trọng quy định này và không gửi yêu cầu; bạn hãy chọn chuyên mục khác.
Máy chủ nguồn phản hồi bậnHOST_RATE_LIMITEDMáy chủ nguồn phản hồi mã HTTP 429 yêu cầu giảm tần suất. Ứng dụng của bạn nên tạm nghỉ ít phút trước khi thực hiện lần gọi tiếp theo.
Không thể kết nối tới websiteROBOTS_UNREACHABLEKết nối mạng tới máy chủ nguồn đang bị gián đoạn tạm thời. Thuộc tính error.retryable sẽ là True, bạn có thể thử lại sau ít phút.

Mẫu kịch bản xử lý ngoại lệ trong Python

Dưới đây là cấu trúc xử lý ngoại lệ chuẩn khi xây dựng hàm lấy tin trong ứng dụng của bạn:

Python
import time
import vnstock_news
from vnstock_news import NewsError

def lay_tin_co_kiem_soat(site_name, max_retries=3):
    """Hàm lấy tin có cơ chế xử lý ngoại lệ và thử lại khi gặp gián đoạn tạm thời."""
    for attempt in range(1, max_retries + 1):
        try:
            df = vnstock_news.fetch_feeder(site_name=site_name, within="2h")
            print(f"Cập nhật thành công {len(df)} tin từ {site_name}.")
            return df

        except NewsError as err:
            print(f"[Lần thử {attempt}] Phát sinh sự cố: {err.code}")
            print(f"Hướng dẫn khắc phục: {err.action}")

            # Nếu lỗi phân quyền hoặc sai tham số, không nên thử lại
            if not err.retryable:
                print("Lỗi cần điều chỉnh cấu hình hoặc tham số, dừng thực thi.")
                break

            # Nếu gián đoạn mạng tạm thời, chờ một khoảng thời gian ngắn rồi thử lại
            if attempt < max_retries:
                print("Gián đoạn tạm thời, chờ 30 giây để thử lại...")
                time.sleep(30)
            else:
                print("Đã thử lại nhiều lần nhưng chưa thành công, bỏ qua lượt này.")

    return None

# Gọi thử hàm
df_cafef = lay_tin_co_kiem_soat("cafef")