Documentatie bekijken
Handleidingen
Verwerk een bestand van video IDs, haal elk resultaatdeel op en controleer dekking voordat u de dataset in uw toepassing invoert.
Op deze pagina
Van een ID-bestand naar een gecontroleerde dataset
Gebruik deze workflow voor een videocatalogus, onderzoekscollectie of intake wachtrij. Eén bestand gebruikt één bron en dezelfde opties voor elke ID. Begin met de twee-video metadata sample en vervang dan je eigen bestand.
video-ids.txt → Bulk job → bulk-results.ndjson
→ audit/completed.ndjson resultaten voor uw toepassing
→ audit/failed-video-ids.txt bevestigde fouten te beoordelen
→ audit/missing.ndjson ingangen waarvan de resultaten ontbreken
→ audit/summary.json dekking en resultaat teltVoordat u begint
Installeer de CLI en gebruik een bestaand profiel of FLASHDATA_API_KEY met youtube_metadata-permissie. Bevestig data.accessVerified: true en bekijk beschikbare balans, prijsstelling voor twee verzoeken en actuele limieten. Voor uw eigen bestand, gebruik de ID telling bij het controleren van de prijzen. Elke verwerkte ID is een aparte query, niet één platte lading voor het bestand.
Gebruik Bash met jq of PowerShell 7 voor stappen 1–3. De optionele import audit in stap 4 maakt gebruik van Python 3.10+ en zijn standaard bibliotheek. De CLI zelf vereist noch Node.js noch Python.
flashdata auth status --json
flashdata account balance --json
flashdata account pricing --source youtube_metadata --request-count 2
flashdata account limits1. Bereid de IDs voor
Uitvoeren in een nieuwe werkmap. Gebruik UTF-8 tekst met één 11-karakter video ID per regel, geen YouTube URL. Maximale bestandsgrootte is 2 GiB. Verwijder lege regels en duplicaten: de CLI wijst foute invoer af, en herhaalde IDs worden apart verwerkt.
# 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. Het bestand uitvoeren
De CLI creëert een taak, uploadt het bestand, start de verwerking en slaat elk resultaatdeel op in één NDJSON-bestand. Gebruik een nieuw uitvoerpad. De lokale run ID bulk-first houdt de remote taak ontvangst voor herstel.
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. Inspecteer de resultaten
Open bulk-results.ndjson. Elke lijn is een JSON record met index, video_id en status. Succesvolle rijen bevatten een resultaatarray; foutieve rijen bevatten een fout. Sluit records aan bij de invoer door nul gebaseerde index, niet bestandsvolgorde. Het Bash commando gebruikt 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. Controleer dekking voordat u importeert
Bewaar audit-bulk.py hieronder. Voer het uit tegen het ongewijzigde invoerbestand en alle opgehaalde resultaatdelen. Het controleert elke index, video ID en bron, verwerpt dubbele resultaatrijen, en scheidt bevestigde fouten van ontbrekende resultaten. Voor een andere bron, --source SOURCE_ID toevoegen.
Verwacht inputRows: 2, voltooid: 2, mislukt: 0, ontbrekend: 0 en allSucceeded: true voor het succesvolle monster. Alleen voltooide rijen behoren tot de resultaatimport van de aanvraag. Houd de samenvatting van de controle en de mislukte resultaten naast hen.
audit-bulk.py opslaan
Maak audit-bulk.py naast video-ids.txt en bulk-results.ndjson in de werkmap. Kopieer de volledige code hieronder in het en sla het op.
Het script leest bestanden regel voor regel en gebruikt een lokale SQLite index in plaats van het laden van de hele dataset in het geheugen. Het vereist een gevalideerd invoerbestand van video IDs. Elke audit maakt gebruik van een nieuwe uitvoermap; gedeeltelijke bestanden blijven gescheiden totdat de verwerking voltooid is.
# 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)Uitvoeren van de import audit
Uitvoeren vanuit de map met het script, originele invoer en gedownloade resultaten. De audit leest alleen lokale bestanden.
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 auditGereedgemaakte rijen importeren en de audit bijhouden
| Bestand / signaal | Gebruik het zo |
|---|---|
| completed.ndjson | Sluit je aan bij de index van het oorspronkelijke bestand. Gebruik video_id voor een catalogussleutel; bewaar de job/snapshot-identiteit bij het opslaan van de verversgeschiedenis. |
| failed.ndjson + failed-video-ids.txt | Controleer fouten voordat opzettelijk opnieuw proberen deze IDs. Succesvolle en ontbrekende items zijn uitgesloten van de lijst met mislukte ID. |
| missing.ndjson | Herstellen alle resultaat delen van de bestaande taak, dan audit het herstelde bestand in een nieuwe directory. Ontbrekende uitvoer is geen bevestigde mislukte zoekopdracht. |
| summary.json | coverageComplete controleert of elke invoer een resultaat heeft. allSucceeded vereist ook geen mislukte video's. De audit verlaat 2 voor storingen of ontbrekende rijen. |
| 1 / geen summary.json verlaten | Onjuiste of niet-correcte gegevens: controleer de opgeslagen bestanden. Publiceer de gedeeltelijke audit niet als een volledige dataset. |
Als sommige video's falen
Een voltooide Bulk-taak kan mislukte video's bevatten. De CLI slaat deze rijen ook op, en eindigt dan met bulk_item_failures. Controleer hun fouten voordat u beslist of u de individuele IDs opnieuw wilt proberen; niet het gehele bestand automatisch opnieuw insturen.
jq -c 'select(.status != "completed") | {index, video_id, status, error}' bulk-results.ndjsonVooruitgang en capaciteit volgen
Lees de bewaarde taak terwijl het oorspronkelijke commando draait. De CLI wraps status onder data; direct HTTP wraps het onder taak. Controleer met een vertraging en back-off, en eer Retry-After op 429. Een lokale timeout of gesloten terminal annuleert geen externe werkzaamheden.
| Veld | Lees het als |
|---|---|
| input.scannedBytes / input.bytes | Voortgang van bestandsscans, niet afgeronde vragen of geüploade media. |
| input.complete | Alle invoer is gelezen; zoekopdrachten en resultaat verpakking kan nog steeds draaien. |
| counts.accepted / completed / failed | Ingediend IDs, succesvolle video's en mislukte video's. Uitstekend = geaccepteerd − voltooid − mislukt. |
| counts.invalid / results | Ongeldige invoerlijnen / records verpakt tot nu toe. HTTP kan bestanden met ongeldige regels accepteren; de CLI valideert invoer voordat u uploadt. |
| delivery | Levering van klantgegevens: uploadedParts, retryCount, storageType en customerStorage. Los van de media-upload van elke 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 --jsonWeet wanneer te wachten of te handelen
Bulk stuurt geleidelijk binnen de maxPendingJobs-capaciteit van uw account, gedeeld met andere jobs. Onvoldoende credits of een inactief abonnement kan de job pauzeren. Controleer pauseReason voordat u verder gaat.
| Staat | Volgende actie |
|---|---|
| awaiting_upload | Upload het bestand en start dan de bestaande taak. |
| running / finalizing | Wacht. Afronden kan omvatten onafgemaakte vragen, verpakking en opslag levering. |
| paused | Oplossen pauseReason en hervatten van dezelfde taak. |
| completed | Download alle resultaatonderdelen en controleer mislukte rijen. |
| failed / cancelled | Inspecteer job.error en het opgeslagen ontvangstbewijs. Geaccepteerd werk kan nog steeds finish; er wordt geen voltooid manifest gepubliceerd. |
Een onderbroken workflow hervatten
Na een lokale timeout of onderbroken resultaat downloaden, herstellen bulk-eerste. Dit leest de bestaande remote taak; het stuurt de dataset niet opnieuw in. Gebruik een nieuwe uitvoerbestandsnaam. Een partial_result fout kan een gedeeltelijk lokaal bestand verlaten; houd het gescheiden van het herstelde resultaat.
Gebruik in de loop van de tijd hetzelfde CLI-profiel en -directory. Voor een genoemd profiel, voeg --profile NAAM toe aan elk commando.
| Situatie | Repareren |
|---|---|
| awaiting_upload | runs recover herhaalt geen upload of start. Controleer de opgeslagen ID, upload de status en het originele bestand voordat u expliciet verder gaat. |
| paused | Oplossen van de gemelde oorzaak, gebruik dan bulk CV met de opgeslagen ID. Herstel hervat niet automatisch gepauzeerd werk. |
| 401 / 403 | Herstellen van geldige toegang tot het indienen van account en bron. Dezelfde taak hergebruiken nadat de authenticatie is vastgesteld. |
| 409 / 410 | 409: de resultaten zijn nog niet klaar. 410: de opgeslagen resultaten verlopen; gebruik uw opgeslagen kopie. |
| Verlopen upload URL | Bevestig dat de oude baan nooit is begonnen voordat er een nieuwe werd gemaakt. Een onzekere inzending is een reden om eerst de opgeslagen ID te lezen. |
flashdata runs show bulk-first --json
flashdata runs recover bulk-first --output recovered-results.ndjson --timeout 30m --jsonPauzeren of hervatten van een baan
Vervang BULK_ID door ID van runs show bulk-first. Pauzeer stopt nieuwe inzendingen en resultaatverpakking; geaccepteerde vragen blijven. pauseReason oplossen alvorens opnieuw te beginnen. Voor gewijzigde opties of opslaggegevens, update de bestaande taak via de Bulk API.
flashdata bulk pause BULK_ID --jsonflashdata bulk resume BULK_ID --jsonPermanent annuleren
Alleen annuleren als je van plan bent om de baan op te geven. Annuleringen niet ongedaan geaccepteerde vragen of terugbetaling voltooid werk. Grachten kunnen nog steeds veranderen, en er wordt geen voltooid manifest gepubliceerd. De pauze is omkeerbaar.
flashdata bulk cancel BULK_ID --jsonOphalen van elk resultaat deel
Voor een bestaande voltooide taak volgt de CLI zijn manifest en slaat elk resultaatdeel op in één NDJSON-bestand. Gebruik een nieuw uitvoerpad en voer de import audit uit op het gecombineerde bestand. Download resultaten beschrijven geleverde media; het zijn geen MP4 of audio bytes.
flashdata bulk results BULK_ID --output saved-results.ndjson --timeout 30m --jsonLevering aan uw opslag
Bewaar uw providergegevens als storage.json in de werkmap voordat u dit commando uitvoert. Gebruik de hieronder gekoppelde providervelden; houd het bestand privé. CLI's --storage-config leest dit JSON-bestand en selecteert result_storage voor gegevens of opslag voor media. --options neemt ook een bestandspad, niet inline JSON.
Uitvoeren met de opgeslagen opslagconfiguratie
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