Documentatie bekijken
Handleidingen
Start achtergrondwerk voor een applicatie of agent, hervat de opgeslagen taak ID en verzamel alle batchresultaten.
Op deze pagina
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. |
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.
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.
flashdata auth status --json
flashdata account balance --json
flashdata account limits --jsonHoud deze terminal open voor de resterende opdrachten. Agenten moeten de sleutel uit hun geheime winkel of omgeving lezen.
# 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_KEYEen 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.
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.
flashdata search "battery recycling research" --num 5 \
--mode async --run-id async-first --output submission.json --json(
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
)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.
Een succesvolle wachttijd geeft data.status: completed terug in CLI JSON.
(
set -euC
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs wait "$JOB_ID" --timeout 2m --json
)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.
(
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
){
"job": {
"id": "EXAMPLE_JOB_ID",
"source": "google_search",
"status": "completed",
"error": null
}
}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.
(
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
)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.
(
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
)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. |
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.jsonHervatten 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.
(
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
)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.
[
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
}
},
{
"source": "google_search",
"query": "lithium battery recycling methods",
"params": {
"num": 5
}
}
]flashdata batch submit --input batch.json \
--run-id batch-first --output batch-submission.json --json(
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
)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 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)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.
python3 collect-batch.pypython collect-batch.pyjq '.[] | {index, job_id, status, result_file, error}' batch-results/outcomes.jsonOntvang 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.
- Persist het evenement en terug 2xx snel. Dedupliceer delivery_id (ook verzonden als X-Delivery-Id).
- 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.
- Op voltooid, ophalen en opslaan van het resultaat. Controleer de taakfout bij falen. Blijf peilen als een terugval als er geen evenement aankomt.
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
},
"callback_url": "https://your-app.example/webhooks/flashdata"
}{
"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"
}
]
}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.
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. |
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.
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 |
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.
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.
Stel een aanvraag samen
Geavanceerde parameters
Begint bij 1. Elke pagina is een afzonderlijke aanvraag.
Tijdfilter van Google, bijvoorbeeld qdr:d voor de afgelopen 24 uur.
Aanvulling webhook
Webhook payload, verificatie en herhalingenMarkdown geldt voor voltooide resultaten. Ontvangst en functiestatus houden hun oorspronkelijke velden.
https://data.flashdata.dev/v1/queries