# Enregistrer et réutiliser les résultats

Conservez un résultat avec ses paramètres d’origine, ses liens sources et sa consommation, puis transmettez-le à un autre processus sans nouvelle requête.

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

<a id="realtime"></a>

## Interroger une fois, réutiliser le résultat dans plusieurs tâches

Créez un rapport, relancez votre parseur ou fournissez les mêmes sources à une étape ultérieure de l’agent. Ce workflow conserve une recherche dans une archive portable ; sa lecture ne nécessite ni clé FlashData ni état CLI d’origine.

### Ce que vous conserverez

```text
archive/saved-search/
  request.json        requête et paramètres d’origine
  response.json       réponse API inchangée
  citations.ndjson    titres, URL sources et extraits
  manifest.json       identifiant d’exécution, consommation, tailles et SHA-256
```

- [Vous avez déjà un résultat asynchrone ?](https://flashdata.dev/fr/docs/guides/save-results/reference.md#jobs)
- [Enregistrer un jeu de données Bulk](https://flashdata.dev/fr/docs/guides/save-results/reference.md#bulk)
- [Conserver les médias téléchargés](https://flashdata.dev/fr/docs/guides/save-results/reference.md#media)

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

## Avant de commencer

Utilisez un nouveau dossier de travail, la CLI FlashData avec la permission google_search et des crédits disponibles. Réutilisez un profil authentifié ou FLASHDATA_API_KEY. Les vérifications Bash utilisent jq ; sous Windows, utilisez PowerShell 7. Les scripts d’archivage local utilisent Python 3.10+ et sa bibliothèque standard.

Continuez lorsque data.accessVerified vaut true. Pour les nouvelles tentatives CLI, conservez le profil, l’utilisateur du système et le répertoire d’état d’origine. Un agent doit charger ses identifiants existants depuis son stockage de secrets.

### Vérifier l’accès enregistré

```bash
flashdata auth status --json
```

- [Installer la CLI](https://flashdata.dev/fr/docs/guides/flashdata-cli/reference.md#install)
- [Créer une clé API](https://flashdata.dev/app/api-keys)
- [Utiliser HTTP](https://flashdata.dev/fr/docs/guides/save-results/reference.md#http)

<a id="save"></a>

## 1. Conserver les paramètres et enregistrer une réponse

Enregistrez request.json ci-dessous, puis exécutez une seule commande. --input utilise exactement cette requête ; conservez ensuite le fichier sans le modifier. --output enregistre le corps API dans search.json ; --json affiche les métadonnées CLI. saved-search est l’identifiant d’exécution local de cette tâche.

### request.json

```json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}
```

### Bash

#### Lancer une recherche

```bash
flashdata query --input request.json \
  --run-id saved-search --output search.json --json
```


### PowerShell

#### Lancer une recherche

```powershell
flashdata query --input request.json `
  --run-id saved-search --output search.json --json
```



<a id="inspect"></a>

## 2. Valider la réponse enregistrée

Le résultat attendu contient source: google_search, status: done et un tableau results. Affichez title, link et snippet pour chaque résultat organique. Les résultats réels varient ; une collection vide dans une réponse réussie se distingue d’une requête en échec ou d’un champ absent.

### Bash / jq

#### Valider et lire search.json

```bash
jq -e '.source == "google_search" and .status == "done"
  and (.results | type == "array")
  and all(.results[]; (.organic | type == "array"))' search.json > /dev/null &&
jq -c '.results[] | .organic[] | {title, link, snippet}' search.json
```


### PowerShell

#### Valider et lire search.json

```powershell
$result = Get-Content -Raw -LiteralPath search.json | ConvertFrom-Json
if ($result.source -ne 'google_search' -or $result.status -ne 'done' -or
    -not ($result.results -is [array])) {
  throw 'Inspect search.json before treating the task as complete.'
}
foreach ($page in $result.results) {
  if (-not ($page.organic -is [array])) { throw 'Missing organic results array.' }
  $page.organic | Select-Object title, link, snippet
}
```



<a id="record"></a>

## 3. Archiver les paramètres, la réponse et les citations

Enregistrez archive.py ci-dessous, puis exécutez-le avec l’identifiant d’exécution de l’étape 1. Il conserve les fichiers bruts, extrait les liens sources et écrit manifest.json en dernier avec les sommes de contrôle et la consommation. Le résultat attendu indique complete: true ; le nombre de citations dépend des résultats de recherche. Aucune requête réseau n’est effectuée.


<a id="archive-script"></a>

### Enregistrer archive.py

Créez archive.py à côté de request.json et search.json dans le dossier de travail. Copiez-y le code complet ci-dessous et enregistrez-le.

Cet exemple archive des résultats Google Search. Les répertoires d’archive existants sont conservés intacts. Gardez request.json, search.json et l’exécution correspondante ensemble jusqu’à la fin de l’archivage.

#### archive.py

```python
# archive.py — Python 3.10+, standard library only; no network requests.
import argparse
import hashlib
import json
import re
from datetime import datetime, timezone
from pathlib import Path
from urllib.parse import urlsplit

parser = argparse.ArgumentParser()
parser.add_argument('--run-id', required=True)
args = parser.parse_args()
if not re.fullmatch(r'[A-Za-z0-9_-]+', args.run_id):
    raise ValueError('Use the CLI run ID from this task.')
request_bytes = Path('request.json').read_bytes()
result_bytes = Path('search.json').read_bytes()
request = json.loads(request_bytes.decode('utf-8-sig'))
result = json.loads(result_bytes.decode('utf-8-sig'))
if (request.get('source') != 'google_search' or result.get('source') != request['source']
        or result.get('status') not in ['done', 'completed']
        or not isinstance(result.get('results'), list)):
    raise ValueError('Inspect the request and result before archiving.')
citations = []
for page in result['results']:
    if not isinstance(page, dict) or not isinstance(page.get('organic'), list):
        raise ValueError('Expected an organic results array, including when it is empty.')
    for item in page['organic']:
        if not isinstance(item, dict) or not isinstance(item.get('link'), str):
            raise ValueError('A result is missing its source URL.')
        url = urlsplit(item['link'])
        if url.scheme not in ['http', 'https'] or not url.netloc:
            raise ValueError('Inspect an unexpected source URL.')
        citations.append({key: item.get(key, '') for key in ['title', 'link', 'snippet']})
files = {'request.json': request_bytes, 'response.json': result_bytes,
         'citations.ndjson': ''.join(json.dumps(row, ensure_ascii=False) + '\n'
                                    for row in citations).encode('utf-8')}
manifest = {'version': 1, 'run_id': args.run_id, 'source': request['source'],
            'archived_at': datetime.now(timezone.utc).isoformat(),
            'usage': result.get('usage'), 'citation_count': len(citations),
            'files': {name: {'bytes': len(data), 'sha256': hashlib.sha256(data).hexdigest()}
                      for name, data in files.items()}}
folder = Path('archive') / args.run_id
folder.mkdir(parents=True)  # Existing archives are preserved. Choose a new run ID for new work.
for name, data in files.items():
    with (folder / name).open('xb') as output:
        output.write(data)
# Write the manifest last. Without it, the archive is incomplete.
with (folder / 'manifest.json').open('x', encoding='utf-8') as output:
    json.dump(manifest, output, ensure_ascii=False, indent=2)
print(json.dumps({'archive': str(folder), 'citations': len(citations), 'complete': True}))
```


<a id="run-archive"></a>

### Créer l’archive

Lancez la commande depuis le dossier contenant archive.py, request.json et search.json.

#### Bash

##### Créer une nouvelle archive

```bash
python3 archive.py --run-id saved-search
```


#### PowerShell 7

##### Créer une nouvelle archive

```powershell
python archive.py --run-id saved-search
```



<a id="reuse"></a>

## 4. Réutiliser l’archive sans identifiants

Enregistrez reuse.py ci-dessous. Copiez le dossier archive/saved-search complet vers le processus qui en a besoin, puis lancez ce lecteur. Il vérifie chaque fichier avant d’afficher la requête d’origine, la consommation et les citations. Il fonctionne après la révocation de la clé API ou l’expiration du résultat hébergé, car il lit uniquement votre copie enregistrée.


<a id="reuse-script"></a>

### Enregistrer reuse.py

Créez reuse.py dans le dossier de travail contenant archive/. Sur une autre machine, copiez reuse.py et le répertoire archive/saved-search complet en conservant cette organisation.

#### reuse.py

```python
# reuse.py — run without a FlashData key or CLI.
import hashlib
import json
import sys
from pathlib import Path

folder = Path(sys.argv[1])
manifest = json.loads((folder / 'manifest.json').read_text(encoding='utf-8'))
expected = {'request.json', 'response.json', 'citations.ndjson'}
if manifest.get('version') != 1 or set(manifest.get('files', {})) != expected:
    raise ValueError('Unknown or incomplete archive manifest.')
files = {}
for name in sorted(expected):
    data = (folder / name).read_bytes()
    record = manifest['files'][name]
    if len(data) != record['bytes'] or hashlib.sha256(data).hexdigest() != record['sha256']:
        raise ValueError('Archive changed or was not fully copied: ' + name)
    files[name] = data
request = json.loads(files['request.json'].decode('utf-8-sig'))
citations = [json.loads(line) for line in files['citations.ndjson'].decode('utf-8').splitlines()]
if len(citations) != manifest['citation_count']:
    raise ValueError('Citation count does not match the manifest.')
print(json.dumps({'run_id': manifest['run_id'], 'query': request['query'],
                  'archived_at': manifest['archived_at'], 'usage': manifest['usage'],
                  'citations': citations}, indent=2))
```


<a id="read-archive"></a>

### Lire l’archive enregistrée

Enregistrez reuse.py, puis lancez la commande depuis son dossier. Le dernier argument est le chemin de l’archive copiée.

#### Bash

##### Lire l’archive copiée

```bash
python3 reuse.py archive/saved-search
```


#### PowerShell 7

##### Lire l’archive copiée

```powershell
python reuse.py archive/saved-search
```



<a id="cli-cache"></a>

### Exporter depuis le journal CLI

Si vous disposez encore du profil CLI et du répertoire d’état d’origine, exportez l’exécution enregistrée sous un nouveau nom de fichier. Cette opération ne lance aucune nouvelle requête, mais vérifie d’abord l’accès actuel. Un fichier de résultat ou une archive déjà enregistrés peuvent être lus localement sans cette vérification.

#### Exporter l’exécution terminée

```bash
flashdata runs show saved-search --result --output search-copy.json --json
```


<a id="freshness"></a>

## Choisir entre réutiliser et actualiser

archived_at indique quand vous avez enregistré les fichiers, pas quand une page source a changé. Votre application détermine la fraîcheur requise des sources ; copier un fichier n’actualise pas son contenu.

| Tâche | Action |
| --- | --- |
| Relancer un parseur, régénérer un rapport ou poursuivre une étape d’agent | Réutilisez la réponse enregistrée. Conservez avec elle les URL sources, les paramètres de requête et la consommation. |
| Créer une nouvelle synthèse quotidienne ou répondre à une requête modifiée | Créez un nouvel identifiant de tâche ou d’exécution, un nouveau dossier et une nouvelle archive. Conservez les instantanés précédents comme historique. |
| Compter la consommation entre fichiers dérivés | Comptez la requête d’origine une seule fois. Copier une réponse ou produire un autre rapport ne crée pas de frais supplémentaires. |

- [Tâches récurrentes et identifiants d’exécution](https://flashdata.dev/fr/docs/guides/recurring-tasks/reference.md)
- [Formater des résultats existants](https://flashdata.dev/fr/docs/guides/response-formats/reference.md#completed-results)

<a id="retention"></a>

## Savoir ce qui expire

| Résultat | À conserver | Conservation |
| --- | --- | --- |
| Requête en temps réel | Le fichier de réponse et les paramètres d’origine | Votre copie suit votre politique de stockage |
| Tâche asynchrone / Batch | Identifiant de tâche, reçu de soumission et résultat JSON | 24 heures après la fin de la tâche |
| Bulk | Manifeste et toutes les parties NDJSON | 24 heures après la fin de toute la tâche ; vérifiez expiresAt |
| YouTube Download | JSON de livraison et médias dans votre destination | JSON de livraison : conservation de la tâche. Médias : cycle de vie de votre bucket |
| Cache des fragments MCP | Le résultat entièrement reconstitué | 10 minutes ; seuls les quatre résultats volumineux les plus récents sont conservés par clé API |


<a id="sidecar"></a>

## Conserver plutôt un petit fichier de métadonnées

Gardez la réponse d’origine inchangée. Enregistrez un petit fichier complémentaire avec les paramètres, la source, l’heure d’enregistrement et la consommation pour qu’un autre processus comprenne l’origine du résultat. Conservez les URL sources et les repères temporels des vidéos lors des transformations.

### Bash / jq · search-record.json

```bash
(
set -euC
jq --arg run_id 'saved-search' --slurpfile request request.json \
  '{run_id: $run_id, source, input: $request[0],
    saved_at: (now | todateiso8601), result_file: "search.json", usage}' \
  search.json > search-record.json
cat search-record.json
)
```


<a id="http"></a>

## Enregistrer directement par HTTP

Utilisez cette méthode à la place de la requête CLI de l’étape 1. Enregistrez d’abord le même request.json ; cette commande lance une nouvelle requête avec Bash, cURL 7.76+ et jq. Réutilisez FLASHDATA_API_KEY et choisissez un dossier sans search.json. Après validation, les mêmes scripts d’archivage fonctionnent avec ce résultat ; choisissez votre propre identifiant de tâche pour --run-id.

Un code de sortie cURL non nul signifie que le résultat n’est pas prêt à être utilisé. Examinez la réponse enregistrée avant de réessayer ; un délai de connexion peut expirer après l’acceptation de la requête. Utilisez la commande de validation de l’étape 2.

### Définir votre clé si nécessaire

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

### Enregistrer la réponse API

```bash
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test -f request.json
curl --fail-with-body --silent --show-error --max-time 120 \
  --request POST 'https://data.flashdata.dev/v1/queries/realtime' \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --header 'Content-Type: application/json' --header 'Accept: application/json' \
  --data-binary @request.json > search.json
jq . search.json
)
```


<a id="jobs"></a>

## Enregistrer une tâche en arrière-plan existante

Utilisez submission.json du guide asynchrone et les mêmes identifiants de compte. Ces commandes récupèrent des opérations existantes sans soumettre de nouvelle requête. La CLI attend la fin de la tâche et gère la redirection du résultat. Enregistrez ce résultat dans les 24 heures suivant la fin de la tâche.

### CLI + jq

#### Attendre, récupérer et enregistrer

```bash
(
set -euC
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs wait "$JOB_ID" --json
flashdata jobs result "$JOB_ID" --output job-result.json --json
jq '{source, status, results, usage}' job-result.json
)
```


### HTTP / cURL

La vérification s’arrête si la tâche n’est pas completed. Si elle est encore en file d’attente ou en cours, patientez puis relancez ce code de lecture seule ; examinez plutôt l’erreur d’une tâche en échec. Une réponse 302 est suivie sans transmettre votre clé API au stockage. La réponse temporaire est validée avant la création de job-result.json.

#### Bash · cURL + jq

```bash
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e job-result.json || { echo 'Choose a new output filename.' >&2; exit 1; }
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
printf '%s' "$JOB_ID" | grep -Eq '^[A-Za-z0-9_-]+$'
SOURCE=$(jq -er '(.submission // .).source' submission.json)
API="https://api.flashdata.dev/v2/jobs/$JOB_ID"
curl --fail-with-body --silent --show-error \
  --max-time 30 --header "X-API-Key: $FLASHDATA_API_KEY" "$API" >| job-status.json
jq -e --arg id "$JOB_ID" --arg source "$SOURCE" \
  '.job.id == $id and .job.source == $source and .job.status == "completed"' job-status.json >/dev/null
STATUS=$(curl --silent --show-error \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --max-time 120 --dump-header result-headers.txt --output job-result.pending \
  --write-out '%{http_code}' "$API/results")
case "$STATUS" in
  200) ;;
  302)
    LOCATION=$(awk 'tolower($1) == "location:" { sub(/\r$/, "", $2); print $2 }' result-headers.txt)
    # No FlashData API key on the signed storage request.
    curl --fail-with-body --silent --show-error --compressed --max-time 120 \
      --proto '=https' --output job-result.pending "$LOCATION" ;;
  *) echo "HTTP $STATUS: inspect job-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")' job-result.pending >/dev/null
