MaaAssistantArknights/docs/ko-kr/protocol/remote-control-schema.md

---
order: 8
icon: mdi:remote-desktop
---

# 원격 제어 프로토콜

MAA를 원격으로 제어하려면 http(s) 서비스를 제공해야 합니다. 이 서비스는 아래 두 가지 익명 엔드포인트(Endpoint)를 제공해야 하며, 두 엔드포인트는 http(s) 프로토콜의 Web 엔드포인트여야 합니다.

::: warning
엔드포인트가 http 프로토콜인 경우 MAA는 연결 시마다 '안전하지 않음' 경고를 표시합니다. **공개 네트워크에 평문 전송 서비스를 배포하는 것은 매우 위험하므로 권장하지 않습니다. 테스트 용도로만 사용해 주세요.**
:::

::: tip
주의: JSON 파일은 주석을 지원하지 않으므로 아래의 예시에서 주석은 제거하고 사용해 주세요.
:::

## 작업 획득 엔드포인트 (Get Task)

MAA는 이 엔드포인트를 1초 간격으로 지속적으로 폴링하여 실행할 작업을 가져옵니다. 그리고 가져온 목록에 따라 순서대로 작업을 실행합니다.

엔드포인트 경로는 자유롭지만 반드시 http(s) 엔드포인트여야 합니다.  
예: `https://your-control-host.net/maa/getTask`

제어 대상 MAA의 설정 내 `작업 획득 엔드포인트` 입력란에 해당 엔드포인트를 입력해 주세요.

이 엔드포인트는 `Content-Type=application/json`인 POST 요청을 받을 수 있어야 하며, 요청 본문(Body)으로 아래와 같은 JSON을 수신할 수 있어야 합니다.

```json
{
    "user":"ea6c39eb-a45f-4d82-9ecc-33a7bf2ae4dc",          // 사용자가 MAA 설정에 입력한 사용자 식별자
    "device":"f7cd9682-3de9-4eef-9137-ec124ea9e9ec"         // MAA가 자동 생성한 기기 식별자
    ...     // 이 엔드포인트에 다른 용도가 있다면 선택적 파라미터를 추가할 수 있지만, MAA는 user와 device만 전송합니다.
}
```

이 엔드포인트는 JSON 형식의 응답(Response)을 반환해야 하며, 최소한 다음 형식을 만족해야 합니다.

```json
{
    "tasks":                            // MAA가 실행해야 할 작업(Task) 목록입니다. 현재 지원되는 유형은 아래 예시와 같습니다. tasks가 없으면 연결 실패로 간주합니다.
    [
        // 순차 실행 작업: 아래 작업들은 전달된 순서대로 대기열에 들어가 실행됩니다.
        {
            "id": "b353c469-b902-4357-bd8f-d133199eea31",   // 작업의 고유 ID (문자열). 작업 보고 시 사용됩니다.
            "type": "CaptureImage",                         // 스크린샷 작업. 현재 에뮬레이터 화면을 캡처하여 작업 보고의 payload에 Base64 문자열로 담습니다. 이 작업을 내릴 때는 엔드포인트가 허용하는 최대 요청 크기에 주의해 주세요. 스크린샷은 수십 MB에 달할 수 있어 일반적인 게이트웨이의 기본 제한을 초과할 수 있습니다.
        },
        {
            "id": "15be4725-5bd3-443d-8ae3-0a5ae789254c",   // 작업의 고유 ID
            "type": "LinkStart",                            // 원클릭 파밍 시작 (StartUp)
        },
        {
            "id": "15be4725-5bd3-443d-8ae3-0a5ae789254c",   // 작업의 고유 ID
            "type": "LinkStart-Recruiting",                 // 현재 설정에 따라 원클릭 파밍의 하위 기능(예: 공개모집)을 단독 실행합니다. 메인화면의 체크 여부는 무시합니다. 선택 가능한 값은 아래 설명을 참고하세요.
        },
        {
            "id": "b353c469-b902-4357-bd8f-d133199eea31",   // 작업의 고유 ID
            "type": "Toolbox-GachaOnce",                    // 툴박스의 1회 뽑기 작업. 선택 가능 값: 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",                             // 현재 작업 중지. 실행 중인 작업을 중지하고, 목록에 대기 중인 다음 작업이 있다면 실행합니다. 이 명령은 중지 완료를 기다리지 않고 반환되므로, 중지 여부는 HeartBeat로 확인해 주세요.
        },
        {
            "id": "b353c469-b902-4357-bd8f-d133199eea31",   // 작업의 고유 ID
            "type": "HeartBeat",                            // 하트비트 작업. 즉시 반환되며, 현재 '순차 실행 작업' 큐에서 실행 중인 작업의 ID를 payload로 반환합니다. 실행 중인 작업이 없으면 빈 문자열을 반환합니다.
        },
    ],
    ...     // 이 엔드포인트에 다른 용도가 있다면 선택적 반환값을 추가할 수 있지만, MAA는 tasks만 읽습니다.
}
```

이 작업들은 순서대로 실행됩니다. 예를 들어 공개모집 작업을 먼저 보내고 스크린샷 작업을 보내면, 스크린샷은 공개모집이 끝난 뒤 실행됩니다.
이 엔드포인트는 재진입 가능해야 하며, 실행할 작업을 반복해서 반환해야 합니다. MAA는 작업 ID를 자동으로 기록하여, 동일한 ID의 작업은 중복 실행하지 않습니다.

::: note

- **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** 시리즈 작업은 순차 실행 작업으로 간주되어, 수신 즉시 실행되지 않고 이전 작업이 끝난 뒤 실행됩니다.
- 복수의 **즉시 실행 작업**도 전달된 순서대로 실행되지만, 실행 속도가 매우 빠르므로 순서는 크게 신경 쓰지 않아도 됩니다.

