Aller au contenu
FR
Obtenir une clé API
Parcourir la documentation

Guides

Traitement de fichiers Bulk

Traitez un fichier d’identifiants vidéo, récupérez toutes les parties des résultats et vérifiez leur exhaustivité avant d’importer le jeu de données dans votre application.

Sur cette page

Passer d’un fichier d’identifiants à un jeu de données vérifié

Utilisez ce workflow pour un catalogue vidéo, une collection de recherche ou une file d’ingestion. Chaque fichier utilise une seule source et les mêmes options pour tous les identifiants. Commencez par l’exemple de métadonnées de deux vidéos, puis utilisez votre propre fichier.

Fichiers produits par ce workflow
video-ids.txt → tâche Bulk → bulk-results.ndjson
  → audit/completed.ndjson       résultats pour votre application
  → audit/failed-video-ids.txt   échecs confirmés à examiner
  → audit/missing.ndjson        entrées dont le résultat manque
  → audit/summary.json          exhaustivité et décompte des résultats

Avant de commencer

Installez la CLI et utilisez un profil existant ou FLASHDATA_API_KEY avec la permission youtube_metadata. Confirmez data.accessVerified: true et vérifiez le solde disponible, le tarif pour deux requêtes et les limites actuelles. Pour votre propre fichier, utilisez son nombre d’identifiants pour vérifier le prix. Chaque identifiant traité constitue une requête distincte ; le fichier n’est pas facturé au forfait.

Utilisez Bash avec jq ou PowerShell 7 pour les étapes 1 à 3. L’audit d’importation facultatif de l’étape 4 utilise Python 3.10+ et sa bibliothèque standard. La CLI elle-même ne nécessite ni Node.js ni Python.

Vérifications gratuites de l’accès et du compte
flashdata auth status --json
flashdata account balance --json
flashdata account pricing --source youtube_metadata --request-count 2
flashdata account limits

1. Préparer les identifiants

Travaillez dans un nouveau dossier. Utilisez un fichier texte UTF-8 avec un identifiant vidéo de 11 caractères par ligne, et non une URL YouTube. La taille maximale est de 2 GiB. Supprimez les lignes vides et les doublons : la CLI rejette les entrées mal formées, et les identifiants répétés sont traités séparément.

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

2. Traiter le fichier

La CLI crée une tâche, transfère le fichier, démarre le traitement et regroupe toutes les parties des résultats dans un fichier NDJSON. Utilisez un nouveau chemin de sortie. L’identifiant d’exécution local bulk-first conserve le reçu de la tâche distante pour permettre sa reprise.

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

3. Examiner les résultats

Ouvrez bulk-results.ndjson. Chaque ligne est un enregistrement JSON avec index, video_id et status. Les lignes réussies contiennent un tableau results ; les lignes en échec contiennent une erreur. Rapprochez les résultats de l’entrée à l’aide de index, qui commence à zéro, et non selon leur ordre dans le fichier. La commande Bash utilise jq.

Une ligne réussie · exemple abrégé
{"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. Vérifier l’exhaustivité avant l’importation

Enregistrez audit-bulk.py ci-dessous. Exécutez-le avec le fichier d’entrée inchangé et toutes les parties de résultats récupérées. Il vérifie chaque index, identifiant vidéo et source, rejette les lignes de résultat en double et distingue les échecs confirmés des résultats manquants. Pour une autre source, ajoutez --source SOURCE_ID.

L’exemple réussi doit indiquer inputRows: 2, completed: 2, failed: 0, missing: 0 et allSucceeded: true. Importez uniquement les lignes terminées dans les résultats de l’application. Conservez aussi le résumé d’audit et les éléments en échec ou sans résultat.

Enregistrer audit-bulk.py

Créez audit-bulk.py à côté de video-ids.txt et bulk-results.ndjson dans le dossier de travail. Copiez-y le code complet ci-dessous et enregistrez-le.

Le script lit les fichiers ligne par ligne et utilise un index SQLite local plutôt que de charger tout le jeu de données en mémoire. Il nécessite un fichier d’identifiants vidéo préalablement validé. Chaque audit utilise un nouveau répertoire de sortie ; les fichiers partiels restent séparés jusqu’à la fin de l’analyse.

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)

