پیاده‌سازی: فهرست‌های پخش

مثال‌های زیر نشان می‌دهند که چگونه از YouTube Data API (v3) برای انجام عملکردهای مربوط به فهرست‌های پخش و موارد فهرست پخش استفاده کنید.

بازیابی فهرست‌های پخش کاربر کنونی

برای بازیابی فهرست‌های پخش کاربر اصالت‌سنجی‌شده فعلی، روش playlists.list را فراخوانی کنید. در درخواستتان، مقدار پارامتر mine را روی true تنظیم کنید. توجه داشته باشید که درخواستی که از پارامتر mine استفاده می‌کند باید بااستفاده از OAuth 2.0 مجاز شود.

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlists.list?
        part=snippet,contentDetails
        &mine=true

بازیابی فهرست‌های پخش کاربر

این مثال فهرست‌های پخش ایجادشده توسط یک کانال خاص را بازیابی می‌کند. این مثال دو مرحله دارد:

• مرحله ۱: بازیابی شناسه کانال

  روش channels.list را برای بازیابی شناسه کانال مرتبط با نام کاربری YouTube خاصی فراخوانی کنید. (در این مثال، نام کاربری GoogleDevelopers است.) در پاسخ میانای برنامه‌سازی کاربردی، ویژگی id شناسه کانال را مشخص می‌کند.

  https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.channels.list?
          part=id
          &forUsername=GoogleDevelopers

• مرحله ۲: بازیابی فهرست‌های پخش کانال

  برای بازیابی فهرست‌های پخش کانال، روش playlists.list را فراخوانی کنید. مقدار پارامتر channelId را روی مقدار به‌دست‌آمده در مرحله ۱ تنظیم کنید.

  https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlists.list?
          part=snippet,contentDetails
          &channelId=UC_x5XG1OV2P6uZZ5FSM9Ttw

بازیابی اطلاعات درباره یک فهرست پخش خاص

برای بازیابی اطلاعات مربوط به یک یا چند فهرست پخش خاص، روش playlists.list را فراخوانی کنید و پارامتر id را روی فهرستی از شناسه‌های فهرست پخش YouTube تنظیم کنید که با کاما از هم جدا شده‌اند و منابع موردنظر را شناسایی می‌کنند. یک مورد استفاده رایج برای این عملکرد، درخواست بازیابی اطلاعات اضافی درباره گروهی از فهرست‌های پخش است که در مجموعه‌ای از نتایج جستجو برگردانده شده‌اند. برای مثال، ممکن است بخواهید تعداد موارد موجود در هر فهرست پخش را بازیابی کنید.

درخواست زیر متد playlists.list را برای بازیابی تعداد موارد در دو فهرست پخش که با عبارت پُرسمان «GoogleDevelopers» مطابقت دارند فرا می‌خواند. این اطلاعات در ویژگی contentDetails.itemCount منبع playlist قرار دارد، بنابراین درخواست مقدار پارامتر part را روی contentDetails تنظیم می‌کند.

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlists.list?
        part=contentDetails
        &id=PLOU2XLYxmsIIM9h1Ybw2DuRw6o2fkNMeR,PLyYlLs02rgBYRWBzYpoHz7m2SE8mEZ68w

افزودن فهرست پخش

این مثال روش playlists.insert را برای ایجاد یک فهرست پخش خصوصی در کانال کاربر اصالت‌سنجی‌شده فراخوانی می‌کند. هرگونه درخواست API به این روش باید بااستفاده از OAuth 2.0 مجاز شود.

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlists.insert?
        part=snippet,status

پیوند «کاوشگر میاناهای برنامه‌سازی کاربردی» همچنین پارامتری را تنظیم می‌کند که بدنه درخواست «میانای برنامه‌سازی کاربردی» را مشخص می‌کند. بدنه درخواست حاوی منبع playlist است که اطلاعاتی مانند عنوان، توضیحات و وضعیت حریم خصوصی فهرست پخش را تعریف می‌کند. در این مثال، متن درخواست عبارت است از:

