# Realtime 및 동기화

응답에 결과를 얻거나, 일자리를 제출하고 나중에 검색하십시오. 당신의 응용 프로그램 또는 에이전트가 작동을 기다리고 있는지 선택하십시오.

Canonical 참고: https://flashdata.dev/ko/docs/reference/realtime-and-async
검토: 2026-11-04 FlashData

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

## 요청 모드 선택

Google Search와 YouTube Data는 형태를 둘 다 지원합니다. YouTube Download는 동기화, Batch 또는 Bulk를 요구합니다; 그것은 순간을 지원하지 않습니다. 소스 매개 변수는 실시간에서 async로 전환 할 때 동일하게 유지됩니다.

| 의 특징 | 사용시 | 당신은 무엇을 받습니까 |
| --- | --- | --- |
| Realtime | 검색 결과가 현재 상호 작용에 필요합니다. | 동일한 HTTP 응답에 있는 결과 몸. |
| Async | 작업은 프로세스가 분리된 후 계속되어야 합니다. 또는 미디어를 다운로드하는 것입니다. | 즉시 ID 작업; 태치 상태 및 결과 별도. |

### Lifecycle에 관하여

```text
Realtime POST data.flashdata.dev/v1/queries/realtime → 결과
Async POST data.flashdata.dev/v1/queries → 일 ID
          GET api.flashdata.dev/v2/jobs/{id} → 상태
          GET api.flashdata.dev/v2/jobs/{id}/results → 결과
```

