Aller au contenu
FR
Obtenir une clé API
Parcourir la documentation

Guides

Requêtes asynchrones et Batch

Exécutez des tâches en arrière-plan pour une application ou un agent, reprenez-les à partir de leur identifiant enregistré et collectez le résultat de chaque élément du lot.

Sur cette page

Reprendre après l’arrêt de votre processus

Utilisez une tâche en arrière-plan pour un traitement en file d’attente ou un workflow d’agent qui peut se terminer plus tard. Ce guide lance une recherche Google, enregistre son reçu et reprend à partir de ce reçu dans un autre processus.

À conserverRôle
Reçu de la tâchesubmission.json — conservez l’identifiant de la tâche acceptée avec la tâche applicative et ses paramètres d’origine.
Réponse enregistréeresult.json — validez sa source et ses résultats avant de l’importer.
Résultats du lotbatch-results/outcomes.json — une entrée par élément d’entrée, avec son identifiant de tâche et son fichier de résultat.

Avant de commencer

Utilisez une clé API autorisée pour google_search et un solde disponible. Choisissez la CLI ou HTTP pour la soumission, l’attente et la récupération. Les exemples Bash utilisent jq ; HTTP nécessite aussi cURL 7.76+. Travaillez dans un nouveau dossier.

Réutilisez votre profil CLI authentifié ou FLASHDATA_API_KEY. Confirmez que data.accessVerified vaut true. Pour un profil nommé, définissez FLASHDATA_PROFILE afin que les scripts suivants l’utilisent aussi. Si aucune clé n’est configurée, suivez d’abord le guide d’authentification CLI.

Vérifications gratuites de l’accès et du compte
flashdata auth status --json
flashdata account balance --json
flashdata account limits --json

Lancer une recherche en arrière-plan

Ce guide soumet une recherche Google Search. Les vérifications d’état et la récupération du résultat n’en soumettent pas d’autre. Conservez les mêmes identifiants à toutes les étapes.

1. Soumettre une seule fois et conserver le reçu

Le fichier submission.json est votre reçu. HTTP renvoie id, source, status et les liens self/results ; la CLI enregistre le reçu sous submission et renvoie aussi remoteId. HTTP 200 signifie que la requête est acceptée, pas qu’elle est terminée.

Bash · FlashData CLI
flashdata search "battery recycling research" --num 5 \
  --mode async --run-id async-first --output submission.json --json

2. Attendre la tâche existante

Continuez quand la tâche atteint completed. En cas d’échec, examinez son erreur avant toute nouvelle soumission.

Une attente réussie renvoie data.status: completed dans le JSON de la CLI.

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

3. Récupérer et enregistrer la réponse

Enregistrez result.json localement. La tâche terminée et le corps du résultat sont deux enregistrements distincts : le corps de cette recherche contient source: google_search, un tableau results et usage. La validation ci-dessous accepte les états de réussite done ou completed du résultat conservé.

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. Utiliser le résultat dans votre application

Validez la réponse enregistrée, puis extrayez title, link et snippet pour l’interface de recherche ou l’étape suivante de l’agent. Un tableau organic vide dans une réponse réussie signifie qu’aucun élément ne correspond ; un champ absent ou une réponse en échec demande une vérification.

Tâche applicativeTransition
En attenteEnregistrez durablement l’identifiant de la tâche acceptée avant de rendre la main à l’utilisateur ou à l’agent.
PrêteMarquez la tâche comme prête une fois le résultat enregistré et validé. Utilisez votre identifiant de tâche comme clé d’importation ou de mise à jour.
Intervention nécessaireConservez l’identifiant de tâche et l’erreur. Un délai d’attente dépassé ou un échec de récupération ne justifie pas à lui seul une nouvelle soumission.
Lire la réponse locale · aucun appel API
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

Reprendre dans un autre processus

Ouvrez un nouveau terminal dans le même dossier, avec les mêmes identifiants et le même profil. Ces commandes lisent la tâche de submission.json et enregistrent le résultat sous un nouveau nom, sans soumettre d’opération. Réutiliser le même identifiant d’exécution CLI nécessite son répertoire d’état d’origine ; HTTP ne déduplique pas les POST à partir de cet identifiant local.

CLI + jq · reprendre la tâche enregistrée
(
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
)

Soumettre plusieurs requêtes

Batch soumet des tâches indépendantes dans une seule requête. Cet exemple de deux recherches nécessite une capacité d’au moins deux requêtes et deux tâches en attente ; un essai temporaire est limité à une seule. Enregistrez le tableau ci-dessous dans batch.json, dans un dossier de travail distinct.

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

Enregistrer collect-batch.py

Créez collect-batch.py dans le dossier Batch, à côté de batch.json et batch-submission.json. Copiez-y le code complet ci-dessous et enregistrez-le.

Gardez batch.json, batch-submission.json et batch-results/ ensemble. Le script s’arrête si les paramètres ou les reçus enregistrés changent. Il réutilise les fichiers locaux terminés et ne soumet jamais de requête de remplacement après une erreur de lecture.

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)

Suivre chaque tâche acceptée

Après avoir enregistré collect-batch.py, lancez-le depuis le dossier Batch avec Python 3.10+ et la CLI authentifiée. Il fonctionne avec les deux méthodes de soumission ci-dessus. Il lit chaque reçu, attend au maximum deux minutes par tâche inachevée et enregistre chaque réponse réussie. Exécutez un seul collecteur à la fois ; relancez-le pour poursuivre les mêmes tâches.

