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

Руководства

Async и пакетные запросы

Запустите фоновую работу для приложения или агента, вернитесь с его сохраненной работы ID и соберите каждый исход партии.

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

Продолжайте работать после того, как процесс остановится

Используйте фоновое задание для стоящей в очереди задачи приложения или рабочего процесса агента, который может finish позже. Это прохождение выполняет один поиск Google, сохраняет его квитанцию и возобновляет ее в другом процессе.

ДержитеЦель
Подтверждение заданияsubmission.json — сохраняйте принятую работу ID с вашей прикладной задачей и исходным вводом.
Экономный ответresult.json — проверяет источник и результаты перед импортом.
Результаты Batchbatch-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. Используйте результат в своем приложении

Проверить сохраненный ответ, затем извлечь заголовок, ссылку и фрагмент для просмотра поиска или следующего шага агента. Успешный пустой органический массив означает отсутствие соответствующих элементов; отсутствующее поле или неисправное тело нуждается в исследовании.

Задание приложенияПереходный период
ЖдатьСохраняйте принятую работу 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 сам по себе не разъединяет POST, используя локальный запуск 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

Получить полную версию webhook

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

  1. Продолжить мероприятие и вернуться 2xx быстро. Deduplicate delivery_id (также пересылается как X-Delivery-Id).
  2. Мероприятие не подписано. Сопоставьте его идентификатор и источник с сохраненной квитанцией, а затем аутентифицируйте статус, прочитанный с помощью самоссылки оригинала квитанции. Не доверяйте 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-first и аккаунт 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 плюс хранилище назначения. Его результат 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 применяется к полученным результатам. Квитанции и статус работы сохраняют свои первоначальные поля.

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