# Перегляд метаданих відео

Увімкніть YouTube відео ID в збережений запис його назви, канал, тривалість і доступні підрахунки. Зберігайте оригінальну відповідь і використання разом з ним.

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

<a id="prepare"></a>

## Перед тим, як початися

Використовуйте ключ з дозволом youtube_metadata і доступні кредити. Виберіть Python 3.10+ з запитами, або Bash з cURL 7.76+ і jq. На Windows використовується Git Bash для версії Bash.

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

<a id="input"></a>

## 1. Виберіть одне відео

Створіть папку відео-metadata і зберегти request.json там. Відкрийте термінал в цій папці. Замініть video_id з 11-character ID з годинника URL або YouTube Search результат; не пропустіть повну URL.

Встановити як додаткові прапори прямо: цей перший запит omits медіа формати та глави. Це отримує метадані без завантаження відео або його підписів.

### video-metadata/request.json

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


<a id="run"></a>

## 2. Захоплення та збереження метаданих

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

Запустіть з cnapshot-001 як папка виходу. У новій папці надсилає запит на метаданих і зберігає його проінформоване використання. Скрипт перевіряє успішну відповідь, що містить саме одне відео з запитаним ID перед написанням video.json.

### Python

#### Встановити в середовищі Python

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

#### video-metadata/metadata.py

```python
import argparse
import getpass
import json
import os
import re
from datetime import datetime, timezone
from pathlib import Path

import requests

parser = argparse.ArgumentParser()
parser.add_argument("folder", help="New output folder, or an existing saved snapshot")
out = Path(parser.parse_args().folder)

if not out.exists():
    body = Path("request.json").read_bytes()
    request = json.loads(body)
    if (not isinstance(request, dict) or request.get("source") != "youtube_metadata"
            or not isinstance(request.get("video_id"), str)
            or not re.fullmatch(r"[A-Za-z0-9_-]{11}", request["video_id"])):
        raise SystemExit("Use youtube_metadata and an 11-character video_id, not a URL")
    key = os.environ.get("FLASHDATA_API_KEY") or getpass.getpass("FlashData API key: ")
    if not key.strip():
        raise SystemExit("An API key is required")
    out.mkdir()
    (out / "request.json").write_bytes(body)
    (out / "requested-at.txt").write_text(
        datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), encoding="utf-8"
    )
    try:
        response = requests.post(
            "https://data.flashdata.dev/v1/queries/realtime",
            headers={"X-API-Key": key, "Content-Type": "application/json",
                     "Accept": "application/json"},
            data=body, timeout=120, allow_redirects=False,
        )
    except requests.RequestException:
        raise SystemExit(f"Request interrupted. Keep {out} and check History before retrying.")
    (out / "result.json").write_bytes(response.content)
    (out / "response-headers.txt").write_text(
        "\n".join(f"{k}: {v}" for k, v in response.headers.items()), encoding="utf-8"
    )
    (out / "http-status.txt").write_text(str(response.status_code), encoding="utf-8")
else:
    print(f"Reading saved response from {out}; no API call.")

if not (out / "http-status.txt").exists():
    raise SystemExit("Incomplete attempt. Keep the folder and check History before retrying.")
status = (out / "http-status.txt").read_text().strip()
if status != "200":
    raise SystemExit(f"HTTP {status}: inspect {out}/result.json and response-headers.txt")
try:
    data = json.loads((out / "result.json").read_bytes())
except ValueError:
    raise SystemExit("Invalid JSON; inspect the saved result.json")
request = json.loads((out / "request.json").read_bytes())
if not isinstance(data, dict) or data.get("source") != "youtube_metadata" or data.get("status") != "done":
    raise SystemExit("Metadata request did not finish successfully; inspect result.json")
videos = data.get("results")
if (not isinstance(videos, list) or len(videos) != 1 or not isinstance(videos[0], dict)
        or videos[0].get("videoId") != request["video_id"]):
    raise SystemExit("Expected one metadata object matching the requested video_id")
record = {
    "request": request,
    "requested_at": (out / "requested-at.txt").read_text().strip(),
    "usage": data.get("usage"), "result_file": "result.json",
}
for filename, value in (("video.json", videos[0]), ("record.json", record)):
    (out / filename).write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
print(f"Saved {videos[0]['videoId']} to {out}/video.json")
```

