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

Référence canonique : https://flashdata.dev/fr/docs/guides/async-batch
Vérifié le 2026-11-05 par FlashData

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

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

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

- [Choisir entre temps réel et asynchrone](https://flashdata.dev/fr/docs/reference/realtime-and-async/reference.md#choose)
- [Choisir entre Batch et Bulk](https://flashdata.dev/fr/docs/reference/batch-and-bulk/reference.md#choose)
- [Ouvrir le générateur de workflow](https://flashdata.dev/fr/docs/guides/async-batch/reference.md#customize)

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

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

### CLI

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

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

- [Installer la CLI et s’authentifier](https://flashdata.dev/fr/docs/guides/flashdata-cli/reference.md#existing-key)

### HTTP / cURL

Gardez ce terminal ouvert pour les commandes suivantes. Les agents doivent lire la clé depuis leur stockage de secrets ou leur environnement.

#### Définir votre clé 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
```

- [Créer une clé API](https://flashdata.dev/app/api-keys)

- [Essai agent et rattachement](https://flashdata.dev/fr/docs/guides/agent-onboarding/reference.md)
- [Vérifier les tarifs](https://flashdata.dev/fr/docs/guides/credits-and-billing/reference.md)

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

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


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

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

### 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. Attendre la tâche existante

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

### CLI

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

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

Cette commande effectue une seule vérification. Répétez le GET après un court délai tant que job.status vaut pending ou processing. En cas de 429, attendez selon Retry-After dans 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
)
```

#### État terminé · exemple de réponse HTTP

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



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

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

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

Le résultat JSON par défaut redirige vers un stockage signé. Ce code décompresse le résultat conservé et accepte aussi une réponse JSON directe. Seul l’endpoint FlashData reçoit votre clé 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
)
```


- [Examiner et enregistrer les résultats de recherche](https://flashdata.dev/fr/docs/guides/google-search-guide/reference.md#results)

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

## 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 applicative | Transition |
| --- | --- |
| En attente | Enregistrez durablement l’identifiant de la tâche acceptée avant de rendre la main à l’utilisateur ou à l’agent. |
| Prête | Marquez 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écessaire | Conservez 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

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

- [Archiver et réutiliser la réponse](https://flashdata.dev/fr/docs/guides/save-results/reference.md)

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

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

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

- [Résultat de soumission inconnu](https://flashdata.dev/fr/docs/guides/agent-recovery/reference.md#recover)

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

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

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

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

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

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

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

#### PowerShell 7

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

#### Lire chaque résultat · jq

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

- [Modèle de résultat Batch](https://flashdata.dev/fr/docs/reference/batch-and-bulk/reference.md#batch-results)
- [Conserver les identifiants des enregistrements applicatifs](https://flashdata.dev/fr/docs/guides/enrich-youtube-videos/reference.md)

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

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

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

### Corps d’événement · exemple

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

- [Générer un récepteur avec le générateur de workflow](https://flashdata.dev/fr/docs/guides/async-batch/reference.md#customize)

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

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


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

## Reprendre une tâche existante

| Situation | Action |
| --- | --- |
| 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 / processing | Continuez à consulter la tâche existante. Ces états ne sont pas des échecs. |
| failed / 422 | Lisez job.error, corrigez la cause et décidez s’il faut soumettre une nouvelle opération. |
| 429 | Respectez Retry-After. Réduisez le nombre de soumissions simultanées si la capacité de tâches en attente est atteinte. |
| 404 / 409 | 404 : vérifiez l’identifiant et le compte utilisé pour la soumission. 409 : les résultats ne sont pas encore prêts. |
| 410 | Le 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. |

- [Limites de débit et consommation](https://flashdata.dev/fr/docs/guides/usage-and-limits/reference.md)
- [Reprise des exécutions CLI](https://flashdata.dev/fr/docs/guides/cli-automation/reference.md#recover)

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

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

- [Configurer le stockage et le téléchargement](https://flashdata.dev/fr/docs/guides/youtube-download-guide/reference.md)
- [Vérifier le média livré](https://flashdata.dev/fr/docs/guides/youtube-download-guide/reference.md#verify-media)

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

## 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ération | Endpoint |
| --- | --- |
| Soumettre une tâche | POST https://data.flashdata.dev/v1/queries |
| Soumettre un lot | POST https://data.flashdata.dev/v1/queries/batch |
| Lire l’état | GET https://api.flashdata.dev/v2/jobs/{id} |
| Lire les résultats | GET https://api.flashdata.dev/v2/jobs/{id}/results |

- [Protocole temps réel et asynchrone](https://flashdata.dev/fr/docs/reference/realtime-and-async/reference.md)
- [Protocole des requêtes Batch](https://flashdata.dev/fr/docs/reference/batch-and-bulk/reference.md)
- [Règles des formats de réponse](https://flashdata.dev/fr/docs/guides/response-formats/reference.md)

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

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

- [Modes de requête](https://flashdata.dev/fr/docs/reference/realtime-and-async/reference.md#choose)
- [Workflow de fichiers Bulk](https://flashdata.dev/fr/docs/guides/bulk/reference.md)

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

## 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 et schémas des sources](https://flashdata.dev/fr/docs/reference/reference.md)
