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

حوّل شريط فيديو YouTube ID إلى سجل منقذ لقبها وقناتها ومدتها وحساباتها المتاحة. أبقوا الرد الأصلي والإستعمال بجانبه.

مرجع كانوني: https://flashdata.dev/ar/docs/guides/video-metadata-recipe
Reviewed: 2026-11-05 by FlashData

<a id="prepare"></a>

## قبل أن تبدأ

استخدم مفتاحًا بصلاحية youtube_metadata ورصيد متاح. اختر Python 3.10+ مع requests أو Bash مع cURL 7.76+ وjq. على Windows، استخدم Git Bash لنسخة Bash.

- [احصل على مفتاح API](https://flashdata.dev/app/api-keys)
- [تجربة الوكيل وربط الحساب](https://flashdata.dev/ar/docs/guides/agent-onboarding/reference.md)
- [الأرصدة الدائنة والتسعير](https://flashdata.dev/ar/docs/guides/credits-and-billing/reference.md)

<a id="input"></a>

## 1. اختر شريط فيديو واحد

إنشاء ملف فيديو - ميثاداتا وإنقاذ request.json هناك افتح محطة طرفية في ذلك الملف. يستعاض عن video_id بالرمز 11-character ID من ساعة URL أو نتيجة YouTube Search؛ ولا تعبر عن الرقم الكامل URL.

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

### video-metadata/request.json

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


<a id="run"></a>

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

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

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

### Python

#### ضع في رأسك Python البيئة

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

#### video-metadata/metadata.py

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

#### مهرب من البيانات الفيديوية/

```bash
python metadata.py snapshot-001
```


### Bash

#### تحقق من أدواتك

```bash
curl --version
jq --version
```

#### video-metadata/metadata.sh

```bash
#!/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
bash metadata.sh snapshot-001
```



<a id="output"></a>

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

عند النجاح تُطبع Saved <video ID> to snapshot-001/video.json. اقرأ ذلك الملف للحصول على كائن البيانات الوصفية كاملًا، وrecord.json للاطلاع على الطلب المرسل وrequested_at والاستخدام. لا تؤدي قراءة هذه الملفات إلى أي استدعاء API.

### Python

#### اقرأ محليا

```bash
python -m json.tool snapshot-001/video.json
python -m json.tool snapshot-001/record.json
```


### Bash

#### اقرأ محليا

```bash
cat snapshot-001/video.json
cat snapshot-001/record.json
```



<a id="expected"></a>

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

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

#### video-metadata/snapshot-001/video.json

```json
{
  "videoId": "FUfGcZ092b0",
  "title": "Example research video",
  "channel": "Example channel",
  "duration": 120,
  "viewCount": null,
  "transcriptLanguages": [
    "en"
  ]
}
```


<a id="fields"></a>

### اقرأ الحقول

| الميدان | إستخدمه |
| --- | --- |
| videoId | الرقم القياسي مستقر يمكن تغيير أسماء العنوان والقنوات. |
| duration | طول الفيديو في ثواني الحافظة مفقودة null قيم غير معروفة |
| viewCount / likeCount / commentCount | الكونتات متاحة في هذه الصورة ولا يعرف النواة أو المفقودة؛ ولا يبلَّغ عن أي عدد. |
| transcriptLanguages | رموز اللغات المرشحة لطلب الإقفال المستقل. ولا تحدد هذه القائمة ما إذا كان المسار آليا أو يدويا. |


<a id="reuse"></a>

## إعادة استخدام الطلقة أو طلب آخر

أديري نفس القيادة لإعادة البناء video.json و record.json من الاستجابة الموفرة. ولا يلزم تقديم أي طلب رئيسي أو من الشبكة. ولا يغير التحرير على المستوى الأعلى للزدحام المغناطيسي (request.json) المدخلات المخزنة بالقطعة - 001.

### Python

#### إعادة استخدام البيانات

```bash
python metadata.py snapshot-001
```


### Bash

#### إعادة استخدام البيانات

```bash
bash metadata.sh snapshot-001
```


- [تحقيق النتائج وإعادة استخدامها](https://flashdata.dev/ar/docs/guides/save-results/reference.md)

<a id="chapters"></a>

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

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

#### video-metadata/request.json

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

#### Python

##### اطلبي طلقه اخرى

```bash
python metadata.py snapshot-002
```


#### Bash

##### اطلبي طلقه اخرى

```bash
bash metadata.sh snapshot-002
```


- [حقول وخيارات البيانات](https://flashdata.dev/ar/docs/sources/youtube_metadata/reference.md)

<a id="recover"></a>

## إذا كانت البيانات الوصفية غير متاحة

| ماذا حدث؟ | الإجراء المطلوب |
| --- | --- |
| Invalid video_id | استخدم فقط 11-منتج ID. يتوقف التحقق من المدخلات قبل إرسال الطلب. |
| شريط فيديو خاص أو مشطوب أو مقيد | حافظ على الفشل ID. تحقق من خطأ المصدر واختيار شريط فيديو متاح بدلاً من تقديم نفس البند مراراً. |
| نتيجة فارغة أو مختلفة من طراز videoId | النص يتوقف بدون كتابة video.json. فحص الطلب المنقذ ورده قبل استخدام السجل. |
| عدد المفقودين أو الفصول أو اللغات | سجل مطابق للبيانات الفوقية يمكن أن يكون ناجحاً :: الحفاظ على الحقول غير المتاحة على أنها غير معروفة؛ ولا تملئها بالقيم المخترعة. |
| 401 / 403 / 402 | تحقق من المفتاح، إذن وتوازن youtube_metadata، على التوالي، قبل محاولة جديدة. |
| 429 | اقرأ Retry-After في response-headers.txt وانتظر. النص لا يتراجع تلقائياً |
| وقت مستقطع، 5x، غير صحيح JSON أو ملف غير كامل | حافظوا على المحاولة وتحققوا History قبل أن تقدم مرة أخرى. إعادة استخدام ملفها لا تقدم أي طلب جديد. |

### Python

احفظ inspect_metadata.py بجانب metadata.py، ثم شغّله.

#### video-metadata/inspect_metadata.py

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

```bash
python inspect_metadata.py
```


### Bash

#### Inspect locally

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


- [التاريخ](https://flashdata.dev/app/jobs)
- [الأخطاء ورموز الحالة](https://flashdata.dev/ar/docs/errors/reference.md)

<a id="next"></a>

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

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

- [استرجاع الأزمنة المأخوذة](https://flashdata.dev/ar/docs/guides/timestamped-captions-recipe/reference.md)
- [Enrich selected video IDs](https://flashdata.dev/ar/docs/guides/enrich-youtube-videos/reference.md)
