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.

نص الطلب

قدِّم مورد قائمة التشغيل في نص الطلب. بالنسبة لهذا المورد:

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

    • snippet.playlistId
    • snippet.resourceId

  • ويمكنك ضبط قيم لهذه المواقع الإلكترونية:

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

الإجابة

في حال نجاحها، تعرض هذه الطريقة مورد قائمة التشغيل في نص الاستجابة.

الأخطاء

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

نوع الخطأ تفاصيل الخطأ الوصف
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 لطلب بيانات من واجهة برمجة التطبيقات هذه والاطّلاع على طلب البيانات من واجهة برمجة التطبيقات والاستجابة لها.