تخطَّ إلى المحتوى
AR
الحصول على مفتاح API
تصفح الوثائق

أمثلة

إسترجعوا مُقدّم فيديو واحد

حوّل شريط فيديو 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.

:: تحديد كل من العلمين الاختياريين بشكل صريح: يغفل هذا الطلب الأول أشكال الإعلام والفصول. يسترد البيانات الوصفية دون تحميل الفيديو أو أغطيته

video-metadata/request.json
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": false
  }
}

2. إجلبْ وإنقذْ البيانات الفوقيةَ

اختر نسخة واحدة واحفظ نصها بجانبها request.json. إنه يقرأ FLASHDATA_API_KEY أو يطلب مفتاحك في عجل مخفي العملاء يجب أن يحمّلون تلك البيئة المتغيّرة من متجرهم السري.

أركض مع الطلقات001 كمجلد النواتج ويرسل ملف جديد استفساراً عن البيانات الوصفية ويحتفظ باستخدامه المبلغ عنه. ويتحقق النص من استجابة ناجحة تتضمن شريط فيديو واحد بالضبط مع الرقم ID المطلوب قبل كتابة video.json.

ضع في رأسك Python البيئة
python -m pip install requests
video-metadata/metadata.py
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")
مهرب من البيانات الفيديوية/
python metadata.py snapshot-001

3. اقرأ سجل الفيديو

عند النجاح تُطبع 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.json

الناتج المثالي

Abbreviated, illustrative video.json. وتختلف القيم العائدة. ويحفظ النص كل ميدان متاح، بما في ذلك قيم null، ويحتفظ بالاستجابة الكاملة في result.json.

video-metadata/snapshot-001/video.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-001

إدراج الفصول المتاحة

يستعاض عن عبارة " علامات الفصل " بعبارة " request.json مع هذه النسخة واستخدام ملف جديد للنواتج. include_chapters: true ويعيد الفصول عندما تكون متاحة؛ ولا يخلقها. Both include_chapters and include_formats default to true when omitted.

video-metadata/request.json
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": true
  }
}
اطلبي طلقه اخرى
python metadata.py 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، ثم شغّله.

video-metadata/inspect_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")
Inspect locally
python inspect_metadata.py

استخدم الفيديو في سير عملك

الاستخدام videoId لتنضم إلى هذا السجل إلى نتائج بحثك أو مجموعة البيانات للمحتوى الحديث، استرجع مساراً محدداً للاختباء لعدة مرات IDsاستخدم دليل التخصيب وهذه طلبات منفصلة بإذنها واتهامها.