- [많은 쿼리를 제출?](https://flashdata.dev/ko/docs/reference/batch-and-bulk/reference.md)

<a id="submit"></a>

## 자주 묻는 질문

FLASHDATA_API_KEY를 google_search를 허용하는 열쇠로 설정하십시오. 실시간 또는 동기화를 선택하십시오. 각 제출은 청구 가능한 검색을 실행합니다. 같은 새로운 작업 폴더에서 스크립트, 영수증 및 결과를 유지하십시오.

Python 예제는 Python 3.10 + 및 요청을 사용합니다. 각 스크립트는 독립적으로 실행하고 이전 단계에서 저장된 파일을 읽습니다. cURL 대안은 Bash, cURL 7.76+ 및 jq를 필요로 합니다.

### Python · 한 번 설치

```bash
python3 -m pip install requests
```

- [API 열쇠와 우두머리](https://flashdata.dev/ko/docs/guides/headers-and-authentication/reference.md)
- [Google Search 모수](https://flashdata.dev/ko/docs/sources/google_search/reference.md)

<a id="realtime"></a>

### Realtime: 지금 결과를 얻으십시오

POST /v1/queries/realtime는 status: done와 결과 배열을 반환합니다. result.json를 읽으십시오; 오염이 필요하지 않습니다.

#### Python

realtime.py로 저장하고 python3 realtime.py를 실행하십시오.

##### realtime.py

```python
import json
import os
from pathlib import Path

import requests

response = requests.post(
    "https://data.flashdata.dev/v1/queries/realtime",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    json={"source": "google_search", "query": "battery recycling research", "params": {"num": 5}},
    timeout=120, allow_redirects=False,
)
response.raise_for_status()
result = response.json()
Path("result.json").write_text(json.dumps(result, indent=2), encoding="utf-8")
print(json.dumps(result, indent=2))
```


#### cURL / Bash

##### 결과를 얻을 · cURL / Bash

```bash
curl --fail-with-body --silent --show-error \
  'https://data.flashdata.dev/v1/queries/realtime' \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"source":"google_search","query":"battery recycling research","params":{"num":5}}' \
  --output result.json &&
jq '{source, status, results, usage}' result.json
```



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

### Async: 작업 영수증을 저장

POST /v1/queries는 검색 결과가 아닌 보류 작업 영수증을 반환합니다. submission.json를 저장하고 아래 상태와 결과 요청을 계속하십시오.

#### Python

submit_async.py로 저장하고 python3 submit_async.py를 실행하십시오.

##### submit_async.py

```python
import json
import os
from pathlib import Path

import requests

response = requests.post(
    "https://data.flashdata.dev/v1/queries",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    json={"source": "google_search", "query": "battery recycling research", "params": {"num": 5}},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
result = response.json()
Path("submission.json").write_text(json.dumps(result, indent=2), encoding="utf-8")
print(json.dumps(result, indent=2))
```

##### Receipt 필드 · 약어 예

```json
{
  "id": "job_EXAMPLE",
  "source": "google_search",
  "status": "pending"
}
```


#### cURL / Bash

##### ID · cURL / Bash

```bash
curl --fail-with-body --silent --show-error \
  'https://data.flashdata.dev/v1/queries' \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set 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
```

##### Receipt 필드 · 약어 예

```json
{
  "id": "job_EXAMPLE",
  "source": "google_search",
  "status": "pending"
}
```



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

## async 작업 확인

submission.json에서 ID를 사용하여 job.status를 읽으십시오. 보류 또는 가공을 위해, 다시 검사하기 전에 Retry-After 지연을 기다립니다; Python는 그것을 인쇄하고 cURL는 status-headers.txt에서 그것을 저장합니다. 힌트가 반환되지 않는 경우 backoff를 사용하십시오. 성공적인 상태 요청은 작업이 완료되지 않습니다.

| job.status | 다음 작업 |
| --- | --- |
| pending / processing | 대기, 다음 동일한 작업을 확인합니다 ID 다시. |
| completed | 저장된 결과를 검색합니다. |
| failed | job.error를 읽으십시오. 새 작업을 제출하기 전에 원인을 수정합니다. |

### Python

job_status.py로 저장하고 python3 job_status.py를 실행하십시오.

#### job_status.py

```python
import json
import os
from pathlib import Path

import requests

job_id = json.loads(Path("submission.json").read_text(encoding="utf-8"))["id"]
response = requests.get(
    f"https://api.flashdata.dev/v2/jobs/{job_id}",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
Path("job.json").write_text(json.dumps(response.json(), indent=2), encoding="utf-8")
print(json.dumps(response.json()["job"], indent=2))
print("Retry-After:", response.headers.get("Retry-After", "not provided"))
```


### cURL / Bash

#### 상태 읽기 · cURL / Bash

```bash
JOB_ID=$(jq -er '.id' submission.json)
curl --fail-with-body --silent --show-error \
  "https://api.flashdata.dev/v2/jobs/$JOB_ID" \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --dump-header status-headers.txt --output job.json &&
jq '.job | {id, source, status, error}' job.json
```



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

## 완료된 결과를 검색

job.status가 완료된 후 이것을 실행합니다. 기본 결과 응답은 302: 서명된 저장 URL에 위치점입니다. 아래 두 가지 요청은 API 키에 FlashData 자주 묻는 질문 JSON 으로 result.json. YouTube Download를 위해, 이 JSON는 당신의 저장에 배달된 매체를 설명합니다; 그것은 영상 또는 오디오 파일이 아닙니다.

### Python

job_result.py로 저장하고 python3 job_result.py를 실행하십시오.

#### job_result.py

```python
import json
import os
from pathlib import Path

import requests

receipt = json.loads(Path("submission.json").read_text(encoding="utf-8"))
job_id = receipt["id"]
response = requests.get(
    f"https://api.flashdata.dev/v2/jobs/{job_id}/results",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 302:
    raise RuntimeError(f"Expected a result redirect, got {response.status_code}")
url = response.headers["Location"]
if not url.startswith("https://"):
    raise ValueError("Expected an HTTPS storage URL")

# A separate request: no FlashData key is sent to storage.
result = requests.get(url, timeout=120)
result.raise_for_status()
data = result.json()  # Requests automatically decodes Content-Encoding: gzip.
Path("result.json").write_text(json.dumps(data, indent=2), encoding="utf-8")
print(json.dumps(data, indent=2))
```


### cURL / Bash

#### 원래 JSON · cURL / Bash

```bash
JOB_ID=$(jq -er '.id' submission.json)
RESULT_URL=$(curl --fail-with-body --silent --show-error \
  "https://api.flashdata.dev/v2/jobs/$JOB_ID/results" \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --output /dev/null --write-out '%{redirect_url}') &&
curl --fail-with-body --silent --show-error --compressed --proto '=https' \
  "${RESULT_URL:?Expected a signed result URL}" --output result.json &&
jq '{source, status, results, usage}' result.json
```


- [JSON, 텍스트 및 Markdown 형식](https://flashdata.dev/ko/docs/guides/response-formats/reference.md#completed-results)
- [저장 설정 다운로드](https://flashdata.dev/ko/docs/guides/youtube-download-guide/reference.md)

<a id="recovery"></a>

## 핸들 지연 및 실패

| - 연혁 | 해결 방법 |
| --- | --- |
| 제출 시간 | POST는 이미 받아들여질지도 모릅니다. 재조정하기 전에 저장된 영수증 및 계정 내역을 확인하십시오. 반복 된 POST는 새로운 청구 가능한 작업을 만들 수 있습니다. |
| 409 · result_not_ready | 오염 상태를 유지하십시오. 다른 일을 만들지 마십시오. |
| 422 · result_not_ready | 업무가 실패했습니다. 복원하기 전에 job.error를 읽으십시오. |
| 429 | 명예 Retry-After 또는 retry_after; 보류 용량이 가득 때 제출 속도를 감소. |
| 410 · result_expired | 저장된 결과는 완료된 후에 24 시간 만료됩니다. 저장된 사본을 사용하십시오. |

- [오류와 상태 코드](https://flashdata.dev/ko/docs/errors/reference.md)
- [CLI, polling 및 webhook 연습](https://flashdata.dev/ko/docs/guides/async-batch/reference.md)
