Explorar documentação
Guias
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.
| Continue | Propósito |
|---|---|
| Comprovante do trabalho | submission.json - mantenha o trabalho aceito ID com sua tarefa de aplicação e entrada original. |
| Resposta salva | result.json - validar sua fonte e resultados antes de importá-lo. |
| Batch resultados | batch-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.
flashdata auth status --json
flashdata account balance --json
flashdata account limits --jsonMantenha este terminal aberto para os comandos restantes. Os agentes devem ler a chave de sua loja secreta ou ambiente.
# 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_KEYFaç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.
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. 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.
(
set -euC
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs wait "$JOB_ID" --timeout 2m --json
)Isso confere uma vez. Repita o GET após um pequeno atraso enquanto job.status está pendente ou processando. Em 429, espere por Retry-After de 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 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.
(
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
)O resultado padrão do JSON redireciona para o armazenamento assinado. Este código descomprime o resultado armazenado e também aceita uma resposta direta JSON. Apenas o ponto final do FlashData recebe sua chave 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. 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ção | Transição |
|---|---|
| Esperando | Persista no trabalho aceito ID antes de retornar o controle ao usuário ou agente. |
| Pronto | Marque pronto após o resultado ser salvo e validado. Use sua tarefa ID como a chave import/upsert. |
| Precisa de atenção | Mantenha o trabalho ID e erro. Um tempo de votação ou falha de recuperação não é um pedido para se submeter novamente. |
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.jsonRetomar 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.
(
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.
[
{
"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
)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 — 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.
python3 collect-batch.pypython collect-batch.pyjq '.[] | {index, job_id, status, result_file, error}' batch-results/outcomes.jsonReceba 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.
- Persista no evento e devolva 2xx imediatamente. Desduplicar delivery_id (também enviado como X-Delivery-Id).
- 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.
- Terminado, pegue e salve o resultado. No fracasso, inspecione o erro de trabalho. Continue pesquisando como um retorno se nenhum evento chegar.
{
"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"
}
]
}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ção | O que fazer |
|---|---|
| Tempo de envio esgotado | Inspecione 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 / processing | Continue verificando o trabalho existente. Esses estados não são fracassos. |
| failed / 422 | Leia job.error, corrija a causa e decida se submeterá novo trabalho. |
| 429 | Honrar Retry-After. Reduzir a concordância de submissão se a capacidade de trabalho pendente estiver cheia. |
| 404 / 409 | 404 Verifique o ID e entregando contas. 409 Os resultados ainda não estão prontos. |
| 410 | Resultado 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ção | Ponto final |
|---|---|
| Submeta um trabalho | POST https://data.flashdata.dev/v1/queries |
| Submeta um lote | POST https://data.flashdata.dev/v1/queries/batch |
| Leia o status | GET https://api.flashdata.dev/v2/jobs/{id} |
| Leia os resultados | GET 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.
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 WebhookMarkdown aplica-se aos resultados completados. Recibos e status de trabalho mantêm seus campos originais.
https://data.flashdata.dev/v1/queries