# Automatizza con la CLI di FlashData

Convalida una richiesta, eseguila da uno script e legge le ricevute dei risultati e degli errori separati.

Riferimento canonico: https://flashdata.dev/it/docs/guides/cli-automation
Recensito: 2026-11-04 da FlashData

<a id="profiles"></a>

## 1. Selezionare il profilo esistente

Utilizzare il CLI installato, Bash e jq. Su Windows, eseguire gli esempi di shell in Git Bash. Questo passaggio utilizza un profilo di ricerca autenticato; impostare FLASHDATA_STATE_DIR nella directory assoluta in cui il profilo viene memorizzato.

Utilizzare la stessa directory utente e stato OS su ogni comando. FLASHDATA_API_KEY sovrascrive la chiave salvata; lasciala disattivare per usare il profilo. Lo CLI non carica i file .env.

### Controllare l'accesso salvato

```bash
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
flashdata auth status --profile research --state-dir "$FLASHDATA_STATE_DIR" --json
```

- [Collegare il primo CLI](https://flashdata.dev/it/docs/guides/flashdata-cli/reference.md#existing-key)

<a id="profile-paths"></a>

### Località di stato di default

Usa il tuo --state-dir originale se hai scelto una posizione personalizzata. auth status dovrebbe segnalare data.accessVerified: true. Per una distribuzione incustodita, importare la chiave del proprietario tramite stdin dal suo negozio segreto.

| OS | Directory |
| --- | --- |
| Windows | %APPDATA%/FlashData |
| macOS | ~/Library/Application Support/FlashData |
| Linux | $XDG_STATE_HOME/flashdata o ~/.local/state/flashdata |

- [Provvisione delle credenziali del server](https://flashdata.dev/it/docs/guides/production-deployment/reference.md#secrets)

<a id="check"></a>

## 2. Convalida la richiesta e il prezzo

Salvare request.json, quindi eseguire i controlli gratuiti nella stessa directory. Il filtro stampa true solo quando è disponibile un prezzo di origine e l'equilibrio copre una query. Fermati su un'uscita non zero. Un controllo dei prezzi non riserva crediti.

### request.json

```json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}
```

### Bash + jq · nessuna presentazione a pagamento

```bash
set -euo pipefail
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
flashdata account balance --profile research --state-dir "$FLASHDATA_STATE_DIR" \
  --json --non-interactive > balance.json
flashdata query --input request.json --dry-run --run-id cli-research-001 \
  --profile research --state-dir "$FLASHDATA_STATE_DIR" \
  --json --non-interactive > preflight.json
jq -e --slurpfile balance balance.json '
  .ok and .data.dryRun and .data.estimateAvailable
  and ($balance[0].ok == true)
  and any(.data.estimate.prices[]?;
    .source == "google_search" and .available == true
    and (.estimatedCredits | type == "number")
    and ($balance[0].data.availableCredits | type == "number")
    and .estimatedCredits <= $balance[0].data.availableCredits)
' preflight.json
```


<a id="json"></a>

## 3. Correre e leggere la ricevuta

Dopo il passaggio dei controlli, salvare run-search.sh ed eseguire bash run-search.sh. La prima esecuzione di successo presenta una ricerca. Ogni tentativo salva i suoi file in una nuova directory cli-run; la versione stabile ID consente alla CLI di riutilizzare un precedente successo per lo stesso account, profilo e directory di stato.

### run-search.sh

```bash
#!/usr/bin/env bash
set -euo pipefail
umask 077
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
dir=$(mktemp -d "cli-run.XXXXXX")
if ! flashdata query --input request.json --run-id cli-research-001 \
  --profile research --state-dir "$FLASHDATA_STATE_DIR" \
  --output "$dir/result.json" --timeout 2m --json --non-interactive \
  > "$dir/receipt.json" 2> "$dir/error.json"; then
  cat "$dir/error.json" >&2
  printf 'Inspect saved run cli-research-001; receipts: %s\n' "$dir" >&2
  exit 1
fi
jq -e '.schemaVersion == 1 and .ok == true' "$dir/receipt.json" >/dev/null
jq -e '.status == "done" and .source == "google_search"' "$dir/result.json" >/dev/null
jq -r '.results[]?.organic[]? | [.title, .link] | @tsv' "$dir/result.json"
jq '{runId, cached, usage}' "$dir/receipt.json"
printf 'Files: %s\n' "$dir"
```


<a id="receipt-fields"></a>

### Sapere quale file leggere

La busta CLI e la risposta sorgente sono documenti JSON diversi. Senza --output, la risposta sorgente è in dati. Questo esempio utilizza --output, quindi leggere i campi sorgente dal salvato result.json.

| File | Leggi tutto |
| --- | --- |
| receipt.json | ok, runId, cache, utilizzo e percorso di uscita. Una ricevuta cache riporta l'uso originale, non una nuova carica. |
| result.json | fonte, stato, risultati e utilizzo. Per la ricerca Google, leggere results[].organic[]. Un array vuoto può essere un risultato di ricerca valido. |
| error.json | Su uscita non zero, ispezionare error.code, error.httpStatus, error.retryAfter e qualsiasi run/job IDs. |

#### receipt.json · estratto illustrativo

```json
{
  "schemaVersion": 1,
  "ok": true,
  "runId": "cli-research-001",
  "cached": false,
  "data": {
    "output": "cli-run.EXAMPLE/result.json"
  },
  "usage": {
    "credits": 0.02
  }
}
```


<a id="recover"></a>

## Recuperare senza un'altra ricerca

Ispezionare la corsa salvata prima di riprovare. Con l'accesso all'account originale, esportare una corsa di successo in un nome di file che non esiste ancora. Rivendicare gli interruttori dal conto di prova al proprietario; mantenere i risultati di prova precedentemente esportati e utilizzare il nuovo IDs per le nuove attività del proprietario. Viene respinta una richiesta modificata sotto lo stesso run ID; utilizzare un nuovo ID solo per un nuovo compito intenzionale.

### Ispezione, quindi esportare un successo salvato

```bash
flashdata runs show cli-research-001 --profile research \
  --state-dir "$FLASHDATA_STATE_DIR" --json
flashdata runs show cli-research-001 --result --output recovered.json \
  --profile research --state-dir "$FLASHDATA_STATE_DIR" --json
```

- [Posti di lavoro accettati, errori e incerte presentazioni](https://flashdata.dev/it/docs/guides/agent-recovery/reference.md)

<a id="recurring"></a>

## Aggiungi pianificazione quando lo script funziona

Utilizzare --recurring con accesso proprietario installato, uno stabile ID per evento programmato e stato persistente. una prova non può funzionare il lavoro ricorrente. Il tuo ospite possiede il programma; la bandiera controlla solo l'accesso. Utilizzare il corridore completo di ripetizione per la gestione e riavviamenti programmati.

- [Eseguire attività di agente ricorrenti](https://flashdata.dev/it/docs/guides/recurring-tasks/reference.md)
- [Distribuire su un server o un contenitore](https://flashdata.dev/it/docs/guides/production-deployment/reference.md)

<a id="storage"></a>

## Facoltativo: archiviazione scarica privata

Per il download di youtube --storage-config storage.json, salvare solo questo oggetto di archiviazione come storage.json e sostituire i segnaposto localmente. Il file deve essere privato e di proprietà dell'utente in esecuzione. Utilizzare il comando di autorizzazione corrispondente prima di eseguire un download.

### storage.json · S3

```json
{
  "storage_type": "s3",
  "storage_url": "YOUR_BUCKET",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "us-east-1"
}
```

### Linux / macOS

#### Limitare l'accesso ai file

```bash
chmod 600 storage.json
```


### Windows PowerShell

#### Limitare l'accesso ai file

```powershell
$storagePath = (Resolve-Path -LiteralPath './storage.json').Path
$storageUser = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
$storageAcl = [System.Security.AccessControl.FileSecurity]::new()
$storageAcl.SetOwner($storageUser)
$storageAcl.SetAccessRuleProtection($true, $false)
$storageAcl.AddAccessRule([System.Security.AccessControl.FileSystemAccessRule]::new($storageUser, 'FullControl', 'Allow'))
Set-Acl -LiteralPath $storagePath -AclObject $storageAcl
```


- [Fornitori di stoccaggio e risultati di consegna](https://flashdata.dev/it/docs/guides/youtube-download-guide/reference.md#storage)
- [Scarica il comando](https://flashdata.dev/it/docs/guides/flashdata-cli/reference.md#commands)

<a id="next"></a>

## Guide correlate

- [Avvio rapido CLI](https://flashdata.dev/it/docs/guides/flashdata-cli/reference.md)
- [Richiedi la cronologia](https://flashdata.dev/app/jobs)
- [Deposito e revoca Credenziali](https://flashdata.dev/it/docs/guides/production-deployment/reference.md#maintain)
