Переглянути документацію
Посібники
Запустіть фонову роботу для програми або агента, відновіть від його збереженої роботи 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. Використовуйте результат у додатку
Дійсніть збережену відповідь, потім витягніть назву, посилання та snippet для перегляду пошуку або наступного кроку агента. Успішний порожній органічний масив означає, що не відповідає предметам, відсутній поле або не вдалося вивчити потреби тіла.
| Завдання програми | Перехід |
|---|---|
| Офіціант | Поспішати прийнятий роботу 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 сам не deduplicate POSTs за допомогою цього локального запуску 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Отримувати вебхоок
Додати джерело callback_url, запит та параметри в одному запиті або кожен запис Batch. Замініть приклад URL з приймачем. Заяви про завершення або відмову від звітів, отримання результату окремо.
- Потрібні дати і повернути 2xx оперативно. Deduplicate delivery_id (також відправлений як X-Delivery-Id).
- Захід не відзначається. Зробіть свій 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-перший і рахунок 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 access плюс пункт призначення. Його результат 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 для останнього дня.
Markdown діє до готових результатів. Одержувачі та статус роботи зберігають свої оригінальні поля.
https://data.flashdata.dev/v1/queries