تصفح الوثائق
الأدلة
البحث عن أشرطة الفيديو ذات الصلة، واختيار مسارات التصفيق، وتجهيز تحميلات القنوات الجديدة دون تكرار العمل.
في هذه الصفحة
ابدأ بالمعلومات التي لديك بالفعل
ويجيب كل مصدر على سؤال مختلف. إكتشاف سكيب للفيديو المعروف ID أو مقبض القناة، وإثراء فقط الفيديوات التي تحتاجها مهمتك.
| مهمتك | المصدر | مقرر |
|---|---|---|
| ابحث عن فيديو عن موضوع | youtube_search | ابدأ بخمسة مرشحين ثم اختاروا حسب الأهمية |
| تفحص فيديو معروف | youtube_metadata | الحصول على اللقب والقناة والمدة ولغات الإخفاء. |
| Summarize or cite what was said | youtube_transcript / youtube_captions | اختر لغة وطريق آلي أو يدوي. |
| تحقق من تحميلات القنوات الأخيرة | youtube_channel | Compare returned IDs مع معالجتك IDs. |
تقديم أمثلة على الطلب
أنقذوا كل واحد JSON الجسم الذي يستخدم اسم ملفه المثبت وتستخدم شركة Python مُساعدة query.py أدناه؛ ويمكن أن تقدم شركة cURL نفس الملف. إستخدم مفتاحاً مع تصريحات المصدر التي تحتاجها و الفضلات المتاحة وكل عرض هو سؤال واحد، بغض النظر عن عدد الفيديو المعادة.
Python 3.10+. (د) تركيب الطلبات مرة واحدة، باستثناء query.py أدناه، ثم استخدام القيادة إلى جانب كل طلب. ويعاد استخدام النواتج القائمة؛ ويتطلب تغيير المدخلات اسم ملف جديد للنواتج.
python -m pip install requestsBash. يستعاض عن REQUEST.json و RESULT.json بلقب الملف لمثالك المختار. تحقق من النتيجة قبل تكرار الطلب؛ وهذه القيادة تنقذ جثة HTTP حتى من أجل الخطأ.
(
set -eu
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e RESULT.json || { echo 'Read RESULT.json first'; exit 1; }
curl --fail-with-body --silent --show-error --max-time 70 \
--request POST 'https://data.flashdata.dev/v1/queries/realtime' \
--header "X-API-Key: $FLASHDATA_API_KEY" \
--header 'Content-Type: application/json' \
--data-binary @REQUEST.json --output RESULT.json
)جهزوا 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# PowerShell 7: paste the key into a hidden prompt.
$flashdataSecureKey = Read-Host "FlashData API key" -AsSecureString
$env:FLASHDATA_API_KEY = [System.Net.NetworkCredential]::new("", $flashdataSecureKey).Password
Remove-Variable flashdataSecureKeySave query.py for the Python examples
أنشئ query.py في مجلد عمل جديد وانسخ الكود الكامل أدناه إليه. احفظ ملفات طلب JSON وسكربتات Python الأخرى في هذا المجلد، وشغّل جميع الأوامر منه.
# 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.
{
"source": "youtube_search",
"query": "battery recycling process explained",
"params": {
"max_results": 5,
"filters": {
"type": "video",
"subtitles": true
}
}
}python query.py discover-request.json search.jsonيُختار حسب الأهمية، وليس أول ID
احفظ candidates.py بجانب query.py وsearch.json، ثم شغّله من ذلك المجلد. يحافظ على ترتيب البحث ويحذف معرّفات الفيديو المكررة. افحص العناوين والقنوات والمدد، ثم انسخ المعرّف المختار إلى الطلب التالي. القائمة الفارغة تعني بحثًا مكتملًا دون مرشحين.
# 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؛ والتحقق مما إذا كانت نتائجك الأولى مفيدة قبل أن تثريها كلها.
{
"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.
{
"source": "youtube_metadata",
"video_id": "FUfGcZ092b0",
"params": {
"include_formats": false,
"include_chapters": false
}
}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 | طريق قائم يدوياً لا يوجد أي تداعيات بين نوعي المسار |
python -m json.tool metadata.jsonاختيار اللغة والتتبع بشكل صريح
استخدم نفس الشيء video_id كما طلبت البيانات الوصفية وتغيّر لغتك و آليّة لمواءمة المسار المختار youtube_transcript التقصير إلى auto: true; youtube_captions التقصير إلى auto: false. كلاهما إسترجعوا الأصفاد الحالية وليس الكلام إلى النص
{
"source": "youtube_transcript",
"video_id": "FUfGcZ092b0",
"params": {
"language": "en",
"auto": true
}
}python query.py captions-request.json captions.jsonأبقوا الزمان مع الأدلة
احفظ cite-segments.py بجانب captions.json وشغّله من ذلك المجلد. استخدم results[0].segments للاستشهاد: start وend بالثواني. احتفظ بـ languageCode وisAutoGenerated مع النص. يفيد fullText في القراءة لكنه لا يحل محل توقيت المقاطع. إذا غاب المسار المختار، فسجّل الفجوة قبل تقرير جدوى استعلام آخر.
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)python cite-segments.pyتجهيز أشرطة فيديو جديدة فقط من قناة معروفة
استخدم معرّف قناة وحدًا مضبوطًا لـ video_limit بقيمة 1–100. results[0].videos هي القائمة الحديثة العائدة؛ أما videoCount فهو من بيانات القناة الوصفية وليس عدد العناصر العائدة. اختر حدًا وجدولًا يغطيان التحميلات التي تريد مراقبتها.
{
"source": "youtube_channel",
"handle": "@TED",
"params": {
"video_limit": 10
}
}python query.py channel-request.json channel.jsonحافظوا على سؤلكم ونقطه تفتيش
احفظ channel-queue.py بجانب query.py وchannel.json وشغّله من ذلك المجلد. شغّله دون معاملات لإنشاء new-ids.json، ثم عالج تلك المعرّفات واحفظ أدلتها. شغّل --commit فقط بعد نجاح جميع المعرّفات في الطابور؛ ويترك الفشل نقطة الاستئناف دون تغيير. استخدم دليلًا لكل قناة وعاملًا واحدًا لهذا المثال.
# 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.jsonpython -c "from shutil import copyfile; copyfile('channel-next.json', 'channel.json')"استخدام الاقتراحات لتحسين الاستفسار
Suggestions return wordss in results[0], not video records. (أ) اختيار عبارة مفيدة وتقديم طلب منفصل من شركة youtube_search. جهزي اللغة والمنطقة للجماهير التي تبحثين عنها
{
"source": "youtube_suggestions",
"query": "battery recycling",
"params": {
"language": "en",
"region": "US"
}
}python query.py suggestions-request.json suggestions.jsonبطاقات الترخيص المسروقة دون معاملتها كإذن
يعيد youtube_trainability وسم ترخيص الفيديو. تقابل permitted: ["all"] وسم Creative Commons؛ وتشمل ["none"] أيضًا غياب بيانات الترخيص. احتفظ بمعرّف الفيديو واستجابة المصدر وتاريخ الاسترجاع. لا يمنح هذا الوسم حقوق التنزيل أو إعادة الاستخدام أو التدريب.
{
"source": "youtube_trainability",
"video_id": "FUfGcZ092b0"
}python query.py license-request.json license.jsonيَدْفعُ العملَ للتطبيقاتِ والوكلاءِ
| المادة | التنفيذ |
|---|---|
| اختيار قبل الإثراء | لمهمة موضوعية: بحث واحد، واحد مختار من البيانات الوصفية للفيديو، وواحد من اختيار مسار التصفيق. افرض ميزانية النداء في تطبيقك وثمن كل مصدر على حدة |
| إعادة استخدام المدخلات الفعلية | Metadata: video ID + options. Captions: video ID + language + track. وتحتاج طلقات القناة أيضا إلى وقت استرجاع أو تشغيل ID. |
| وقف الأدلة المفقودة | لا تُعيدي إكتشاف فارغ أو تُغيري مسارات التصفيق بصمت. إرجعْ الفجوةَ لذا المستعملِ أَو تدفقِ العملِ يُمْكِنُ أَنْ يَختارَ الإجراءَ التاليَ. |
| الاستخدام الاحتياطي وفشل العمل | احفظ usage مع الاستجابات الناجحة. عند 429، التزم بـ Retry-After؛ وبعد إرسال غير مؤكد افحص History قبل استعلام مدفوع آخر. |