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

Poradniki

Najlepsze praktyki YouTube Data

Znajdź odpowiednie filmy wideo, wybierz ścieżkę podrywu i przerób nowe kanały bez powtarzania pracy.

Na tej stronie

Zacznij od informacji, które już posiadasz

Każde źródło odpowiada na inne pytanie. Pomiń odkrycie dla znanego wideo ID lub uchwyt kanału, i wzbogacić tylko filmy wideo potrzebne zadanie.

Twoje zadanieŹródłoDecyzja
Znajdź filmy o temacieyoutube_searchZacznij od pięciu kandydatów, a następnie wybierz ze względu na znaczenie.
Sprawdź znany filmyoutube_metadataUzyskaj tytuł, kanał, czas trwania i napisy językowe.
Podsumować lub cytować to, co powiedzianoyoutube_transcript / youtube_captionsWybierz język i ścieżkę automatyczną lub ręczną.
Sprawdź ostatnie kanały przesyłaniayoutube_channelPorównaj IDs z przetworzonym IDs.

Uruchom przykłady żądania

Zapisz każde ciało JSON za pomocą wyświetlanej nazwy pliku. Python używa helpera query.py poniżej; cURL może przesłać ten sam plik. Użyj klucza z uprawnieniami źródłowymi, których potrzebujesz i dostępnymi kredytami. Każdy wniosek jest jednym pytaniem, niezależnie od liczby zwróconych filmów wideo.

Python 3.10+. Zainstaluj żądania raz, zapisz query.py poniżej, a następnie użyj polecenia obok każdego żądania. Istniejące wyjścia są ponownie używane; zmienione wejście wymaga nowej nazwy pliku wyjściowego.

Zainstaluj
python -m pip install requests

Ustaw klawisz API

Ponownie użyj FLASHDATA_API_KEY z terminala lub tajnego sklepu. W przeciwnym razie wpisz klucz używając jednego ukrytego sygnału poniżej. Utrzymuj go w procesie, wykonując te przykłady.

Ustaw klucz
# 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

Zapisz query.py dla przykładów Python

Utwórz query.py w nowym katalogu roboczym i skopiuj do niego cały kod poniżej. Zapisz żądanie JSON plików i innych skryptów Python w tym folderze i uruchom wszystkie polecenia stamtąd.

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))

Znajdź kandydatów przed pobraniem szczegółów

Filtr wideo wyklucza inne typy wyników; napisy zawężają odkrycia do filmów z podpisami. Nie wybiera języka napisy ani nie gwarantuje ścieżki, której potrzebujesz. Zapisz jako discover-request.json.

discover-request.json
{
  "source": "youtube_search",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 5,
    "filters": {
      "type": "video",
      "subtitles": true
    }
  }
}
Prześlij raz query.py
python query.py discover-request.json search.json

Wybierz ze względu na znaczenie, a nie pierwszy ID

Zapisz candidates.py obok query.py i search.json, a następnie uruchom go z tego folderu. Utrzymuje kolejność wyszukiwania i usuwa duplikat wideo IDs. Sprawdź tytuły, kanały i czas trwania, a następnie skopiuj wybrany ID do następnej prośby. Pusta lista jest zakończonym wyszukiwaniem bez kandydatów.

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))
Przeczytaj zapisane wyszukiwanie
python candidates.py

Rozwiń tylko wtedy, gdy krótka lista jest niewystarczająca

Wyszukiwarka standardowa obsługuje max_results aż do 20. Dla szerszej kolekcji, przełącz na youtube_search_extended, który obsługuje do 700 i ma oddzielne ceny. Ten przykład pyta o 50; sprawdź, czy Twoje pierwsze wyniki są przydatne przed wzbogaceniem ich wszystkich.

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

Pobieranie tylko metadanych, których potrzebujesz

Zastąpić próbkę video_id wybranym ID. Utrzymuj format i rozdziały wyłączone dla prostej karty wideo lub podpisy-język sprawdzania. Włącz include_chapters dla konturu lub include_formats przy wyborze formatu nośnika.

metadata-request.json
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": false
  }
}
Prześlij raz query.py
python query.py metadata-request.json metadata.json

Sprawdź dostępne języki

Przeczytaj wyniki [0] .transcriptLanguages przed wybraniem napisów. Formaty, rozdziały i języki są polami zwróconego obiektu wideo; zapis użycia należy do odpowiedzi zewnętrznej.

UstawienieUżyj go do
languageKod transcriptLanguages, takich jak en lub zh- Hans. Lista ta nie wyróżnia ręcznych i automatycznych torów.
auto: trueIstniejący automatycznie generowany utwór.
auto: falseIstniejący ręczny utwór. Między dwoma typami torów nie ma odwrotu.
Przeczytaj metadata.json · bez zapytania
python -m json.tool metadata.json

Wybierz język i śledzić wyraźnie

