تصفح الوثائق
أمثلة
حوّل شريط فيديو YouTube ID إلى سجل منقذ لقبها وقناتها ومدتها وحساباتها المتاحة. أبقوا الرد الأصلي والإستعمال بجانبه.
في هذه الصفحة
قبل أن تبدأ
استخدم مفتاحًا بصلاحية youtube_metadata ورصيد متاح. اختر Python 3.10+ مع requests أو Bash مع cURL 7.76+ وjq. على Windows، استخدم Git Bash لنسخة Bash.
1. اختر شريط فيديو واحد
إنشاء ملف فيديو - ميثاداتا وإنقاذ request.json هناك افتح محطة طرفية في ذلك الملف. يستعاض عن video_id بالرمز 11-character ID من ساعة URL أو نتيجة YouTube Search؛ ولا تعبر عن الرقم الكامل URL.
:: تحديد كل من العلمين الاختياريين بشكل صريح: يغفل هذا الطلب الأول أشكال الإعلام والفصول. يسترد البيانات الوصفية دون تحميل الفيديو أو أغطيته
{
"source": "youtube_metadata",
"video_id": "FUfGcZ092b0",
"params": {
"include_formats": false,
"include_chapters": false
}
}2. إجلبْ وإنقذْ البيانات الفوقيةَ
اختر نسخة واحدة واحفظ نصها بجانبها request.json. إنه يقرأ FLASHDATA_API_KEY أو يطلب مفتاحك في عجل مخفي العملاء يجب أن يحمّلون تلك البيئة المتغيّرة من متجرهم السري.
أركض مع الطلقات001 كمجلد النواتج ويرسل ملف جديد استفساراً عن البيانات الوصفية ويحتفظ باستخدامه المبلغ عنه. ويتحقق النص من استجابة ناجحة تتضمن شريط فيديو واحد بالضبط مع الرقم ID المطلوب قبل كتابة video.json.
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. اقرأ سجل الفيديو
عند النجاح تُطبع Saved <video ID> to snapshot-001/video.json. اقرأ ذلك الملف للحصول على كائن البيانات الوصفية كاملًا، وrecord.json للاطلاع على الطلب المرسل وrequested_at والاستخدام. لا تؤدي قراءة هذه الملفات إلى أي استدعاء API.
python -m json.tool snapshot-001/video.json
python -m json.tool snapshot-001/record.jsoncat snapshot-001/video.json
cat snapshot-001/record.jsonالناتج المثالي
Abbreviated, illustrative video.json. وتختلف القيم العائدة. ويحفظ النص كل ميدان متاح، بما في ذلك قيم null، ويحتفظ بالاستجابة الكاملة في result.json.
{
"videoId": "FUfGcZ092b0",
"title": "Example research video",
"channel": "Example channel",
"duration": 120,
"viewCount": null,
"transcriptLanguages": [
"en"
]
}اقرأ الحقول
| الميدان | إستخدمه |
|---|---|
| videoId | الرقم القياسي مستقر يمكن تغيير أسماء العنوان والقنوات. |
| duration | طول الفيديو في ثواني الحافظة مفقودة null قيم غير معروفة |
| viewCount / likeCount / commentCount | الكونتات متاحة في هذه الصورة ولا يعرف النواة أو المفقودة؛ ولا يبلَّغ عن أي عدد. |
| transcriptLanguages | رموز اللغات المرشحة لطلب الإقفال المستقل. ولا تحدد هذه القائمة ما إذا كان المسار آليا أو يدويا. |
إعادة استخدام الطلقة أو طلب آخر
أديري نفس القيادة لإعادة البناء video.json و record.json من الاستجابة الموفرة. ولا يلزم تقديم أي طلب رئيسي أو من الشبكة. ولا يغير التحرير على المستوى الأعلى للزدحام المغناطيسي (request.json) المدخلات المخزنة بالقطعة - 001.
python metadata.py snapshot-001bash metadata.sh snapshot-001إدراج الفصول المتاحة
يستعاض عن عبارة " علامات الفصل " بعبارة " request.json مع هذه النسخة واستخدام ملف جديد للنواتج. include_chapters: true ويعيد الفصول عندما تكون متاحة؛ ولا يخلقها. Both include_chapters and include_formats default to true when omitted.
{
"source": "youtube_metadata",
"video_id": "FUfGcZ092b0",
"params": {
"include_formats": false,
"include_chapters": true
}
}python metadata.py snapshot-002bash metadata.sh snapshot-002إذا كانت البيانات الوصفية غير متاحة
| ماذا حدث؟ | الإجراء المطلوب |
|---|---|
| Invalid video_id | استخدم فقط 11-منتج ID. يتوقف التحقق من المدخلات قبل إرسال الطلب. |
| شريط فيديو خاص أو مشطوب أو مقيد | حافظ على الفشل ID. تحقق من خطأ المصدر واختيار شريط فيديو متاح بدلاً من تقديم نفس البند مراراً. |
| نتيجة فارغة أو مختلفة من طراز videoId | النص يتوقف بدون كتابة video.json. فحص الطلب المنقذ ورده قبل استخدام السجل. |
| عدد المفقودين أو الفصول أو اللغات | سجل مطابق للبيانات الفوقية يمكن أن يكون ناجحاً :: الحفاظ على الحقول غير المتاحة على أنها غير معروفة؛ ولا تملئها بالقيم المخترعة. |
| 401 / 403 / 402 | تحقق من المفتاح، إذن وتوازن youtube_metadata، على التوالي، قبل محاولة جديدة. |
| 429 | اقرأ Retry-After في response-headers.txt وانتظر. النص لا يتراجع تلقائياً |
| وقت مستقطع، 5x، غير صحيح JSON أو ملف غير كامل | حافظوا على المحاولة وتحققوا History قبل أن تقدم مرة أخرى. إعادة استخدام ملفها لا تقدم أي طلب جديد. |
احفظ inspect_metadata.py بجانب metadata.py، ثم شغّله.
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
doneاستخدم الفيديو في سير عملك
الاستخدام videoId لتنضم إلى هذا السجل إلى نتائج بحثك أو مجموعة البيانات للمحتوى الحديث، استرجع مساراً محدداً للاختباء لعدة مرات IDsاستخدم دليل التخصيب وهذه طلبات منفصلة بإذنها واتهامها.