Saltar al contenido
ES
Obtener clave API
Explorar documentación

Guías

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.

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 trabajosubmission.json — mantener el trabajo aceptado ID con su tarea de aplicación y la entrada original.
Respuesta guardadaresult.json: valida su fuente y sus resultados antes de importarla.
Resultados Batchbatch-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.

Acceso gratuito y cheques de cuenta
flashdata auth status --json
flashdata account balance --json
flashdata account limits --json

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.

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.

Bash · FlashData CLI
flashdata search "battery recycling research" --num 5 \
  --mode async --run-id async-first --output submission.json --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.

Bash · FlashData CLI
(
set -euC
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs wait "$JOB_ID" --timeout 2m --json
)

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.

Bash · FlashData CLI
(
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
)

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ónTransición
EsperandoPersiste el trabajo aceptado ID antes de devolver el control al usuario o agente.
ListoMarcar listo después de que el resultado se guarda y valida. Utilice su tarea ID como la clave import/upsert.
Necesita atenciónMantenga 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
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

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
(
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.

batch.json
[
  {
    "source": "google_search",
    "query": "battery recycling research",
    "params": {
      "num": 5
    }
  },
  {
    "source": "google_search",
    "query": "lithium battery recycling methods",
    "params": {
      "num": 5
    }
  }
]
Bash · FlashData CLI
flashdata batch submit --input batch.json \
  --run-id batch-first --output batch-submission.json --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
# 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.

Bash
python3 collect-batch.py
PowerShell 7
python collect-batch.py
Leer cada resultado · jq
jq '.[] | {index, job_id, status, result_file, error}' batch-results/outcomes.json

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
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
Cuerpo de eventos · ilustrativo
{
  "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ónQué hacer
Fecha límite de presentaciónLas 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 / processingSigue revisando el trabajo existente, estos estados no son fracasos.
failed / 422Lea job.error, corrija la causa y decida si debe presentar un nuevo trabajo.
429Honor Retry-After. Reducir el acuerdo de presentación si la capacidad de trabajo pendiente está completa.
404 / 409404: verifique el ID y la cuenta de envío. 409: los resultados aún no están listos.
410Resultado 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ónPunto final
Submit one jobPOST https://data.flashdata.dev/v1/queries
Presentar un lotePOST https://data.flashdata.dev/v1/queries/batch
Estado de lecturaGET https://api.flashdata.dev/v2/jobs/{id}
Leer resultadosGET 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.

Parámetros de origen

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 webhookCarga de pago Webhook, verificación y retries

Markdown se aplica a los resultados completados. Los receipts y el estado de trabajo mantienen sus campos originales.

POSThttps://data.flashdata.dev/v1/queries
import gzip
import json
import random
import time
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"
payload = {
    "source": "google_search",
    "query": "openai",
    "params": {
        "gl": "us",
        "hl": "en",
        "num": 10,
        "page": 1,
    },
}

def api_get(url):
    request = urllib.request.Request(url, headers={"X-API-Key": api_key})
    with urllib.request.urlopen(request, timeout=60) as response:
        return json.load(response), response.headers

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, request, file_pointer, code, message, headers, new_url):
        return None

def read_result(url):
    request = urllib.request.Request(url, headers={"X-API-Key": api_key})
    try:
        with urllib.request.build_opener(NoRedirect).open(request, timeout=60):
            raise RuntimeError("Expected a result redirect")
    except urllib.error.HTTPError as response:
        if response.code != 302 or not response.headers.get("Location"):
            raise
        storage_url = response.headers["Location"]
        response.close()
    # Never forward the API key to storage.
    with urllib.request.urlopen(urllib.request.Request(storage_url, headers={"Accept-Encoding": "gzip"}), timeout=60) as response:
        content = response.read()
        if response.headers.get("Content-Encoding") == "gzip":
            content = gzip.decompress(content)
        return json.loads(content)

def link(job, relation):
    return next(item["href"] for item in job["links"] if item["rel"] == relation)

request = urllib.request.Request(
    "https://data.flashdata.dev/v1/queries",
    data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
    headers={"Content-Type": "application/json", "X-API-Key": api_key},
    method="POST",
)
with urllib.request.urlopen(request, timeout=120) as response:
    submission = json.load(response)
jobs = submission.get("queries", [submission])
for submitted in jobs:
    print("Job:", submitted["id"])
    deadline = time.monotonic() + 300
    while time.monotonic() < deadline:
        status, headers = api_get(link(submitted, "self"))
        job = status.get("job", status)
        if job["status"] == "completed":
            result = job.get("result") if submitted["source"] == "youtube_download" and job.get("result") is not None else read_result(link(submitted, "results"))
            print(json.dumps(result, ensure_ascii=False, indent=2))
            break
        if job["status"] == "failed":
            raise RuntimeError(f"{submitted['id']}: {job.get('error', 'Job failed')}")
        hint = headers.get("Retry-After", "1")
        delay = max(1, min(5, int(hint))) if hint.isdigit() else 5
        time.sleep(min(delay * random.uniform(1, 1.2), max(0, deadline - time.monotonic())))
    else:
        raise TimeoutError(f"Still running; save this job ID: {submitted['id']}")
Recibimiento de empleo, luego encuesta para los resultadosautenticación X-API-Key