{
  "snippet": {
    "title": "New playlist",
    "description": "New playlist description"
  },
  "status": {
    "privacyStatus": "private"
  }
}

مثال زیر فهرست پخش جدید را به‌عنوان نمایش پادکست علامت‌گذاری می‌کند:

{
  "snippet": {
    "title": "New playlist",
    "description": "New playlist description"
  },
  "status": {
    "podcastStatus": "enabled"
  }
}

نمونه‌های کد مرتبط: Java،‏ JavaScript،‏ .NET،‏ PHP،‏ Python

به‌روزرسانی کردن فهرست پخش

این نمونه وضعیت حریم خصوصی فهرست پخش را از private به public به‌روز می‌کند. این مثال دو مرحله دارد:

• مرحله ۱: بازیابی شناسه فهرست پخش

  روش playlists.list را برای بازیابی فهرست‌های پخش در کانال کاربر اصالت‌سنجی‌شده فعلی فراخوانی کنید. درخواست نمونه بالا برای بازیابی فهرست‌های پخش کاربر فعلی این درخواست را نشان می‌دهد. برنامه‌ای که میانای برنامه‌سازی کاربردی را فراخوانی می‌کند می‌تواند پاسخ میانای برنامه‌سازی کاربردی را پردازش کند تا فهرستی از فهرست‌های پخش را نمایش دهد و از شناسه هر فهرست پخش به‌عنوان کلید استفاده کند.

• مرحله ۲: به‌روزرسانی فهرست پخش

  برای اصلاح فهرست پخش خاصی، روش playlists.update را فراخوانی کنید. این روش به یک کد مجوز OAuth 2.0 معتبر نیاز دارد.

  بدنه درخواست باید شامل بخش snippet منبع playlist باشد زیرا هنگام فراخوانی این روش، دارایی snippet.title الزامی است. علاوه‌براین، اگر منبع فهرست پخش درحال به‌روزرسانی مقادیر snippet.description یا snippet.tags را مشخص کند، آن مقادیر باید در درخواست به‌روزرسانی دوباره مشخص شوند، درغیراین‌صورت حذف خواهند شد.

  https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlists.update?
          part=snippet,status

  همانند مثال بالا برای افزودن فهرست پخش، پیوند به «کاوشگر میاناهای برنامه‌سازی کاربردی» پارامتری را تنظیم می‌کند که بدنه درخواست میانای برنامه‌سازی کاربردی را مشخص می‌کند. بدنه درخواست حاوی منبع playlist است که اطلاعاتی مانند عنوان، شرح، و وضعیت حریم خصوصی فهرست پخش را تعریف می‌کند. در این مثال از بدنه درخواست زیر استفاده شده است:

  {
    "id": "PLAYLIST_ID",
    "snippet": {
      "title": "New playlist",
      "description": "New playlist description"
    },
    "status": {
      "privacyStatus": "public"
    }
  }

  مثال زیر فهرست پخش را به‌عنوان نمایش پادکست علامت‌گذاری می‌کند:

  {
    "id": "PLAYLIST_ID",
    "snippet": {
      "title": "New playlist",
      "description": "New playlist description"
    },
    "status": {
      "podcastStatus": "enabled"
    }
  }

  توجه: اگر این پُرسمان را در APIs Explorer آزمایش می‌کنید، باید شناسه فهرست پخش معتبری را در بدنه منبع جایگزین کنید. برای دریافت شناسه فهرست پخش، توصیه می‌کنیم ابتدا درخواست نشان‌داده‌شده در بالا را برای افزودن فهرست پخش اجرا کنید. شناسه فهرست پخش را از پاسخ میانای برنامه‌سازی کاربردی استخراج کنید و از آن مقدار برای فهرست پخشی که می‌خواهید به‌روز کنید استفاده کنید. عنوان و شرح فهرست پخش استفاده‌شده در این مثال همان عنوان و شرح استفاده‌شده در آن مثال است.

افزودن مورد فهرست پخش

این نمونه موردی را به فهرست پخش اضافه می‌کند. این درخواست باید بااستفاده از OAuth 2.0 مجاز شود. این مثال دو مرحله دارد:

