Giới thiệu (Introduction)

VIGI Camera OpenAPI cho phép các ứng dụng của bên thứ ba giao tiếp với camera VIGI thông qua mạng để thực hiện các tác vụ như cấu hình thiết bị, đăng ký nhận sự kiện và xử lý các chức năng liên quan đến luồng video.

Thông qua Control Interface, OpenAPI Client có thể truy vấn hoặc cấu hình các tham số của camera, đồng thời đăng ký nhận các thông báo sự kiện.

Thông qua Stream Interface, OpenAPI Client có thể thực hiện các thao tác liên quan đến luồng video, chẳng hạn như:

• Preview
• Playback
• Recording Download
• Talk

Bài viết này hướng dẫn cách bật OpenAPI trên camera VIGI, hoàn tất quá trình xác thực, gọi các API thuộc Control Interface và tìm hiểu quy trình chung khi gửi yêu cầu đến Stream Interface.

Yêu cầu (Requirements)

• VIGI IPC hỗ trợ OpenAPI. Để kiểm tra danh sách model được hỗ trợ, vui lòng tham khảo tài liệu Devices Supported by VIGI Open API)
• Tài liệu VIGI IPC OpenAPI Document.
• Một OpenAPI Client có thể truy cập camera thông qua mạng.

Cấu hình (Configuration)

Cấu hình quyền truy cập OpenAPI

Trước khi gọi các giao diện VIGI Camera OpenAPI, hãy bật OpenAPI trên camera. Các bước dưới đây sử dụng trang quản lý web của camera làm ví dụ.

Bước 1: Đăng nhập vào giao diện web của camera bằng địa chỉ IP của thiết bị.

Nhập Username và Password, sau đó nhấp Log In.

Bước 2: Truy cập: Settings > Network Settings > OpenAPI. Bật công tắc OpenAPI, sau đó nhấp Apply để lưu cấu hình.

Xác thực Control Interface và gửi yêu cầu API

Control Interface của VIGI Camera OpenAPI sử dụng giao thức HTTPS.

Trước khi gọi các API thuộc Control Interface, OpenAPI Client cần thực hiện quá trình xác thực Do Auth để lấy stok. Mặc định, Control Interface sử dụng cổng 20443.

Bước 1. Gửi yêu cầu doAuth lần đầu để lấy các trường dùng cho quá trình xác thực.

Gửi một yêu cầu POST đến:

https://<Camera_IP>:20443

Trong phần Request Body:

• Đặt method là doAuth.
• Đặt params là null.

Camera sẽ trả về các trường xác thực dùng để tính toán giá trị phản hồi (Digest Authentication), bao gồm:

• realm
• nonce
• algorithm
• uri
• method

Ví dụ lệnh curl trên Windows:

Request:
curl.exe --% -k -X POST https://192.168.0.100:20443 -H "Content-Type: application/json" -d "{\"method\":\"doAuth\",\"params\":null}"
Response:
{"method":"doAuth","authenticate":{"realm":"TP-LINK IP-Camera","nonce":"c51594999c7dcfd020e97a2688d431d0","algorithm":"SHA-256","uri":"doAuth","method":"POST"},"errCode":-10020}

Bước 2. Gửi yêu cầu doAuth lần thứ hai để lấy stok

Tính toán giá trị response dựa trên các trường xác thực được trả về ở Bước 1 và mật khẩu đăng nhập của camera. Nếu trường algorithm được trả về là SHA-256, hãy tính giá trị response theo công thức sau:

A1 = SHA256(admin:<realm>:<password>)

A2 = SHA256(<method>:<uri>)

response = SHA256(A1:<nonce>:A2)
 

Sau đó, gửi một yêu cầu POST đến: https://<Camera_IP>:20443

Trong phần Request Body:

• Đặt method là doAuth.
• Trong params, truyền vào:
  • Giá trị nonce được trả về ở Bước 1.
  • Giá trị response đã được tính toán theo công thức ở trên.

Ví dụ lệnh curl trên Windows như sau:

Request:
curl.exe --% -k -X POST https://192.168.0.100:20443 -H "Content-Type: application/json" -d "{\"method\":\"doAuth\",\"params\":{\"nonce\":\"c51594999c7dcfd020e97a2688d431d0\",\"response\":\"ae990e323d2370c9a6cbcf638b5808f006f2c32343034787205f00d81c1fe16a\"}}"
Response:
{"method":"doAuth","stok":"jqNXOtUS7*Qu0XSvOqO0uOXst1ZlOOcD","errCode":0}

Bước 3. Gọi các API của Control Interface

Sau khi lấy được stok, hãy thêm giá trị này vào Request URL và gửi yêu cầu đến Control Interface ở định dạng JSON.

• Phương thức (Method): POST
• Định dạng Request URL: https://<Camera_IP>:20443/stok=<stok>

Phần này cung cấp hai ví dụ:

1. Một yêu cầu Control Interface thông dụng để thiết lập múi giờ (Time Zone) cho camera.
2. Một yêu cầu Event Subscription để đăng ký nhận thông báo sự kiện từ camera.

