# Async & пакетні запити

Запустіть фонову роботу для програми або агента, відновіть від його збереженої роботи ID і зберіть кожен результат партії.

Канонічне посилання: https://flashdata.dev/uk/docs/guides/async-batch
Переглянуто: 2026-11-05 від FlashData

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

## Продовжити роботу після завершення процесу

Використовуйте фонову роботу для черги завдання програми або робочого процесу агента, який може переходити через finish. Цей прохід проходить один пошук Google, зберігає його надходження та відновлює з цього отримання в іншому процесі.

| Зареєструватися | Мета |
| --- | --- |
| Підтвердження завдання | submission.json — зберегти прийнята робота ID з вашим завданням та оригінальним введенням. |
| Збережено відповідь | result.json — увімкнено джерело та результати до імпортування. |
| Batch результати | batch-results/outcomes.json — один запис на вхід, з його роботою ID і файлом результату. |

- [Realtime versus async](https://flashdata.dev/uk/docs/reference/realtime-and-async/reference.md#choose)
- [Batch проти Bulk](https://flashdata.dev/uk/docs/reference/batch-and-bulk/reference.md#choose)
- [Відкрийте конструктор робочого процесу](https://flashdata.dev/uk/docs/guides/async-batch/reference.md#customize)

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

## Перед тим, як початися

Використовуйте ключ API з доступом google_search та доступними кредитами. Виберіть CLI або HTTP для подання, очікування та ретривалю. Приклади Bash використовують jq; HTTP також потребує cURL 7.76+. Запуск у новій папці роботи.

### CLI

Застосуйте свій автентичний профіль CLI або FLASHDATA_API_KEY. Підтвердження data.accessVerified - true. Встановити FLASHDATA_PROFILE для названого профілю так пізніше скриптів використовувати його занадто. Якщо ключ не налаштований, скористайтеся посібником з автентичності CLI.

#### Безкоштовні перевірки доступу та облікових записів

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

- [Встановлення та автентифікації CLI](https://flashdata.dev/uk/docs/guides/flashdata-cli/reference.md#existing-key)

### HTTP / cURL

Зберігати цей термінал для інших команд. Агенти повинні прочитати ключ від свого секретного магазину або навколишнього середовища.

#### Настроювання ключа API

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

- [Створіть ключ API](https://flashdata.dev/app/api-keys)

- [Пробний доступ агента й прив’язування облікового запису](https://flashdata.dev/uk/docs/guides/agent-onboarding/reference.md)
- [Ознайомитися з цінними пропозиціями](https://flashdata.dev/uk/docs/guides/credits-and-billing/reference.md)

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

## Запуск фонового пошуку

Цей прохід подає один Google Search. Перевірка стану та перевизначення результату не подають іншого запиту. Використовуйте однакові значення протягом усього.


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

## 1. Подати заявку і зберігати чек

Файл submission.json є вашим квитанцією. HTTP повертає ідентифікатор, джерело, статус та посилання self/results; CLI заощаджує надходження під подання, а також повертає remoteId. HTTP 200 приймається, не завершується.

### 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. Очікується існуючої роботи

Продовжити роботу при заповненні роботи. Якщо це не вдалося, перевірте свою помилку перед поданням будь-якого іншого.

### CLI

Успішне очікування повертає data.status: completed в 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

Це перевіряє один раз Повторіть GET після короткого затримки, поки job.status загинає або переробляється. На 429 чекатиме Retry-After від 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
)
```

#### Повний статус · ілюстративний відповідь HTTP

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



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

## 3. Отримати і зберегти відповідь

Заощаджуйте result.json локально. Закінчена робота і її результат тіло є окремими записами: це тіло пошуку містить джерело: google_search, масив результатів і використання. Усиновлення нижче приймає виконаний або завершений статус результату.

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

За замовчуванням JSON результат перенаправлення до підписаного сховища. Цей код декомпресує збережений результат, а також приймає безпосередню відповідь JSON. Тільки кінцева точка FlashData отримує ключ 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
)
```


- [Огляд та збереження результатів пошуку](https://flashdata.dev/uk/docs/guides/google-search-guide/reference.md#results)

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

## 4. Використовуйте результат у додатку

Дійсніть збережену відповідь, потім витягніть назву, посилання та snippet для перегляду пошуку або наступного кроку агента. Успішний порожній органічний масив означає, що не відповідає предметам, відсутній поле або не вдалося вивчити потреби тіла.

| Завдання програми | Перехід |
| --- | --- |
| Офіціант | Поспішати прийнятий роботу ID перед тим як повернути контроль користувача або агента. |
| Про нас | Позначте готовий після того, як результат зберігається і діє. Використовуйте своє завдання ID як ключ import/upsert. |
| Потрібна увага | Зберігайте роботу ID і похибку. Недокладна відмова від випилювання або перерозподілу не є запитом повторно подати. |

### Читати локальну відповідь · без викликів 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
```

- [Архів і повторно використовує відповідь](https://flashdata.dev/uk/docs/guides/save-results/reference.md)

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

## Резюме в іншому процесі

Відкрийте для себе свіже термінал в одній папці, з тим же credential/profile. Ці команди читати роботу в submission.json і зберегти на нове ім'я файлу. Вони ніколи не подають роботу. Виправлення того ж CLI Увійти ID вимагає оригінального державного каталогу; HTTP сам не deduplicate POSTs за допомогою цього локального запуску 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
)
```

- [Невідомий результат подання](https://flashdata.dev/uk/docs/guides/agent-recovery/reference.md#recover)

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

## Подати кілька запитів

Batch надсилає незалежні завдання одним запитом. Цей приклад із двома запитами потребує місткості щонайменше для двох запитів і двох незавершених завдань; тимчасовий пробний доступ обмежений одним. Збережіть масив нижче як batch.json в окремій робочій папці.

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

### Зберегти collect-batch.py

Список collect-batch.py в Batch робоча папка біля batch.json і batch-submission.json. Скопіюйте загальний код нижче в ньому і заощаджуйте його.

Зареєструватися batch.json, batch-submission.json і партії-результи / разом. Скрипт припиняється, якщо збережені вводи або зміни квитанцій. За допомогою локальних файлів і ніколи не подає запит на заміну після помилки читання.

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

### Відстежуйте кожну прийнята робота

Після збереження collect-batch.py, запустіть його з робочої папки Batch з Python 3.10+ і автентифікований CLI. Працює з будь-яким способом подання. Прочитає кожну квитанцію, чекаючи до двох хвилин на незакінчену роботу і заощаджує кожну успішну відповідь. Запуск одного колектора в часі; перейменувати його для продовження тих же завдань.

Визначити два записи в batch-results/outcomes.json для зразка. Імпорт завершених записів за індексом введення та роботою ID. Вимкнено, припинено і read_error записи залишаються видимими; вихідний код 2 означає огляд або відновити їх. Збірник відправляє не нові запити.

#### Bash

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

#### PowerShell 7

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

#### Читати кожен результат · jq

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

- [Batch результат модель](https://flashdata.dev/uk/docs/reference/batch-and-bulk/reference.md#batch-results)
- [Зареєструйтеся на додаток IDs](https://flashdata.dev/uk/docs/guides/enrich-youtube-videos/reference.md)

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

## Отримувати вебхоок

Додати джерело callback_url, запит та параметри в одному запиті або кожен запис Batch. Замініть приклад URL з приймачем. Заяви про завершення або відмову від звітів, отримання результату окремо.

1. Потрібні дати і повернути 2xx оперативно. Deduplicate delivery_id (також відправлений як X-Delivery-Id).
2. Захід не відзначається. Зробіть свій id і джерело, щоб ваш збережений квитанція, а потім автентифікуйте читання статусу за допомогою саморегулятора. Не довіряйте URLs, що надавалася неперевершеним подіям.
3. На завершеному, фіксують і зберігають результат. Про не вдалося, перевіряючи похибку роботи. Зберігайте опитування, якщо не прибуває події.

### Запит тіла з зворотним викликом

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

### Тіло подій · ілюстративний

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

- [Генерація ресивера в конструкторі робочого процесу](https://flashdata.dev/uk/docs/guides/async-batch/reference.md#customize)

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

### Зворотній зв'язок URL

Використовуйте публічний HTTPS URL на порту 443, на більшості символів 2,048, без облікових даних або фрагмента. Кожен вирішений IP повинен бути громадським. Omit callback_url або використовувати null або порожній рядок, щоб відключити повідомлення.


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

## Відновити існуючу роботу

| Ситуація | Що робити |
| --- | --- |
| Відхилений термін дії | Інспектор runs show async-перший і рахунок History. runs recover може отримати прийнята робота IDs; якщо немає ID було збережено, відмовляючи надсилання іншим POST. |
| pending / processing | Зареєструватися на роботу. Ці стани не мають збою. |
| failed / 422 | Читати далі job.errorВиправте причину і вирішіть, чи подайте нову роботу. |
| 429 | Заслужений Retry-After. Знижувати конвактиву про подачу, якщо об'єми кінцевої роботи повною. |
| 404 / 409 | 404: перевірте ID і вказав рахунок. 409: результати ще не готові. |
| 410 | Зберігайте результат JSON Закінчується 24 години після завершення. Використовуйте збережену копію. Компанія «Медіа» вже доставила до вашого сховища, що означає політику збереження пам’яті. |

- [Обмеження ставок та використання](https://flashdata.dev/uk/docs/guides/usage-and-limits/reference.md)
- [CLI відновлення запуску](https://flashdata.dev/uk/docs/guides/cli-automation/reference.md#recover)

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

## Запуск роботи YouTube Download?

Завантажте використовується async або Batch і потребує власника API ключ з youtube_download access плюс пункт призначення. Його результат JSON описує медіа, які вже доставлені до Вашого відро; кінцева точка результатів не потокове відеобайти. Використовуйте посібник для налаштування сховища та перевірки доставленого файлу.

- [Налаштування зберігання та завантаження](https://flashdata.dev/uk/docs/guides/youtube-download-guide/reference.md)
- [Перевірити доставку ЗМІ](https://flashdata.dev/uk/docs/guides/youtube-download-guide/reference.md#verify-media)

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

## Формати та формати відповіді

Всі чотири використання X-API-Key. Використовуйте той самий ключ, як подача. Статус і результат читання безкоштовні, але номінальний. На прикладі використовується JSON; оберіть Accept і X-Respond-With в конструкторі для інших результатів. Завантажте зареєстроване сховище за допомогою URL, без ключа FlashData.

| Операція | Навігація |
| --- | --- |
| Подати заявку | POST https://data.flashdata.dev/v1/queries |
| Подати пакет | POST https://data.flashdata.dev/v1/queries/batch |
| Статус на сервери | GET https://api.flashdata.dev/v2/jobs/{id} |
| Читати результати | GET https://api.flashdata.dev/v2/jobs/{id}/results |

- [Realtime і протокол асинхрону](https://flashdata.dev/uk/docs/reference/realtime-and-async/reference.md)
- [Протокол запитів Batch](https://flashdata.dev/uk/docs/reference/batch-and-bulk/reference.md)
- [Правила формата відповіді](https://flashdata.dev/uk/docs/guides/response-formats/reference.md)

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

## Підтримувані джерела та режими

Використовуйте конструктор нижче для поточних параметрів джерела. Google Search і YouTube Data підтримка фонових робочих місць. YouTube Download використовує фонові робочі місця та призначення. Для великого файлу відео IDs з загальними варіантами, скористайтеся посібником Bulk.

- [Режими запиту](https://flashdata.dev/uk/docs/reference/realtime-and-async/reference.md#choose)
- [Bulk файловий робочий процес](https://flashdata.dev/uk/docs/guides/bulk/reference.md)

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

## Побудувати робочий процес для вашого джерела

Виберіть джерело, відредагуйте свої параметри та скопіюйте сформований робочий процес у вашій мові. Увімкніть зворотний дзвінок, щоб відкрити приймач приклад. Цей конструктор попередньо перегляд коду та відповіді про зразок; запити, які працюють тільки при виконанні коду або використанні консолі.

- [Параметри джерела та схеми](https://flashdata.dev/uk/docs/reference/reference.md)
