PlaylistItems

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

يستخدم YouTube أيضًا قائمة تشغيل لتحديد قائمة الفيديوهات التي تم تحميلها على قناة، ويمثّل كل playlistItem في هذه القائمة فيديو تم تحميله. يمكنك استرداد رقم تعريف قائمة التشغيل الخاصة بهذه القائمة من المورد channel لقناة معيّنة. يمكنك بعد ذلك استخدام طريقة playlistItems.list لإضافة عنصر إلى القائمة.

الطُرق

تتيح واجهة برمجة التطبيقات الطرق التالية لموارد playlistItems:

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

تمثيل الموارد

يعرض بنية JSON التالية تنسيق مورد playlistItems:

{
  "kind": "youtube#playlistItem",
  "etag": etag,
  "id": string,
  "snippet": {
    "publishedAt": datetime,
    "channelId": string,
    "title": string,
    "description": string,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
      }
    },
    "channelTitle": string,
    "videoOwnerChannelTitle": string,
    "videoOwnerChannelId": string,
    "playlistId": string,
    "position": unsigned integer,
    "resourceId": {
      "kind": string,
      "videoId": string,
    }
  },
  "contentDetails": {
    "videoId": string,
    "startAt": string,
    "endAt": string,
    "note": string,
    "videoPublishedAt": datetime
  },
  "status": {
    "privacyStatus": string
  }
}

الخصائص

يحدّد الجدول التالي السمات التي تظهر في هذا المرجع:

الخصائص
kind string
تحدّد هذه السمة نوع مورد واجهة برمجة التطبيقات. ستكون القيمة youtube#playlistItem.
etag etag
تمثّل هذه السمة Etag الخاصة بهذا المرجع.
id string
المعرّف الذي يستخدمه YouTube لتحديد عنصر قائمة التشغيل بشكل فريد.
snippet ‫object
يحتوي العنصر snippet على تفاصيل أساسية حول عنصر قائمة التشغيل، مثل عنوانه وموضعه في قائمة التشغيل.
snippet.publishedAt datetime
تمثّل هذه السمة تاريخ ووقت إضافة العنصر إلى قائمة التشغيل. يتم تحديد القيمة بالتنسيق ISO 8601.
snippet.channelId string
المعرّف الذي يستخدمه YouTube لتحديد المستخدم الذي أضاف العنصر إلى قائمة التشغيل بشكلٍ فريد.
snippet.title string
تمثّل هذه السمة عنوان السلعة.
snippet.description string
وصف السلعة
snippet.thumbnails object
خريطة للصور المصغّرة المرتبطة بعنصر قائمة التشغيل. بالنسبة إلى كل عنصر في الخريطة، يكون المفتاح هو اسم الصورة المصغّرة، والقيمة هي عنصر يحتوي على معلومات أخرى حول الصورة المصغّرة.
snippet.thumbnails.(key) object
قيم المفاتيح الصالحة هي:
  • default: الصورة المصغّرة التلقائية يبلغ حجم الصورة المصغّرة التلقائية للفيديو أو المرجع الذي يشير إلى فيديو، مثل عنصر في قائمة تشغيل أو نتيجة بحث، 120 بكسل عرضًا و90 بكسل ارتفاعًا. يبلغ عرض الصورة المصغّرة التلقائية للقناة 88 بكسل وطولها 88 بكسل.
  • medium: نسخة من الصورة المصغّرة بدقة أعلى بالنسبة إلى فيديو (أو مرجع يشير إلى فيديو)، يبلغ عرض هذه الصورة 320 بكسل وارتفاعها 180 بكسل. بالنسبة إلى قناة، يبلغ عرض هذه الصورة 240 بكسل وارتفاعها 240 بكسل.
  • ‫high: نسخة عالية الدقة من الصورة المصغّرة بالنسبة إلى فيديو (أو مرجع يشير إلى فيديو)، يبلغ عرض هذه الصورة 480 بكسل وارتفاعها 360 بكسل. بالنسبة إلى القناة، يبلغ عرض هذه الصورة 800 بكسل وارتفاعها 800 بكسل.
  • ‫standard: نسخة من الصورة المصغّرة بدقة أعلى من دقة الصورة high. تتوفّر هذه الصورة لبعض الفيديوهات والمراجع الأخرى التي تشير إلى الفيديوهات، مثل عناصر قائمة التشغيل أو نتائج البحث. يبلغ عرض هذه الصورة 640 بكسل وارتفاعها 480 بكسل.
  • ‫maxres: نسخة عالية الدقة من الصورة المصغّرة يتوفّر حجم الصورة هذا لبعض الفيديوهات والمراجع الأخرى التي تشير إلى الفيديوهات، مثل عناصر قائمة التشغيل أو نتائج البحث. يبلغ عرض هذه الصورة 1280 بكسل وارتفاعها 720 بكسل.
  • fhd: نسخة الصورة المصغّرة بدقة فائقة (1080p) يتوفّر حجم الصورة هذا لبعض الفيديوهات. يبلغ عرض هذه الصورة 1920 بكسل وارتفاعها 1080 بكسل.
  • qhd – نسخة الصورة المصغّرة بدقة Quad High Definition (1440p / 2K) يتوفّر حجم الصورة هذا لبعض الفيديوهات. يبلغ عرض هذه الصورة 2560 بكسل وارتفاعها 1440 بكسل.
  • ‫uhd: نسخة الصورة المصغّرة فائقة الدقة (4K) يتوفّر حجم الصورة هذا لبعض الفيديوهات. يبلغ عرض هذه الصورة 3840 بكسل وارتفاعها 2160 بكسل.
