Sari la conținut

Gestionează joburile cron

Listează, adaugă, modifică, dezactivează și șterge comenzile programate (joburile cron) ale unui cont de hosting prin API și urmărește ultima rulare.

Ghidul arată cum gestionezi prin API joburile cron ale unui cont de hosting. Un job cron rulează o comandă după un program, în containerul web al unui site, ca utilizator al site-ului.

  • O cheie API cu scope-ul crons:read pentru a lista joburile cron și crons:write pentru a le adăuga, modifica sau șterge (scope-uri).
  • Id-ul contului și id-ul site-ului care rulează comanda. Le găsești cu GET /api/v1/accounts și GET /api/v1/accounts/{account_id}/sites.
  • Un plan care permite joburi cron. Fără el, adăugarea unui job răspunde 403 plan_feature_disabled.
export PLUSPANEL_URL="https://panel.example.com"
export PLUSPANEL_API_KEY="ppk_…"
export ACCOUNT_ID="5a5a5a5a-1111-4222-8333-444455556666"
export SITE_ID="6b6b6b6b-1111-4222-8333-444455556666"

GET /api/v1/accounts/{id}/crons întoarce toate joburile cron ale contului, cu rezultatul ultimei rulări.

curl -fsS "$PLUSPANEL_URL/api/v1/accounts/$ACCOUNT_ID/crons" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY"
{
  "items": [
    {
      "id": "8d8d8d8d-1111-4222-8333-444455556666",
      "account_id": "5a5a5a5a-1111-4222-8333-444455556666",
      "site_id": "6b6b6b6b-1111-4222-8333-444455556666",
      "schedule": "*/15 * * * *",
      "command": "echo hello from cron",
      "enabled": true,
      "source": "user",
      "last_run_at": "2026-11-14T09:45:00Z",
      "last_exit": 0
    }
  ],
  "sync": { "state": "applied" }
}
  • last_run_at și last_exit sunt goale (null) până când jobul a rulat o dată. Un cod de ieșire diferit de 0 înseamnă că a eșuat comanda; ieșirea ei este în cron.log al site-ului.
  • source este user pentru joburile adăugate de tine și migration pentru cele aduse de o migrare cPanel.
  • sync.state arată dacă serverul a aplicat lista: applied, pending sau failed.

POST /api/v1/accounts/{id}/crons adaugă un job. site_id, schedule și command sunt obligatorii; enabled este implicit true.

curl -fsS -X POST "$PLUSPANEL_URL/api/v1/accounts/$ACCOUNT_ID/crons" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"site_id": "'"$SITE_ID"'", "schedule": "*/15 * * * *", "command": "echo hello from cron"}'

Răspunsul este 201, cu noul job în cron și un job_id: serverul aplică schimbarea ca pe un job, deci jobul cron ajunge pe server după o clipă. Păstrează id-ul noului job ca CRON_ID pentru pașii următori.

  • schedule are cinci câmpuri (minut, oră, ziua lunii, luna, ziua săptămânii) sau una dintre valorile @hourly, @daily, @weekly, @monthly, @yearly. @reboot nu este suportat. Orele sunt în UTC.
  • command este text imprimabil, de cel mult 1024 de octeți. O comandă rulează cel mult o oră.
  • Un cont are cel mult 100 de joburi cron.

PATCH /api/v1/crons/{id} schimbă oricare dintre schedule, command, site_id și enabled; membrii pe care îi omiți rămân neschimbați. Dezactivarea păstrează jobul în listă.

curl -fsS -X PATCH "$PLUSPANEL_URL/api/v1/crons/$CRON_ID" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Răspunsul are aceeași formă ca la un job nou: cron și job_id. Ca să trimiți schimbarea doar dacă nimeni altcineva nu a modificat între timp jobul, folosește un antet If-Match.

curl -fsS -X DELETE "$PLUSPANEL_URL/api/v1/crons/$CRON_ID" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY"

Răspunsul este 204, fără corp.

O schimbare se întoarce înainte ca serverul s-o fi aplicat. Ca s-o aștepți, citește job_id cu GET /api/v1/jobs/{id} (scope jobs:read) până când status este final, sau urmărește GET .../crons până când sync.state este applied. O aplicare eșuată apare ca sync.state: "failed".

Status Cod Ce înseamnă
401 invalid_api_key Cheia lipsește, a expirat sau a fost revocată.
403 plan_feature_disabled Planul contului nu permite joburi cron.
403 Cheia nu are scope crons, sau utilizatorul nu poate administra acest cont.
404 Contul sau jobul cron nu există ori nu este vizibil pentru tine.
409 crons_unsupported_agent Agentul serverului nu rulează joburi cron.
409 conflict Contul are deja 100 de joburi cron.
422 validation_failed Programul sau comanda este invalidă, ori site-ul nu aparține contului.

Erorile sunt problem details: decide după code.

Când serverul a aplicat o schimbare, jobul se termină și se trimite un eveniment job.succeeded (job.failed dacă a eșuat); data.object_id este job_id din răspuns. Abonează-te la ele așa cum este descris la webhook-uri.