Salta al contenuto
IT
Ottieni la chiave API
Sfoglia la documentazione

Guide

Salvare e riutilizzare i risultati

Mantenere un risultato con il suo ingresso originale, i link di origine e l'uso, quindi consegnarlo ad un altro processo senza un'altra query.

In questa pagina

Fare una domanda una volta, utilizzare il risultato attraverso le attività

Costruisci un rapporto, riscatta il tuo parser o fai un agente dopo passo le stesse prove. Questo flusso di lavoro salva una ricerca come archivio portatile; la lettura che l'archivio non ha bisogno né di una chiave FlashData né dello stato CLI originale.

Ciò che manterrà
archive/saved-search/
  request.json query originale e parametri
  response.json invariata risposta API
  Titoli citations.ndjson, fonte URLs e snippets
  manifest.json eseguire ID, utilizzo, formati di file e SHA-256

Prima di iniziare

Utilizzare una nuova cartella di lavoro, il FlashData CLI con il permesso google_search e i crediti disponibili. Riutilizzare un profilo autenticato o FLASHDATA_API_KEY. L'ispezione Bash utilizza jq; Windows utilizza PowerShell 7. Gli script di archivio locali utilizzano Python 3.10+ e la sua libreria standard.

Continuare quando data.accessVerified è true. Per le retries CLI, mantenere lo stesso profilo, utente OS e directory di stato. Un agente dovrebbe caricare le sue credenziali esistenti dal suo negozio segreto.

Controlla l'accesso salvato
flashdata auth status --json

1. Mantenere l'ingresso e salvare una risposta

Salva request.json sotto, quindi eseguire un comando. --input utilizza questa richiesta esatta; mantenere il file invariato in seguito. --output salva il API corpo in search.json; --json stampe CLI metadati. la ricerca salvata è l'esecuzione locale di questo compito ID.

request.json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}
Esegui una ricerca
flashdata query --input request.json \
  --run-id saved-search --output search.json --json

2. Convalida la risposta salvata

Fonte prevista: google_search, status: done e un array di risultati. Stampare il titolo di ogni risultato organico, link e snippet. I risultati effettivi variano; una collezione di successo vuota è diversa da una richiesta fallita o da un campo mancante.

Convalida e leggi search.json
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

3. Archivia l'ingresso, la risposta e le citazioni

Salvare archive.py di seguito, quindi eseguire con il run ID dal passo 1. Esso conserva i file grezzi, estrae i link di origine e scrive manifest.json ultimo con i checksum di file e l'utilizzo. Aspettatevi completa: true; il conteggio citazione dipende dai risultati di ricerca. Non vengono effettuate richieste di rete.

Salvare archive.py

Creare archive.py accanto a request.json e search.json nella cartella di lavoro. Copia il codice completo qui sotto e salvalo.

L'esempio archivia i risultati della ricerca Google. Le attuali directory archivistiche sono mantenute intatte. Mantenere request.json, search.json e l'esecuzione corrispondente insieme fino a quando l'archiviazione non si completa.

archive.py
# 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}))

Creare l'archivio

Eseguire dalla cartella contenente archive.py, request.json e search.json.

Costruire un nuovo archivio
python3 archive.py --run-id saved-search

4. Riutilizzare l'archivio senza credenziali

Salva reuse.py qui sotto. Copiare la cartella archive/saved-search completa al processo che ne ha bisogno, quindi eseguire questo lettore. Verifica ogni file prima di stampare la query originale, l'uso e le citazioni. Funziona dopo la revoca di API-chiave o la scadenza del risultato ospitato perché legge solo la copia salvata.

Salvare reuse.py

Creare reuse.py nella cartella di lavoro contenente archive/. Su un'altra macchina, copiare sia reuse.py che la directory archive/saved-search completa, mantenendo questo layout.

reuse.py
# 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))

Leggi l'archivio salvato

Salvare reuse.py, quindi eseguire dalla sua cartella. L'argomento finale è il percorso dell'archivio copiato.

Leggi l'archivio copiato
python3 reuse.py archive/saved-search

Esportazione dalla rivista CLI invece

Se hai ancora il profilo e la directory di stato CLI originale, esporta l'esecuzione salvata in un nuovo nome di file. Questo non rende nessuna nuova query, ma verifica prima l'accesso dal vivo. Un file di risultato esistente o archivio può essere letto localmente senza tale controllo.

Esportare la corsa completa
flashdata runs show saved-search --result --output search-copy.json --json

Decidi quando riutilizzare o rinfrescare

archived_at registra quando hai salvato i file, non quando una pagina di origine è cambiata. La vostra domanda decide quanto le prove devono essere recenti; copiare un file non aggiorna il suo contenuto.

CompitiAzione
Recuperare un parser, rigenerare un rapporto o continuare un passo agenteRiutilizzare la risposta salvata. Mantenere la fonte URLs, i parametri di query e l'utilizzo con esso.
Produrre un nuovo briefing giornaliero o rispondere a una domanda cambiataCreare una nuova task/run ID, cartella di lavoro e archivio. Tenere le istantanee più vecchie come storia.
Conta l'uso attraverso i file derivatiContare la query originale una volta. Copiare una risposta o fare un altro rapporto non crea un'altra carica.

Sapere che cosa scade

