Output e codici di uscita

La CLI di Octoparse supporta output leggibile dalle persone per l’uso nel terminale e output leggibile dalle macchine per l’automazione. Usa questa pagina quando richiami la CLI di Octoparse da script, agenti, processi CI o altri ambienti di automazione.

Output JSON

Usa --json quando hai bisogno di una singola risposta JSON stabile.

octoparse task list --json
octoparse auth status --json
octoparse local status <taskId> --json

I comandi riusciti restituiscono un contenitore JSON con ok: true e un campo data:

{
  "ok": true,
  "data": {
    "items": [
      { "taskId": "abc123", "taskName": "Example task", "status": "Idle" }
    ],
    "page": 1,
    "pageSize": 20,
    "total": 1
  }
}

I comandi non riusciti restituiscono ok: false con un campo error contenente un codice e un messaggio:

{
  "ok": false,
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "API key is required for this command."
  }
}

La struttura esatta di data dipende dal comando. I codici di errore comuni includono AUTH_REQUIRED, AUTH_INVALID, TASK_INVALID, LINUX_ARM64_UNSUPPORTED, ENGINE_RUN_FAILED e UNSUPPORTED_EXPORT_FORMAT. Esegui octoparse capabilities --json per visualizzare l’elenco completo.

Flussi di eventi JSONL

Usa --jsonl per le estrazioni locali di lunga durata. L’output trasmette un oggetto JSON per riga:

octoparse run <taskId> --jsonl

Un flusso tipico:

{"event":"run.started","taskId":"abc123","timestamp":"2026-01-01T10:00:00.000Z"}
{"event":"row","taskId":"abc123","count":1}
{"event":"captcha","taskId":"abc123","service":"..."}
{"event":"proxy","taskId":"abc123","status":"..."}
{"event":"run.completed","taskId":"abc123","savedRows":42}

Tipi di evento stabili:

Evento	Quando si attiva
`warning`	Avviso di runtime non irreversibile
`billing.warning`	Avviso di saldo basso
`billing.error`	Saldo esaurito
`run.started`	Esecuzione locale avviata
`row`	Una riga è stata salvata
`log`	Riga del log del motore
`captcha`	Richiesta CAPTCHA dal runtime
`proxy`	Richiesta o stato del Proxy
`download.started`	Download del file avviato
`download.succeeded`	Download del file completato
`download.failed`	Download del file non riuscito
`run.paused`	Esecuzione messa in pausa
`run.resumed`	Esecuzione ripresa
`run.stopping`	Interruzione richiesta, esecuzione in fase di chiusura
`run.stopped`	Esecuzione interrotta dall’utente
`run.failed`	Esecuzione non riuscita a causa di un errore

I nomi e i campi degli eventi possono evolversi tra le versioni. Considera ogni riga un oggetto JSON autonomo e gestisci in modo sicuro i campi sconosciuti.

Elementi delle esecuzioni scollegate

Quando esegui con --detach, la CLI scrive i file di avvio nella directory di output:

File	Contenuto
`bootstrap.json`	Metadati e stato iniziale dell’esecuzione
`stdout.log`	Output standard dell’esecuzione
`stderr.log`	Errore standard dell’esecuzione

File degli elementi dell’esecuzione locale, nella directory di esecuzione:

File	Contenuto
`meta.json`	Metadati dell’esecuzione
`control.json`	Stato di controllo dell’esecuzione
`events.jsonl`	Tutti gli eventi JSONL
`logs.jsonl`	Righe del log del motore
`rows.jsonl`	Righe salvate
`downloads.jsonl`	Eventi di download

stdout e stderr

Flusso	Modalità umana	Modalità `--json` / `--jsonl`
stdout	Output del comando	JSON o JSONL strutturato
stderr	Diagnostica, avvisi, errori	Testo normale o contenitore di errori JSON

Questa separazione consente agli strumenti di automazione di reindirizzare l’output richiesto senza mescolarlo ai log diagnostici.

Codici di uscita

Codice di uscita	Significato	Cause tipiche
0	Riuscito	Comando completato come richiesto
1	Operazione non riuscita	Errore di autenticazione, attività non trovata, errore di esportazione
2	Errore del runtime o dell’ambiente	Versione Node.js non corrispondente, Chrome non disponibile, inizializzazione del motore non riuscita, Linux arm64
3	Definizione di attività non supportata	L’attività usa il browser kernel o un flusso di lavoro legacy non supportato dalla CLI v1

Un codice di uscita diverso da zero indica che il comando non è stato completato come previsto.

Consigli per l’automazione

Usa --json per gli script che richiedono un’unica risposta strutturata.
Usa --jsonl per l’esecuzione di attività di lunga durata.
Considera i codici di uscita diversi da zero come passaggi di automazione non riusciti.
Acquisisci stderr separatamente durante il debug.
Non esporre chiavi API o token nei log o nell’output CI.
Esegui octoparse capabilities --json all’inizio del flusso di lavoro di un agente per individuare la superficie dei comandi corrente e il contratto della macchina.

Per agenti AI e ambienti di automazione, preferisci --json o --jsonl all’output leggibile dalle persone. Inizia con octoparse capabilities --json per ottenere il contratto completo della macchina.

PANORAMICA

PER INIZIARE

CREARE ATTIVITÀ

ATTIVITÀ ED ESECUZIONI

DATI

AUTOMAZIONE

RIFERIMENTO

Output JSON

Flussi di eventi JSONL

Elementi delle esecuzioni scollegate

stdout e stderr

Codici di uscita

Consigli per l’automazione

​Output JSON

​Flussi di eventi JSONL

​Elementi delle esecuzioni scollegate

​stdout e stderr

​Codici di uscita

​Consigli per l’automazione

Output JSON

Flussi di eventi JSONL

Elementi delle esecuzioni scollegate

stdout e stderr

Codici di uscita

Consigli per l’automazione