Pular para o conteúdo
PT
Obter chave API
Explorar documentação

Guias

Async e pedidos de lote

Executar o trabalho de fundo para um aplicativo ou agente, retomar de seu trabalho salvo ID e coletar todos os resultados do lote.

Nesta página

Continue trabalhando depois que seu processo parar

Use uma tarefa de fundo para uma tarefa de aplicativo na fila ou um fluxo de trabalho de agente que pode finish mais tarde. Esta caminhada faz uma busca no Google, guarda seu recibo e retoma daquele recibo em outro processo.

ContinuePropósito
Comprovante do trabalhosubmission.json - mantenha o trabalho aceito ID com sua tarefa de aplicação e entrada original.
Resposta salvaresult.json - validar sua fonte e resultados antes de importá-lo.
Batch resultadosbatch-results/outcomes.json - uma entrada por entrada, com seu trabalho ID e arquivo de resultado.

Antes de começar

Use uma chave API com acesso google_search e créditos disponíveis. Escolha CLI ou HTTP para submissão, espera e recuperação. Os exemplos Bash usam jq; HTTP também precisa cURL 7.76+. Corra em uma nova pasta de trabalho.

Reutilize seu perfil CLI autenticado ou FLASHDATA_API_KEY. Confirmar data.accessVerified é true. Defina FLASHDATA_PROFILE para um perfil chamado então scripts mais tarde usam também. Se nenhuma chave estiver configurada, use o guia de autenticação CLI primeiro.

Acesso gratuito e verificações de contas
flashdata auth status --json
flashdata account balance --json
flashdata account limits --json

Faça uma busca de fundo

Esta passagem envia um Google Search. Verificações de status e recuperação de resultados não enviam outra pergunta. Reutilize a mesma credencial.

1. Submeta-se uma vez e guarde o recibo

O arquivo submission.json é o seu recibo. HTTP retorna um id, fonte, status e ligações self/results; CLI salva o recibo sob submissão e também devolve remoteId. HTTP 200 significa aceito, não terminado.

Bash · FlashData CLI
flashdata search "battery recycling research" --num 5 \
  --mode async --run-id async-first --output submission.json --json

2. Aguarde o trabalho existente

Continue quando o trabalho estiver concluído. Se falhou, inspecione o erro antes de enviar qualquer outra coisa.

Uma espera bem sucedida retorna data.status: completed em CLI JSON.

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 e salvar a resposta

Salve result.json localmente. O trabalho concluído e seu corpo de resultados são registros separados: o corpo desta busca contém fonte: google_search, uma matriz de resultados e uso. A validação abaixo aceita o resultado armazenado feito ou concluído status de sucesso.

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. Use o resultado em sua aplicação

Validar a resposta salva, então extrair título, link e trecho para uma visão de busca ou o próximo passo do agente. Uma matriz orgânica vazia de sucesso significa que não há itens correspondentes, um campo perdido ou corpo fracassado precisa de investigação.

Tarefa de aplicaçãoTransição
EsperandoPersista no trabalho aceito ID antes de retornar o controle ao usuário ou agente.
ProntoMarque pronto após o resultado ser salvo e validado. Use sua tarefa ID como a chave import/upsert.
Precisa de atençãoMantenha o trabalho ID e erro. Um tempo de votação ou falha de recuperação não é um pedido para se submeter novamente.
Leia a resposta local, sem chamadas 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

Retomar em outro processo

Abra um terminal novo na mesma pasta, com o mesmo credential/profile.. Esses comandos leram o trabalho em submission.json e salvaram para um novo nome de arquivo. Eles nunca se submetem a trabalho. Reusar o mesmo CLI executar ID requer seu diretório de estado original; HTTP em si não desduplica POSTS usando essa corrida local ID.

CLI + jq · recuperar o trabalho salvo
(
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
)

Envie várias perguntas

Batch submete trabalhos independentes em um pedido. Este exemplo precisa de capacidade para pelo menos duas consultas e dois trabalhos pendentes, um teste temporário é limitado a um. Guarde o array abaixo como batch.json em uma pasta de trabalho separada.

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

Salve collect-batch.py

Crie collect-batch.py na pasta de trabalho Batch ao lado de batch.json e batch-submission.json. Copie o código completo abaixo e salve-o.

Mantenha batch.json, batch-submission.json e resultados em lote/juntos. O roteiro para se as entradas salvas ou recibos mudarem. Ele reutiliza arquivos locais completos e nunca envia consultas de substituição após um erro de leitura.

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)

Rastreie cada trabalho aceito

