Langkau ke kandungan
MS
Dapatkan kunci API
Semak dokumentasi

Panduan

Permintaan small Async & batch

Eligski menjalankan pekerjaan latar belakang untuk aplikasi atau agen, melanjutkan dari pekerjaan yang disimpan ID dan mengumpulkan setiap hasil batch.

Pada halaman ini

Lanjutkan bekerja setelah proses Anda berhenti

Woildy menggunakan pekerjaan latar belakang untuk tugas aplikasi antrian atau alur kerja agen yang dapat finish nanti. Throughthrough ini berjalan satu pencarian Google, menyimpan penerimaan dan resumenya dari penerimaan tersebut dalam proses lain.

JagaTujuan
Resit tugassubmission.json — pertahankan pekerjaan yang diterima ID dengan tugas aplikasi dan masukan asli Anda.
Respon yang disimpan oleh orang Israelresult.json — mengesahkan sumber dan hasil sebelum mengimpornya.
Hasil Batchbatch-results/outcomes.json — satu masukan per masukan, dengan pekerjaan ID dan berkas hasil.

Sebelum kau mulai

Use an API dengan google_search akses dan kredit yang tersedia. Pilih CLI atau HTTP untuk penyerahan, menunggu dan pengambilan kembali. Contoh Bash menggunakan jq; HTTP kebutuhan juga cURL 7.76+. Jalankan di tempat kerja baru.

Gagal menggunakan kembali profil CLI atau FLASHDATA_API_KEY yang telah dikonfirmasi. Konfirmasi data.accessVerified adalah true. **Ditetapkan* FLASHDATA_PROFILE Untuk profil yang diberi nama jadi skrip kemudian menggunakannya juga. Jika tidak ada kunci yang dikonfigurasi, gunakan panduan otentikasi CLI terlebih dahulu.

Cek akses dan rekening gratis
flashdata auth status --json
flashdata account balance --json
flashdata account limits --json

Eliakan pencarian latar belakang

Melalui walkthrough ini menyerahkan satu Google Search. Pemeriksaan status dan pengambilan hasil tidak mengajukan pertanyaan lain. Penggunaan kembali kredensial yang sama sepanjang.

1. Kirim sekali dan simpan penerimaan

Berkas submission.json adalah tanda terimamu. HTTP 2) mengembalikan id, sumber, status dan self/results links; THE CLI menyimpan penerimaan di bawah penyerahan 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 menyerahkan hal lain.

A first wait yang sukses mengembalikan data.status: completed dalam 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 tanggapannya

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

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

Memvalidasi respon yang disimpan, kemudian ekstrak judul, link dan snippet untuk tampilan pencarian atau langkah berikutnya agen. Sebuah array organik kosong yang berhasil tidak berarti tidak ada item yang cocok; sebuah medan yang hilang atau badan yang gagal membutuhkan penyelidikan.

Tugas AplikasiTransisi
Sedang menungguKegigitan zodiak yang diterima ID sebelum mengembalikan kontrol ke pengguna atau agen.
SiapMark XEVE siap setelah hasilnya disimpan dan divalidasi. Gunakan ID sebagai kunci import/upsert.
Perlu diperhatikanTetap jaga pekerjaan ID dan kesalahan. PERTENTUAN Pungutan atau kegagalan pengambilan kembali bukanlah permintaan untuk mengajukan kembali.
Membaca tanggapan lokal · tidak ada panggilan 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

Sambung kembali dalam proses lain

Buka sebuah terminal segar di folder yang sama, dengan credential/profile. yang sama Perintah-perintah ini membaca pekerjaan di submission.json dan menyimpan ke nama berkas baru. Mereka tidak pernah menyerahkan pekerjaan. Mengecoh kembali CLI yang sama menjalankan ID membutuhkan direktori keadaan asalnya; HTTP sendiri tidak mendeduplikasi POSTs menggunakan bahwa lokal menjalankan ID.

CLI + jq · memulihkan pekerjaan tersimpan
(
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
)

Berikan beberapa pertanyaan

Batch menyerahkan pekerjaan independen dalam satu permintaan. Contoh dua-query ini membutuhkan kapasitas untuk setidaknya dua pertanyaan dan dua pekerjaan tertunda; percobaan sementara terbatas pada satu. Simpan array di bawah ini sebagai batch.json dalam folder kerja yang 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

Cipta collect-batch.py Di dalam Batch Di samping itu, di sebelah folder kerja mereka, ada beberapa tempat kerja. batch.json Dan batch-submission.json. Salin kode lengkap di bawah ke dalamnya dan menyimpannya.

Keep batch.json, batch-submission.json dan batch-results/ bersama-sama. Skrip berhenti jika input yang disimpan atau penerimaan berubah. Ia menggunakan ulang berkas lokal yang telah selesai dan tidak pernah mengajukan pertanyaan penggantian setelah kesalahan baca.

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)

Trek masing-masing diterima pekerjaan

Medis setelah diselamatkan collect-batch.pyLari dari Batch Kerusi dengan folder kerja Python 3.10AYAT + dan terotentikasi CLI. Ini bekerja dengan baik metode penyerahan di atas. Ia membaca setiap penerimaan, menunggu hingga dua menit per pekerjaan yang belum selesai dan menyimpan setiap respon yang berhasil. Pengumpul di satu waktu larikan lagi untuk melanjutkan pekerjaan yang sama.

