stable · guide · 0.1.0

建立排程與驗證 invocation

註冊 operation

Project Credential 需要 schedules:write scope。先以 POST /scheduled-operations 註冊 HTTPS endpoint、operation name、簽章 secret 與最大嘗試次數；secret 至少 32 個字元，之後不會由 API 回傳。

接著以 POST /invocation-schedules 建立一次性或 recurring schedule。同一排程重試時沿用相同 Idempotency-Key 與完全相同的 body。

立即 background work

若工作不需等待指定時間，建立一次性 schedule，將 run_at 設為目前或過去時間並省略 interval_seconds。Durable invocation 會立即符合 worker claim 條件，但不是同步執行，也沒有固定開始延遲保證。API 回應後使用 invocation_id 查詢狀態；不要維持 HTTP request 等待業務工作完成。

未來一次執行使用未來的 run_at；固定間隔執行才加入 interval_seconds。

Shell example

: "${MINICENTER_PROJECT_CREDENTIAL:?set the sandbox Project Credential}"
: "${MINICENTER_SCHEDULED_OPERATION_ID:?register an operation first}"
: "${MINICENTER_URL:=https://sandbox.minicenter.otus.tw}"
curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer ${MINICENTER_PROJECT_CREDENTIAL}" \
  --header "Idempotency-Key: docs-daily-report-1" \
  --header "Content-Type: application/json" \
  --data "{\"registered_operation_id\":\"${MINICENTER_SCHEDULED_OPERATION_ID}\",\"arguments\":{\"report_id\":\"weekly-sales\"},\"run_at\":\"2026-08-01T01:00:00Z\",\"interval_seconds\":86400}" \
  "${MINICENTER_URL}/api/v1/invocation-schedules"

驗證與去重

MiniCenter 送出的 body 遵循 Scheduled invocation Event reference。先確認：

X-MiniCenter-Timestamp 在五分鐘 replay window 內。
X-MiniCenter-Invocation-ID 等於 body 的 id。
X-MiniCenter-Signature 等於 sha256=HMAC_SHA256(secret, timestamp + "." + invocation_id + "." + raw_body)。
在同一資料庫交易中以 invocation ID 建立唯一 receipt，再執行業務效果。

重複 delivery 應回應成功但不重複業務效果。