Cài đặt và tài khoản

Vnstock Pipeline thế hệ 6 gồm thư viện chính và vài phần đi kèm. Cài phần nào tuỳ việc bạn định làm.

Yêu cầu

• Python 3.10 trở lên, trên Windows, macOS hoặc Linux.
• Tài khoản Vnstock thuộc gói quyền sử dụng từ cấp Golden (Tự động hoá cá nhân) trở lên, để chạy tác vụ nạp dữ liệu và mở phiên stream.
• Khoá API bạn đăng ký ở nguồn định dùng. Riêng cổng dữ liệu thị trường công khai của Binance thì không cần khoá.

Nên cài vào một môi trường ảo riêng. Gói thế hệ 6 cùng tên với bản 3.x (vnstock-pipeline), chỉ khác số phiên bản, nên cài vào môi trường đang có bản 3.x sẽ thay bản đó (Chuyển từ bản 3.x).

Cài thư viện

python -m venv ~/.venv_pipeline6 && source ~/.venv_pipeline6/bin/activate
pip install -U --extra-index-url https://vnstocks.com/api/packages "vnstock==6.0.0rc2" "vnstock-oapi==0.1.0rc1"
vnstock login                                                     # khoá tài khoản Vnstock, dán khi được hỏi
vnstock install "vnstock-pipeline[rest,stream,excel]==6.0.0rc1"
vnstock-pipeline --version

Kho phân phối chỉ giao thư viện theo gói quyền sử dụng cho máy đã đăng nhập, nên pipeline được cài bằng vnstock install (lệnh này dùng khoá đã lưu trên máy), không cài thẳng bằng pip. Trên Windows, kích hoạt môi trường bằng ~\.venv_pipeline6\Scripts\activate.

Thư viện có lõi Rust biên dịch sẵn cho phần giấy phép, giải mã thông điệp và dựng nến. Phần Python là giao diện lập trình quanh lõi đó: kho, tác vụ, phiên, dòng lệnh.

Đăng nhập tài khoản Vnstock

Đã chạy vnstock login ở bước cài thì máy đã đăng nhập; mục này dành cho máy chạy tự động, nơi khoá nằm trong biến môi trường.

Khoá tài khoản lấy ở trang tài khoản. Đây là khoá của Vnstock, không phải khoá của nguồn. Nên để khoá trong biến môi trường hoặc tệp .env, đừng dán vào mã.

export VNSTOCK_API_KEY="..."          # hoặc ghi VNSTOCK_API_KEY="..." vào tệp .env
vnstock-pipeline account login
vnstock-pipeline account status       # cấp quyền, quyền dùng, thiết bị, thời hạn bản phát hành

Đăng nhập một lần dùng chung cho mọi thư viện Vnstock trên máy. Nếu bạn đã đăng nhập cho bản 3.x hay cho thư viện Vnstock khác thì không phải làm lại.

Trong Python:

from vnstock_pipeline import account, license_status

account.login()                        # đọc VNSTOCK_API_KEY
license_status()["entitled"]           # True khi máy được dùng pipeline

Lệnh nào cần quyền

Một lượt chạy chỉ kiểm tra giấy phép, không trừ hạn mức. Phần mềm được cấp quyền theo gói, còn dữ liệu bạn lấy bằng khoá của chính bạn và theo hạn mức của nguồn.

Lần đầu chạy lệnh nạp dữ liệu hay mở phiên trên một máy, pipeline in một lần lưu ý về việc dùng dữ liệu (dữ liệu đi thẳng từ nguồn tới máy bạn, quyền với dữ liệu theo điều khoản của nguồn).

Thời hạn bản phát hành

Mỗi bản phát hành có thời hạn dùng, xem bằng account status. Khi đã có bản mới, hoặc bản đang cài gần tới ngày cuối, lệnh in thêm một dòng nhắc ở cuối. Bản hết hạn hoặc bị tắt thì lệnh cần quyền báo lỗi; cập nhật bằng vnstock update, hoặc chạy lại lệnh cài ở trên với số phiên bản mới.

Đo lượt dùng

Đo lượt dùng chỉ chạy khi tài khoản đồng ý. Phần mềm đếm lệnh và tác vụ đã chạy. Với mỗi phiên stream, nó ghi thêm tỉ lệ thông điệp giải mã lỗi, tỉ lệ lệnh gửi lại hoặc trùng, số khoảng hở nến và số lần nối lại (theo khoảng, không phải số chính xác), và phiên kết thúc thế nào. Phần mềm không ghi mã chứng khoán, kênh, tên nguồn, đường dẫn hay nội dung dữ liệu. Tắt bằng vnstock-pipeline account telemetry off, hoặc vnstock_pipeline.telemetry.disable().

Lưu khoá của nguồn

Khoá nguồn do phần kết nối vnstock-oapi đọc, từ biến môi trường, tệp .env ở thư mục đang chạy, hoặc keyring của hệ điều hành; pipeline không đọc khoá. Máy không có keyring (GitHub Codespaces, Docker, máy chủ Linux) thì dùng biến môi trường hoặc .env, xem Máy không có keyring. Các bước đăng ký khoá ở từng nguồn có ở Cài đặt và khoá nguồn của vnstock 6.

vnstock-oapi keys set <nguồn>   # nhập khoá, không hiện ký tự khi gõ
vnstock-oapi check <nguồn>      # gọi thử một thao tác để kiểm khoá
vnstock-oapi status             # khoá và phiên đang có trên máy, không gọi mạng

Nguồn có phiên thì mở phiên trước:

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

Nguồn mở phiên bằng OTP mà hết phiên thì lệnh báo một dòng OtpRequiredError kèm cách mở lại phiên. Chạy vnstock-oapi auth <nguồn> rồi chạy lại lệnh.

Lỗi về quyền thường gặp

Lỗi do nguồn trả về (khoá sai, hết phiên, vượt hạn mức) được in thành một dòng có tên lỗi và cách sửa. Thêm --debug trước tên lệnh để xem đầy đủ chi tiết kỹ thuật khi cần báo lỗi.

Bước tiếp theo

Cấu hình và lưu trữ.