Synology File Station Upload & Download API

 

 테스트 환경

• Ubuntu 22.04
• DSM Version 6

DSM 로그인 웹 API 개발자 가이드를 확인해 보면 웹 API를 사용하여 DSM 로그인을 수행하는 방법을 설명하고 Synology NAS의 API를 기반으로 응용 프로그램을 확장하여 응용 프로그램이 HTTP/HTTPS 요청 및 응답을 통해 DSM 또는 DSM 패키지와 상호 작용할 수 있다고 한다.

 

본 글에서는 curl을 이용하여 해당 API를 진행한다.

 

가이드 문서를 보면 전체 API Work Flow는 아래와 같다.

 

 

먼저 애플리케이션이 Synology 프로덕션과 상호 작용하도록 하려면 애플리케이션이 먼저 계정과 비밀번호로 로그인해야 한다. 성공하면 API는 인증된 세션 ID를 반환하게 되는데, 반환한 세션 ID는 보관하고 다른 API 요청을 할 때 사용해야 한다.

 

로그인

로그인 API는 아래와 같은 형태로 사용 가능하다.

curl -X POST "http://{서버 주소}//webapi/auth.cgi" \
  -d "api=SYNO.API.Auth" \
  -d "version=3" \
  -d "method=login" \
  -d "account={사용자 계정}" \
  -d "passwd={계정 비밀번호}" \
  -d "session=FileStation" \
  -d "format=sid"

 

터미널 창에 위와 같이 입력을 하게 되면 세션 ID를 반환하게 된다. 세션 ID는 API 매개변수를 /webapi/entry.cgi 사용하여 요청을 통해 간단히 액세스 할 수 있다.

 

API에 대한 유효한 요청을 구성하는 데 사용되는 5가지 기본 요소는 다음과 같습니다.

path : API 경로. 
api : 요청된 API의 이름.

version : 요청된 API의 버전입니다.
method : 요청된 API의 메서드.
_sid : API를  사용하여 로그인 요청에 이미 Cookie를 저장하고 이 Cookie를 HTTP/HTTPS 헤더에 전달하는 경우 이 매개변수를 무시할 수 있습니다. 그렇지 않은 경우 API의 로그인 응답에서 검색할 수 있는 값을 인수 SYNO.API.Auth로 HTTP/HTTPS 또는 GET/POST 메서드를 전달합니다.

 

예를 들면 file1.txt라는 파일을 업로드하기 위해 업로드 API를 사용할 경우에는 아래와 같은 형식으로 진행한다. 

 

본 글에서는 _sid 옵션을 사용하지 않고 Cookie 매개 변수를 사용했다.

업로드

curl -X POST "http://{서버 주소}/webapi/entry.cgi" \
  -F "api=SYNO.FileStation.Upload" \
  -F "version=2" \
  -F "method=upload" \
  -F "path=/home/test" \
  -F "create_parents=true" \
  -F "file=@file1.txt" \
  -H "Cookie: id={세션 ID}"

 

업로드 API의 Parameter 값은 공식 API 가이드 문서에 나와 있다.

Cookie값의 경우 이전 로그인 API에서 반환한 세션 ID를 입력한다. 입력하면 아래와 같은 성공 실패 여부가 반환된다.

실제 File Station에 로그인해서 해당 폴더를 확인해 보면 file1.txt가 생성된 것을 알 수 있다.

다운로드 API도 업로드 API와 다르지 않다. 아래 명령은 업로드 API를 통해 업로드 한 file1.txt를 다운로드하여 file2.txt라는 이름으로 저장하는 명령어이다.

다운로드

curl -X GET "http://{서버 주소}/webapi/entry.cgi" \
  -G \
  -d "api=SYNO.FileStation.Download" \
  -d "version=2" \
  -d "method=download" \
  -d "path=/home/test/file1.txt" \
  -H "Cookie: id=n3FxMGxswVX7pUNliP1LfgVIOIBK7IGa5HEJQz3shjU5Fj8AP-FfXvA7Z3zigmVIOogc2d47GU1ozFNgi18ilU" \
  -o file2.txt
  
  *폴더 Path를 입력할 경우 폴더가 압축된 상태로 다운로드된다.

다운로드 API도 마찬가지로 Parameter 값은 공식 API 가이드 문서에 나와 있다.

Cookie값의 경우 이전 로그인 API에서 반환한 세션 ID를 입력한다. 입력하면 아래와 같이 다운로드 정보가 나타나며, 경로에 있는 파일을 확인해 보면 file2.txt가 있는 것을 확인할 수 있다.

마지막으로 API 사용이 끝났다면, 로그아웃 API를 사용하여 로그아웃을 진행한다.

로그아웃

curl -X POST "http://{서버 주소}//webapi/auth.cgi" \
  -d "api=SYNO.API.Auth" \
  -d "version=3" \
  -d "method=logout" \
  -d "session=FileStation" \
  -H "Cookie: {세션 ID}"

명령어를 실행 후 정상적으로 로그아웃이 되었다면 아래와 같이 나오게 되며, 이전에 진행했던 세션 ID는 더 이상 사용할 수 없게 된다.

공식 가이드 문서를 참고하면 이 외에도 많은 API가 있으니 가이드에 맞게 위 명령어를 수정하면, 쉽게 진행할 수 있다.

참고 :

https://global.download.synology.com/download/Document/Software/DeveloperGuide/Package/FileStation/All/enu/Synology_File_Station_API_Guide.pdf

 

https://velog.io/@mmsori/Synology-Download-API

Synology Download API