浏览文档
指南
将结果与原始输入、来源链接及用量一起保存,再交给另一个进程使用,无需重新查询。
本页内容
查询一次,在多个任务间复用结果
生成报告、重新运行解析程序,或为智能体后续步骤提供相同证据。本流程将一次搜索保存为可携带归档;读取归档不需要 FlashData 密钥或原 CLI 状态。
archive/saved-search/
request.json 原始查询及参数
response.json 未修改的 API 响应
citations.ndjson 标题、来源 URL 及摘要
manifest.json 运行 ID、用量、文件大小及 SHA-256开始前
使用新的工作目录、具有 google_search 权限及可用额度的 FlashData CLI,复用已认证配置档或 FLASHDATA_API_KEY。Bash 检查需要 jq,Windows 使用 PowerShell 7。本地归档脚本使用 Python 3.10+ 标准库。
data.accessVerified 为 true 时继续。CLI 重试需保持相同配置档、系统用户及状态目录。智能体应从密钥存储加载已有凭据。
flashdata auth status --json1. 保留输入并保存一次响应
保存下方 request.json,再运行一条命令。--input 使用此请求,之后保持文件不变。--output 将 API 响应保存到 search.json;--json 输出 CLI 元数据。saved-search 是本任务的本地运行 ID。
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
}
}flashdata query --input request.json \
--run-id saved-search --output search.json --jsonflashdata query --input request.json `
--run-id saved-search --output search.json --json2. 验证已保存响应
预期包含 source: google_search、status: done 及 results 数组。输出每条自然搜索结果的标题、链接和摘要。实际结果会变化;成功但为空的集合,与请求失败或字段缺失不同。
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$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
}3. 归档输入、响应及引用
保存下方 archive.py,再使用第 1 步运行 ID 执行。脚本保留原始文件,提取来源链接,最后写入包含文件校验和及用量的 manifest.json。预期 complete: true;引用数量取决于搜索结果。不发送网络请求。
保存 archive.py
在工作目录中、request.json 和 search.json 旁创建 archive.py,复制下方完整代码并保存。
示例归档 Google 搜索结果,保留已有归档目录。归档完成前,将 request.json、search.json 与对应运行保存在一起。
# 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}))创建归档
在 archive.py、request.json 和 search.json 所在目录运行。
python3 archive.py --run-id saved-searchpython archive.py --run-id saved-search4. 无需凭据复用归档
保存下方 reuse.py。将完整 archive/saved-search 目录复制给需要它的进程,再运行读取程序。脚本验证每个文件后输出原查询、用量及引用。密钥撤销或托管结果到期后仍可运行,因为它只读取已保存副本。
保存 reuse.py
在包含 archive/ 的工作目录创建 reuse.py。在另一台机器上使用时,同时复制 reuse.py 和完整的 archive/saved-search 目录,保持此目录结构。
# 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))读取已保存的归档
保存 reuse.py 后,在其所在目录运行。最后一个参数是复制后的归档路径。
python3 reuse.py archive/saved-searchpython reuse.py archive/saved-search也可从 CLI 运行记录导出
仍有原 CLI 配置档及状态目录时,可将已保存运行导出到新文件。不会发送新查询,但会先验证实时访问权限。已有结果文件或归档可在本地读取,无需此检查。
flashdata runs show saved-search --result --output search-copy.json --json决定何时复用或刷新
archived_at 记录文件保存时间,不表示来源页面更新时间。应用决定证据需要多新,复制文件不会刷新内容。
| 任务 | 操作 |
|---|---|
| 重跑解析、重新生成报告或继续智能体步骤 | 复用已保存响应,保留来源 URL、查询参数及用量。 |
| 生成新的每日简报或回答变化后的查询 | 创建新的任务或运行 ID、工作目录及归档,保留旧快照作为历史。 |
| 统计派生文件的用量 | 原查询只计算一次。复制响应或生成另一份报告不会产生新费用。 |
了解保留期限
| 结果 | 应保存什么 | 保留期 |
|---|---|---|
| 实时查询 | 响应文件及原始输入 | 已保存副本遵循你的存储策略 |
| Async / Batch 任务 | 任务 ID、提交回执及结果 JSON | 完成后 24 小时 |
| Bulk | 清单及所有 NDJSON 分片 | 整个任务完成后 24 小时;检查 expiresAt |
| YouTube 下载 | 交付 JSON 及目标存储中的媒体 | 交付 JSON 遵循任务保留期;媒体遵循 Bucket 生命周期 |
| MCP 分片缓存 | 合并后的完整结果 | 10 分钟;每个 API Key 仅保留最近四个大结果 |
也可只保存简要附加记录
保留原始响应不变。另存输入、来源、保存时间及用量,便于后续流程理解文件的生成方式。转换结果时保留来源 URL 及视频时间戳。
(
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
)通过 HTTP 直接保存
可用此方式代替第 1 步 CLI 查询。先保存相同 request.json;此代码使用 Bash、cURL 7.76+ 及 jq 运行一次新查询。复用 FLASHDATA_API_KEY,选择没有 search.json 的目录。验证后,可用相同脚本归档此结果;--run-id 使用你的任务 ID。
cURL 非零退出码表示结果尚不可用。重试前检查已保存响应;连接超时可能发生在查询已接纳之后。使用第 2 步验证命令。
# 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(
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
)保存已有后台任务
使用异步指南中的 submission.json 及同一账户凭据。以下命令读取已有任务,不提交新查询。CLI 会等待完成并处理结果重定向。请在完成后 24 小时内保存结果。
(
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
)任务未 completed 时状态检查会停止。若仍 queued 或 running,等待后再次运行这段只读代码;若 failed 则检查错误。302 下载不转发 API Key;临时响应验证通过后才生成 job-result.json。
(
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
)保存全部 Bulk 结果分片
将 BULK_ID 替换为提交回执中的 ID。任务完成后,CLI 按清单收集全部分片,保存为一个 NDJSON 文件。需要计数和分片元数据时,也应保留清单。
文件可能同时包含成功和失败行。核对输入索引及计数后再将整个任务标记完成。不要为了恢复一条失败行而重跑整个输入文件。
flashdata bulk results BULK_ID --output bulk-results.ndjson --timeout 30m --json保留交付记录与媒体
delivery.json 包含交付记录,而非视频或音频字节。随任务保存 URL、大小和校验和。媒体位于你的目标存储,并遵循该存储的生命周期。
私有目标存储需要使用提供商凭据或签名 URL 检查对象。临时结果 JSON 丢失,不意味着已存媒体被删除。
jq '.results[] | {file_url, file_size, md5, downloaded_bytes, output_format}' delivery.json合并 MCP 分片后保存
工具返回 result_id、chunk 及 next_offset 时,用同一 API Key 调用 get_result 读取后续分片。必须使用工具实际返回的 next_offset;下方仅为占位示例。
- 按 offset 顺序追加各分片,跟随 next_offset,直到其为 null。
- 拼接完成后一次性解析 JSON,再将完整结果写入自己的文件或存储。
- 在 expires_at 前保存。缓存每个 API Key 仅保留四个大结果;新结果可能导致旧结果在 10 分钟前被移除。
{
"name": "get_result",
"arguments": {
"result_id": "RESULT_ID_FROM_TOOL",
"offset": 16000
}
}修复保存及读取问题
| 问题 | 处理方式 |
|---|---|
| 输出文件已存在 | 先检查已有文件。CLI 运行已完成时,使用 runs show 和新文件名导出,不重新提交查询。 |
| CLI 找不到运行 | 使用原系统用户、配置及状态目录。若保留了远程任务 ID,可直接获取该任务。 |
| 复用时出现 401 / 403 | 运行 flashdata auth status --json,恢复有效访问。已保存的本地文件仍可直接读取,无需 API 访问。 |
| 409 / 410 | 409:等待已有任务。410:使用已保存副本;临时结果已过期。 |
| 查询后磁盘写入失败 | 保留运行 ID 或任务 ID。修复存储后,先恢复已有任务,再考虑是否需要重新提交。 |
| 归档无清单或校验和不符 | 恢复或重新复制原文件,保留不完整归档以供检查。重建归档不需要新查询。 |
| MCP · result_unavailable | 检查结果 ID、offset、API Key 及到期时间。缓存过期时使用已保存副本,不要通过循环付费查询来尝试恢复。 |