Ví dụ 1: Thiết lập múi giờ cho camera

API setTimeZone được sử dụng để cấu hình múi giờ của camera.

Trong Request Body:

• Đặt method là setTimeZone.
• Trong params, cấu hình các tham số:
  • timezone
  • area

Ví dụ dưới đây sẽ cấu hình múi giờ của camera thành America/Los_Angeles.

Request:
curl.exe --% -k -X POST https://192.168.0.100:20443/stok=jqNXOtUS7*Qu0XSvOqO0uOXst1ZlOOcD -H "Content-Type: application/json" -d "{\"method\":\"setTimeZone\",\"params\":{\"timezone\":\"UTC-08:00\",\"area\":\"America/Los_Angeles\"}}"
Response:
{"method":"setTimeZone","errCode":0}

Ví dụ 2: Đăng ký nhận thông báo sự kiện (Event Messages)

API subscribeMsg được sử dụng để đăng ký nhận các thông báo phát hiện sự kiện (Event Detection Messages).

Trong Request Body:

• Đặt method là subscribeMsg.
• Trong params, cấu hình các tham số:
  • event_type
  • heartbeat

Sau khi gửi yêu cầu, giữ kết nối luôn ở trạng thái mở (Keep the connection open).

Camera sẽ:

• Gửi các Heartbeat Packets theo chu kỳ để duy trì kết nối.
• Khi có sự kiện được kích hoạt, camera sẽ đẩy (Push) các thông báo sự kiện đến OpenAPI Client thông qua chính kết nối đang mở này.

Request:

curl.exe --% -k -N -X POST https://192.168.0.100:20443/stok=jqNXOtUS7*Qu0XSvOqO0uOXst1ZlOOcD -H "Content-Type: application/json" -d "{\"method\":\"subscribeMsg\",\"params\":{\"event_type\":[\"all\"],\"heartbeat\":10}}"

Response:

{"method":"subscribeMsg","errCode":0}

Xác thực Stream Interface và gửi yêu cầu Stream

Stream Interface của VIGI Camera OpenAPI được thiết lập thông qua giao thức RTSP.

Trước khi gửi các yêu cầu liên quan đến luồng video (Stream Requests), OpenAPI Client cần hoàn tất quá trình Digest Authentication. Phần này sử dụng kịch bản tải xuống bản ghi (Recording Download) để minh họa quy trình làm việc tổng quát của Stream Interface.

Bước 1. Lấy các tham số cần thiết cho yêu cầu Stream (nếu cần)

Đối với một số thao tác trên Stream Interface, chẳng hạn như tải xuống bản ghi (Recording Download), OpenAPI Client cần lấy trước các tham số cần thiết thông qua Control Interface.

Ví dụ, trước khi gửi yêu cầu tải xuống, hãy gọi API getMediaList được mô tả trong Mục 4.11.1 của tài liệu VIGI IPC OpenAPI Document để lấy các thông tin như:

• Recording Start Time
• Recording End Time
• FileID
• event_type
• Và các thông tin liên quan khác.

Sau đó, sử dụng các tham số này trong yêu cầu Recording Download của Stream Interface.

Bước 2. Kiểm tra cổng RTSP

Trên giao diện quản lý web của camera, truy cập: Settings > Network Settings > Network Service > RTSP để kiểm tra RTSP Port của camera. Trong ví dụ này, RTSP Port là 554.

Lưu ý: Nếu camera được truy cập thông qua Port Forwarding, hãy sử dụng RTSP Port được ánh xạ trên router (External RTSP Port) thay vì RTSP Port nội bộ của camera.

Bước 3. Thiết lập kết nối RTSP và hoàn tất Digest Authentication

OpenAPI Client thiết lập kết nối TCP đến cổng RTSP của camera và gửi yêu cầu MULTITRANS đầu tiên. Camera sẽ phản hồi 401 Unauthorized kèm theo các tham số dùng cho Digest Authentication. Sau đó, OpenAPI Client tính toán giá trị xác thực (Authentication Response) dựa trên:

• Username
• Password
• Request Method
• Request URI
• Các tham số xác thực được camera trả về

Tiếp theo, OpenAPI Client gửi lại yêu cầu MULTITRANS kèm theo Authentication Header.

Để biết chi tiết về cách tính Digest Authentication, vui lòng tham khảo Mục 2.2.2 – Digest Authentication trong tài liệu VIGI IPC OpenAPI Document.

Bước 4. Gửi yêu cầu đến Stream Interface

Sau khi Digest Authentication thành công, OpenAPI Client có thể gửi các yêu cầu đến Stream Interface, chẳng hạn như:

• Preview
• Playback
• Recording Download
• Stop
• Play
• Force I-frame
• Talk

Đối với chức năng Recording Download, camera sẽ trả về phản hồi 200 OK cùng với thông tin về Codec, sau đó bắt đầu truyền dữ liệu RTP thông qua kết nối TCP.

