Virtual Machine Manager API 소개

관련지식
synology, vmm, api

시놀로지에서는 몇가지 기능에 대해 API를 제공하고 있습니다. 대표적으로 크롬 확장프로그램의 Download Station 이 API를 이용해서 개발된것인데요. Virtual Machine Manager 에서도 일부 기능에 대한 API를 제공하고 있습니다.

Synology Virtual Machine Manager API Guide
https://global.download.synology.com/download/Document/Software/DeveloperGuide/Package/Virtualization/All/enu/Synology_Virtual_Machine_Manager_API_Guide.pdf

몇가지만 소개하겠습니다.

로그인

API를 사용할수 있는 권한이 필요하기 때문에 로그인 과정이 필요합니다. 아래 URL에서 아이디와 비밀번호를 수정하여 호출합니다.

/webapi/auth.cgi?api=SYNO.API.Auth&method=login&version=3&account=아이디&passwd=비밀번호&format=sid&session=dsm_info

올바르게 입력했다면 아래와 같은 값을 받게 됩니다.

{"data":{"sid":"Q6LNev8pHtg3k14B0MPN931252"},"success":true}

sid는 세션아이디로 이후 모든 호출에서 사용되므로 저장해두면 됩니다.(로그인 할때마다 바뀝니다.) 실패했을 경우 에러코드를 주게 되는데 API 가이드에서 에러코드를 찾으면 원인을 확인할 수 있습니다.

목록 조회

만들어진 Virtual Machine 목록을 조회할수 있습니다.

/webapi/entry.cgi?api=SYNO.Virtualization.API.Guest&version=1&method=list&additional=true&_sid=세션아이디

정상적으로 호출할 경우 아래와 같은 데이터를 받게 됩니다. 저는 한개가 설치되어있어서 하나만 나오지만, 여러개 설치된 경우 더 많이 보시게 됩니다. guest_name은 다른 API를 호출할때 또 사용됩니다.

{
    "data": {
        "guests": [
            {
                "autorun": 0,
                "description": "",
                "guest_id": "a8100eec-b8d5-45cd-8a8d-881ef6d6199a",
                "guest_name": "window10",
                "ip": [],
                "status": "shutdown",
                "storage_id": "93ed49a5-ed6f-4c58-a5dc-7e3a7d8c1648",
                "storage_name": "storage1",
                "vcpu_num": 4,
                "vdisks": [
                    {
                        "controller": 1,
                        "unmap": false,
                        "vdisk_id": "6b76f7f4-68f7-4b3d-a9c7-0600b462ee46",
                        "vdisk_size": 122880
                    }
                ],
                "vnics": [
                    {
                        "mac": "02:11:32:20:e1:ef",
                        "model": 2,
                        "network_id": "bfeee844-3dee-48fd-a1cc-00d2cae7b767",
                        "network_name": "Default VM Network",
                        "vnic_id": "a8d379de-7f72-4c5e-a523-5393e1723fb9"
                    }
                ],
                "vram_size": 4096
            }
        ]
    },
    "success": true
}

가상머신 On/Off

아래 세개의 API는 파라미터만 다를뿐 호출 구조는 완전히 동일합니다.

전원켜기

/webapi/entry.cgi?_sid=세션아이디&api=SYNO.Virtualization.API.Guest.Action&method=poweron&version=1&guest_name=게스트이름

종료하기

/webapi/entry.cgi?_sid=세션아이디&api=SYNO.Virtualization.API.Guest.Action&method=shutdown&version=1&guest_name=게스트이름

강제종료

/webapi/entry.cgi?_sid=세션아이디&api=SYNO.Virtualization.API.Guest.Action&method=poweroff&version=1&guest_name=게스트이름

‘종료하기’ 와 ‘강제종료’ 는 VMM 메뉴에서도 구분되어 있습니다. OS에 종료 시그널을 보내는것과, 전원 버튼을 꾹 눌러서 끄는 차이인것 같네요.

참고

참고로 가상 머신이 실행중인 경우에는 NAS의 전원예약 종료가 되지 않습니다. 수동으로 종료하려고 할 경우에도, 아래와 같은 메시지가 보이게 되죠. 그런데 VMM 메뉴를 열어볼때까지는 가상머신의 실행 여부를 알기가 좀 어렵습니다. 필요하다면 위 API를 이용해서 가상머신 On/Off 기능이나 가상머신 상태 대시보드를 만들수가 있습니다.