# Solicitudes asíncronas y por lotes

Ejecuta trabajos en segundo plano para tu aplicación o agente, reanúdalos con su ID guardado y recopila todos los resultados del lote.

Referencia canónica: https://flashdata.dev/es/docs/guides/async-batch
Revisado: 2026-11-05 por FlashData

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

## Continuar el trabajo después de que tu proceso se detenga

Usar un trabajo de fondo para una tarea de aplicación extenuada o un flujo de trabajo de agente que puede terminar más tarde. Este recorrido funciona una búsqueda Google, ahorra su recibo y se reanudará de ese recibo en otro proceso.

| Mantente quieto. | Propósito |
| --- | --- |
| Comprobante del trabajo | submission.json — mantener el trabajo aceptado ID con su tarea de aplicación y la entrada original. |
| Respuesta guardada | result.json: valida su fuente y sus resultados antes de importarla. |
| Resultados Batch | batch-results/outcomes.json — una entrada por elemento de entrada, con su ID de trabajo y archivo de resultado. |

- [Realtime versus async](https://flashdata.dev/es/docs/reference/realtime-and-async/reference.md#choose)
- [Batch versus Bulk](https://flashdata.dev/es/docs/reference/batch-and-bulk/reference.md#choose)
- [Abra el constructor de flujo de trabajo](https://flashdata.dev/es/docs/guides/async-batch/reference.md#customize)

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

## Antes de empezar

Usar un API llave con google_search acceso y créditos disponibles. Elija CLI o HTTP para su presentación, espera y recuperación. Bash ejemplos de uso jq; HTTP también necesidades cURL 7.76+. Correr en una nueva carpeta de trabajo.

### CLI

Reutiliza tu perfil autenticado CLI o FLASHDATA_API_KEY. Confirme data.accessVerified es cierto. Establecer FLASHDATA_PROFILE para un perfil llamado así que los scripts posteriores lo usen también. Si no se configura ninguna clave, use la guía de autenticación CLI primero.

#### Acceso gratuito y cheques de cuenta

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

- [Instalar y autenticar el CLI](https://flashdata.dev/es/docs/guides/flashdata-cli/reference.md#existing-key)

### HTTP / cURL

Mantenga esta terminal abierta para los comandos restantes. Los agentes deben leer la clave de su tienda secreta o entorno.

#### Establecer la tecla 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
```

- [Crear una clave API](https://flashdata.dev/app/api-keys)

- [Prueba para agentes y vinculación](https://flashdata.dev/es/docs/guides/agent-onboarding/reference.md)
- [Precio de verificación](https://flashdata.dev/es/docs/guides/credits-and-billing/reference.md)

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

## Ejecutar una búsqueda de fondo

Este recorrido presenta una búsqueda Google. Los cheques de estado y la recuperación de resultados no presentan otra consulta. Reutilizar la misma credencial en todo.


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

## 1. Presentar una vez y guardar el recibo

El archivo submission.json es su recibo. HTTP devuelve un enlace id, source, status y self/results; CLI guarda el recibo bajo sumisión y también devuelve remoteId. HTTP 200 significa aceptado, no terminado.

### 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. Esperar el trabajo existente

Continúe cuando el trabajo esté terminado. Si falla, inspeccione su error antes de enviar cualquier otra cosa.

### CLI

Una espera completada correctamente devuelve data.status: completed en la salida JSON de la CLI.

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

Repetir el GET después de un breve retraso mientras job.status está pendiente o procesado. En 429, espere a Retry-After desde 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
)
```

#### Estado completado · respuesta ilustrativa HTTP

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



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

## 3. Recuperar y guardar la respuesta

Guardar result.json localmente. El trabajo completado y su cuerpo de resultado son registros separados: el cuerpo de esta búsqueda contiene fuente: google_search, una matriz de resultados y uso. La validación a continuación acepta el estado de éxito hecho o completado del resultado almacenado.

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

El resultado predeterminado de JSON redirige al almacenamiento firmado. Este código descomprime el resultado almacenado y también acepta una respuesta directa de JSON. Sólo el punto final FlashData recibe su llave 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
)
```


- [Inspeccionar y guardar resultados de búsqueda](https://flashdata.dev/es/docs/guides/google-search-guide/reference.md#results)

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

## 4. Utilice el resultado en su aplicación

Validar la respuesta guardada, luego extraer el título, enlace y snippet para una vista de búsqueda o el siguiente paso del agente. Un array orgánico vacío exitoso significa que no hay elementos coincidentes; un campo perdido o cuerpo fallido necesita investigación.

| Tareas de aplicación | Transición |
| --- | --- |
| Esperando | Persiste el trabajo aceptado ID antes de devolver el control al usuario o agente. |
| Listo | Marcar listo después de que el resultado se guarda y valida. Utilice su tarea ID como la clave import/upsert. |
| Necesita atención | Mantenga el trabajo ID y el error. Un tiempo de votación o fallo de recuperación no es una solicitud de presentar de nuevo. |

### Lea la respuesta local · sin llamadas 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
```

- [Archivo y reutilización de la respuesta](https://flashdata.dev/es/docs/guides/save-results/reference.md)

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

## Reanudar en otro proceso

Abrir un terminal fresco en la misma carpeta, con la misma credencial/profile. Estos comandos leen el trabajo en submission.json y guardar a un nuevo nombre de archivo. Ellos nunca envían trabajo. CLI Corren ID requiere su directorio estatal original; HTTP en sí mismo no deduplicar los POST usando esa carrera local ID.

### CLI + jq · recuperar el trabajo guardado

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

- [Resultado de la presentación desconocida](https://flashdata.dev/es/docs/guides/agent-recovery/reference.md#recover)

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

## Presentar varias consultas

Batch presenta empleos independientes en una sola solicitud. Este ejemplo de dos preguntas necesita capacidad para al menos dos consultas y dos trabajos pendientes; un ensayo temporal se limita a uno. Guardar la matriz abajo como batch.json en una carpeta de trabajo independiente.

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

### Guardar collect-batch.py

Cree collect-batch.py en la carpeta de trabajo Batch junto a batch.json y batch-submission.json. Copia el código completo a continuación y guárdalo.

Mantenga batch.json, batch-submission.json y resultos por lotes/ juntos. El script se detiene si las entradas o recibos guardados cambian. Reutiliza archivos locales completados y nunca presenta consultas de reemplazo después de un error de lectura.

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

### Seguimiento de cada trabajo aceptado

Después de guardar collect-batch.py, ejecute desde la carpeta de trabajo Batch con Python 3.10+ y el autentificado CLI. Funciona con el método de presentación anterior. Lee cada recibo, espera hasta dos minutos por trabajo sin terminar y ahorra cada respuesta exitosa. Ejecute un colector a la vez; vuelva a ejecutarlo para continuar los mismos trabajos.

El ejemplo debe producir dos entradas en batch-results/outcomes.json. Importa las completadas por índice de entrada e ID de trabajo. Las entradas con errores, pendientes o read_error siguen visibles; el código de salida 2 indica que debes revisarlas o reanudarlas. El recopilador no envía nuevas consultas.

#### Bash

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

#### PowerShell 7

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

#### Leer cada resultado · jq

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

- [Modelo de resultado de Batch](https://flashdata.dev/es/docs/reference/batch-and-bulk/reference.md#batch-results)
- [Registro de la aplicación IDs](https://flashdata.dev/es/docs/guides/enrich-youtube-videos/reference.md)

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

## Recibir un Webhook de terminación

Añadir callback_url junto a la fuente, consulta y params en una sola solicitud o cada entrada Batch. Reemplazar el ejemplo URL con su receptor. Eventos reporte finalización o fracaso; recuperar el resultado por separado.

1. Persiste el evento y devuelve 2xx rápidamente. Deduplicar delivery_id (también enviado como X-Delivery-Id).
2. El evento no está firmado. Coincide con su id y fuente a su recibo guardado, luego autentique un estado leído utilizando el enlace de la recepción original. No confíe en URLs suministrado por un evento no verificado.
3. Al terminar, buscar y guardar el resultado. Al fallar, inspeccione el error de trabajo. Mantenga la votación como un retroceso si no llega ningún evento.

### Solicitar cuerpo con un callback

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

### Cuerpo de eventos · ilustrativo

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

- [Generar un receptor en el constructor de flujos de trabajo](https://flashdata.dev/es/docs/guides/async-batch/reference.md#customize)

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

### Requisitos de llamada URL

Utilice un HTTPS URL público en el puerto 443, en la mayoría de los caracteres 2,048, sin credenciales o un fragmento. Cada IP resuelta debe ser pública. Omit callback_url, o utilizar nulo o una cadena vacía, para desactivar notificaciones.


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

## Recuperar un trabajo existente

| Situación | Qué hacer |
| --- | --- |
| Fecha límite de presentación | Las carreras de inspección muestran async-first y cuenta Historia. carreras recuperar puede recuperar trabajo aceptado IDs; si no se salvó ID, reconciliar la presentación antes de enviar otro POST. |
| pending / processing | Sigue revisando el trabajo existente, estos estados no son fracasos. |
| failed / 422 | Lea job.error, corrija la causa y decida si debe presentar un nuevo trabajo. |
| 429 | Honor Retry-After. Reducir el acuerdo de presentación si la capacidad de trabajo pendiente está completa. |
| 404 / 409 | 404: verifique el ID y la cuenta de envío. 409: los resultados aún no están listos. |
| 410 | Resultado almacenado JSON expira las horas 24 después de la terminación. Utilice su copia guardada. Los medios ya entregados a su almacenamiento sigue la política de retención de almacenamiento. |

- [Límites de tarifas y uso](https://flashdata.dev/es/docs/guides/usage-and-limits/reference.md)
- [Recuperación de funcionamiento CLI](https://flashdata.dev/es/docs/guides/cli-automation/reference.md#recover)

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

## Ejecutar un YouTube Descargar trabajo?

Descargar utiliza async o Batch y necesita una tecla API propietario con acceso youtube_download más almacenamiento de destino. Resultado JSON describe los medios ya entregados a su cubo; el punto final de los resultados no transmite los bytes de vídeo. Utilice la guía de descarga para configurar el almacenamiento y verificar el archivo entregado.

- [Configurar almacenamiento y descarga](https://flashdata.dev/es/docs/guides/youtube-download-guide/reference.md)
- [Verificar los medios entregados](https://flashdata.dev/es/docs/guides/youtube-download-guide/reference.md#verify-media)

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

## Hosts y formatos de respuesta

Los cuatro usan X-API-Key. Utilice la misma clave que la presentación. Estado y resultado leídos son gratuitos, pero limitados por tarifas. Los ejemplos utilizan JSON; elige Accept y X-Respond-With en el constructor para otras representaciones de resultados. Una descarga de almacenamiento firmada utiliza su URL, sin la tecla FlashData.

| Operación | Punto final |
| --- | --- |
| Submit one job | POST https://data.flashdata.dev/v1/queries |
| Presentar un lote | POST https://data.flashdata.dev/v1/queries/batch |
| Estado de lectura | GET https://api.flashdata.dev/v2/jobs/{id} |
| Leer resultados | GET https://api.flashdata.dev/v2/jobs/{id}/results |

- [Protocolo Realtime y async](https://flashdata.dev/es/docs/reference/realtime-and-async/reference.md)
- [Protocolo de solicitud de Batch](https://flashdata.dev/es/docs/reference/batch-and-bulk/reference.md)
- [Normas de formato de respuesta](https://flashdata.dev/es/docs/guides/response-formats/reference.md)

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

## Fuentes y modos de apoyo

Utilice el constructor a continuación para los parámetros actuales de la fuente. Google Buscar y YouTube Trabajos de soporte de datos. YouTube Download utiliza trabajos de fondo y almacenamiento de destino. Para un gran archivo de vídeo IDs con opciones compartidas, utilice la guía Bulk.

- [Modos de solicitud](https://flashdata.dev/es/docs/reference/realtime-and-async/reference.md#choose)
- [flujo de trabajo de archivos Bulk](https://flashdata.dev/es/docs/guides/bulk/reference.md)

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

## Construya un flujo de trabajo para su fuente

Escoge una fuente, edita sus parámetros y copia el flujo de trabajo generado en tu idioma. Permite un callback para revelar el ejemplo del receptor. Este constructor prevea el código y las respuestas de la muestra; las solicitudes se ejecutan sólo cuando ejecuta el código o utiliza la consola.

- [Parámetros de origen y esquemas](https://flashdata.dev/es/docs/reference/reference.md)
