التنفيذ: الفيديوهات

توضّح الأمثلة التالية كيفية استخدام YouTube Data API (الإصدار 3) لتنفيذ وظائف متعلقة بالفيديوهات.

استرداد الفيديوهات التي تم تحميلها على قناة

يستردّ هذا المثال الفيديوهات التي تم تحميلها على قناة معيّنة، ويتضمّن خطوتَين:

يوضّح هذا المثال كيفية استرداد قائمة بفيديوهات YouTube الأكثر رواجًا، والتي يتم اختيارها باستخدام خوارزمية تجمع العديد من الإشارات المختلفة لتحديد مدى الرواج بشكل عام.

لاسترداد قائمة الفيديوهات الأكثر رواجًا، استدعِ طريقة videos.list واضبط قيمة المَعلمة chart على mostPopular. يتضمّن الرسم البياني mostPopular الفيديوهات الرائجة في مجال الموسيقى والأفلام وألعاب الفيديو.

بعد ذلك، يمكنك اختياريًا ضبط المَعلمات التالية:

  • regionCode: يطلب من واجهة برمجة التطبيقات عرض قائمة بالفيديوهات في المنطقة المحدّدة. قيمة المَعلمة هي رمز البلد المؤلف من حرفَين تبعًا لترميز ISO 3166-1 alpha-2. يمكنك استخدام طريقة i18nRegions.list لاسترداد قائمة برموز المناطق التي يتيحها YouTube.
  • videoCategoryId: تحدّد هذه السمة فئة الفيديو التي يجب استرداد الفيديوهات الأكثر رواجًا فيها. يمكنك استخدام طريقة videoCategories.list لاسترداد قائمة بمعرّفات الفئات التي يتيحها YouTube.

على سبيل المثال، يستردّ الطلب التالي فيديوهات الرياضة الأكثر رواجًا في إسبانيا:

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.list?
        part=snippet
        &chart=mostPopular
        &regionCode=es
        &videoCategoryId=17

استرداد إحصاءات الفيديوهات المجمّعة

يستردّ هذا المثال إحصاءات لقائمة فيديوهات باستخدام الطريقة videos.batchGetStats.

لاستخدام هذه الطريقة، اضبط قيمة المَعلمة id في الطلب على قائمة قيم مفصولة بفاصلة تتضمّن معرّفات فيديوهات على YouTube التي تريد استرداد إحصاءاتها. اضبط قيمة المَعلمة part على قائمة قيم مفصولة بفاصلة لأجزاء مورد videoStat التي تريد أن تتضمّنها الاستجابة. الأجزاء المتوافقة هي snippet وstatistics وcontentDetails وid.

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

يسترد الطلب أدناه إحصاءات لمعرّفَي الفيديو VIDEO_ID_1 وVIDEO_ID_2:

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.batchGetStats?
        part=snippet,statistics
        &id=VIDEO_ID_1,VIDEO_ID_2

تحميل فيديو

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

  • يتضمّن مستند videos.insert الخاص بواجهة برمجة التطبيقات عدة عيّنات من الرموز البرمجية توضّح كيفية تحميل فيديو باستخدام لغات برمجة مختلفة.

  • يوضّح دليل عمليات التحميل القابلة للاستئناف تسلسل طلبات HTTP التي يستخدمها التطبيق لتحميل الفيديوهات باستخدام عملية تحميل قابلة للاستئناف. هذا الدليل مخصّص بشكل أساسي للمطوّرين الذين لا يمكنهم استخدام مكتبات عملاء Google API، والتي يوفّر بعضها إمكانية تحميل البيانات بشكل قابل للاستئناف.

  • يستخدم مثال JavaScript لتحميل فيديو مشاركة المراجع مع نطاقات خارجية (CORS) لتوضيح كيفية تحميل ملف فيديو من خلال صفحة ويب. تتيح مكتبة التحميل المتوافقة مع سياسة مشاركة الموارد المتعددة المصادر (CORS) التي يستخدمها الإصدار 3 من واجهة برمجة التطبيقات إمكانية استئناف عمليات التحميل بشكل طبيعي. بالإضافة إلى ذلك، يوضّح المثال كيفية التحقّق من حالة فيديو تم تحميله من خلال استرداد الجزء processingDetails من مورد video، بالإضافة إلى كيفية التعامل مع تغييرات الحالة للفيديو الذي تم تحميله.

التحقّق من حالة فيديو تم تحميله

