# Realtime e asincrona

Ottenere risultati nella risposta, o inviare un lavoro e recuperarli più tardi. Scegli come la tua applicazione o agente aspetta il lavoro.

Riferimento canonico: https://flashdata.dev/it/docs/reference/realtime-and-async
Recensito: 2026-11-04 da FlashData

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

## Scegli una modalità di richiesta

Google Search e YouTube Data supportano entrambe le modalità. YouTube Download richiede asincrona, Batch o Bulk; non supporta in tempo reale. I parametri di origine rimangono gli stessi quando si passa da in tempo reale ad asincrona.

| Modalità | Utilizzare quando | Che cosa ricevi |
| --- | --- | --- |
| Realtime | Un risultato di ricerca è necessario nell'interazione corrente. | Il corpo risultante nella stessa risposta HTTP. |
| Async | Il lavoro dovrebbe continuare dopo che il processo si disconnette, o si sta scaricando i media. | Un lavoro ID immediatamente; lo stato di acquisizione e i risultati separatamente. |

### Richiedi il ciclo di vita

```text
Realtime POST data.flashdata.dev/v1/queries/realtime → risultati
Async POST data.flashdata.dev/v1/queries → lavoro ID
          GET api.flashdata.dev/v2/jobs/{id} → stato
          GET api.flashdata.dev/v2/jobs/{id}/results → risultati
```

- [Inviare molte domande?](https://flashdata.dev/it/docs/reference/batch-and-bulk/reference.md)

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

## Invia una richiesta

Impostare FLASHDATA_API_KEY a una chiave che consente google_search. Scegliere in tempo reale o asincrona; ogni presentazione esegue una ricerca leggibile. Mantenere script, ricevute e risultati nella stessa nuova cartella di lavoro.

Gli esempi Python utilizzano Python 3.10+ e Richieste. Ogni script viene eseguito in modo indipendente e legge i file salvati dai passaggi precedenti. L'alternativa cURL ha bisogno di Bash, cURL 7.76+ e jq.

### Python · installare una volta

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

- [Chiave e intestazioni API](https://flashdata.dev/it/docs/guides/headers-and-authentication/reference.md)
- [Google Parametri di ricerca](https://flashdata.dev/it/docs/sources/google_search/reference.md)

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

### Realtime: ottenere il risultato ora

POST /v1/queries/realtime restituisce status: done e un array di risultati. Leggi result.json; non è necessario alcun polling.

#### Python

Salvare come realtime.py ed eseguire pithon3 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

##### Ottieni il risultato · 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: salvare una ricevuta di lavoro

POST /v1/queries restituisce una ricevuta di lavoro in sospeso, non i risultati della ricerca. Salvare submission.json e continuare con lo stato e le richieste di risultati qui sotto.

#### Python

Salvare come submit_async.py ed eseguire pithon3 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))
```

##### Campi riceventi · esempio abbreviato

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


#### cURL / Bash

##### Inviare e salvare il lavoro 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
```

##### Campi riceventi · esempio abbreviato

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



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

## Controllare un lavoro asincastro

Leggi job.status utilizzando lo ID in submission.json. Per l'in sospeso o l'elaborazione, attendere il ritardo Retry-After prima di controllare di nuovo; Python lo stampa e cURL lo salva in status-headers.txt. Utilizzare il backoff se non viene restituito alcun suggerimento. Una richiesta di stato di successo non significa che il lavoro sia completato.

| job.status | Prossima azione |
| --- | --- |
| pending / processing | Attendere, quindi controllare lo stesso lavoro ID di nuovo. |
| completed | Recuperare il risultato salvato. |
| failed | Leggi job.error. Fissare la causa prima di presentare nuovo lavoro. |

### Python

Salvare come job_status.py ed eseguire pithon3 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

#### Stato di lettura · 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>

## Recuperare il risultato completato

Eseguire questo dopo che job.status è completato. La risposta dei risultati di default è 302: Punti di posizione per uno storage firmato URL. Le due richieste di seguito mantengono la chiave API su FlashData e salvano l'originale JSON a result.json. Per YouTube Download, questo JSON descrive i media consegnati al vostro storage; non è il file video o audio.

### Python

Salvare come job_result.py ed eseguire pithon3 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

#### Codice originale 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
```


- [formati JSON, testo e Markdown](https://flashdata.dev/it/docs/guides/response-formats/reference.md#completed-results)
- [Scarica la configurazione di archiviazione](https://flashdata.dev/it/docs/guides/youtube-download-guide/reference.md)

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

## Maniglia ritardi e guasti

| Situazione | Cosa fare |
| --- | --- |
| La sottomissione si esaurisce | A POST potrebbe essere già stato accettato. Controllare la cronologia delle entrate e dell'account salvati prima di risottomettere; i POST ripetuti possono creare nuovi lavori fatturabili. |
| 409 · result_not_ready | Tenere lo stato di inquinamento. Non creare un altro lavoro. |
| 422 · result_not_ready | Il lavoro e' fallito. Leggi job.error prima di riprovare. |
| 429 | Onorare Retry-After o retry_after; ridurre il tasso di presentazione quando la capacità in attesa è piena. |
| 410 · result_expired | I risultati archiviati scadono ore 24 dopo il completamento. Usa la copia salvata. |

- [Errori e codici di stato](https://flashdata.dev/it/docs/errors/reference.md)
- [CLI, polling e webhook passano](https://flashdata.dev/it/docs/guides/async-batch/reference.md)
