Sfoglia la documentazione
Guide
Elaborare un file di video IDs, recuperare ogni parte del risultato e controllare la copertura prima di importare il set di dati nella vostra applicazione.
In questa pagina
Da un file ID a un set di dati controllato
Utilizzare questo flusso di lavoro per un catalogo video, una raccolta di ricerca o una coda di ingestione. Un file utilizza una fonte e le stesse opzioni per ogni ID. Iniziare con il campione di metadati a due video, quindi sostituire il proprio file.
video-ids.txt → Lavoro Bulk → bulk-results.ndjson
→ audit/completed.ndjson risultati per la vostra applicazione
→ audit/failed-video-ids.txt ha confermato i guasti alla recensione
→ Ingressi audit/missing.ndjson i cui risultati sono mancanti
→ Copertura audit/summary.json e conteggi dei risultatiPrima di iniziare
Installare lo CLI e utilizzare un profilo esistente o FLASHDATA_API_KEY con il permesso youtube_metadata. Confermare data.accessVerified: true e rivedere l'equilibrio disponibile, i prezzi per due richieste e i limiti attuali. Per il proprio file, utilizzare il suo conteggio ID quando si controllano i prezzi. Ogni ID processato è una query separata, non una carica piatta per il file.
Utilizzare Bash con jq o PowerShell 7 per i passaggi 1–3. L'audit di importazione opzionale nella fase 4 utilizza Python 3.10+ e la sua libreria standard. Lo CLI stesso non richiede né Node.js né Python.
flashdata auth status --json
flashdata account balance --json
flashdata account pricing --source youtube_metadata --request-count 2
flashdata account limits1. Preparare la IDs
Eseguire in una nuova cartella di lavoro. Utilizzare il testo UTF-8 con un video 11-character ID per linea, non un YouTube URL. La dimensione massima del file è 2 GiB. Rimuovere le linee vuote e i duplicati: lo CLI rifiuta l'ingresso malformato e i ripetuti IDs vengono elaborati separatamente.
# Run in a new working directory.
(
set -euC
printf '%s\n' 'jNQXAC9IVRw' 'dQw4w9WgXcQ' > video-ids.txt
)
cat video-ids.txtif (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.txt2. Eseguire il file
Lo CLI crea un lavoro, carica il file, inizia l'elaborazione e salva ogni parte del risultato in un file NDJSON. Utilizzare un nuovo percorso di uscita. Il locale run ID in primo luogo mantiene la ricevuta di lavoro remota per il recupero.
flashdata bulk run --source youtube_metadata \
--input video-ids.txt --run-id bulk-first \
--output bulk-results.ndjson --timeout 30m --jsonflashdata bulk run --source youtube_metadata `
--input video-ids.txt --run-id bulk-first `
--output bulk-results.ndjson --timeout 30m --json3. Ispezione dei risultati
Aprire bulk-results.ndjson. Ogni linea è un record JSON con indice, video_id e stato. Le righe di successo contengono un array di risultati; le righe fallite contengono un errore. Unisci i record all'ingresso per indice zero-based, non l'ordine di file. Il comando Bash utilizza jq.
{"index":0,"video_id":"jNQXAC9IVRw","source":"youtube_metadata","status":"completed","results":[{"videoId":"jNQXAC9IVRw","title":"Example video title"}]}# Bash + jq: read each record without loading the whole file.
jq -c '{index, video_id, status, title: .results[0].title, error}' bulk-results.ndjsonGet-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 }
}4. Controllare la copertura prima di importare
Salva audit-bulk.py qui sotto. Eseguire contro il file di input invariato e tutte le parti di risultato recuperate. Controlla ogni indice, video ID e sorgente, rifiuta le righe dei risultati duplicati e separa i guasti confermati dai risultati mancanti. Per un'altra fonte, aggiungere --source SOURCE_ID.
inputRows: 2, completato: 2, fallito: 0, mancante: 0 e allSucceeded: true per il campione di successo. Solo le righe completate appartengono all'importazione dei risultati dell'applicazione. Tenere il riepilogo dell'audit e i risultati senza successo accanto a loro.
Salvare audit-bulk.py
Creare audit-bulk.py accanto a video-ids.txt e bulk-results.ndjson nella cartella di lavoro. Copia il codice completo qui sotto e salvalo.
Lo script legge i file linea per riga e utilizza un indice SQLite locale invece di caricare l'intero set di dati in memoria. Richiede un file di input convalidato del video IDs. Ogni audit utilizza una nuova directory di output; i file parziali rimangono separati fino a quando la parsing non finisce.
# 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)Eseguire l'audit di importazione
Eseguire dalla cartella contenente lo script, l'ingresso originale e i risultati scaricati. L'audit legge solo i file locali.
python3 audit-bulk.py --input video-ids.txt --results bulk-results.ndjson --out auditpython audit-bulk.py --input video-ids.txt --results bulk-results.ndjson --out auditImportare righe completate e mantenere l'audit
| File / segnale | Usalo in questo modo |
|---|---|
| completed.ndjson | Iscriviti per indice al file originale. Utilizzare video_id per una chiave di catalogo; conservare l'identità job/snapshot quando si memorizza la cronologia di aggiornamento. |
| failed.ndjson + failed-video-ids.txt | Rivedere gli errori prima di riprovare deliberatamente questi IDs. Gli elementi di successo e mancanti sono esclusi dall'elenco fallito-ID. |
| missing.ndjson | Recuperare tutte le parti del risultato dal lavoro esistente, quindi controllare il file recuperato in una nuova directory. L'uscita mancante non è una domanda fallita confermata. |
| summary.json | coverageComplete verifica che ogni input ha un risultato. allSucceeded non richiede anche video falliti. L'audit esce da 2 per guasti o righe mancanti. |
| Uscita 1 / no summary.json | Dati malformati o errati: ispezionare i file salvati. Non pubblicare l'audit parziale come set di dati completo. |
Se alcuni video falliscono
Un lavoro Bulk completato può contenere video falliti. Lo CLI salva anche quelle righe, poi esce con bulk_item_failures. Ispezionare i loro errori prima di decidere se ripristinare il singolo IDs; non risottomettere l'intero file automaticamente.
jq -c 'select(.status != "completed") | {index, video_id, status, error}' bulk-results.ndjsonTraccia il progresso e la capacità
Leggi il lavoro salvato mentre il comando originale viene eseguito. Lo stato CLI avvolge i dati; HTTP lo avvolge direttamente sotto lavoro. Controllare con un ritardo e un backoff, e onorare Retry-After su 429. Un timeout locale o un terminale chiuso non cancella il lavoro remoto.
| Campo di applicazione | Leggilo come |
|---|---|
| input.scannedBytes / input.bytes | avanzamento della scansione dei file, non domande completate o supporti caricati. |
| input.complete | Tutti gli input sono stati letti; le query e l'imballaggio dei risultati possono ancora essere in esecuzione. |
| counts.accepted / completed / failed | Presentato IDs, video di successo e video falliti. Eccezionale = accettato − completato − fallito. |
| counts.invalid / results | Linee di ingresso non valide / record imballati finora. HTTP può accettare file contenenti linee non valide; CLI convalida l'ingresso prima del caricamento. |
| delivery | Consegna dei dati del cliente: uploadedParts, retryCount, storageType e customerStorage. Separato dal caricamento dei media di ogni video. |
(
set -eu
BULK_ID=$(flashdata runs show bulk-first --json | jq -er '.data.remoteId')
flashdata bulk get "$BULK_ID" --json
)$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 --jsonSapere quando aspettare o agire
Bulk si presenta gradualmente all'interno della capacità maxPendingJobs del tuo account, condivisa con altri lavori. I crediti insufficienti o un abbonamento inattivo possono mettere in pausa il lavoro. Controllare pauseReason prima di riprendere.
| Stato | Prossima azione |
|---|---|
| awaiting_upload | Caricare il file, quindi avviare il lavoro esistente. |
| running / finalizing | Aspetta. Finalizzazione può includere domande incompiute, imballaggio e consegna di stoccaggio. |
| paused | Risolvere pauseReason e riprendere lo stesso lavoro. |
| completed | Scarica tutte le parti dei risultati e ispeziona le righe fallite. |
| failed / cancelled | Ispezionare job.error e la ricevuta salvata. Il lavoro accettato può ancora finish; non viene pubblicato nessun manifesto completato. |
Riprendi un flusso di lavoro interrotto
Dopo un timeout locale o interrotto il download dei risultati, recuperare bulk-first. Questo legge il lavoro remoto esistente; non invia nuovamente il dataset. Utilizzare un nuovo nome file di output. Un errore partial_result può lasciare un file locale parziale; tenerlo separato dal risultato recuperato.
Utilizzare lo stesso profilo CLI e directory di stato in tutto. Per un profilo di nome, aggiungere --profile NAME ad ogni comando.
| Situazione | Risolto |
|---|---|
| awaiting_upload | runs recover non riproduce un upload o un inizio. Controllare lo stato di upload e il file originale salvato ID, prima di continuare esplicitamente. |
| paused | Risolvere la causa segnalata, quindi utilizzare il curriculum di massa con il ID salvato. Il recupero non riprende automaticamente il lavoro in pausa. |
| 401 / 403 | Ripristina l'accesso valido all'account e alla fonte di presentazione. Riutilizzare lo stesso lavoro dopo la correzione dell'autenticazione. |
| 409 / 410 | 409: i risultati non sono pronti. 410: i risultati memorizzati sono scaduti; utilizzare la copia salvata. |
| Caricamento scaduto URL | Conferma che il vecchio lavoro non è mai iniziato prima di crearne uno nuovo. Una presentazione incerta è un motivo per leggere il suo salvato ID prima. |
flashdata runs show bulk-first --json
flashdata runs recover bulk-first --output recovered-results.ndjson --timeout 30m --jsonPausa o riprendere un lavoro
Sostituire BULK_ID con ID dal primo blocco runs show. Pause ferma nuove presentazioni e il packaging dei risultati; le domande accettate continuano. Risolvere pauseReason prima di riprendere. Per le opzioni modificate o le credenziali di archiviazione, aggiornare il lavoro esistente tramite Bulk API.
flashdata bulk pause BULK_ID --jsonflashdata bulk resume BULK_ID --jsonAnnullare definitivamente
Cancella solo quando hai intenzione di abbandonare il lavoro. La cancellazione non annulla le domande accettate o rimborsa il lavoro completato. I conti possono ancora cambiare, e nessun manifesto completato è pubblicato. La pausa e' reversibile.
flashdata bulk cancel BULK_ID --jsonRecuperare ogni parte del risultato
Per un lavoro completato esistente, lo CLI segue il suo manifesto e salva ogni parte del risultato in un file NDJSON. Utilizzare un nuovo percorso di output ed eseguire l'audit di importazione sul file combinato. I risultati del download descrivono i supporti consegnati; non sono MP4 o byte audio.
flashdata bulk results BULK_ID --output saved-results.ndjson --timeout 30m --jsonConsegna al tuo storage
Salvare le credenziali del provider come storage.json nella cartella di lavoro prima di eseguire questo comando. Utilizzare i campi del fornitore collegati di seguito; mantenere il file privato. Lo CLI --storage-config legge questo file JSON e seleziona result_storage per i dati o lo storage per i media. --options prende anche un percorso di file, non inline JSON.
Eseguire con la configurazione di archiviazione salvata
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