# Async Permintaan & batch

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

Referensi kanonikal: https://flashdata.dev/id/docs/guides/async-batch
Diulang: 2026-11-05 oleh FlashData

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

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

| Simpan | Tujuan |
| --- | --- |
| Bukti penerimaan pekerjaan | submission.json - pertahankan pekerjaan yang diterima ID dengan tugas aplikasi Anda dan masukan asli. |
| Respon tersimpan | result.json - memvalidasi sumber dan hasilnya sebelum mengimpornya. |
| Batch keluar | batch-results/outcomes.json - satu entri per masukan, dengan pekerjaan ID dan berkas hasil. |

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

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

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

### CLI

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

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

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

### HTTP / cURL

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

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

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

- [Uji coba agen dan penautan akun](https://flashdata.dev/id/docs/guides/agent-onboarding/reference.md)
- [Periksa harga](https://flashdata.dev/id/docs/guides/credits-and-billing/reference.md)

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

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


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

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

### 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 mengirimkan hal lain.

### CLI

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

Cek ini sekali. Ulangi GET setelah penundaan singkat sementara job.status ditunda atau diproses. Pada 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 selesai HTTP respon

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



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

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

### 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 bawaan mengarahkan ke penyimpanan yang ditandatangani. Kode ini mendekompresi hasil yang tersimpan dan juga menerima respon JSON langsung. Hanya FlashData yang menerima kunci API.

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


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

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

## 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 aplikasi | Transisi |
| --- | --- |
| Menunggu | Persist pekerjaan yang diterima ID sebelum kembali kontrol ke pengguna atau agen. |
| Siap | Mark siap setelah hasil disimpan dan disahkan. Gunakan tugas Anda ID sebagai kunci import/upsert. |
| Butuh perhatian | Menjaga pekerjaan ID dan kesalahan. Penghitungan waktu pemungutan suara atau kegagalan pengambilan bukan permintaan untuk mengirimkan lagi. |

### Baca respon lokal yang dipanggil 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
```

- [Archive dan gunakan kembali respon](https://flashdata.dev/id/docs/guides/save-results/reference.md)

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

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

```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](https://flashdata.dev/id/docs/guides/agent-recovery/reference.md#recover)

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

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

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

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

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

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

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

- [Batch model hasil](https://flashdata.dev/id/docs/reference/batch-and-bulk/reference.md#batch-results)
- [Jauhkan catatan aplikasi IDs](https://flashdata.dev/id/docs/guides/enrich-youtube-videos/reference.md)

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

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

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

### Tubuh acara

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

- [Hasilkan penerima dalam pembangun arus kerja](https://flashdata.dev/id/docs/guides/async-batch/reference.md#customize)

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

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


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

## Mengembalikan pekerjaan yang telah ada

| Situasi | Yang perlu dilakukan |
| --- | --- |
| Waktu submisi habis | Inspeksi 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 / processing | Terus periksa pekerjaan yang ada. Negara bagian ini bukanlah kegagalan. |
| failed / 422 | Baca job.error, perbaiki penyebabnya dan putuskan apakah akan mengirimkan pekerjaan baru. |
| 429 | Kehormatan Retry-After. Mengurangi konkusi pengiriman jika kapasitas pekerjaan pending- penuh. |
| 404 / 409 | 404: periksa ID dan masukkan akun. 409: hasil belum siap. |
| 410 | Hasil tersimpan JSON kadaluarsa 24 jam setelah penyelesaian. Gunakan salinan disimpan Anda. Media sudah dikirim ke tempat penyimpananmu mengikuti kebijakan penyimpanan itu. |

- [Batas rate dan penggunaan](https://flashdata.dev/id/docs/guides/usage-and-limits/reference.md)
- [CLI jalankan pemulihan](https://flashdata.dev/id/docs/guides/cli-automation/reference.md#recover)

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

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

- [Atur penyimpanan dan unduh](https://flashdata.dev/id/docs/guides/youtube-download-guide/reference.md)
- [Verifikasi media yang dikirim](https://flashdata.dev/id/docs/guides/youtube-download-guide/reference.md#verify-media)

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

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

| Operasi | Endpoint |
| --- | --- |
| Kirim satu pekerjaan | POST https://data.flashdata.dev/v1/queries |
| Ajukan suatu batch | POST https://data.flashdata.dev/v1/queries/batch |
| Baca status | GET https://api.flashdata.dev/v2/jobs/{id} |
| Hasil baca | GET https://api.flashdata.dev/v2/jobs/{id}/results |

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

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

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

- [Moda permintaan](https://flashdata.dev/id/docs/reference/realtime-and-async/reference.md#choose)
- [Bulk file workflow](https://flashdata.dev/id/docs/guides/bulk/reference.md)

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

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