Vnstock Logo

Đăng nhập và dòng lệnh

Mở rộng

Mục lục

Tài liệu phiên bản trước: vnstock v5.0.1

Trang này viết cho phiên bản trước thế hệ 6 và được giữ để tra cứu. Phiên bản hiện hành là vnstock v6.0.1 — xem tài liệu v6.0.1 và hướng dẫn chuyển sang thế hệ 6.

Khi cài đặt thư viện vnstock thế hệ 5, bạn có sẵn công cụ dòng lệnh vnstock trong terminal. Công cụ này hỗ trợ quản lý tài khoản, cấu hình và chẩn đoán hệ thống: đăng nhập, xem cấp tài khoản, kiểm tra hạn mức sử dụng chung và kiểm thử môi trường. Toàn bộ tác vụ truy xuất dữ liệu vẫn được viết tự nhiên bằng Python.

Mọi lệnh CLI đều hỗ trợ tham số --json để xuất kết quả có cấu trúc cho máy đọc (phù hợp với script tự động hoá, CI/CD hoặc trợ lý AI).


Danh mục lệnh CLI

LệnhMô tả
vnstock register (hoặc vnstock login)Nhập khoá API, xác thực với máy chủ vnstocks.com, đăng ký thiết bị và lưu khoá đã mã hoá trên máy
vnstock logoutXoá khoá API và thông tin xác thực đã lưu trên máy hiện tại
vnstock statusHiển thị cấp tài khoản, hạn dùng, mã thiết bị, phiên bản thư viện và trạng thái bản cài
vnstock usageXem phần trăm hạn mức sử dụng chung còn lại của giờ, ngày, tháng và mốc đặt lại (--detail xem số đo kỹ thuật)
vnstock policyKiểm tra chính sách truy xuất đang áp dụng trên máy (các tuyến được mở, nguồn dữ liệu khả dụng)
vnstock installCài đặt các thư viện bổ sung mà cấp tài khoản của bạn được phép sử dụng
vnstock doctorChạy 7 bài kiểm tra chẩn đoán môi trường tự động, kèm hướng dẫn khắc phục
vnstock versionKiểm tra phiên bản thư viện và lõi Rust; thông báo khi có bản mới trên kho phát hành
vnstock settings languageXem hoặc thiết lập ngôn ngữ hiển thị thông báo (vi, en, both, default)
vnstock envXem đường dẫn thư mục lưu trữ cấu hình, trạng thái và máy chủ kết nối

Gõ vnstock --help hoặc vnstock <lệnh> --help để xem hướng dẫn chi tiết cho từng lệnh.


Đăng nhập và xác thực

Đăng nhập qua dòng lệnh

Shell
vnstock register              # hỏi khoá API, chuỗi khoá được ẩn khi gõ
vnstock status                # kiểm tra lại cấp và hạn dùng

Để kích hoạt nhanh nhất, bạn hãy truy cập trang Tải về & Kích hoạt để đăng nhập và sao chép câu lệnh kèm sẵn khoá API trong một bước duy nhất (hoặc lấy khoá tại trang tài khoản). Khoá cấp Cộng đồng hoàn toàn miễn phí cho cá nhân, học tập và nghiên cứu. Nếu không đăng nhập, thư viện tự động hoạt động ở cấp Khách với giới hạn số kỳ báo cáo và số dòng dữ liệu.

Đăng nhập trong Script tự động hoá và CI/CD

Khi chạy trong môi trường tự động, bạn có thể truyền khoá API qua stdin để tránh lưu vết khoá trong lịch sử shell:

Shell
printf '%s' "$VNSTOCK_API_KEY" | vnstock register --stdin

Đăng nhập trực tiếp trong Python và Jupyter Notebook

Trong notebook hoặc ứng dụng Python, bạn có thể đăng nhập thông qua các hàm tiện ích ở gốc gói:

Python
import os
import vnstock

# Đăng nhập (thực hiện một lần trên mỗi máy)
vnstock.login(os.environ["VNSTOCK_API_KEY"])

# Kiểm tra trạng thái và hạn mức
print(vnstock.status())
print(vnstock.usage())

# Đăng xuất khi cần dọn dẹp
# vnstock.logout()

Lưu ý bảo mật: Không dán trực tiếp khoá API vào tệp mã nguồn sẽ đẩy lên Git. Hãy lưu khoá trong tệp .env của dự án hoặc biến môi trường VNSTOCK_API_KEY.


Quản lý hạn mức sử dụng chung

Lệnh vnstock usage hiển thị phần trăm hạn mức sử dụng còn lại của tài khoản trong khung giờ, ngày và tháng hiện tại:

