Перейти до вмісту
UK
Отримати ключ API
Переглянути документацію

Посібники

Async & пакетні запити

Запустіть фонову роботу для програми або агента, відновіть від його збереженої роботи 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

Запуск фонового пошуку

Цей прохід подає один Google Search. Перевірка стану та перевизначення результату не подають іншого запиту. Використовуйте однакові значення протягом усього.

1. Подати заявку і зберігати чек

Файл submission.json є вашим квитанцією. HTTP повертає ідентифікатор, джерело, статус та посилання self/results; CLI заощаджує надходження під подання, а також повертає remoteId. HTTP 200 приймається, не завершується.

Bash · FlashData CLI
flashdata search "battery recycling research" --num 5 \
  --mode async --run-id async-first --output submission.json --json

2. Очікується існуючої роботи

Продовжити роботу при заповненні роботи. Якщо це не вдалося, перевірте свою помилку перед поданням будь-якого іншого.

Успішне очікування повертає data.status: completed в CLI JSON.

Bash · FlashData CLI
(
set -euC
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs wait "$JOB_ID" --timeout 2m --json
)

3. Отримати і зберегти відповідь

Заощаджуйте result.json локально. Закінчена робота і її результат тіло є окремими записами: це тіло пошуку містить джерело: google_search, масив результатів і використання. Усиновлення нижче приймає виконаний або завершений статус результату.

Bash · FlashData CLI
(
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
)

4. Використовуйте результат у додатку

Дійсніть збережену відповідь, потім витягніть назву, посилання та snippet для перегляду пошуку або наступного кроку агента. Успішний порожній органічний масив означає, що не відповідає предметам, відсутній поле або не вдалося вивчити потреби тіла.

Завдання програмиПерехід
ОфіціантПоспішати прийнятий роботу ID перед тим як повернути контроль користувача або агента.
Про насПозначте готовий після того, як результат зберігається і діє. Використовуйте своє завдання ID як ключ import/upsert.
Потрібна увагаЗберігайте роботу ID і похибку. Недокладна відмова від випилювання або перерозподілу не є запитом повторно подати.
Читати локальну відповідь · без викликів API
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.

CLI + jq · відновити збережену роботу
(
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 в окремій робочій папці.

batch.json
[
  {
    "source": "google_search",
    "query": "battery recycling research",
    "params": {
      "num": 5
    }
  },
  {
    "source": "google_search",
    "query": "lithium battery recycling methods",
    "params": {
      "num": 5
    }
  }
]
Bash · FlashData CLI
flashdata batch submit --input batch.json \
  --run-id batch-first --output batch-submission.json --json

Зберегти collect-batch.py

Список collect-batch.py в Batch робоча папка біля batch.json і batch-submission.json. Скопіюйте загальний код нижче в ньому і заощаджуйте його.

Зареєструватися batch.json, batch-submission.json і партії-результи / разом. Скрипт припиняється, якщо збережені вводи або зміни квитанцій. За допомогою локальних файлів і ніколи не подає запит на заміну після помилки читання.

collect-batch.py
# 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 означає огляд або відновити їх. Збірник відправляє не нові запити.

Bash
python3 collect-batch.py
PowerShell 7
python collect-batch.py
Читати кожен результат · jq
jq '.[] | {index, job_id, status, result_file, error}' batch-results/outcomes.json

Отримувати вебхоок

Додати джерело callback_url, запит та параметри в одному запиті або кожен запис Batch. Замініть приклад URL з приймачем. Заяви про завершення або відмову від звітів, отримання результату окремо.

  1. Потрібні дати і повернути 2xx оперативно. Deduplicate delivery_id (також відправлений як X-Delivery-Id).
  2. Захід не відзначається. Зробіть свій id і джерело, щоб ваш збережений квитанція, а потім автентифікуйте читання статусу за допомогою саморегулятора. Не довіряйте URLs, що надавалася неперевершеним подіям.
  3. На завершеному, фіксують і зберігають результат. Про не вдалося, перевіряючи похибку роботи. Зберігайте опитування, якщо не прибуває події.
Запит тіла з зворотним викликом
{
  "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 / 409404: перевірте 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 для останнього дня.

Веб-сайтWebhook перезавантаження, перевірка та речення

Markdown діє до готових результатів. Одержувачі та статус роботи зберігають свої оригінальні поля.

POSThttps://data.flashdata.dev/v1/queries
import gzip
import json
import random
import time
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"
payload = {
    "source": "google_search",
    "query": "openai",
    "params": {
        "gl": "us",
        "hl": "en",
        "num": 10,
        "page": 1,
    },
}

def api_get(url):
    request = urllib.request.Request(url, headers={"X-API-Key": api_key})
    with urllib.request.urlopen(request, timeout=60) as response:
        return json.load(response), response.headers

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, request, file_pointer, code, message, headers, new_url):
        return None

def read_result(url):
    request = urllib.request.Request(url, headers={"X-API-Key": api_key})
    try:
        with urllib.request.build_opener(NoRedirect).open(request, timeout=60):
            raise RuntimeError("Expected a result redirect")
    except urllib.error.HTTPError as response:
        if response.code != 302 or not response.headers.get("Location"):
            raise
        storage_url = response.headers["Location"]
        response.close()
    # Never forward the API key to storage.
    with urllib.request.urlopen(urllib.request.Request(storage_url, headers={"Accept-Encoding": "gzip"}), timeout=60) as response:
        content = response.read()
        if response.headers.get("Content-Encoding") == "gzip":
            content = gzip.decompress(content)
        return json.loads(content)

def link(job, relation):
    return next(item["href"] for item in job["links"] if item["rel"] == relation)

request = urllib.request.Request(
    "https://data.flashdata.dev/v1/queries",
    data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
    headers={"Content-Type": "application/json", "X-API-Key": api_key},
    method="POST",
)
with urllib.request.urlopen(request, timeout=120) as response:
    submission = json.load(response)
jobs = submission.get("queries", [submission])
for submitted in jobs:
    print("Job:", submitted["id"])
    deadline = time.monotonic() + 300
    while time.monotonic() < deadline:
        status, headers = api_get(link(submitted, "self"))
        job = status.get("job", status)
        if job["status"] == "completed":
            result = job.get("result") if submitted["source"] == "youtube_download" and job.get("result") is not None else read_result(link(submitted, "results"))
            print(json.dumps(result, ensure_ascii=False, indent=2))
            break
        if job["status"] == "failed":
            raise RuntimeError(f"{submitted['id']}: {job.get('error', 'Job failed')}")
        hint = headers.get("Retry-After", "1")
        delay = max(1, min(5, int(hint))) if hint.isdigit() else 5
        time.sleep(min(delay * random.uniform(1, 1.2), max(0, deadline - time.monotonic())))
    else:
        raise TimeoutError(f"Still running; save this job ID: {submitted['id']}")
Отримання роботи, після чого опитування за результатамиавтентифікації X-API-Key