# Permintaan small Async & batch

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

Referensi boonical: https://flashdata.dev/ms/docs/guides/async-batch
Diulas: 2026-11-05 oleh FlashData

<a id="choose"></a>

## 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.

| Jaga | Tujuan |
| --- | --- |
| Resit tugas | submission.json — pertahankan pekerjaan yang diterima ID dengan tugas aplikasi dan masukan asli Anda. |
| Respon yang disimpan oleh orang Israel | result.json — mengesahkan sumber dan hasil sebelum mengimpornya. |
| Hasil Batch | batch-results/outcomes.json — satu masukan per masukan, dengan pekerjaan ID dan berkas hasil. |

- [Realtime versus async](https://flashdata.dev/ms/docs/reference/realtime-and-async/reference.md#choose)
- [Batch versus versus Bulk](https://flashdata.dev/ms/docs/reference/batch-and-bulk/reference.md#choose)
- [Bukalah pembangun aliran kerja](https://flashdata.dev/ms/docs/guides/async-batch/reference.md#customize)

<a id="prepare"></a>

## 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.

### CLI

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

```bash
flashdata auth status --json
flashdata account balance --json
flashdata account limits --json
```

- [Pasang dan sahkan CLI](https://flashdata.dev/ms/docs/guides/flashdata-cli/reference.md#existing-key)

### HTTP / cURL

Tetap buka terminal ini untuk perintah yang tersisa. Agen Agen harus membaca kunci dari toko rahasia atau lingkungan mereka.

#### Ketikkan kunci API anda

```bash
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY
```

- [Xachive membuat kunci API](https://flashdata.dev/app/api-keys)

- [Percubaan ejen dan pemautan akaun](https://flashdata.dev/ms/docs/guides/agent-onboarding/reference.md)
- [Periksa harga](https://flashdata.dev/ms/docs/guides/credits-and-billing/reference.md)

<a id="job-lifecycle"></a>

## 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.


<a id="async-batch"></a>

## 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.

### CLI

#### Bash · FlashData CLI

```bash
flashdata search "battery recycling research" --num 5 \
  --mode async --run-id async-first --output submission.json --json
```


### HTTP / cURL

#### Bash · cURL + jq

```bash
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e submission.json || { echo "Use the saved receipt or a new filename." >&2; exit 1; }
curl --fail-with-body --silent --show-error \
  --request POST 'https://data.flashdata.dev/v1/queries' \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"source":"google_search","query":"battery recycling research","params":{"num":5}}' \
  --output submission.json
jq '{id, source, status, links}' submission.json
)
```



<a id="job-status"></a>

## 2. Tunggu pekerjaan yang sudah ada

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

### CLI

A first wait yang sukses mengembalikan data.status: completed dalam CLI JSON.

#### Bash · FlashData CLI

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


### HTTP / cURL

Ini cek sekali. GET setelah penundaan singkat sementara job.status sedang tertunda atau diproses. 429, tunggu Retry-After dari job-headers.txt.

#### Bash · cURL + jq

```bash
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
JOB_ID=$(jq -er '(.remoteId // .id // .submission.id) | select(test("^[A-Za-z0-9_-]+$"))' submission.json)
STATUS_URL="https://api.flashdata.dev/v2/jobs/$JOB_ID"
curl --fail-with-body --silent --show-error \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --max-time 30 --dump-header job-headers.txt --output job.json "$STATUS_URL"
jq -e --arg id "$JOB_ID" '.job.id == $id' job.json >/dev/null
jq '.job | {id, source, status, error}' job.json
)
```

#### Status Completed · respon HTTP yang terlengkapi

```json
{
  "job": {
    "id": "EXAMPLE_JOB_ID",
    "source": "google_search",
    "status": "completed",
    "error": null
  }
}
```



<a id="job-results"></a>

## 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.

### CLI

#### Bash · FlashData CLI

```bash
(
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
)
```


### HTTP / cURL

Hasil JSON standar dialihkan ke penyimpanan yang ditandatangani. Kode code ini menyahkompresi hasil yang disimpan dan juga menerima respon JSON langsung. Hanya FlashData titik akhir menerima kunci API anda.

#### Bash · cURL + jq

```bash
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
JOB_ID=$(jq -er '(.remoteId // .id // .submission.id) | select(test("^[A-Za-z0-9_-]+$"))' submission.json)
SOURCE=$(jq -er '(.submission // .).source' submission.json)
jq -e --arg id "$JOB_ID" --arg source "$SOURCE" \
  '.job.id == $id and .job.source == $source and .job.status == "completed"' job.json >/dev/null
test ! -e result.json || { echo "Choose a new output filename." >&2; exit 1; }
RESULT_URL="https://api.flashdata.dev/v2/jobs/$JOB_ID/results"
STATUS=$(curl --silent --show-error \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --max-time 120 --dump-header result-headers.txt --output result.pending \
  --write-out '%{http_code}' "$RESULT_URL")
case "$STATUS" in
  200) ;;
  302)
    LOCATION=$(awk 'tolower($1) == "location:" { sub(/\r$/, "", $2); print $2 }' result-headers.txt)
    # The signed storage URL is fetched WITHOUT the FlashData API key.
    curl --fail-with-body --silent --show-error --compressed --max-time 120 --proto '=https' \
      --output result.pending "$LOCATION" ;;
  *) echo "Result HTTP $STATUS; inspect result.pending and result-headers.txt." >&2; exit 1 ;;
esac
jq -e --arg source "$SOURCE" '.source == $source and (.status == "done" or .status == "completed")
  and (.results | type == "array")' result.pending >/dev/null
cat result.pending > result.json
jq '{id, source, status, results, usage}' result.json
)
```


- [Periksa dan simpan hasil pencarian](https://flashdata.dev/ms/docs/guides/google-search-guide/reference.md#results)

<a id="use-result"></a>

## 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 Aplikasi | Transisi |
| --- | --- |
| Sedang menunggu | Kegigitan zodiak yang diterima ID sebelum mengembalikan kontrol ke pengguna atau agen. |
| Siap | Mark XEVE siap setelah hasilnya disimpan dan divalidasi. Gunakan ID sebagai kunci import/upsert. |
| Perlu diperhatikan | Tetap jaga pekerjaan ID dan kesalahan. PERTENTUAN Pungutan atau kegagalan pengambilan kembali bukanlah permintaan untuk mengajukan kembali. |

### Membaca tanggapan lokal · tidak ada panggilan API

```bash
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
```

- [Arsip dan penggunaan kembali tanggapan](https://flashdata.dev/ms/docs/guides/save-results/reference.md)

<a id="resume"></a>

## 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

```bash
(
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
)
```

- [Hasil pengiriman tidak diketahui oleh golongan yang tidak diketahui](https://flashdata.dev/ms/docs/guides/agent-recovery/reference.md#recover)

<a id="batch"></a>

## 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

```json
[
  {
    "source": "google_search",
    "query": "battery recycling research",
    "params": {
      "num": 5
    }
  },
  {
    "source": "google_search",
    "query": "lithium battery recycling methods",
    "params": {
      "num": 5
    }
  }
]
```

### CLI

#### Bash · FlashData CLI

```bash
flashdata batch submit --input batch.json \
  --run-id batch-first --output batch-submission.json --json
```


### HTTP / cURL

#### Bash · cURL + jq

```bash
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e batch-submission.json || { echo "Keep the saved batch receipt." >&2; exit 1; }
jq '{queries: .}' batch.json > batch-request.json
curl --fail-with-body --silent --show-error \
  --request POST 'https://data.flashdata.dev/v1/queries/batch' \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @batch-request.json --output batch-submission.json
jq '.queries[] | {id, source, status}' batch-submission.json
)
```



<a id="batch-collector"></a>

### 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

```python
# 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)
```


<a id="batch-results"></a>

### 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

```bash
python3 collect-batch.py
```

#### PowerShell 7

```powershell
python collect-batch.py
```

#### Baca setiap hasil · jq

```bash
jq '.[] | {index, job_id, status, result_file, error}' batch-results/outcomes.json
```

- [Model hasil Batch](https://flashdata.dev/ms/docs/reference/batch-and-bulk/reference.md#batch-results)
- [Pertahankan rekam aplikasi IDs](https://flashdata.dev/ms/docs/guides/enrich-youtube-videos/reference.md)

<a id="webhooks"></a>

## 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

```json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
```

### Tubuh peristiwa-peristiwa yang · penjelas

```json
{
  "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"
    }
  ]
}
```

- [Eksekusi sebuah penerima dalam pembina aliran kerja](https://flashdata.dev/ms/docs/guides/async-batch/reference.md#customize)

<a id="callbacks"></a>

### 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.


<a id="limits"></a>

## Memulihkan pekerjaan yang sudah ada

| Situasi Orang Asing | Tindakan |
| --- | --- |
| Submission Timed out | Periksa 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 / processing | Terus periksa pekerjaan yang sudah ada. Negara-negara bagian ini bukan kegagalan. |
| failed / 422 | Bacalah job.error, memperbaiki penyebab dan memutuskan apakah untuk mengajukan pekerjaan baru. |
| 429 | Kehormatan Retry-After. Mengurangi konkurensi penyerahan jika kapasitas pekerjaan-pensinggahan penuh. |
| 404 / 409 | 404Periksa ID Dan mengirimkan rekening. 409Hasil belum siap. |
| 410 | Hasil tored JSON berakhir 24 jam setelah selesai. Gunakan salinan disimpan Anda. Media sudah dikirim ke tempat penyimpanan Anda mengikuti kebijakan retensi penyimpanan. |

- [Batas laju dan penggunaan defakul](https://flashdata.dev/ms/docs/guides/usage-and-limits/reference.md)
- [XANCLI menjalankan pemulihan](https://flashdata.dev/ms/docs/guides/cli-automation/reference.md#recover)

<a id="delivery"></a>

## 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.

- [Konfigur penyimpanan dan muat turun](https://flashdata.dev/ms/docs/guides/youtube-download-guide/reference.md)
- [Media yang disampaikan dengan verifikasi](https://flashdata.dev/ms/docs/guides/youtube-download-guide/reference.md#verify-media)

<a id="api-hosts"></a>

## 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.

| Operasi | Titik akhir Ukur |
| --- | --- |
| Berikan satu pekerjaan | POST https://data.flashdata.dev/v1/queries |
| Kerahkan separa | POST https://data.flashdata.dev/v1/queries/batch |
| Status baca | GET https://api.flashdata.dev/v2/jobs/{id} |
| Baca hasil | GET https://api.flashdata.dev/v2/jobs/{id}/results |

- [Realtime dan protokol async](https://flashdata.dev/ms/docs/reference/realtime-and-async/reference.md)
- [Protokol permintaan Batch](https://flashdata.dev/ms/docs/reference/batch-and-bulk/reference.md)
- [Aturan format respon](https://flashdata.dev/ms/docs/guides/response-formats/reference.md)

<a id="supported-sources"></a>

## 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.

- [Mod permintaan ORANG](https://flashdata.dev/ms/docs/reference/realtime-and-async/reference.md#choose)
- [Aliran kerja berkas Bulk](https://flashdata.dev/ms/docs/guides/bulk/reference.md)

<a id="customize"></a>

## 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 dan skema sumber](https://flashdata.dev/ms/docs/reference/reference.md)
