تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

الخطوة 1: استرداد معرّف قائمة التشغيل للفيديوهات التي حمّلتها القناة

استخدِم الطريقة channels.list لاسترداد معرّف قائمة التشغيل التي تحتوي على الفيديوهات التي حمّلتها القناة. يجب أن تتضمّن قيمة مَعلمة part في الطلب contentDetails كأحد أجزاء المورد channel التي يتم استرجاعها. في استجابة واجهة برمجة التطبيقات، يحتوي الحقل contentDetails.relatedPlaylists.uploads على معرّف قائمة التشغيل.

هناك عدة طرق لتحديد القناة:
- اضبط قيمة المَعلمة mine على true لاسترداد معلومات قناة المستخدم الذي تمّت مصادقة هويته حاليًا على YouTube. يجب أن تتم الموافقة على طلبك باستخدام بروتوكول OAuth 2.0.
```
https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.channels.list?
        part=contentDetails
        &mine=true
```
- اضبط المَعلمة forUsername على اسم مستخدم على YouTube لاسترداد معلومات القناة المرتبطة باسم المستخدم هذا. يضبط هذا المثال قيمة المَعلمة forUsername على Google لاسترداد معلومات عن قناة Google الرسمية على YouTube.
```
https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.channels.list?
        part=contentDetails
        &forUsername=Google
```
- اضبط المَعلمة id على معرّف القناة على YouTube الذي يحدّد بشكلٍ فريد القناة التي يتم استرداد المعلومات عنها. يضبط هذا المثال المَعلمة id على UCK8sQmJBp8GCxrOtXWBpyEA، ما يحدّد أيضًا قناة Google الرسمية على YouTube.
```
https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.channels.list?
        part=contentDetails
        &id=UCK8sQmJBp8GCxrOtXWBpyEA
```
الخطوة 2: استرداد قائمة الفيديوهات المحمَّلة

استخدِم الطريقة playlistItems.list لاسترداد قائمة الفيديوهات المحمَّلة. اضبط قيمة المَعلمة playlistId على القيمة التي تم الحصول عليها في الخطوة 1. في هذا المثال، تم ضبط قيمة المَعلمة على UUK8sQmJBp8GCxrOtXWBpyEA، وهي قائمة الفيديوهات التي تم تحميلها إلى قناة Google الرسمية على YouTube.
```
https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlistItems.list?
        part=snippet,contentDetails,status
        &playlistId=UUK8sQmJBp8GCxrOtXWBpyEA
```

استرداد الفيديوهات الأكثر رواجًا

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

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

‫regionCode: لتوجيه واجهة برمجة التطبيقات إلى عرض قائمة بالفيديوهات الخاصة بالمنطقة المحدّدة
‫videoCategoryId: لتحديد فئة الفيديو التي يجب استرداد الفيديوهات الأكثر رواجًا فيها.

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

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

تحميل فيديو

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

تحتوي مستندات طريقة 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 في v3 API لتحميل صورة مصغّرة مخصّصة وضبطها لفيديو. في طلبك، تحدّد قيمة المَعلمة 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
```