# Economize e reutilize os resultados

Mantenha um resultado com sua entrada original, links de origem e uso, então entregue-o para outro processo sem outra consulta.

Referência canônica: https://flashdata.dev/pt/docs/guides/save-results
2026-11-05 por FlashData

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

## Consulta uma vez, use o resultado através de tarefas

Faça um relatório, reproduza seu analisador ou dê a um agente posterior as mesmas provas. Este fluxo de trabalho salva uma busca como um arquivo portátil, lendo que o arquivo não precisa nem de uma chave FlashData nem do estado original CLI.

### O que você vai guardar

```text
archive/saved-search/
  request.json consulta original e parâmetros
  response.json resposta inalterada API
  citations.ndjson títulos, fonte URLs e trechos
  manifest.json roda ID, uso, tamanhos de arquivos e SHA-256
```

- [Já tem um resultado sincronizado?](https://flashdata.dev/pt/docs/guides/save-results/reference.md#jobs)
- [Salve um conjunto de dados Bulk](https://flashdata.dev/pt/docs/guides/save-results/reference.md#bulk)
- [Mantenha a mídia baixada](https://flashdata.dev/pt/docs/guides/save-results/reference.md#media)

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

## Antes de começar

Use uma nova pasta de trabalho, a FlashData CLI com permissão google_search e créditos disponíveis. Reutilize um perfil autenticado ou FLASHDATA_API_KEY. A inspeção Bash usa jq; Windows usa PowerShell 7. Os scripts de arquivos locais usam Python 3.10+ e sua biblioteca padrão.

Continue quando data.accessVerified é true. Para CLI, mantenha o mesmo perfil, usuário OS e diretório de estado. Um agente deve carregar sua credencial existente de sua loja secreta.

### Verifique seu acesso salvo

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

- [Instale o CLI](https://flashdata.dev/pt/docs/guides/flashdata-cli/reference.md#install)
- [Crie uma chave API](https://flashdata.dev/app/api-keys)
- [Use HTTP em vez disso](https://flashdata.dev/pt/docs/guides/save-results/reference.md#http)

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

## 1. Mantenha a entrada e salve uma resposta

Salve request.json Em baixo, então execute um comando. --input  Usa este pedido exato, mantenha o arquivo inalterado depois. --output  salva o API  Corpo em search.json; --json Impressões digitais CLI Metadados. Pesquisa salva é a execução local desta tarefa. ID.

### request.json

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

### Bash

#### Faça uma busca

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


### PowerShell

#### Faça uma busca

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



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

## 2. Validar a resposta salva

Fonte esperada: google_search, status: done e uma matriz de resultados. Imprima o título de cada resultado orgânico, link e trecho. Os resultados reais variam, uma coleção vazia de sucesso é diferente de uma solicitação falhada ou um campo perdido.

### Bash / jq

#### Validar e ler 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 e ler 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. Arquive as entradas, respostas e citações

Salve archive.py abaixo, então execute com a corrida ID do passo 1. Ele preserva os arquivos brutos, extrai links de origem e escreve manifest.json último com arquivos de verificação e uso. Espere complete: true, a contagem de citações depende dos resultados da busca. Nenhum pedido de rede é feito.


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

### Salve archive.py

Crie archive.py ao lado de request.json e search.json em sua pasta de trabalho. Copie o código completo abaixo e salve-o.

O exemplo arquiva resultados Google Search. Os arquivos existentes são mantidos intactos. Mantenha request.json, search.json e a correspondência juntos até o arquivamento terminar.

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

### Crie o arquivo

Corra da pasta que contém archive.py, request.json e search.json.

#### Bash

##### Construir um novo arquivo

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


#### PowerShell 7

##### Construir um novo arquivo

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



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

## 4. Reutilize o arquivo sem credenciais

Salve reuse.py abaixo. Copie a pasta archive/saved-search completa para o processo que precisa, então execute este leitor. Verifica todos os arquivos antes de imprimir a consulta, uso e citações originais. Funciona após a revogação da chave API ou expiração do resultado hospedado porque só lê sua cópia salva.


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

### Salve reuse.py

Crie reuse.py na pasta de trabalho contendo archive/. Em outra máquina, copie reuse.py e o diretório completo archive/saved-search, mantendo este 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>

### Leia o arquivo salvo

Salve reuse.py, e depois corra de sua pasta. O argumento final é o caminho para o arquivo copiado.

#### Bash

##### Leia o arquivo copiado

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


#### PowerShell 7

##### Leia o arquivo copiado

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



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

### Exportar do diário CLI em vez disso

Se você ainda tem o perfil original CLI e diretório de estado, exporte a execução salva para um novo nome de arquivo. Isso não faz nenhuma nova consulta, mas verifica o acesso ao vivo primeiro. Um arquivo ou arquivo de resultados existentes pode ser lido localmente sem esse verificação.

#### Exportar a corrida completa

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


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

## Decida quando reutilizar ou atualizar

archived_at grava quando você salvou os arquivos, não quando uma página de origem mudou. Seu pedido decide o quão recente a evidência deve ser, copiar um arquivo não atualiza seu conteúdo.

| Tarefa | Ação |
| --- | --- |
| Reproduzir um analisador, regenerar um relatório ou continuar um passo de agente | Reutilize a resposta salva. Mantenha a fonte URLs, parâmetros de consulta e uso com ela. |
| Produza uma nova informação diária ou responda a uma pergunta mudada. | Criar um novo task/run ID, pasta de trabalho e arquivo. Mantenha fotos antigas como história. |
| Contagem de uso em arquivos derivados | Conte a pergunta original uma vez. Copiar uma resposta ou fazer outro relatório não cria outra carga. |

- [Tarefas recorrentes e executar IDs](https://flashdata.dev/pt/docs/guides/recurring-tasks/reference.md)
- [Formatar resultados existentes](https://flashdata.dev/pt/docs/guides/response-formats/reference.md#completed-results)

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

## Saiba o que expira

| Resultado | O que guardar? | Retenção |
| --- | --- | --- |
| Consulta Realtime | O arquivo de resposta e entrada original | Sua cópia salva segue sua política de armazenamento |
| Async / Batch trabalho | Trabalho ID, envio de recibo e resultado JSON | 24 horas após a conclusão |
| Bulk | Manifesto e todas as partes NDJSON | 24 horas após todo o trabalho terminar, verifique expiresAt |
| YouTube Download | Entrega JSON e mídia em seu destino | Entrega JSON: retenção de trabalho. Mídia: seu ciclo de vida do balde |
| MCP cache de pedaços | O resultado totalmente montado | 10 minutos, apenas os quatro mais novos resultados grandes por chave API são mantidos |


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

## Fique com um pequeno sidecar

Mantenha a resposta original inalterada. Economize um pequeno sidecar com a entrada, fonte, economizar tempo e uso para que um processo posterior possa entender o que produziu o arquivo. Mantenha o código URLs e as datas de vídeo ao transformar os 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>

## Salve diretamente com HTTP

Use isso em vez da consulta CLI no passo 1. Salve o mesmo request.json primeiro, isto é executado uma nova consulta usando Bash, cURL 7.76+ e jq. Reutilize FLASHDATA_API_KEY e escolha uma pasta sem search.json. Após a validação, os mesmos scripts de arquivo funcionam com este resultado; escolha sua própria tarefa ID para --run-id.

Uma saída cURL nonzero significa que o resultado não está pronto para uso. Inspecione a resposta salva antes de tentar novamente, um tempo limite de conexão pode acontecer depois que uma consulta foi aceita. Use o comando de validação no passo 2.

### Defina sua chave se necessário

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

### Salve a resposta 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>

## Salve um trabalho de fundo existente

Use submission.json do guia de sincronização e a mesma credencial de contas. Esses comandos recuperam o trabalho existente, eles não enviam outra consulta. O CLI espera pela conclusão e lida com o redirecionamento do resultado. Economize o resultado em 24 horas de conclusão.

### CLI + jq

#### Espere, recupere e salve

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

A verificação de status para se o trabalho não estiver concluído. Se ainda estiver na fila ou correndo, espere e execute este trecho somente de leitura novamente; inspecione um trabalho fracassado em vez disso. Um 302 é baixado sem encaminhar sua chave API. A resposta temporária é validada antes de job-result.json ser criada.

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


- [Retomar um trabalho de sincronização existente](https://flashdata.dev/pt/docs/guides/async-batch/reference.md#resume)
- [Resultado do contrato de resposta](https://flashdata.dev/pt/docs/reference/realtime-and-async/reference.md#results)
- [Recupere como Markdown](https://flashdata.dev/pt/docs/guides/response-formats/reference.md#completed-results)

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

## Salve cada parte do resultado do Bulk

Substitua BULK_ID pelo ID em seu recibo de submissão. Após o trabalho terminar, o CLI segue o manifesto e salva todas as partes como um arquivo NDJSON. Mantenha o manifesto também quando precisar de contagens e metadados.

O arquivo pode conter linhas bem sucedidas e falhadas. Reconcile os índices de entrada e conta antes de marcar a tarefa completa. Não repita todo o arquivo de entrada para recuperar uma linha falhada.

### Recolha o trabalho concluído

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

- [Verifique cada entrada antes de importar](https://flashdata.dev/pt/docs/guides/bulk/reference.md#audit)
- [Manifesto, conta e NDJSON](https://flashdata.dev/pt/docs/reference/bulk-processing/reference.md#downloadBulkJobManifest)

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

## Mantenha o registro de entrega e mídia

delivery.json contém um registro de entrega, não o vídeo ou os bytes de áudio. Salve seu URL, tamanho e soma de verificações ao lado da tarefa. A mídia vive em seu armazenamento de destino e segue o ciclo de vida desse armazenamento.

Para um destino privado, use as credenciais do provedor ou assinou URL para inspecionar o objeto. Um resultado temporário perdido JSON não significa que sua mídia armazenada foi deletada.

### Inspecione um resultado de download salvo. jq

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

- [Verifique o tamanho, o checksum e a mídia](https://flashdata.dev/pt/docs/guides/youtube-download-guide/reference.md#verify-media)

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

## Junte os pedaços MCP antes de salvar

Quando uma ferramenta devolve result_id, bloco e next_offset, leia os pedaços restantes com get_result usando a mesma chave API. Use o next_offset exato devolvido pela ferramenta; os valores abaixo são placeholders.

1. Anexar cada pedaço em ordem offset. Siga next_offset até que seja null.
2. Processe o texto juntado uma vez como JSON, então escreva o resultado completo para o seu próprio arquivo ou armazenamento.
3. Salve antes de expires_at. Novas grandes respostas podem despejar resultados mais antigos antes do limite de minutos 10; o cache mantém quatro por chave API.

### MCP tools/call argumentos

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

- [Cliente MCP com coleção de pedaços](https://flashdata.dev/pt/docs/guides/mcp-custom-client/reference.md)

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

## Conserte os problemas de salvamento e recuperação

| Problema | Consertar |
| --- | --- |
| Arquivo de saída já existe | Inspecione-o primeiro. Para uma execução completa do CLI, use runs show com um novo nome de arquivo em vez de enviar outra consulta. |
| CLI não consegue encontrar a corrida | Use o usuário original OS, perfil e diretório de estado. Se você manteve um trabalho remoto ID, recupere esse trabalho diretamente. |
| 401 / 403 em reutilização | Execute flashdata auth status --json e restaure acesso válido. Um arquivo local já salvo ainda pode ser lido sem acesso ao API. |
| 409 / 410 | 409 Espere pelo trabalho existente. 410: use sua cópia salva, o resultado temporário expirou. |
| Erro de disco após uma consulta | Mantenha o ID ou o trabalho ID. Conserte o armazenamento e recupere o trabalho existente antes de considerar uma nova submissão. |
| Arquivo não tem manifesto ou um checksum falha | Restaure ou copie os arquivos originais de novo. Mantenha um arquivo incompleto para inspeção. Reconstruir o arquivo não requer uma nova consulta. |
| MCP · result_unavailable | Verifique o resultado ID, offset, chave API e expirar. Use uma cópia salva se o cache expirou; não faça um loop repetindo uma consulta paga. |

- [Comandos de recuperação CLI](https://flashdata.dev/pt/docs/guides/cli-automation/reference.md#recover)
- [Peço solução de problemas](https://flashdata.dev/pt/docs/guides/troubleshooting/reference.md)
