Pular para o conteúdo
PT
Obter chave API
Explorar documentação

Guias

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.

Nesta página

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

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
flashdata auth status --json

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
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}
Faça uma busca
flashdata query --input request.json \
  --run-id saved-search --output search.json --json

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.

Validar e ler 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. 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.

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

Crie o arquivo

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

Construir um novo arquivo
python3 archive.py --run-id saved-search

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.

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

Leia o arquivo salvo

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

Leia o arquivo copiado
python3 reuse.py archive/saved-search

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
flashdata runs show saved-search --result --output search-copy.json --json

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.

TarefaAção
Reproduzir um analisador, regenerar um relatório ou continuar um passo de agenteReutilize 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 derivadosConte a pergunta original uma vez. Copiar uma resposta ou fazer outro relatório não cria outra carga.

Saiba o que expira

ResultadoO que guardar?Retenção
Consulta RealtimeO arquivo de resposta e entrada originalSua cópia salva segue sua política de armazenamento
Async / Batch trabalhoTrabalho ID, envio de recibo e resultado JSON24 horas após a conclusão
BulkManifesto e todas as partes NDJSON24 horas após todo o trabalho terminar, verifique expiresAt
YouTube DownloadEntrega JSON e mídia em seu destinoEntrega JSON: retenção de trabalho. Mídia: seu ciclo de vida do balde
MCP cache de pedaçosO resultado totalmente montado10 minutos, apenas os quatro mais novos resultados grandes por chave API são mantidos

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

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

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.

Espere, recupere e salve
(
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
)

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
flashdata bulk results BULK_ID --output bulk-results.ndjson --timeout 30m --json

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
jq '.results[] | {file_url, file_size, md5, downloaded_bytes, output_format}' delivery.json

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
{
  "name": "get_result",
  "arguments": {
    "result_id": "RESULT_ID_FROM_TOOL",
    "offset": 16000
  }
}

Conserte os problemas de salvamento e recuperação

ProblemaConsertar
Arquivo de saída já existeInspecione-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 corridaUse 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çãoExecute flashdata auth status --json e restaure acesso válido. Um arquivo local já salvo ainda pode ser lido sem acesso ao API.
409 / 410409 Espere pelo trabalho existente. 410: use sua cópia salva, o resultado temporário expirou.
Erro de disco após uma consultaMantenha 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 falhaRestaure 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_unavailableVerifique 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.