• مرحله ۱: بازیابی شناسه فهرست پخش مناسب

  روش playlists.list را فراخوانی کنید تا فهرست‌های پخش در کانال کاربر اصالت‌سنجی‌شده فعلی را بازیابی کنید. درخواست نمونه بالا برای بازیابی فهرست‌های پخش کاربر فعلی این درخواست را نشان می‌دهد. برنامه‌ای که میانای برنامه‌سازی کاربردی را فراخوانی می‌کند می‌تواند پاسخ میانای برنامه‌سازی کاربردی را پردازش کند تا فهرستی از فهرست‌های پخش را نمایش دهد و از شناسه هر فهرست پخش به‌عنوان کلید استفاده کند.

• مرحله ۲: افزودن ویدیو به فهرست پخش

  برای افزودن ویدیو به فهرست پخش، روش playlistItems.insert را فراخوانی کنید. این درخواست باید بااستفاده از OAuth 2.0 مجاز شود. بدنه درخواست منبع playlistItem است که حداقل مقادیر زیر را مشخص می‌کند:

  • snippet.playlistId فهرست پخشی را که ویدیو را به آن اضافه می‌کنید، شناسایی می‌کند. این شناسه فهرست پخشی است که در مرحله ۱ به‌دست آوردید.
  • ‫snippet.resourceId.kind حاوی مقدار youtube#video است.
  • snippet.resourceId.videoId ویدیویی را که به فهرست پخش اضافه می‌کنید شناسایی می‌کند. مقدار دارایی یک شناسه ویدیو YouTube یکتا است.

  درخواست API زیر یک ویدیو را به فهرست پخش اضافه می‌کند. متن درخواست:

  {
    "snippet": {
      "playlistId": "PLAYLIST_ID",
      "resourceId": {
        "kind": "youtube#video",
        "videoId": "VIDEO_ID"
      }
    }
  }

  برای تکمیل درخواست در APIs Explorer، باید مقادیری برای ویژگی‌های snippet.playlistId و snippet.resourceId.videoId تنظیم کنید.

  https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlistItems.insert?
          part=snippet

  توجه: مستندات مربوط به روش playlistItems.insert مقادیر ویژگی دیگری را که می‌توانید هنگام افزودن یک مورد فهرست پخش تنظیم کنید، شناسایی می‌کند.

افزودن تصویر فهرست پخش

می‌توانید از روش playlistImages.insert در API نسخه ۳ برای بارگذاری تصویر ریزعکس سفارشی و تنظیم آن برای فهرست پخش استفاده کنید. در درخواست شما، مقدار پارامتر playlistId فهرست پخشی را که تصویر کوچک برای آن استفاده خواهد شد، شناسایی می‌کند.

این پُرسمان را نمی‌توان بااستفاده از APIs Explorer آزمایش کرد زیرا APIs Explorer از قابلیت بارگذاری فایل‌های رسانه‌ای که برای این روش الزامی است پشتیبانی نمی‌کند.

به‌روزرسانی کردن مورد فهرست پخش

این نمونه یک مورد فهرست پخش را به‌روزرسانی می‌کند تا اولین مورد در فهرست پخش باشد. این درخواست باید بااستفاده از OAuth 2.0 مجاز شود. این مثال سه مرحله دارد:

• مرحله ۱: شناسه فهرست پخش مناسب را بازیابی کنید

  روش playlists.list را برای بازیابی فهرست‌های پخش در کانال کاربر اصالت‌سنجی‌شده فعلی فراخوانی کنید. نمونه درخواست بالا برای بازیابی فهرست‌های پخش کاربر فعلی این درخواست را نشان می‌دهد. برنامه‌ای که API را فرا می‌خواند می‌تواند پاسخ API را پردازش کند تا فهرستی از فهرست‌های پخش را بااستفاده از شناسه هر فهرست پخش به‌عنوان کلید نمایش دهد.

