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

الأدلة

YouTube Data أفضل الممارسات

البحث عن أشرطة الفيديو ذات الصلة، واختيار مسارات التصفيق، وتجهيز تحميلات القنوات الجديدة دون تكرار العمل.

في هذه الصفحة

ابدأ بالمعلومات التي لديك بالفعل

ويجيب كل مصدر على سؤال مختلف. إكتشاف سكيب للفيديو المعروف ID أو مقبض القناة، وإثراء فقط الفيديوات التي تحتاجها مهمتك.

مهمتكالمصدرمقرر
ابحث عن فيديو عن موضوعyoutube_searchابدأ بخمسة مرشحين ثم اختاروا حسب الأهمية
تفحص فيديو معروفyoutube_metadataالحصول على اللقب والقناة والمدة ولغات الإخفاء.
Summarize or cite what was saidyoutube_transcript / youtube_captionsاختر لغة وطريق آلي أو يدوي.
تحقق من تحميلات القنوات الأخيرةyoutube_channelCompare returned IDs مع معالجتك IDs.

تقديم أمثلة على الطلب

أنقذوا كل واحد JSON الجسم الذي يستخدم اسم ملفه المثبت وتستخدم شركة Python مُساعدة query.py أدناه؛ ويمكن أن تقدم شركة cURL نفس الملف. إستخدم مفتاحاً مع تصريحات المصدر التي تحتاجها و الفضلات المتاحة وكل عرض هو سؤال واحد، بغض النظر عن عدد الفيديو المعادة.

Python 3.10+. (د) تركيب الطلبات مرة واحدة، باستثناء query.py أدناه، ثم استخدام القيادة إلى جانب كل طلب. ويعاد استخدام النواتج القائمة؛ ويتطلب تغيير المدخلات اسم ملف جديد للنواتج.

تثبيت
python -m pip install requests

جهزوا API المفتاح

إعادة استخدام FLASHDATA_API_KEY من محطتك أو متجرك السري. و إلا أدخل المفتاح مستخدماً واحداً مخفياً في الأسفل أبقها في العملية التي تدير هذه الأمثلة.

حدد المفتاح
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY

Save query.py for the Python examples

أنشئ query.py في مجلد عمل جديد وانسخ الكود الكامل أدناه إليه. احفظ ملفات طلب JSON وسكربتات Python الأخرى في هذا المجلد، وشغّل جميع الأوامر منه.

query.py
# query.py — submit a saved request once, then reuse its response.
import json
import os
import sys
from pathlib import Path
import requests

if len(sys.argv) != 3:
    raise SystemExit("Usage: python query.py REQUEST.json RESULT.json")
payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8-sig"))
output = Path(sys.argv[2])
marker = output.with_name(output.name + ".request.json")
receipt = output.with_name(output.name + ".http.json")
if marker.exists():
    if json.loads(marker.read_text()) != payload:
        raise SystemExit("Changed request: choose a new output filename.")
    if not output.exists() or not receipt.exists():
        raise SystemExit("Outcome unknown: check History before resubmitting.")
    saved = json.loads(receipt.read_text())
    if saved["status"] != 200 or json.loads(output.read_text(encoding="utf-8")).get("status") != "done":
        raise SystemExit(f"Saved request failed or incomplete; Retry-After: {saved['retry_after']}. Inspect {output}.")
    print(f"Read the saved {output}; no new query submitted.")
    raise SystemExit(0)
if output.exists():
    raise SystemExit("Output already exists. Read it or choose a new filename.")
key = os.environ["FLASHDATA_API_KEY"]
with marker.open("x", encoding="utf-8") as file:
    json.dump(payload, file)
response = requests.post("https://data.flashdata.dev/v1/queries/realtime",
                         headers={"X-API-Key": key}, json=payload,
                         timeout=70, allow_redirects=False)
output.write_text(response.text, encoding="utf-8")
receipt.write_text(json.dumps({"status": response.status_code,
                               "retry_after": response.headers.get("Retry-After")}), encoding="utf-8")
if response.status_code != 200:
    raise SystemExit(f"HTTP {response.status_code}; Retry-After: {response.headers.get('Retry-After')}")
if response.json().get("status") != "done":
    raise SystemExit(f"Inspect {output} and History before retrying.")
print(json.dumps({"saved": str(output), "usage": response.json().get("usage")}, indent=2))

اعثر على المرشحين قبل جلب التفاصيل

ويستبعد مرشح الفيديو أنواع النتائج الأخرى؛ ويضيق العنوان الفرعي الاكتشافات إلى أشرطة الفيديو التي تحتوي على أغطية. إنه لا يختار لغة الإخفاء أو يضمن المسار الذي تحتاجه انقذوا discover-request.json.

discover-request.json
{
  "source": "youtube_search",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 5,
    "filters": {
      "type": "video",
      "subtitles": true
    }
  }
}
Submit once with query.py
python query.py discover-request.json search.json

يُختار حسب الأهمية، وليس أول ID

