Saltar al contenido
ES
Obtener clave API
Explorar documentación

Guías

Guarda y reutiliza resultados

Guarda el resultado junto con la entrada original, los enlaces a las fuentes y el consumo. Después, pásalo a otro proceso sin repetir la consulta.

En esta página

Una vez consulta, usa el resultado en tareas

Construir un informe, recorrer su parser o dar un agente posterior paso la misma evidencia. Este flujo de trabajo ahorra una búsqueda como archivo portátil; leer que el archivo no necesita una llave FlashData ni el estado original CLI.

Lo que vas a mantener
archivo/saved-search/
  request.json original consulta y parámetros
  response.json no ha cambiado la respuesta API
  Títulos citations.ndjson, fuente URLs y snippets
  manifest.json ejecutar ID, uso, tamaños de archivo y SHA-256

Antes de empezar

Utilice una nueva carpeta de trabajo, la FlashData CLI con google_search permiso y créditos disponibles. Reutilizar un perfil autenticado o FLASHDATA_API_KEY. Bash usos de inspección jq; Windows usos PowerShell 7. Los scripts de archivo locales utilizan Python 3.10+ y su biblioteca estándar.

Continúe cuando data.accessVerified es cierto. Para los retries CLI, mantenga el mismo perfil, el usuario OS y el directorio estatal. Un agente debe cargar su credencial existente desde su tienda secreta.

Compruebe su acceso guardado
flashdata auth status --json

1. Mantenga la entrada y ahorre una respuesta

Guardar request.json debajo, luego ejecute un comando. --input usa esta solicitud exacta; mantener el archivo sin cambios después. --output salva a los API cuerpo en search.json; --json impresiones CLI metadatos. búsqueda salva es la carrera local de esta tarea ID.

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

2. Validar la respuesta guardada

Fuente de espera: google_search, status: done y una matriz de resultados. Imprima el título, enlace y fragmento de cada resultado orgánico. Los resultados reales varían; una colección de éxito vacío es diferente de una solicitud fallida o un campo perdido.

Validar y leer 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. Archivar la entrada, respuesta y citas

Guardar archive.py a continuación, ejecutelo con la ejecución ID desde el paso 1. Conserva los archivos crudos, extrae enlaces de fuente y escribe manifest.json por último con cheques de archivo y uso.Esperar completo: verdadero; el recuento de citas depende de los resultados de la búsqueda. No se hacen solicitudes de red.

Guardar archive.py

Cree archive.py junto a request.json y search.json en su carpeta de trabajo. Copia el código completo a continuación y guárdalo.

Los archivos de ejemplo Google Resultados de búsqueda. Los directorios de archivos existentes se mantienen intactos. Mantenga request.json, search.json y el funcionamiento de coincidencias hasta que el archivo se complete.

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

Crear el archivo

Corre desde la carpeta que contiene archive.py, request.json y search.json.

Construir un nuevo archivo
python3 archive.py --run-id saved-search

4. Reutiliza el archivo sin credenciales

Guardar reuse.py abajo. Copiar el archivo completo/saved-search al proceso que lo necesita, luego ejecutar este lector. Verifica cada archivo antes de imprimir la consulta original, el uso y citas. Funciona después de la revocación API-key o expiración de archivo alojado porque sólo lee su copia guardada.

Guardar reuse.py

Crear reuse.py en la carpeta de trabajo que contiene archivo/. En otra máquina, copie tanto reuse.py como el directorio completo de archivo/saved-search, manteniendo este diseño.

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

Lea el archivo guardado

Guardar reuse.py, luego ejecutar desde su carpeta. El argumento final es el camino al archivo copiado.

Lea el archivo copiado
python3 reuse.py archive/saved-search

Exportar de la revista CLI en su lugar

Si todavía tiene el perfil original de CLI y el directorio estatal, exporte la ejecución guardada a un nuevo nombre de archivo. Esto no hace ninguna consulta nueva, pero verifica el acceso en vivo primero. Un archivo de resultado existente o archivo se puede leer localmente sin ese cheque.

Exportar la ejecución final
flashdata runs show saved-search --result --output search-copy.json --json

Decide cuándo reutilizar o refrescar

archived_at registra cuando guarda los archivos, no cuando una página de origen cambió. Su aplicación decide lo reciente que debe ser la evidencia; copiar un archivo no actualiza su contenido.

TareasMedida
Recorre un parser, regenera un informe o continúa un paso de agenteReutiliza la respuesta guardada. Mantenga la fuente URLs, parámetros de consulta y uso con ella.
Producir una nueva sesión diaria o responder a una consulta cambiadaCree una nueva tarea/run ID, carpeta de trabajo y archivo. Mantenga las instantáneas más antiguas como historia.
Contar el uso en archivos derivadosContar la consulta original una vez. Copiar una respuesta o hacer otro informe no crea otro cargo.

Saber lo que expira