• مرحله ۲: بازیابی موارد در فهرست پخش انتخاب‌شده

  برای بازیابی فهرست ویدیوها در فهرست پخش انتخاب‌شده، روش playlistItems.list را فراخوانی کنید. مقدار پارامتر playlistId را روی شناسه فهرست پخشی که در مرحله ۱ به‌دست آوردید تنظیم کنید.

  هر منبع در پاسخ API شامل یک ویژگی id است که شناسه عنصر فهرست پخش را مشخص می‌کند و آن عنصر را به‌صورت منحصربه‌فرد شناسایی می‌کند. در مرحله بعد، از آن مقدار برای برداشتن موردی از فهرست استفاده خواهید کرد.

• مرحله ۳: به‌روزرسانی مورد فهرست پخش انتخاب‌شده

  برای تغییر جایگاه ویدیو در فهرست پخش، روش playlistItems.update را فراخوانی کنید. مقدار پارامتر part را روی snippet تنظیم کنید. بدنه درخواست باید منبع playlistItem باشد که حداقل مقادیر زیر را تنظیم کند:

  • ویژگی id را روی شناسه مورد فهرست پخش که در مرحله ۲ به‌دست آمده است تنظیم کنید.
  • ویژگی snippet.playlistId را روی شناسه فهرست پخش به‌دست‌آمده در مرحله ۱ تنظیم کنید.
  • خصوصیت snippet.resourceId.kind را روی youtube#video تنظیم کنید.
  • ویژگی snippet.resourceId.videoId را روی شناسه ویدیویی تنظیم کنید که ویدیو موجود در فهرست پخش را به‌طور منحصربه‌فرد شناسایی می‌کند.
  • دارایی snippet.position را روی 0 یا هر موقعیت دیگری که می‌خواهید مورد در آنجا نشان داده شود تنظیم کنید (بااستفاده از نمایه مبتنی بر ۰).

  درخواست API زیر یک مورد فهرست پخش را به‌روزرسانی می‌کند تا اولین مورد در فهرست پخش باشد. متن درخواست این است:

  {
    "id": "PLAYLIST_ITEM_ID",
    "snippet": {
      "playlistId": "PLAYLIST_ID",
      "resourceId": {
        "kind": "youtube#video",
        "videoId": "VIDEO_ID"
      },
      "position": 0
    }
  }

  برای تکمیل درخواست در APIs Explorer، باید مقادیری برای ویژگی‌های id، snippet.playlistId، و snippet.resourceId.videoId تنظیم کنید.

  https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlistItems.update?
          part=snippet

به‌روزرسانی کردن تصویر فهرست پخش

می‌توانید از روش playlistImages.update در v3 API برای به‌روزرسانی تصویر کوچک فهرست پخش استفاده کنید. در درخواست شما، مقدار پارامتر playlistId فهرست پخشی را که تصویر کوچک برای آن استفاده خواهد شد مشخص می‌کند.

این پُرسمان را نمی‌توان بااستفاده از APIs Explorer آزمایش کرد زیرا APIs Explorer از قابلیت بارگذاری فایل‌های رسانه‌ای که برای این روش الزامی است پشتیبانی نمی‌کند.

برداشتن موردی از فهرست پخش

این نمونه ویدیویی را از فهرست پخش حذف می‌کند. این درخواست باید بااستفاده از OAuth 2.0 مجاز شود. این مثال سه مرحله دارد. دو مرحله اول همانند مراحل مثال بالا برای به‌روزرسانی مورد فهرست پخش است.

پس‌از تکمیل این مراحل، متد playlistItems.delete را برای حذف ویدیو از فهرست پخش فراخوانی کنید. پارامتر id درخواست را روی شناسه عنصر فهرست پخش برای عنصری که می‌خواهید بردارید تنظیم کنید. این درخواست باید بااستفاده از OAuth 2.0 مجاز شود.

توجه داشته باشید که شناسه مورد فهرست پخش که برای شناسایی ویدیو در فهرست پخش استفاده می‌شود با شناسه ویدیو YouTube که ویدیو را به‌طور منحصربه‌فرد شناسایی می‌کند متفاوت است. شناسه عنصر فهرست پخش ویدیو را به‌عنوان عنصری در یک فهرست پخش خاص شناسایی می‌کند.

