軟體 HALO 智慧感測器 API 基礎軟體
向前
本文檔描述了 Halo 智慧感測器的一組設施，統稱為 BASIC API（或應用程式介面）。本討論旨在供有興趣將一個或多個 HALO 智慧感測器 (HALO) 與第 3 方（非 IPVideo）軟體組件或系統整合的程式設計師或整合商使用。一般來說，HALO API 旨在透過傳統乙太網路將資訊從 HALO 高效傳輸到外部程式。為了實現這一目標，API 分為三個部分：事件驅動套接字連接、心跳套接字連接和事件數據 URL。 BACnet 介面也存在並在單獨的文件中介紹。
API設計
API 是使用 TCP/IP 等業界標準格式設計的。 HTTP、HTTPS 和 JSON。該設計不需要在外部程式或應用程式的開發中使用任何特殊或專有技術或程式庫。 API 非常靈活，可以進行配置和編程，以最有效的方式準確提供所需的資料。本指南的以下部分介紹了上述每個部分的操作細節。
外部消息
此設施用於在事件觸發（設定）時向外部程式、VMS 系統、伺服器等傳送警報或警報和事件資料。還可以啟用可選訊息以在事件清除（重設）時發出信號。這種傳送可以即時傳送到 TCP/IP 套接字或 HTTP/S 伺服器。有一系列可配置的協議和可自訂的內容。可以進行身份驗證和加密。
心跳
心跳訊息以可配置的時間間隔（而不是在事件觸發時）發送，以提供即時/可用性證明。它們具有與外部訊息傳遞類似的功能，但通常配置為包含一般狀態訊息，而不是有關特定事件的詳細資訊。
事件數據 URL
此功能僅在 NDA 下可用，並且僅應在外部程式需要存取任何和所有事件值、閾值和狀態標誌時使用。該數據通常由外部程式按需檢索，但頻率不是很高。當使用適度的輪詢率時，此方法通常會產生一些延遲。典型的輪詢速率範圍從每分鐘一次到每 5 秒一次，絕對最大速率為每秒一次。此方法也可用於在收到事件（警報）時擷取附加支援資料。
外部訊息詳細信息
HALO 的一部分 web 介面整合彈出視窗提供單一第 3 方連接的配置，其中可以將各種值傳送到遠端 TCP 套接字或 HTTP/HTTPS 伺服器。佔位符（令牌）用於將即時值插入傳輸的文字中。儘管標記為“外部訊息傳遞”，但該通道可用於幾乎任何需要即時事件觸發的用途，由 HALO 主動傳遞。這種安排非常靈活，因為「操作」上的選擇決定了哪些 HALO 事件通過該通道傳輸。
在 HTTP 模式下，Set 和 Reset 字串是 URL必須根據所需目標伺服器的要求輸入和格式化。使用者和密碼欄位可用於身份驗證。請參閱下面的 HTTP 模式。
在 TCP 模式下，設定和重置字串只是傳送到接收 TCP 套接字的單一訊息的資料。它們可以根據目的地的需要進行格式化。目的地在位址和連接埠欄位中指定。請參閱下面的 TCP 模式。
對於任一模式，都會顯示最新訊息的狀態，這可以幫助修復連線或其他問題。您可以使用「動作」彈出視窗上的「事件測試」按鈕來強制顯示訊息：
設定或重設的全域開/關必須為開才能啟用這些類型的消息。通常不使用重置，因為僅對事件的開始感興趣，但這可能會有所不同。每個事件都可以獨立指定是否使用「操作」彈出視窗中的「設定」或「重設」訊息。眼球按鈕將顯示關鍵字替換和格式化後發送內容的粗略表示。重複延遲可用於透過在發送另一則訊息之前進行延遲來限制頻繁訊息的發送。這是每個事件獨立完成的。 HALO 具有 15 秒的內建事件保持時間，以防止事件快速重新觸發。如果您想確保每分鐘發送的某種類型的事件不超過 1 個，您可以將重複延遲設為 60（秒）。
心跳詳情
心跳傳輸的功能與上述類似，只是不會與「操作」頁面互動。相反，心跳傳輸會依照間隔欄位的配置定期發生。 URL必須根據所需目標伺服器的要求輸入和格式化。使用者和密碼欄位可用於身份驗證。請參閱下面的 HTTP 模式。
雖然心跳的主要目的是向遠端應用程式提供 HALO 智慧感測器的壽命證明，但此訊息也可用於傳輸選定的感測器或當前事件狀態資訊。前任amp上面的 le 發送一個長字串參數 URL 其中包括 Halo 名稱、大部分感測器值，最後是 Triggered=%ACTIVE%（可以為空或目前觸發事件的清單）。
HTTP（和 HTTPS）模式
外部訊息傳遞和心跳字串可以是 http: 或 https: URL根據需要。目標伺服器可以根據需要輸入路徑和參數。可以根據需要插入％NAME％（HALO設備名稱）或％EID％（事件ID）等關鍵字，並且在發送訊息時將替換為相應的資料。顯示常用關鍵字清單以供快速參考。
這 URL 路徑可以包含關鍵字以及參數 URL。參數可能是 NAME=VALUE 對或 JSON 對象，或自訂格式，取決於目標伺服器。前任amp外部訊息傳遞的檔案將包含 %EID% 以指示觸發的事件：
- https://server.com/event/%NAME%/%EID%
- https://server.com/event?location=%NAME%&event=%EID%
- https://server.com/event?{“location”:”:%NAME%”,”event”:”%EID%”}
ExampHeartbeat 的文件可能會添加 %ACTIVE%（目前觸發的事件）或感測器值：
- https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
- https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
%SENSOR:…% 值使用 evtYYYYMMDD.csv 日誌中右側感測器列標題中找到的名稱 files。他們通常是：
如果目標伺服器偏好 HTTP PUT 或 POST 而不是 GET 請求，您可以新增前綴 URL 與 PUT: 或 POST: 一起使用。獨立地，您可以透過新增 [JSONBODY] 關鍵字後面跟著 JSON 格式的物件來新增在許多伺服器中流行的 JSON 有效負載。前任amp樂：
PUT:https://server.com/event[JSONBODY]{“位置”:“%NAME%”,“事件”:“%EID%”}
這 URL 支援典型的 IP 位址（和 IPv6）以及連接埠和使用者密碼選項，或者如果需要，您可以使用使用者和密碼欄位作為基本或摘要等驗證方法的目標伺服器：
https://username:password@123.321.123.321:9876/event…
TCP模式
外部訊息傳遞和心跳字串僅用於數據，因為位址和連接埠欄位指定了目的地。位址支援名稱、IPv4 和 IPv6。
該字串的格式可以類似於上述 HTTP 訊息的資料部分，或依照目標伺服器的要求。
Examp外部訊息傳遞的檔案將包含 %EID% 以指示觸發的事件：
位置=%NAME%，事件=%EID%
{“位置”:“:%NAME%”,“事件”:“%EID%”}
ExampHeartbeat 的文件可能會添加 %ACTIVE%（目前觸發的事件）或感測器值：
位置=%NAME%&已觸發=%ACTIVE%
{“位置”:“:%NAME%”,“NH3”:%SENSOR:NH3%}
“Integration Set”和“Integration Reset”列中的核取方塊決定哪些事件觸發傳送。有關事件和操作設定的更多信息，請參閱 HALO 管理員指南。
JSON 事件訊息的傳遞
一些開發人員喜歡接收格式化為行業標準自標記 JSON 的事件數據，而不是純 ASCII 文本，因為前者更可靠且更容易解析。在光環上 web 在頁面「訊息傳遞」標籤中，您可以在「外部訊息傳遞」設定「設定字串」和「重置字串」以及「心跳」「訊息」中提供 JSON 訊息。
Examp萊斯：
「外部訊息」設定設定字串：
{ “設備”:”%NAME%”, “事件”:”%EID%”, “警報”:”是” }
這將向指定的伺服器發送 TCP 或 UDP JSON 訊息，報告友善設備名稱、事件名稱以及剛剛啟動的情況。
「外部訊息」設定重置字串：
{ “設備”:”%NAME%”, “事件”:”%EID%”, “警報”:”否” }
這將向指定伺服器發送 TCP 或 UDP JSON 訊息，報告友好設備名稱、事件名稱以及情況現已停止。
「心跳」訊息：
{ “設備”:“%NAME%”, “活動”:“%DATE% %TIME%” }
這將定期向指定伺服器發送 TCP 或 UDP JSON 訊息，報告 HALO 在指定時間處於活動狀態。
文件/資源
 |
軟體 HALO 智慧感測器 API 基礎軟體 [pdf] 使用者指南 HALO智慧感測器API基礎軟體 |
