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

Guias

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.

Nesta página

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

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
flashdata auth status --json
flashdata account balance --json
flashdata account pricing --source youtube_metadata --request-count 2
flashdata account limits

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
# Run in a new working directory.
(
  set -euC
  printf '%s\n' 'jNQXAC9IVRw' 'dQw4w9WgXcQ' > video-ids.txt
)
cat video-ids.txt

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
flashdata bulk run --source youtube_metadata \
  --input video-ids.txt --run-id bulk-first \
  --output bulk-results.ndjson --timeout 30m --json

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
{"index":0,"video_id":"jNQXAC9IVRw","source":"youtube_metadata","status":"completed","results":[{"videoId":"jNQXAC9IVRw","title":"Example video title"}]}
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

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.

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

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
python3 audit-bulk.py --input video-ids.txt --results bulk-results.ndjson --out audit

Importar linhas completas e manter a auditoria

Arquivo / sinalUse-o assim
completed.ndjsonJunte-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.txtReveja erros antes de tentar de novo esses IDs. Bem-sucedidos e itens desaparecidos estão excluídos do fracasso.ID Lista.
missing.ndjsonRecupere 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.jsoncoverageComplete 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.jsonDados malformados ou descomprometidos: inspecione os arquivos salvos. Não publique a auditoria parcial como um conjunto de dados completo.

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
jq -c 'select(.status != "completed") | {index, video_id, status, error}' bulk-results.ndjson

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.

CampoLeia como
input.scannedBytes / input.bytesO progresso da varredura de arquivos, não completaram as consultas ou a mídia enviada.
input.completeTodas as entradas foram lidas; consultas e embalagem de resultados ainda podem estar funcionando.
counts.accepted / completed / failedSubmetido IDs, vídeos de sucesso e vídeos fracassados. Excelente = aceito - completado - falhou.
counts.invalid / resultsLinhas de entrada/registros inválidos empacotados até agora. HTTP pode aceitar arquivos contendo linhas inválidas; o CLI valida a entrada antes do upload.
deliveryEntrega de dados ao cliente: uploadedParts, retryCount, storageType e customerStorage. Separado do upload de mídia de cada vídeo.
Bash
(
set -eu
BULK_ID=$(flashdata runs show bulk-first --json | jq -er '.data.remoteId')
flashdata bulk get "$BULK_ID" --json
)

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.

EstadoPróxima ação
awaiting_uploadCarregue o arquivo, e comece o trabalho existente.
running / finalizingEspere. Finalizar pode incluir consultas inacabadas, embalagem e entrega de armazenamento.
pausedResolva pauseReason e retome o mesmo trabalho.
completedBaixe todas as partes do resultado e inspecione linhas falhadas.
failed / cancelledInspecione job.error e o recibo guardado. O trabalho aceito ainda pode ser finish; nenhum manifesto completo é publicado.

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çãoConsertar
awaiting_uploadruns recover não repete um upload ou começa. Verifique o ID salvo, status de upload e arquivo original antes de continuar explicitamente.
pausedResolva 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 / 403Restaure o acesso válido à conta e fonte. Reutilize o mesmo trabalho depois que a autenticação for consertada.
409 / 410409 Os resultados não estão prontos. 410 Os resultados armazenados expiraram, use sua cópia salva.
URLConfirmar 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
flashdata runs show bulk-first --json
flashdata runs recover bulk-first --output recovered-results.ndjson --timeout 30m --json

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
flashdata bulk pause BULK_ID --json
Retomar depois de consertar a causa
flashdata bulk resume BULK_ID --json

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
flashdata bulk cancel BULK_ID --json

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
flashdata bulk results BULK_ID --output saved-results.ndjson --timeout 30m --json

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.

Executar com a configuração de armazenamento salvo

Adicione armazenamento ao fluxo de metadados
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