Để biết chi tiết về các phương thức và tham số của Stream Interface, vui lòng tham khảo Mục 5 – OpenAPI Stream Interface trong tài liệu VIGI IPC OpenAPI Document.

Bước 5. Nhận và phân tích dữ liệu RTP

Dữ liệu luồng được truyền dưới dạng RTP over TCP.

OpenAPI Client cần thực hiện các bước sau:

• Nhận diện các gói RTP thông qua ký tự bắt đầu $.
• Đọc Channel ID và Payload Length.
• Phân tích RTP Header và RTP Payload.
• Xác định loại dữ liệu truyền (Media Type) dựa trên RTP Payload Type.

Để biết chi tiết về cấu trúc gói RTP over TCP, vui lòng tham khảo Mục 2.3 – Data Transmission. Để biết định nghĩa của các Payload Type, vui lòng tham khảo Appendix 2 – Payload Type trong tài liệu VIGI IPC OpenAPI Document.

Bước 6. Kiểm tra và xử lý codec âm thanh (nếu có dữ liệu âm thanh)

Nếu thao tác trên Stream Interface có liên quan đến dữ liệu âm thanh, chẳng hạn như:

• Recording Download có kèm âm thanh.
• Talk.

Trước tiên, hãy gọi API getAudioEncode được mô tả trong Mục 4.4.6 của tài liệu VIGI IPC OpenAPI Document để kiểm tra Audio Codec mà camera đang sử dụng. Sau đó, OpenAPI Client cần xử lý Audio RTP Payload theo giá trị encode_type được API trả về.

Kiểm tra (Verification)

Sau khi gọi các API của Control Interface như trong các ví dụ trên, hãy xác minh kết quả theo các bước dưới đây.

Kiểm tra Ví dụ 1: Thiết lập múi giờ cho camera

Sau khi yêu cầu setTimeZone trả về: "errCode": 0

hãy đăng nhập vào giao diện quản lý web của camera và truy cập: Settings > System Settings > Basic Settings > Date

Kiểm tra xem giá trị Time Zone đã được thay đổi sang múi giờ đã cấu hình hay chưa. Trong ví dụ này, Time Zone phải được thay đổi thành: (UTC-08:00) Pacific Time.

Kiểm tra Ví dụ 2: Đăng ký nhận thông báo sự kiện

Sau khi yêu cầu subscribeMsg trả về:

{

  "result": "success",

  "errCode": 0

}

hãy tiếp tục giữ lệnh ở trạng thái đang chạy.

Camera sẽ:

• Gửi các heartbeat packets theo khoảng thời gian heartbeat đã cấu hình.
• Đẩy các event messages thông qua chính kết nối đó khi có sự kiện được kích hoạt.

Trong ví dụ này:

• event_type được đặt là all.
• heartbeat được đặt là 10.

Do đó, cửa sổ Terminal sẽ hiển thị:

• Một heartbeat packet sau mỗi 10 giây.
• Các event messages khi bất kỳ sự kiện đã đăng ký nào được kích hoạt.

Kết luận (Conclusion)

Sau khi hoàn thành các bước trong bài viết này, bạn có thể bật OpenAPI trên camera VIGI, hoàn tất quá trình xác thực (Authentication) và gọi các API thuộc Control Interface hoặc Stream Interface theo nhu cầu sử dụng.

Các ví dụ trong bài viết cũng minh họa cách:

• Xác minh kết quả của các API thông dụng thuộc Control Interface.
• Hiểu quy trình làm việc tổng quát của các yêu cầu gửi đến Stream Interface.

Câu hỏi thường gặp (QA)

Q1. OpenAPI Client nên quản lý kết nối như thế nào khi gọi các API của Control Interface?

A1. Đối với các API thuộc Control Interface, OpenAPI Client nên tạo một kết nối mới cho mỗi yêu cầu API.

Sau khi lấy được stok thông qua API doAuth, hãy sử dụng stok để gọi API cần thiết, chẳng hạn như:

• getDeviceInfo
• setTimeZone

Mỗi yêu cầu API nên được gửi thông qua một kết nối riêng biệt, giúp mỗi yêu cầu được xử lý độc lập. Riêng đối với API subscribeMsg, sau khi đăng ký thành công, cần giữ kết nối luôn ở trạng thái mở (Keep the connection open) để camera có thể gửi:

• Heartbeat Packets
• Event Messages

thông qua chính kết nối đó.

Q2. Tôi có thể tải tài liệu VIGI IPC OpenAPI Document ở đâu?

A2. Truy cập Download Center , tìm kiếm model camera cần sử dụng và mở trang tải xuống của sản phẩm. Trong mục Manual, tải xuống tài liệu VIGI IPC OpenAPI Document tương ứng với model camera của bạn.

Để tìm hiểu thêm chi tiết về từng chức năng và cách cấu hình, vui lòng truy cập Download Center để tải xuống hoặc tham khảo User Guide dành cho sản phẩm của bạn.