احفظ candidates.py بجانب query.py وsearch.json، ثم شغّله من ذلك المجلد. يحافظ على ترتيب البحث ويحذف معرّفات الفيديو المكررة. افحص العناوين والقنوات والمدد، ثم انسخ المعرّف المختار إلى الطلب التالي. القائمة الفارغة تعني بحثًا مكتملًا دون مرشحين.

candidates.py
# candidates.py — read a saved response; no API calls.
import json
import re
from pathlib import Path

data = json.loads(Path("search.json").read_text(encoding="utf-8"))
if data.get("status") != "done":
    raise SystemExit("Search did not complete; inspect search.json.")
candidates, seen = [], set()
for item in (data.get("results") or [{}])[0].get("results", []):
    video_id = item.get("videoId", "")
    if not re.fullmatch(r"[A-Za-z0-9_-]{11}", video_id) or video_id in seen:
        continue
    seen.add(video_id)
    candidates.append({"videoId": video_id, "title": item.get("title"),
                       "channel": item.get("channel"), "duration": item.get("duration"),
                       "url": "https://www.youtube.com/watch?v=" + video_id})
Path("candidates.json").write_text(json.dumps(candidates, indent=2), encoding="utf-8")
print(json.dumps(candidates, indent=2))
اقرأ البحث المنقذ
python candidates.py

لا يتسع إلا إذا كانت القائمة القصيرة غير كافية

دعم البحث القياسي max_results حتى 20. وللجمع على نطاق أوسع، ينتقل إلى youtube_search_extended، الذي يدعم حتى الرقم 700، وله تسعير منفصل. وهذا المثال يطلب من شركة 50؛ والتحقق مما إذا كانت نتائجك الأولى مفيدة قبل أن تثريها كلها.

extended-request.json
{
  "source": "youtube_search_extended",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 50,
    "filters": {
      "type": "video"
    }
  }
}
اركض مرة واحدة
python query.py extended-request.json extended.json

إسترجع فقط البيانات الفوقية التي تحتاجها سمتك

يستعاض عن العينة video_id مع اختيارك ID. أبقوا صيغ و فصولاً معوقة لبطاقة فيديو بسيطة أو لفحص لغة الإقفال Enable include_chapters for an outline, or include_formats when choose a media format.

metadata-request.json
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": false
  }
}
Submit once with query.py
python query.py metadata-request.json metadata.json

فحص اللغات المتاحة

Read results[0].transcriptLanguages before choose captions. والصيغ والفصول واللغات هي ميادين على الجسم المرئي المعاد؛ وسجل الاستخدام يعود إلى الرد الخارجي.

Settingإستخدمه
languageرمز من transcriptLanguages، مثل en أو zh-Hans. لا تميّز هذه القائمة بين المسارات اليدوية والتلقائية.
auto: trueمسار متولد آلياً
auto: falseطريق قائم يدوياً لا يوجد أي تداعيات بين نوعي المسار
اقرأ metadata.json ; لا يوجد أي استفسار
python -m json.tool metadata.json

اختيار اللغة والتتبع بشكل صريح

استخدم نفس الشيء video_id كما طلبت البيانات الوصفية وتغيّر لغتك و آليّة لمواءمة المسار المختار youtube_transcript التقصير إلى auto: true; youtube_captions التقصير إلى auto: false. كلاهما إسترجعوا الأصفاد الحالية وليس الكلام إلى النص

captions-request.json
{
  "source": "youtube_transcript",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": true
  }
}
Submit once with query.py
python query.py captions-request.json captions.json

أبقوا الزمان مع الأدلة

احفظ cite-segments.py بجانب captions.json وشغّله من ذلك المجلد. استخدم results[0].segments للاستشهاد: start وend بالثواني. احتفظ بـ languageCode وisAutoGenerated مع النص. يفيد fullText في القراءة لكنه لا يحل محل توقيت المقاطع. إذا غاب المسار المختار، فسجّل الفجوة قبل تقرير جدوى استعلام آخر.

cite-segments.py
import json
from pathlib import Path

response = json.loads(Path("captions.json").read_text(encoding="utf-8"))
if response.get("status") != "done":
    raise SystemExit("Inspect captions.json before continuing.")
track = (response.get("results") or [{}])[0]
if not track.get("segments"):
    raise SystemExit("No caption evidence was returned.")
for segment in track["segments"][:3]:
    url = f"https://www.youtube.com/watch?v={track['videoId']}&t={int(segment['start'])}s"
    print(segment["text"], url)
اقرأوا اسطوانات منقذة لا API اتصلي
python cite-segments.py

تجهيز أشرطة فيديو جديدة فقط من قناة معروفة

استخدم معرّف قناة وحدًا مضبوطًا لـ video_limit بقيمة 1–100. results[0].videos هي القائمة الحديثة العائدة؛ أما videoCount فهو من بيانات القناة الوصفية وليس عدد العناصر العائدة. اختر حدًا وجدولًا يغطيان التحميلات التي تريد مراقبتها.

channel-request.json
{
  "source": "youtube_channel",
  "handle": "@TED",
  "params": {
    "video_limit": 10
  }
}
Submit once with query.py
python query.py channel-request.json channel.json

