浏览文档
开始使用
验证请求,通过脚本运行,并分别读取结果与错误回执。
本页内容
1. 选择已有配置档
需要已安装的 CLI、Bash 和 jq;Windows 在 Git Bash 中运行 shell 示例。本流程使用已认证的 research 配置档;将 FLASHDATA_STATE_DIR 设为该配置档所在目录的绝对路径。
所有命令使用相同系统用户和状态目录。FLASHDATA_API_KEY 会覆盖保存的密钥;使用配置档时不设置该变量。CLI 不加载 .env 文件。
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
flashdata auth status --profile research --state-dir "$FLASHDATA_STATE_DIR" --json默认状态位置
若使用自定义 --state-dir,请保留原路径。auth status 应显示 data.accessVerified: true。无人值守部署应从密钥存储通过标准输入导入所有者密钥。
| 系统 | 目录 |
|---|---|
| Windows | %APPDATA%/FlashData |
| macOS | ~/Library/Application Support/FlashData |
| Linux | $XDG_STATE_HOME/flashdata or ~/.local/state/flashdata |
2. 验证请求与价格
保存 request.json,在同一目录运行免费检查。仅当来源价格可用且余额足以支付一次查询时,过滤器才输出 true。非零退出时停止。价格检查不预留 Credits。
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
}
}set -euo pipefail
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
flashdata account balance --profile research --state-dir "$FLASHDATA_STATE_DIR" \
--json --non-interactive > balance.json
flashdata query --input request.json --dry-run --run-id cli-research-001 \
--profile research --state-dir "$FLASHDATA_STATE_DIR" \
--json --non-interactive > preflight.json
jq -e --slurpfile balance balance.json '
.ok and .data.dryRun and .data.estimateAvailable
and ($balance[0].ok == true)
and any(.data.estimate.prices[]?;
.source == "google_search" and .available == true
and (.estimatedCredits | type == "number")
and ($balance[0].data.availableCredits | type == "number")
and .estimatedCredits <= $balance[0].data.availableCredits)
' preflight.json3. 运行并读取回执
检查通过后保存 run-search.sh,并运行 bash run-search.sh。首次成功执行提交一次搜索。每次尝试在新的 cli-run 目录保存文件;稳定运行 ID 让 CLI 在同一账户、配置档及状态目录复用之前的成功结果。
#!/usr/bin/env bash
set -euo pipefail
umask 077
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
dir=$(mktemp -d "cli-run.XXXXXX")
if ! flashdata query --input request.json --run-id cli-research-001 \
--profile research --state-dir "$FLASHDATA_STATE_DIR" \
--output "$dir/result.json" --timeout 2m --json --non-interactive \
> "$dir/receipt.json" 2> "$dir/error.json"; then
cat "$dir/error.json" >&2
printf 'Inspect saved run cli-research-001; receipts: %s\n' "$dir" >&2
exit 1
fi
jq -e '.schemaVersion == 1 and .ok == true' "$dir/receipt.json" >/dev/null
jq -e '.status == "done" and .source == "google_search"' "$dir/result.json" >/dev/null
jq -r '.results[]?.organic[]? | [.title, .link] | @tsv' "$dir/result.json"
jq '{runId, cached, usage}' "$dir/receipt.json"
printf 'Files: %s\n' "$dir"确认应读取哪个文件
CLI 回执与来源响应是不同的 JSON 文档。不使用 --output 时,来源响应位于 data。本例使用 --output,因此应从保存的 result.json 读取来源字段。
| 文件 | 读取内容 |
|---|---|
| receipt.json | ok、runId、cached、usage 及输出路径。缓存回执报告原始用量,不是新费用。 |
| result.json | source、status、results 和 usage。Google 搜索读取 results[].organic[];空数组也可能是有效搜索结果。 |
| error.json | 非零退出时,检查 error.code、error.httpStatus、error.retryAfter 及运行/任务 ID。 |
{
"schemaVersion": 1,
"ok": true,
"runId": "cli-research-001",
"cached": false,
"data": {
"output": "cli-run.EXAMPLE/result.json"
},
"usage": {
"credits": 0.02
}
}恢复结果,无需再次搜索
重试前先检查已保存运行。通过原账户的有效访问,将成功运行导出到尚不存在的文件。认领会从试用账户切换至所有者账户;保留之前导出的试用结果,并为新的所有者任务使用新 ID。同一运行 ID 下更改请求会被拒绝;仅在明确创建新任务时使用新 ID。
flashdata runs show cli-research-001 --profile research \
--state-dir "$FLASHDATA_STATE_DIR" --json
flashdata runs show cli-research-001 --result --output recovered.json \
--profile research --state-dir "$FLASHDATA_STATE_DIR" --json脚本可运行后添加调度
周期任务需使用已安装的所有者访问、--recurring、每个预期时段的稳定 ID 及持久化状态。试用无法运行周期任务。宿主管理调度,该参数仅检查访问。计划日期处理与重启请使用完整定时任务脚本。
可选:私有下载存储
使用 youtube download --storage-config storage.json 时,仅将此存储对象保存为 storage.json,并在本地替换占位符。文件须为执行用户所有且私有。运行下载前使用相应系统的权限命令。
{
"storage_type": "s3",
"storage_url": "YOUR_BUCKET",
"access_key": "YOUR_ACCESS_KEY",
"secret_key": "YOUR_SECRET_KEY",
"region": "us-east-1"
}chmod 600 storage.json$storagePath = (Resolve-Path -LiteralPath './storage.json').Path
$storageUser = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
$storageAcl = [System.Security.AccessControl.FileSecurity]::new()
$storageAcl.SetOwner($storageUser)
$storageAcl.SetAccessRuleProtection($true, $false)
$storageAcl.AddAccessRule([System.Security.AccessControl.FileSystemAccessRule]::new($storageUser, 'FullControl', 'Allow'))
Set-Acl -LiteralPath $storagePath -AclObject $storageAcl