# Async 및 일괄 요청

응용 프로그램 또는 에이전트에 대 한 배경 작업을 실행, 그것의 저장된 작업 ID에서 이력서 및 모든 배치 결과 수집.

Canonical 참고: https://flashdata.dev/ko/docs/guides/async-batch
검토: 2026-11-05 FlashData

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

## 프로세스가 중지한 후 계속 작업

나중에 finish를 사용할 수 있는 쿼츠 애플리케이션 작업 또는 에이전트 워크플로우에 대한 배경 작업을 사용합니다. 이 walkthrough는 하나의 Google 검색을 실행하고 영수증을 저장하고 다른 과정에서 그 영수증에서 이력서를 저장합니다.

| 보관 | 제품정보 |
| --- | --- |
| 작업 접수 정보 | submission.json - 응용 프로그램 작업과 원본 입력으로 허용되는 작업 ID를 유지합니다. |
| 저장된 응답 | result.json - 소스를 검증하고 결과를 가져 오기 전에 검증합니다. |
| Batch 결과 | batch-results/outcomes.json - 입력 당 한 항목, 작업 ID 및 결과 파일. |

- [Realtime versus 동기화](https://flashdata.dev/ko/docs/reference/realtime-and-async/reference.md#choose)
- [Batch versus Bulk](https://flashdata.dev/ko/docs/reference/batch-and-bulk/reference.md#choose)
- [워크플로우 빌더 열기](https://flashdata.dev/ko/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/ko/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/ko/docs/guides/agent-onboarding/reference.md)
- [가격 확인](https://flashdata.dev/ko/docs/guides/credits-and-billing/reference.md)

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

## 배경 검색 실행

이 연습은 Google Search를 제출합니다. 상태 확인 및 결과 검색은 다른 쿼리를 제출하지 않습니다. 전반적으로 동일한 자격 증명을 재사용합니다.


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

## 1. 한 번 제출하고 영수증을 보관하십시오

submission.json 파일은 영수증입니다. HTTP는 id, 소스, 상태 및 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

이 체크는 한 번입니다. job.status가 보류되거나 처리되는 동안 짧은 지연 후에 GET를 반복하십시오. 에 의해 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
)
```


- [Inspect and save 검색 결과](https://flashdata.dev/ko/docs/guides/google-search-guide/reference.md#results)

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

## 4. 당신의 신청에 있는 결과를 사용하십시오

저장된 응답을 검증하고, 검색보기 또는 에이전트의 다음 단계를 위해 제목, 링크 및 스니펫을 추출합니다. 성공적인 빈 유기 배열은 일치하는 품목을 의미하지 않습니다; 누락된 분야 또는 실패한 몸은 조사를 필요로 합니다.

| 적용 작업 | 관련 기사 |
| --- | --- |
| 을 읽다 | Persist는 사용자 또는 대리인에 통제를 돌려보내기 전에 받아들여진 일 ID를 주장합니다. |
| 지원하다 | 결과가 저장되고 검증된 후 Mark가 준비되었습니다. import/upsert 키로 작업 ID를 사용하십시오. |
| 자주 묻는 질문 | 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/ko/docs/guides/save-results/reference.md)

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

## 다른 과정에 이력서

같은 폴더에 신선한 터미널을 열고, 같은 credential/profile. 이 명령은 submission.json에서 작업을 읽고 새 파일명에 저장합니다. 그들은 결코 일을 제출하지 않습니다. 동일한 CLI 실행을 재사용 ID는 원래 상태 디렉토리를 요구합니다; HTTP 자체는 로컬 실행 ID를 사용하여 POST를 deduplicate하지 않습니다.

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

batch.json와 batch-submission.json 옆에 Batch 작업 폴더에 collect-batch.py를 만듭니다. 아래의 전체 코드를 복사하고 저장합니다.

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 저장 후 Python 3.10+와 정통 CLI를 가진 Batch 작업 폴더에서 실행하십시오. 위의 제출 방법 중 하나와 함께 작동합니다. 그것은 모든 영수증을 읽고, 불완전한 일 당 2 분까지 기다리고 각 성공적인 응답을 저장합니다. 한 명의 수집가를 한 번에 실행하십시오. 동일한 작업을 계속하려면 다시 실행하십시오.

샘플에 대한 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/ko/docs/reference/batch-and-bulk/reference.md#batch-results)
- [응용 프로그램 레코드를 유지 IDs](https://flashdata.dev/ko/docs/guides/enrich-youtube-videos/reference.md)

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

## 웹훅을 완료

callback_url를 소스 옆에 추가, 쿼리 및 단일 요청 또는 각 Batch 항목에 params. 수신기를 가진 예 URL를 대체하십시오. 이벤트 보고서 완료 또는 실패; 결과를 개별적으로 검색합니다.

1. 이벤트를 감독하고 2xx를 신속하게 반환합니다. delivery_id (또한 X-Delivery-Id로 보내)를 분해하십시오.
2. 이벤트가 취소되지 않습니다. 저장된 영수증에 그것의 ID와 근원 일치하고, 그 후에 본래 영수증의 각자 연결을 사용하여 읽는 상태를 정정합니다. URLs를 믿을 수 없습니다.
3. 완료되면 fetch를 저장하고 결과를 저장합니다. 실패한 경우, 작업 오류를 검사합니다. 이벤트가 도착하지 않으면 가을으로 오염을 지키십시오.

### 콜백을 가진 몸 요청

```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/ko/docs/guides/async-batch/reference.md#customize)

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

### Callback URL 요구 사항

포트 443에 HTTPS URL, 대부분의 2,048 문자에서, credentials 또는 파편없이. 모든 해결된 IP는 공개해야 합니다. Omit callback_url 또는 null 또는 빈 문자열을 사용하여 알림을 비활성화합니다.


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

## 기존의 작업을 복구

| - 연혁 | 해결 방법 |
| --- | --- |
| 제출 시간 | runs show async-first 및 계정 History를 검사하십시오. runs recover는 IDs를 받아들일 수 있습니다; ID가 저장되지 않은 경우에, 다른 POST를 보내기 전에 제출을 재구성하십시오. |
| pending / processing | 기존의 작업을 계속하십시오. 이 상태는 실패하지 않습니다. |
| failed / 422 | job.error를 읽고, 원인을 수정하고 새로운 작업을 제출 여부를 결정하십시오. |
| 429 | 명예 Retry-After. pending-job 용량이 가득하다면 제출 concurrency를 줄입니다. |
| 404 / 409 | 404: ID를 확인하고 계정을 제출하십시오. 409: 결과는 아직 준비되어 있지 않습니다. |
| 410 | 저장된 결과 JSON는 24 시간을 완료한 후 만료됩니다. 저장된 사본을 사용하십시오. 미디어는 이미 저장에 전달되어 저장의 보존 정책을 따르고 있습니다. |

- [비율 한계 및 사용법](https://flashdata.dev/ko/docs/guides/usage-and-limits/reference.md)
- [CLI 런 복구](https://flashdata.dev/ko/docs/guides/cli-automation/reference.md#recover)

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

## YouTube Download 작업 실행?

다운로드는 동기화 또는 Batch를 사용하고 youtube_download 액세스 플러스 대상 저장과 소유자 API 키가 필요합니다. 그 결과 JSON는 미디어가 이미 양동이에 전달되었습니다. 결과 엔드포인트는 비디오 바이트를 스트리밍하지 않습니다. 다운로드 가이드를 사용하여 저장을 구성하고 전달된 파일을 확인합니다.

- [저장 및 다운로드 구성](https://flashdata.dev/ko/docs/guides/youtube-download-guide/reference.md)
- [납품된 미디어](https://flashdata.dev/ko/docs/guides/youtube-download-guide/reference.md#verify-media)

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

## 호스트 및 응답 형식

모든 4 사용 X-API-Key. 제출과 동일한 키를 사용합니다. 상태와 결과 읽기는 무료입니다, 하지만 속도 제한. 예제는 JSON를 사용합니다. Accept 및 X-Respond-With를 다른 결과 표현에 대한 빌더로 선택하십시오. 서명된 저장 다운로드는 그것을 사용합니다 URL, 없이 FlashData 주요.

| - 연혁 | 끝점 |
| --- | --- |
| 1개의 일자리를 제출 | 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/ko/docs/reference/realtime-and-async/reference.md)
- [Batch 요청 프로토콜](https://flashdata.dev/ko/docs/reference/batch-and-bulk/reference.md)
- [응답 형식 규칙](https://flashdata.dev/ko/docs/guides/response-formats/reference.md)

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

## 지원된 소스 및 모드

소스의 현재 매개 변수에 대한 아래 빌더를 사용합니다. Google Search 및 YouTube Data 지원 배경 작업. YouTube Download는 배경 작업 및 목적지 저장을 사용합니다. 공유 옵션이있는 비디오 IDs의 큰 파일에 대해서는 Bulk 가이드를 사용하십시오.

- [요청 모드](https://flashdata.dev/ko/docs/reference/realtime-and-async/reference.md#choose)
- [Bulk 파일 워크플로우](https://flashdata.dev/ko/docs/guides/bulk/reference.md)

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

## 소스에 대한 작업 흐름을 구축

소스를 선택하고 매개 변수를 편집하고 언어의 생성 된 워크플로를 복사합니다. 수신자 예를 공개하기 위해 콜백을 활성화하십시오. 이 빌더 미리보기 코드 및 샘플 응답; 요청은 코드를 실행하거나 콘솔을 사용합니다.

- [소스 매개 변수 및 schemas](https://flashdata.dev/ko/docs/reference/reference.md)
