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)

ベアラートークンを使用するプロキシサーバーのパスワードを入力します。

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 配列が含まれ、各ヘッダーは 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()

コールバックオブジェクト設定後に呼び出すと、ポーリング頻度が 1 秒に 1 回に変わります。

setRealtime()

コールバックオブジェクト設定後に呼び出すと、ポーリング頻度が 1 秒に 60 回に変わります。MIDI コントローラーなどとのリアルタイム通信に便利です。