# YouTube Data кращих практик

Знайдіть відповідні відео, оберіть треки та обробіть новий канал, що завантажується без повторення роботи.

Канонічне посилання: https://flashdata.dev/uk/docs/guides/youtube-data-guide
Переглянуто: 2026-11-04 від FlashData

<a id="choose"></a>

## Почати з інформацією, яку ви вже маєте

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

| Ваше завдання | Джерело | Пожертвувати |
| --- | --- | --- |
| Знайти відео про тему | youtube_search | Почати з п'яти кандидатів, потім вибрати відповідну актуальність. |
| Огляд відомого відео | youtube_metadata | Отримати назву, канал, тривалість і підпис мов. |
| Summarize або цитувати те, що сказав він | youtube_transcript / youtube_captions | Виберіть мову та автоматичну або ручну доріжок. |
| Перевірити останні завантаження каналів | youtube_channel | Порівняйте повернуто IDs з обробленим IDs. |

- [Знайти відео](https://flashdata.dev/uk/docs/guides/youtube-data-guide/reference.md#discover)
- [Робота з відомим відео](https://flashdata.dev/uk/docs/guides/youtube-data-guide/reference.md#metadata)
- [Моніторинг каналу](https://flashdata.dev/uk/docs/guides/youtube-data-guide/reference.md#channel)

<a id="setup"></a>

## Запустити приклади запиту

Заощаджуйте кожен корпус JSON за допомогою його відображення Python використовує адаптер query.py нижче; cURL може подати той самий файл. Введіть номер мобільного, який Ви вказали при укладаннi договору з банком - для ідентифікації. Кожна подача - це один запит, незалежно від кількості повернутих відео.

### Python

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

#### Встановити

```bash
python -m pip install requests
```


### cURL

Bash. Замініть REQUEST.json і RESULT.json з файлами для обраного прикладу. Перевірити результат перед повторенням запиту; це команда зберігає тіло HTTP навіть за помилку.

#### Подати збережений JSON запитати

```bash
(
set -eu
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e RESULT.json || { echo 'Read RESULT.json first'; exit 1; }
curl --fail-with-body --silent --show-error --max-time 70 \
  --request POST 'https://data.flashdata.dev/v1/queries/realtime' \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @REQUEST.json --output RESULT.json
)
```



<a id="authenticate"></a>

### Настроювання ключа API

Запобігти FLASHDATA_API_KEY з вашого терміналу або секретного магазину. В іншому випадку введіть ключ за допомогою однієї прихованої підказки нижче. Зберігати його в процесі, що працює цими прикладами.

#### Bash

##### Встановити ключ

```bash
# 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
```


#### PowerShell 7

##### Встановити ключ

```powershell
# PowerShell 7: paste the key into a hidden prompt.
$flashdataSecureKey = Read-Host "FlashData API key" -AsSecureString
$env:FLASHDATA_API_KEY = [System.Net.NetworkCredential]::new("", $flashdataSecureKey).Password
Remove-Variable flashdataSecureKey
```


- [API ключі](https://flashdata.dev/app/api-keys)
- [Пробний доступ агента й прив’язування облікового запису](https://flashdata.dev/uk/docs/guides/agent-onboarding/reference.md)

<a id="runner"></a>

### Заощаджуйте query.py для прикладів Python

Створіть query.py у новій робочій папці та скопіюйте код нижче. Збережіть запит JSON файли та інші скрипти Python у цій папці та запустіть всі команди з них.

#### query.py

```python
# 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))
```


<a id="discover"></a>

## Знайдіть кандидатів перед отриманням інформації

Відеофільтр виключає інші типи результатів; субтитри відкриття до відео з підписами. Не вибираєте мову підписки або гарантуйте потрібну вам трек. Збережіть як discover-request.json.

### discover-request.json

```json
{
  "source": "youtube_search",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 5,
    "filters": {
      "type": "video",
      "subtitles": true
    }
  }
}
```

### Відправте один раз з query.py

```bash
python query.py discover-request.json search.json
```


<a id="candidates"></a>

### Оберіть актуальність, не перший ID

Заощаджуйте candidates.py з query.py і search.json, потім запустіть його з цієї папки. Він зберігає порядок пошуку і видаляє дублікати відео IDs. Заголовки, канали і тривалість, потім скопіюйте вибраний ID на наступний запит. Порожній список – це не тільки кандидати.

#### candidates.py

```python
# 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))
```

#### Читати збережений пошук

```bash
python candidates.py
```


<a id="extended"></a>

### Витратити тільки при недостатньому списку

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

#### extended-request.json

```json
{
  "source": "youtube_search_extended",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 50,
    "filters": {
      "type": "video"
    }
  }
}
```

#### Запуск одного

```bash
python query.py extended-request.json extended.json
```

- [Подати більш тривалий пошук асинхронно](https://flashdata.dev/uk/docs/reference/realtime-and-async/reference.md#async)
- [Вибраний IDs](https://flashdata.dev/uk/docs/guides/enrich-youtube-videos/reference.md)

<a id="metadata"></a>

## Отримати лише метадані, які потрібно знати

Замініть зразок video_id з вибраним ID. Зберігати формати та розділи, відключені для простої відеокарти або замовчування. Увімкнути include_chapters для контуру, або include_formats при виборі медіа формату.

### metadata-request.json

```json
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": false
  }
}
```

### Відправте один раз з query.py

```bash
python query.py metadata-request.json metadata.json
```

- [Поля відповіді метаданих](https://flashdata.dev/uk/docs/sources/youtube_metadata/reference.md#response)
- [Відновлення інформації](https://flashdata.dev/uk/docs/guides/media-delivery-pipeline/reference.md)

<a id="tracks"></a>

### Огляд доступних мов

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

| Настроювання | Використовуйте його для |
| --- | --- |
| language | Код від transcriptLanguages, наприклад, zh-Hans. Цей список не відрізняє ручні та автоматичні доріжки. |
| auto: true | В даний час автоматично генерується трек. |
| auto: false | В наявності ручна надана доріжка. Не існує недоліку двох типів треків. |

#### Читати metadata.json · немає запиту

```bash
python -m json.tool metadata.json
```


<a id="captions"></a>

## Виберіть мову та відстежити явно

Використовуйте те ж саме video_id, як запит метаданих та змінити мову та автоматично, щоб відповідати вибраному треку. За замовчуванням youtube_transcript до auto: true; За замовчуванням youtube_captions до auto: false. Як отримати існуючі підписи, не мовно-текстові.

### captions-request.json

```json
{
  "source": "youtube_transcript",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": true
  }
}
```

### Відправте один раз з query.py

```bash
python query.py captions-request.json captions.json
```

- [Параметри підписки](https://flashdata.dev/uk/docs/sources/youtube_transcript/reference.md#parameters)
- [Побудувати загальний підсумок](https://flashdata.dev/uk/docs/guides/youtube-summary/reference.md)

<a id="citations"></a>

### Зберігати часову заглушку з доказами

Заощаджуйте cite-segments.py біля captions.json і запустіть його з цієї папки. Використовуйте results[0].segments для цитування: початок та кінець секунди. Зареєструватися languageCode і isAutoGenerated з текстом. fullText корисно для читання, але не замінює термінів сегмента. Якщо обраний трек відсутній, запишіть проміжок перед тим, як вирішити, чи варто ще один запит.

#### cite-segments.py

```python
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 виклик

```bash
python cite-segments.py
```


<a id="channel"></a>

## Процес тільки нові відео з відомого каналу

Використовуйте ручку каналів і обмежену video_limit (1–100). results[0].videos є повернутим недавнім переліком; videoCount є метадані каналу, не кількість повернутих елементів. Виберіть ліміт і графік, який закриває завантаження, потрібно дотримуватися.

### channel-request.json

```json
{
  "source": "youtube_channel",
  "handle": "@TED",
  "params": {
    "video_limit": 10
  }
}
```

### Відправте один раз з query.py

```bash
python query.py channel-request.json channel.json
```


<a id="channel-diff"></a>

### Зберігайте черги та контрольно-вимірювальна точка

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

#### channel-queue.py

```python
# 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))
```

#### План → процес → комітувати

```bash
python channel-queue.py
# Process every ID in new-ids.json and save its result first.
python channel-queue.py --commit
```

- [Графік роботи та використання облікових записів](https://flashdata.dev/uk/docs/guides/recurring-tasks/reference.md)
- [Збагатити список відео](https://flashdata.dev/uk/docs/guides/enrich-youtube-videos/reference.md)

<a id="channel-checkpoint"></a>

### Почати свіжий канал перевірити навмисно

Допоможисер запиту перевикористає збережену відповідь. Для наступного запланованого перевірки використовуйте назву нового результату, перевірте його, потім скопіюйте, що завершили відповідь на channel.json на черги. Тримайте processed-ids.json між пробігами. Цей список не є повноканальним експортом або потоковим передаванням.

#### Наступна реєстрація · вибрати свіжу ім'я файлу

```bash
python query.py channel-request.json channel-next.json
```

#### Після підтвердження статусу здійснюється

```bash
python -c "from shutil import copyfile; copyfile('channel-next.json', 'channel.json')"
```


<a id="suggestions"></a>

## Використовуйте пропозиції для поліпшення запиту

Запрошення повертає фрази у results[0], не відеозаписи. Виберіть корисну фразу і зробити окремий запит youtube_search. Налаштуйте мову та регіон для аудиторії, яку ви вивчаєте.

### suggestions-request.json

```json
{
  "source": "youtube_suggestions",
  "query": "battery recycling",
  "params": {
    "language": "en",
    "region": "US"
  }
}
```

### Відправте один раз з query.py

```bash
python query.py suggestions-request.json suggestions.json
```


<a id="license"></a>

## Зберігайте ліцензійні етикетки без обробки їх як дозволу

youtube_trainability повертає на відео мітку ліцензії. Дозволено: ["all"] карти на творчі Загальні положення; ["none"] також охоплює відсутні ліцензійні метадані. Зберігайте відео ID, відповідь на джерело та дати ретривалі. Ця етикетка не надає завантаження, повторно використовувати або навчати права.

### license-request.json

```json
{
  "source": "youtube_trainability",
  "video_id": "FUfGcZ092b0"
}
```

### Відправте один раз з query.py

```bash
python query.py license-request.json license.json
```


<a id="operations"></a>

## Підключіть роботу для додатків і агентів

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

- [Realtime та async](https://flashdata.dev/uk/docs/reference/realtime-and-async/reference.md)
- [Batch і Bulk](https://flashdata.dev/uk/docs/reference/batch-and-bulk/reference.md)
- [Помилки та рети](https://flashdata.dev/uk/docs/errors/reference.md#retries)
- [Поточне ціноутворення та баланс](https://flashdata.dev/uk/docs/guides/credits-and-billing/reference.md)
