Saltar al contenido
ES
Obtener clave API
Explorar documentación

Guías

Procesa archivos con Bulk

Procesa un archivo de identificadores de vídeo, recupera todas las partes del resultado y comprueba que estén completas antes de importar los datos a tu aplicación.

En esta página

Desde un archivo ID a un conjunto de datos comprobado

Utilice este flujo de trabajo para un catálogo de vídeo, colección de investigación o cola de ingestión. Un archivo utiliza una fuente y las mismas opciones para cada ID. Comience con la muestra de metadatos de dos vídeos, y luego sustituya su propio archivo.

Archivos producidos por este flujo de trabajo
video-ids.txt → trabajo Bulk → bulk-results.ndjson
  → audit/completed.ndjson       resultados para tu aplicación
  → audit/failed-video-ids.txt   errores confirmados que debes revisar
  → audit/missing.ndjson        entradas cuyos resultados faltan
  → audit/summary.json          cobertura y recuento de resultados

Antes de empezar

Instala el CLI y utiliza un perfil existente o FLASHDATA_API_KEY con permiso youtube_metadata. Confirma data.accessVerified: saldo verdadero y de revisión disponible, precios para dos solicitudes y límites actuales. Para su propio archivo, utilice su cuenta ID al realizar la comprobación de precios. Cada ID procesado es una consulta independiente, no una carga plana para el archivo.

Uso Bash con jq o PowerShell 7 para la adopción de medidas 1–3. La auditoría de las importaciones opcionales en el paso 4 usos Python 3.10+ y su biblioteca estándar. CLI en sí mismo no se requiere Node.js ni tampoco Python.

Acceso gratuito y cheques de cuenta
flashdata auth status --json
flashdata account balance --json
flashdata account pricing --source youtube_metadata --request-count 2
flashdata account limits

1. Preparar el IDs

Ejecutar en una nueva carpeta de trabajo.8 texto con uno 11- vídeo de la imagen ID por línea, no una YouTube URL. El tamaño máximo del archivo es 2 GiB. Quitar líneas en blanco y duplicados: el CLI rechaza la entrada malformada, y repetida IDs se procesan por separado.

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

2. Ejecute el archivo

El CLI crea un trabajo, sube el archivo, comienza a procesar y guarda cada parte de resultado en un archivo NDJSON. Usa una nueva ruta de salida. El ID de ejecución local mantiene el recibo remoto de trabajo para la recuperación.

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

3. Inspeccionar los resultados

Open bulk-results.ndjson. Cada línea es un registro JSON con índice, video_id y estado. Las filas exitosas contienen una matriz de resultados; las filas fallidas contienen un error. Únete a los registros por índice basado en cero, no orden de archivos. El comando Bash utiliza jq.

Una fila exitosa · ejemplo 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 la cobertura antes de importar

Guardar audit-bulk.py a continuación. Ejecutar contra el archivo de entrada sin cambios y todas las partes de resultado recuperadas. Chequea cada índice, video ID y fuente, rechaza las filas de resultado duplicados, y separa fallos confirmados de los resultados perdidos. Para otra fuente, añadir --source SOURCE_ID.

Expect inputRows: 2, completed: 2, failed: 0, missing: 0 y allSucceeded: true for the successful sample. Sólo las filas completadas pertenecen a la importación de resultados de la aplicación. Mantenga el resumen de la auditoría y los resultados no exitosos junto a ellos.

Guardar audit-bulk.py

Cree audit-bulk.py junto a video-ids.txt y bulk-results.ndjson en la carpeta de trabajo. Copia el código completo a continuación y guárdalo.

El script lee la línea de archivos por línea y utiliza un índice SQLite local en lugar de cargar todo el conjunto de datos en la memoria. Requiere un archivo de entrada validado del vídeo IDs. Cada auditoría utiliza un nuevo directorio de salida; los archivos parciales permanecen separados hasta que se termina la parsing.

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)

Ejecutar la auditoría de importación

Ejecutar desde la carpeta que contiene el script, los resultados originales y descargados. La auditoría sólo lee los archivos locales.

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

Importar filas completadas y mantener la auditoría

Archivo / señalÚsalo de esta manera.
completed.ndjsonÚnete por índice al archivo original. Utilice video_id para una clave de catálogo; mantenga el trabajo/snapshot al almacenar la historia de refrescos.
failed.ndjson + failed-video-ids.txtRevise los errores antes de reiniciar deliberadamente estos IDs. Los artículos exitosos y desaparecidos están excluidos de la lista fallida-ID.
missing.ndjsonRecuperar todas las partes del resultado del trabajo existente, luego auditar el archivo recuperado en un nuevo directorio. La pérdida de salida no es una consulta confirmada fallida.
summary.jsoncoverageComplete comprueba que cada entrada tiene un resultado. allSucceeded también requiere no videos fallidos. La auditoría sale 2 para fallos o filas perdidas.
Exit 1 / no summary.jsonDatos malformados o desajustados: inspeccionar los archivos guardados. No publicar la auditoría parcial como conjunto de datos completo.

Si algunos vídeos fallan

Un trabajo Bulk completado puede contener videos fallidos. El CLI guarda esas filas también, luego sale con bulk_item_failures. Inspeccione sus errores antes de decidir si volver a iniciar IDs individual; no vuelva a presentar el archivo completo automáticamente.

