Lewati ke isi
ID
Dapatkan kunci API
Jelajahi dokumentasi

Panduan

Async Permintaan & batch

Jalankan pekerjaan latar belakang untuk aplikasi atau agen, lanjutkan dari pekerjaannya yang disimpan ID dan mengumpulkan setiap hasil batch.

Di halaman ini

Lanjutkan pekerjaan setelah proses Anda berhenti

Gunakan pekerjaan latar belakang untuk antrian tugas aplikasi atau suatu agen workflow yang dapat finish nanti. Ini walkthrough berjalan satu Google pencarian, menyimpan penerimaan dan resume dari bahwa penerimaan dalam proses lain.

SimpanTujuan
Bukti penerimaan pekerjaansubmission.json - pertahankan pekerjaan yang diterima ID dengan tugas aplikasi Anda dan masukan asli.
Respon tersimpanresult.json - memvalidasi sumber dan hasilnya sebelum mengimpornya.
Batch keluarbatch-results/outcomes.json - satu entri per masukan, dengan pekerjaan ID dan berkas hasil.

Sebelum Anda mulai

Gunakan kunci API dengan akses google_search dan kredit yang tersedia. Pilih CLI atau HTTP untuk penyerahan, menunggu dan mengambil. Contoh Bash menggunakan jq; HTTP juga membutuhkan cURL 7.76 +. Jalankan dalam folder kerja baru.

Gunakan lagi profil CLI terotentikasi atau FLASHDATA_API_KEY. Konfirmasikan data.accessVerified adalah true. Set FLASHDATA_PROFILE untuk profil bernama jadi kemudian script menggunakannya juga. Jika tak ada kunci yang dikonfigurasi, gunakan panduan otentikasi CLI terlebih dahulu.

Cek akses dan akun bebas
flashdata auth status --json
flashdata account balance --json
flashdata account limits --json

Jalankan pencarian latar belakang

Ini walkthrough menyerahkan satu Google Search. Pemeriksaan status dan pengambilan hasil tidak mengirimkan kueri lain. Gunakan kembali kredensial yang sama di seluruh.

1. Kirim sekali dan menyimpan tanda terima

Berkas submission.json adalah tanda terimanya. HTTP mengembalikan sebuah id, sumber, status dan link self/results; CLI menyimpan tanda terima di bawah pengiriman dan juga mengembalikan remoteId. HTTP 200 berarti diterima, belum selesai.

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

2. Tunggu pekerjaan yang sudah ada

Lanjutkan ketika pekerjaan selesai. Jika gagal, periksa kesalahannya sebelum mengirimkan hal lain.

Sebuah menunggu yang sukses kembali data.status: completed in 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. Ambil dan simpan respon

Simpan result.json lokal. Pekerjaan yang selesai dan hasilnya adalah catatan yang terpisah: tubuh pencarian ini berisi sumber: google_search, hasil array dan penggunaan. Validasi di bawah ini menerima hasil yang disimpan dilakukan atau menyelesaikan status sukses.

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. Gunakan hasil dalam aplikasi Anda

Validasi respon tersimpan, kemudian ekstrak judul, link, dan snippet untuk suatu tampilan pencarian atau langkah selanjutnya agen. Array organik yang sukses berarti tidak ada item yang cocok; bidang yang hilang atau tubuh yang gagal perlu diselidiki.

Tugas aplikasiTransisi
MenungguPersist pekerjaan yang diterima ID sebelum kembali kontrol ke pengguna atau agen.
SiapMark siap setelah hasil disimpan dan disahkan. Gunakan tugas Anda ID sebagai kunci import/upsert.
Butuh perhatianMenjaga pekerjaan ID dan kesalahan. Penghitungan waktu pemungutan suara atau kegagalan pengambilan bukan permintaan untuk mengirimkan lagi.
Baca respon lokal yang dipanggil 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

Lanjutkan dalam proses lain

Buka terminal baru dalam folder yang sama, dengan credential/profile. yang sama Perintah-perintah ini membaca tugas dalam submission.json dan menyimpan ke nama berkas baru. Mereka tidak pernah menyerahkan pekerjaan. Menggunakan kembali CLI yang sama menjalankan ID memerlukan direktori asli negara bagian; HTTP sendiri tidak mendeduplikasi POSTs menggunakan lokal run 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
)

Kirim beberapa pertanyaan

Batch menyerahkan pekerjaan independen dalam satu permintaan. Contoh dua pertanyaan ini membutuhkan kapasitas setidaknya dua pertanyaan dan dua pekerjaan yang tertunda; percobaan sementara terbatas pada satu. Simpan array di bawah ini sebagai batch.json dalam sebuah folder kerja terpisah.

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

Simpan collect-batch.py

Buat collect-batch.py dalam folder kerja Batch di samping batch.json dan batch-submission.json. Salin kode lengkap di bawah ini dan simpan.

Jaga batch.json, batch-submission.json dan hasil-hasil batch- bersama-sama. Naskah berhenti jika masukan disimpan atau perubahan tanda terima. Ia memakai kembali berkas lokal yang telah selesai dan tidak pernah menyerahkan kueri pengganti setelah kesalahan pembacaan.

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)

Lacak setiap pekerjaan yang diterima

Setelah menabung collect-batch.py, menjalankannya dari Batch bekerja folder dengan Python 3.10+ dan yang terotentikasi CLI. Ini bekerja dengan metode pengiriman baik di atas. Ini membaca setiap tanda terima, menunggu dua menit untuk pekerjaan yang belum selesai dan menyimpan setiap respon sukses. Menjalankan satu kolektor pada satu waktu; jalankan ulang untuk melanjutkan pekerjaan yang sama.