cat job-result.pending > job-result.json
jq '{source, status, results, usage}' job-result.json
)
```


- [Reprendre une tâche asynchrone existante](https://flashdata.dev/fr/docs/guides/async-batch/reference.md#resume)
- [Spécification de la réponse de résultat](https://flashdata.dev/fr/docs/reference/realtime-and-async/reference.md#results)
- [Récupérer en Markdown](https://flashdata.dev/fr/docs/guides/response-formats/reference.md#completed-results)

<a id="bulk"></a>

## Enregistrer toutes les parties d’un résultat Bulk

Remplacez BULK_ID par l’identifiant du reçu de soumission. Une fois la tâche terminée, la CLI suit le manifeste et regroupe toutes les parties dans un fichier NDJSON. Conservez aussi le manifeste si vous avez besoin des compteurs et des métadonnées des parties.

Le fichier peut contenir des lignes réussies et des lignes en échec. Rapprochez les index d’entrée et les compteurs avant de déclarer toute la tâche terminée. Ne relancez pas tout le fichier d’entrée pour récupérer une seule ligne en échec.

### Collecter la tâche terminée

```bash
flashdata bulk results BULK_ID --output bulk-results.ndjson --timeout 30m --json
```

- [Vérifier chaque entrée avant l’importation](https://flashdata.dev/fr/docs/guides/bulk/reference.md#audit)
- [Manifeste, compteurs et NDJSON](https://flashdata.dev/fr/docs/reference/bulk-processing/reference.md#downloadBulkJobManifest)

<a id="media"></a>

## Conserver le résultat de livraison et le média

delivery.json contient un enregistrement de livraison, pas les octets vidéo ou audio. Conservez son URL, sa taille et sa somme de contrôle avec la tâche. Le média reste dans votre stockage de destination et suit son cycle de vie.

Pour une destination privée, utilisez les identifiants du fournisseur ou une URL signée pour examiner l’objet. L’absence du résultat JSON temporaire ne signifie pas que le média stocké a été supprimé.

### Examiner un résultat Download enregistré · jq

```bash
jq '.results[] | {file_url, file_size, md5, downloaded_bytes, output_format}' delivery.json
```

- [Vérifier la taille, la somme de contrôle et le média](https://flashdata.dev/fr/docs/guides/youtube-download-guide/reference.md#verify-media)

<a id="mcp"></a>

## Assembler les fragments MCP avant l’enregistrement

Quand un outil renvoie result_id, chunk et next_offset, lisez les fragments suivants avec get_result en utilisant la même clé API. Utilisez exactement la valeur next_offset renvoyée par l’outil ; les valeurs ci-dessous sont des exemples à remplacer.

1. Ajoutez chaque fragment dans l’ordre des offsets. Suivez next_offset jusqu’à ce qu’il vaille null.
2. Analysez une seule fois le texte reconstitué comme du JSON, puis écrivez le résultat complet dans votre fichier ou votre stockage.
3. Enregistrez avant expires_at. De nouvelles réponses volumineuses peuvent évincer d’anciens résultats avant la limite de 10 minutes ; le cache en conserve quatre par clé API.

### Arguments MCP tools/call

```json
{
  "name": "get_result",
  "arguments": {
    "result_id": "RESULT_ID_FROM_TOOL",
    "offset": 16000
  }
}
```

- [Client MCP exécutable avec collecte des fragments](https://flashdata.dev/fr/docs/guides/mcp-custom-client/reference.md)

<a id="recovery"></a>

## Résoudre les problèmes d’enregistrement et de récupération

| Problème | Correction |
| --- | --- |
| Le fichier de sortie existe déjà | Examinez-le d’abord. Pour une exécution CLI terminée, utilisez runs show avec un nouveau nom de fichier de sortie au lieu de soumettre une autre requête. |
| La CLI ne trouve pas l’exécution | Utilisez l’utilisateur du système, le profil et le répertoire d’état d’origine. Si vous avez conservé un identifiant de tâche distante, récupérez cette tâche directement. |
| 401 / 403 lors de la réutilisation | Exécutez flashdata auth status --json et rétablissez un accès valide. Un fichier local déjà enregistré reste lisible sans accès API. |
| 409 / 410 | 409 : attendez la tâche existante. 410 : utilisez votre copie enregistrée ; le résultat temporaire a expiré. |
| Erreur disque après une requête | Conservez l’identifiant d’exécution ou de tâche. Corrigez le stockage et récupérez les opérations existantes avant d’envisager une nouvelle soumission. |
| L’archive n’a pas de manifeste ou une somme de contrôle est incorrecte | Restaurez les fichiers d’origine ou copiez-les à nouveau. Conservez l’archive incomplète pour l’examiner ; reconstruire l’archive ne nécessite pas de nouvelle requête. |
| MCP · result_unavailable | Vérifiez l’identifiant du résultat, l’offset, la clé API et l’expiration. Si le cache a expiré, utilisez une copie enregistrée ; ne répétez pas en boucle une requête payante. |

- [Commandes de reprise CLI](https://flashdata.dev/fr/docs/guides/cli-automation/reference.md#recover)
- [Dépannage des requêtes](https://flashdata.dev/fr/docs/guides/troubleshooting/reference.md)
