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

Referencia canónica: https://flashdata.dev/es/docs/guides/save-results
Revisado: 2026-11-05 por FlashData

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

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

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

- [¿Ya tiene un resultado asinc?](https://flashdata.dev/es/docs/guides/save-results/reference.md#jobs)
- [Guardar un conjunto de datos Bulk](https://flashdata.dev/es/docs/guides/save-results/reference.md#bulk)
- [Mantenga los medios descargados](https://flashdata.dev/es/docs/guides/save-results/reference.md#media)

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

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

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

- [Instalar el CLI](https://flashdata.dev/es/docs/guides/flashdata-cli/reference.md#install)
- [Crear una clave API](https://flashdata.dev/app/api-keys)
- [Use HTTP en su lugar](https://flashdata.dev/es/docs/guides/save-results/reference.md#http)

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

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

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

### Bash

#### Ejecutar una búsqueda

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


### PowerShell

#### Ejecutar una búsqueda

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



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

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

### Bash / jq

#### Validar y leer 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

#### Validar y leer 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. 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.


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

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

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

### Crear el archivo

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

#### Bash

##### Construir un nuevo archivo

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


#### PowerShell 7

##### Construir un nuevo archivo

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



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

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


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

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

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

### Lea el archivo guardado

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

#### Bash

##### Lea el archivo copiado

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


#### PowerShell 7

##### Lea el archivo copiado

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



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

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

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


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

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

| Tareas | Medida |
| --- | --- |
| Recorre un parser, regenera un informe o continúa un paso de agente | Reutiliza 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 cambiada | Cree una nueva tarea/run ID, carpeta de trabajo y archivo. Mantenga las instantáneas más antiguas como historia. |
| Contar el uso en archivos derivados | Contar la consulta original una vez. Copiar una respuesta o hacer otro informe no crea otro cargo. |

- [Recurrir tareas y ejecutar IDs](https://flashdata.dev/es/docs/guides/recurring-tasks/reference.md)
- [Formato de los resultados existentes](https://flashdata.dev/es/docs/guides/response-formats/reference.md#completed-results)

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

## Saber lo que expira

| Resultado | Qué mantener | Retención |
| --- | --- | --- |
| Realtime consulta | El archivo de respuesta y la entrada original | Su copia guardada sigue su política de almacenamiento |
| Trabajo Async / Batch | Job ID, recibo de la comunicación y resultado JSON | 24 horas después de la terminación |
| Bulk | Manifiesto y todas las piezas NDJSON | 24 horas después de que todo el trabajo termine; comprobar expiresAt |
| YouTube Download | Entrega JSON y medios en su destino | Entrega JSON: retención de trabajo. Medios: su cubo ciclo de vida |
| MCP chunk cache | El resultado totalmente montado | 10 minutos; sólo se conservan los cuatro nuevos resultados grandes por API |


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

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

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

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

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

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

### CLI + jq

#### Espera, recupera y salva

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

El control de estado se detiene si el trabajo no se completa. Si sigue siendo apagado o corriendo, espere y ejecute este solo fragmento de lectura de nuevo; inspeccione un trabajo fallido en su lugar. Un 302 se descarga sin enviar su tecla API. La respuesta temporal se valida antes de que se cree 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
)
```


- [Reanudar un trabajo asinc existente](https://flashdata.dev/es/docs/guides/async-batch/reference.md#resume)
- [Contrato de respuesta a los resultados](https://flashdata.dev/es/docs/reference/realtime-and-async/reference.md#results)
- [Retire como Markdown](https://flashdata.dev/es/docs/guides/response-formats/reference.md#completed-results)

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

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

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

- [Compruebe cada entrada antes de importar](https://flashdata.dev/es/docs/guides/bulk/reference.md#audit)
- [Manifiesto, cuenta y NDJSON](https://flashdata.dev/es/docs/reference/bulk-processing/reference.md#downloadBulkJobManifest)

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

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

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

- [Verificar tamaño, suma de comprobación y medios](https://flashdata.dev/es/docs/guides/youtube-download-guide/reference.md#verify-media)

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

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

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

- [Correble cliente MCP con colección de trozos](https://flashdata.dev/es/docs/guides/mcp-custom-client/reference.md)

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

## Problemas de ahorro y recuperación

| Problema | Arreglos |
| --- | --- |
| Archivo de salida ya existe | Inspeccione 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 carrera | Utilice el usuario original OS, perfil y directorio estatal. Si mantiene un trabajo remoto ID, recupere ese trabajo directamente. |
| 401 / 403 en reutilización | Ejecutar flashdata auth status --json y restaurar el acceso válido. Un archivo local ya guardado todavía se puede leer sin acceso API. |
| 409 / 410 | 409: espere el trabajo existente. 410: use su copia guardada; el resultado temporal ha expirado. |
| Error de disco después de una consulta | Mantenga 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 falla | Restaurar 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_unavailable | Resultado 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. |

- [comandos de recuperación CLI](https://flashdata.dev/es/docs/guides/cli-automation/reference.md#recover)
- [Solución de problemas](https://flashdata.dev/es/docs/guides/troubleshooting/reference.md)
