Przejdź do treści
PL
Uzyskaj klucz API
Przeglądaj dokumentację

Poradniki

Przetwarzanie plików Bulk

Przetworzyć plik wideo IDs, pobrać każdą część wyniku i sprawdzić pokrycie przed importem zbioru danych do aplikacji.

Na tej stronie

Z pliku ID do zaznaczonego zbioru danych

Użyj tego przepływu pracy do katalogu wideo, zbierania badań lub kolejki spożycia. Jeden plik używa jednego źródła i tych samych opcji dla każdego ID. Zacznij od próbki metadanych dwuwideo, a następnie podmień swój własny plik.

Pliki wytwarzane przez ten przepływ pracy
video-ids.txt → Bulk praca → bulk-results.ndjson
  → Wyniki audit/completed.ndjson dla Twojej aplikacji
  → audit/failed-video-ids.txt potwierdzone niepowodzenie przeglądu
  → Wejścia audit/missing.ndjson, których wyniki są brakujące
  → Zakres audit/summary.json i liczba wyników

Zanim zaczniesz

Zainstaluj CLI i użyj istniejącego profilu lub FLASHDATA_API_KEY za pozwoleniem youtube_metadata. Potwierdź data.accessVerified: true i sprawdź dostępne saldo, ceny za dwa wnioski i aktualne limity. Dla własnego pliku, użyj jego ID liczyć podczas sprawdzania cen. Każdy przetworzony ID jest odrębnym zapytaniem, nie jest to jedna płaska opłata za plik.

Należy stosować Bash z jq lub PowerShell 7 w krokach 1–3. Opcjonalny audyt przywozowy na etapie 4 wykorzystuje Python 3.10 + i jego standardową bibliotekę. Sam CLI nie wymaga Node.js ani Python.

Bezpłatny dostęp i kontrole rachunków
flashdata auth status --json
flashdata account balance --json
flashdata account pricing --source youtube_metadata --request-count 2
flashdata account limits

1. Przygotować IDs

Uruchom nowy folder roboczy. Użyj tekstu UTF-8 z jednym wideo 11- znaków ID na linię, a nie YouTube URL. Maksymalny rozmiar pliku to 2 GiB. Usuń puste linie i duplikaty: CLI odrzuca błędne wejście i powtarzane IDs są przetwarzane oddzielnie.

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

2. Uruchom plik

CLI tworzy zadanie, wysyła plik, rozpoczyna przetwarzanie i zapisuje każdą część wyniku do jednego pliku NDJSON. Użyj nowej ścieżki wyjścia. Lokalny bieg ID bulk- pierwszy zachowuje zdalny pokwitowanie zadania do odzyskania.

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

3. Sprawdzić wyniki

Otwórz bulk-results.ndjson. Każda linia jest rekordem JSON z indeksem, video_id i statusem. Udane wiersze zawierają tablicę wyników; błędne wiersze zawierają błąd. Dołącz rekordy do wejścia przez indeks zerowy, a nie kolejność plików. Polecenie Bash używa jq.

Jeden udany wiersz · skrócony przykład
{"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. Sprawdź zakres przed przywozem

Zapisz audit-bulk.py poniżej. Uruchom go na niezmienionym pliku wejściowym i wszystkich odzyskanych częściach wyników. Sprawdza każdy indeks, wideo ID i źródło, odrzuca duplikaty wierszy wyników i oddziela potwierdzone błędy od brakujących wyników. Dla innego źródła dodaj --source SOURCE_ID.

Oczekiwanie inputRows: 2, zakończone: 2, nie powiodło się: 0, brakuje: 0 i allSucceeded: true dla udanej próbki. Tylko wypełnione wiersze należą do importu wyniku aplikacji. Utrzymywanie podsumowania audytu i nieskuteczne wyniki obok nich.

Zapisz audit-bulk.py

Utwórz audit-bulk.py obok video-ids.txt i bulk-results.ndjson w katalogu roboczym. Skopiuj do niego cały kod poniżej i zapisz go.

Skrypt odczytuje pliki po linii i używa lokalnego indeksu SQLite zamiast wczytywania całego zbioru danych do pamięci. Wymaga on walidacji pliku wejściowego wideo IDs. Każdy audyt używa nowego katalogu wyjściowego; pliki częściowe pozostają oddzielone do czasu zakończenia parsowania.

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)