Shell
vnstock usage
Text
Hạn mức còn lại, cấp Bronze (dùng chung cho mọi thư viện và thiết bị):
  giờ này    [██████████████████··]  90%   đặt lại lúc 15:00
  hôm nay    [████████████████····]  80%   đặt lại 00:00 ngày 14/10
  tháng này  [███████████████████·]  96%   đặt lại ngày 01/11

Hạn mức này là một quỹ sử dụng chung cho toàn bộ các thư viện trong hệ sinh thái Vnstock trên mọi thiết bị liên kết với tài khoản.

Nhận biết khi kết quả bị giới hạn theo cấp

Khi một truy vấn dữ liệu bị giới hạn (ví dụ: cấp Cộng đồng nhận tối đa 8 kỳ báo cáo tài chính hoặc 10.000 nến ngày), thư viện sẽ phát cảnh báo UserWarning trong phiên chạy. Thông tin cắt giảm được ghi rõ trong thuộc tính metadata df.attrs của DataFrame:

Python
from vnstock import Fundamental

df = Fundamental().equity("FPT").income_statement(period="quarter")
print({k: v for k, v in df.attrs.items() if k.startswith("tier_cap_")})

Xem chi tiết danh mục hàm và giới hạn theo từng cấp tại trang Cấp tài khoản và giới hạn.


Cài đặt thư viện bổ sung

Thế hệ 5 cung cấp thêm các thư viện chuyên sâu mở theo cấp tài khoản:

Thư việnVai tròCấp tối thiểu
vnstockThư viện cốt lõi truy xuất dữ liệu chứng khoán, tài chính, vĩ môMọi cấp
vnstock_quant (thay vnstock_ta)Phân tích định lượng, chỉ báo kỹ thuật, đo lường rủi ro, tối ưu danh mụcCộng đồng dùng thử 30 lượt/ngày; Gói quyền sử dụng mở đầy đủ
vnstock_newsTheo dõi tin tức tài chính qua RSS và sitemap của các toà soạnSilver
vnstock_pipelineQuản lý quy trình lưu trữ tệp cục bộ, xuất tệp cho Amibroker/MetaTraderGolden

Khi tài khoản đã đăng ký gói tương ứng, lệnh vnstock install sẽ tự động phát hiện và cài đặt các thư viện được cấp quyền vào đúng môi trường Python hiện hành:

Shell
vnstock install --list      # xem danh sách thư viện và điều kiện cấp quyền
vnstock install             # cài đặt toàn bộ thư viện mở theo cấp của bạn
vnstock install -U          # nâng cấp các thư viện mở rộng lên bản mới nhất

Chẩn đoán môi trường tự động

Khi gặp sự cố kết nối hoặc cấu hình, hãy sử dụng công cụ chẩn đoán:

Shell
vnstock doctor

Lệnh doctor thực hiện tuần tự 7 bài kiểm tra (phiên bản Python, kiến trúc CPU, tính toàn vẹn của lõi Rust, kết nối máy chủ, trạng thái khoá API, phân quyền tệp). Nếu phát hiện lỗi, lệnh dừng lại ở bài kiểm tra đầu tiên không đạt và đưa ra hướng dẫn khắc phục cụ thể.


Cấu hình ngôn ngữ hiển thị

Thông báo lỗi và đầu ra của lệnh vnstock mặc định hiển thị song ngữ (tiếng Việt trước, tiếng Anh sau). Bạn có thể cấu hình hiển thị một ngôn ngữ duy nhất:

Shell
vnstock settings language vi       # chỉ hiển thị tiếng Việt
vnstock settings language en       # chỉ hiển thị tiếng Anh
vnstock settings language default  # khôi phục hiển thị song ngữ

Phiên bản và nâng cấp

Kiểm tra phiên bản đang cài đặt và đối chiếu với kho phát hành:

Shell
vnstock version

Mỗi bản phát hành chính thức có thời hạn hoạt động 365 ngày. Trước khi hết hạn 30 ngày, thư viện sẽ phát cảnh báo nhắc nhở nâng cấp. Để nâng cấp lên bản mới nhất:

Shell
pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock

Dấu nhắc tương tác (Interactive REPL)

Gõ vnstock không kèm tham số trong terminal để mở giao diện dòng lệnh tương tác:

Shell
vnstock

Trong dấu nhắc tương tác:

  • Gõ / để xem danh sách các lệnh nhanh.
  • Dùng phím Tab để hoàn thành lệnh.
  • Nhập /data price FPT để xem nhanh bảng giá mẫu kèm câu lệnh Python tương ứng.
  • Gõ /exit hoặc nhấn Ctrl+D để thoát.