Cloud Scheduler로 Cloud Run 작업 예약: 재시도 대비

Cloud Run 작업(job)을 스케줄에 따라 실행하려면 Cloud Scheduler 트리거를 추가하세요. 작업의 Triggers 탭에서 Add Scheduler Trigger를 선택하고 unix-cron 형식의 빈도와 시간대를 지정하거나, 작업의 :run URL로 POST하는 Cloud Scheduler HTTP 작업을 만들면 됩니다. 작업은 하나 이상의 태스크로 이뤄지며, 실패한 태스크는 기본적으로 최대 3번 다시 시작됩니다. 그러므로 유료 API를 호출하는 태스크는 그 호출의 키를 날짜로 만들어야 합니다. 그러면 태스크가 다시 시작될 때마다 다시 결제하는 대신 같은 요청을 재전송합니다.

Google Cloud 관련 내용은 스케줄에 따라 작업 실행하기를 비롯해 출처에 나열한 다른 Google 문서에서, Sume 관련 내용은 Format 호출하기 (영문), 실행과 결과 (영문), 오류와 비용 (영문)에서 가져왔습니다. 모두 2026-09-28에 확인했습니다. Sume에는 Google Cloud 전용 연동이 없으며, 태스크가 일반 HTTPS 호출을 한 번 보냅니다. 같은 패턴의 AWS 버전은 Lambda 함수를 스케줄에 따라 실행하는 방법에서 다룹니다.

Cloud Scheduler 트리거는 어떻게 만드나요?

먼저 Cloud Scheduler API를 사용 설정하세요(gcloud services enable cloudscheduler.googleapis.com). Cloud Scheduler Admin 역할이나 cloudscheduler.jobs.create가 포함된 커스텀 역할이 필요하고, gcloud CLI로 작업을 실행하려면 Cloud Run Invoker 역할도 필요합니다. 콘솔에서 작업을 열고 Triggers 탭을 클릭한 다음 Add Scheduler Trigger를 클릭하세요. 입력할 항목은 다음과 같습니다.

• 이름과 리전: Scheduler 작업의 리전은 Cloud Run 작업의 리전과 같지 않아도 됩니다.
• unix-cron 형식의 빈도(Frequency, 예: 0 12 * * *)와 시간대(Timezone).
• 작업을 호출할 권한이 있는 서비스 계정.

gcloud scheduler jobs create http daily-recap-trigger \
  --location=us-central1 \
  --schedule="0 6 * * *" \
  --time-zone="America/New_York" \
  --uri="https://run.googleapis.com/v2/projects/PROJECT_ID/locations/us-central1/jobs/daily-recap:run" \
  --http-method=POST \
  --oauth-service-account-email=PROJECT_NUMBER-compute@developer.gserviceaccount.com

예약된 작업은 왜 API를 두 번 이상 호출할 수 있나요?

다시 시작된 태스크는 POST를 포함해 코드를 처음부터 다시 실행하기 때문입니다. 0이 아닌 코드로 종료한 컨테이너는 실패한 것이며, Cloud Run은 작업의 최대 재시도 횟수까지 태스크를 다시 시작합니다. 재시도가 켜져 있으면 태스크 타임아웃은 시도마다 적용되며, 제시간에 끝나지 않은 시도는 중지됩니다. 설정하면 Cloud Scheduler도 자체 호출을 재시도할 수 있고, 사람이 콘솔이나 gcloud CLI에서 작업을 직접 실행할 수도 있습니다.

태스크는 유료 API에 무엇을 보내야 하나요?

UTC 날짜로 키를 만든 생성 요청 하나이며, 본문도 그날에는 고정해야 합니다. 태스크가 다시 시작되면 Sume는 같은 키와 본문에 원래 영수증과 idempotency_hit: true를 담아 200으로 응답하므로, 두 번째 실행은 시작되지 않습니다. 나머지 재전송 사례는 AI 영상 API 멱등성 키에서 다루며, Sume Format 실행 실패에서 설명하듯 failed로 끝난 실행에는 새 키가 필요합니다. 키를 CLOUD_RUN_TASK_ATTEMPT로 만들지 마세요. 이 카운터는 0에서 시작해 재시도할 때마다 올라가므로, 다시 시작할 때마다 새 유료 실행이 됩니다. 또 트리거는 UTC 자정에서 충분히 떨어진 시각으로 예약하세요. 그래야 다시 시작된 태스크가 다음 날의 날짜를 계산하는 일이 없습니다.

API 키는 Google이 API 키 보관에 권장하는 Secret Manager에 저장하고, 작업의 서비스 ID에 Secret Manager Secret Accessor 역할을 부여한 뒤, gcloud run jobs update daily-recap --set-secrets SUME_API_KEY=sume-api-key:1로 키를 노출하세요. Google은 환경 변수로 노출할 때 버전을 고정하라고 권장합니다. 환경 변수는 인스턴스가 시작될 때 해석됩니다. urlopen은 오류 상태에서 HTTPError를 일으키며, 이 오류에도 상태 code와 본문이 그대로 담겨 있습니다. 그리고 종료 코드가 Cloud Run에 태스크가 실패했음을 알립니다.

import datetime, json, os, sys, urllib.error, urllib.request

day = datetime.datetime.now(datetime.timezone.utc).date().isoformat()
body = {
    "input": {"day": day},  # fixed for the day: same key, same body
    "communication": {"webhook_url": "https://example.com/hooks/sume"},
}
req = urllib.request.Request(
    "https://api.sume.com/v1/formats/acme/daily-recap/runs",
    data=json.dumps(body).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['SUME_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": f"daily-recap-{day}",  # unchanged on every restart
    },
    method="POST",
)
try:
    with urllib.request.urlopen(req, timeout=30) as resp:
        run = json.load(resp)["data"]  # 202: new run, 200: replay
except urllib.error.HTTPError as err:
    print(err.code, err.read().decode())  # Sume's JSON error
    sys.exit(1)  # non-zero: the task failed and may restart
print(run["id"], run["idempotency_hit"])

태스크가 영상이 완성될 때까지 기다려야 하나요?

아닙니다. 롱폼 영상은 만드는 데 15분에서 30분이 걸려 기본 태스크 타임아웃인 10분보다 길며, 시간이 다 된 시도는 중지됩니다. 기다리기를 멈춰도 실행이나 그 지출은 절대 멈추지 않습니다. 제출하고, 실행 ID를 출력하고, 0으로 종료하세요. 실행이 완료되거나 실패하면 Sume가 서명된 format.run.terminal 영수증 하나를 communication.webhook_url로 POST하므로, 여러분이 운영하는 공개 HTTPS 엔드포인트라면 어디서든 결과를 받을 수 있습니다. 받는 쪽은 Sume 영상 실행용 서명된 웹훅에서 보여 줍니다. 폴링을 택한다면, 실행은 생성 후 최대 90분 안에 failed로 확정되므로 태스크 타임아웃을 그보다 길게 잡으면 실행 전체를 기다릴 수 있습니다.