#### Запуск відео-метаданих/

```bash
python metadata.py snapshot-001
```


### Bash

#### Перевірити інструменти

```bash
curl --version
jq --version
```

#### video-metadata/metadata.sh

```bash
#!/usr/bin/env bash
set -euo pipefail
out="${1:?Usage: bash metadata.sh OUTPUT_FOLDER}"

if [[ ! -e "$out" ]]; then
  jq -e '.source == "youtube_metadata" and
    (.video_id | if type == "string" then length == 11 and test("^[A-Za-z0-9_-]{11}$")
     else false end)' request.json > /dev/null
  if [[ -z "${FLASHDATA_API_KEY:-}" ]]; then
    read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
    printf '\n'
  fi
  : "${FLASHDATA_API_KEY:?An API key is required}"
  mkdir -- "$out"
  cp request.json "$out/request.json"
  date -u +'%Y-%m-%dT%H:%M:%SZ' > "$out/requested-at.txt"
  curl --fail-with-body --silent --show-error --max-time 120 \
    --request POST 'https://data.flashdata.dev/v1/queries/realtime' \
    --header "X-API-Key: $FLASHDATA_API_KEY" \
    --header 'Content-Type: application/json' --header 'Accept: application/json' \
    --data-binary "@$out/request.json" \
    --dump-header "$out/response-headers.txt" --output "$out/result.json" \
    --write-out '%{http_code}' > "$out/http-status.txt" || {
      printf 'Request failed. Keep %s and inspect its saved files before retrying.\n' "$out" >&2
      exit 1
    }
else
  printf 'Reading saved response from %s; no API call.\n' "$out"
fi

if [[ ! -f "$out/http-status.txt" ]] || [[ "$(cat "$out/http-status.txt")" != 200 ]]; then
  printf 'Incomplete or failed attempt. Inspect the saved files and History before retrying.\n' >&2
  exit 1
fi
video=$(jq -e --slurpfile request "$out/request.json" '
  if .source != "youtube_metadata" or .status != "done"
  then error("Expected a successful youtube_metadata response") else . end
  | .results
  | if type != "array" then error("Expected a metadata array")
    elif length != 1 then error("Expected exactly one video") else .[0] end
  | if type != "object" then error("Expected a metadata object")
    elif .videoId != $request[0].video_id then error("Returned videoId does not match the request")
    else . end' "$out/result.json")
printf '%s\n' "$video" > "$out/video.json"
jq --slurpfile request "$out/request.json" \
  --arg requested_at "$(tr -d '\r\n' < "$out/requested-at.txt")" \
  '{request: $request[0], requested_at: $requested_at, usage, result_file: "result.json"}' \
  "$out/result.json" > "$out/record.json"
printf 'Saved %s to %s/video.json\n' "$(jq -r .videoId "$out/video.json")" "$out"
```

#### Запуск відео-метаданих/

```bash
bash metadata.sh snapshot-001
```



<a id="output"></a>

## 3. Читати відеозапис

Збережено відео ID> до snapshot-001/video.json. Читання файлу для об’єкта повного метаданих та record.json для конкретного поданого запиту requested_at і використання. Читання цих файлів не викликає виклику API.

### Python

#### Читати локально

```bash
python -m json.tool snapshot-001/video.json
python -m json.tool snapshot-001/record.json
```


### Bash

#### Читати локально

```bash
cat snapshot-001/video.json
cat snapshot-001/record.json
```



<a id="expected"></a>

### Приклад виходу

Аббревіатура, ілюстративний video.json. Повернуті значення варіюватися. Скрипт зберігає всі доступні поля, включаючи значення null, і зберігає повну відповідь в result.json.

#### video-metadata/snapshot-001/video.json

```json
{
  "videoId": "FUfGcZ092b0",
  "title": "Example research video",
  "channel": "Example channel",
  "duration": 120,
  "viewCount": null,
  "transcriptLanguages": [
    "en"
  ]
}
```


<a id="fields"></a>

### Читати поля

