Cài đặt và khoá nguồn

Thế hệ 6 gồm hai thư viện. vnstock-oapi quản lý khoá trên máy và kết nối Open API của nguồn; vnstock đọc kết quả rồi trả về bảng chuẩn hoá. Bạn cần cài cả hai.

Cài thư viện

python -m venv ~/.venv_vnstock6 && source ~/.venv_vnstock6/bin/activate
pip install -U --extra-index-url https://vnstocks.com/api/packages "vnstock==6.0.0rc2" "vnstock-oapi==0.1.0rc1"
vnstock version

Các thư viện Vnstock được phát hành qua kho phân phối của vnstocks.com, không qua PyPI. Hãy giữ --extra-index-url https://vnstocks.com/api/packages trong cả lệnh cài và lệnh cập nhật.

Thế hệ 6 dùng chung tên gói vnstock với thế hệ 5. Cài vào môi trường đang có thế hệ 5 sẽ thay bản đó, nên lệnh trên tạo một môi trường ảo riêng. Trên Windows, kích hoạt bằng ~\.venv_vnstock6\Scripts\activate.

Cần Python 3.10 trở lên. vnstock kèm lõi Rust biên dịch sẵn (binary wheels), không cần cài trình biên dịch.

Sau khi cài, máy có hai lệnh: vnstock (tài khoản Vnstock, kiểm máy, tra hàm) và vnstock-oapi (khoá và phiên của từng nguồn).

Tài khoản Vnstock

Tài khoản Vnstock dùng chung với thế hệ 5: đã đăng nhập ở thế hệ 5 thì không phải đăng nhập lại.

vnstock status        # tài khoản, cấp quyền, hạn dùng của bản đang cài
vnstock login         # đăng nhập bằng khoá API lấy tại vnstocks.com

from vnstock import account
account.status()

Khoá tài khoản Vnstock khác khoá của nguồn. Nó không thay khoá nguồn và không được gửi tới nguồn.

Đăng ký khoá ở nguồn

Mỗi nguồn là một tài khoản riêng của bạn, theo điều khoản riêng của nguồn đó. Bạn chỉ cần khoá ở nguồn bạn định dùng.

OTP không bao giờ được lưu. Bạn gõ OTP mỗi lần mở phiên bằng vnstock-oapi auth <nguồn>.

Thế hệ 6 không bao giờ hỏi mật khẩu tài khoản chứng khoán của bạn. Nếu một phần mềm mang tên Vnstock hỏi mật khẩu đó, phần mềm ấy không phải bản chính thức: đừng nhập, và báo cho Vnstock qua support@vnstocks.com.

Với fmp: gói Basic giới hạn 250 lời gọi mỗi ngày, nhiều dữ liệu cần gói trả phí. Bạn dùng được mọi tính năng gói của mình hỗ trợ; vnstock không giới hạn thêm. Đăng ký gói của FMP qua link giới thiệu của vnstock thì được giảm 20%, và vnstock nhận chia sẻ hoa hồng từ FMP.

Cất khoá

vnstock-oapi tìm khoá theo thứ tự: biến môi trường, tệp .env trong thư mục đang chạy, rồi keyring của hệ điều hành. Giá trị tìm thấy trước được ưu tiên.

vnstock-oapi keys set <nguồn>      # cất vào keyring (khuyên dùng)
vnstock-oapi keys delete <nguồn>   # xoá

Hoặc tệp .env, với tên biến đúng như bảng trên:

<NGUỒN>_API_KEY="..."

Nguồn dùng cặp key và secret thì thêm dòng secret:

<NGUỒN>_API_SECRET="..."

Không commit tệp .env, không dán khoá vào sổ tay chia sẻ. .env chỉ được đọc ở thư mục bạn đang chạy lệnh, không đọc ở thư mục cha.

Máy không có keyring

GitHub Codespaces, Docker, máy chủ Linux và WSL thường không có keyring. Trên các máy này, vnstock-oapi keys set dừng với lỗi NoKeyringError. Khoá không được cất, nên bạn dùng một trong hai cách sau.

Biến môi trường. Trên GitHub Codespaces, vào GitHub → Settings → Codespaces → Secrets, tạo secret đúng tên ở bảng trên (dạng <NGUỒN>_API_KEY, <NGUỒN>_API_SECRET) và cho phép repo bạn dùng. Codespace mới tạo, hoặc codespace khởi động lại, sẽ có các secret này dưới dạng biến môi trường. Khoá không nằm trong repo. Trên máy khác, đặt biến bằng export hoặc bằng cấu hình của môi trường chạy.

Tệp .env riêng tư. Tạo .env trong thư mục chạy lệnh, rồi khoá quyền đọc và loại tệp khỏi git:

chmod 600 .env
echo ".env" >> .gitignore

Nguồn có phiên cần thêm chỗ cất phiên (vnstock keys cho biết nguồn nào cần mở phiên). Khi không có keyring, đặt:

export VNSTOCK_OAPI_SESSION_BACKEND=file

Phiên khi đó nằm trong một tệp chỉ tài khoản của bạn đọc được (quyền 600).

Gói keyrings.alt cũng làm keys set chạy được, nhưng gói này lưu khoá thành chữ thường, không mã hoá. Nên dùng biến môi trường hoặc .env ở trên.

Kiểm khoá

vnstock keys                # nguồn nào đã có khoá, khoá lấy từ đâu, nguồn nào cần mở phiên; không gọi mạng
vnstock-oapi check          # gọi thử một thao tác nhẹ nhất ở mỗi nguồn đã có khoá
vnstock-oapi check <nguồn>  # chỉ một nguồn

Nguồn có phiên thì mở phiên trước khi gọi dữ liệu:

vnstock-oapi auth <nguồn>   # mở phiên, hỏi OTP nếu nguồn cần

check cho biết nguồn nào đang thiếu khoá hoặc từ chối khoá. Hãy xử lý lỗi này trước khi gọi hàm dữ liệu.

auth chỉ cần cho nguồn có phiên và luôn cần tên nguồn; vnstock keys cho biết nguồn nào cần mở phiên. Ở nguồn không có phiên, mỗi request mang theo khoá nên không có phiên để mở, và auth luôn báo "không cần phiên", kể cả khi máy chưa có khoá. Muốn biết khoá dùng được chưa, chạy vnstock-oapi check <nguồn>.

Kiểm cả máy

vnstock doctor

doctor kiểm lần lượt: kết nối tới vnstocks.com, bản đang cài còn dùng được tới ngày nào, tài khoản Vnstock, có bản mới không, thư viện vnstock-oapi, khoá và phiên của từng nguồn. Mỗi mục chưa ổn đi kèm lệnh sửa. Nguồn chưa có khoá chỉ là cảnh báo: bạn chỉ cần khoá ở nguồn bạn dùng.

Bước tiếp theo

Chọn nguồn cho lời gọi của bạn.