Lewati ke isi
ID
Dapatkan kunci API
Jelajahi dokumentasi

Panduan

Simpan dan gunakan ulang hasil

Simpan hasil dengan masukan aslinya, link sumber dan penggunaan, kemudian serahkan ke proses lain tanpa permintaan lain.

Di halaman ini

Query sekali, gunakan hasil dari tugas

Buat laporan, jalankan ulang parser Anda atau memberikan agen kemudian langkah bukti yang sama. Sistem kerja ini menyimpan satu pencarian sebagai arsip portabel; membaca bahwa arsip tidak memerlukan kunci FlashData maupun negara asli CLI.

What you will keep
archive/saved-search/
  request.json asli query dan parameter
  response.json       tidak berubah API respon
  Judul citations.ndjson, sumber URLs dan snippet
  manifest.json       jalankan ID, penggunaan, ukuran berkas dan SHA-256

Sebelum Anda mulai

Gunakan folder kerja baru, FlashData CLI dengan google_search ijin dan kredit yang tersedia. Gunakan lagi profil terotentikasi atau FLASHDATA_API_KEY. Bash menggunakan inspeksi jq; Windows menggunakan PowerShell 7. Skrip arsip lokal memakai Python 3.10+ dan perpustakaan standarnya.

Lanjutkan ketika data.accessVerified adalah true. Untuk CLI retries, simpan profil yang sama, pengguna OS dan direktori negara. Seorang agen harus memuat kredensial yang ada dari toko rahasia.

Periksa akses tersimpan Anda
flashdata auth status --json

1. Simpan masukan dan simpan satu respon

Simpan request.json di bawah ini, kemudian jalankan satu perintah. --input gunakan permintaan ini; simpan berkas tidak berubah sesudahnya. --output Simpan API tubuh di search.json; --json cetak CLI metadate. saved- pencarian adalah tugas ini lokal run ID.

request.json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}
Jalankan satu pencarian
flashdata query --input request.json \
  --run-id saved-search --output search.json --json

2. Validasi respon disimpan

Sumber yang diharapkan: google_search, status: done dan hasil array. Cetak setiap judul hasil organik, tautan, dan snippet. Hasil sebenarnya bervariasi; koleksi sukses yang kosong berbeda dari permintaan yang gagal atau ruas yang hilang.

Validasi dan baca 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. Arsipkan masukan, respon, dan kutipan

Simpan archive.py di bawah ini, kemudian jalankan dengan menjalankan ID dari langkah 1. Ini mempertahankan berkas mentah, mengekstrak link sumber dan menulis manifest.json terakhir dengan file checksums dan penggunaan. Mengharapkan complete: true; jumlah kutipan tergantung pada hasil pencarian. Tak ada permintaan jaringan yang dibuat.

Simpan archive.py

Buat archive.py di samping request.json dan search.json dalam folder kerja Anda. Salin kode lengkap di bawah ini dan simpan.

Contoh arsip hasil Google Search. Direktori arsip yang telah ada disimpan utuh. Pertahankan request.json, search.json dan pasangan yang cocok dijalankan bersama sampai archiving komplit.

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

Buat arsip

Jalankan dari folder yang berisi archive.py, request.json dan search.json.

Bangun arsip baru
python3 archive.py --run-id saved-search

4. Gunakan kembali arsip tanpa kredensial

Simpan reuse.py di bawah ini. Salin folder archive/saved-search lengkap ke proses yang membutuhkannya, kemudian jalankan pembaca ini. Ini memverifikasi setiap berkas sebelum mencetak kueri, penggunaan, dan kutipan asli. Ini bekerja setelah API-kunci pembatalan atau hosted- hasil kadaluarsa karena membaca hanya salinan tersimpan Anda.

Simpan reuse.py

Buat reuse.py dalam folder yang berisi archive/. Di mesin lain, salin baik reuse.py dan lengkap archive/saved-search direktori, menjaga tata letak ini.

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

Baca arsip yang tersimpan

Simpan reuse.py, kemudian jalankan dari folder tersebut. Argumen terakhir adalah path ke arsip yang disalin.

Baca arsip yang disalin
python3 reuse.py archive/saved-search

Ekspor dari jurnal CLI

Jika Anda masih memiliki profil asli CLI dan direktori state, ekspor run tersimpan ke nama berkas baru. Ini tidak membuat permintaan baru, tetapi memverifikasi akses langsung terlebih dahulu. Berkas hasil atau arsip yang ada dapat dibaca secara lokal tanpa pemeriksaan tersebut.

Ekspor run selesai
flashdata runs show saved-search --result --output search-copy.json --json

Putuskan kapan akan memakai ulang atau menyegarkan

archived_at mencatat ketika Anda menyimpan file, bukan ketika halaman sumber berubah. Aplikasi Anda memutuskan bagaimana bukti baru-baru ini harus; menyalin sebuah berkas tidak menyegarkan isinya.

TugasAksi
Rerun sebuah parser, regenerasi laporan atau melanjutkan langkah agenGunakan lagi respon yang disimpan. Pertahankan sumber URLs, parameter query dan penggunaan dengan itu.
Menghasilkan briefing harian baru atau menjawab permintaan berubahBuat yang baru task/run ID, bekerja folder dan arsip. Jauhkan snapshots tua sebagai sejarah.
Cacah penggunaan di seluruh berkas turunanHitung pertanyaan aslinya sekali. Menyalin jawaban atau membuat laporan lain tidak membuat muatan lain.

Tahu apa yang kadaluarsa

