Documentatie bekijken
Voorbeelden
Zet een YouTube video ID om in een opgeslagen record van zijn titel, kanaal, duur en beschikbare nummers. Houd de oorspronkelijke reactie en het gebruik ernaast.
Op deze pagina
Voordat u begint
Gebruik een sleutel met youtube_metadata toestemming en beschikbare credits. Kies Python 3.10+ met verzoeken, of Bash met cURL 7.76+ en jq. Gebruik Git Bash op Windows voor de Bash versie.
1. Kies één video
Maak een video-metadatamap en sla request.json daar op. Open een terminal in die map. Vervang video_id door het 11-karakter ID van een horloge URL of een YouTube Search-resultaat; passeer niet het volledige URL.
Stel beide optionele vlaggen expliciet in: dit eerste verzoek laat mediaformaten en hoofdstukken weg. Het haalt metadata op zonder de video of de bijschriften te downloaden.
{
"source": "youtube_metadata",
"video_id": "FUfGcZ092b0",
"params": {
"include_formats": false,
"include_chapters": false
}
}2. De metadata ophalen en opslaan
Kies één versie en sla het script op naast request.json. Het leest FLASHDATA_API_KEY of vraagt om uw sleutel op een verborgen prompt. Agenten moeten die omgevingsvariabele uit hun geheime winkel laden.
Uitvoeren met snapshot-001 als uitvoermap. Een nieuwe map stuurt een metadata-query en slaat het gerapporteerde gebruik op. Het script controleert op een succesvol antwoord met precies één video met de gevraagde ID voordat u video.json schrijft.
python -m pip install requestsimport 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")
python metadata.py snapshot-001curl --version
jq --version#!/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 metadata.sh snapshot-0013. Lees het videorecord
Opgeslagen <video ID> naar snapshot-001/video.json. Lees dat bestand voor het volledige metadata object en record.json voor het exacte ingediende verzoek, requested_at en gebruik. Het lezen van deze bestanden maakt geen API oproep.
python -m json.tool snapshot-001/video.json
python -m json.tool snapshot-001/record.jsoncat snapshot-001/video.json
cat snapshot-001/record.jsonVoorbeelduitvoer
Afgekort, illustratief video.json. Teruggegeven waarden variëren. Het script bewaart elk beschikbaar veld, inclusief null waarden, en houdt de volledige respons in result.json.
{
"videoId": "FUfGcZ092b0",
"title": "Example research video",
"channel": "Example channel",
"duration": 120,
"viewCount": null,
"transcriptLanguages": [
"en"
]
}Lees de velden
| Veld | Gebruik het voor |
|---|---|
| videoId | Het record is stabiel. Titel- en kanaalnamen kunnen veranderen. |
| duration | Videolengte in seconden. Bewaar ontbrekende of null-waarden als onbekend. |
| viewCount / likeCount / commentCount | Telt beschikbaar in deze snapshot. Null of ontbrekende is onbekend; nul is een gerapporteerde telling. |
| transcriptLanguages | Kandidaattaalcodes voor een afzonderlijk bijschriftverzoek. Deze lijst geeft niet aan of een track automatisch of handmatig is. |
Hergebruik de snapshot of vraag een andere
Voer hetzelfde commando uit om video.json en record.json te herbouwen vanuit het opgeslagen antwoord. Er is geen sleutel of netwerkverzoek nodig. Het bewerken van de top-level request.json verandert de invoer die is opgeslagen met snapshot-001 niet.
python metadata.py snapshot-001bash metadata.sh snapshot-001Beschikbare hoofdstukken toevoegen
Om hoofdstukmarkeringen op te nemen, vervang request.json met deze versie en gebruik een nieuwe uitvoermap. include_chapters: true geeft hoofdstukken terug indien beschikbaar; het maakt ze niet aan. Zowel include_chapters als include_formats standaard naar true indien weggelaten.
{
"source": "youtube_metadata",
"video_id": "FUfGcZ092b0",
"params": {
"include_formats": false,
"include_chapters": true
}
}python metadata.py snapshot-002bash metadata.sh snapshot-002Als metadata niet beschikbaar zijn
| Wat is er gebeurd? | Wat je moet doen |
|---|---|
| Ongeldige video_id | Gebruik alleen het 11-karakter ID. De invoervalidatie stopt voordat het verzoek wordt verzonden. |
| Privé-, verwijderde of beperkte video | Houd de storing voor die ID. Controleer de bronfout en kies een toegankelijke video in plaats van herhaaldelijk hetzelfde item in te dienen. |
| Leeg resultaat of een andere videoId | Het script stopt zonder video.json te schrijven. Controleer het opgeslagen verzoek en antwoord voordat u de record gebruikt. |
| Ontbrekende nummers, hoofdstukken of talen | Een overeenkomstige metadata record kan nog steeds succesvol zijn. Bewaar niet-beschikbare velden als onbekend; vul ze niet met uitgevonden waarden. |
| 401 / 403 / 402 | Controleer de sleutel, youtube_metadata permissie en balans, respectievelijk, voordat een nieuwe poging. |
| 429 | Lees Retry-After in response-headers.txt en wacht. Het script wordt nooit automatisch opnieuw gebruikt. |
| Timeout, 5xx, ongeldige JSON of een onvolledige map | Houd de poging en controleer History alvorens opnieuw te verzenden. Het hergebruik van de map maakt geen nieuwe aanvraag. |
Bewaar inspect_metadata.py naast metadata.py, voer het dan uit.
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")python inspect_metadata.pyfor 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
doneGebruik de video in je workflow
Gebruik videoId om deze record aan te sluiten bij uw zoekresultaten of dataset. Voor gesproken inhoud, haal een specifieke titel track volgende. Gebruik voor meerdere IDs de verrijkingsgids. Dit zijn afzonderlijke verzoeken met hun eigen permissies en kosten.