RisultatoCosa tenereRetenzione
Domanda RealtimeIl file di risposta e l'ingresso originaleLa copia salvata segue la politica di archiviazione
Lavoro Async / BatchJob ID, ricevuta di presentazione e risultato JSON24 ore dopo il completamento
BulkManifest e tutte le parti NDJSON24 ore dopo l'intero lavoro completato; controllare expiresAt
YouTube DownloadConsegna JSON e media nella tua destinazioneConsegna JSON: ritenzione di lavoro. Media: il tuo ciclo di vita del secchio
MCP chunk cacheIl risultato completamente montatoMinuti 10; solo i quattro nuovi risultati grandi per chiave API sono mantenuti

Tenere un piccolo sidecar invece

Mantenere la risposta originale invariata. Salvare una piccola sidecar con l'ingresso, la fonte, risparmiare tempo e l'uso in modo che un processo successivo possa capire ciò che ha prodotto il file. Tenere la sorgente URLs e i timestamp video quando si trasformano i risultati.

Bash / jq · search-record.json
(
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
)

Salvare direttamente con HTTP

Utilizzare questo invece della query CLI nel passo 1. Salvare la stessa request.json prima; questo viene eseguito una nuova query utilizzando Bash, cURL 7.76+ e jq. Riutilizzare FLASHDATA_API_KEY e scegliere una cartella senza search.json. Dopo la convalida, gli stessi script di archivio funzionano con questo risultato; scegli il tuo compito ID per --run-id.

Un'uscita nonzero cURL significa che il risultato non è pronto per l'uso. Ispezionare la risposta salvata prima di riprovare; un timeout di connessione può accadere dopo che una query è stata accettata. Utilizzare il comando di validazione nel passo 2.

Impostare la chiave se necessario
# 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
Salvare la risposta API
(
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
)

Salvare un lavoro di sfondo esistente

Utilizzare submission.json dalla guida asincrona e le stesse credenziali account. Questi comandi recuperano il lavoro esistente; non inviano un'altra query. La CLI aspetta il completamento e gestisce il risultato reindirizzare. Salvare il risultato entro le ore di completamento 24.

Aspetta, recupera e salva
(
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
)

Salva ogni parte del risultato Bulk

Sostituisci BULK_ID con ID nella ricevuta di presentazione. Dopo il completamento del lavoro, il CLI segue il manifesto e salva ogni parte come un file NDJSON. Tenere il manifesto anche quando avete bisogno di conteggi e metadati di parte.

Il file può contenere file sia di successo che di fallimento. Indici e conteggi di ingresso riconciliabili prima di marcare l'intero compito completo. Non eseguire l'intero file di input per recuperare una riga fallita.

Raccogliere il lavoro completato
flashdata bulk results BULK_ID --output bulk-results.ndjson --timeout 30m --json

Mantenere il record di consegna e i media

delivery.json contiene un record di consegna, non i byte video o audio. Salvare il suo URL, dimensione e checksum insieme all'attività. I media vivono nella vostra destinazione di stoccaggio e seguono il ciclo di vita di quel deposito.

Per una destinazione privata, utilizzare le credenziali del fornitore o firmato URL per ispezionare l'oggetto. Un risultato temporaneo mancante JSON non significa che il supporto memorizzato è stato cancellato.

Ispezione di un risultato di download salvato · jq
jq '.results[] | {file_url, file_size, md5, downloaded_bytes, output_format}' delivery.json

Assemblare i pezzi MCP prima di salvare

Quando uno strumento restituisce result_id, chunk e next_offset, leggere i pezzi rimanenti con get_result utilizzando la stessa chiave API. Utilizzare l'esatto next_offset restituito dallo strumento; i valori qui sotto sono segnaposto.

  1. Appendere ogni pezzo in ordine compensato. Seguire next_offset fino a quando non è null.
  2. Parsare il testo unito una volta come JSON, quindi scrivere il risultato completo al proprio file o archiviazione.
  3. Salvare prima di expires_at. Le nuove risposte di grandi dimensioni possono sfrattare i risultati precedenti prima del limite 10-minuto; la cache mantiene quattro per chiave API.
Argomenti MCP tools/call
{
  "name": "get_result",
  "arguments": {
    "result_id": "RESULT_ID_FROM_TOOL",
    "offset": 16000
  }
}

Risolvere i problemi di salvataggio e di recupero

ProblematicheRisolto
Il file di output esiste giàIspezionare prima. Per un'esecuzione CLI completata, utilizzare runs show con un nuovo nome file di output invece di inviare un'altra query.
CLI non riesce a trovare la corsaUtilizzare la directory OS originale utente, profilo e stato. Se hai mantenuto un lavoro remoto ID, recuperalo direttamente.
401 / 403 sul riutilizzoEseguire flashdata auth status --json e ripristinare l'accesso valido. Un file locale già salvato può ancora essere letto senza accesso API.
409 / 410409: attendere il lavoro esistente. 410: utilizzare la copia salvata; il risultato temporaneo è scaduto.
Errore del disco dopo una queryMantenere l'esecuzione ID o il lavoro ID. Fissare lo storage e recuperare il lavoro esistente prima di prendere in considerazione una nuova presentazione.
L'archivio non ha manifesto o un checksum non riesceRipristinare o copiare nuovamente i file originali. Mantenere un archivio incompleto per l'ispezione; ricostruire l'archivio non richiede una nuova query.
MCP · result_unavailableRisultato di controllo ID, offset, chiave API e scadenza. Utilizzare una copia salvata se la cache è scaduta; non loop ripetendo una query pagata.