HasilApa yang harus disimpanRetensi
Realtime queryBerkas respon dan masukan asliSalinan tersimpan Anda mengikuti kebijakan penyimpanan Anda
Async / Batch tugasJob ID, penerimaan pengiriman dan hasil JSON24 jam setelah selesai
BulkPerpotongan NDJSON dan semua yang nyata24 jam setelah seluruh pekerjaan selesai; periksa expiresAt
YouTube DownloadPengiriman JSON dan media di tujuan AndaPengiriman JSON: pekerjaan retensi. Media: Anda ember lifecycle
MCP park cacheHasil yang telah dirakit sepenuhnya10 menit; hanya empat hasil terbaru besar per kunci API yang ditahan

Jaga sespan kecil sebagai gantinya

Jauhkan respon asli tidak berubah. Simpan sebuah sespan kecil dengan masukan, sumber, menghemat waktu dan penggunaan sehingga proses kemudian dapat memahami apa yang dihasilkan file. Pertahankan sumber URLs dan penanda waktu video ketika mengubah hasil.

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
)

Simpan langsung dengan HTTP

Gunakan ini sebagai ganti permintaan CLI dalam langkah 1. Simpan yang sama request.json pertama; ini menjalankan satu query baru menggunakan Bash, cURL 7.76+ dan jq. Gunakan FLASHDATA_API_KEY dan pilih folder tanpa search.json. Setelah validasi, skrip arsip yang sama bekerja dengan hasil ini; pilih tugas Anda sendiri ID untuk --run-id.

Sebuah keluar bukan nol cURL berarti hasil tidak siap untuk digunakan. Inspeksi respon yang disimpan sebelum mencoba ulang; suatu waktu koneksi dapat terjadi setelah permintaan diterima. Gunakan perintah validasi dalam langkah 2.

Tetapkan kunci bila diperlukan
# 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
Simpan respon 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
)

Simpan suatu tugas latar belakang yang ada

Gunakan submission.json dari panduan async dan kredensial account yang sama. Perintah-perintah ini mengambil pekerjaan yang sudah ada; mereka tidak mengirimkan permintaan lain. CLI menunggu untuk penyelesaian dan menangani hasil redirect. Simpan hasilnya dalam waktu 24 jam penyelesaian.

Tunggu, ambil dan selamatkan
(
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
)

Simpan setiap bagian hasil Bulk

Ganti BULK_ID dengan ID dalam penerimaan penyerahan Anda. Setelah pekerjaan selesai, CLI mengikuti manifes dan menyimpan setiap bagian sebagai satu file NDJSON. Simpan manifes juga ketika Anda perlu menghitung dan bagian metadata.

Berkas dapat memuat baris baik sukses maupun gagal. Reconcile input indeks dan dihitung sebelum menandai seluruh tugas komplit. Jangan jalankan ulang seluruh berkas masukan untuk mengembalikan satu baris yang gagal.

Mengumpulkan tugas yang selesai
flashdata bulk results BULK_ID --output bulk-results.ndjson --timeout 30m --json

Simpan catatan pengiriman dan media

delivery.json berisi catatan pengiriman, bukan video atau byte audio. Simpan URL-nya, ukuran dan checksum di samping tugas. Media tinggal di penyimpanan tujuan Anda dan mengikuti bahwa lifecycle penyimpanan.

Untuk tujuan pribadi, gunakan kredensial penyedia tersebut atau tandatangani URL untuk memeriksa objek tersebut. Hasil sementara yang hilang JSON tidak berarti media yang tersimpan telah dihapus.

Inspeksi hasil unduhan yang disimpan jq
jq '.results[] | {file_url, file_size, md5, downloaded_bytes, output_format}' delivery.json

Kumpulkan potongan MCP sebelum menyimpan

Ketika suatu alat kembali result_id, chunk dan next_offset, membaca potongan yang tersisa dengan get_result menggunakan sama API kunci. Gunakan next_offset yang tepat yang dikembalikan oleh alat; nilai di bawah ini adalah placeholder.

  1. Tambahkan setiap potongan dalam urutan ofset. Ikuti next_offset sampai null.
  2. Bagian teks bergabung sekali sebagai JSON, kemudian menulis hasil penuh ke file atau penyimpanan Anda sendiri.
  3. Simpan sebelum expires_at. Respon besar baru dapat mengusir hasil yang lebih tua sebelum 10batas -minute; cache terus empat per API kunci.
MCP tools/call argumen
{
  "name": "get_result",
  "arguments": {
    "result_id": "RESULT_ID_FROM_TOOL",
    "offset": 16000
  }
}

Perbaiki masalah penyimpanan dan pengambilan

MasalahPerbaiki
Berkas keluaran sudah adaPeriksa dulu. Untuk menjalankan CLI lengkap, gunakan runs show dengan nama berkas keluaran baru daripada mengirimkan query lain.
CLI tidak dapat menemukan jalankanGunakan pengguna asli OS, profil, dan direktori negara. Jika Anda terus pekerjaan remote ID, mengambil pekerjaan itu secara langsung.
401 / 403 di reuseJalankan data kilas auth status --json dan mengembalikan akses yang valid. Berkas lokal yang telah disimpan masih dapat dibaca tanpa akses API.
409 / 410409: tunggu untuk pekerjaan yang telah ada. 410: gunakan salinan tersimpan Anda; hasil sementara telah berakhir.
Galat diska setelah suatu permintaanTetap jalankan ID atau kerja ID. Perbaiki penyimpanan dan memulihkan pekerjaan yang ada sebelum mempertimbangkan penyerahan baru.
Arsip tidak memiliki manifest atau checksum gagalKembalikan atau salin berkas asli lagi. Simpan arsip tidak lengkap untuk pemeriksaan; membangun kembali arsip tidak memerlukan kueri baru.
MCP · result_unavailablePeriksa hasil ID, ofset, kunci API dan kadaluarsa. Gunakan salinan tersimpan jika cache telah berakhir; jangan loop dengan mengulangi kuiri dibayar.