Lancer l’audit d’importation

Exécutez la commande depuis le dossier contenant le script, le fichier d’entrée d’origine et les résultats téléchargés. L’audit lit uniquement des fichiers locaux.

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

Importer les lignes terminées et conserver l’audit

Fichier / indicateurUtilisation
completed.ndjsonRapprochez les lignes du fichier d’origine selon index. Utilisez video_id comme clé de catalogue ; conservez l’identité de la tâche ou de l’instantané pour historiser les mises à jour.
failed.ndjson + failed-video-ids.txtExaminez les erreurs avant de relancer volontairement ces identifiants. Les éléments réussis et manquants sont exclus de la liste des identifiants en échec.
missing.ndjsonRécupérez toutes les parties de résultats de la tâche existante, puis auditez le fichier récupéré dans un nouveau répertoire. Un résultat manquant n’est pas un échec de requête confirmé.
summary.jsoncoverageComplete vérifie que chaque entrée possède un résultat. allSucceeded exige en plus qu’aucune vidéo n’ait échoué. L’audit renvoie le code de sortie 2 en présence d’échecs ou de lignes manquantes.
Code de sortie 1 / aucun summary.jsonDonnées mal formées ou incohérentes : examinez les fichiers enregistrés. Ne publiez pas l’audit partiel comme un jeu de données complet.

Si certaines vidéos échouent

Une tâche Bulk terminée peut contenir des vidéos en échec. La CLI enregistre aussi ces lignes, puis se termine avec bulk_item_failures. Examinez les erreurs avant de décider de relancer certains identifiants ; ne soumettez pas automatiquement tout le fichier à nouveau.

Afficher uniquement les enregistrements non réussis · jq
jq -c 'select(.status != "completed") | {index, video_id, status, error}' bulk-results.ndjson

Suivre la progression et la capacité

Consultez la tâche enregistrée pendant l’exécution de la commande d’origine. La CLI place l’état sous data ; la réponse HTTP directe le place sous job. Espacez les vérifications avec un délai croissant et respectez Retry-After en cas de 429. Un délai d’attente local dépassé ou un terminal fermé n’annule pas les opérations distantes.

ChampSignification
input.scannedBytes / input.bytesProgression de la lecture du fichier, et non des requêtes terminées ou des médias transférés.
input.completeToute l’entrée a été lue ; les requêtes et la préparation des fichiers de résultats peuvent encore être en cours.
counts.accepted / completed / failedIdentifiants soumis, vidéos réussies et vidéos en échec. En cours = accepted − completed − failed.
counts.invalid / resultsLignes d’entrée invalides / enregistrements déjà inclus dans les fichiers de résultats. HTTP peut accepter des fichiers contenant des lignes invalides ; la CLI valide l’entrée avant son transfert.
deliveryLivraison des données au client : uploadedParts, retryCount, storageType et customerStorage. Elle est distincte du transfert du média de chaque vidéo.
Bash
(
set -eu
BULK_ID=$(flashdata runs show bulk-first --json | jq -er '.data.remoteId')
flashdata bulk get "$BULK_ID" --json
)

Savoir quand attendre ou intervenir

Bulk soumet progressivement les requêtes dans la limite maxPendingJobs du compte, partagée avec les autres tâches. Des crédits insuffisants ou un abonnement inactif peuvent mettre la tâche en pause. Consultez pauseReason avant de la reprendre.