Mostrar sólo registros no exitosos · jq
jq -c 'select(.status != "completed") | {index, video_id, status, error}' bulk-results.ndjson

Seguimiento de los progresos y la capacidad

Lea el trabajo guardado mientras el comando original funciona. El CLI envuelve el estado bajo los datos; HTTP directo lo envuelve en el trabajo. Compruebe con un retraso y la devolución, y honor Retry-After en 429. Un tiempo de salida local o terminal cerrado no cancela el trabajo remoto.

CampoLéelo como
input.scannedBytes / input.bytesProgreso del análisis de archivos, no consultas completadas o medios subidos.
input.completeToda la entrada ha sido leída; las consultas y el embalaje de resultados pueden seguir funcionando.
counts.accepted / completed / failedSubmitted IDs, successful videos and failed videos. Outstanding = accepted − completed − failed.
counts.invalid / resultsLas líneas de entrada / registros inválidos empaquetados hasta ahora. HTTP puede aceptar archivos que contienen líneas inválidas; el CLI valida la entrada antes de subir.
deliveryEntrega de datos del cliente: uploadedParts, retryCount, storageType y customerStorage. Separar desde la subida de medios 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
)

Saber cuándo esperar o actuar

Bulk envía solicitudes gradualmente dentro de la capacidad maxPendingJobs de tu cuenta, compartida con otros trabajos. La falta de créditos o una suscripción inactiva pueden pausar el trabajo. Consulta pauseReason antes de reanudarlo.

EstadoSiguiente acción
awaiting_uploadSube el archivo, y luego comience el trabajo existente.
running / finalizingEspera. La finalización puede incluir consultas inacabadas, embalaje y entrega de almacenamiento.
pausedResolver pauseReason y reanudar el mismo trabajo.
completedDescargue todas las partes del resultado e inspeccione filas fallidas.
failed / cancelledInspeccione job.error y el recibo guardado. El trabajo aceptado puede terminar; no se publica ningún manifiesto completado.

Reanudar un flujo de trabajo interrumpido

Después de un timeout local o la descarga de resultados interrumpido, recuperar el primer volumen. Esto lee el trabajo remoto existente; no envía el conjunto de datos de nuevo. Utilice un nuevo nombre de archivo de salida. Un error partial_result puede dejar un archivo local parcial; mantenerlo separado del resultado recuperado.

Utilice el mismo perfil CLI y directorio estatal en todas partes. Para un perfil llamado, agregue --profile NAME a cada comando.

SituaciónArreglos
awaiting_uploadse recupera no vuelve a reproducir una carga o comienza. Compruebe el ID guardado, estado de carga y archivo original antes de continuar explícitamente.
pausedResolver la causa reportada, luego utilizar el curriculum vitae con el ID salvado. La recuperación no reanudar el trabajo pausado automáticamente.
401 / 403Restaurar el acceso válido a la cuenta de envío y fuente. Reutilizar el mismo trabajo después de la autenticación se fija.
409 / 410409: los resultados no están listos. 410: los resultados almacenados expiraron; use su copia guardada.
Carga de carga expirida URLConfirme el viejo trabajo nunca comenzó antes de crear uno nuevo. Una comunicación incierta es una razón para leer su ID salvado primero.
Recuperar la carrera salvada
flashdata runs show bulk-first --json
flashdata runs recover bulk-first --output recovered-results.ndjson --timeout 30m --json

Pausa o reanudar un trabajo

Reemplazamiento BULK_ID con el ID de las carreras muestran a granel primero. La pausa detiene nuevas presentaciones y empaquetado de resultados; las consultas aceptadas continúan. pauseReason antes de reanudar. Para cambiar opciones o credenciales de almacenamiento, actualice el trabajo existente a través del Bulk API.

Pausa
flashdata bulk pause BULK_ID --json
Resumir después de reparar la causa
flashdata bulk resume BULK_ID --json

Cancelar permanentemente

Solo cancela cuando se pretende abandonar el trabajo. Cancelación no deshacer las consultas aceptadas o el reembolso del trabajo completado. Cuentas todavía pueden cambiar, y no se publica ningún manifiesto completado. La pausa es reversible.

Cancelar el trabajo elegido
flashdata bulk cancel BULK_ID --json

Recuperar cada parte de resultado

Para un trabajo completado existente, el CLI sigue su manifiesto y guarda cada parte de resultado en un archivo NDJSON. Utilice una nueva ruta de salida y ejecute la auditoría de importación en el archivo combinado. Descargue resultados describir los medios entregados; no son MP4 o bytes de audio.

Trae todas las partes de un trabajo existente
flashdata bulk results BULK_ID --output saved-results.ndjson --timeout 30m --json

Entrega a tu almacenamiento

Guardar las credenciales de su proveedor como storage.json en la carpeta de trabajo antes de ejecutar este comando. Utilice los campos del proveedor vinculados a continuación; mantenga el archivo privado. CLI's --storage-config lee esto JSON archivo y selecciones result_storage para datos o almacenamiento para los medios. --options también toma una ruta de archivo, no inline JSON.

Correr con la configuración de almacenamiento guardada

Añadir almacenamiento al flujo de trabajo de metadatos
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