# Async & richieste di batch

Eseguire il lavoro di sfondo per un'applicazione o un agente, riprendere dal suo lavoro salvato ID e raccogliere ogni risultato batch.

Riferimento canonico: https://flashdata.dev/it/docs/guides/async-batch
Recensito: 2026-11-05 da FlashData

<a id="choose"></a>

## Continua a lavorare dopo la tua cessazione di processo

Utilizzare un lavoro di sfondo per un'attività di applicazione in coda o un flusso di lavoro agente che può finish in seguito. Questo passaggio esegue una ricerca Google, salva la sua ricevuta e riprende da quella ricevuta in un altro processo.

| Continua | Oggetto |
| --- | --- |
| Ricevuta dell’operazione | submission.json — mantenere il lavoro accettato ID con il compito di applicazione e l'ingresso originale. |
| Risposta salvata | result.json — convalidare la sua fonte e i risultati prima di importarlo. |
| Risultati Batch | batch-results/outcomes.json — una voce per input, con il suo lavoro ID e il file di risultato. |

- [Realtime rispetto all'asinclinazione](https://flashdata.dev/it/docs/reference/realtime-and-async/reference.md#choose)
- [Batch rispetto a Bulk](https://flashdata.dev/it/docs/reference/batch-and-bulk/reference.md#choose)
- [Aprire il costruttore del flusso di lavoro](https://flashdata.dev/it/docs/guides/async-batch/reference.md#customize)

<a id="prepare"></a>

## Prima di iniziare

Utilizzare una chiave API con accesso google_search e crediti disponibili. Scegliere CLI o HTTP per la presentazione, l'attesa e il recupero. Gli esempi Bash utilizzano jq; HTTP ha anche bisogno di cURL 7.76+. Eseguire in una nuova cartella di lavoro.

### CLI

Riutilizzare il profilo CLI autenticato o FLASHDATA_API_KEY. Confermare data.accessVerified è true. Impostare FLASHDATA_PROFILE per un profilo chiamato così gli script successivi lo utilizzano anche. Se non viene configurata alcuna chiave, prima utilizzare la guida di autenticazione CLI.

#### Accesso gratuito e assegni account

```bash
flashdata auth status --json
flashdata account balance --json
flashdata account limits --json
```

- [Installare e autenticare CLI](https://flashdata.dev/it/docs/guides/flashdata-cli/reference.md#existing-key)

### HTTP / cURL

Mantenere questo terminale aperto per i comandi rimanenti. Gli agenti dovrebbero leggere la chiave dal loro negozio segreto o ambiente.

#### Impostare il tasto API

```bash
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY
```

- [Creare una chiave API](https://flashdata.dev/app/api-keys)

- [Prova per agenti e collegamento](https://flashdata.dev/it/docs/guides/agent-onboarding/reference.md)
- [Controllare i prezzi](https://flashdata.dev/it/docs/guides/credits-and-billing/reference.md)

<a id="job-lifecycle"></a>

## Eseguire una ricerca di sfondo

Questo passaggio invia una ricerca Google. I controlli di stato e il recupero dei risultati non inviano un'altra query. Riutilizzare le stesse credenziali in tutto.


<a id="async-batch"></a>

## 1. Inviare una volta e mantenere la ricevuta

Il file submission.json è la tua ricevuta. HTTP restituisce un collegamento id, sorgente, stato e self/results; CLI salva la ricevuta sotto presentazione e restituisce anche remoteId. HTTP 200 significa accettato, non finito.

### CLI

#### Bash · FlashData CLI

```bash
flashdata search "battery recycling research" --num 5 \
  --mode async --run-id async-first --output submission.json --json
```


### HTTP / cURL

#### Bash · cURL + jq

```bash
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e submission.json || { echo "Use the saved receipt or a new filename." >&2; exit 1; }
curl --fail-with-body --silent --show-error \
  --request POST 'https://data.flashdata.dev/v1/queries' \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"source":"google_search","query":"battery recycling research","params":{"num":5}}' \
  --output submission.json
jq '{id, source, status, links}' submission.json
)
```



<a id="job-status"></a>

## 2. Attendere il lavoro esistente

Continuare quando il lavoro è completato. Se non è riuscito, ispezionare il suo errore prima di inviare altro.

### CLI

Un'attesa di successo restituisce data.status: completed in CLI JSON.

#### Bash · FlashData CLI

```bash
(
set -euC
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs wait "$JOB_ID" --timeout 2m --json
)
```


### HTTP / cURL

Questo va bene una volta. Ripetere lo GET dopo un breve ritardo mentre job.status è in attesa o in fase di elaborazione. Su 429, attendere Retry-After da job-headers.txt.

#### Bash · cURL + jq

```bash
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
JOB_ID=$(jq -er '(.remoteId // .id // .submission.id) | select(test("^[A-Za-z0-9_-]+$"))' submission.json)
STATUS_URL="https://api.flashdata.dev/v2/jobs/$JOB_ID"
curl --fail-with-body --silent --show-error \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --max-time 30 --dump-header job-headers.txt --output job.json "$STATUS_URL"
jq -e --arg id "$JOB_ID" '.job.id == $id' job.json >/dev/null
jq '.job | {id, source, status, error}' job.json
)
```

#### Stato completo · risposta illustrativa HTTP

```json
{
  "job": {
    "id": "EXAMPLE_JOB_ID",
    "source": "google_search",
    "status": "completed",
    "error": null
  }
}
```



<a id="job-results"></a>

## 3. Recuperare e salvare la risposta

Salva result.json localmente. Il lavoro completato e il suo corpo di risultato sono record separati: il corpo di questa ricerca contiene la fonte: google_search, un array di risultati e l'utilizzo. La validazione qui sotto accetta lo stato di successo del risultato memorizzato o completato.

### CLI

#### Bash · FlashData CLI

```bash
(
set -euC
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs result "$JOB_ID" --output result.json --json
jq '{source, status, results, usage}' result.json
)
```


### HTTP / cURL

Il risultato di default JSON reindirizza alla memoria firmata. Questo codice decomprime il risultato memorizzato e accetta anche una risposta JSON diretta. Solo l'endpoint FlashData riceve la chiave API.

#### Bash · cURL + jq

```bash
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
JOB_ID=$(jq -er '(.remoteId // .id // .submission.id) | select(test("^[A-Za-z0-9_-]+$"))' submission.json)
SOURCE=$(jq -er '(.submission // .).source' submission.json)
jq -e --arg id "$JOB_ID" --arg source "$SOURCE" \
  '.job.id == $id and .job.source == $source and .job.status == "completed"' job.json >/dev/null
test ! -e result.json || { echo "Choose a new output filename." >&2; exit 1; }
RESULT_URL="https://api.flashdata.dev/v2/jobs/$JOB_ID/results"
STATUS=$(curl --silent --show-error \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --max-time 120 --dump-header result-headers.txt --output result.pending \
  --write-out '%{http_code}' "$RESULT_URL")
case "$STATUS" in
  200) ;;
  302)
    LOCATION=$(awk 'tolower($1) == "location:" { sub(/\r$/, "", $2); print $2 }' result-headers.txt)
    # The signed storage URL is fetched WITHOUT the FlashData API key.
    curl --fail-with-body --silent --show-error --compressed --max-time 120 --proto '=https' \
      --output result.pending "$LOCATION" ;;
  *) echo "Result HTTP $STATUS; inspect result.pending and result-headers.txt." >&2; exit 1 ;;
esac
jq -e --arg source "$SOURCE" '.source == $source and (.status == "done" or .status == "completed")
  and (.results | type == "array")' result.pending >/dev/null
cat result.pending > result.json
jq '{id, source, status, results, usage}' result.json
)
```


- [Ispezione e salvataggio dei risultati di ricerca](https://flashdata.dev/it/docs/guides/google-search-guide/reference.md#results)

<a id="use-result"></a>

## 4. Utilizzare il risultato nella tua applicazione

Convalida la risposta salvata, poi estrae il titolo, il link e il snippet per una vista di ricerca o il passo successivo dell'agente. Un array organico vuoto di successo non significa elementi corrispondenti; un campo mancante o un corpo non riuscito ha bisogno di indagine.

| Attività di applicazione | Transizione |
| --- | --- |
| Aspettare | Persistere il lavoro accettato ID prima di restituire il controllo all'utente o all'agente. |
| Pronti | Mark pronto dopo che il risultato è salvato e convalidato. Utilizzare il vostro compito ID come la chiave import/upsert. |
| Necessità di attenzione | Mantenere il lavoro ID ed errore. Un timeout di inquinamento o un guasto di recupero non è una richiesta di presentare di nuovo. |

### Leggi la risposta locale · no chiamate API

```bash
jq -e '.source == "google_search" and (.status == "done" or .status == "completed")
  and (.results | type == "array")
  and all(.results[]; (.organic | type == "array"))' result.json > /dev/null &&
jq -c '.results[] | .organic[] | {title, link, snippet}' result.json
```

- [Archivio e riutilizzo della risposta](https://flashdata.dev/it/docs/guides/save-results/reference.md)

<a id="resume"></a>

## Riprendi in un altro processo

Aprire un terminale fresco nella stessa cartella, con la stessa credential/profile. Questi comandi leggono il lavoro in submission.json e salvano un nuovo nome di file. Non si sottopongono mai al lavoro. Riutilizzare la stessa CLI run ID richiede la sua directory di stato originale; HTTP stesso non deduplica POSTs utilizzando quella locale eseguire ID.

### CLI + jq · recuperare il lavoro salvato

```bash
(
set -eu
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs get "$JOB_ID" --json
flashdata jobs wait "$JOB_ID" --timeout 2m --json
flashdata jobs result "$JOB_ID" --output recovered-result.json --json
)
```

- [Esito di presentazione sconosciuto](https://flashdata.dev/it/docs/guides/agent-recovery/reference.md#recover)

<a id="batch"></a>

## Inviare diverse domande

Batch presenta lavori indipendenti in una sola richiesta. Questo esempio a due piani ha bisogno di capacità per almeno due domande e due posti di lavoro in sospeso; una prova temporanea è limitata ad una. Salvare l'array qui sotto come batch.json in una cartella di lavoro separata.

### batch.json

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

### CLI

#### Bash · FlashData CLI

```bash
flashdata batch submit --input batch.json \
  --run-id batch-first --output batch-submission.json --json
```


### HTTP / cURL

#### Bash · cURL + jq

```bash
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e batch-submission.json || { echo "Keep the saved batch receipt." >&2; exit 1; }
jq '{queries: .}' batch.json > batch-request.json
curl --fail-with-body --silent --show-error \
  --request POST 'https://data.flashdata.dev/v1/queries/batch' \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @batch-request.json --output batch-submission.json
jq '.queries[] | {id, source, status}' batch-submission.json
)
```



<a id="batch-collector"></a>

### Salvare collect-batch.py

Creare collect-batch.py nella cartella di lavoro Batch accanto a batch.json e batch-submission.json. Copia il codice completo qui sotto e salvalo.

Mantenere batch.json, batch-submission.json e batch-risultati/ insieme. Lo script si ferma se gli ingressi salvati o le ricevute cambiano. Riutilizza i file locali completati e non invia mai query sostitutive dopo un errore di lettura.

#### collect-batch.py

```python
# collect-batch.py — Python 3.10+ and FlashData CLI; no new submissions.
import json
import re
import subprocess
import sys
from pathlib import Path


def read(path):
    return json.loads(Path(path).read_text(encoding='utf-8-sig'))


def cli(*args):
    result = subprocess.run(['flashdata', *args, '--json', '--non-interactive', '--timeout', '2m'],
                            check=True, capture_output=True, text=True, encoding='utf-8')
    return json.loads(result.stdout)['data']


inputs = read('batch.json')
saved = read('batch-submission.json')
receipts = saved.get('submission', saved)['queries']
if not isinstance(inputs, list) or not inputs or len(inputs) != len(receipts):
    raise ValueError('Keep the original batch input and matching receipt.')
ids = [r.get('id', '') for r in receipts]
if len(set(ids)) != len(ids) or any(not re.fullmatch(r'[A-Za-z0-9_-]+', x) for x in ids):
    raise ValueError('Invalid or duplicate job IDs.')
folder = Path('batch-results')
folder.mkdir(exist_ok=True)
binding = json.dumps({'inputs': inputs, 'receipts': receipts}, sort_keys=True)
try:
    with (folder / 'input-receipts.json').open('x', encoding='utf-8') as file:
        file.write(binding)
except FileExistsError:
    if (folder / 'input-receipts.json').read_text(encoding='utf-8') != binding:
        raise ValueError('Inputs or receipts changed. Restore the original snapshot.')

outcomes = [{'index': index, 'input': request, 'job_id': receipt['id'], 'status': 'unread'}
            for index, (request, receipt) in enumerate(zip(inputs, receipts))]
for index, (request, receipt) in enumerate(zip(inputs, receipts)):
    job_id = receipt['id']
    file = folder / (job_id + '.json')
    row = {'index': index, 'input': request, 'job_id': job_id, 'status': 'unread'}
    try:
        if not file.exists():
            try:
                job = cli('jobs', 'wait', job_id)
            except subprocess.CalledProcessError:
                job = cli('jobs', 'get', job_id)
            if job['id'] != job_id or job['source'] != request['source']:
                raise ValueError('Job does not match the saved receipt/input.')
            row.update(status=job['status'], error=job.get('error'))
            if job['status'] == 'completed':
                cli('jobs', 'result', job_id, '--output', str(file))
        if file.exists():
            result = read(file)
            if (result.get('source') != request['source']
                    or result.get('status') not in ['done', 'completed']
                    or not isinstance(result.get('results'), list)):
                raise ValueError('Inspect the saved result before importing it.')
            row.update(status='completed', result_file=str(file), error=None)
    except (OSError, ValueError, KeyError, subprocess.CalledProcessError) as error:
        row.update(status='read_error', error=getattr(error, 'stderr', None) or str(error))
    outcomes[index] = row
    pending = folder / 'outcomes.next'
    pending.write_text(json.dumps(outcomes, ensure_ascii=False, indent=2), encoding='utf-8')
    pending.replace(folder / 'outcomes.json')
    print(index, job_id, row['status'])
print('Saved batch-results/outcomes.json. No queries were submitted.')
sys.exit(0 if all(row['status'] == 'completed' for row in outcomes) else 2)
```


<a id="batch-results"></a>

### Traccia ogni lavoro accettato

Dopo aver salvato collect-batch.py, eseguirlo dalla cartella di lavoro Batch con Python 3.10+ e l'autenticazione CLI. Funziona con il metodo di presentazione sopra. Legge ogni ricevuta, aspetta fino a due minuti per lavoro incompiuto e salva ogni risposta di successo. Eseguire un collettore alla volta; riscattarlo per continuare gli stessi lavori.

Aspettatevi due voci in batch-results/outcomes.json per il campione. Importa le voci completate dall'indice di input e dal lavoro ID. Le voci in sospeso e read_error rimangono visibili; il codice di uscita 2 significa rivederle o riprenderle. Il collezionista non invia nuove domande.

#### Bash

```bash
python3 collect-batch.py
```

#### PowerShell 7

```powershell
python collect-batch.py
```

#### Leggi ogni risultato · jq

```bash
jq '.[] | {index, job_id, status, result_file, error}' batch-results/outcomes.json
```

- [Modello di risultato Batch](https://flashdata.dev/it/docs/reference/batch-and-bulk/reference.md#batch-results)
- [Mantenere il record di applicazione IDs](https://flashdata.dev/it/docs/guides/enrich-youtube-videos/reference.md)

<a id="webhooks"></a>

## Ricevere un Webhook di completamento

Aggiungi callback_url accanto alla sorgente, alla query e ai params in una singola richiesta o ogni voce Batch. Sostituire l'esempio URL con il ricevitore. Eventi relazione di completamento o fallimento; recuperare il risultato separatamente.

1. Persistere l'evento e restituire immediatamente 2xx. Deduplicare delivery_id (inviato anche come X-Delivery-Id).
2. L'evento non è firmato. Abbina il suo id e la fonte al tuo scontrino salvato, quindi autentichi uno stato letto utilizzando il collegamento di auto della ricevuta originale. Non fidarti di URLs fornito da un evento non verificato.
3. A completamento, prendere e salvare il risultato. In caso di fallimento, ispezionare l'errore di lavoro. Tenere l'inquinamento come un fallback se non arriva nessun evento.

### Richiedere corpo con un callback

```json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
```

### Corpo evento · illustrativo

```json
{
  "delivery_id": "completion:EXAMPLE_JOB_ID",
  "id": "EXAMPLE_JOB_ID",
  "source": "google_search",
  "status": "completed",
  "links": [
    {
      "rel": "self",
      "href": "https://api.flashdata.dev/v2/jobs/EXAMPLE_JOB_ID",
      "method": "GET"
    },
    {
      "rel": "results",
      "href": "https://api.flashdata.dev/v2/jobs/EXAMPLE_JOB_ID/results",
      "method": "GET"
    }
  ]
}
```

- [Generare un ricevitore nel costruttore del flusso di lavoro](https://flashdata.dev/it/docs/guides/async-batch/reference.md#customize)

<a id="callbacks"></a>

### Requisiti di Callback URL

Utilizzare un pubblico HTTPS URL sulla porta 443, al massimo caratteri 2,048, senza credenziali o un frammento. Ogni IP risolto deve essere pubblico. Omit callback_url, o utilizzare null o una stringa vuota, per disabilitare le notifiche.


<a id="limits"></a>

## Recuperare un lavoro esistente

| Situazione | Cosa fare |
| --- | --- |
| La sottomissione si esaurisce | Ispezione runs show asinc-first e account History. runs recover può recuperare il lavoro accettato IDs; se non è stato salvato ID, riconciliare la presentazione prima di inviare un altro POST. |
| pending / processing | Continua a controllare il lavoro esistente. Questi stati non sono fallimenti. |
| failed / 422 | Leggi job.error, correggi la causa e decidi se inviare un nuovo lavoro. |
| 429 | Honor Retry-After. Ridurre la convalutazione di presentazione se la capacità di lavoro in attesa è piena. |
| 404 / 409 | 404: controlla il ID e invia il conto. 409: i risultati non sono ancora pronti. |
| 410 | Il risultato memorizzato JSON scade alle ore 24 dopo il completamento. Usa la copia salvata. I media già consegnati al vostro storage seguono la politica di conservazione dello storage. |

- [Limiti di tasso e utilizzo](https://flashdata.dev/it/docs/guides/usage-and-limits/reference.md)
- [Recupero di esecuzione CLI](https://flashdata.dev/it/docs/guides/cli-automation/reference.md#recover)

<a id="delivery"></a>

## Eseguire un YouTube Scaricare il lavoro?

Download utilizza asincrona o Batch e ha bisogno di una chiave API proprietario con accesso youtube_download più archiviazione di destinazione. Il suo risultato JSON descrive i media già consegnati al vostro secchio; il endpoint dei risultati non trasmette byte video. Utilizzare la guida Download per configurare lo storage e verificare il file consegnato.

- [Configurare lo storage e il download](https://flashdata.dev/it/docs/guides/youtube-download-guide/reference.md)
- [Verificare i media consegnati](https://flashdata.dev/it/docs/guides/youtube-download-guide/reference.md#verify-media)

<a id="api-hosts"></a>

## Host e formati di risposta

Tutti e quattro usano X-API-Key. Utilizzare la stessa chiave della presentazione. Le letture di stato e di risultato sono gratuite, ma il tasso è limitato. Gli esempi utilizzano JSON; scegliere Accept e X-Respond-With nel costruttore per altre rappresentazioni dei risultati. Un download di archiviazione firmato utilizza il suo URL, senza la chiave FlashData.

| Operazione | Punto di arrivo |
| --- | --- |
| Inviare un lavoro | POST https://data.flashdata.dev/v1/queries |
| Inviare un lotto | POST https://data.flashdata.dev/v1/queries/batch |
| Situazione di lettura | GET https://api.flashdata.dev/v2/jobs/{id} |
| Leggi i risultati | GET https://api.flashdata.dev/v2/jobs/{id}/results |

- [Realtime e protocollo asincastro](https://flashdata.dev/it/docs/reference/realtime-and-async/reference.md)
- [Protocollo di richiesta Batch](https://flashdata.dev/it/docs/reference/batch-and-bulk/reference.md)
- [Regole del formato di risposta](https://flashdata.dev/it/docs/guides/response-formats/reference.md)

<a id="supported-sources"></a>

## Fonti e modalità supportate

Utilizzare il costruttore qui sotto per i parametri attuali della fonte. Google Ricerca e YouTube Supporto dati lavori di sfondo. YouTube Download utilizza lavori di sfondo e archiviazione di destinazione. Per un grande file di video IDs con opzioni condivise, utilizzare la guida Bulk.

- [Modalità di richiesta](https://flashdata.dev/it/docs/reference/realtime-and-async/reference.md#choose)
- [Flusso di lavoro del file Bulk](https://flashdata.dev/it/docs/guides/bulk/reference.md)

<a id="customize"></a>

## Costruire un flusso di lavoro per la tua fonte

Scegli una sorgente, modifica i suoi parametri e copia il flusso di lavoro generato nella tua lingua. Abilitare un callback per rivelare l'esempio del ricevitore. Questo costruttore prevede le risposte al codice e al campione; le richieste vengono eseguite solo quando si esegue il codice o si utilizza la console.

- [Parametri e schemi di origine](https://flashdata.dev/it/docs/reference/reference.md)