حافظوا على سؤلكم ونقطه تفتيش

احفظ channel-queue.py بجانب query.py وchannel.json وشغّله من ذلك المجلد. شغّله دون معاملات لإنشاء new-ids.json، ثم عالج تلك المعرّفات واحفظ أدلتها. شغّل --commit فقط بعد نجاح جميع المعرّفات في الطابور؛ ويترك الفشل نقطة الاستئناف دون تغيير. استخدم دليلًا لكل قناة وعاملًا واحدًا لهذا المثال.

channel-queue.py
# channel-queue.py — plan first; commit only after every queued video is processed.
import json
import re
import sys
from pathlib import Path

checkpoint = Path("processed-ids.json")
processed = set(json.loads(checkpoint.read_text()) if checkpoint.exists() else [])
queue = Path("new-ids.json")
if sys.argv[1:] == ["--commit"]:
    processed.update(json.loads(queue.read_text()))
    temporary = checkpoint.with_suffix(".tmp")
    temporary.write_text(json.dumps(sorted(processed)), encoding="utf-8")
    temporary.replace(checkpoint)
    queue.unlink()
    print("Checkpoint saved.")
elif sys.argv[1:]:
    raise SystemExit("Usage: python channel-queue.py [--commit]")
else:
    data = json.loads(Path("channel.json").read_text(encoding="utf-8"))
    if data.get("status") != "done":
        raise SystemExit("Channel query did not complete.")
    ids = dict.fromkeys(video.get("videoId", "") for video in
                        (data.get("results") or [{}])[0].get("videos", []))
    new = [value for value in ids if re.fullmatch(r"[A-Za-z0-9_-]{11}", value)
           and value not in processed]
    if queue.exists() and json.loads(queue.read_text()) != new:
        raise SystemExit("Finish the existing queue before replacing it.")
    queue.write_text(json.dumps(new, indent=2), encoding="utf-8")
    print(json.dumps(new, indent=2))
تخطيط → معالجة → تثبيت النتائج
python channel-queue.py
# Process every ID in new-ids.json and save its result first.
python channel-queue.py --commit

ابدأي بفحص القناة الجديدة عمداً

مساعد الإستفسار يعيد إستجابة منقذة وللتحقق المقرر التالي، استخدم اسم ملف جديد للنتائج، وفتشه، ثم نسخة من الرد المستكمل على channel.json للخطوة التي طرحتها. استمر processed-ids.json بين الركضات هذه القائمة الأخيرة ليست تصديراً كاملاً أو مجرى أحداث.

الشيك التالي: اختيار اسم ملف جديد
python query.py channel-request.json channel-next.json
بعد التأكد من الوضع
python -c "from shutil import copyfile; copyfile('channel-next.json', 'channel.json')"

استخدام الاقتراحات لتحسين الاستفسار

Suggestions return wordss in results[0], not video records. (أ) اختيار عبارة مفيدة وتقديم طلب منفصل من شركة youtube_search. جهزي اللغة والمنطقة للجماهير التي تبحثين عنها

suggestions-request.json
{
  "source": "youtube_suggestions",
  "query": "battery recycling",
  "params": {
    "language": "en",
    "region": "US"
  }
}
Submit once with query.py
python query.py suggestions-request.json suggestions.json

بطاقات الترخيص المسروقة دون معاملتها كإذن

يعيد youtube_trainability وسم ترخيص الفيديو. تقابل permitted: ["all"] وسم Creative Commons؛ وتشمل ["none"] أيضًا غياب بيانات الترخيص. احتفظ بمعرّف الفيديو واستجابة المصدر وتاريخ الاسترجاع. لا يمنح هذا الوسم حقوق التنزيل أو إعادة الاستخدام أو التدريب.

license-request.json
{
  "source": "youtube_trainability",
  "video_id": "FUfGcZ092b0"
}
Submit once with query.py
python query.py license-request.json license.json

يَدْفعُ العملَ للتطبيقاتِ والوكلاءِ

المادةالتنفيذ
اختيار قبل الإثراءلمهمة موضوعية: بحث واحد، واحد مختار من البيانات الوصفية للفيديو، وواحد من اختيار مسار التصفيق. افرض ميزانية النداء في تطبيقك وثمن كل مصدر على حدة
إعادة استخدام المدخلات الفعليةMetadata: video ID + options. Captions: video ID + language + track. وتحتاج طلقات القناة أيضا إلى وقت استرجاع أو تشغيل ID.
وقف الأدلة المفقودةلا تُعيدي إكتشاف فارغ أو تُغيري مسارات التصفيق بصمت. إرجعْ الفجوةَ لذا المستعملِ أَو تدفقِ العملِ يُمْكِنُ أَنْ يَختارَ الإجراءَ التاليَ.
الاستخدام الاحتياطي وفشل العملاحفظ usage مع الاستجابات الناجحة. عند 429، التزم بـ Retry-After؛ وبعد إرسال غير مؤكد افحص History قبل استعلام مدفوع آخر.