Перейти к содержимому
RU
Ключ API
Обзор документации

Руководства

Лучшие практики YouTube Data

Найдите соответствующие видео, выберите дорожки подписей и обработайте новые загрузки канала без повторения работы.

На этой странице

Начните с информации, которая у вас уже есть

Каждый источник отвечает на разные вопросы. Пропустите обнаружение для известного видео ID или ручки канала, и обогатите только видео, которые нужны вашей задаче.

Ваша задачаИсточникРешение
Найти видео по темеyoutube_searchНачните с пяти кандидатов, затем выберите по релевантности.
Проверить известное видеоyoutube_metadataПолучите название, канал, продолжительность и языки подписей.
Подытожить или процитировать сказанноеyoutube_transcript / youtube_captionsВыберите язык и автоматический или ручной трек.
Проверить последние загрузки каналаyoutube_channelСравните возвращенный IDs с обработанным IDs.

Запустите примеры запросов

Сохраните каждый JSON, используя отображаемое имя файла. Python использует помощник query.py ниже; cURL может отправить тот же файл. Используйте ключ с необходимыми разрешениями источника и доступными кредитами. Каждая заявка представляет собой один запрос, независимо от количества возвращенных видео.

Python 3.10+. Установите запросы один раз, сохраните query.py ниже, затем используйте команду рядом с каждым запросом. Существующие выходы повторно используются; измененный вход требует нового имени файла вывода.

Установить
python -m pip install requests

Установите ключ API

Повторное использование FLASHDATA_API_KEY из вашего терминала или секретного магазина. В противном случае введите ключ, используя одну скрытую подсказку ниже. Держите его в процессе выполнения этих примеров.

Установите ключ
# 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

Сохранить query.py для примеров Python

Создайте query.py в новой рабочей папке и скопируйте в нее полный код ниже. Сохраните файлы JSON и другие скрипты Python в этой папке и запустите все команды оттуда.

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

Найдите кандидатов, прежде чем приносить детали

Видеофильтр исключает другие типы результатов; субтитры сужают обнаружение видео с подписями. Он не выбирает язык подписи или не гарантирует нужный вам трек. Сохраните как discover-request.json.

discover-request.json
{
  "source": "youtube_search",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 5,
    "filters": {
      "type": "video",
      "subtitles": true
    }
  }
}
Отправить один раз с query.py
python query.py discover-request.json search.json

Выбор по релевантности, а не первый ID

Сохраните candidates.py рядом с query.py и search.json, а затем запустите его из этой папки. Он сохраняет порядок поиска и удаляет дублированное видео IDs. Проверяйте заголовки, каналы и продолжительность, а затем скопируйте выбранный ID в следующий запрос. Пустой список - это завершенный поиск без кандидатов.

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))
Читать сохраненный поиск
python candidates.py

Расширение только тогда, когда короткий список недостаточен

Стандартный поиск поддерживает max_results вплоть до 20. Для более широкой коллекции перейдите на youtube_search_extended, который поддерживает до 700 и имеет отдельную цену. Этот пример запрашивает 50; проверьте, полезны ли ваши первые результаты, прежде чем обогатить их все.

extended-request.json
{
  "source": "youtube_search_extended",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 50,
    "filters": {
      "type": "video"
    }
  }
}
Беги один раз
python query.py extended-request.json extended.json

Восстанавливайте только метаданные, необходимые вашей функции

Замените образец video_id выбранным ID. Держите форматы и главы отключенными для простой видеокарты или проверки языка подписи. Включите include_chapters для схемы или include_formats при выборе медиаформата.

metadata-request.json
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": false
  }
}
Отправить один раз с query.py
python query.py metadata-request.json metadata.json

Проверка доступных языков

Прочитайте results[0].transcriptLanguages, прежде чем выбрать подписи. Форматы, главы и языки являются полями на возвращаемом видеообъекте; запись использования принадлежит внешнему ответу.

настройкаИспользуйте его для
languageКод от transcriptLanguages, например, en или zh-Hans. В этом списке не различают ручные и автоматические дорожки.
auto: trueСуществующий автоматически сгенерированный трек.
auto: falseСуществующая ручная дорожка. Между этими двумя типами трасс нет никаких откатов.
Читать metadata.json · без запроса
python -m json.tool metadata.json

Выберите язык и отслеживайте явно

