PlaylistItems: insert

تضيف هذه الطريقة مرجعًا إلى قائمة تشغيل.

التأثير في الحصة: يتطلّب طلب هذه الطريقة تكلفة حصة تبلغ 50 وحدة.

حالات الاستخدام الشائعة

طلب

طلب HTTP

POST https://www.googleapis.com/youtube/v3/playlistItems

التفويض

يتطلّب هذا الطلب الحصول على إذن باستخدام نطاق واحد على الأقل من النطاقات التالية (مزيد من المعلومات حول المصادقة والتفويض).

النطاق
https://www.googleapis.com/auth/youtubepartner
https://www.googleapis.com/auth/youtube
https://www.googleapis.com/auth/youtube.force-ssl

المعلمات

يسرد الجدول التالي المَعلمات التي يتيحها طلب البحث هذا. جميع المَعلمات المُدرَجة هي مَعلمات طلب بحث.

المعلمات
المَعلمات المطلوبة
part string
تخدم المَعلمة part غرضَين في هذه العملية. تحدّد هذه المَعلمة السمات التي ستضبطها عملية الكتابة، بالإضافة إلى السمات التي سيتضمّنها ردّ من واجهة برمجة التطبيقات.

تحتوي القائمة التالية على أسماء part التي يمكنك تضمينها في قيمة المَعلمة:
  • contentDetails
  • id
  • snippet
  • status
المَعلمات الاختيارية
onBehalfOfContentOwner string
لا يمكن استخدام هذه المَعلمة إلا في طلب مصرَّح به بشكل صحيح. ملاحظة: هذه المَعلمة مخصّصة حصريًا لشركاء المحتوى في YouTube.

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

نص الطلب

قدِّم مورد playlistItem في نص الطلب. بالنسبة إلى هذا المرجع:

  • يجب تحديد قيمة للسمات التالية:

    • snippet.playlistId
    • snippet.resourceId

  • يمكنك ضبط قيم للخصائص التالية:

    • snippet.playlistId
    • snippet.position
    • snippet.resourceId
    • contentDetails.note
    • contentDetails.startAt
    • contentDetails.endAt

الردّ

في حال نجاح العملية، تعرض هذه الطريقة مرجع playlistItem في نص الاستجابة.

الأخطاء

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

نوع الخطأ تفاصيل الخطأ الوصف
forbidden (403) playlistContainsMaximumNumberOfVideos تحتوي قائمة التشغيل على الحد الأقصى المسموح به لعدد الفيديوهات.
forbidden (403) playlistItemsNotAccessible لم يتم تفويض الطلب بشكل صحيح لإدراج عنصر قائمة التشغيل المحدّد.
invalidValue (400) invalidContentDetails السمة contentDetails في الطلب غير صالحة. قد يكون السبب المحتمل هو أنّ حقل contentDetails.note يتجاوز 280 حرفًا.
invalidValue (400) invalidPlaylistItemPosition يحاول الطلب ضبط موضع عنصر قائمة التشغيل على قيمة غير صالحة أو غير متوافقة. تحقَّق من قيمة السمة position في snippet الخاص بالمورد.
invalidValue (400) invalidResourceType إنّ السمة type المحدّدة لمعرّف المورد غير متوافقة مع هذه العملية. يحدّد معرّف المورد العنصر الذي تتم إضافته إلى قائمة التشغيل، مثل youtube#video.
invalidValue (400) manualSortRequired يحاول الطلب ضبط موضع عنصر قائمة التشغيل، ولكن قائمة التشغيل لا تستخدم الترتيب اليدوي. (على سبيل المثال، قد يتم ترتيب عناصر قائمة التشغيل حسب التاريخ أو مدى الرواج). يمكنك معالجة الخطأ عن طريق إزالة العنصر snippet.position من المورد الذي يُدرجه الطلب. إذا أردت أن يكون لعنصر قائمة التشغيل موضع معيّن في القائمة، عليك أولاً تعديل خيار الترتيب في قائمة التشغيل إلى يدوي في إعدادات قائمة التشغيل. يمكن تعديل هذه الإعدادات في مدير الفيديو في YouTube.
invalidValue (400) videoAlreadyInAnotherSeriesPlaylist الفيديو الذي تحاول إضافته إلى قائمة التشغيل مُدرَج في قائمة تشغيل أخرى لفيديوهات متسلسلة.
notFound (404) playlistNotFound يتعذّر العثور على قائمة التشغيل المحدّدة باستخدام المَعلمة playlistId في الطلب.
notFound (404) videoNotFound تعذّر العثور على الفيديو الذي تحاول إضافته إلى قائمة التشغيل. تحقَّق من قيمة السمة videoId للتأكّد من صحتها.
required (400) channelIdRequired لا يحدّد الطلب قيمة لسمة channelId المطلوبة.
required (400) playlistIdRequired لا يحدّد الطلب قيمة لسمة playlistId المطلوبة.
required (400) resourceIdRequired يجب أن يتضمّن الطلب موردًا يحدّد فيه العنصر snippet resourceId.
invalidValue (400) playlistOperationUnsupported لا تتيح واجهة برمجة التطبيقات إمكانية إدراج فيديوهات في قائمة التشغيل المحدّدة. على سبيل المثال، لا يمكنك إدراج فيديو في قائمة تشغيل الفيديوهات التي حمّلتها.

جرِّبها الآن.

استخدِم APIs Explorer لطلب بيانات من واجهة برمجة التطبيقات هذه والاطّلاع على طلب واجهة برمجة التطبيقات والاستجابة.