Parcourir la documentation
Guides
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.
Sur cette page
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.
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-256Avant 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.
flashdata auth status --json1. 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.
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
}
}flashdata query --input request.json \
--run-id saved-search --output search.json --jsonflashdata query --input request.json `
--run-id saved-search --output search.json --json2. 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.
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$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
}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.
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 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}))Créer l’archive
Lancez la commande depuis le dossier contenant archive.py, request.json et search.json.
python3 archive.py --run-id saved-searchpython archive.py --run-id saved-search4. 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.
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 — 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))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.
python3 reuse.py archive/saved-searchpython reuse.py archive/saved-searchExporter 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.
flashdata runs show saved-search --result --output search-copy.json --jsonChoisir 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. |
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 |
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.
(
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
)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.
# 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(
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
)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.
(
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
)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.
(
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
)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.
flashdata bulk results BULK_ID --output bulk-results.ndjson --timeout 30m --jsonConserver 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é.
jq '.results[] | {file_url, file_size, md5, downloaded_bytes, output_format}' delivery.jsonAssembler 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.
- Ajoutez chaque fragment dans l’ordre des offsets. Suivez next_offset jusqu’à ce qu’il vaille null.
- Analysez une seule fois le texte reconstitué comme du JSON, puis écrivez le résultat complet dans votre fichier ou votre stockage.
- 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.
{
"name": "get_result",
"arguments": {
"result_id": "RESULT_ID_FROM_TOOL",
"offset": 16000
}
}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. |