Ga naar de inhoud
NL
API-sleutel ophalen
Documentatie bekijken

Handleidingen

Bulk-bestandsverwerking

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.

Bestanden geproduceerd door deze workflow
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 telt

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

Gratis toegang en accountcontroles
flashdata auth status --json
flashdata account balance --json
flashdata account pricing --source youtube_metadata --request-count 2
flashdata account limits

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

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

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

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

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

Eén succesvolle rij · afgekort voorbeeld
{"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. 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
# 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.

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

Gereedgemaakte rijen importeren en de audit bijhouden

Bestand / signaalGebruik het zo
completed.ndjsonSluit 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.txtControleer fouten voordat opzettelijk opnieuw proberen deze IDs. Succesvolle en ontbrekende items zijn uitgesloten van de lijst met mislukte ID.
missing.ndjsonHerstellen alle resultaat delen van de bestaande taak, dan audit het herstelde bestand in een nieuwe directory. Ontbrekende uitvoer is geen bevestigde mislukte zoekopdracht.
summary.jsoncoverageComplete 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 verlatenOnjuiste 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.

Alleen mislukte records · jq tonen
jq -c 'select(.status != "completed") | {index, video_id, status, error}' bulk-results.ndjson

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

VeldLees het als
input.scannedBytes / input.bytesVoortgang van bestandsscans, niet afgeronde vragen of geüploade media.
input.completeAlle invoer is gelezen; zoekopdrachten en resultaat verpakking kan nog steeds draaien.
counts.accepted / completed / failedIngediend IDs, succesvolle video's en mislukte video's. Uitstekend = geaccepteerd − voltooid − mislukt.
counts.invalid / resultsOngeldige invoerlijnen / records verpakt tot nu toe. HTTP kan bestanden met ongeldige regels accepteren; de CLI valideert invoer voordat u uploadt.
deliveryLevering van klantgegevens: uploadedParts, retryCount, storageType en customerStorage. Los van de media-upload van elke video.
Bash
(
set -eu
BULK_ID=$(flashdata runs show bulk-first --json | jq -er '.data.remoteId')
flashdata bulk get "$BULK_ID" --json
)

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

StaatVolgende actie
awaiting_uploadUpload het bestand en start dan de bestaande taak.
running / finalizingWacht. Afronden kan omvatten onafgemaakte vragen, verpakking en opslag levering.
pausedOplossen pauseReason en hervatten van dezelfde taak.
completedDownload alle resultaatonderdelen en controleer mislukte rijen.
failed / cancelledInspecteer 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.

SituatieRepareren
awaiting_uploadruns recover herhaalt geen upload of start. Controleer de opgeslagen ID, upload de status en het originele bestand voordat u expliciet verder gaat.
pausedOplossen van de gemelde oorzaak, gebruik dan bulk CV met de opgeslagen ID. Herstel hervat niet automatisch gepauzeerd werk.
401 / 403Herstellen van geldige toegang tot het indienen van account en bron. Dezelfde taak hergebruiken nadat de authenticatie is vastgesteld.
409 / 410409: de resultaten zijn nog niet klaar. 410: de opgeslagen resultaten verlopen; gebruik uw opgeslagen kopie.
Verlopen upload URLBevestig 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.
Herstel de opgeslagen run
flashdata runs show bulk-first --json
flashdata runs recover bulk-first --output recovered-results.ndjson --timeout 30m --json

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

Pauze
flashdata bulk pause BULK_ID --json
Hervatten na de vaststelling van de oorzaak
flashdata bulk resume BULK_ID --json

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

De gekozen taak annuleren
flashdata bulk cancel BULK_ID --json

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

Alle onderdelen van een bestaande taak ophalen
flashdata bulk results BULK_ID --output saved-results.ndjson --timeout 30m --json

Levering 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

Opslag toevoegen aan de metadata workflow
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