Salta al contenuto
IT
Ottieni la chiave API
Sfoglia la documentazione

Guide

YouTube Migliori pratiche di dati

Trova i video pertinenti, seleziona le tracce didascalia e elabora nuovi upload dei canali senza ripetere il lavoro.

In questa pagina

Inizia con le informazioni che hai già

Ogni fonte risponde a una domanda diversa. Salta la scoperta per un noto video ID o maniglia del canale, e arricchisci solo i video di cui hai bisogno.

Il tuo compitoFonteDecisione
Trova i video su un argomentoyoutube_searchIniziare con cinque candidati, quindi selezionare per importanza.
Ispezione di un video notoyoutube_metadataOttieni il titolo, il canale, la durata e le lingue didascalia.
Summarizzare o citare ciò che è stato dettoyoutube_transcript / youtube_captionsScegli una lingua e una traccia automatica o manuale.
Controllare gli upload recenti del canaleyoutube_channelConfronta IDs restituito con il tuo IDs processato.

Eseguire gli esempi di richiesta

Salvare ogni corpo JSON utilizzando il nome del file visualizzato. Python utilizza l'helper query.py qui sotto; cURL può inviare lo stesso file. Utilizzare una chiave con le autorizzazioni di origine di cui hai bisogno e i crediti disponibili. Ogni presentazione è una domanda, indipendentemente dal numero di video restituiti.

Python 3.10+. Installare le richieste una volta, salvare query.py di seguito, quindi utilizzare il comando accanto a ogni richiesta. Le uscite esistenti vengono riutilizzate; l'ingresso modificato richiede un nuovo nome di file di output.

Installa
python -m pip install requests

Impostare il tasto API

Riutilizza FLASHDATA_API_KEY dal tuo terminale o negozio segreto. In caso contrario, inserire la chiave utilizzando un prompt nascosto qui sotto. Mantenere il processo di esecuzione di questi esempi.

Impostare la chiave
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY

Salvare query.py per gli esempi Python

Crea query.py in una nuova cartella di lavoro e copia il codice completo qui sotto. Salvare la richiesta di file JSON e altri script Python in questa cartella e eseguire tutti i comandi da lì.

query.py
# query.py — submit a saved request once, then reuse its response.
import json
import os
import sys
from pathlib import Path
import requests

if len(sys.argv) != 3:
    raise SystemExit("Usage: python query.py REQUEST.json RESULT.json")
payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8-sig"))
output = Path(sys.argv[2])
marker = output.with_name(output.name + ".request.json")
receipt = output.with_name(output.name + ".http.json")
if marker.exists():
    if json.loads(marker.read_text()) != payload:
        raise SystemExit("Changed request: choose a new output filename.")
    if not output.exists() or not receipt.exists():
        raise SystemExit("Outcome unknown: check History before resubmitting.")
    saved = json.loads(receipt.read_text())
    if saved["status"] != 200 or json.loads(output.read_text(encoding="utf-8")).get("status") != "done":
        raise SystemExit(f"Saved request failed or incomplete; Retry-After: {saved['retry_after']}. Inspect {output}.")
    print(f"Read the saved {output}; no new query submitted.")
    raise SystemExit(0)
if output.exists():
    raise SystemExit("Output already exists. Read it or choose a new filename.")
key = os.environ["FLASHDATA_API_KEY"]
with marker.open("x", encoding="utf-8") as file:
    json.dump(payload, file)
response = requests.post("https://data.flashdata.dev/v1/queries/realtime",
                         headers={"X-API-Key": key}, json=payload,
                         timeout=70, allow_redirects=False)
output.write_text(response.text, encoding="utf-8")
receipt.write_text(json.dumps({"status": response.status_code,
                               "retry_after": response.headers.get("Retry-After")}), encoding="utf-8")
if response.status_code != 200:
    raise SystemExit(f"HTTP {response.status_code}; Retry-After: {response.headers.get('Retry-After')}")
if response.json().get("status") != "done":
    raise SystemExit(f"Inspect {output} and History before retrying.")
print(json.dumps({"saved": str(output), "usage": response.json().get("usage")}, indent=2))

Trova i candidati prima di ottenere i dettagli

Il filtro video esclude altri tipi di risultati; sottotitoli restringe la scoperta ai video con didascalie. Non seleziona una lingua didascalia o garantisce la traccia di cui hai bisogno. Salva come discover-request.json.

discover-request.json
{
  "source": "youtube_search",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 5,
    "filters": {
      "type": "video",
      "subtitles": true
    }
  }
}
Invia una volta con query.py
python query.py discover-request.json search.json

Selezionare per rilevanza, non il primo ID

