Scheduler

Scheduler는 한 Space에 등록하는 반복 실행 예약입니다. Script 하나와 도는 시각을 묶어 두면, 그 시각이 될 때마다 서버가 그 Script를 실행합니다. 예를 들어 옷가게 쇼핑몰에서 재고가 0인 상품을 찾아 거래처 발주 창구를 호출하는 Script를 매일 한 번 돌리려면, 그 Script를 가리키는 Scheduler를 하나 만들어 둡니다.

Scheduler는 CMA에서 관리하는 Space 하위 리소스이며, 경로는 /spaces/{spaceId}/schedulers를 기준으로 합니다. 발행(publish) 개념이 없고 sys.version도 없습니다. 생성하면 곧바로 예약에 들어가며, 수정에 버전 헤더가 필요하지 않습니다. 대신 두 가지가 다른 리소스와 다릅니다. 실행할 Script는 생성 후 바꿀 수 없고, 만들거나 고치려면 Space 설정 권한 외에 그 Script의 실행 권한이 따로 필요합니다. 실행 결과는 SchedulerLog로 남으며, 성공한 실행은 1시간, 실패한 실행은 3일 뒤에 사라집니다.

리소스 구조

다음은 Scheduler를 생성했을 때의 응답입니다. sys에 식별자와 참조가, 본문에 이름·도는 시각·켜짐 여부가 담깁니다.

{
  "sys": {
    "id": "7kQm2ZbTn4Rc9WvXpL3dHsY6fJ",
    "type": "Scheduler",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "script": { "sys": { "id": "3trmXRMKq7bd0Prbef1NcZ", "type": "Refer", "targetType": "Script" } },
    "createdBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-08-26T01:20:07.442Z",
    "updatedBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-08-26T01:20:07.442Z"
  },
  "name": "재고 발주",
  "cronExpression": "0 0 * * *",
  "activated": true
}

주요 키:

• sys.id: Scheduler의 고유 식별자입니다. 단일 조회·수정·삭제 경로의 {schedulerId}에 들어갑니다.
• sys.script: 이 예약이 실행할 Script입니다. 생성 시에만 정할 수 있고 이후 바꿀 수 없습니다. 다른 Script를 돌리려면 새 Scheduler를 만듭니다.
• name: 콘솔에 보이는 라벨입니다. 실행에는 쓰이지 않습니다.
• cronExpression: 도는 시각입니다. 다섯 칸(분·시·일·월·요일)이며 UTC로 해석됩니다. 아래 도는 시각 적기 참조.
• activated: 켜짐 여부입니다. false면 저장은 남고 실행만 하지 않습니다.

sys.version이 없습니다. 수정 요청에 X-Weegloo-Version 헤더를 보내지 않습니다.

시스템 속성 (sys)

space·script·createdBy·updatedBy는 Refer 모양({ "sys": { "id", "type": "Refer", "targetType" } })으로 들어갑니다.

본문 속성:

도는 시각 적기

다섯 칸을 왼쪽부터 분·시·일·월·요일 순으로 씁니다. 초 단위 칸은 없습니다.

*(전부), ,(목록), -(범위), /(간격)를 쓸 수 있고, 요일은 숫자(07, 0과 7은 일요일) 또는 이름(SUNSAT)으로 적습니다.

모든 값은 UTC로 해석됩니다. 지역 시간과의 차이를 계산해 넣어야 하며, 날짜나 요일을 지정한 시각은 그 차이 때문에 실제로 실행되는 날이 달라질 수 있습니다.

한 번도 발화하지 않는 값은 저장되지 않습니다. 0 0 30 2 *(2월 30일)처럼 형식은 맞아도 오지 않는 날을 가리키면 거부됩니다.

상태와 제약

동작과 권한에 대한 규칙:

