Ga naar de inhoud
NL
API-sleutel ophalen
Documentatie bekijken

Handleidingen

Async & batchverzoeken

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.

HoudenBetreft
Taakbevestigingsubmission.json Houd de geaccepteerde baan ID met uw toepassingstaak en originele invoer.
Opgeslagen antwoordresult.json valideert zijn bron en resultaten voordat hij het importeert.
Batch resultatenbatch-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.

Gratis toegang en accountcontroles
flashdata auth status --json
flashdata account balance --json
flashdata account limits --json

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.

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.

Bash · FlashData CLI
flashdata search "battery recycling research" --num 5 \
  --mode async --run-id async-first --output submission.json --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.

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

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.

Bash · FlashData CLI
(
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
)

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.

ToepassingstakenOvergang
WachtenPerst de geaccepteerde baan ID voordat u de controle teruggeeft aan de gebruiker of agent.
KlaarMarkeer klaar nadat het resultaat is opgeslagen en gevalideerd. Gebruik je taak ID als de import/upsert sleutel.
Heeft aandacht nodigHoud 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
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

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
(
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.

batch.json
[
  {
    "source": "google_search",
    "query": "battery recycling research",
    "params": {
      "num": 5
    }
  },
  {
    "source": "google_search",
    "query": "lithium battery recycling methods",
    "params": {
      "num": 5
    }
  }
]
Bash · FlashData CLI
flashdata batch submit --input batch.json \
  --run-id batch-first --output batch-submission.json --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
# 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.

Bash
python3 collect-batch.py
PowerShell 7
python collect-batch.py
Lees elk resultaat · jq
jq '.[] | {index, job_id, status, result_file, error}' batch-results/outcomes.json

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
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
Gebeurtenisinhoud · illustratief
{
  "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

SituatieWat je moet doen
Indiening is verlopenInspecteer 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 / processingBlijf de bestaande baan controleren. Deze staten zijn geen mislukkingen.
failed / 422Lees job.error, corrigeer de oorzaak en beslis of je nieuw werk wilt indienen.
429Eer Retry-After. Verminder de indiening concurrence als de in behandeling zijnde-werkcapaciteit is vol.
404 / 409404: controleer de ID en verzendaccount. 409: de resultaten zijn nog niet klaar.
410Opgeslagen 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.

WerkingEindpunt
Een klus indienenPOST https://data.flashdata.dev/v1/queries
Een partij indienenPOST https://data.flashdata.dev/v1/queries/batch
LeesstatusGET https://api.flashdata.dev/v2/jobs/{id}
Resultaten lezenGET 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.

Bronparameters

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 webhookWebhook payload, verificatie en herhalingen

Markdown geldt voor voltooide resultaten. Ontvangst en functiestatus houden hun oorspronkelijke velden.

POSThttps://data.flashdata.dev/v1/queries
import gzip
import json
import random
import time
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"
payload = {
    "source": "google_search",
    "query": "openai",
    "params": {
        "gl": "us",
        "hl": "en",
        "num": 10,
        "page": 1,
    },
}

def api_get(url):
    request = urllib.request.Request(url, headers={"X-API-Key": api_key})
    with urllib.request.urlopen(request, timeout=60) as response:
        return json.load(response), response.headers

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, request, file_pointer, code, message, headers, new_url):
        return None

def read_result(url):
    request = urllib.request.Request(url, headers={"X-API-Key": api_key})
    try:
        with urllib.request.build_opener(NoRedirect).open(request, timeout=60):
            raise RuntimeError("Expected a result redirect")
    except urllib.error.HTTPError as response:
        if response.code != 302 or not response.headers.get("Location"):
            raise
        storage_url = response.headers["Location"]
        response.close()
    # Never forward the API key to storage.
    with urllib.request.urlopen(urllib.request.Request(storage_url, headers={"Accept-Encoding": "gzip"}), timeout=60) as response:
        content = response.read()
        if response.headers.get("Content-Encoding") == "gzip":
            content = gzip.decompress(content)
        return json.loads(content)

def link(job, relation):
    return next(item["href"] for item in job["links"] if item["rel"] == relation)

request = urllib.request.Request(
    "https://data.flashdata.dev/v1/queries",
    data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
    headers={"Content-Type": "application/json", "X-API-Key": api_key},
    method="POST",
)
with urllib.request.urlopen(request, timeout=120) as response:
    submission = json.load(response)
jobs = submission.get("queries", [submission])
for submitted in jobs:
    print("Job:", submitted["id"])
    deadline = time.monotonic() + 300
    while time.monotonic() < deadline:
        status, headers = api_get(link(submitted, "self"))
        job = status.get("job", status)
        if job["status"] == "completed":
            result = job.get("result") if submitted["source"] == "youtube_download" and job.get("result") is not None else read_result(link(submitted, "results"))
            print(json.dumps(result, ensure_ascii=False, indent=2))
            break
        if job["status"] == "failed":
            raise RuntimeError(f"{submitted['id']}: {job.get('error', 'Job failed')}")
        hint = headers.get("Retry-After", "1")
        delay = max(1, min(5, int(hint))) if hint.isdigit() else 5
        time.sleep(min(delay * random.uniform(1, 1.2), max(0, deadline - time.monotonic())))
    else:
        raise TimeoutError(f"Still running; save this job ID: {submitted['id']}")
Kwijtschelding, daarna poll voor resultatenX-API-Key-authenticatie