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

Riferimento canonico: https://flashdata.dev/it/docs/guides/save-results
Recensito: 2026-11-05 da FlashData

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

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

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

- [Hai gia' un risultato asincastro?](https://flashdata.dev/it/docs/guides/save-results/reference.md#jobs)
- [Salvare un set di dati Bulk](https://flashdata.dev/it/docs/guides/save-results/reference.md#bulk)
- [Tieni i media scaricati](https://flashdata.dev/it/docs/guides/save-results/reference.md#media)

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

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

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

- [Installare la CLI](https://flashdata.dev/it/docs/guides/flashdata-cli/reference.md#install)
- [Creare una chiave API](https://flashdata.dev/app/api-keys)
- [Utilizzare HTTP invece](https://flashdata.dev/it/docs/guides/save-results/reference.md#http)

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

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

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

### Bash

#### Esegui una ricerca

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


### PowerShell

#### Esegui una ricerca

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



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

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

### Bash / jq

#### Convalida e leggi 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

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


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

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

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

### Creare l'archivio

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

#### Bash

##### Costruire un nuovo archivio

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


#### PowerShell 7

##### Costruire un nuovo archivio

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



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

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


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

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

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

### Leggi l'archivio salvato

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

#### Bash

##### Leggi l'archivio copiato

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


#### PowerShell 7

##### Leggi l'archivio copiato

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



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

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

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


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

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

| Compiti | Azione |
| --- | --- |
| Recuperare un parser, rigenerare un rapporto o continuare un passo agente | Riutilizzare 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 cambiata | Creare una nuova task/run ID, cartella di lavoro e archivio. Tenere le istantanee più vecchie come storia. |
| Conta l'uso attraverso i file derivati | Contare la query originale una volta. Copiare una risposta o fare un altro rapporto non crea un'altra carica. |

- [Attività ricorrenti ed eseguire IDs](https://flashdata.dev/it/docs/guides/recurring-tasks/reference.md)
- [Formattazione dei risultati esistenti](https://flashdata.dev/it/docs/guides/response-formats/reference.md#completed-results)

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

## Sapere che cosa scade

| Risultato | Cosa tenere | Retenzione |
| --- | --- | --- |
| Domanda Realtime | Il file di risposta e l'ingresso originale | La copia salvata segue la politica di archiviazione |
| Lavoro Async / Batch | Job ID, ricevuta di presentazione e risultato JSON | 24 ore dopo il completamento |
| Bulk | Manifest e tutte le parti NDJSON | 24 ore dopo l'intero lavoro completato; controllare expiresAt |
| YouTube Download | Consegna JSON e media nella tua destinazione | Consegna JSON: ritenzione di lavoro. Media: il tuo ciclo di vita del secchio |
| MCP chunk cache | Il risultato completamente montato | Minuti 10; solo i quattro nuovi risultati grandi per chiave API sono mantenuti |


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

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

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

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

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

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

### CLI + jq

#### Aspetta, recupera e 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

Il controllo di stato si ferma se il lavoro non è completato. Se è ancora in coda o in esecuzione, attendere e eseguire questo snippet di sola lettura di nuovo; ispezionare un lavoro fallito invece. A 302 viene scaricato senza inoltrare la chiave API. La risposta temporanea viene validata prima che venga creata 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
)
```


- [Riprendi un lavoro asincastro esistente](https://flashdata.dev/it/docs/guides/async-batch/reference.md#resume)
- [Risultato contratto di risposta](https://flashdata.dev/it/docs/reference/realtime-and-async/reference.md#results)
- [Recuperare come Markdown](https://flashdata.dev/it/docs/guides/response-formats/reference.md#completed-results)

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

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

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

- [Controllare ogni input prima di importare](https://flashdata.dev/it/docs/guides/bulk/reference.md#audit)
- [Manifestazione, conteggi e NDJSON](https://flashdata.dev/it/docs/reference/bulk-processing/reference.md#downloadBulkJobManifest)

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

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

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

- [Verificare le dimensioni, il checksum e i media](https://flashdata.dev/it/docs/guides/youtube-download-guide/reference.md#verify-media)

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

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

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

- [client Runnable MCP con collezione di pezzi](https://flashdata.dev/it/docs/guides/mcp-custom-client/reference.md)

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

## Risolvere i problemi di salvataggio e di recupero

| Problematiche | Risolto |
| --- | --- |
| 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 corsa | Utilizzare la directory OS originale utente, profilo e stato. Se hai mantenuto un lavoro remoto ID, recuperalo direttamente. |
| 401 / 403 sul riutilizzo | Eseguire flashdata auth status --json e ripristinare l'accesso valido. Un file locale già salvato può ancora essere letto senza accesso API. |
| 409 / 410 | 409: attendere il lavoro esistente. 410: utilizzare la copia salvata; il risultato temporaneo è scaduto. |
| Errore del disco dopo una query | Mantenere 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 riesce | Ripristinare o copiare nuovamente i file originali. Mantenere un archivio incompleto per l'ispezione; ricostruire l'archivio non richiede una nuova query. |
| MCP · result_unavailable | Risultato di controllo ID, offset, chiave API e scadenza. Utilizzare una copia salvata se la cache è scaduta; non loop ripetendo una query pagata. |

- [Comandi di ripristino CLI](https://flashdata.dev/it/docs/guides/cli-automation/reference.md#recover)
- [Richiedi la risoluzione dei problemi](https://flashdata.dev/it/docs/guides/troubleshooting/reference.md)