• 두 가지 권한이 함께 필요합니다. 역할(SpaceRole)의 settings에 SETTING_SCHEDULER가 있어야 하고, 그와 별개로 대상 Script에 대한 Execute 권한이 있어야 합니다. 생성뿐 아니라 수정·부분 수정에서도 확인합니다. 도는 시각을 바꾸는 것은 그 Script를 언제 실행할지 정하는 일이고, 꺼진 것을 켜는 것은 실행을 시작하는 일이기 때문입니다. 둘 중 하나라도 없으면 요청이 거부됩니다.
• 실행은 sys.createdBy의 권한으로 일어납니다. Script 안의 :self 필터도 그 사용자로 해석됩니다. 수정자가 달라도 실행 주체는 바뀌지 않습니다.
• 작성자가 실행 권한을 잃으면 자동으로 꺼집니다. 다음 실행 시각에 서버가 확인해 실행하지 않고 activated를 false로 내립니다. 권한이 복구되어도 자동으로 켜지지 않습니다.
• 개수에 한도가 있습니다. Organization 하나가 가질 수 있는 Scheduler 개수가 요금제별로 정해져 있습니다(Free 1개, Basic 5개, Pro 30개, Enterprise 무제한). 그 한도를 넘기면 생성이 거부됩니다.
• 실행 횟수는 Script와 공유합니다. 한 번 돌 때마다 요금제의 Script 실행 횟수를 하나 씁니다. Scheduler 전용 실행 한도는 없습니다. 그 한도를 넘겨 Organization의 Script 실행이 정지되면, 이후 실행 시각이 돌아오는 Scheduler는 실행되지 않고 activated가 false로 바뀝니다. 이때는 SchedulerLog가 하나 남고 sys.error에 사유가 담깁니다. 그 Scheduler는 꺼진 뒤 다시 예약되지 않습니다.
• 놓친 실행은 보충하지 않습니다. 실행되지 못한 회차가 있어도 나중에 몰아서 돌지 않고 다음 시각부터 다시 돕니다.
• 사용 중인 Script는 삭제되지 않습니다. 어떤 Scheduler가 참조하는 Script를 지우려 하면 그 삭제가 거부됩니다(Script의 오류 참조).
• 발행이 없습니다. 상태값이나 발행 단계 없이 생성하면 바로 예약에 들어가고, 삭제도 사전 단계 없이 바로 됩니다.

SchedulerLog

Scheduler가 한 번 돌 때마다 실행 기록이 하나 남습니다. 조회 전용이며 생성·수정·삭제 엔드포인트가 없습니다. 경로는 /spaces/{spaceId}/schedulers/{schedulerId}/logs입니다.

{
  "sys": {
    "id": "5nRt8YcVm2Qb7WxZpK4dGhJ9sL",
    "type": "SchedulerLog",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "requestId": "3trmXRM8dNvQ2LbYpK7fHsJ3gWc4Rt",
    "success": true,
    "createdBy": { "sys": { "id": "7kQm2ZbTn4Rc9WvXpL3dHsY6fJ", "type": "Refer", "targetType": "Scheduler" } },
    "createdAt": "2026-09-03T00:00:02.503Z",
    "updatedBy": { "sys": { "id": "7kQm2ZbTn4Rc9WvXpL3dHsY6fJ", "type": "Refer", "targetType": "Scheduler" } },
    "updatedAt": "2026-09-03T00:00:02.503Z"
  }
}

모든 값이 sys 안에 있고 본문 속성은 없습니다. 값이 없는 키는 응답에서 빠집니다(위 예시에는 error가 없습니다).

scheduler 필드가 없습니다. 어느 Scheduler가 남긴 기록인지는 sys.createdBy가 가리키며, 그 targetType은 "Scheduler"입니다. sys.updatedBy도 같은 Scheduler입니다.

startedAt·endedAt·result와 소요 시간 필드도 없습니다. 한 회차가 얼마나 걸렸는지와 Script가 돌려준 값은 같은 requestId를 가진 ScriptLog에 있습니다(sys.durationMs·sys.value·sys.statusCode). 필드 구성은 Script 리소스와 엔드포인트에서 다룹니다.

한 회차는 로그를 둘 남깁니다. 하나는 이 얇은 SchedulerLog이고, 다른 하나는 그 실행 자체를 담은 ScriptLog입니다(ScriptLog의 sys.trigger가 이 Scheduler를 가리킵니다). 둘은 같은 requestId로 묶입니다.

기록은 실행이 끝난 뒤에 한 번 쓰이고 바뀌지 않습니다. 성공한 실행은 1시간, 실패한 실행은 3일 뒤에 사라집니다. 만료 시각을 담은 필드는 응답에 없고, 때가 되면 기록이 사라집니다. 그보다 오래 남겨야 하는 값은 Script 안에서 Content로 저장하세요.

오류

Scheduler를 다룰 때 만나는 코드입니다. 모든 리소스에 공통인 코드는 공통 오류를 참조하세요.

API

아래 모든 엔드포인트의 기준 URL은 https://cma.weegloo.com/v1이며, Authorization 헤더에 CMA를 인증하는 Bearer 토큰이 필요합니다. Scheduler에는 sys.version이 없으므로 수정에 X-Weegloo-Version 헤더를 보내지 않습니다.

관련 문서

• Script: Scheduler가 실행하는 리소스. 정의 구조와 statement 종류를 다룹니다.
• Webhook: 시각이 아니라 이벤트로 Script를 실행하는 리소스.
• SpaceRole: SETTING_SCHEDULER 설정 권한과 Script의 Execute 권한을 담는 역할.
• Scheduler 개념: 무엇에 쓰는 기능인지와 콘솔에서 다루는 방법.