Salvare candidates.py accanto a query.py e search.json, quindi eseguirlo da quella cartella. Mantiene l'ordine di ricerca e rimuove il video duplicato IDs. Ispezionare i titoli, i canali e la durata, quindi copiare un ID selezionato nella prossima richiesta. Una lista vuota è una ricerca completa senza candidati.

candidates.py
# candidates.py — read a saved response; no API calls.
import json
import re
from pathlib import Path

data = json.loads(Path("search.json").read_text(encoding="utf-8"))
if data.get("status") != "done":
    raise SystemExit("Search did not complete; inspect search.json.")
candidates, seen = [], set()
for item in (data.get("results") or [{}])[0].get("results", []):
    video_id = item.get("videoId", "")
    if not re.fullmatch(r"[A-Za-z0-9_-]{11}", video_id) or video_id in seen:
        continue
    seen.add(video_id)
    candidates.append({"videoId": video_id, "title": item.get("title"),
                       "channel": item.get("channel"), "duration": item.get("duration"),
                       "url": "https://www.youtube.com/watch?v=" + video_id})
Path("candidates.json").write_text(json.dumps(candidates, indent=2), encoding="utf-8")
print(json.dumps(candidates, indent=2))
Leggi la ricerca salvata
python candidates.py

Espandi solo quando la lista corta è insufficiente

Standard Search supporta max_results fino a 20. Per una raccolta più ampia, passare a youtube_search_extended, che supporta fino a 700 e ha prezzi separati. Questo esempio chiede 50; controlla se i primi risultati sono utili prima di arricchirli tutti.

extended-request.json
{
  "source": "youtube_search_extended",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 50,
    "filters": {
      "type": "video"
    }
  }
}
Scappa una volta
python query.py extended-request.json extended.json

Recuperare solo i metadati di cui hai bisogno

Sostituisci il campione video_id con il tuo ID selezionato. Mantenere formati e capitoli disabilitati per una semplice scheda video o controllo in lingua didascalia. Abilitare include_chapters per un profilo, o include_formats quando si sceglie un formato multimediale.

metadata-request.json
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": false
  }
}
Invia una volta con query.py
python query.py metadata-request.json metadata.json

Ispezione delle lingue disponibili

Leggi i risultati[0].transcriptLanguages prima di scegliere le didascalie. Formati, capitoli e lingue sono campi sull'oggetto video restituito; il record di utilizzo appartiene alla risposta esterna.

ImpostazioneUsalo per
languageUn codice da transcriptLanguages, come en o zh-Hans. Questa lista non distingue le tracce manuali e automatiche.
auto: trueUna traccia generata automaticamente esistente.
auto: falseUna traccia fornita manualmente esistente. Non c'è alcun ritorno tra i due tipi di traccia.
Leggi metadata.json · nessuna query
python -m json.tool metadata.json

Scegli la lingua e traccia esplicitamente

Utilizzare lo stesso video_id come la vostra richiesta di metadati e cambiare lingua e auto per abbinare la traccia scelta. youtube_transcript di default per l'auto: true; youtube_captions di default per l'auto: false. Entrambi recuperano le didascalie esistenti, non parole-to-text.

captions-request.json
{
  "source": "youtube_transcript",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": true
  }
}
Invia una volta con query.py
python query.py captions-request.json captions.json

Tenere il timestamp con le prove

Salvare cite-segments.py accanto a captions.json ed eseguirlo da quella cartella. Utilizzare i risultati[0].segmenti per le citazioni: inizio e fine sono secondi. Conservare languageCode e isAutoGenerated con il testo. fullText è utile per la lettura, ma non sostituisce la tempistica del segmento. Se la traccia scelta manca, registra il divario prima di decidere se vale un'altra domanda.

cite-segments.py
import json
from pathlib import Path

response = json.loads(Path("captions.json").read_text(encoding="utf-8"))
if response.get("status") != "done":
    raise SystemExit("Inspect captions.json before continuing.")
track = (response.get("results") or [{}])[0]
if not track.get("segments"):
    raise SystemExit("No caption evidence was returned.")
for segment in track["segments"][:3]:
    url = f"https://www.youtube.com/watch?v={track['videoId']}&t={int(segment['start'])}s"
    print(segment["text"], url)
Leggi le didascalie salvate · no API
python cite-segments.py

Elabora solo nuovi video da un canale noto

Utilizzare una maniglia del canale e un limitato video_limit (1–100). risultati[0].videos è l'elenco recente restituito; videoCount è metadati del canale, non il numero di elementi restituiti. Scegli un limite e un calendario che coprano i caricamenti che devi osservare.

