mirror of
https://github.com/MaaAssistantArknights/MaaAssistantArknights.git
synced 2026-07-16 17:57:01 +08:00
67bbf9aac5
Co-authored-by: wlwxj <d1ve_wh4le@outlook.com> Co-authored-by: Rbqwow <55343783+Rbqwow@users.noreply.github.com> Co-authored-by: Constrat <56174894+Constrat@users.noreply.github.com> Co-authored-by: HX3N <scarlet7518@gmail.com> Co-authored-by: Wallsman <63186641+wallsman@users.noreply.github.com> Co-authored-by: Loong <wangl.cc@outlook.com> Co-authored-by: 神代綺凛 <i@loli.best> Co-authored-by: SherkeyXD <57581480+SherkeyXD@users.noreply.github.com>
161 lines
13 KiB
Markdown
161 lines
13 KiB
Markdown
---
|
|
order: 8
|
|
icon: mdi:remote-desktop
|
|
---
|
|
|
|
# 원격 제어 프로토콜
|
|
|
|
MAA를 원격으로 제어하려면 http(s) 서비스를 제공해야 합니다. 이 서비스는 아래 두 가지 익명 엔드포인트를 제공해야 합니다. 이 두 엔드포인트는 웹 엔드포인트이며 http(s) 프로토콜이어야 합니다.
|
|
|
|
::: warning
|
|
엔드포인트가 http 프로토콜인 경우 MAA는 연결시마다 안전하지 않음 경고를 발생시킵니다. **공개 네트워크에 프로토콜을 배포하는 것은 매우 권장되지 않으며 위험합니다. 테스트 용도로만 사용하세요!**
|
|
:::
|
|
|
|
::: tip
|
|
주의: JSON 형식은 주석을 지원하지 않으므로 아래의 예시에서 주석은 제거해주시기 바랍니다.
|
|
:::
|
|
|
|
## 작업 엔드포인트 가져오기
|
|
|
|
MAA는 이 엔드 포인트를 계속하여 폴링하여 실행해야하는 작업을 시도하고 가져와야합니다. 그리고 가져온 목록에 따라 순서대로 실행합니다.
|
|
|
|
엔드 포인트 경로는 자유롭지만 반드시 http(s) 엔드 포인트 여야합니다. 예를 들어: `https://your-control-host.net/maa/getTask`
|
|
|
|
제어 대상 MAA는 이 엔드포인트를 MAA 설정의 `작업 가져오기 엔드포인트` 텍스트 상자에 작성해야합니다.
|
|
|
|
이 엔드포인트는 `Content-Type=application/json`의 POST 요청을 수락해야하며, 이 요청은 다음과 같은 JSON을 요청 본문으로 수락 할 수 있어야합니다.
|
|
|
|
```json
|
|
{
|
|
"user":"ea6c39eb-a45f-4d82-9ecc-33a7bf2ae4dc", // 사용자가 MAA 설정에 제공한 사용자 식별자.
|
|
"device":"f7cd9682-3de9-4eef-9137-ec124ea9e9ec" // MAA가 생성 한 장치 식별자.
|
|
... // 이 엔드포인트에 다른 용도가 있는 경우 선택적 매개 변수를 추가 할 수 있지만 MAA는 user 및 device 만 전달합니다.
|
|
}
|
|
```
|
|
|
|
이 엔드포인트는 JSON 형식의 응답을 반환해야하며 최소한 다음 형식을 충족해야합니다.
|
|
|
|
```json
|
|
{
|
|
"tasks": // MAA가 실행해야하는 Task 목록입니다. 현재 지원되는 유형은 아래 예시와 같습니다. 작업이없는 경우 연결이 무효로 간주됩니다.
|
|
[
|
|
// 순차 실행 작업: 아래 작업은 전달된 순서대로 대기열에 들어갑니다
|
|
{
|
|
"id": "b353c469-b902-4357-bd8f-d133199eea31", //작업의 고유 ID, 문자열 형식입니다. 작업 보고서에 사용됩니다.
|
|
"type": "CaptureImage", //스크린샷 작업입니다. 현재 시뮬레이터의 스크린샷을 캡처하고 작업 보고서의 페이로드에 Base64 문자열로 넣습니다. 이러한 유형의 작업을 발행해야하는 경우 요청하는 엔드 포인트가 수용 할 수 있는 최대 요청 크기에 주의하세요. 스크린샷은 수십 메가바이트가 있으며 일반적인 게이트웨이의 기본 크기 제한을 초과할 수 있습니다.
|
|
},
|
|
{
|
|
"id": "15be4725-5bd3-443d-8ae3-0a5ae789254c", //작업의 고유 ID, 문자열 형식입니다. 작업 보고서에 사용됩니다.
|
|
"type": "LinkStart", //원 클릭 모의 농장 시작
|
|
},
|
|
{
|
|
"id": "15be4725-5bd3-443d-8ae3-0a5ae789254c", //작업의 고유 ID, 문자열 형식입니다. 작업 보고서에 사용됩니다.
|
|
"type": "LinkStart-Recruiting", //현재 구성에 따라 원 클릭 모의 농장의 해당 하위 기능을 독립적으로 실행합니다. 주 요구 사항에 대한 이러한 타입의 옵션은 아래에 나와 있습니다.
|
|
},
|
|
{
|
|
"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를 페이로드로 반환합니다. 현재 작업이 없으면 빈 문자열을 반환합니다.
|
|
},
|
|
],
|
|
... //이 엔드포인트에 다른 용도가 있는 경우 선택적 반환 값을 추가 할 수 있지만 MAA는 작업 만 읽습니다.
|
|
}
|
|
```
|
|
|
|
이러한 작업은 순서대로 실행되므로 먼저 공개 인수를 내보내고 나중에 스크린샷을 보내면 스크린샷이 공개 인수 이후에 실행됩니다.
|
|
이 엔드 포인트는 재진입이 가능하고 반복적으로 작업을 반환해야합니다. MAA는 작업 ID를 자동으로 기록하며 동일한 ID의 경우 작업을 다시 실행하지 않습니다.
|
|
|
|
::: note
|
|
|
|
- LinkStart-[TaskName] 유형의 작업 유형의 LinkStart의 선택 가능한 값은 LinkStart-Base, LinkStart-WakeUp, LinkStart-Combat, LinkStart-Recruiting, LinkStart-Mall, LinkStart-Mission, LinkStart-AutoRoguelike, LinkStart-ReclamationAlgorithm입니다.
|
|
- Settings-[SettingsName] 작업 유형의 유형 매개 변수의 선택 가능한 값은 Settings-ConnectionAddress, Settings-Stage1입니다.
|
|
- 설정 시리즈 작업은 여전히 순서대로 실행되며 작업을 받은 즉시 실행되지 않으며 이전 작업 뒤에 배치됩니다.
|
|
- 여러 즉시 실행 작업은 순서대로 실행되지만 이러한 작업은 모두 빠르게 실행되므로 순서에 관심을 두지 않아도됩니다.
|
|
:::
|
|
|
|
## 작업 보고 엔드 포인트
|
|
|
|
MAA가 작업을 완료하면 작업의 실행 결과를 원격에 보고해야합니다.
|
|
|
|
엔드 포인트 경로는 자유롭지만 반드시 http(s) 엔드 포인트 여야합니다. 예를 들어: `https://your-control-host.net/maa/reportStatus`
|
|
|
|
제어 대상 MAA는이 엔드 포인트를 MAA 설정의 `작업 보고 엔드포인트` 텍스트 상자에 작성해야합니다
|
|
|
|
이 엔드포인트는 `Content-Type=application/json`의 POST 요청을 수락해야하며, 이 요청은 다음과 같은 JSON을 요청 본문으로 수락 할 수 있어야합니다.
|
|
|
|
```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 만 반환됩니다. 특별한 경우에만 실패를 반환합니다. 실패한 경우 상세 내용은 해당 작업 소개에서 명확하게 설명됩니다.
|
|
"payload":"", // 보고서에 대한 데이터는 문자열 형식입니다. 작업 유형에 따라 달라집니다. 예를 들어 스크린샷 작업 보고서는 여기에 스크린샷의 Base64 문자열을 가져옵니다.
|
|
... // 이 엔드포인트에 다른 용도가 있는 경우 선택적 매개 변수를 추가 할 수 있지만 MAA는 user 및 device 만 전달합니다.
|
|
}
|
|
```
|
|
|
|
이 엔드 포인트의 반환 내용은 상관 없습니다. 그러나 200OK를 반환하지 않으면 MAA 측에서 `업로드 실패`라는 알림이 표시됩니다.
|
|
|
|
## 예시 워크플로우 - QQBot을 사용하여 MAA 제어
|
|
|
|
A 개발자는 자신의 QQBot을 사용하여 MAA를 제어하려고합니다. 따라서 공개 네트워크에서 노출 된 백엔드를 개발하여 다음 두 가지 엔드포인트를 제공합니다.
|
|
|
|
> [!tip]
|
|
> https://myqqbot.com/maa/getTask
|
|
> https://myqqbot.com/maa/reportStatus
|
|
|
|
사용자의 편의를 위해 getTask 인터페이스는 어떤 매개 변수를 받더라도 기본적으로 200OK와 비어있는 작업 목록을 반환합니다.
|
|
요청이 수신되면 A는 데이터베이스에서 중복 장치를 확인하고 그렇지 않으면 해당 장치와 사용자를 데이터베이스에 기록합니다.
|
|
즉,이 워크플로우에서는이 엔드포인트가 사용자 등록을 담당합니다.
|
|
|
|
그는 QQBot에 사용자의 장치 ID를 제출하는 명령을 제공했습니다.
|
|
|
|
그의 QQBot 사용 설명서에는 MAA의 `사용자 식별자`에 자신의 QQ 번호를 입력하고 `장치 식별자`를 QQ 채팅으로 보내도록 지시합니다.
|
|
|
|
A는 장치 ID를 수신하면 QQBot이 메시지의 사용자 QQ 번호를 기준으로 데이터베이스에서 해당 레코드를 찾아보고 없으면 사용자가 먼저 MAA를 구성하라고 알립니다.
|
|
MAA를 구성 한 후 사용자가 MAA를 구성하면 MAA가 지속적으로 요청을 보내기 때문에 사용자가 MAA를 구성하면 메시지를 제출 할 때 데이터베이스에 일치하는 레코드가 있어야합니다.
|
|
|
|
이후 Bot은 데이터베이스의 해당 레코드를 확인하고 검증 된 플래그를 설정하여이 장치 및 사용자가 빠른 getTask 요청에 대한 진정한 작업 목록을 반환하도록합니다.
|
|
|
|
사용자가 QQBot을 통해 명령을 제출하면 Bot은 데이터베이스에 작업을 작성하므로 getTask가 이러한 작업을 반환합니다. 또한 사용자가 명령을 제출할 때마다,이 QQBot은 기본적으로 스크린 샷 작업 하나를 추가합니다.
|
|
|
|
작업이 완료되면 MAA가 reportStatus를 호출하여 결과를 보고하면 Bot은 결과를받고 사용자에게 메시지를 보내고 스크린 샷을 표시합니다.
|
|
|
|
## 예시 워크플로우 - 웹 사이트를 사용하여 MAA 제어
|
|
|
|
B 개발자는 웹 사이트를 작성했으며 웹 사이트를 통해 MAA를 대량으로 관리하려고합니다. 따라서 공개 네트워크에서 자체 사용자 관리 시스템을 보유하고 두 가지 익명 엔드 포인트를 제공하는 백엔드를 개발했습니다.
|
|
|
|
> [!tip]
|
|
> https://mywebsite.com/maa/getTask
|
|
> https://mywebsite.com/maa/reportStatus。
|
|
|
|
웹 사이트에는 MAA 인스턴스에 대한 연결을 표시하는 페이지가 있습니다. B 개발자는 랜덤 문자열을 `사용자 키`라고하는 이 페이지에 표시하고 장치 ID를 입력할 수있는 텍스트 상자가 있습니다.
|
|
|
|
웹 사이트는 MAA의 `사용자 식별자`에 사용자 키를 입력하고 `장치 식별자`를 웹 사이트에 입력하도록 요구합니다.
|
|
|
|
MAA의 설정에 올바르게 MAA 연결을 만들려면 웹 사이트에서 사용자 키 및 장치 ID가 정확해야합니다.
|
|
|
|
사용자가 웹 사이트를 통해 MAA에 대한 제어 명령을 제출하면 웹 사이트는 데이터베이스에 작업을 작성합니다.
|
|
|
|
웹 사이트는이 페이지를 공개하기 때문에 누구나 사용자 키를 복사하여 사용할 수 있지만 장치 ID가 없으면 적절한 데이터베이스 레코드를 찾을 수 없으므로 getTask 호출에 대한 결과는 빈 목록입니다.
|
|
|
|
작업이 완료되면 MAA가 reportStatus를 호출하여 결과를 보고하면 웹 사이트는 결과를받고 사용자에게 페이지를 업데이트하여 작업 결과를 표시합니다.
|
|
|
|
<!-- markdownlint-disable-file MD034 --> |