n8n에서 시놀로지 오피스 API 사용하기 2부 포스팅입니다. 1부에서는 시놀로지 오피스 API의 기본 개념과 장점을 살펴보았습니다. 이번 포스팅은 시놀로지 오피스 API 구동 방법과 n8n에서 연동하여 스프레드시트를 활용하는 방법을 알아보려 합니다.
이전 포스팅 : n8n 자동화 입문, 초보자를 위한 시놀로지 오피스 API 1부 개요와 활용 장점
시놀로지 오피스 API 활용을 위한 준비물
API 이용을 위해서는 다음의 세가지가 사전에 설치되거나, 신청이 되어 있어야 합니다.
Container manager (구 docker) 설치
API 서버 구동을 위해 Docker 상에서 이미지가 실행이 되고 있어야 합니다. 다음 단계의 실행 스텝을 따라하시면 됩니다.
Synology Drive 설치 (synology 오피스)
순서상 가장 먼저, Synology Drive 가 설치 되어 있어야, 시놀로지 오피스를 사용할 수 있습니다.
Synology Account
NAS 를 구매한 분들중 API 이용을 위해서는 아래의 시놀로지 API 홈페이지에서 설문을 작성하고 이용해야 한다고 합니다. 설문 작성이 필수 인지는 잘 모르겠지만, 일단 작성은 합니다.
관련 홈페이지 : https://office-suite-api.synology.com
n8n에서 시놀로지 스프레드시트 API 사용하기
지금부터 설명하는 API 사용 방법은 기본적으로 아래의 유튜브 영상을 참고했습니다.
본 포스팅으로 헷갈리는 분들은 다음의 영상을 함께 참고하시면 도움이 됩니다.
1. 시놀로지 오피스 API 사용 스프레드시트 중심)
스텝1. NAS 도커로 API 서버 설치하기
터미널(SSH) 사용, 명령어 입력이 편한
다음 두 가지 명령을 순차적으로 실행하여 도커를 이용하여 API 서버를 설치하고 구동합니다.
- API 이미지를 다운 받는 명령
docker pull synology/spreadsheet-api:3.4.12. 서버 구동 :
- Auth_Secret 은 임의의 키 값을 반드시 넣어서 활용하세요. (“secret-key–for-auth-token’ 은 예시입니다.)
- “synology/spreadssheet-api:3.4.1 은 위에서 다운 받은 이미지와 이름이 반드시 동일해야 합니다.
docker run -e AUTH_SECRET=secret-key-for-auth-token -p '3000:3000' synology/spreadsheet-api:3.4.1nas GUI 활용이 편한 분
1)컨테이너 메니져 ► 레지스트리 ► synology/spreadsheet-api 이미지 찾기 ► 최신 버전 다운 시작
2)다운 완료후 이미지 더블 클릭 ► 자동재시작 활성화 ► 환경변수추가 ► AUTH_SECRET, 항목 추가 ► 완료 ►API 서버 구동 확인
스텝2. API 토큰 발급 및 관리
여기서 발급 받은 토큰을 활용하여 이후 모든 API 를 구동합니다. 따라서 발급받은 토큰은 별도로 저장할 필요가 있습니다.
또한 이 토큰 값은 28일에 만료가 됩니다. 즉 다시 발급을 받아야 한다는 점을 기억해야 합니다.
터미널(SSH) 사용, 명령어 입력이 편한 분
curl -X POST "http://{server_url}/spreadsheets/authorize" \
-H "accept: application/json" \
-H "content-type: application/json" \
-d '{"username":"username","password":"password","host":"my-nas:5000","protocol":"http"}'초록색 글자는 사용자의 환경에 따라 변경하여 사용합니다. 즉 자신의 NAS IP:5000 , 유저ID, 패드워드 등을 이용합니다. https 를 이용할 경우, 5001 을 이용합니다.
n8n 노드활용 발급 받기
- HTTP request 노드를 사용합니다.
- Method 는 “Post” 를 선택합니다.
- n8n 노드는 명령어 입력과 거의 유사합니다. 주소란에 API 서버 주소를 입력합니다. (서버 주소에서 포트는 3000 입니다.)
- 명령어에 “H” 로 되어 있는 값들은 send headers 를 활성화하고 각 개별 항목으로 입력합니다.
- 명령어에 “d” 로 되어 있는 값은 send Body (활성화) ► Body Content Type : JSON, ► Specific Body : Using JSON 선택을 합니다.
- 아래 빈칸에는 Json 형식으로 다음을 입력합니다.
{
"username": "username",
"password": "계정비밀번호",
"host": "NAS IP:5000",
"protocol": "http"
}
- execute step 을 눌러 token 값을 화인 합니다. (별도로 저장합니다.)
스텝3. 실제 API 활용, n8n HTTP Request 노드로 API 연결하기
API 를 이용해서 여러가지를 할 수 있지만, 간단한 예로 스프레드시트를 새롭게 만드는 것을 예를 들어 보겠습니다.
모든 다른 명령은 동일한 패턴입니다. 입력하는 변수만 조금씩 변동될 뿐입니다.
- 홈페이지 접속 원하는 기능 탐색 : https://office-suite-api.synology.com/Synology-Spreadsheet/v3-4-1#post-/spreadsheets/create
- n8n 에서는 request node 활용
- 원하는 기능 구현을 위한 method 확인 : 시트 Create 는 Post
- 앞서 token 발행과 동일, 단
authorization값으로 이미 발행된 token 값 적용합니다. - 반드시 Bearer {token} 형태로 입력 (띄어쓰기 조심) : Bearer skdkqidneidi12dis ~
curl -X POST "https://{server_url}/spreadsheets/create" \
-H "accept: application/json" \
-H "authorization:"Bearer 토큰입력" \
-H "content-type: application/json" \
-d '{"name":"Spreadsheet Name"}'스텝4. 토큰 자동 갱신 설정으로 안정적 연동하기
앞서 토큰은 28일마다 갱신을 해야 한다고 하였습니다.
따라서, 28일마다 앞의 토큰 발행 프로세스를 반복해야 합니다. 하지만 n8n 에서 schedule 노드와 dB를 잘 활용하면, 자동으로 28일마다 토큰을 자동으로 갱신할 수 있습니다.
저는 Redis 라는 DB 를 활용하였습니다. 스프레드시트 자체를 DB 로 활용해도 됩니다.
20th_day_schedule: 28일마다 실행(토큰 롤오버)
Get_synology_token: /spreadsheets/authorize로 JWT 발급
token_redis (SET): token과 만료 시간 저장(TTL=28일 권장)
token_redis1 (GET): 사용 시 토큰 조회
get_value: 실제 API 엔드포인트 호출(헤더 Authorization: Bearer <token>
2. API 연동 활용 사례
지금까지 알아본 API 는 n8n 과 함께 사용되며 다양한 조합을 구성해 볼 수 있습니다. 다음은 n8n 과 연동하여 스프레드시트를 활용할 수 있는 간단한 예시입니다.
반복 문서 자동화: 양식 템플릿을 복제 후 날짜/고객명만 채워 저장. 월 최대 30~60분 단축.
데이터 실시간 업데이트: 웹훅 → n8n → 시트 Append로 1~2초 내 반영, 대시보드와 즉시 연동.
AI 에이전트 결합: 요약/분류 결과를 시트에 기록하고, 조건부 규칙으로 담당자에게 알림 전송.
n8n에서 시놀로지 오피스 API 사용하기 포스팅을 마치며
시놀로지 오피스 API를 n8n과 연동하면 단순한 문서 관리 도구를 넘어 자동화 플랫폼으로 활용할 수 있습니다. 처음에는 다소 낯설지만, 단계별로 차근차근 진행하면 누구나 손쉽게 설정할 수 있습니다.