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

Referência canônica: https://flashdata.dev/pt/docs/guides/async-batch
2026-11-05 por FlashData

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

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

- [Realtime versus async](https://flashdata.dev/pt/docs/reference/realtime-and-async/reference.md#choose)
- [Batch versus Bulk](https://flashdata.dev/pt/docs/reference/batch-and-bulk/reference.md#choose)
- [Abra o construtor de fluxo de trabalho](https://flashdata.dev/pt/docs/guides/async-batch/reference.md#customize)

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

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

### CLI

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

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

- [Instale e autentice o CLI](https://flashdata.dev/pt/docs/guides/flashdata-cli/reference.md#existing-key)

### HTTP / cURL

Mantenha este terminal aberto para os comandos restantes. Os agentes devem ler a chave de sua loja secreta ou ambiente.

#### Defina sua chave 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
```

- [Crie uma chave API](https://flashdata.dev/app/api-keys)

- [Teste para agentes e vinculação](https://flashdata.dev/pt/docs/guides/agent-onboarding/reference.md)
- [Verifique os preços](https://flashdata.dev/pt/docs/guides/credits-and-billing/reference.md)

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

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


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

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

### 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. Aguarde o trabalho existente

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

### CLI

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

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

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.

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

#### Status finalizado · Resposta ilustrativa de HTTP

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



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

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

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

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.

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


- [Inspecione e salve resultados de busca](https://flashdata.dev/pt/docs/guides/google-search-guide/reference.md#results)

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

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

### Leia a resposta local, sem chamadas 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
```

- [Arquive e reutilize a resposta](https://flashdata.dev/pt/docs/guides/save-results/reference.md)

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

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

```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 desconhecido da submissão](https://flashdata.dev/pt/docs/guides/agent-recovery/reference.md#recover)

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

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

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

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

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

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

#### PowerShell 7

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

#### Leia cada resultado. jq

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

- [Batch modelo de resultado](https://flashdata.dev/pt/docs/reference/batch-and-bulk/reference.md#batch-results)
- [Mantenha o registro da aplicação IDs](https://flashdata.dev/pt/docs/guides/enrich-youtube-videos/reference.md)

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

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

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

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

- [Gere um receptor no construtor de fluxo de trabalho](https://flashdata.dev/pt/docs/guides/async-batch/reference.md#customize)

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

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


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

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

- [Limites de taxa e uso](https://flashdata.dev/pt/docs/guides/usage-and-limits/reference.md)
- [CLI recuperação de execução](https://flashdata.dev/pt/docs/guides/cli-automation/reference.md#recover)

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

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

- [Configure o armazenamento e o download](https://flashdata.dev/pt/docs/guides/youtube-download-guide/reference.md)
- [Verifique a mídia entregue](https://flashdata.dev/pt/docs/guides/youtube-download-guide/reference.md#verify-media)

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

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

- [Realtime e protocolo ASYNC](https://flashdata.dev/pt/docs/reference/realtime-and-async/reference.md)
- [Batch protocolo de solicitação](https://flashdata.dev/pt/docs/reference/batch-and-bulk/reference.md)
- [Regras do formato de resposta](https://flashdata.dev/pt/docs/guides/response-formats/reference.md)

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

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

- [Solicitar modos](https://flashdata.dev/pt/docs/reference/realtime-and-async/reference.md#choose)
- [Fluxo de trabalho de arquivos Bulk](https://flashdata.dev/pt/docs/guides/bulk/reference.md)

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

## 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 e esquemas](https://flashdata.dev/pt/docs/reference/reference.md)