يوضّح هذا المثال كيفية التحقّق من حالة فيديو تم تحميله. سيظهر الفيديو الذي تم تحميله على الفور في خلاصة الفيديوهات التي حمّلها المستخدم الذي تم إثبات هويته. في المقابل، لن يظهر الفيديو على YouTube قبل أن تتم معالجته.

  • الخطوة 1: تحميل الفيديو

    استدعِ طريقة videos.insert لتحميل الفيديو. إذا كان الطلب ناجحًا، ستحتوي استجابة واجهة برمجة التطبيقات على مورد video يحدّد معرّف الفيديو الفريد للفيديو الذي تم تحميله.

  • الخطوة 2: التحقّق من حالة الفيديو

    استدعِ الدالة videos.list للتحقّق من حالة الفيديو. اضبط قيمة المَعلمة id على رقم تعريف الفيديو الذي تم الحصول عليه في الخطوة 1. اضبط قيمة المَعلمة part على processingDetails.

    في حال تمت معالجة الطلب بنجاح، ستحتوي استجابة واجهة برمجة التطبيقات على مورد video. تحقَّق من قيمة السمة processingDetails.processingStatus لتحديد ما إذا كان YouTube لا يزال يعالج الفيديو. ستتغيّر قيمة السمة إلى قيمة أخرى غير processing، مثل succeeded أو failed، عند انتهاء YouTube من معالجة الفيديو.

    يتضمّن نص الطلب المورد video الذي تحدّد فيه السمة id معرّف الفيديو الذي تريد حذفه. في هذا المثال، يحتوي المرجع أيضًا على عنصر recordingDetails.

    يتحقّق الطلب أدناه من حالة فيديو. لإكمال الطلب في مستكشف واجهات برمجة التطبيقات، عليك ضبط قيمة السمة id.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.list?
        part=snippet,processingDetails
        &id=VIDEO_ID

ملاحظة: يمكن لتطبيقك أن يطلب من واجهة برمجة التطبيقات التحقّق بشكل دوري من حالة فيديو تم تحميله حديثًا. بعد معالجة الفيديو، يمكن لتطبيقك إنشاء إشعار أو المتابعة بإجراء آخر يعتمد على حالة الفيديو.

تعديل فيديو

يوضّح هذا المثال كيفية تعديل فيديو لإضافة معلومات حول وقت تسجيله ومكانه. يتضمّن المثال الخطوات التالية:

  • الخطوة 1: استرداد معرّف الفيديو

    اتّبِع الخطوات المذكورة أعلاه لاسترداد الفيديوهات المحمَّلة لقناة المستخدم الذي تمّت مصادقته حاليًا. يمكن استخدام القائمة لعرض قائمة بالفيديوهات، باستخدام معرّف كل فيديو كمفتاح.

    ملاحظة: هناك العديد من الطرق الأخرى للحصول على معرّفات الفيديوهات، مثل استرداد نتائج البحث أو إدراج عناصر في قائمة تشغيل. ومع ذلك، بما أنّه لا يمكن تعديل الفيديو إلا من قِبل مالكه، فإنّ استرداد قائمة بالفيديوهات التي يملكها المستخدم الذي يمنح الإذن بطلب البيانات من واجهة برمجة التطبيقات هو الخطوة الأولى المحتملة في هذه العملية.

  • الخطوة 2: تعديل فيديو

    استدعِ الدالة videos.update لتعديل فيديو معيّن. اضبط قيمة المَعلمة part على recordingDetails. (تعتمد قيمة المَعلمة على حقول البيانات الوصفية للفيديو الذي يتم تعديله).

    يتضمّن نص الطلب المورد video الذي تحدّد فيه السمة id معرّف الفيديو الذي تريد تعديله. في هذا المثال، يحتوي المرجع أيضًا على عنصر recordingDetails.

    يشير المرجع النموذجي أدناه إلى أنّه تم تسجيل الفيديو في 30 تشرين الأول (أكتوبر) 2013 في بوسطن:

    {
  "id": "VIDEO_ID",
  "recordingDetails": {
    "location": {
      "latitude": "42.3464",
      "longitude": "-71.0975"
    }
    "recordingDate": "2013-10-30T23:15:00.000Z"
  }
}

    لإكمال الطلب في مستكشف واجهات برمجة التطبيقات، عليك ضبط قيمة السمة id.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.update?
        part=snippet

تحميل صورة مصغّرة مخصّصة وضبطها لفيديو

يمكنك استخدام طريقة thumbnails.set في الإصدار 3 من واجهة برمجة التطبيقات لتحميل صورة مصغّرة مخصّصة وضبطها لفيديو. في طلبك، تحدّد قيمة المَعلمة videoId الفيديو الذي سيتم استخدام الصورة المصغّرة له.

لا يمكن اختبار هذا الطلب باستخدام "مستكشف واجهات برمجة التطبيقات" لأنّه لا يتيح إمكانية تحميل ملفات وسائط، وهو شرط أساسي لهذه الطريقة.

عيّنات الرموز البرمجية ذات الصلة: PHP وPython

لحذف فيديو