Mengharapkan dua entri dalam batch-results/outcomes.json untuk sampel. Impor entri selesai oleh indeks masukan dan tugas ID. Gagal, tertunda dan read_error entri tetap terlihat; kode keluar 2 berarti review atau resume mereka. Kolektor tidak mengirim pertanyaan baru.

Bash
python3 collect-batch.py
PowerShell 7
python collect-batch.py
Baca setiap hasil jq
jq '.[] | {index, job_id, status, result_file, error}' batch-results/outcomes.json

Menerima sebuah webhook pelengkapan

Tambahkan callback_url di samping sumber, query dan param dalam satu permintaan atau setiap entri Batch. Ganti contoh URL dengan penerima Anda. Laporan kejadian selesai atau gagal; ambil hasilnya secara terpisah.

  1. Persist acara dan kembali 2xx segera. delivery_id yang terduplikasi (juga dikirim sebagai X-Delivery-Id).
  2. Acara ini belum ditandatangani. Cocok dengan id dan sumber ke tanda terima tersimpan Anda, kemudian mengotorisasi status yang dibaca menggunakan nota asli 's self link. Jangan percaya URLs diberikan oleh sebuah peristiwa yang belum diverifikasi.
  3. Setelah selesai, ambil dan simpan hasilnya. Pada gagal, memeriksa kesalahan pekerjaan. Tetap polling sebagai fallback jika tidak ada acara tiba.
Meminta tubuh dengan callback
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
Tubuh acara
{
  "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"
    }
  ]
}

Callback persyaratan URL

Gunakan publik HTTPS URL pada port 443, paling banyak karakter 2,048, tanpa kredensial atau fragmen. Setiap IP yang diselesaikan harus dipublikasikan. Abaikan callback_url, atau gunakan null atau string kosong, untuk menonaktifkan pemberitahuan.

Mengembalikan pekerjaan yang telah ada

SituasiYang perlu dilakukan
Waktu submisi habisInspeksi runs show async-first dan account History. runs recover dapat mengambil pekerjaan yang diterima IDs; jika tidak ID diselamatkan, mendamaikan penyerahan sebelum mengirim yang lain POST.
pending / processingTerus periksa pekerjaan yang ada. Negara bagian ini bukanlah kegagalan.
failed / 422Baca job.error, perbaiki penyebabnya dan putuskan apakah akan mengirimkan pekerjaan baru.
429Kehormatan Retry-After. Mengurangi konkusi pengiriman jika kapasitas pekerjaan pending- penuh.
404 / 409404: periksa ID dan masukkan akun. 409: hasil belum siap.
410Hasil tersimpan JSON kadaluarsa 24 jam setelah penyelesaian. Gunakan salinan disimpan Anda. Media sudah dikirim ke tempat penyimpananmu mengikuti kebijakan penyimpanan itu.

Menjalankan YouTube Download?

Unduh menggunakan asinc atau Batch dan membutuhkan pemilik kunci API dengan akses youtube_download ditambah penyimpanan tujuan. Hasilnya JSON menjelaskan media telah dikirim ke ember Anda; hasil titik akhir tidak stream video bytes. Gunakan panduan Unduh untuk menata penyimpanan dan verifikasi berkas yang dikirim.

Format host dan respon

Semua empat menggunakan X-API-Key. Gunakan kunci yang sama dengan pengiriman. Status dan hasil baca bebas, tapi rate- terbatas. Contoh-contoh tersebut menggunakan JSON; pilih Accept dan X-Respond-With dalam pembangun untuk representasi hasil lainnya. Sebuah download penyimpanan ditandatangani menggunakan URL nya, tanpa kunci FlashData.

OperasiEndpoint
Kirim satu pekerjaanPOST https://data.flashdata.dev/v1/queries
Ajukan suatu batchPOST https://data.flashdata.dev/v1/queries/batch
Baca statusGET https://api.flashdata.dev/v2/jobs/{id}
Hasil bacaGET https://api.flashdata.dev/v2/jobs/{id}/results

Sumber dan mode yang didukung

Gunakan pembangun di bawah ini untuk parameter sumber saat ini. Google Search dan YouTube Data mendukung pekerjaan latar belakang. YouTube Download menggunakan pekerjaan latar belakang dan penyimpanan tujuan. Untuk berkas besar video IDs dengan opsi bersama, gunakan panduan Bulk.

Bangun suatu alur kerja bagi sumber Anda

Pilih sumber, sunting parameter dan salin alur kerja yang dihasilkan dalam bahasa Anda. Aktifkan callback untuk mengungkapkan contoh penerima. Pembangunan ini pratilik kode dan tanggapan sampel; permintaan hanya dijalankan ketika Anda mengeksekusi kode atau menggunakan konsol.

Parameter sumber

Buat permintaan

Parameter lanjutan

Dimulai dari 1. Setiap halaman merupakan permintaan terpisah.

Filter waktu Google, seperti qdr:d untuk 24 jam terakhir.

Pengait web penyelesaianMuatan Webhook, verifikasi, dan coba lagi

Markdown berlaku untuk hasil selesai. Tanda terima dan status pekerjaan menjaga bidang asli mereka.

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']}")
Tanda terima Job, lalu jajak pendapat untuk hasilOtentikasi X-API-Key