# Processamento de arquivos Bulk

Processe um arquivo de vídeo IDs, recupere cada parte do resultado e verifique a cobertura antes de importar o conjunto de dados para sua aplicação.

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

<a id="first-task"></a>

## De um arquivo ID a um conjunto de dados verificados

Use este fluxo de trabalho para um catálogo de vídeo, coleta de pesquisa ou fila de ingestão. Um arquivo usa uma fonte e as mesmas opções para cada ID. Comece com a amostra de metadados de dois vídeos, e depois substitua seu próprio arquivo.

### Arquivos produzidos por este fluxo de trabalho

```text
video-ids.txt → Bulk trabalho → bulk-results.ndjson
  → Resultados audit/completed.ndjson para sua aplicação
  → audit/failed-video-ids.txt confirmou falhas na revisão.
  → audit/missing.ndjson entradas cujos resultados estão faltando
  →audit/summary.json cobertura e resultados conta
```

- [Mantenha o registro da aplicação IDs com uma pequena lista](https://flashdata.dev/pt/docs/guides/enrich-youtube-videos/reference.md)
- [Batch versus Bulk](https://flashdata.dev/pt/docs/reference/batch-and-bulk/reference.md#choose)
- [Bulk API playground](https://flashdata.dev/pt/docs/reference/bulk-processing/reference.md#playground)
- [Downloads de vídeos do YouTube em massa](https://flashdata.dev/pt/products/youtube-download#bulk-downloads)

<a id="before-you-start"></a>

## Antes de começar

Instale o CLI e use um perfil existente ou FLASHDATA_API_KEY com permissão youtube_metadata. Confirme data.accessVerified: true e reveja o saldo disponível, preços para dois pedidos e limites atuais. Para o seu próprio arquivo, use a conta ID ao verificar os preços. Cada ID processado é uma consulta separada, não uma carga plana para o arquivo.

Use Bash com jq ou PowerShell 7 para os passos 1–3. A auditoria de importação opcional na etapa 4 usa Python 3.10+ e sua biblioteca padrão. O próprio CLI não requer Node.js nem Python.

### Acesso gratuito e verificações de contas

```bash
flashdata auth status --json
flashdata account balance --json
flashdata account pricing --source youtube_metadata --request-count 2
flashdata account limits
```

- [Instale o CLI](https://flashdata.dev/pt/docs/guides/flashdata-cli/reference.md#install)
- [Crie uma chave API](https://flashdata.dev/app/api-keys)
- [Agente acesso e reivindicando](https://flashdata.dev/pt/docs/guides/agent-access/reference.md)
- [Use HTTP em vez disso](https://flashdata.dev/pt/docs/reference/bulk-processing/reference.md#endpoints)

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

## 1Prepare-se. IDs

Corra em uma nova pasta de trabalho. Use a UTF.8 Mandar mensagem com um. 11-Vídeo de caráter ID por linha, não um YouTube URL. O tamanho máximo do arquivo é 2 GiB. Remova linhas em branco e duplicações: o CLI rejeita entradas malformadas, e IDs repetidos são processados separadamente.

### Bash

#### Bash

```bash
# Run in a new working directory.
(
  set -euC
  printf '%s\n' 'jNQXAC9IVRw' 'dQw4w9WgXcQ' > video-ids.txt
)
cat video-ids.txt
```


### PowerShell 7

#### PowerShell 7

```powershell
if (Test-Path -LiteralPath video-ids.txt) { throw 'Keep the existing file or use a new folder.' }
$idsFile = Join-Path (Get-Location) 'video-ids.txt'
$idsText = [string]::Join([char]10, @('jNQXAC9IVRw', 'dQw4w9WgXcQ', ''))
[IO.File]::WriteAllText($idsFile, $idsText, [Text.UTF8Encoding]::new($false))
Get-Content -LiteralPath video-ids.txt
```



<a id="run"></a>

## 2. Processe o arquivo

O CLI cria um trabalho, carrega o arquivo, começa a processar e salva cada parte do resultado em um arquivo NDJSON. Use um novo caminho de saída. A corrida local ID em massa primeiro mantém o recibo remoto de trabalho para recuperação.

### Bash

#### Bash

```bash
flashdata bulk run --source youtube_metadata \
  --input video-ids.txt --run-id bulk-first \
  --output bulk-results.ndjson --timeout 30m --json
```


### PowerShell 7

#### PowerShell 7

```powershell
flashdata bulk run --source youtube_metadata `
  --input video-ids.txt --run-id bulk-first `
  --output bulk-results.ndjson --timeout 30m --json
```


- [Verifique o progresso em outro terminal](https://flashdata.dev/pt/docs/guides/bulk/reference.md#progress)
- [Recupere-se depois de um tempo](https://flashdata.dev/pt/docs/guides/bulk/reference.md#controls)

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

## 3. Verifique os resultados

Abra o bulk-results.ndjson. Cada linha é um registro JSON com índice, video_id e status. Linhas bem-sucedidas contêm uma matriz de resultados; linhas falhadas contêm um erro. Junte os registros à entrada por índice baseado em zero, não ordem de arquivos. O comando Bash usa jq.

### Uma fileira bem sucedida, um exemplo abreviado

```json
{"index":0,"video_id":"jNQXAC9IVRw","source":"youtube_metadata","status":"completed","results":[{"videoId":"jNQXAC9IVRw","title":"Example video title"}]}
```

### Bash

#### Bash

```bash
# Bash + jq: read each record without loading the whole file.
jq -c '{index, video_id, status, title: .results[0].title, error}' bulk-results.ndjson
```


### PowerShell 7

#### PowerShell 7

```powershell
Get-Content -LiteralPath bulk-results.ndjson | ForEach-Object {
  $row = $_ | ConvertFrom-Json
  $title = if ($row.results) { $row.results[0].title } else { $null }
  [pscustomobject]@{ index = $row.index; video_id = $row.video_id; status = $row.status; title = $title; error = $row.error }
}
```



<a id="audit"></a>

## 4. Verifique a cobertura antes de importar

Salve audit-bulk.py abaixo. Compare com o arquivo de entrada inalterado e todas as partes recuperadas. Ele verifica todos os índices, vídeos ID e fonte, rejeita linhas de resultados duplicadas, e separa falhas confirmadas de resultados perdidos. Para outra fonte, adicione --source SOURCE_ID.

inputRows: 2, completado: 2, falhou: 0, faltando: 0 e allSucceeded: true para a amostra de sucesso. Apenas linhas completas pertencem à importação do resultado da aplicação. Mantenha o resumo da auditoria e resultados mal sucedidos ao lado deles.


<a id="audit-script"></a>

### Salve audit-bulk.py

Crie audit-bulk.py ao lado de video-ids.txt e bulk-results.ndjson na pasta de trabalho. Copie o código completo abaixo e salve-o.

O script lê arquivos linha por linha e usa um índice SQLite local em vez de carregar todo o conjunto de dados na memória. Requer um arquivo de entrada validado do vídeo IDs. Cada auditoria usa um novo diretório de saída, arquivos parciais permanecem separados até o final da análise.

#### audit-bulk.py

```python
# audit-bulk.py — Python 3.10+, standard library only; no network requests.
import argparse
import json
import re
import sqlite3
import sys
from contextlib import ExitStack
from pathlib import Path

parser = argparse.ArgumentParser()
parser.add_argument('--input', required=True)
parser.add_argument('--results', required=True)
parser.add_argument('--out', required=True)
parser.add_argument('--source', default='youtube_metadata')
args = parser.parse_args()
out = Path(args.out)
try:
    out.mkdir()  # Keep any previous audit. Use a new directory for another attempt.
    with ExitStack() as stack:
        db = sqlite3.connect(out / 'index.sqlite')
        stack.callback(db.close)
        db.execute('CREATE TABLE inputs (idx INTEGER PRIMARY KEY, video_id TEXT, outcome TEXT)')
        count = 0
        with open(args.input, encoding='utf-8-sig') as inputs:
            for index, line in enumerate(inputs):
                video_id = line.strip()
                if not re.fullmatch(r'[A-Za-z0-9_-]{11}', video_id):
                    raise ValueError('Invalid ID on input line ' + str(index + 1))
                db.execute('INSERT INTO inputs VALUES (?, ?, NULL)', (index, video_id))
                count += 1
        if not count:
            raise ValueError('The input file is empty.')
        db.commit()
        files = {name: stack.enter_context(open(out / (name + '.part'), 'x', encoding='utf-8'))
                 for name in ['completed.ndjson', 'failed.ndjson', 'missing.ndjson', 'failed-video-ids.txt']}
        completed = failed = 0
        with open(args.results, encoding='utf-8-sig') as results:
            for line_number, line in enumerate(results, 1):
                if not line.strip():
                    continue
                row = json.loads(line)
                if not isinstance(row, dict) or type(row.get('index')) is not int:
                    raise ValueError('Invalid result index on line ' + str(line_number))
                expected = db.execute('SELECT video_id, outcome FROM inputs WHERE idx = ?',
                                      (row['index'],)).fetchone()
                if (not expected or row.get('video_id') != expected[0]
                        or row.get('source') != args.source or expected[1] is not None):
                    raise ValueError('Unknown, duplicate or mismatched result on line ' + str(line_number))
                status = row.get('status')
                if status not in ['completed', 'failed']:
                    raise ValueError('Unexpected item status on line ' + str(line_number))
                if status == 'completed':
                    if not isinstance(row.get('results'), list):
                        raise ValueError('Completed row is missing its results array.')
                    if args.source == 'youtube_metadata' and (len(row['results']) != 1
                            or not isinstance(row['results'][0], dict)
                            or row['results'][0].get('videoId') != expected[0]):
                        raise ValueError('Metadata does not belong to the requested video.')
                    completed += 1
                else:
                    failed += 1
                db.execute('UPDATE inputs SET outcome = ? WHERE idx = ?', (status, row['index']))
                files[status + '.ndjson'].write(json.dumps(row, ensure_ascii=False) + '\n')
        db.commit()
        missing = 0
        for index, video_id in db.execute('SELECT idx, video_id FROM inputs WHERE outcome IS NULL ORDER BY idx'):
            files['missing.ndjson'].write(json.dumps({'index': index, 'video_id': video_id,
                                                     'status': 'missing_result'}) + '\n')
            missing += 1
        for (video_id,) in db.execute("SELECT video_id FROM inputs WHERE outcome = 'failed' GROUP BY video_id ORDER BY MIN(idx)"):
            files['failed-video-ids.txt'].write(video_id + '\n')
        summary = {'source': args.source, 'inputRows': count, 'completed': completed,
                   'failed': failed, 'missing': missing, 'coverageComplete': missing == 0,
                   'allSucceeded': failed == 0 and missing == 0}
    for name in files:
        (out / (name + '.part')).rename(out / name)
    with open(out / 'summary.json', 'x', encoding='utf-8') as output:
        json.dump(summary, output, indent=2)
    print(json.dumps(summary, indent=2))
    sys.exit(0 if summary['allSucceeded'] else 2)
except Exception as error:
    print(str(error), file=sys.stderr)
    print('Audit not complete. Preserve this directory and inspect the inputs/results.', file=sys.stderr)
    sys.exit(1)
```


<a id="run-audit"></a>

### Execute a auditoria de importação

Corra da pasta que contém o script, entrada original e resultados baixados. A auditoria só lê arquivos locais.

#### Bash

##### Bash

```bash
python3 audit-bulk.py --input video-ids.txt --results bulk-results.ndjson --out audit
```


#### PowerShell 7

##### PowerShell 7

```powershell
python audit-bulk.py --input video-ids.txt --results bulk-results.ndjson --out audit
```



<a id="import"></a>

### Importar linhas completas e manter a auditoria

| Arquivo / sinal | Use-o assim |
| --- | --- |
| completed.ndjson | Junte-se pelo índice ao arquivo original. Use video_id para uma chave de catálogo, mantenha a identidade job/snapshot ao armazenar o histórico de atualização. |
| failed.ndjson + failed-video-ids.txt | Reveja erros antes de tentar de novo esses IDs. Bem-sucedidos e itens desaparecidos estão excluídos do fracasso.ID Lista. |
| missing.ndjson | Recupere todas as partes do resultado do trabalho existente, então audite o arquivo recuperado em um novo diretório. Saída desaparecida não é uma consulta confirmada. |
| summary.json | coverageComplete Verifica que cada entrada tem um resultado. allSucceeded Também não requer vídeos fracassados. A auditoria sai do 2 para falhas ou falta de linhas. |
| Saia de 1 / sem summary.json | Dados malformados ou descomprometidos: inspecione os arquivos salvos. Não publique a auditoria parcial como um conjunto de dados completo. |

- [Recupere os resultados existentes](https://flashdata.dev/pt/docs/guides/bulk/reference.md#controls)
- [Retenção de resultados](https://flashdata.dev/pt/docs/guides/save-results/reference.md#bulk)

<a id="item-failures"></a>

## Se alguns vídeos falharem

Um trabalho Bulk completo pode conter vídeos fracassados. O CLI salva as linhas também, e sai com bulk_item_failures. Inspecione seus erros antes de decidir se tentará novamente o IDs individual, não reenvie o arquivo todo automaticamente.

### Mostrar apenas registros mal sucedidos · jq

```bash
jq -c 'select(.status != "completed") | {index, video_id, status, error}' bulk-results.ndjson
```


<a id="progress"></a>

## Trilha progresso e capacidade

Leia o trabalho salvo enquanto o comando original corre. O CLI envolve status sob dados, HTTP direto envolve em trabalho. Verifique com atraso e retrocesso, e honre Retry-After em 429. Um tempo limite local ou terminal fechado não cancela o trabalho remoto.

| Campo | Leia como |
| --- | --- |
| input.scannedBytes / input.bytes | O progresso da varredura de arquivos, não completaram as consultas ou a mídia enviada. |
| input.complete | Todas as entradas foram lidas; consultas e embalagem de resultados ainda podem estar funcionando. |
| counts.accepted / completed / failed | Submetido IDs, vídeos de sucesso e vídeos fracassados. Excelente = aceito - completado - falhou. |
| counts.invalid / results | Linhas de entrada/registros inválidos empacotados até agora. HTTP pode aceitar arquivos contendo linhas inválidas; o CLI valida a entrada antes do upload. |
| delivery | Entrega de dados ao cliente: uploadedParts, retryCount, storageType e customerStorage. Separado do upload de mídia de cada vídeo. |

### Bash

#### Bash

```bash
(
set -eu
BULK_ID=$(flashdata runs show bulk-first --json | jq -er '.data.remoteId')
flashdata bulk get "$BULK_ID" --json
)
```


### PowerShell 7

#### PowerShell 7

```powershell
$run = flashdata runs show bulk-first --json | ConvertFrom-Json
if ($LASTEXITCODE -ne 0 -or -not $run.data.remoteId) { throw 'Read the saved run before continuing.' }
flashdata bulk get $run.data.remoteId --json
```



<a id="states"></a>

### Saiba quando esperar ou agir

Bulk apresenta gradualmente dentro da capacidade da sua conta maxPendingJobs, compartilhada com outros trabalhos. Créditos insuficientes ou uma assinatura inativa podem pausar o trabalho. Verifique pauseReason antes de retomar.

| Estado | Próxima ação |
| --- | --- |
| awaiting_upload | Carregue o arquivo, e comece o trabalho existente. |
| running / finalizing | Espere. Finalizar pode incluir consultas inacabadas, embalagem e entrega de armazenamento. |
| paused | Resolva pauseReason e retome o mesmo trabalho. |
| completed | Baixe todas as partes do resultado e inspecione linhas falhadas. |
| failed / cancelled | Inspecione job.error e o recibo guardado. O trabalho aceito ainda pode ser finish; nenhum manifesto completo é publicado. |


<a id="controls"></a>

## Retomar um fluxo de trabalho interrompido

Depois de um intervalo local ou o download do resultado interrompido, recupere o volume primeiro. Isto lê o trabalho remoto existente, não envia o conjunto de dados novamente. Use um novo nome de saída. Um erro do partial_result pode deixar um arquivo local parcial, mantê-lo separado do resultado recuperado.

Use o mesmo perfil CLI e diretório de estado por toda parte. Para um perfil chamado, adicione --profile NAME a cada comando.

| Situação | Consertar |
| --- | --- |
| awaiting_upload | runs recover não repete um upload ou começa. Verifique o ID salvo, status de upload e arquivo original antes de continuar explicitamente. |
| paused | Resolva a causa relatada e use o currículo em massa com o ID salvo. A recuperação não retoma o trabalho pausado automaticamente. |
| 401 / 403 | Restaure o acesso válido à conta e fonte. Reutilize o mesmo trabalho depois que a autenticação for consertada. |
| 409 / 410 | 409 Os resultados não estão prontos. 410 Os resultados armazenados expiraram, use sua cópia salva. |
| URL | Confirmar que o antigo trabalho nunca começou antes de criar um novo. Uma submissão incerta é uma razão para ler seu ID salvo primeiro. |

### Recupere a corrida salva

```bash
flashdata runs show bulk-first --json
flashdata runs recover bulk-first --output recovered-results.ndjson --timeout 30m --json
```

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

<a id="pause"></a>

### Pause ou retome um trabalho

Substitua BULK_ID pelo ID do runs show em primeiro lugar. Pausa para novas submissões e embalagem de resultados; consultas aceitas continuam. Resolva pauseReason antes de retomar. Para opções alteradas ou credenciais de armazenamento, atualize o trabalho existente através do Bulk API.

#### Pausa

```bash
flashdata bulk pause BULK_ID --json
```

#### Retomar depois de consertar a causa

```bash
flashdata bulk resume BULK_ID --json
```

- [Atualize um trabalho Bulk](https://flashdata.dev/pt/docs/reference/bulk-processing/reference.md#updateBulkJob)

<a id="cancel"></a>

### Cancele permanentemente

Só cancele quando pretende abandonar o trabalho. O cancelamento não desfaz as consultas aceitas ou o reembolso do trabalho concluído. Contagens ainda podem mudar, e nenhum manifesto completo é publicado. Pausa é reversível.

#### Cancele o trabalho escolhido

```bash
flashdata bulk cancel BULK_ID --json
```


<a id="manifest"></a>

## Recupere cada parte do resultado

Para um trabalho já concluído, o CLI segue seu manifesto e salva cada parte do resultado em um arquivo NDJSON. Use um novo caminho de saída e execute a auditoria de importação no arquivo combinado. Os resultados do download descrevem mídia entregue, eles não são MP4 ou bytes de áudio.

### Pegue todas as partes de um trabalho existente

```bash
flashdata bulk results BULK_ID --output saved-results.ndjson --timeout 30m --json
```

- [Verifique a cobertura do conjunto de dados](https://flashdata.dev/pt/docs/guides/bulk/reference.md#audit)
- [Manifesto, peças e referências de retenção](https://flashdata.dev/pt/docs/reference/bulk-processing/reference.md#downloadBulkJobManifest)

<a id="storage"></a>

## Entregue-se ao seu depósito

Guarde suas credenciais como storage.json na pasta de trabalho antes de executar este comando. Use os campos de provedor ligados abaixo, mantenha o arquivo em particular. O CLI's --storage-config Lê isso. JSON Arquivo e seleção result_storage para dados ou armazenamento para mídia. --options Também toma um caminho de arquivo, não em linha JSON.

- [Campos de credencial do provedor](https://flashdata.dev/pt/docs/sources/youtube_download/reference.md#storage)
- [Entrega de armazenamento e caminhos de objetos](https://flashdata.dev/pt/docs/reference/bulk-processing/reference.md#storage)
- [Configure o pedido Bulk API](https://flashdata.dev/pt/docs/reference/bulk-processing/reference.md#playground)

<a id="storage-run"></a>

### Executar com a configuração de armazenamento salvo

#### Adicione armazenamento ao fluxo de metadados

```bash
flashdata bulk run --source youtube_metadata --input video-ids.txt --storage-config storage.json --run-id bulk-with-storage --output stored-results.ndjson --timeout 30m --json
```