Expect dua entri dalam batch-results/outcomes.json untuk sampel. Impor masukan selesai oleh indeks masukan dan pekerjaan ID. Gagal, tertunda dan entri read_error tetap terlihat; kode keluar 2 berarti meninjau atau melanjutkannya. Pengumpul tidak mengirimkan 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

Ipar akan menerima pelengkapan webhook

Tambah callback_url di samping sumber, kueri dan param dalam satu permintaan atau setiap entri Batch. Gantikan contoh URL dengan penerimamu. Peristiwa-peristiwa yang dilaporkan oleh peristiwa-peristiwa tersebut selesai atau gagal; mengambil kembali hasilnya secara terpisah.

  1. Dan segera mengembalikan 2xx. duplicate delivery_id (juga dikirim sebagai X-Delivery-Id).
  2. Acara ini tidak ditandatangani. Hagon Padankan id dan sumbernya ke penerimaan yang telah disimpan, kemudian otentifikasikan pembacaan status dengan menggunakan self link penerimaan asli. Jangan percayai URLs yang disuplai oleh peristiwa yang belum diverifikasi.
  3. Pada selesai, ambil dan simpan hasilnya. Pada gagal, memeriksa kesalahan pekerjaan. jajak pendapat tetap sebagai mundur jika tidak ada acara yang tiba.
Badan permintaan dengan panggil balik
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
Tubuh peristiwa-peristiwa yang · penjelas
{
  "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"
    }
  ]
}

Panggilanback URL

NEGERI Gunakan HTTPS URL pada port 443, paling banyak karakter 2,048, tanpa kelayakan atau fragmen. Setiap IP yang diselesaikan harus publik. ¡Omit callback_url, atau gunakan null atau string kosong, untuk mematikan pemberitahuan.

Memulihkan pekerjaan yang sudah ada

Situasi Orang AsingTindakan
Submission Timed outPeriksa runs show async-first dan akun History. runs recover dapat menerima pekerjaan yang diterima IDs; jika tidak ada ID yang disimpan, mendamaikan penyerahan sebelum mengirim POST lainnya.
pending / processingTerus periksa pekerjaan yang sudah ada. Negara-negara bagian ini bukan kegagalan.
failed / 422Bacalah job.error, memperbaiki penyebab dan memutuskan apakah untuk mengajukan pekerjaan baru.
429Kehormatan Retry-After. Mengurangi konkurensi penyerahan jika kapasitas pekerjaan-pensinggahan penuh.
404 / 409404Periksa ID Dan mengirimkan rekening. 409Hasil belum siap.
410Hasil tored JSON berakhir 24 jam setelah selesai. Gunakan salinan disimpan Anda. Media sudah dikirim ke tempat penyimpanan Anda mengikuti kebijakan retensi penyimpanan.

Kau menjalankan pekerjaan YouTube Download?

Unduhan COMPD menggunakan async atau Batch dan membutuhkan kunci API pemilik dengan youtube_download akses ditambah penyimpanan destinasi. Hasil JSON menggambarkan media yang sudah disampaikan ke ember Anda; titik akhir hasil tidak mengstream byte video. Mengeluarkan panduan untuk mengatur penyimpanan dan memverifikasi file yang dikirimkan.

Host dan format tanggapan

Semua empat menggunakan X-API-Key. Guna kunci yang sama seperti penyerahan. Status dan hasil membaca bebas, tapi tingkat terbatas. Contoh-contoh iodex menggunakan JSON; pilih Accept dan X-Respond-With di dalam pembangun untuk perwakilan hasil lain. Sebuah unduhan penyimpanan yang ditandatangani menggunakan URL, tanpa kunci FlashData.

OperasiTitik akhir Ukur
Berikan satu pekerjaanPOST https://data.flashdata.dev/v1/queries
Kerahkan separaPOST https://data.flashdata.dev/v1/queries/batch
Status bacaGET https://api.flashdata.dev/v2/jobs/{id}
Baca hasilGET https://api.flashdata.dev/v2/jobs/{id}/results

Sumber dan mode yang didukung

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

Bina aliran kerja untuk sumber Anda

Pilih sumber, sunting parameternya dan salin aliran kerja yang dihasilkan dalam bahasa Anda. Memungkinkan panggilan balik untuk mengungkapkan contoh penerima. builder ini mepratoner kode dan respon sampel; permintaan dijalankan hanya ketika Anda mengeksekusi kode atau menggunakan konsol.

Parameter sumber

Bina permintaan

Parameter lanjutan

Mulai dari 1. Setiap halaman adalah permintaan terpisah.

Filter waktu Google, seperti qdr:d untuk hari terakhir.

webhook pelengkapan hasil penyempurnaan dilakukanMuatan Webhook, verifikasi dan retriy

Markdown berlaku untuk hasil yang telah selesai. Penerimaan dan status pekerjaan mempertahankan bidang asal 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']}")
Resepsi penerimaan resis penerimaan, lalu jajak pendapat untuk hasilOtentikasi X-API-Key