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()

在设置回调对象后调用此方法将轮询频率更改为每秒一次。