Обзор документации
Руководства
Сохраняйте результат с его исходным вводом, исходными ссылками и использованием, а затем передавайте его другому процессу без другого запроса.
На этой странице
Запрос один раз, используйте результат в задачах
Создайте отчет, повторите анализ или дайте более позднему агенту те же доказательства. Этот рабочий процесс сохраняет один поиск в качестве переносного архива; чтение этого архива не требует ни ключа FlashData, ни исходного состояния CLI.
archive/saved-search/
request.json - оригинальный запрос и параметры
response.json без изменений ответ API
citations.ndjson titles, источник URLs и фрагменты
manifest.json запускает ID, использование, размеры файлов и SHA-256Прежде чем начать
Используйте новую рабочую папку FlashData CLI с разрешением google_search и доступными кредитами. Повторное использование аутентифицированного профиля или FLASHDATA_API_KEY. Инспекция Bash использует jq; Windows использует PowerShell 7. Скрипты локального архива используют Python 3.10+ и его стандартную библиотеку.
Если data.accessVerified — это true. Для повторных запросов CLI сохраняйте тот же профиль, пользователя OS и каталог состояния. Агент должен загрузить свои существующие учетные данные из своего секретного магазина.
flashdata auth status --json1. Сохраните ввод и сохраните один ответ
Спасти request.json Внизу, затем выполните одну команду. --input Использует этот точный запрос; сохраняйте файл неизменным после этого. --output спасает API тело в search.json; --json отпечатки CLI Сберегаемый поиск - это локальный запуск этой задачи 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. Проверить сохраненный ответ
Источник: google_search, status: done и массив результатов. Печать названия каждого органического результата, ссылки и фрагмента. Фактические результаты варьируются; пустая удачная коллекция отличается от неудавшейся заявки или отсутствующего поля.
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 ниже, затем запустите его с помощью запуска ID с шага 1. Он сохраняет необработанные файлы, извлекает исходные ссылки и пишет manifest.json последний с контрольными суммами файлов и использованием. Ожидайте complete: true; количество ссылок зависит от результатов поиска. Сетевые запросы не принимаются.
Скачать archive.py
Создайте archive.py рядом с request.json и search.json в рабочей папке. Скопируйте полный код ниже и сохраните его.
В примере архивируются результаты Google Search. Существующие архивные каталоги держатся в неприкосновенности. Держите 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 в нужный ей процесс, затем запустите этот считыватель. Он проверяет каждый файл перед печатью оригинального запроса, использования и цитирования. Он работает после отзыва ключа API или истечения срока действия хостинга, потому что он читает только сохраненную копию.
Скачать reuse.py
Создание reuse.py в рабочей папке, содержащей archive/. На другом компьютере скопируйте как 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 записывает данные при сохранении файлов, а не при изменении исходной страницы. Ваша заявка решает, насколько недавними должны быть доказательства; копирование файла не обновляет его содержание.
| Задание | Меры |
|---|---|
| Перезапуск парсера, восстановление отчета или продолжение действия агента | Повторно использовать сохраненный ответ. Храните источник URLs, параметры запроса и использование с ним. |
| Создайте новый ежедневный брифинг или ответ на измененный запрос | Создайте новую task/run ID, рабочую папку и архив. Держите старые снимки в качестве истории. |
| Использование Count в производных файлах | Подсчитайте первоначальный запрос один раз. Копирование ответа или составление другого отчета не создает другой платы. |
Знать, что истекает
| Результат | Что оставить | Сохранение |
|---|---|---|
| Запрос Realtime | Файл ответа и оригинальный ввод | Сохраненная копия соответствует политике хранения |
| Async / Batch / Работа | Работа ID, получение заявки и результат JSON | 24 часов после завершения |
| Bulk | Манифест и все части NDJSON | 24 через несколько часов после завершения работы; проверьте expiresAt |
| YouTube Download | Доставка JSON и медиа в пункт назначения | Доставка JSON: удержание работы. Медиа: ваш жизненный цикл |
| MCP кэш-память | Полностью собранный результат | 10 минуты; сохранены только четыре самых новых больших результата на ключ API |
Держите вместо этого небольшую коляску
Оставьте первоначальный ответ без изменений. Сохраните небольшую коляску с вводом, источником, сэкономьте время и использование, чтобы более поздний процесс мог понять, что произвел файл. Храните исходные URLs и временные метки видео при преобразовании результатов.
(
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
Используйте это вместо запроса CLI на этапе 1. Сначала сохраните тот же request.json; это запускает один новый запрос с использованием Bash, cURL 7.76+ и jq. Повторно используйте FLASHDATA_API_KEY и выберите папку без search.json. После валидации с этим результатом работают те же архивные скрипты; выберите свою задачу ID для --run-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
)Проверка статуса прекращается, если работа не завершена. Если он все еще стоит в очереди или работает, подождите и снова запустите этот фрагмент только для чтения; вместо этого проверьте неудавшуюся работу. 302 загружается без пересылки ключа API. Временный ответ проверяется до создания 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, прочитайте оставшиеся фрагменты с помощью get_result, используя тот же ключ API. Используйте точный next_offset, возвращенный инструментом; приведенные ниже значения являются заполнителями.
- Прибавьте каждый кусок в офсетном порядке. Следуйте за next_offset, пока он не станет null.
- Проанализируйте один раз соединённый текст как JSON, а затем запишите полный результат в свой файл или хранилище.
- Сохранить до expires_at. Новые большие ответы могут вытеснить старые результаты до предела 10-минуты; кэш сохраняет четыре на ключ API.
{
"name": "get_result",
"arguments": {
"result_id": "RESULT_ID_FROM_TOOL",
"offset": 16000
}
}Исправить проблемы сохранения и поиска
| Проблема | исправлять |
|---|---|
| Выходной файл уже существует | Сначала проверьте. Для завершения выполнения CLI используйте runs show с новым выходным именем файла вместо отправки другого запроса. |
| CLI не может найти бег | Используйте исходный пользователь OS, профиль и каталог состояния. Если вы сохранили удаленную работу ID, верните эту работу напрямую. |
| 401 / 403 для повторного использования | Запустите flashdata auth status --json и восстановите действительный доступ. Уже сохраненный локальный файл можно прочитать без доступа к API. |
| 409 / 410 | 409: ждите существующей работы. 410: используйте сохраненную копию; временный результат истек. |
| Ошибка диска после запроса | Запуск ID или работа ID. Исправьте хранение и восстановите существующие работы, прежде чем рассматривать новое представление. |
| Архив не имеет манифеста или контрольная сумма не работает | Восстановление или копирование оригинальных файлов. Держите неполный архив для проверки; восстановление архива не требует нового запроса. |
| MCP · result_unavailable | Проверить результат ID, офсет, ключ API и срок действия. Используйте сохраненную копию, если кэш истек; не зацикливайтесь, повторяя оплаченный запрос. |