:::

## 작업 보고 엔드포인트 (Report Status)

MAA가 작업을 완료하면, 이 엔드포인트를 통해 작업 실행 결과를 원격 서버로 보고합니다.

엔드포인트 경로는 자유롭지만 반드시 http(s) 엔드포인트여야 합니다.  
예: `https://your-control-host.net/maa/reportStatus`

제어 대상 MAA의 설정 내 `작업 보고 엔드포인트` 입력란에 해당 엔드포인트를 입력해 주세요.

이 엔드포인트는 `Content-Type=application/json`인 POST 요청을 받을 수 있어야 하며, 요청 본문(Body)으로 아래와 같은 JSON을 수신할 수 있어야 합니다.

```json
{
    "user":"ea6c39eb-a45f-4d82-9ecc-33a7bf2ae4dc",          // 사용자가 MAA 설정에 입력한 사용자 식별자
    "device":"f7cd9682-3de9-4eef-9137-ec124ea9e9ec",        // MAA가 자동 생성한 기기 식별자
    "task":"15be4725-5bd3-443d-8ae3-0a5ae789254c",          // 보고할 작업의 ID (Get Task 시 받은 ID와 일치)
    "status":"SUCCESS",                                     // 작업 실행 결과 (SUCCESS 또는 FAILED). 일반적으로 성공/실패 여부와 관계없이 SUCCESS만 반환하며, 특수한 경우에만 FAILED를 반환합니다(해당 작업 설명에 명시됨).
    "payload":"",                                           // 보고 데이터 (문자열). 작업 유형에 따라 다릅니다. 예: 스크린샷 작업은 여기에 Base64 문자열이 들어갑니다.
    ...     // 이 엔드포인트에 다른 용도가 있다면 선택적 파라미터를 추가할 수 있지만, MAA는 user와 device만 전송합니다.
}
```

이 엔드포인트의 반환 내용은 자유롭지만, 200 OK를 반환하지 않으면 MAA 측에 `업로드 실패` 알림이 표시됩니다.

## 예시 워크플로우 - QQBot으로 MAA 제어

A 개발자는 자신의 QQBot으로 MAA를 제어하고 싶어 합니다. 이를 위해 공용 네트워크에 노출된 백엔드를 개발하고 두 개의 엔드포인트를 제공했습니다:

```text
https://myqqbot.com/maa/getTask
https://myqqbot.com/maa/reportStatus
```

사용자 편의를 위해 `getTask` 인터페이스는 어떤 파라미터가 오든 기본적으로 200 OK와 빈 `tasks` 목록을 반환합니다.
A는 요청이 올 때마다 데이터베이스에 중복된 `device`가 있는지 확인하고, 없으면 해당 `device`와 `user`를 기록합니다. 즉, 이 인터페이스는 사용자 등록 기능도 겸합니다.

A는 QQBot에 사용자가 자신의 `deviceId`를 제출할 수 있는 명령어를 추가했습니다.
그리고 사용 설명서에 "MAA의 `사용자 식별자`에 자신의 QQ 번호를 적고, `기기 식별자`를 복사해서 봇에게 보내세요"라고 안내했습니다.

QQBot이 식별자를 받으면, 메시지를 보낸 유저의 QQ 번호를 이용해 데이터베이스에 해당 기록이 있는지 찾습니다. 없으면 사용자에게 MAA 설정을 먼저 하라고 안내합니다.
(MAA를 설정하면 지속적으로 요청을 보내므로, 사용자가 봇에게 메시지를 보낼 즈음엔 이미 DB에 기록이 있어야 합니다.)

기록이 있다면 봇은 해당 DB 레코드에 '인증됨' 표시를 합니다. 이제 `getTask`는 인증된 `device`와 `user` 요청에 대해 진짜 작업 목록을 반환하기 시작합니다.

사용자가 QQBot을 통해 명령(예: "파밍 시작")을 내리면, 봇은 DB에 작업을 추가합니다. 잠시 후 `getTask` 요청이 오면 이 작업을 반환합니다. A는 친절하게도 사용자가 명령을 보낼 때마다 자동으로 스크린샷 작업도 하나씩 추가하도록 만들었습니다.

MAA가 작업을 마치고 `reportStatus`를 호출하면, 봇은 결과를 받아 사용자에게 QQ 메시지로 알림과 스크린샷을 전송합니다.

## 예시 워크플로우 - 웹사이트로 MAA 제어

B 개발자는 웹사이트를 통해 MAA를 대량으로 관리하고 싶습니다. 자체 회원 시스템이 있는 웹사이트 백엔드를 만들고, 익명 접근 가능한 두 엔드포인트를 열었습니다:

```text
https://mywebsite.com/maa/getTask
https://mywebsite.com/maa/reportStatus
```

웹사이트에는 MAA 연결 페이지가 있고, B가 `사용자 키`라고 부르는 랜덤 문자열과 `기기 식별자` 입력칸이 있습니다.
웹사이트는 사용자에게 "MAA의 `사용자 식별자`에 이 사용자 키를 넣고, MAA의 `기기 식별자`를 여기에 입력하세요"라고 안내합니다.

웹사이트에서 '연결 생성'이 성공해야만 `getTask`가 200 OK를 반환하도록 하고, 그 외에는 401 Unauthorized를 반환하게 설정했습니다.
따라서 사용자가 MAA에 정보를 잘못 입력하고 '연결 테스트'를 누르면 실패 알림을 받게 됩니다.

사용자는 웹사이트에서 작업을 내리고, 대기열을 확인하고, 스크린샷을 볼 수 있습니다. 구현 방식은 QQBot 예시와 비슷하게 `getTask`와 `reportStatus`의 조합으로 이루어집니다.