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.
De ce ai nevoie
Secțiune intitulată „De ce ai nevoie”- O cheie API cu scope-ul
crons:readpentru a lista joburile cron șicrons:writepentru 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șiGET /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"
1. Listează joburile cron
Secțiune intitulată „1. Listează joburile cron”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șilast_exitsunt goale (null) până când jobul a rulat o dată. Un cod de ieșire diferit de0înseamnă că a eșuat comanda; ieșirea ei este încron.logal site-ului.sourceesteuserpentru joburile adăugate de tine șimigrationpentru cele aduse de o migrare cPanel.sync.statearată dacă serverul a aplicat lista:applied,pendingsaufailed.
2. Adaugă un job cron
Secțiune intitulată „2. Adaugă un job cron”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.
scheduleare cinci câmpuri (minut, oră, ziua lunii, luna, ziua săptămânii) sau una dintre valorile@hourly,@daily,@weekly,@monthly,@yearly.@rebootnu este suportat. Orele sunt în UTC.commandeste 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.
3. Modifică sau dezactivează un job cron
Secțiune intitulată „3. Modifică sau dezactivează un job 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.
4. Șterge un job cron
Secțiune intitulată „4. Șterge un job cron”curl -fsS -X DELETE "$PLUSPANEL_URL/api/v1/crons/$CRON_ID" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY"
Răspunsul este 204, fără corp.
Urmărește schimbarea pe server
Secțiune intitulată „Urmărește schimbarea pe server”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.
Evenimente
Secțiune intitulată „Evenimente”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.
Legături utile
Secțiune intitulată „Legături utile”- Site-uri: joburile cron în panou.
- Referința API: fiecare operație
crons, cu câmpurile ei. - Convențiile API: erori, idempotență și ETag-uri.
- Autentificare și chei API: scope-uri și folosirea cheilor.