يوضّح هذا المثال كيفية حذف فيديو، ويتضمّن الخطوات التالية:

  • الخطوة 1: استرداد معرّف الفيديو

    اتّبِع الخطوات المذكورة أعلاه لاسترداد الفيديوهات المحمَّلة لقناة المستخدم الذي تمّت مصادقته حاليًا. يمكن استخدام القائمة لعرض قائمة بالفيديوهات، باستخدام معرّف كل فيديو كمفتاح.

    ملاحظة: هناك العديد من الطرق الأخرى للحصول على معرّفات الفيديوهات، مثل استرداد نتائج البحث أو إدراج عناصر في قائمة تشغيل. ومع ذلك، بما أنّه لا يمكن حذف فيديو إلا من قِبل مالكه، فإنّ استرداد قائمة بالفيديوهات التي يملكها المستخدم الذي يمنح الإذن بطلب بيانات من واجهة برمجة التطبيقات هو على الأرجح الخطوة الأولى في هذه العملية.

  • الخطوة 2: حذف فيديو

    استدعِ الطريقة videos.delete لحذف فيديو معيّن. في الطلب، تحدّد المَعلمة id معرّف الفيديو الذي تريد حذفه. يجب أن يتم السماح بالطلب باستخدام OAuth 2.0. إذا كنت تختبر طلب البحث هذا في "مستكشف واجهات برمجة التطبيقات"، عليك استبدال قيمة المَعلمة id بمعرّف فيديو صالح.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.delete?
        id=VIDEO_ID

الإبلاغ عن فيديو مسيء

يوضّح هذا المثال كيفية الإبلاغ عن فيديو يتضمّن محتوًى مسيئًا، ويتضمّن الخطوات التالية:

  • الخطوة 1: استرداد المعرّفات التي توضّح سبب الإبلاغ عن الفيديو

    أرسِل طلبًا معتمدًا إلى طريقة videoAbuseReportReasons.list لاسترداد قائمة بالأسباب الصالحة للإبلاغ عن فيديو. يحتوي نموذج videoAbuseReportReason المورد أدناه على معلومات للإبلاغ عن فيديو يتضمّن محتوًى غير مرغوب فيه أو محتوًى مضلّلاً.

    {
  "kind": "youtube#videoAbuseReportReason",
  "etag": "\"tbWC5XrSXxe1WOAx6MK9z4hHSU8/Or2VqBIilpHU7j__oPzUFCvGVBw\"",
  "id": "S",
  "snippet": {
    "label": "Spam or misleading",
    "secondaryReasons": [
      {
        "id": "27",
        "label": "Spam or mass advertising"
      },
      {
        "id": "28",
        "label": "Misleading thumbnail"
      },
      {
        "id": "29",
        "label": "Malware or phishing"
      },
      {
        "id": "30",
        "label": "Pharmaceutical drugs for sale"
      },
      {
        "id": "31",
        "label": "Other misleading info"
      }
    ]
  }
}

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

  • الخطوة 2: الإبلاغ عن الفيديو بسبب المحتوى المسيء

    أرسِل طلبًا معتمدًا إلى طريقة videos.reportAbuse للإبلاغ عن الفيديو. يتضمّن نص الطلب عنصر JSON يحدّد كلاً من الفيديو الذي يتم الإبلاغ عنه وسبب الإبلاغ عنه. كما هو موضّح في الخطوة 1، بالنسبة إلى بعض أنواع الأسباب، يمكن إضافة سبب ثانوي وننصح بشدة بذلك.

    تحدّد السمة videoId الخاصة بكائن JSON الفيديو الذي يتم الإبلاغ عنه.

    يُبلغ نموذج عنصر JSON أدناه عن فيديو يتضمّن محتوًى غير مرغوب فيه أو محتوًى مضلّلاً، وتحديدًا عن استخدام صورة مصغّرة مضلّلة. كما هو موضّح في نموذج عنصر JSON أعلاه، يكون رقم التعريف الخاص بالمحتوى غير المرغوب فيه أو المضلِّل هو S. رقم التعريف الخاص بالصورة المصغّرة المضلِّلة هو 28.

    {
  "videoId": "VIDEO_ID",
  "reasonId": "S",
  "secondaryReasonId": "28",
  "comments": "Testing the video flagging feature.",
  "language": "en"
}

    يجب منح الإذن لطلب videos.reportAbuse باستخدام OAuth 2.0. يؤدي الرابط أدناه إلى تحميل عنصر JSON أعلاه في "مستكشف واجهات برمجة التطبيقات". لاختبار طلب البحث، عليك استبدال قيمة السمة videoId بمعرّف فيديو صالح. يُرجى العِلم أنّ إرسال هذا الطلب سيؤدي إلى الإبلاغ عن الفيديو.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.reportAbuse