ResultadoQué mantenerRetención
Realtime consultaEl archivo de respuesta y la entrada originalSu copia guardada sigue su política de almacenamiento
Trabajo Async / BatchJob ID, recibo de la comunicación y resultado JSON24 horas después de la terminación
BulkManifiesto y todas las piezas NDJSON24 horas después de que todo el trabajo termine; comprobar expiresAt
YouTube DownloadEntrega JSON y medios en su destinoEntrega JSON: retención de trabajo. Medios: su cubo ciclo de vida
MCP chunk cacheEl resultado totalmente montado10 minutos; sólo se conservan los cuatro nuevos resultados grandes por API

Mantenga un pequeño sidecar en su lugar

Mantenga la respuesta original sin cambios. Guardar un pequeño sidecar con la entrada, fuente, ahorrar tiempo y uso para que un proceso posterior pueda entender lo que produjo el archivo. Mantenga la fuente URLs y video timetamps al transformar los resultados.

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
)

Guardar directamente con HTTP

Use esto en lugar de la CLI consulta en el paso 1. Guardar lo mismo request.json primero; esto ejecuta una nueva consulta utilizando Bash, cURL 7.76+ y jqReutilización FLASHDATA_API_KEY y elegir una carpeta sin search.json. Después de la validación, los mismos scripts de archivo funcionan con este resultado; elige tu propia tarea ID para --run-id.

Una salida nozero cURL significa que el resultado no está listo para su uso. Inspeccione la respuesta guardada antes de reintentar; un tiempo de conexión puede ocurrir después de que una consulta fue aceptada. Utilice el comando de validación en el paso 2.

Establezca su llave si es necesario
# 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
Guardar la respuesta 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
)

Guardar un trabajo de antecedentes existente

Utilice submission.json de la guía asinc y la misma cuenta credencial. Estos comandos recuperan el trabajo existente; no envían otra consulta. El CLI espera la terminación y maneja el resultado redireccionado. Ahorre el resultado dentro de las horas de terminación 24.

Espera, recupera y 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
)

Guardar cada parte de resultado de Bulk

Reemplazar BULK_ID con el ID en su recibo de presentación. Después de que el trabajo termine, el CLI sigue el manifiesto y guarda cada parte como un archivo NDJSON. Mantenga el manifiesto también cuando necesita contar y parte metadatos.

El archivo puede contener tanto filas exitosas como fallidas. Recuperar índices de entrada y cuenta antes de marcar la tarea completa. No reimprimir todo el archivo de entrada para recuperar una fila fallida.

Recopilar el trabajo completado
flashdata bulk results BULK_ID --output bulk-results.ndjson --timeout 30m --json

Mantenga el registro de entrega y los medios

delivery.json contiene un registro de entrega, no los bytes de vídeo o audio. Guarde su URL, tamaño y checksum junto a la tarea. Los medios de comunicación viven en su almacenamiento de destino y sigue el ciclo de vida de ese almacenamiento.

Para un destino privado, utilice las credenciales de ese proveedor o firmó URL para inspeccionar el objeto. Un resultado temporal perdido JSON no significa que su medio almacenado fue borrado.

Inspeccione un resultado de descarga guardado · jq
jq '.results[] | {file_url, file_size, md5, downloaded_bytes, output_format}' delivery.json

Assemble MCP chunks antes de ahorrar

Cuando una herramienta devuelve result_id, pedazo y next_offset, leer los pedazos restantes con get_result usando el mismo API llave. next_offset devuelto por la herramienta; los valores siguientes son los titulares de los puestos.

  1. Apéndice cada pedazo en orden offset. Siga next_offset hasta que esté null.
  2. Parse el texto unido una vez como JSON, escriba el resultado completo a su propio archivo o almacenamiento.
  3. Guardar antes de expires_at. Nuevas respuestas grandes pueden desalojar los resultados más antiguos antes del límite de minutos de 10; el caché mantiene cuatro por tecla API.
MCP tools/call arguments
{
  "name": "get_result",
  "arguments": {
    "result_id": "RESULT_ID_FROM_TOOL",
    "offset": 16000
  }
}

Problemas de ahorro y recuperación

ProblemaArreglos
Archivo de salida ya existeInspeccione primero. Para una ejecución CLI completada, use ejecuta show con un nuevo nombre de archivo de salida en lugar de enviar otra consulta.
CLI no puede encontrar la carreraUtilice el usuario original OS, perfil y directorio estatal. Si mantiene un trabajo remoto ID, recupere ese trabajo directamente.
401 / 403 en reutilizaciónEjecutar flashdata auth status --json y restaurar el acceso válido. Un archivo local ya guardado todavía se puede leer sin acceso API.
409 / 410409: espere el trabajo existente. 410: use su copia guardada; el resultado temporal ha expirado.
Error de disco después de una consultaMantenga la carrera ID o trabajo ID. Arreglar el almacenamiento y recuperar el trabajo existente antes de considerar una nueva presentación.
El archivo no tiene manifiesto o un chequesum fallaRestaurar o copiar los archivos originales de nuevo. Mantenga un archivo incompleto para la inspección; reconstruir el archivo no requiere una nueva consulta.
MCP · result_unavailableResultado de comprobación ID, offset, tecla API y caducidad. Utilice una copia guardada si el caché ha expirado; no se bucle por repetir una consulta pagada.