遠端控制協定
約 2263 字大約 8 分鐘
若要實作對 MAA 的遠端控制,您須提供一個服務,該服務必須是 HTTP(S) 服務,並提供下列兩個可匿名存取的端點(Endpoint)。這兩個端點必須是 HTTP(S) 協定的 Web 端點。
注意
若該端點為 HTTP 協定,MAA 會在每次連線時發出不安全警告。在外網上部署明文傳輸服務是極不推薦且危險的行為,僅供測試使用。
提示
請注意,json 檔案不支援註解。文件中的註解僅供說明參考,請勿直接複製使用。
獲取任務端點
MAA 會以 1 秒的間隔持續輪詢此端點,嘗試獲取要執行的任務,並按照獲取到的列表依序執行。
端點路徑不限,但必須是 HTTP(S) 端點。例如:https://your-control-host.net/maa/getTask
被控端 MAA 須將該端點填寫至 MAA 設定的 獲取任務端點 文字框中。
該端點必須能接受 Content-Type=application/json 的 POST 請求,且該請求必須可接受下列 JSON 作為請求內容(Content):
{
"user":"ea6c39eb-a45f-4d82-9ecc-33a7bf2ae4dc", // 使用者在 MAA 設定中填寫的使用者識別碼。
"device":"f7cd9682-3de9-4eef-9137-ec124ea9e9ec" // MAA 自動產生的設備識別碼。
... // 若您的端點有其他用途,可自行新增選填參數,但 MAA 只會傳遞 user 與 device。
}該端點必須回傳 json 格式的 Response,且至少須滿足下列格式:
{
"tasks": // 須讓 MAA 執行的 Task 列表。目前支援的類型如範例所示,若不存在 tasks 則視為連線無效。
[
// 順序執行任務:下列任務會按照指派順序排隊執行
{
"id": "b353c469-b902-4357-bd8f-d133199eea31", // 任務唯一 ID(字串),彙報任務時會使用。
"type": "CaptureImage" // 截圖任務。會擷取一張目前模擬器截圖,並以 Base64 字串形式置於彙報任務的 payload 中。若需下發此類型任務,請務必注意端點可接受的最大請求限制,因截圖可能達數十 MB,會超過一般網關的預設大小限制。
},
{
"id": "15be4725-5bd3-443d-8ae3-0a5ae789254c", // 任務唯一 ID(字串),彙報任務時會使用。
"type": "LinkStart" // 啟動一鍵長草。
},
{
"id": "15be4725-5bd3-443d-8ae3-0a5ae789254c", // 任務唯一 ID(字串),彙報任務時會使用。
"type": "LinkStart-Recruiting" // 立即根據當前設定,單獨執行一鍵長草中的對應子功能,無視主介面上該功能的勾選框。此類 Type 的可選值詳見下述。
},
{
"id": "b353c469-b902-4357-bd8f-d133199eea31", // 任務唯一 ID(字串),彙報任務時會使用。
"type": "Toolbox-GachaOnce" // 工具箱抽卡任務。可選值:Toolbox-GachaOnce, Toolbox-GachaTenTimes。
},
{
"id": "b353c469-b902-4357-bd8f-d133199eea31", // 任務唯一 ID(字串),彙報任務時會使用。
"type": "Settings-ConnectionAddress", // 修改設定項任務,等同於執行 ConfigurationHelper.SetValue("ConnectionAddress", params)。為求安全,僅部分設定可修改,詳見下述。
"params": "value" // 要修改的值。
},
// 立即執行任務:下列任務可在順序執行任務運作中執行,且 MAA 保證任何一個任務都會儘快回傳結果,通常用於控制遠端控制功能本身。
{
"id": "b353c469-b902-4357-bd8f-d133199eea31", // 任務唯一 ID(字串),彙報任務時會使用。
"type": "CaptureImageNow" // 立刻截圖任務。與上方截圖任務基本相同,區別在於此任務會立刻執行,不會等待其他任務。
},
{
"id": "b353c469-b902-4357-bd8f-d133199eea31", // 任務唯一 ID(字串),彙報任務時會使用。
"type": "StopTask" // 「結束目前任務」。將嘗試結束目前執行的任務。若列表內還有其他任務,將繼續執行下一個。該任務不會等待並確認目前任務已停止才回傳,請使用心跳任務確認停止指令是否生效。
},
{
"id": "b353c469-b902-4357-bd8f-d133199eea31", // 任務唯一 ID(字串),彙報任務時會使用。
"type": "HeartBeat" // 心跳任務。會立即回傳,並將目前「順序執行任務」隊列中正在執行的任務 ID 作為 Payload 回傳;若目前無任務執行,則回傳空字串。
}
],
... // 若您的端點有其他用途,可自行新增回傳值,但 MAA 只會讀取 tasks。
}這些任務會依序執行,意即若先指派一項公招任務,再指派一項截圖任務,則截圖會在公招任務結束後才執行。 該端點應具備可重入性,並可重複回傳須執行的任務。MAA 會自動記錄任務 ID,相同 ID 不會重複執行。
注
LinkStart-[TaskName]型任務的 type 可選值為:LinkStart-Base, LinkStart-WakeUp, LinkStart-Combat, LinkStart-Recruiting, LinkStart-Mall, LinkStart-Mission, LinkStart-AutoRoguelike, LinkStart-Reclamation。Settings-[SettingsName]型任務的 type 可選值為:Settings-ConnectionAddress, Settings-Stage1。- Settings 系列任務仍須依序執行,收到任務時不會立刻執行,而是排在上一項任務之後。
- 多個立即執行任務亦會按部就班執行,但因執行速度極快,通常無需關注其順序。
彙報任務端點
每當 MAA 執行完一項任務,就會透過此端點將執行結果彙報給遠端。
端點路徑不限,但必須是 HTTP(S) 端點。例如:https://your-control-host.net/maa/reportStatus
被控端 MAA 須將該端點填寫至 MAA 設定的 彙報任務端點 文字框中
該端點必須能接受 Content-Type=application/json 的 POST 請求,且請求內容(Content)須符合下列 json 格式:
{
"user":"ea6c39eb-a45f-4d82-9ecc-33a7bf2ae4dc", // 使用者在 MAA 設定中填寫的使用者識別碼。
"device":"f7cd9682-3de9-4eef-9137-ec124ea9e9ec", // MAA 自動產生的設備識別碼。
"task":"15be4725-5bd3-443d-8ae3-0a5ae789254c", // 要彙報的任務 ID,與獲取任務時的 ID 對應。
"status":"SUCCESS", // 任務執行結果:SUCCESS 或 FAILED。通常不論成敗皆彙報 SUCCESS,僅特殊情形才會彙報 FAILED(相關情形於上方任務介紹中說明)。
"payload":"", // 彙報時攜帶的資料(字串)。視任務類型而定,如截圖任務彙報時,會攜帶截圖的 Base64 字串。
... // 若您的端點有其他用途,可自行新增選填參數,但 MAA 只會傳遞 user 與 device。
}該端點的回傳內容不限,但若未回傳 200 OK,MAA 端會彈出通知顯示 上傳失敗。
範例工作流——使用 QQBot 控制 MAA
開發者 A 想要用自己的 QQBot 控制 MAA,因此開發了一個後端服務並部署於外網上,提供兩個端點:
https://myqqbot.com/maa/getTask
https://myqqbot.com/maa/reportStatus為了提升使用者體驗,他的 getTask 介面不論接收何種參數,均預設回傳 200 OK 與空的 tasks 列表。
每當接收到請求,他會檢查資料庫是否有重複的 device;若無,則將該 device 與 user 記錄在資料庫中。
意即在此工作流下,該介面同時承擔了使用者註冊的功能。
他在 QQBot 上提供一條指令,供使用者提交自己的 deviceId。
在 QQBot 的使用說明中,他引導使用者在 MAA 的 使用者識別碼 填寫自己的 QQ 號,再將 設備識別碼 透過 QQ 傳送給 Bot。
QQBot 收到識別碼後,根據訊息中的使用者 QQ 號尋找資料庫是否有對應資料;若無,則要求使用者先設定 MAA。
由於 MAA 設定完成後會持續發送請求,因此當使用者透過 QQ 提交時,資料庫內理應已有匹配記錄。
此時 Bot 將資料庫內的該筆記錄標記為「已驗證」。日後 getTask 收到相同的 device 與 user 請求時,便會回傳真正的任務列表。
當使用者透過 QQBot 提交指令後,Bot 將一項任務寫入資料庫,稍後 getTask 便會回傳該任務。此外,該 QQBot 甚至在每次使用者提交指令後,均預設額外指派一個截圖任務。
MAA 執行完畢後會調用 reportStatus 彙報結果,Bot 收到結果後便於 QQ 端發送通知並展示截圖。
範例工作流——用網站控制 MAA
開發者 B 寫了一個網站,設想透過網站批次管理 MAA,因此擁有一套自有的使用者管理系統。他的後端部署於外網上,提供兩個可匿名存取的端點:
https://mywebsite.com/maa/getTask
https://mywebsite.com/maa/reportStatus網站上的連線介面會展示一個稱為 使用者金鑰 的隨機字串,並提供一個填入設備 ID 的文字框。
網站要求使用者在 MAA 的 使用者識別碼 填寫使用者金鑰,並將 設備識別碼 填入網站。
唯有在網站上成功建立 MAA 連線,getTask 才會回傳 200 OK,其餘情況均回傳 401 Unauthorized。
因此若使用者在 MAA 填錯資訊,按下測試連線按鈕時會提示測試失敗。
使用者可於網站上指派任務、排隊、查看截圖等,這些功能的實作方式與上述 QQBot 範例類似,皆透過 getTask 與 reportStatus 組合達成。