Użyj tego samego video_id, co żądasz metadanych, a także zmień język i auto, aby dopasować wybrany utwór. youtube_transcript domyślnie pasuje do auto: true; youtube_captions domyślnie do auto: false. Obie pobierają istniejące podpisy, a nie przekaz do tekstu.

captions-request.json
{
  "source": "youtube_transcript",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": true
  }
}
Prześlij raz query.py
python query.py captions-request.json captions.json

Zatrzymaj znacznik czasu wraz z dowodami

Zapisz cite-segments.py obok captions.json i uruchom go z tego folderu. Użyj wyników [0] .segmenty dla cytowania: start i koniec są sekundami. Zachować languageCode i isAutoGenerated z tekstem. fullText jest przydatny do odczytu, ale nie zastępuje czasu segmentu. Jeśli wybrana ścieżka jest brakująca, zapisz lukę przed podjęciem decyzji, czy inne zapytanie jest warte zachodu.

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)
Odczyt zapisanych napisów · bez wywołania API
python cite-segments.py

Przetwarzanie tylko nowych filmów ze znanego kanału

Użyj uchwytu kanału i ograniczonego video_limit (1–100). Rezultaty [0] .Video to zwrócona lista; videoCount to metadane kanału, a nie liczba zwróconych elementów. Wybierz limit i harmonogram, który obejmuje pliki, które należy obserwować.

channel-request.json
{
  "source": "youtube_channel",
  "handle": "@TED",
  "params": {
    "video_limit": 10
  }
}
Prześlij raz query.py
python query.py channel-request.json channel.json

Zachowaj kolejkę i punkt kontrolny zakończenia

Zapisz channel-queue.py obok query.py i channel.json i uruchom go z tego folderu. Uruchom bez argumentów, aby utworzyć new-ids.json, a następnie przetworzyć i zapisać dowody dla tych IDs. Uruchom --commit tylko po każdym sukcesie kolejki ID; awaria pozostawia punkt kontrolny bez zmian. Użyj jednego katalogu na kanał i jednego pracownika dla tego przykładu.

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))
Plan → proces → commit
python channel-queue.py
# Process every ID in new-ids.json and save its result first.
python channel-queue.py --commit

Rozpocząć sprawdzanie kanału z premedytacją

Pomocnik zapytania ponownie używa zapisanej odpowiedzi. Dla następnej planowej kontroli, użyj nowej nazwy pliku wyniku, sprawdź go, a następnie skopiuj, który zakończył odpowiedź na channel.json dla kroku kolejki. Zachowaj processed-ids.json pomiędzy biegami. Ten ostatni wykaz nie jest pełnokanałowym eksportem ani strumieniem zdarzeń.

Następna kontrola · wybierz świeżą nazwę pliku
python query.py channel-request.json channel-next.json
Po potwierdzeniu statusu jest wykonane
python -c "from shutil import copyfile; copyfile('channel-next.json', 'channel.json')"

Użyj sugestii, aby poprawić zapytanie

Sugeruje zwrot zwrotów w wynikach [0], a nie nagrania wideo. Wybierz przydatne zdanie i zrób osobne youtube_search żądanie. Ustaw język i region dla publiczności, którą badasz.

suggestions-request.json
{
  "source": "youtube_suggestions",
  "query": "battery recycling",
  "params": {
    "language": "en",
    "region": "US"
  }
}
Prześlij raz query.py
python query.py suggestions-request.json suggestions.json

Przechowywanie etykiet licencyjnych bez traktowania ich jako zezwolenia

youtube_trainability zwraca etykietę licencyjną dla wideoo. dozwolone: ["all"] maps to Creative Commons; ["none"] obejmuje również brakujące metadane licencji. Zachowaj wideo ID, odpowiedź źródła i datę pobrania. Niniejsza etykieta nie przyznaje praw do pobierania, ponownego wykorzystywania lub szkolenia.

license-request.json
{
  "source": "youtube_trainability",
  "video_id": "FUfGcZ092b0"
}
Prześlij raz query.py
python query.py license-request.json license.json

Ogranicza pracę dla aplikacji i agentów

ArtykułWykonanie
Wybierz przed wzbogaceniemDla zadania tematycznego: jedno wyszukiwanie, jeden wybrany metadane wideo i jeden wybrany utwór podsumowujący. Wymuszanie budżetu połączeń w aplikacji i cena każdego źródła oddzielnie.
Ponowne wykorzystanie przez rzeczywisty wkładMetadane: opcje wideo ID +. Podpisy: wideo ID + język + utwór. Migawki kanału również potrzebują czasu pobierania lub uruchomić ID.
Zatrzymaj brakujące dowodyNie należy ponownie próbować pustego wyniku wyszukiwania lub po cichu przełączać śladów nagrywania. Zwróć lukę, aby użytkownik lub przepływ pracy mógł wybrać następne działanie.
Zachowanie użytkowania i nieudanej pracyZapisz użycie z udanych odpowiedzi. Na 429, honor Retry-After; po niepewnym zgłoszeniu, sprawdzić History przed innym płatnym zapytaniem.