تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

توضّح الأمثلة التالية كيفية استخدام 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

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

يستردّ هذا المثال إحصاءات لقائمة فيديوهات باستخدام طريقة 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
```

إدارة وصول العلامات التجارية الشريكة إلى الفيديو (وصول العلامات التجارية الشريكة إلى الفيديو بمبادرة من صنّاع المحتوى)

تتيح ميزة "وصول العلامات التجارية الشريكة إلى الفيديو" التي يبدأها صانع المحتوى لمالك الفيديو مشاركة إذن الوصول إلى الفيديو مع قناة علامة تجارية شريكة. يتطلّب ذلك الجزء brandPartner.

منح إذن الوصول (إدراج)

لإعداد إذن الوصول عند تحميل فيديو، يجب تضمين brandPartner في المَعلمة part وتقديم عنصر brandPartner في نص الطلب. يجب تحديد إما channelId (معرّف القناة الخارجي الذي يبدأ بـ "UC") أو channelHandle (الذي يبدأ بـ "@") لتحديد قناة العلامة التجارية.

POST /youtube/v3/videos?part=snippet,status,brandPartner
{
  "snippet": {
    "title": "Video Title",
    "description": "Video Description",
    "categoryId": "22"
  },
  "status": {
    "privacyStatus": "private"
  },
  "brandPartner": {
    "channelHandle": "@brandchannel"
  }
}

سيتم عرض channelId الذي تم حلّه فقط في الردّ.

تعديل إذن الوصول أو إزالته (تعديل)

لتعديل إذن الوصول إلى قناة علامة تجارية مختلفة أو لإزالة إذن الوصول، يمكنك استدعاء الطريقة videos.update باستخدام brandPartner في المَعلمة part.

لاستبدال إذن الوصول، قدِّم channelId أو channelHandle الجديد في نص الطلب:

PUT /youtube/v3/videos?part=brandPartner
{
  "id": "VIDEO_ID",
  "brandPartner": {
    "channelId": "UC_SOME_BRAND_CHANNEL_ID"
  }
}

لإزالة إذن الوصول، أرسِل طلبًا يتضمّن brandPartner في المَعلمة part، ولكن مع عنصر brandPartner فارغ في نص الطلب:

PUT /youtube/v3/videos?part=brandPartner
{
  "id": "VIDEO_ID",
  "brandPartner": {}
}

تحميل صورة مصغّرة مخصّصة وتعيينها لفيديو

يمكنك استخدام طريقة 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
```

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