snippet.thumbnails.(key).url string
تمثّل عنوان URL الخاص بالصورة.
snippet.thumbnails.(key).width unsigned integer
تمثّل هذه السمة عرض الصورة.
snippet.thumbnails.(key).height unsigned integer
تمثّل هذه السمة ارتفاع الصورة.
snippet.channelTitle string
تمثّل هذه السمة عنوان القناة التي ينتمي إليها عنصر قائمة التشغيل.
snippet.videoOwnerChannelTitle string
تمثّل هذه السمة عنوان القناة التي حمّلت الفيديو.
snippet.videoOwnerChannelId string
تمثّل هذه السمة معرّف القناة التي حمّلت هذا الفيديو.
snippet.playlistId string
المعرّف الذي يستخدمه YouTube لتحديد قائمة التشغيل التي يتضمّنها عنصر قائمة التشغيل بشكل فريد.
snippet.position unsigned integer
ترتيب ظهور العنصر في قائمة التشغيل تستخدم القيمة فهرسًا يبدأ من الصفر، لذا يكون موضع العنصر الأول 0، وموضع العنصر الثاني 1، وهكذا.
snippet.resourceId object
يحتوي العنصر id على معلومات يمكن استخدامها لتحديد المرجع بشكل فريد والمضمّن في قائمة التشغيل كعنصر في قائمة التشغيل.
snippet.resourceId.kind string
يمثّل هذا الحقل نوع المرجع أو نوع المورد المُشار إليه.
snippet.resourceId.videoId string
إذا كانت قيمة السمة snippet.resourceId.kind هي youtube#video، ستكون هذه السمة متوفّرة وستتضمّن قيمتها المعرّف الذي يستخدمه YouTube لتحديد الفيديو بشكل فريد في قائمة التشغيل.
contentDetails object
يتم تضمين العنصر contentDetails في المرجع إذا كان العنصر المضمّن هو فيديو على YouTube. يحتوي العنصر على معلومات إضافية عن الفيديو.
contentDetails.videoId string
المعرّف الذي يستخدمه YouTube للتعريف عن فيديو بشكل فريد. لاسترداد مرجع video، اضبط مَعلمة طلب البحث id على هذه القيمة في طلب بيانات من واجهة برمجة التطبيقات.
contentDetails.startAt string
ملاحظة: تم إيقاف هذه السمة نهائيًا، وفي حال ضبطها، سيتم تجاهل قيمتها.

الوقت الذي يجب أن يبدأ فيه تشغيل الفيديو، ويتم قياسه بالثواني من بداية الفيديو. (يمكن لمالك قائمة التشغيل تحديد الأوقات التي يجب فيها بدء تشغيل الفيديو وإيقافه عندما يتم تشغيله في سياق قائمة التشغيل). القيمة التلقائية هي 0.
contentDetails.endAt string
ملاحظة: تم إيقاف هذه السمة نهائيًا، وفي حال ضبطها، سيتم تجاهل قيمتها.

الوقت الذي يجب أن يتوقف فيه الفيديو عن التشغيل، ويتم قياسه بالثواني من بداية الفيديو. (يمكن لمالك قائمة التشغيل تحديد الأوقات التي يجب فيها بدء تشغيل الفيديو وإيقافه عندما يتم تشغيله في سياق قائمة التشغيل). افترِض تلقائيًا أنّ video.endTime هو نهاية الفيديو.
contentDetails.note string
ملاحظة من إنشاء المستخدمين لهذا العنصر. يبلغ الحد الأقصى لطول قيمة السمة 280 حرفًا.
contentDetails.videoPublishedAt datetime
يشير هذا الحقل إلى تاريخ ووقت نشر الفيديو على YouTube. يتم تحديد القيمة بالتنسيق ISO 8601.
status object
يحتوي العنصر status على معلومات حول حالة خصوصية عنصر قائمة التشغيل.
status.privacyStatus string
تعرض هذه السمة حالة الخصوصية لعنصر قائمة التشغيل. يمكن للقناة التي حمّلت الفيديو الذي يمثّله عنصر قائمة التشغيل ضبط هذه القيمة باستخدام الطريقتَين videos.insert أو videos.update.