Uruchom audyt przywozu

Uruchom z folderu zawierającego skrypt, oryginalne wejście i pobrane wyniki. Audyt czyta tylko lokalne pliki.

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

Import zakończonych wierszy i prowadzenie audytu

Plik / sygnałUżyj tego w ten sposób
completed.ndjsonDołącz przez indeks do oryginalnego pliku. Użyj video_id jako klucza katalogowego; zachowuj tożsamość job/snapshot podczas przechowywania historii odświeżania.
failed.ndjson + failed-video-ids.txtPrzed umyślnym ponownym uruchomieniem tych IDs należy ponownie sprawdzić błędy. Pozytywne i brakujące elementy są wyłączone z listy niepowodzeń- ID.
missing.ndjsonOdzyskiwanie wszystkich wyników z istniejącego zadania, a następnie kontrola odzyskanego pliku w nowym katalogu. Brak wyjścia nie jest potwierdzonym nieudanym zapytaniem.
summary.jsoncoverageComplete sprawdza, czy każde wejście ma wynik. allSucceeded również nie wymaga nieudanych filmów. Audyt opuszcza 2 w przypadku awarii lub brakujących wierszy.
Exit 1 / no summary.jsonNieprawidłowe lub źle dopasowane dane: sprawdź zapisane pliki. Nie należy publikować audytu częściowego jako kompletnego zbioru danych.

Jeśli niektóre filmy zawiodą

Zakończone zadanie Bulk może zawierać nieudane filmy. CLI również zapisuje te wiersze, a następnie wychodzi z bulk_item_failures. Sprawdź ich błędy przed podjęciem decyzji, czy należy ponownie spróbować IDs; nie usuwaj automatycznie całego pliku.

Pokaż tylko nieudane rekordy · jq
jq -c 'select(.status != "completed") | {index, video_id, status, error}' bulk-results.ndjson

Postępy i przepustowość toru

Przeczytaj zapisane zadanie podczas wykonywania oryginalnego polecenia. Status CLI obejmuje dane; bezpośredni HTTP obejmuje go w trakcie pracy. Sprawdź z opóźnieniem i wycofaniem, i honorować Retry-After na 429. Lokalny timeout lub zamknięty terminal nie anuluje zdalnej pracy.

PolePrzeczytaj jako
input.scannedBytes / input.bytesPostęp skanowania plików, niezakończone zapytania lub przesłane media.
input.completeWszystkie dane wejściowe zostały przeczytane; pytania i opakowania mogą być nadal uruchomione.
counts.accepted / completed / failedPrzedstawione IDs, udane filmy i nieudane filmy. Wybitny = zaakceptowany − zakończony − nieudany.
counts.invalid / resultsNieprawidłowe linie wejściowe / rekordy zapakowane do tej pory. HTTP może akceptować pliki zawierające nieprawidłowe linie; przed wysłaniem uwierzytelnia wejście CLI.
deliveryDostawa danych klienta: uploadedParts, retryCount, storageType i customerStorage. Oddziel się od transmisji każdego wideo.
Bash
(
set -eu
BULK_ID=$(flashdata runs show bulk-first --json | jq -er '.data.remoteId')
flashdata bulk get "$BULK_ID" --json
)

Wiedz, kiedy czekać lub działać

Bulk przekazuje stopniowo w ramach pojemności Twojego konta maxPendingJobs, dzielonej z innymi zadaniami. Niewystarczające kredyty lub nieaktywna subskrypcja może wstrzymać pracę. Przed wznowieniem należy sprawdzić pauseReason.

