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

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

مرجع كانوني: https://flashdata.dev/ar/docs/guides/youtube-data-guide
Reviewed: 2026-11-04 by FlashData

<a id="choose"></a>

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

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

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

- [العثور على أشرطة فيديو](https://flashdata.dev/ar/docs/guides/youtube-data-guide/reference.md#discover)
- [عمل مع فيديو معروف](https://flashdata.dev/ar/docs/guides/youtube-data-guide/reference.md#metadata)
- [رصد قناة](https://flashdata.dev/ar/docs/guides/youtube-data-guide/reference.md#channel)

<a id="setup"></a>

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

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

### Python

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

#### تثبيت

```bash
python -m pip install requests
```


### cURL

Bash. يستعاض عن REQUEST.json و RESULT.json بلقب الملف لمثالك المختار. تحقق من النتيجة قبل تكرار الطلب؛ وهذه القيادة تنقذ جثة HTTP حتى من أجل الخطأ.

#### Submit a save JSON request

```bash
(
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
)
```



<a id="authenticate"></a>

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

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

#### Bash

##### حدد المفتاح

```bash
# 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

##### حدد المفتاح

```powershell
# 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 flashdataSecureKey
```


- [مفاتيح API](https://flashdata.dev/app/api-keys)
- [تجربة الوكيل وربط الحساب](https://flashdata.dev/ar/docs/guides/agent-onboarding/reference.md)

<a id="runner"></a>

### Save query.py for the Python examples

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

#### query.py

```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))
```


<a id="discover"></a>

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

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

### discover-request.json

```json
{
  "source": "youtube_search",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 5,
    "filters": {
      "type": "video",
      "subtitles": true
    }
  }
}
```

### Submit once with query.py

```bash
python query.py discover-request.json search.json
```


<a id="candidates"></a>

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

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

#### candidates.py

```python
# 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))
```

#### اقرأ البحث المنقذ

```bash
python candidates.py
```


<a id="extended"></a>

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

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

#### extended-request.json

```json
{
  "source": "youtube_search_extended",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 50,
    "filters": {
      "type": "video"
    }
  }
}
```

#### اركض مرة واحدة

```bash
python query.py extended-request.json extended.json
```

- [يُقدم بحثاً أطول بغرابة](https://flashdata.dev/ar/docs/reference/realtime-and-async/reference.md#async)
- [Enrich selected IDs](https://flashdata.dev/ar/docs/guides/enrich-youtube-videos/reference.md)

<a id="metadata"></a>

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

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

### metadata-request.json

```json
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": false
  }
}
```

### Submit once with query.py

```bash
python query.py metadata-request.json metadata.json
```

- [مجالات الاستجابة](https://flashdata.dev/ar/docs/sources/youtube_metadata/reference.md#response)
- [سير العمل في مجال تقديم الخدمات الإعلامية](https://flashdata.dev/ar/docs/guides/media-delivery-pipeline/reference.md)

<a id="tracks"></a>

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

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

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

#### اقرأ metadata.json ; لا يوجد أي استفسار

```bash
python -m json.tool metadata.json
```


<a id="captions"></a>

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

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

### captions-request.json

```json
{
  "source": "youtube_transcript",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": true
  }
}
```

### Submit once with query.py

```bash
python query.py captions-request.json captions.json
```

- [بارامترات القدرات](https://flashdata.dev/ar/docs/sources/youtube_transcript/reference.md#parameters)
- [إعداد موجز كامل](https://flashdata.dev/ar/docs/guides/youtube-summary/reference.md)

<a id="citations"></a>

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

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

#### cite-segments.py

```python
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 اتصلي

```bash
python cite-segments.py
```


<a id="channel"></a>

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

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

### channel-request.json

```json
{
  "source": "youtube_channel",
  "handle": "@TED",
  "params": {
    "video_limit": 10
  }
}
```

### Submit once with query.py

```bash
python query.py channel-request.json channel.json
```


<a id="channel-diff"></a>

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

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

#### channel-queue.py

```python
# 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))
```

#### تخطيط → معالجة → تثبيت النتائج

```bash
python channel-queue.py
# Process every ID in new-ids.json and save its result first.
python channel-queue.py --commit
```

- [وثائق التفويض المتعلقة بالجدول الزمني وإعادة الاستخدام](https://flashdata.dev/ar/docs/guides/recurring-tasks/reference.md)
- [إثراء قائمة الفيديو](https://flashdata.dev/ar/docs/guides/enrich-youtube-videos/reference.md)

<a id="channel-checkpoint"></a>

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

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

#### الشيك التالي: اختيار اسم ملف جديد

```bash
python query.py channel-request.json channel-next.json
```

#### بعد التأكد من الوضع

```bash
python -c "from shutil import copyfile; copyfile('channel-next.json', 'channel.json')"
```


<a id="suggestions"></a>

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

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

### suggestions-request.json

```json
{
  "source": "youtube_suggestions",
  "query": "battery recycling",
  "params": {
    "language": "en",
    "region": "US"
  }
}
```

### Submit once with query.py

```bash
python query.py suggestions-request.json suggestions.json
```


<a id="license"></a>

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

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

### license-request.json

```json
{
  "source": "youtube_trainability",
  "video_id": "FUfGcZ092b0"
}
```

### Submit once with query.py

```bash
python query.py license-request.json license.json
```


<a id="operations"></a>

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

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

- [Realtime and async](https://flashdata.dev/ar/docs/reference/realtime-and-async/reference.md)
- [Batch and bulk](https://flashdata.dev/ar/docs/reference/batch-and-bulk/reference.md)
- [الأخطاء والمخابرات](https://flashdata.dev/ar/docs/errors/reference.md#retries)
- [التسعير والتوازن الحاليان](https://flashdata.dev/ar/docs/guides/credits-and-billing/reference.md)