Используйте тот же video_id, что и ваш запрос метаданных, и измените язык и авто, чтобы соответствовать выбранному треку. youtube_transcript по умолчанию на auto: true; youtube_captions по умолчанию на auto: false. Оба извлекают существующие подписи, а не речь в текст.

captions-request.json
{
  "source": "youtube_transcript",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": true
  }
}
Отправить один раз с query.py
python query.py captions-request.json captions.json

Сохраняйте метки времени с доказательствами

Сохраните cite-segments.py рядом с captions.json и запустите его из этой папки. Используйте results[0].segments для цитирования: начало и конец - секунды. Сохраняйте languageCode и isAutoGenerated с текстом. fullText полезен для чтения, но не заменяет синхронизацию сегментов. Если выбранный трек отсутствует, запишите пробел, прежде чем решить, стоит ли другой запрос.

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)
Читать сохраненные подписи · без звонка API
python cite-segments.py

Обработка только новых видео с известного канала

Используйте ручку канала и ограниченный video_limit (1–100). results[0].videos - это возвращенный недавний список; videoCount - это метаданные канала, а не количество возвращенных элементов. Выберите лимит и расписание, которые покрывают загрузку, которую вы должны соблюдать.

channel-request.json
{
  "source": "youtube_channel",
  "handle": "@TED",
  "params": {
    "video_limit": 10
  }
}
Отправить один раз с query.py
python query.py channel-request.json channel.json

Держите очередь и контрольный пункт завершения

Сохраните channel-queue.py рядом с query.py и channel.json и запустите его из этой папки. Выполняйте без аргументов создание new-ids.json, затем обрабатывайте и сохраняйте доказательства для этих IDs. Запустите --commit только после того, как каждая очередь ID будет успешной; отказ оставляет контрольную точку неизменной. Используйте для этого примера один каталог на канал и одного сотрудника.

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))
План → процесс → Совершение
python channel-queue.py
# Process every ID in new-ids.json and save its result first.
python channel-queue.py --commit

Начните новую проверку канала намеренно

Помощник запроса повторно использует сохраненный ответ. Для следующей плановой проверки используйте новое имя файла результата, проверьте его, а затем скопируйте заполненный ответ на channel.json для шага очереди. Храните processed-ids.json между заездами. Этот недавний список не является полноканальным экспортом или потоком событий.

Следующая проверка · выберите новое имя файла
python query.py channel-request.json channel-next.json
После подтверждения статуса сделано
python -c "from shutil import copyfile; copyfile('channel-next.json', 'channel.json')"

Используйте предложения для улучшения запроса

Предложения возвращают фразы в results[0], а не видеозаписи. Выберите полезную фразу и сделайте отдельный запрос youtube_search. Установите язык и регион для аудитории, которую вы исследуете.

suggestions-request.json
{
  "source": "youtube_suggestions",
  "query": "battery recycling",
  "params": {
    "language": "en",
    "region": "US"
  }
}
Отправить один раз с query.py
python query.py suggestions-request.json suggestions.json

Хранить этикетки лицензий, не рассматривая их как разрешение

youtube_trainability возвращает лицензионную этикетку для видео. разрешено: ["all"] карты в Creative Commons; ["none"] также охватывает отсутствующие метаданные лицензии. Сохраните видео ID, источник ответа и дату поиска. Этот ярлык не предоставляет права на загрузку, повторное использование или обучение.

license-request.json
{
  "source": "youtube_trainability",
  "video_id": "FUfGcZ092b0"
}
Отправить один раз с query.py
python query.py license-request.json license.json

Свяжите работу с приложениями и агентами

ПравилоОсуществление
Выберите, прежде чем обогащатьДля тематической задачи: один поиск, один выбранный метаданные видео и один выбранный трек подписи. Выполните бюджет звонков в своем приложении и расцените каждый источник отдельно.
Повторное использование по фактическому входуМетаданные: видео ID + опции. Видео ID + язык + трек. Снимки канала также требуют времени поиска или запуска ID.
Остановитесь на недостающих уликахНе повторяйте пустой результат обнаружения или бесшумно переключайте дорожки подписей. Верните пробел, чтобы пользователь или рабочий процесс могли выбрать следующее действие.
Сохранение использования и неудачные работыСохранить использование с успешными ответами. На 429, почитайте Retry-After; после неопределенного представления, проверьте History перед другим платным запросом.