# Ambil metadata satu video

Putar video YouTube ID ke dalam catatan tersimpan judul, saluran, durasi dan jumlah yang tersedia. Simpan respon asli dan penggunaan di sampingnya.

Referensi kanonikal: https://flashdata.dev/id/docs/guides/video-metadata-recipe
Diulang: 2026-11-05 oleh FlashData

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

## Sebelum Anda mulai

Gunakan kunci dengan izin youtube_metadata dan kredit yang tersedia. Pilih Python 3.10+ dengan permintaan, atau Bash dengan cURL 7.76+ dan jq. Hidup Windows, gunakan Git Bash untuk Bash versi.

- [Dapatkan API key](https://flashdata.dev/app/api-keys)
- [Uji coba agen dan penautan akun](https://flashdata.dev/id/docs/guides/agent-onboarding/reference.md)
- [Kredit dan harga](https://flashdata.dev/id/docs/guides/credits-and-billing/reference.md)

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

## 1. Pilih satu video

Buat folder video- metadata dan simpan request.json di sana. Buka terminal pada folder itu. Ganti video_id dengan 11-character ID dari pengawasan. URL atau YouTube Search hasil; jangan lulus penuh URL.

Set kedua tanda opsional secara eksplisit: permintaan pertama ini menghilangkan format media dan bab. Ia mengambil metadata tanpa mengunduh video atau takarannya.

### video-metadata/request.json

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


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

## 2. Ambil dan simpan metadata

Pilih satu versi dan simpan script di samping request.json. Tertulis FLASHDATA_API_KEY atau meminta kunci Anda pada prompt tersembunyi. Agen harus memuat variabel lingkungan dari toko rahasia mereka.

Jalankan dengan snapshot - 001 sebagai folder keluaran. Folder baru mengirim satu kuiri metadata dan menyimpan penggunaan yang dilaporkan. Cek skrip untuk respon sukses berisi satu video dengan ID yang diminta sebelum menulis video.json.

### Python

#### Pasang di lingkungan Python Anda

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

#### Jalankan dari video-metadata /

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


### Bash

#### Periksa alat-alatmu

```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"
```

#### Jalankan dari video-metadata /

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



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

## 3. Baca rekaman video

Cetakan sukses disimpan < video ID > ke snapshot-001/video.json. Baca berkas itu untuk objek metadata lengkap dan record.json untuk permintaan yang diajukan secara tepat, requested_at dan penggunaan. Membaca berkas ini tidak membuat panggilan API.

### Python

#### Baca lokal

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


### Bash

#### Baca lokal

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



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

### Contoh keluaran

Abbreviated, illustratif video.json. Nilai dikembalikan bervariasi. Skrip mempertahankan setiap ruas yang tersedia, termasuk nilai null, dan menyimpan respon lengkap dalam 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>

### Baca bidang

| Ruas | Gunakan untuk |
| --- | --- |
| videoId | Rekor itu kunci stabil. Judul dan nama tampilan saluran dapat berubah. |
| duration | Panjang video dalam hitungan detik. Pertahankan nilai-nilai yang hilang atau null sebagai tidak diketahui. |
| viewCount / likeCount / commentCount | Menghitung tersedia dalam snapshot ini. Nuklir atau hilang tidak diketahui; nol adalah jumlah yang dilaporkan. |
| transcriptLanguages | Kode bahasa kandidat untuk permintaan judul terpisah. Daftar ini tidak mengidentifikasi apakah trek otomatis atau manual. |


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

## Gunakan lagi snapshot atau permintaan lain

Jalankan perintah yang sama untuk membangun kembali video.json dan record.json dari respon yang disimpan. Tak ada permintaan kunci atau jaringan yang diperlukan. Menyunting level atas request.json tidak mengubah masukan yang tersimpan dengan snapshot - 001.

### Python

#### Gunakan ulang data yang disimpan

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


### Bash

#### Gunakan ulang data yang disimpan

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


- [Simpan dan gunakan ulang hasil](https://flashdata.dev/id/docs/guides/save-results/reference.md)

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

### Sertakan bab yang tersedia

Untuk memasukkan penanda bab, ganti request.json dengan versi ini dan gunakan folder keluaran baru. include_chapters: true mengembalikan bab bila tersedia; ini tidak membuat mereka. Baik include_chapters maupun include_formats baku ke true ketika diabaikan.

#### video-metadata/request.json

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

#### Python

##### Meminta snapshot lain

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


#### Bash

##### Meminta snapshot lain

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


- [Bidang metadata dan opsi](https://flashdata.dev/id/docs/sources/youtube_metadata/reference.md)

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

## Jika metadata tidak tersedia

| Apa yang terjadi? | Yang perlu dilakukan |
| --- | --- |
| video_id tidak valid | Gunakan hanya karakter 11- ID. Validasi masukan berhenti sebelum mengirim permintaan. |
| Pribadi, dihapus atau video dibatasi | Simpan kegagalan untuk itu ID. Periksa kesalahan sumber dan pilih video yang dapat diakses daripada berulang kali mengirimkan item yang sama. |
| Hasil kosong atau videoId yang berbeda | Naskah berhenti tanpa menulis video.json. Inspeksi permintaan dan jawaban yang tersimpan sebelum memakai catatan. |
| Hilang jumlah, bab atau bahasa | Catatan metadata yang cocok masih bisa sukses. Pertahankan ruas yang tak tersedia sebagai tak dikenal; jangan isi dengan nilai yang ditemukan. |
| 401 / 403 / 402 | Periksa kuncinya, youtube_metadata izin dan keseimbangan, secara terhormat, sebelum usaha baru. |
| 429 | Baca Retry-After in response-headers.txt dan menunggu. Skrip tidak pernah mengulang secara otomatis. |
| Timeout, 5xx, JSON tidak valid atau sebuah folder tidak lengkap | Terus berusaha dan periksa History sebelum mengirimkan lagi. Menggunakan kembali folder tidak membuat permintaan baru. |

### Python

Simpan inspect_metadata.py di samping metadata.py, kemudian jalankan.

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

#### Inspeksi secara lokal

```bash
python inspect_metadata.py
```


### Bash

#### Inspeksi secara lokal

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


- [Meminta riwayat](https://flashdata.dev/app/jobs)
- [Kesalahan dan kode status](https://flashdata.dev/id/docs/errors/reference.md)

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

## Gunakan video dalam alur kerja Anda

Gunakan videoId untuk bergabung dengan rekaman ini ke hasil pencarian atau data. Untuk isi yang diucapkan, ambil trek judul spesifik berikutnya. Untuk beberapa IDs, gunakan panduan pengayaan. Ini adalah permintaan terpisah dengan hak mereka sendiri dan biaya.

- [Ambil taktimestamp takarir](https://flashdata.dev/id/docs/guides/timestamped-captions-recipe/reference.md)
- [Enrich video terpilih IDs](https://flashdata.dev/id/docs/guides/enrich-youtube-videos/reference.md)
