Перейти к содержимому
RU
Ключ API
Обзор документации

Руководства

Сохранить и повторно использовать результаты

Сохраняйте результат с его исходным вводом, исходными ссылками и использованием, а затем передавайте его другому процессу без другого запроса.

На этой странице

Запрос один раз, используйте результат в задачах

Создайте отчет, повторите анализ или дайте более позднему агенту те же доказательства. Этот рабочий процесс сохраняет один поиск в качестве переносного архива; чтение этого архива не требует ни ключа 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 --json

1. Сохраните ввод и сохраните один ответ

Спасти request.json Внизу, затем выполните одну команду. --input Использует этот точный запрос; сохраняйте файл неизменным после этого. --output спасает API тело в search.json; --json отпечатки CLI Сберегаемый поиск - это локальный запуск этой задачи ID.

request.json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}
Запуск одного поиска
flashdata query --input request.json \
  --run-id saved-search --output search.json --json

2. Проверить сохраненный ответ

Источник: google_search, status: done и массив результатов. Печать названия каждого органического результата, ссылки и фрагмента. Фактические результаты варьируются; пустая удачная коллекция отличается от неудавшейся заявки или отсутствующего поля.

Проверить и прочитать 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. Архив входа, ответа и цитат

Сохраните archive.py ниже, затем запустите его с помощью запуска ID с шага 1. Он сохраняет необработанные файлы, извлекает исходные ссылки и пишет manifest.json последний с контрольными суммами файлов и использованием. Ожидайте complete: true; количество ссылок зависит от результатов поиска. Сетевые запросы не принимаются.

Скачать archive.py

Создайте archive.py рядом с request.json и search.json в рабочей папке. Скопируйте полный код ниже и сохраните его.

В примере архивируются результаты Google Search. Существующие архивные каталоги держатся в неприкосновенности. Держите request.json, search.json и сопоставление вместе до завершения архивирования.

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

Создайте архив

Запустите папку с archive.py, request.json и search.json.

Постройте новый архив
python3 archive.py --run-id saved-search

4. Повторное использование архива без учетных данных

Сохраните reuse.py ниже. Скопируйте полную папку archive/saved-search в нужный ей процесс, затем запустите этот считыватель. Он проверяет каждый файл перед печатью оригинального запроса, использования и цитирования. Он работает после отзыва ключа API или истечения срока действия хостинга, потому что он читает только сохраненную копию.

Скачать reuse.py

Создание reuse.py в рабочей папке, содержащей archive/. На другом компьютере скопируйте как reuse.py, так и полный каталог archive/saved-search, сохранив этот макет.

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

Читайте сохраненный архив

Сохраните reuse.py, а затем выполните его из папки. Последний аргумент — путь к копируемому архиву.

Прочитайте скопированный архив
python3 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, получение заявки и результат JSON24 часов после завершения
BulkМанифест и все части NDJSON24 через несколько часов после завершения работы; проверьте expiresAt
YouTube DownloadДоставка JSON и медиа в пункт назначенияДоставка JSON: удержание работы. Медиа: ваш жизненный цикл
MCP кэш-памятьПолностью собранный результат10 минуты; сохранены только четыре самых новых больших результата на ключ API

Держите вместо этого небольшую коляску

Оставьте первоначальный ответ без изменений. Сохраните небольшую коляску с вводом, источником, сэкономьте время и использование, чтобы более поздний процесс мог понять, что произвел файл. Храните исходные URLs и временные метки видео при преобразовании результатов.

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
)

Сохранение напрямую с помощью 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
Сохранить ответ 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
)

Сохранить существующую фоновую работу

Используйте 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
)

Сохраните каждую часть результата Bulk

Замените BULK_ID на ID в квитанции о представлении. После завершения работы CLI следует за манифестом и сохраняет каждую часть в виде одного файла NDJSON. Сохраняйте манифест, когда вам нужны подсчеты и части метаданных.

Файл может содержать как успешные, так и неудавшиеся строки. Согласуйте входные индексы и подсчеты, прежде чем пометить всю задачу. Не перезапускайте весь вводный файл, чтобы восстановить одну неудачную строку.

Соберите выполненную работу
flashdata bulk results BULK_ID --output bulk-results.ndjson --timeout 30m --json

Храните запись доставки и носители

delivery.json содержит запись доставки, а не видео или аудио байты. Сохраните свой URL, размер и контрольную сумму вместе с задачей. Средства массовой информации живут в вашем хранилище назначения и следуют за жизненным циклом этого хранилища.

Для частного назначения используйте учетные данные этого провайдера или подписанный URL для проверки объекта. Отсутствующий временный результат JSON не означает, что ваши сохраненные носители были удалены.

Проверьте сохраненный результат загрузки · jq
jq '.results[] | {file_url, file_size, md5, downloaded_bytes, output_format}' delivery.json

Соберите куски MCP перед сохранением

Когда инструмент возвращает result_id, chunk и next_offset, прочитайте оставшиеся фрагменты с помощью get_result, используя тот же ключ API. Используйте точный next_offset, возвращенный инструментом; приведенные ниже значения являются заполнителями.

  1. Прибавьте каждый кусок в офсетном порядке. Следуйте за next_offset, пока он не станет null.
  2. Проанализируйте один раз соединённый текст как JSON, а затем запишите полный результат в свой файл или хранилище.
  3. Сохранить до expires_at. Новые большие ответы могут вытеснить старые результаты до предела 10-минуты; кэш сохраняет четыре на ключ API.
MCP tools/call Аргументы
{
  "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 / 410409: ждите существующей работы. 410: используйте сохраненную копию; временный результат истек.
Ошибка диска после запросаЗапуск ID или работа ID. Исправьте хранение и восстановите существующие работы, прежде чем рассматривать новое представление.
Архив не имеет манифеста или контрольная сумма не работаетВосстановление или копирование оригинальных файлов. Держите неполный архив для проверки; восстановление архива не требует нового запроса.
MCP · result_unavailableПроверить результат ID, офсет, ключ API и срок действия. Используйте сохраненную копию, если кэш истек; не зацикливайтесь, повторяя оплаченный запрос.