نحن بصدد تعديل Data API لتتطابق مع طريقة YouTube في احتساب مشاهدات Shorts. مزيد من المعلومات

تمت ترجمة هذه الصفحة بواسطة 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 لاسترداد معلومات قناة YouTube الرسمية من Google.
```
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. تتضمّن 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

تحميل فيديو

بما أنّ أداة APIs Explorer لا تتيح إمكانية تحميل الملفات، لا يرتبط هذا الوصف بمثال قابل للتنفيذ. ستساعدك المراجع التالية في تعديل تطبيقك ليتمكّن من تحميل الفيديوهات باستخدام الإصدار 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
```

التنفيذ: الفيديوهات تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.