# Async & batchverzoeken

Start achtergrondwerk voor een applicatie of agent, hervat de opgeslagen taak ID en verzamel alle batchresultaten.

Canonische referentie: https://flashdata.dev/nl/docs/guides/async-batch
Beoordeeld: 2026-11-05 door FlashData

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

## Ga door met werken na het stoppen van uw proces

Gebruik een achtergrondtaak voor een applicatietaak in de wachtrij of een agentworkflow die later finish kan uitvoeren. Deze walkthrough draait een Google zoekopdracht, slaat de ontvangst en hervat van dat ontvangstbewijs in een ander proces.

| Houden | Betreft |
| --- | --- |
| Taakbevestiging | submission.json Houd de geaccepteerde baan ID met uw toepassingstaak en originele invoer. |
| Opgeslagen antwoord | result.json valideert zijn bron en resultaten voordat hij het importeert. |
| Batch resultaten | batch-results/outcomes.json Een ingang per invoer, met zijn taak ID en resultaatbestand. |

- [Realtime versus async](https://flashdata.dev/nl/docs/reference/realtime-and-async/reference.md#choose)
- [Batch versus Bulk](https://flashdata.dev/nl/docs/reference/batch-and-bulk/reference.md#choose)
- [Open de workflow bouwer](https://flashdata.dev/nl/docs/guides/async-batch/reference.md#customize)

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

## Voordat u begint

Gebruik een API sleutel met google_search toegang en beschikbare credits. Kies CLI of HTTP voor indiening, wachten en ophalen. De Bash voorbeelden gebruiken jq; HTTP heeft ook cURL 7.76+ nodig. Uitvoeren in een nieuwe werkmap.

### CLI

Hergebruik uw geauthentificeerde CLI-profiel of FLASHDATA_API_KEY. Bevestig dat data.accessVerified true is. Stel FLASHDATA_PROFILE in voor een genoemd profiel, zodat latere scripts het ook gebruiken. Als er geen sleutel is geconfigureerd, gebruik dan eerst de CLI authenticatie-handleiding.

#### Gratis toegang en accountcontroles

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

- [De CLI installeren en authenticeren](https://flashdata.dev/nl/docs/guides/flashdata-cli/reference.md#existing-key)

### HTTP / cURL

Houd deze terminal open voor de resterende opdrachten. Agenten moeten de sleutel uit hun geheime winkel of omgeving lezen.

#### Stel uw API-sleutel in

```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
```

- [Een API-sleutel aanmaken](https://flashdata.dev/app/api-keys)

- [Proefgebruik en accountkoppeling](https://flashdata.dev/nl/docs/guides/agent-onboarding/reference.md)
- [Prijscontrole](https://flashdata.dev/nl/docs/guides/credits-and-billing/reference.md)

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

## Een achtergrondzoekopdracht uitvoeren

Deze walkthrough dient één Google Search in. Status controles en resultaat ophalen niet indienen van een andere vraag. Hergebruik dezelfde credentialiteit doorheen de hele tijd.


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

## 1. Eenmaal indienen en het ontvangstbewijs bewaren

Het submission.json-bestand is uw ontvangstbewijs. HTTP geeft een id, bron, status en self/results-links terug; CLI slaat de ontvangst op onder indiening en geeft ook remoteId terug. HTTP 200 betekent geaccepteerd, niet voltooid.

### 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. Wacht op de bestaande taak

Ga door als de taak is voltooid. Als het mislukt, controleer zijn fout voordat het indienen van iets anders.

### CLI

Een succesvolle wachttijd geeft data.status: completed terug 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

Dit klopt één keer. Herhaal de GET na een korte vertraging terwijl job.status in behandeling is. Op 429, wacht op Retry-After van 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
)
```

#### Voltooide status · illustratieve HTTP-respons

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



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

## 3. Ophalen en opslaan van het antwoord

result.json lokaal opslaan. De voltooide taak en het resultaat lichaam zijn aparte records: deze zoekopdracht's lichaam bevat bron: google_search, een resultaten array en gebruik. De onderstaande validatie accepteert de opgeslagen resultaat's gedaan of voltooid succes status.

### 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

De standaard JSON resultaat verwijst naar ondertekende opslag. Deze code decomprimeert het opgeslagen resultaat en accepteert ook een directe JSON respons. Alleen het FlashData-eindpunt ontvangt uw API-sleutel.

#### 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
)
```


- [Zoekresultaten inspecteren en opslaan](https://flashdata.dev/nl/docs/guides/google-search-guide/reference.md#results)

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

## 4. Gebruik het resultaat in uw toepassing

Valideer het opgeslagen antwoord en haal dan titel, koppeling en knipsel uit voor een zoekweergave of de volgende stap van de agent. Een succesvolle lege organische array betekent geen overeenkomende items; een ontbrekend veld of mislukt lichaam moet worden onderzocht.

| Toepassingstaken | Overgang |
| --- | --- |
| Wachten | Perst de geaccepteerde baan ID voordat u de controle teruggeeft aan de gebruiker of agent. |
| Klaar | Markeer klaar nadat het resultaat is opgeslagen en gevalideerd. Gebruik je taak ID als de import/upsert sleutel. |
| Heeft aandacht nodig | Houd de taak ID en fout. Een peiling timeout of het ophalen falen is niet een verzoek om opnieuw in te dienen. |

### Lees het lokale antwoord · geen API-gesprekken

```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
```

- [Archief en hergebruik de reactie](https://flashdata.dev/nl/docs/guides/save-results/reference.md)

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

## Hervatten in een ander proces

Open een nieuwe terminal in dezelfde map, met dezelfde credential/profile. Deze commando's lezen de taak in submission.json en slaan op naar een nieuwe bestandsnaam. Ze geven nooit werk. Het hergebruik van dezelfde CLI-run ID vereist zijn oorspronkelijke status directory; HTTP zelf dedupliceert POST's niet met behulp van de lokale ID.

### CLI + jq · herstel de opgeslagen taak

```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
)
```

- [Onbekend resultaat van indiening](https://flashdata.dev/nl/docs/guides/agent-recovery/reference.md#recover)

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

## Meerdere vragen indienen

Batch stuurt onafhankelijke jobs in één verzoek. Dit twee-verzochte voorbeeld heeft capaciteit nodig voor ten minste twee vragen en twee hangende banen; een tijdelijke proef is beperkt tot één. Sla de array hieronder op als batch.json in een aparte werkmap.

### 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>

### collect-batch.py opslaan

Maak collect-batch.py in de Batch werkmap naast batch.json en batch-submission.json. Kopieer de volledige code hieronder in het en sla het op.

Houd batch.json, batch-submission.json en batch-resultaten/samen. Het script stopt als de opgeslagen invoer of ontvangstbewijzen veranderen. Het hergebruikt voltooide lokale bestanden en dient nooit vervangende vragen in na een leesfout.

#### 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>

### Volg elke geaccepteerde baan

Na het opslaan van collect-batch.py, voer het uit vanaf de Batch werkmap met Python 3.10+ en de geauthentiseerde CLI. Het werkt met een van beide indieningsmethode hierboven. Het leest elke bon, wacht tot twee minuten per onafgemaakte taak en bespaart elke succesvolle reactie. Voer één verzamelaar tegelijk uit; herrun het om dezelfde taken voort te zetten.

Verwacht twee inzendingen in batch-results/outcomes.json voor het monster. Importeer voltooide items per invoerindex en taak ID. Fout, hangende en read_error ingangen blijven zichtbaar; exit code 2 betekent herzien of hervatten. De verzamelaar stuurt geen nieuwe vragen.

#### Bash

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

#### PowerShell 7

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

#### Lees elk resultaat · jq

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

- [Batch resultaatmodel](https://flashdata.dev/nl/docs/reference/batch-and-bulk/reference.md#batch-results)
- [IDs van de toepassing bijhouden](https://flashdata.dev/nl/docs/guides/enrich-youtube-videos/reference.md)

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

## Ontvang een aangevulde webhook

Voeg callback_url naast bron, query en params in een enkele aanvraag of elke Batch-invoer. Vervang het voorbeeld URL door uw ontvanger. Gebeurtenissen melden voltooiing of mislukking; het resultaat apart ophalen.

1. Persist het evenement en terug 2xx snel. Dedupliceer delivery_id (ook verzonden als X-Delivery-Id).
2. Het evenement is niet ondertekend. Pas zijn id en bron aan je opgeslagen ontvangstbewijs aan en authenticeer vervolgens een status gelezen door gebruik te maken van de zelfkoppeling van het originele ontvangstbewijs. Vertrouw URLs niet die geleverd wordt door een niet geverifieerde gebeurtenis.
3. Op voltooid, ophalen en opslaan van het resultaat. Controleer de taakfout bij falen. Blijf peilen als een terugval als er geen evenement aankomt.

### Verzoeklichaam met terugroep

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

### Gebeurtenisinhoud · illustratief

```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"
    }
  ]
}
```

- [Genereer een ontvanger in de workflow builder](https://flashdata.dev/nl/docs/guides/async-batch/reference.md#customize)

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

### Terugroep URL eisen

Gebruik een publieke HTTPS URL op poort 443, hooguit 2,048 tekens, zonder referenties of een fragment. Elk opgelost IP moet openbaar zijn. callback_url of null of een lege string gebruiken om notificaties uit te schakelen.


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

## Krijg een bestaande baan terug

| Situatie | Wat je moet doen |
| --- | --- |
| Indiening is verlopen | Inspecteer runs show async-first en account History. runs recover kan geaccepteerde baan IDs ophalen; als er geen ID is opgeslagen, combineer de inzending voordat u een andere POST verstuurt. |
| pending / processing | Blijf de bestaande baan controleren. Deze staten zijn geen mislukkingen. |
| failed / 422 | Lees job.error, corrigeer de oorzaak en beslis of je nieuw werk wilt indienen. |
| 429 | Eer Retry-After. Verminder de indiening concurrence als de in behandeling zijnde-werkcapaciteit is vol. |
| 404 / 409 | 404: controleer de ID en verzendaccount. 409: de resultaten zijn nog niet klaar. |
| 410 | Opgeslagen resultaat JSON verloopt 24 uren na voltooiing. Gebruik je bewaarde kopie. Media die al in uw opslag zijn geleverd, volgt het bewaarbeleid van die opslag. |

- [Snelheidslimieten en gebruik](https://flashdata.dev/nl/docs/guides/usage-and-limits/reference.md)
- [CLI run recovery](https://flashdata.dev/nl/docs/guides/cli-automation/reference.md#recover)

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

## Een YouTube Download-taak uitvoeren?

Download maakt gebruik van async of Batch en heeft een eigenaar API sleutel nodig met youtube_download toegang plus bestemmingsopslag. Het resultaat JSON beschrijft de media die al in uw emmer geleverd zijn; het resultaat eindpunt streamt geen video bytes. Gebruik de Download-handleiding om opslag te configureren en het geleverde bestand te verifiëren.

- [Opslag instellen en downloaden](https://flashdata.dev/nl/docs/guides/youtube-download-guide/reference.md)
- [Verifiëren van geleverde media](https://flashdata.dev/nl/docs/guides/youtube-download-guide/reference.md#verify-media)

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

## Hosts en responsformaten

Alle vier gebruiken ze X-API-Key. Gebruik dezelfde sleutel als de inzending. Status en resultaat lezen zijn gratis, maar tarief-beperkt. De voorbeelden gebruiken JSON; kies Accept en X-Respond-With in de bouwer voor andere resultaatrepresentaties. Een gesigneerde opslagdownload gebruikt zijn URL, zonder de FlashData sleutel.

| Werking | Eindpunt |
| --- | --- |
| Een klus indienen | POST https://data.flashdata.dev/v1/queries |
| Een partij indienen | POST https://data.flashdata.dev/v1/queries/batch |
| Leesstatus | GET https://api.flashdata.dev/v2/jobs/{id} |
| Resultaten lezen | GET https://api.flashdata.dev/v2/jobs/{id}/results |

- [Realtime en async protocol](https://flashdata.dev/nl/docs/reference/realtime-and-async/reference.md)
- [Batch-verzoekprotocol](https://flashdata.dev/nl/docs/reference/batch-and-bulk/reference.md)
- [Regels voor responsformaat](https://flashdata.dev/nl/docs/guides/response-formats/reference.md)

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

## Ondersteunde bronnen en modi

Gebruik de bouwer hieronder voor de huidige parameters van de bron. Google Search en YouTube Data ondersteunen achtergrondtaken. YouTube Download gebruikt achtergrond jobs en destination storage. Voor een groot bestand van video IDs met gedeelde opties, gebruik de Bulk-handleiding.

- [Verzoekmodi](https://flashdata.dev/nl/docs/reference/realtime-and-async/reference.md#choose)
- [Bulk bestandsworkflow](https://flashdata.dev/nl/docs/guides/bulk/reference.md)

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

## Bouw een workflow voor uw broncode

Kies een bron, bewerk de parameters en kopieer de gegenereerde workflow in uw taal. Een callback inschakelen om het ontvangervoorbeeld te onthullen. Deze bouwer previews code en steekproef antwoorden; verzoeken draaien alleen wanneer u de code uitvoert of gebruik maken van de console.

- [Bronparameters en schema's](https://flashdata.dev/nl/docs/reference/reference.md)