| Поле | Використовуйте його для |
| --- | --- |
| videoId | Стійкий ключ запису. Ім'я та імена каналів можуть змінюватися. |
| duration | Довжина відео в секундах. Збережіть відсутні або null значення як невідомі. |
| viewCount / likeCount / commentCount | Кількість доступних у цьому знімку. Нул або не відхилений, нульовий - це звітний рахунок. |
| transcriptLanguages | Кандидатські мовні коди для окремого запиту на заставу. Цей список не визначає, чи є автоматичним або ручним. |


<a id="reuse"></a>

## Запобігти знімку або запитати інший

Запустіть таку ж команду, щоб відновити video.json і record.json від збереженої відповіді. Не потрібен ключ або мережевий запит. Редагування верхнього рівня request.json не змінює вхід, що зберігається з оснащенням Snapshot-001.

### Python

#### Запобігання збережених даних

```bash
python metadata.py snapshot-001
```


### Bash

#### Запобігання збережених даних

```bash
bash metadata.sh snapshot-001
```


- [Заощаджувати та повторно використовувати результати](https://flashdata.dev/uk/docs/guides/save-results/reference.md)

<a id="chapters"></a>

### Український переклад І. Огієнка

Щоб включити главні маркери, замініть request.json з цією версією і використовуйте нову папку виведення. include_chapters: true повертає глави при наявності; він не створює їх. Як include_chapters і include_formats за замовчуванням до true при пропущенні.

#### video-metadata/request.json

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

#### Python

##### Запитати ще знімок

```bash
python metadata.py snapshot-002
```


#### Bash

##### Запитати ще знімок

```bash
bash metadata.sh snapshot-002
```


- [Метадані та параметри](https://flashdata.dev/uk/docs/sources/youtube_metadata/reference.md)

<a id="recover"></a>

## Якщо метадані є недоступними

| Що відбулося | Що робити |
| --- | --- |
| Інвалід video_id | Використовуйте тільки 11-character ID. Перед відправкою запиту на вказану перевірку припиняється. |
| Приватне, видалене або обмежене відео | Зберігати про це ID. Перевірити помилку джерела і вибрати доступне відео замість багаторазового подання одного елемента. |
| Empty результат або інший videoId | Скрипка зупиняється без написання video.json. Перевірте збережений запит та відповідь перед використанням запису. |
| Місячні підрахунки, глави або мови | Успішно збігаються з даними метаданих. Збереження недоступних полів, не заповнювати їх придуманими значеннями. |
| 401 / 403 / 402 | Перевірити ключ, дозвіл youtube_metadata і баланс, відповідно, перед новою спробою. |
| 429 | Читати Retry-After в response-headers.txt і чекати. Скрипт ніколи не відредагує автоматично. |
| Час, 5xxx, недійсний JSON або неповна папка | Зберігайте спробу і перевірте History до подачі знову. Відновити свою папку не потрібно. |

### Python

Заощаджуйте inspect_metadata.py beside metadata.py, потім запустіть його.

#### video-metadata/inspect_metadata.py

```python
from pathlib import Path

for name in ("http-status.txt", "response-headers.txt", "result.json"):
    path = Path("snapshot-001") / name
    print(f"--- {name} ---")
    print(path.read_text(encoding="utf-8", errors="replace") if path.exists() else "Not saved")
```

#### Опитування локально

```bash
python inspect_metadata.py
```


### Bash

#### Опитування локально

```bash
for name in http-status.txt response-headers.txt result.json; do
  printf '\n--- %s ---\n' "$name"
  if [[ -f "snapshot-001/$name" ]]; then cat "snapshot-001/$name"; else printf 'Not saved\n'; fi
done
```


- [Історія запиту](https://flashdata.dev/app/jobs)
- [Помилки й коди стану](https://flashdata.dev/uk/docs/errors/reference.md)

<a id="next"></a>

## Використовуйте відео у вашому робочому процесі

Використовуйте videoId, щоб приєднатися до цього запису до результатів пошуку або даних. Для спійманого вмісту, отримання певного треку заголовка. Для декількох IDs використовуйте керівництво збагачення. Це окремі запити з власними дозволами та зарядами.

- [Зберігати часові підписи](https://flashdata.dev/uk/docs/guides/timestamped-captions-recipe/reference.md)
- [Збагачений відео IDs](https://flashdata.dev/uk/docs/guides/enrich-youtube-videos/reference.md)
