Обзор документации
Руководства
Запустите фоновую работу для приложения или агента, вернитесь с его сохраненной работы ID и соберите каждый исход партии.
На этой странице
Продолжайте работать после того, как процесс остановится
Используйте фоновое задание для стоящей в очереди задачи приложения или рабочего процесса агента, который может finish позже. Это прохождение выполняет один поиск Google, сохраняет его квитанцию и возобновляет ее в другом процессе.
| Держите | Цель |
|---|---|
| Подтверждение задания | submission.json — сохраняйте принятую работу ID с вашей прикладной задачей и исходным вводом. |
| Экономный ответ | result.json — проверяет источник и результаты перед импортом. |
| Результаты Batch | batch-results/outcomes.json — одна запись на вход, с заданием ID и файлом результата. |
Прежде чем начать
Используйте ключ API с доступом google_search и доступными кредитами. Выберите CLI или HTTP для отправки, ожидания и поиска. Примеры Bash используют jq; HTTP также нуждается в cURL 7.76+. Запустите новую рабочую папку.
Повторно используйте аутентифицированный профиль CLI или FLASHDATA_API_KEY. Подтверждаем, что data.accessVerified является true. Установите FLASHDATA_PROFILE для имени профиля, чтобы его использовали и более поздние скрипты. Если ключ не настроен, сначала используйте руководство по аутентификации CLI.
flashdata auth status --json
flashdata account balance --json
flashdata account limits --jsonДержите терминал открытым для остальных команд. Агенты должны прочитать ключ из своего тайного магазина или окружения.
# 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Запуск фонового поиска
Этот шаг представляет один Google Search. Проверки состояния и поиск результата не отправляют другой запрос. Повторно использовать одни и те же данные на протяжении всего периода.
1. Отправить один раз и сохранить квитанцию
Файл submission.json является вашей квитанцией. HTTP возвращает ссылки на идентификатор, источник, статус и self/results; CLI сохраняет квитанцию по представлению, а также возвращает remoteId. HTTP 200 означает принятый, а не законченный.
flashdata search "battery recycling research" --num 5 \
--mode async --run-id async-first --output submission.json --json(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e submission.json || { echo "Use the saved receipt or a new filename." >&2; exit 1; }
curl --fail-with-body --silent --show-error \
--request POST 'https://data.flashdata.dev/v1/queries' \
--header "X-API-Key: $FLASHDATA_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"source":"google_search","query":"battery recycling research","params":{"num":5}}' \
--output submission.json
jq '{id, source, status, links}' submission.json
)2. Дождитесь существующей работы
Продолжайте, когда работа будет завершена. Если он не удался, проверьте его ошибку, прежде чем отправлять что-либо еще.
Успешное ожидание возвращает data.status: completed в CLI JSON.
(
set -euC
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs wait "$JOB_ID" --timeout 2m --json
)Это проверяется один раз. Повторите GET после короткой задержки, пока job.status находится на рассмотрении или обрабатывается. На 429, ждите Retry-After от job-headers.txt.
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
JOB_ID=$(jq -er '(.remoteId // .id // .submission.id) | select(test("^[A-Za-z0-9_-]+$"))' submission.json)
STATUS_URL="https://api.flashdata.dev/v2/jobs/$JOB_ID"
curl --fail-with-body --silent --show-error \
--header "X-API-Key: $FLASHDATA_API_KEY" \
--max-time 30 --dump-header job-headers.txt --output job.json "$STATUS_URL"
jq -e --arg id "$JOB_ID" '.job.id == $id' job.json >/dev/null
jq '.job | {id, source, status, error}' job.json
){
"job": {
"id": "EXAMPLE_JOB_ID",
"source": "google_search",
"status": "completed",
"error": null
}
}3. Восстановить и сохранить ответ
Сохраните result.json локально. Завершенное задание и его тело результата являются отдельными записями: тело этого поиска содержит источник: google_search, массив результатов и использование. Валидация ниже принимает сохраненный результат выполненного или завершенного статуса успеха.
(
set -euC
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs result "$JOB_ID" --output result.json --json
jq '{source, status, results, usage}' result.json
)Результат JSON по умолчанию перенаправляет на подписанное хранилище. Этот код декомпрессирует сохраненный результат, а также принимает прямой ответ JSON. Только конечная точка FlashData получает ключ API.
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
JOB_ID=$(jq -er '(.remoteId // .id // .submission.id) | select(test("^[A-Za-z0-9_-]+$"))' submission.json)
SOURCE=$(jq -er '(.submission // .).source' submission.json)
jq -e --arg id "$JOB_ID" --arg source "$SOURCE" \
'.job.id == $id and .job.source == $source and .job.status == "completed"' job.json >/dev/null
test ! -e result.json || { echo "Choose a new output filename." >&2; exit 1; }
RESULT_URL="https://api.flashdata.dev/v2/jobs/$JOB_ID/results"
STATUS=$(curl --silent --show-error \
--header "X-API-Key: $FLASHDATA_API_KEY" \
--max-time 120 --dump-header result-headers.txt --output result.pending \
--write-out '%{http_code}' "$RESULT_URL")
case "$STATUS" in
200) ;;
302)
LOCATION=$(awk 'tolower($1) == "location:" { sub(/\r$/, "", $2); print $2 }' result-headers.txt)
# The signed storage URL is fetched WITHOUT the FlashData API key.
curl --fail-with-body --silent --show-error --compressed --max-time 120 --proto '=https' \
--output result.pending "$LOCATION" ;;
*) echo "Result HTTP $STATUS; inspect 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")' result.pending >/dev/null
cat result.pending > result.json
jq '{id, source, status, results, usage}' result.json
)4. Используйте результат в своем приложении
Проверить сохраненный ответ, затем извлечь заголовок, ссылку и фрагмент для просмотра поиска или следующего шага агента. Успешный пустой органический массив означает отсутствие соответствующих элементов; отсутствующее поле или неисправное тело нуждается в исследовании.
| Задание приложения | Переходный период |
|---|---|
| Ждать | Сохраняйте принятую работу ID перед возвращением управления пользователю или агенту. |
| Готовы | Марк готов после того, как результат будет сохранен и подтвержден. Используйте задачу ID в качестве ключа import/upsert. |
| Требует внимания | Сохраняйте работу ID и ошибку. Отказ в проведении опроса или поиск не является просьбой повторно подать заявку. |
jq -e '.source == "google_search" and (.status == "done" or .status == "completed")
and (.results | type == "array")
and all(.results[]; (.organic | type == "array"))' result.json > /dev/null &&
jq -c '.results[] | .organic[] | {title, link, snippet}' result.jsonВозобновление в другом процессе
Откройте новый терминал в той же папке, с тем же credential/profile. Эти команды читают работу в submission.json и сохраняют новое имя файла. Они никогда не подают работы. Повторное использование того же CLI, что и ID, требует его исходного каталога состояния. HTTP сам по себе не разъединяет POST, используя локальный запуск ID.
(
set -eu
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs get "$JOB_ID" --json
flashdata jobs wait "$JOB_ID" --timeout 2m --json
flashdata jobs result "$JOB_ID" --output recovered-result.json --json
)Отправить несколько запросов
Batch предоставляет независимые рабочие места по одному запросу. Этот пример с двумя запросами требует наличия как минимум двух запросов и двух незавершенных рабочих мест; временная пробная версия ограничена одной. Сохраните массив ниже как batch.json в отдельной рабочей папке.
[
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
}
},
{
"source": "google_search",
"query": "lithium battery recycling methods",
"params": {
"num": 5
}
}
]flashdata batch submit --input batch.json \
--run-id batch-first --output batch-submission.json --json(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e batch-submission.json || { echo "Keep the saved batch receipt." >&2; exit 1; }
jq '{queries: .}' batch.json > batch-request.json
curl --fail-with-body --silent --show-error \
--request POST 'https://data.flashdata.dev/v1/queries/batch' \
--header "X-API-Key: $FLASHDATA_API_KEY" \
--header 'Content-Type: application/json' \
--data-binary @batch-request.json --output batch-submission.json
jq '.queries[] | {id, source, status}' batch-submission.json
)Скачать collect-batch.py
Создайте collect-batch.py в рабочей папке Batch рядом с batch.json и batch-submission.json. Скопируйте полный код ниже и сохраните его.
Держите вместе batch.json, batch-submission.json и пакетные результаты. Сценарий останавливается, если сохраненные входы или квитанции меняются. Он повторно использует заполненные локальные файлы и никогда не отправляет запросы на замену после ошибки чтения.
# collect-batch.py — Python 3.10+ and FlashData CLI; no new submissions.
import json
import re
import subprocess
import sys
from pathlib import Path
def read(path):
return json.loads(Path(path).read_text(encoding='utf-8-sig'))
def cli(*args):
result = subprocess.run(['flashdata', *args, '--json', '--non-interactive', '--timeout', '2m'],
check=True, capture_output=True, text=True, encoding='utf-8')
return json.loads(result.stdout)['data']
inputs = read('batch.json')
saved = read('batch-submission.json')
receipts = saved.get('submission', saved)['queries']
if not isinstance(inputs, list) or not inputs or len(inputs) != len(receipts):
raise ValueError('Keep the original batch input and matching receipt.')
ids = [r.get('id', '') for r in receipts]
if len(set(ids)) != len(ids) or any(not re.fullmatch(r'[A-Za-z0-9_-]+', x) for x in ids):
raise ValueError('Invalid or duplicate job IDs.')
folder = Path('batch-results')
folder.mkdir(exist_ok=True)
binding = json.dumps({'inputs': inputs, 'receipts': receipts}, sort_keys=True)
try:
with (folder / 'input-receipts.json').open('x', encoding='utf-8') as file:
file.write(binding)
except FileExistsError:
if (folder / 'input-receipts.json').read_text(encoding='utf-8') != binding:
raise ValueError('Inputs or receipts changed. Restore the original snapshot.')
outcomes = [{'index': index, 'input': request, 'job_id': receipt['id'], 'status': 'unread'}
for index, (request, receipt) in enumerate(zip(inputs, receipts))]
for index, (request, receipt) in enumerate(zip(inputs, receipts)):
job_id = receipt['id']
file = folder / (job_id + '.json')
row = {'index': index, 'input': request, 'job_id': job_id, 'status': 'unread'}
try:
if not file.exists():
try:
job = cli('jobs', 'wait', job_id)
except subprocess.CalledProcessError:
job = cli('jobs', 'get', job_id)
if job['id'] != job_id or job['source'] != request['source']:
raise ValueError('Job does not match the saved receipt/input.')
row.update(status=job['status'], error=job.get('error'))
if job['status'] == 'completed':
cli('jobs', 'result', job_id, '--output', str(file))
if file.exists():
result = read(file)
if (result.get('source') != request['source']
or result.get('status') not in ['done', 'completed']
or not isinstance(result.get('results'), list)):
raise ValueError('Inspect the saved result before importing it.')
row.update(status='completed', result_file=str(file), error=None)
except (OSError, ValueError, KeyError, subprocess.CalledProcessError) as error:
row.update(status='read_error', error=getattr(error, 'stderr', None) or str(error))
outcomes[index] = row
pending = folder / 'outcomes.next'
pending.write_text(json.dumps(outcomes, ensure_ascii=False, indent=2), encoding='utf-8')
pending.replace(folder / 'outcomes.json')
print(index, job_id, row['status'])
print('Saved batch-results/outcomes.json. No queries were submitted.')
sys.exit(0 if all(row['status'] == 'completed' for row in outcomes) else 2)Отслеживайте каждую принятую работу
После сохранения collect-batch.py запустите его из рабочей папки Batch с Python 3.10+ и аутентифицированным CLI. Работает с любым из вышеперечисленных методов. Он считывает каждую квитанцию, выжидает до двух минут за незавершенную работу и сохраняет каждый успешный ответ. Запустите один коллектор за раз; повторите его, чтобы продолжить те же самые работы.
Ожидайте две записи в batch-results/outcomes.json для выборки. Импорт завершенных записей по входному индексу и вакансии ID. Неудачные, отложенные и read_error записи остаются видимыми; выходной код 2 означает просмотр или возобновление их. Коллектор не отправляет новых запросов.
python3 collect-batch.pypython collect-batch.pyjq '.[] | {index, job_id, status, result_file, error}' batch-results/outcomes.jsonПолучить полную версию webhook
Добавьте callback_url рядом с источником, запросом и парамами в одном запросе или в каждой записи Batch. Замените пример URL на приемник. События сообщают о завершении или неудаче; получить результат отдельно.
- Продолжить мероприятие и вернуться 2xx быстро. Deduplicate delivery_id (также пересылается как X-Delivery-Id).
- Мероприятие не подписано. Сопоставьте его идентификатор и источник с сохраненной квитанцией, а затем аутентифицируйте статус, прочитанный с помощью самоссылки оригинала квитанции. Не доверяйте URLs, предоставленному непроверенным событием.
- По завершении, вытащите и сохраните результат. После неудачи проверьте ошибку в работе. Продолжайте опросы в качестве запасного варианта, если не произойдет никакого события.
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
},
"callback_url": "https://your-app.example/webhooks/flashdata"
}{
"delivery_id": "completion:EXAMPLE_JOB_ID",
"id": "EXAMPLE_JOB_ID",
"source": "google_search",
"status": "completed",
"links": [
{
"rel": "self",
"href": "https://api.flashdata.dev/v2/jobs/EXAMPLE_JOB_ID",
"method": "GET"
},
{
"rel": "results",
"href": "https://api.flashdata.dev/v2/jobs/EXAMPLE_JOB_ID/results",
"method": "GET"
}
]
}Обратная связь URL
Используйте публичный HTTPS URL на порте 443, максимум символов 2,048, без учетных данных или фрагмента. Каждый разрешенный IP должен быть публичным. Omit callback_url, или использовать null или пустую строку, чтобы отключить уведомления.
Восстановление существующей работы
| Положение | Что делать |
|---|---|
| Представление отсрочено | Проверить runs show async-first и аккаунт History. runs recover может получить принятую работу IDs; если ID не был сохранен, согласуйте представление перед отправкой другого POST. |
| pending / processing | Проверяйте существующую работу. Эти государства не являются провалами. |
| failed / 422 | Прочитайте job.error, исправьте причину и решите, следует ли подавать новую работу. |
| 429 | Честь Retry-After. Сократить параллель между представлением, если вместимость отложенной работы заполнена. |
| 404 / 409 | 404: проверьте ID и отправьте счет. 409: результаты еще не готовы. |
| 410 | Срок действия JSON истекает через несколько часов после завершения 24. Используйте сохраненную копию. Средства массовой информации, уже доставленные на ваше хранилище, следуют политике хранения. |
Работать в YouTube Download?
Загрузка использует Async или Batch и требует ключа API владельца с доступом youtube_download плюс хранилище назначения. Его результат JSON описывает медиа, уже доставленные в ваше корзину; конечная точка результатов не передает потоковые видео байты. Используйте руководство по загрузке для настройки хранилища и проверки доставленного файла.
Хосты и форматы ответов
Все четверо используют X-API-Key. Используйте тот же ключ, что и в представлении. Статус и результаты чтения являются бесплатными, но ограничены по ставке. Примеры используют JSON; выберите Accept и X-Respond-With в конструкторе для других представлений результатов. Подписанная загрузка хранилища использует URL без ключа FlashData.
| Операция | Конечная точка |
|---|---|
| Отправить одну работу | POST https://data.flashdata.dev/v1/queries |
| Отправить партию | POST https://data.flashdata.dev/v1/queries/batch |
| Статус чтения | GET https://api.flashdata.dev/v2/jobs/{id} |
| Читать результаты | GET https://api.flashdata.dev/v2/jobs/{id}/results |
Поддерживаемые источники и режимы
Используйте конструктор ниже для текущих параметров источника. Google Search и YouTube Data поддерживают фоновые задания. YouTube Download использует фоновые задания и хранилище назначения. Для большого файла видео IDs с общими опциями используйте руководство Bulk.
Создайте рабочий процесс для вашего источника
Выберите источник, отредактируйте его параметры и скопируйте сгенерированный рабочий процесс на вашем языке. Включите обратный вызов, чтобы показать пример приемника. Этот конструктор просматривает код и образцы ответов; запросы запускаются только при выполнении кода или использовании консоли.
Создать запрос
Дополнительные параметры
Начинается с 1. Каждая страница представляет собой отдельный запрос.
Фильтр времени Google, такой как qdr:d за прошедший день.
Завершение webhook
Полезная нагрузка Webhook, проверка и повторные попыткиMarkdown применяется к полученным результатам. Квитанции и статус работы сохраняют свои первоначальные поля.
https://data.flashdata.dev/v1/queries