Depois de salvar collect-batch.py, execute-o da pasta de trabalho Batch com Python 3.10+ e o CLI autenticado. Funciona com qualquer método de submissão acima. Ele lê cada recibo, espera até dois minutos por trabalho inacabado e salva cada resposta bem sucedida. Corra um colecionador de cada vez, reproduza para continuar os mesmos trabalhos.

Espere duas entradas no batch-results/outcomes.json para a amostra. Importar entradas completas por índice de entrada e trabalho ID. Falhado, pendentes e entradas read_error permanecem visíveis; código de saída 2 significa revisão ou retomada. O colecionador não envia novas perguntas.

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

Receba um webhook completo

Adicione callback_url ao lado de fonte, consulta e params em um único pedido ou cada entrada Batch. Substitua o exemplo URL pelo seu receptor. Os eventos reportam conclusão ou falha, recuperam o resultado separadamente.

  1. Persista no evento e devolva 2xx imediatamente. Desduplicar delivery_id (também enviado como X-Delivery-Id).
  2. O evento não está assinado. Coincidir seu id e fonte com seu recibo salvo, e então autenticar um status lido usando o link do recibo original. Não confie em URLs fornecido por um evento não verificado.
  3. Terminado, pegue e salve o resultado. No fracasso, inspecione o erro de trabalho. Continue pesquisando como um retorno se nenhum evento chegar.
Requisito corpo com uma chamada de volta
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
Corpo 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"
    }
  ]
}

RECURSOS DE URL

Use um HTTPS URL público no porto 443, no máximo caracteres 2,048, sem credenciais ou um fragmento. Todo IP resolvido deve ser público. Omita callback_url, ou use null ou uma string vazia, para desativar notificações.

Recupere um trabalho existente

SituaçãoO que fazer
Tempo de envio esgotadoInspecione runs show primeiro e conta History. runs recover pode recuperar o trabalho aceito IDs; se nenhum ID foi salvo, concilie a submissão antes de enviar outro POST.
pending / processingContinue verificando o trabalho existente. Esses estados não são fracassos.
failed / 422Leia job.error, corrija a causa e decida se submeterá novo trabalho.
429Honrar Retry-After. Reduzir a concordância de submissão se a capacidade de trabalho pendente estiver cheia.
404 / 409404 Verifique o ID e entregando contas. 409 Os resultados ainda não estão prontos.
410Resultado armazenado JSON expira 24 horas após a conclusão. Use sua cópia guardada. A mídia já foi entregue ao seu armazenamento, segue a política de retenção do armazenamento.

Dirigindo um trabalho de download YouTube?

O download usa async ou Batch e precisa de uma chave API com acesso youtube_download mais armazenamento de destino. Seu resultado JSON descreve a mídia já entregue ao seu balde, o ponto final de resultados não transmite bytes de vídeo. Use o guia de download para configurar o armazenamento e verificar o arquivo entregue.

Hosts e formatos de resposta

Todos os quatro usam X-API-Key. Use a mesma chave que a submissão. Status e resultado são livres, mas limitados. Os exemplos usam JSON; escolha Accept e X-Respond-With no construtor para outras representações de resultados. Um download de armazenamento assinado usa seu URL, sem a chave FlashData.

OperaçãoPonto final
Submeta um trabalhoPOST https://data.flashdata.dev/v1/queries
Submeta um lotePOST https://data.flashdata.dev/v1/queries/batch
Leia o statusGET https://api.flashdata.dev/v2/jobs/{id}
Leia os resultadosGET https://api.flashdata.dev/v2/jobs/{id}/results

Fontes e modos apoiados

Use o construtor abaixo para os parâmetros atuais da fonte. Google Search e YouTube Data suportam trabalhos de fundo. YouTube Download usa trabalhos de fundo e armazenamento de destino. Para um grande arquivo de vídeo IDs com opções compartilhadas, use o guia Bulk.

Construa um fluxo de trabalho para sua fonte

Escolha uma fonte, edite seus parâmetros e copie o fluxo de trabalho gerado em seu idioma. Ative uma chamada para revelar o exemplo do receptor. Este construtor pré-visualiza as respostas de código e amostra; solicitações são executadas apenas quando você executa o código ou usa o console.

Parâmetros de origem

Monte uma requisição

Parâmetros avançados

Começa em 1. Cada página é uma requisição separada.

Filtro de tempo do Google, como qdr:d para as últimas 24 horas.

"Filme de finalização"Carregamento, verificação e repetições do Webhook

Markdown aplica-se aos resultados completados. Recibos e status de trabalho mantêm seus campos originais.

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']}")
Recibo de trabalho, e depois pesquisa para resultadosX-API-Key autenticação