ÉtatAction suivante
awaiting_uploadTransférez le fichier, puis démarrez la tâche existante.
running / finalizingPatientez. La finalisation peut inclure des requêtes inachevées, la préparation des fichiers de résultats et leur livraison au stockage.
pausedCorrigez la cause indiquée par pauseReason et reprenez la même tâche.
completedTéléchargez toutes les parties de résultats et examinez les lignes en échec.
failed / cancelledExaminez job.error et le reçu enregistré. Les opérations acceptées peuvent encore se terminer ; aucun manifeste final n’est publié.

Reprendre un workflow interrompu

Après un délai d’attente local dépassé ou une interruption du téléchargement des résultats, reprenez bulk-first. Cette opération lit la tâche distante existante sans soumettre à nouveau le jeu de données. Utilisez un nouveau nom de fichier de sortie. Une erreur partial_result peut laisser un fichier local partiel ; gardez-le séparé du résultat récupéré.

Conservez le même profil CLI et le même répertoire d’état à toutes les étapes. Pour un profil nommé, ajoutez --profile NAME à chaque commande.

SituationCorrection
awaiting_uploadruns recover ne répète ni le transfert du fichier ni le démarrage. Vérifiez l’identifiant enregistré, l’état du transfert et le fichier d’origine avant de continuer explicitement.
pausedCorrigez la cause signalée, puis utilisez bulk resume avec l’identifiant enregistré. La récupération ne reprend pas automatiquement une tâche en pause.
401 / 403Rétablissez un accès valide au compte et à la source utilisés pour la soumission. Réutilisez la même tâche après avoir corrigé l’authentification.
409 / 410409 : les résultats ne sont pas prêts. 410 : les résultats conservés ont expiré ; utilisez votre copie enregistrée.
L’URL de transfert a expiréConfirmez que l’ancienne tâche n’a jamais démarré avant d’en créer une nouvelle. Si la soumission est incertaine, consultez d’abord son identifiant enregistré.
Reprendre l’exécution enregistrée
flashdata runs show bulk-first --json
flashdata runs recover bulk-first --output recovered-results.ndjson --timeout 30m --json

Mettre une tâche en pause ou la reprendre

Remplacez BULK_ID par l’identifiant renvoyé par runs show bulk-first. La pause arrête les nouvelles soumissions et la préparation des fichiers de résultats ; les requêtes acceptées continuent. Corrigez pauseReason avant de reprendre. Pour modifier les options ou les identifiants de stockage, mettez à jour la tâche existante via l’API Bulk.

Mettre en pause
flashdata bulk pause BULK_ID --json
Reprendre après correction
flashdata bulk resume BULK_ID --json

Annuler définitivement

Annulez uniquement si vous souhaitez abandonner la tâche. L’annulation ne revient pas sur les requêtes acceptées et ne rembourse pas les opérations terminées. Les compteurs peuvent encore évoluer et aucun manifeste final n’est publié. La pause est réversible.

Annuler la tâche choisie
flashdata bulk cancel BULK_ID --json

Récupérer toutes les parties des résultats

Pour une tâche existante terminée, la CLI suit le manifeste et regroupe toutes les parties des résultats dans un fichier NDJSON. Utilisez un nouveau chemin de sortie et lancez l’audit d’importation sur le fichier regroupé. Les résultats de téléchargement décrivent les médias livrés ; ils ne contiennent pas les octets MP4 ou audio.

Récupérer toutes les parties d’une tâche existante
flashdata bulk results BULK_ID --output saved-results.ndjson --timeout 30m --json

Livrer vers votre stockage

Enregistrez les identifiants de votre fournisseur dans storage.json, dans le dossier de travail, avant d’exécuter cette commande. Utilisez les champs décrits dans le lien ci-dessous et gardez le fichier privé. L’option CLI --storage-config lit ce fichier JSON et sélectionne result_storage pour les données ou storage pour les médias. --options attend aussi un chemin de fichier, et non du JSON en ligne.

Exécuter avec la configuration de stockage enregistrée

Ajouter le stockage au workflow de métadonnées
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