PaństwoNastępna akcja
awaiting_uploadWyślij plik, a następnie uruchom istniejące zadanie.
running / finalizingCzekaj. Finalizacja może obejmować niedokończone zapytania, pakowania i przechowywania dostawy.
pausedRozwiąż pauseReason i wznowij tę samą pracę.
completedPobieranie wszystkich wyników i kontrolowanie nieudanych wierszy.
failed / cancelledSprawdź job.error i zapisany paragon. Przyjmowana praca może nadal być zgodna z finish; nie publikuje się wypełnionego manifestu.

Wznowienie przerwanego przepływu pracy

Po lokalnym timeout lub przerywany pobór wyników, odzyskać bulk- pierwszy. Odczytuje to istniejące zdalne zadanie; nie przekazuje ponownie zbioru danych. Użyj nowej nazwy pliku wyjściowego. Błąd partial_result może pozostawić częściowy plik lokalny; należy go oddzielić od odzyskanego wyniku.

Użyj tego samego profilu CLI i katalogu stanu w całym. Dla nazwanego profilu dodaj nazwę --profile do każdego polecenia.

SytuacjaNapraw
awaiting_uploadruns recover nie odtwarza wysyłania ani uruchamiania. Sprawdź zapisany ID, wgraj status i oryginalny plik przed wyraźną kontynuacją.
pausedRozwiąż zgłoszoną przyczynę, a następnie użyj masowego CV z zapisanym ID. Odzyskiwanie nie wznawia automatycznie wstrzymanej pracy.
401 / 403Przywróć poprawny dostęp do konta i źródła. Ponowne użycie tego samego zadania po ustaleniu uwierzytelniania.
409 / 410409: wyniki nie są gotowe. 410: zapisane wyniki wygasły; użyj zapisanej kopii.
Przeterminowane wysyłanie URLPotwierdź, że stara praca nigdy nie zaczęła się przed stworzeniem nowej. Niepewne złożenie jest powodem, aby najpierw przeczytać zapisane ID.
Odzyskiwanie zapisanego biegu
flashdata runs show bulk-first --json
flashdata runs recover bulk-first --output recovered-results.ndjson --timeout 30m --json

Wstrzymać lub wznowić pracę

Zastąpić BULK_ID za pomocą ID od bulk- pierwszego bulk- runs show. Pauza zatrzymuje nowe zgłoszenia i opakowania wyników; akceptowane pytania nadal. Rozstrzygnij pauseReason przed wznowieniem. W przypadku zmienionych opcji lub uwierzytelniania pamięci, uaktualnij istniejące zadanie za pośrednictwem Bulk API.

Pauza
flashdata bulk pause BULK_ID --json
Wznowić po ustaleniu przyczyny
flashdata bulk resume BULK_ID --json

Anuluj na stałe

Odwołaj tylko wtedy, gdy zamierzasz zrezygnować z pracy. Anulowanie nie cofnie zaakceptowanych zapytań lub zwrotu zakończonych prac. Liczenia mogą się jeszcze zmienić, a nie zostanie opublikowany żaden wypełniony manifest. Pauza jest odwracalna.

Anuluj wybrane zadanie
flashdata bulk cancel BULK_ID --json

Pobieranie każdej części wyniku

Dla istniejącego zadania zakończonego, CLI podąża za manifestem i zapisuje każdą część wyniku w jednym pliku NDJSON. Użyj nowej ścieżki wyjścia i uruchom audyt importu w połączonym pliku. Pobieranie wyników opisuje dostarczone media; nie są one MP4 lub audio bajtów.

Pobierz wszystkie części z istniejącej pracy
flashdata bulk results BULK_ID --output saved-results.ndjson --timeout 30m --json

Dostarcz do magazynu

Przed uruchomieniem tego polecenia zapisz swoje referencje dostawcy jako storage.json w folderze roboczym. Użyj pól dostawcy powiązanych poniżej; zachowuj plik w tajemnicy. W CLIjest --storage-config przeczytaj to JSON plik i wybieranie result_storage dla danych lub przechowywania dla mediów. --options pobiera także ścieżkę pliku, a nie inline JSON.

Uruchom z zapisaną konfiguracją pamięci masowej

Dodawanie pamięci masowej do przepływu pracy metadanych
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