channel-request.json
{
  "source": "youtube_channel",
  "handle": "@TED",
  "params": {
    "video_limit": 10
  }
}
Invia una volta con query.py
python query.py channel-request.json channel.json

Mantenere una coda e un checkpoint di completamento

Salvare channel-queue.py accanto a query.py e channel.json, ed eseguirlo da quella cartella. Eseguire senza argomenti per creare new-ids.json, quindi elaborare e salvare le prove per quelle IDs. Eseguire --commit solo dopo che ogni coda ID riesce; un guasto lascia il punto di controllo invariato. Utilizzare una directory per canale e un lavoratore per questo esempio.

channel-queue.py
# channel-queue.py — plan first; commit only after every queued video is processed.
import json
import re
import sys
from pathlib import Path

checkpoint = Path("processed-ids.json")
processed = set(json.loads(checkpoint.read_text()) if checkpoint.exists() else [])
queue = Path("new-ids.json")
if sys.argv[1:] == ["--commit"]:
    processed.update(json.loads(queue.read_text()))
    temporary = checkpoint.with_suffix(".tmp")
    temporary.write_text(json.dumps(sorted(processed)), encoding="utf-8")
    temporary.replace(checkpoint)
    queue.unlink()
    print("Checkpoint saved.")
elif sys.argv[1:]:
    raise SystemExit("Usage: python channel-queue.py [--commit]")
else:
    data = json.loads(Path("channel.json").read_text(encoding="utf-8"))
    if data.get("status") != "done":
        raise SystemExit("Channel query did not complete.")
    ids = dict.fromkeys(video.get("videoId", "") for video in
                        (data.get("results") or [{}])[0].get("videos", []))
    new = [value for value in ids if re.fullmatch(r"[A-Za-z0-9_-]{11}", value)
           and value not in processed]
    if queue.exists() and json.loads(queue.read_text()) != new:
        raise SystemExit("Finish the existing queue before replacing it.")
    queue.write_text(json.dumps(new, indent=2), encoding="utf-8")
    print(json.dumps(new, indent=2))
Piani → processo → commit
python channel-queue.py
# Process every ID in new-ids.json and save its result first.
python channel-queue.py --commit

Avviare un controllo del canale fresco deliberatamente

Il query helper riutilizza una risposta salvata. Per il successivo controllo programmato, utilizzare un nuovo nome di file di risultato, ispezionarlo, quindi copiare quella risposta completa a channel.json per la fase di coda. Tenere processed-ids.json tra le piste. Questo elenco recente non è un'esportazione a pieno canale o un flusso di eventi.

Prossimo controllo · scegliere un nome di file fresco
python query.py channel-request.json channel-next.json
Dopo aver confermato lo stato è fatto
python -c "from shutil import copyfile; copyfile('channel-next.json', 'channel.json')"

Utilizzare i suggerimenti per migliorare la query

Suggerimenti restituiscono frasi nei risultati[0], non record video. Selezionare una frase utile e fare una richiesta youtube_search separata. Impostare la lingua e la regione per il pubblico che si sta ricercando.

suggestions-request.json
{
  "source": "youtube_suggestions",
  "query": "battery recycling",
  "params": {
    "language": "en",
    "region": "US"
  }
}
Invia una volta con query.py
python query.py suggestions-request.json suggestions.json

Archiviare etichette di licenza senza trattarle come permesso

youtube_trainability restituisce un'etichetta di licenza per un video. permesso: ["all"] mappe a Creative Commons; ["none"] copre anche i metadati di licenza mancanti. Tenere il video ID, risposta di origine e data di recupero. Questa etichetta non concede diritti di download, riutilizzo o formazione.

license-request.json
{
  "source": "youtube_trainability",
  "video_id": "FUfGcZ092b0"
}
Invia una volta con query.py
python query.py license-request.json license.json

Creare il lavoro per applicazioni e agenti

ArticoloAtto
Selezionare prima di arricchirePer un'attività di argomento: una ricerca, un metadati selezionati del video e una traccia di didascalia scelta. Applicare il budget delle chiamate nella tua app e il prezzo di ogni fonte separatamente.
Riutilizzo da parte dell'ingresso effettivoMetadati: video ID + opzioni. Didascalie: video ID + lingua + traccia. Le snapshot del canale hanno anche bisogno di un tempo di recupero o di eseguire ID.
Smettere di mancare di proveNon riprovare un risultato di scoperta vuoto o commutare silenziosamente le tracce di didascalia. Restituire il gap in modo che l'utente o il flusso di lavoro possano scegliere l'azione successiva.
Conservare l'uso e il lavoro fallitoSalvare l'uso con risposte di successo. Su 429, onore Retry-After; dopo una presentazione incerta, controllare History prima di un'altra domanda a pagamento.