L’exemple doit produire deux entrées dans batch-results/outcomes.json. Importez les entrées terminées selon l’index d’entrée et l’identifiant de tâche. Les entrées failed, pending et read_error restent visibles ; le code de sortie 2 indique qu’il faut les examiner ou les reprendre. Le collecteur n’envoie aucune nouvelle requête.

Bash
python3 collect-batch.py
PowerShell 7
python collect-batch.py
Lire chaque résultat · jq
jq '.[] | {index, job_id, status, result_file, error}' batch-results/outcomes.json

Recevoir un webhook de fin de tâche

Ajoutez callback_url à côté de source, query et params dans une requête unique ou dans chaque entrée Batch. Remplacez l’URL de l’exemple par celle de votre récepteur. Les événements signalent la réussite ou l’échec ; récupérez le résultat séparément.

  1. Enregistrez l’événement durablement et renvoyez rapidement 2xx. Dédupliquez selon delivery_id, également envoyé dans X-Delivery-Id.
  2. L’événement n’est pas signé. Comparez ses champs id et source au reçu enregistré, puis effectuez une lecture d’état authentifiée via le lien self de ce reçu. Ne faites pas confiance aux URL fournies par un événement non vérifié.
  3. À l’état completed, récupérez et enregistrez le résultat. À l’état failed, examinez l’erreur de la tâche. Conservez les lectures périodiques comme solution de secours si aucun événement n’arrive.
Corps de requête avec callback
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
Corps d’événement · exemple
{
  "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"
    }
  ]
}

Exigences de l’URL de callback

Utilisez une URL HTTPS publique sur le port 443, de 2 048 caractères au maximum, sans identifiants ni fragment. Toutes les adresses IP résolues doivent être publiques. Omettez callback_url, ou utilisez null ou une chaîne vide, pour désactiver les notifications.

Reprendre une tâche existante

SituationAction
Délai de soumission dépasséConsultez runs show async-first et History dans votre compte. runs recover peut récupérer les identifiants des tâches acceptées ; si aucun identifiant n’a été enregistré, établissez le résultat de la soumission avant d’envoyer un autre POST.
pending / processingContinuez à consulter la tâche existante. Ces états ne sont pas des échecs.
failed / 422Lisez job.error, corrigez la cause et décidez s’il faut soumettre une nouvelle opération.
429Respectez Retry-After. Réduisez le nombre de soumissions simultanées si la capacité de tâches en attente est atteinte.
404 / 409404 : vérifiez l’identifiant et le compte utilisé pour la soumission. 409 : les résultats ne sont pas encore prêts.
410Le résultat JSON conservé expire 24 heures après la fin de la tâche. Utilisez votre copie enregistrée. Les médias déjà livrés dans votre stockage suivent sa politique de conservation.

Vous lancez un téléchargement YouTube ?

Le téléchargement utilise le mode asynchrone ou Batch et nécessite une clé API propriétaire autorisée pour youtube_download, ainsi qu’un stockage de destination. Son résultat JSON décrit le média déjà livré dans votre bucket ; l’endpoint de résultat ne diffuse pas les octets vidéo. Consultez le guide Download pour configurer le stockage et vérifier le fichier livré.

Hôtes et formats de réponse

Les quatre opérations utilisent X-API-Key. Conservez la clé de la soumission. Les lectures d’état et de résultat sont gratuites, mais soumises aux limites de débit. Les exemples utilisent JSON ; sélectionnez Accept et X-Respond-With dans le générateur pour obtenir d’autres représentations. Le téléchargement depuis le stockage signé utilise son URL, sans la clé FlashData.

OpérationEndpoint
Soumettre une tâchePOST https://data.flashdata.dev/v1/queries
Soumettre un lotPOST https://data.flashdata.dev/v1/queries/batch
Lire l’étatGET https://api.flashdata.dev/v2/jobs/{id}
Lire les résultatsGET https://api.flashdata.dev/v2/jobs/{id}/results

Sources et modes pris en charge

Utilisez le générateur ci-dessous pour les paramètres actuels de la source. Google Search et YouTube Data prennent en charge les tâches en arrière-plan. YouTube Download utilise ces tâches avec un stockage de destination. Pour un grand fichier d’identifiants vidéo partageant les mêmes options, consultez le guide Bulk.

Construire un workflow pour votre source

Choisissez une source, modifiez ses paramètres et copiez le workflow généré dans votre langage. Activez un callback pour afficher l’exemple de récepteur. Ce générateur affiche du code et des exemples de réponse ; les requêtes ne sont exécutées que lorsque vous lancez le code ou utilisez la console.

Paramètres de la source

Préparer une requête

Paramètres avancés

Démarre à 1. Chaque page est une requête séparée.

Filtre temporel Google, par exemple qdr:d pour les dernières 24 heures.

Webhook de fin de tâcheContenu du webhook, vérification et nouvelles tentatives

Markdown s’applique aux résultats une fois le traitement terminé. Les reçus et l’état des tâches conservent leurs champs d’origine.

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']}")
Tâche acceptée ; suivez son état pour récupérer le résultatAuthentification X-API-Key