Explorar documentación
Guías
Ejecuta trabajos en segundo plano para tu aplicación o agente, reanúdalos con su ID guardado y recopila todos los resultados del lote.
En esta página
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. |
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.
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.
flashdata auth status --json
flashdata account balance --json
flashdata account limits --jsonMantenga esta terminal abierta para los comandos restantes. Los agentes deben leer la clave de su tienda secreta o entorno.
# 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_KEYEjecutar 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.
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.
flashdata search "battery recycling research" --num 5 \
--mode async --run-id async-first --output submission.json --json(
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
)2. Esperar el trabajo existente
Continúe cuando el trabajo esté terminado. Si falla, inspeccione su error antes de enviar cualquier otra cosa.
Una espera completada correctamente devuelve data.status: completed en la salida JSON de la CLI.
(
set -euC
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs wait "$JOB_ID" --timeout 2m --json
)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.
(
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
){
"job": {
"id": "EXAMPLE_JOB_ID",
"source": "google_search",
"status": "completed",
"error": null
}
}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.
(
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
)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.
(
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
)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. |
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.jsonReanudar 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.
(
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
)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.
[
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
}
},
{
"source": "google_search",
"query": "lithium battery recycling methods",
"params": {
"num": 5
}
}
]flashdata batch submit --input batch.json \
--run-id batch-first --output batch-submission.json --json(
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
)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 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)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.
python3 collect-batch.pypython collect-batch.pyjq '.[] | {index, job_id, status, result_file, error}' batch-results/outcomes.jsonRecibir 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.
- Persiste el evento y devuelve 2xx rápidamente. Deduplicar delivery_id (también enviado como X-Delivery-Id).
- 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.
- 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.
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
},
"callback_url": "https://your-app.example/webhooks/flashdata"
}{
"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"
}
]
}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.
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. |
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.
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 |
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.
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.
Prepara una solicitud
Parámetros avanzados
Empieza en 1. Cada página es una solicitud separada.
Filtro de tiempo Google, como qdr:d durante el pasado día.
Completion webhook
Carga de pago Webhook, verificación y retriesMarkdown se aplica a los resultados completados. Los receipts y el estado de trabajo mantienen sus campos originales.
https://data.flashdata.dev/v1/queries