Web API

簡介

Cavalry 提供了一種透過建立 WebClient 物件並與其方法互動來與 Web 上的 API 端點進行互動的方式，可執行 get、post 或 put 操作。這些 API 呼叫是阻塞的，意味著它們必須成功完成後才能繼續執行指令碼的下一部分。

除了 WebClient，Cavalry 還提供了一個簡單的 WebServer。您可以呼叫 /get 來取得您在伺服器上設定的任何回應，或者如果您喜歡冒險，可以使用 /post。為幫助使用 /post，WebServer 可以輪詢新資料，並在檢測到資料到達時觸發回呼函式。

入門

嘗試以下範例以了解 Web API。

簡單的 get 請求。

// Make a new WebClientvar client = new api.WebClient("https://www.boredapi.com");// Send the Get Request (this returns a random activity to do if you're bored).client.get("/api/activity");// Check it succeededif (client.status() == 200) {    let obj = JSON.parse(client.body());    // Safety check, and print the activity    if ('activity' in obj) {        console.log("Random activity: "+obj.activity);    }}

取得並儲存 SVG 檔案。

// Update Uri and pathvar client = new api.WebClient("https://cavalry.studio");client.get("/path/to/logo.svg");if (client.status() == 200) {    api.writeToFile("/path/to/cavLogo.svg", client.body());}

WebClient

使用 WebClient 時，建構函式只能包含基本 URL（例如 https://www.boredapi.com）。傳入路由（例如 https://www.boredapi.com/api/activity）將導致錯誤，WebClient.status() 將回傳 -1。

setBasicAuthentication(username:string, password:string)

為任何後續請求設定基本驗證。

setDigestAuthentication(username:string, password:string)

為任何後續請求設定摘要驗證。

setTokenAuthentication(token:string)

為任何後續請求設定基於權杖的驗證。

addHeader(key:string, value:string)

為後續請求新增請求標頭。API 金鑰、應用金鑰、內容類型等可以透過此方式新增。

getHeaders() → object

var client = new api.WebClient("https://www.boredapi.com");client.get("/api/activity");if (client.status() == 200) {    let headers = client.getHeaders();    for (const [key, value] of Object.entries(headers)) {      console.log(`${key}: ${value}`);    }}

status() → int

回傳請求的狀態。例如 200 表示 OK。

body() → string

回傳的回應體。這通常是 JSON 格式，但如果您不確定，可以使用 getHeaders() 檢查 Content-Type 標頭。

get(path:string)

執行 get 請求。完成後，status() 以及如果成功的話 body() 應該可用。

post(path:string, content:string, contentType:string)

執行 post 請求。完成後，status() 以及如果成功的話 body() 應該可用。

put(path:string, content:string, contentType:string)

執行 put 請求。完成後，status() 以及如果成功的話 body() 應該可用。

postFromFile(path:string, filePath:string, contentType:string)

直接發布檔案的輔助方法。特別是在上傳二進位檔案（如圖片或影片）時需要此方法。執行 post 請求。完成後，status() 以及如果成功的話 body() 應該可用。

putFromFile(path:string, filePath:string, contentType:string)

直接發布檔案的輔助方法。特別是在上傳二進位檔案（如圖片或影片）時需要此方法。執行 put 請求。完成後，status() 以及如果成功的話 body() 應該可用。

writeBodyToBinaryFile(path:string)

如果使用 get 取得了二進位資料（即圖片或影片），則不能將其傳遞給通常的 api.writeToFile() 呼叫。您必須使用此函式將回應體資料寫入檔案（然後可以將其作為資源拉入 Cavalry 中）。

setProxy(hostAddress:string, port:number)

輸入代理伺服器的 IP 和埠號。

setProxyBasicAuthentication(username:string, password:string)

輸入使用者名稱和密碼以向代理伺服器進行驗證。

setProxyBearerAuthentication(password:string)

為使用 bearer 權杖的代理伺服器輸入密碼。

WebServer

一個實作 Cavalry Server 的 UI 指令碼的完整範例。請將其儲存到 Cavalry Scripts 資料夾 Help > Scripts 中，然後透過 Window > Scripts 選單載入。

var server = new api.WebServer();var button = new ui.Button("Start Server");button.onClick = function () {    if (!server.isRunning()) {        server.listen("localhost", 1234);        button.setText("Stop Server");    } else {        server.stop();        button.setText("Start Server");    }}function Callbacks() {     this.onPost = function () {        console.log("Queue length: "+server.postCount());        processButton.setEnabled(true);    }}var processButton = new ui.Button("Process Posts");processButton.setEnabled(false);processButton.onClick = function () {    while(server.postCount()) {        let obj = server.getNextPost();        console.log("Process: "+obj.result);    }    processButton.setEnabled(false);}var callbackObj = new Callbacks();server.addCallbackObject(callbackObj);ui.add(button);ui.add(processButton);ui.show();

此指令碼執行後，在 JavaScript Editor 中執行以下程式碼，/post 文字應該列印到主控台。

var client = new api.WebClient("http://localhost:1234");client.post("/post", "Cavalry Needs You!", "text/plain");client.post("/post", "Join the Cavalry!", "text/plain");

listen(host:string, port:int)

在指定的埠號上啟動伺服器偵聽主機位址（例如 localhost）。

stop()

停止伺服器，任何輪詢也將停止。

setResultForGet(resultText:string)

設定 /get 請求的結果，目前僅支援 text/plain。

getNextPost() → object

由於在您有機會回應之前可能發生多次 /post 事件，Cavalry 將為您排隊。此函式將取得下一個（最舊的）post 並將其從佇列中彈出，意味著一旦您取得它，就無法再從伺服器存取它。該物件將包含一個 result 字串和一個 headers 陣列，每個 header 是一個具有 name 和 value 的物件。請注意，/post 事件僅支援非二進位資料。

getNewestPost() → object

與上述方法相同，只是它跳過未處理的 /post，取得最新的並從佇列中彈出。

postCount() → int

回傳未處理的 /post 事件數。使用 getNextPost() 或 getNewestPost() 函式處理 post。

clearPosts()

清除所有未處理的 /post 事件。使用 getNextPost() 或 getNewestPost() 函式處理 post。

addCallbackObject(callbackObj:object)

設定回呼物件（類似於 UI 回呼物件）。這是一個實作了 onPost 函式的 JavaScript 物件。設定回呼物件將啟動伺服器輪詢新資訊。預設情況下，每 3 秒輪詢伺服器一次。

var server = new api.WebServer();function Callbacks() {     this.onPost = function () {        console.log("Check result: " + server.getNewestPost().result);    }}var callbackObj = new Callbacks();server.addCallbackObject(callbackObj);

setHighFrequency()

在設定回呼物件後呼叫此方法將輪詢頻率更改為每秒一次。

setRealtime()

在設定回呼物件後呼叫此方法將輪詢頻率更改為每秒 60 次。這對於與 MIDI 控制器等裝置進行即時通訊非常有用。