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

Довідник API

Realtime та async

Отримати результати у відповідь, або подавати роботу і отримати їх пізніше. Виберіть, як працює ваш додаток або агент.

На цій сторінці

Виберіть режим запиту

Google Search і YouTube Data підтримують обидва режими. YouTube Download вимагає асинхрону, Batch або Bulk; він не підтримує в режимі реального часу. Параметри джерела залишаються однаковими при переході від в режимі реального часу до асинхрону.

КОМПЛЕКСВикористовуйте колиЩо ви отримуєте
RealtimeРезультат пошуку необхідний в поточній взаємодії.В результаті тіла в тій же відповіді HTTP.
AsyncРобота повинна продовжуватися після того, як ваш процес відключається, або ви завантажуєте медіа.Робота ID відразу; статус fetch і результати окремо.
Запит життєвого циклу
Realtime POST data.flashdata.dev/v1/queries/realtime → результати
Async POST data.flashdata.dev/v1/queries → робота ID
          GET api.flashdata.dev/v2/jobs/{id} → статус
          GET api.flashdata.dev/v2/jobs/{id}/results → результати

Надіслати запит

Набір FLASHDATA_API_KEY до ключа, що дозволяє google_search. Виберіть в режимі реального часу або асинхронізацію; кожен подач працює на один зарахований пошук. Зберігайте скрипти, чеки та результати в тій же новій папці.

Python використовує Python 3.10+ і запити. Кожен скрипт працює самостійно і прочитає збережені файли з попередніх кроків. Про нас cURL альтернативні потреби Bash, cURL 7.76+ й jq.

Python · встановити один раз
python3 -m pip install requests

Realtime: отримати результат зараз

POST /v1/queries/realtime повертає status: done і масив результатів. Читання result.json; не потрібно опитування.

Заощаджуйте як realtime.py і запустіть python3 realtime.py.

realtime.py
import json
import os
from pathlib import Path

import requests

response = requests.post(
    "https://data.flashdata.dev/v1/queries/realtime",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    json={"source": "google_search", "query": "battery recycling research", "params": {"num": 5}},
    timeout=120, allow_redirects=False,
)
response.raise_for_status()
result = response.json()
Path("result.json").write_text(json.dumps(result, indent=2), encoding="utf-8")
print(json.dumps(result, indent=2))

Async: зберегти квитанцію

POST /v1/queries повертає передню квитанцію, а не результати пошуку. Заощаджуйте submission.json і продовжуйте з статусом і виконайте запити нижче.

Заощаджуйте як submit_async.py і запустіть python3 submit_async.py.

submit_async.py
import json
import os
from pathlib import Path

import requests

response = requests.post(
    "https://data.flashdata.dev/v1/queries",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    json={"source": "google_search", "query": "battery recycling research", "params": {"num": 5}},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
result = response.json()
Path("submission.json").write_text(json.dumps(result, indent=2), encoding="utf-8")
print(json.dumps(result, indent=2))
Накопичення поля · аббревіатурний приклад
{
  "id": "job_EXAMPLE",
  "source": "google_search",
  "status": "pending"
}

Перевірити роботу асинхрону

Читати далі job.status за допомогою ID в submission.json. Для затримки або обробки чекайте затримку Retry-After до повторної перевірки; Python друкує його і cURL зберігає його в status-headers.txt. Використовуйте зворотний зв'язок, якщо не повертається. Успішний запит про статус не означає завершення роботи.

job.statusПопередня дія
pending / processingЗачекайте, після чого перевірте одну і ту ж роботу ID знову.
completedОтримати збережений результат.
failedЧитати job.error. Виправлення причини перед поданням нової роботи.

Заощаджуйте як job_status.py і запустіть python3 job_status.py.

job_status.py
import json
import os
from pathlib import Path

import requests

job_id = json.loads(Path("submission.json").read_text(encoding="utf-8"))["id"]
response = requests.get(
    f"https://api.flashdata.dev/v2/jobs/{job_id}",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
Path("job.json").write_text(json.dumps(response.json(), indent=2), encoding="utf-8")
print(json.dumps(response.json()["job"], indent=2))
print("Retry-After:", response.headers.get("Retry-After", "not provided"))

Отримати завершений результат

Запустіть це після завершення job.status. Відповідність результатів за замовчуванням - 302: пункти розташування до підписаного сховища URL. Два запити нижче тримати ключ API на FlashData і зберегти оригінальний JSON до result.json. Для YouTube Download це JSON описує медіа, що доставляються до сховища; це не відео або аудіо файл.

Заощаджуйте як job_result.py і запустіть python3 job_result.py.

job_result.py
import json
import os
from pathlib import Path

import requests

receipt = json.loads(Path("submission.json").read_text(encoding="utf-8"))
job_id = receipt["id"]
response = requests.get(
    f"https://api.flashdata.dev/v2/jobs/{job_id}/results",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 302:
    raise RuntimeError(f"Expected a result redirect, got {response.status_code}")
url = response.headers["Location"]
if not url.startswith("https://"):
    raise ValueError("Expected an HTTPS storage URL")

# A separate request: no FlashData key is sent to storage.
result = requests.get(url, timeout=120)
result.raise_for_status()
data = result.json()  # Requests automatically decodes Content-Encoding: gzip.
Path("result.json").write_text(json.dumps(data, indent=2), encoding="utf-8")
print(json.dumps(data, indent=2))

Затримки та збої

СитуаціяЩо робити
Відхилений термін діїА.А. POST вже було прийнято. Перевірити збережену історію отримання та облікового запису перед переадресацією; повторні ПОСТи можуть створювати нові вексельні роботи.
409 · result_not_readyТримайте статус опитування. Не створювати ще одну роботу.
422 · result_not_readyРобота не вдалося. Прочитати job.error перед переробкою.
429Заслужений Retry-After або retry_after; зменшити швидкість подачі при повній потужності.
410 · result_expiredЗберігайте результати затримки 24 після завершення. Використовуйте збережену копію.