برای تکمیل درخواست در APIs Explorer، باید مقدار ویژگی id را تنظیم کنید.

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlistItems.delete?
        id=PLAYLIST_ITEM_ID

برداشتن تصویر فهرست پخش

این نمونه تصویر فهرست پخش را حذف می‌کند. این مثال دو مرحله دارد:

• مرحله ۱: بازیابی فهرست پخش

  روش playlists.list را فراخوانی کنید تا فهرست‌های پخش در کانال کاربر اصالت‌سنجی‌شده فعلی را بازیابی کنید. نمونه درخواست بالا برای بازیابی فهرست‌های پخش کاربر فعلی این درخواست را نشان می‌دهد. برنامه‌ای که میانای برنامه‌سازی کاربردی را فراخوانی می‌کند می‌تواند پاسخ میانای برنامه‌سازی کاربردی را پردازش کند تا فهرستی از فهرست‌های پخش را نمایش دهد و از شناسه هر فهرست پخش به‌عنوان کلید استفاده کند.

• مرحله ۲: بازیابی شناسه تصویر فهرست پخش

  برای بازیابی تصویر ریزعکس فهرست پخش، روش playlistImages.list را فراخوانی کنید. از شناسه فهرست پخش برای فهرست پخشی که می‌خواهید تغییر دهید استفاده کنید.

• مرحله ۳: حذف تصویر فهرست پخش

  برای حذف تصویر فهرست پخش خاص، روش playlistImages.delete را فراخوانی کنید. در درخواست، پارامتر id شناسه تصویر فهرست پخش درحال حذف را مشخص می‌کند. این روش به کد مجوز OAuth 2.0 معتبر نیاز دارد. اگر این پُرسمان را در APIs Explorer آزمایش می‌کنید، باید مقدار پارامتر id را با شناسه فهرست پخش معتبری جایگزین کنید.

  https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlistImages.delete?
          id=ID

  توجه: اگر این پُرسمان را در «کاوشگر میاناهای برنامه‌سازی کاربردی» آزمایش می‌کنید، باید مقدار پارامتر id را با شناسه تصویر فهرست پخش معتبری جایگزین کنید.

برداشتن فهرست پخش

این نمونه فهرست پخش را حذف می‌کند. این مثال دو مرحله دارد:

• مرحله ۱: بازیابی شناسه فهرست پخش

  برای بازیابی فهرست‌های پخش در کانال کاربر اصالت‌سنجی‌شده فعلی، روش playlists.list را فراخوانی کنید. درخواست نمونه بالا برای بازیابی فهرست‌های پخش کاربر فعلی این درخواست را نشان می‌دهد. برنامه‌ای که میانای برنامه‌سازی کاربردی را فراخوانی می‌کند می‌تواند پاسخ میانای برنامه‌سازی کاربردی را پردازش کند تا فهرستی از فهرست‌های پخش را نمایش دهد و از شناسه هر فهرست پخش به‌عنوان کلید استفاده کند.

• مرحله ۲: حذف کردن فهرست پخش

  برای حذف فهرست پخش خاصی، روش playlists.delete را فراخوانی کنید. در درخواست، پارامتر id شناسه فهرست پخش فهرست پخشی را که حذف می‌شود مشخص می‌کند. این روش به کد مجوز OAuth 2.0 معتبر نیاز دارد. اگر این پُرسمان را در APIs Explorer آزمایش می‌کنید، باید مقدار پارامتر id را با شناسه فهرست پخش معتبری جایگزین کنید.

  https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlists.delete?
          id=PLAYLIST_ID

  توجه: اگر این پُرسمان را در APIs Explorer آزمایش می‌کنید، باید مقدار پارامتر id را با شناسه فهرست پخش معتبر جایگزین کنید. برای دریافت شناسه فهرست پخش، توصیه می‌کنیم ابتدا درخواست نشان‌داده‌شده در بالا را برای افزودن فهرست پخش اجرا کنید. شناسه فهرست پخش را از پاسخ میانای برنامه‌سازی کاربردی استخراج کنید و از آن مقدار برای فهرست پخشی که می‌خواهید حذف کنید استفاده کنید.