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

این صفحه نمونه درخواست‌های YouTube Data API را نشان می‌دهد. از YouTube Data API برای بازیابی و دستکاری منابع YouTube مانند ویدیوها، کانال‌ها، و فهرست‌های پخش استفاده می‌کنید. هر نمونه به Google APIs Explorer پیوند داده می‌شود و آن را پر می‌کند تا بتوانید نمونه را اجرا کنید و پاسخ را ببینید.

برای اطلاعات درباره بارگذاری محتوا بااستفاده از YouTube Data API، به بارگذاری‌های قابل‌ازسرگیری مراجعه کنید.

نمای کلی

برای شفافیت ارائه، نمونه‌های موجود در این صفحه عناصر متمایز هر درخواست را نشان می‌دهند و نشانی وب پایه را برای میزبانی که درخواست‌های Data API را پردازش می‌کند (https://www.googleapis.com/youtube/v3) به‌صورت اختصاری نشان می‌دهند. برای ایجاد درخواست خارج از زمینه نمونه‌ها، باید نشانی وب کامل را اضافه کنید.

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

GET {base-URL}/channels?part=contentDetails
                       &mine=true

نشانی وب کامل این درخواست عبارت است از:

GET https://www.googleapis.com/youtube/v3/channels?part=contentDetails
                                                  &mine=true

چندین درخواست داده‌هایی را بازیابی می‌کنند که فقط برای مالک کانال YouTube قابل‌دسترسی است، مانند فهرست مشترکان. این درخواست‌ها مستلزم این است که مالک کانال به Google APIs Explorer اجازه دهد تا درخواست‌های YouTube Data API را ازطرف او انجام دهد. (برای جزئیات مربوط به صدور مجوز دسترسی به داده‌های کانال خصوصی، به پیاده‌سازی اصالت‌سنجی OAuth 2.0 مراجعه کنید.) پس‌از پیوند دادن به «کاوشگر API»، روی دکمه مجوز دادن به درخواست‌ها بااستفاده از OAuth 2.0 کلیک کنید. این مرحله به API Explorer اجازه می‌دهد تا ازطرف مالک درخواست ارسال کند. همچنین دامنه مجوز را انتخاب می‌کنید که انواع درخواست‌هایی را که «کاوشگر API» می‌تواند انجام دهد مشخص می‌کند.

پاسخ به هر درخواست، نمایش JSON از یک منبع YouTube است. پارامتر part در درخواست مشخص می‌کند کدام بخش‌های منبع در پاسخ گنجانده شده است. این پارامتر یک یا چند ویژگی منبع سطح بالا (غیرتو در تو) را که باید در پاسخ گنجانده شود شناسایی می‌کند. برای مثال، برخی‌از بخش‌های منبع ویدیو عبارت‌اند از:

• تکه‌کد
• contentDetails
• بازیکن
• آمار
• وضعیت

همه این بخش‌ها اشیایی هستند که حاوی دارایی‌های تودرتو هستند و می‌توانید این اشیا را به‌عنوان گروه‌هایی از فیلدهای فراداده درنظر بگیرید که ممکن است کارگزار API آن‌ها را بازیابی کند (یا نکند). به همین دلیل، پارامتر part از شما می‌خواهد مؤلفه‌های منبعی را که برنامه‌تان واقعاً استفاده می‌کند انتخاب کنید. برای اطلاعات بیشتر، به شروع به کار با YouTube Data API مراجعه کنید.

بازیابی اطلاعات کانال

این درخواست از روش channels.list برای بازیابی جزئیات مربوط به کانال‌های متعلق به کاربر اصالت‌سنجی‌شده استفاده می‌کند.

GET {base_URL}/channels?part=contentDetails
                       &mine=true

پاسخ به این درخواست شامل شناسه کانال و contentDetails برای کانال کاربر اصالت‌سنجی‌شده است. contentDetails شامل چندین فهرست پخش تولیدشده توسط سیستم مرتبط با کانال می‌شود. بسیاری از درخواست‌های بعدی به شناسه کانال یا یکی از شناسه‌های فهرست پخش نیاز دارند، بنابراین ثبت آن‌ها مهم است.

{
  "id": {CHANNEL_ID},
  "kind": "youtube#channel",
  "etag": etag,
  "contentDetails": {
    "relatedPlaylists": {
      "likes": {LIKES_PLAYLIST_ID},
      "favorites": {FAVORITES_PLAYLIST_ID},
      "uploads": {UPLOADS_PLAYLIST_ID},
      "watchHistory": {WATCHHISTORY_PLAYLIST_ID},
      "watchLater": {WATCHLATER_PLAYLIST_ID}
    },
    "googlePlusUserId": string
  },
}

ویدیوهای بارگذاری‌شده و فهرست‌های پخش تولیدشده توسط سیستم

YouTube همه ویدیوهای بارگذاری‌شده را به فهرست پخشی که با کانال مرتبط است اضافه می‌کند. برای دریافت فهرستی از ویدیوهای بارگذاری‌شده، فهرست پخش «بارگذاری‌ها» را که در پاسخ نشان‌داده‌شده در بالا برای اطلاعات کانال برگردانده شده است، بااستفاده از روش playlistItems.list برای بازیابی ویدیوهای آن فهرست پخش، جستجو می‌کنید.

قبل‌از اجرای درخواست نمونه زیر در Google APIs Explorer،‏ {UPLOADS_PLAYLIST_ID} را با شناسه فهرست پخش از درخواست قبلی جایگزین کنید.

GET {base_URL}/playlistItems?part=contentDetails
                            &playlistId={UPLOADS_PLAYLIST_ID}

توجه داشته باشید که مقدار "id" برای هر مورد برگردانده‌شده، شناسه playlistItem آن است. شناسه ویدیو برای مورد فهرست پخش videoId در بخش contentDetails است.

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

فهرست‌های پخش ایجادشده توسط کاربر

این درخواست از روش playlists.list برای بازیابی فهرست‌های پخش مرتبط با کانال اصالت‌سنجی‌شده استفاده می‌کند. توجه داشته باشید که این درخواست فهرست‌های پخش تولیدشده توسط سیستم که در اطلاعات کانال (بارگذاری‌ها، سابقه تماشا، و غیره) گنجانده شده‌اند را بازیابی نمی‌کند. این روش فقط فهرست‌های پخش ایجادشده توسط کاربر را بازیابی می‌کند.

GET {base_URL}/playlists?part=snippet
                        &mine=true

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

می‌توانید بدون اصالت‌سنجی، اطلاعاتی درباره فهرست‌های پخش عمومی کانال درخواست کنید. وقتی درخواست اصالت‌سنجی‌نشده‌ای ارسال می‌کنید، باید آرگومان key را که کلید API یکتای برنامه درخواست‌کننده را مشخص می‌کند اضافه کنید. برای مثال، این درخواست فهرست‌های پخش مرتبط با کانال GoogleDevelopers را بازیابی می‌کند.

GET {base_URL}/playlists?part=snippet
                        &channelId=UC_x5XG1OV2P6uZZ5FSM9Ttw
                        &key={YOUR_API_KEY}

بازیابی اشتراک‌ها

یک منبع subscription رابطه بین یک کاربر YouTube (مشترک) و یک کانال را تعریف می‌کند. روش subscriptions.list مشترکین یک کانال خاص یا اشتراک‌های یک کاربر خاص را بازیابی می‌کند، بسته به اینکه کدام پارامترها را در درخواست قرار دهید.

مشترکین کانال

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

GET {base_URL}/subscriptions?part=snippet
                            &mySubscribers=true

اشتراک‌های کاربر

از همان روشی که مشترکین را فهرست می‌کند (subscriptions.list) می‌توان برای فهرست کردن کانال‌هایی که کاربر در آن‌ها مشترک است استفاده کرد. این درخواست از پارامتر mine برای بازیابی فهرست کانال‌های YouTube که کاربر اصالت‌سنجی‌شده در آن‌ها مشترک است استفاده می‌کند.

GET {base_URL}/subscriptions?part=snippet
                            &mine=true

بازیابی فعالیت کاربر

یک منبع activity حاوی اطلاعاتی درباره اقدامی است که یک کانال یا کاربر خاص در YouTube انجام داده است – بارگذاری ویدیو، اشتراک در یک کانال، و غیره. روش activities.list کنش‌های مرتبط با کانال یا کاربری را که با معیارهای درخواست مطابقت دارند بازیابی می‌کند. برای مثال، می‌توانید کنش‌های مرتبط با یک کانال خاص، با اشتراک‌های کاربر، یا با صفحه اصلی سفارشی YouTube کاربر را بازیابی کنید.

فعالیت درطول یک دوره زمانی

این درخواست همه کنش‌هایی را که کاربر اصالت‌سنجی‌شده در آوریل ۲۰۱۳ انجام داده است بازیابی می‌کند.

GET {base_URL}/activities?part=snippet,contentDetails
                         &mine=true
                         &publishedAfter=2013-04-01T00%3A00%3A00Z
                         &publishedBefore=2013-05-01T00%3A00%3A00Z

فعالیت صفحه اصلی

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

GET {base_URL}/activities?part=snippet,contentDetails
                         &home=true

برای بازیابی آمار بازدید، سنجه‌های محبوبیت، و اطلاعات جمعیت‌شناسی ویدیوها و کانال‌های YouTube، از YouTube Analytics API استفاده می‌کنید. صفحه درخواست‌های نمونه API نحوه بازیابی گزارش‌های رایج از YouTube Analytics را نشان می‌دهد.

جستجو

روش search.list به شما امکان می‌دهد ویدیوها، کانال‌ها، یا فهرست‌های پخش YouTube را که با معیارهای مشخص‌شده مطابقت دارند جستجو کنید. می‌توانید براساس ویژگی‌های ویدیو، کلیدواژه‌ها، یا موضوعات (یا ترکیبی از این موارد) جستجو کنید و نتایج را براساس عواملی مانند تاریخ ایجاد، تعداد بازدید، یا رتبه‌بندی مرتب کنید.

مانند سایر درخواست‌های YouTube Data API، روش search.list نمایش JSON یک منبع YouTube را برمی‌گرداند. بااین‌حال، برخلاف سایر منابع YouTube، نتیجه جستجو یک شیء پایدار با شناسه یکتا نیست.

بسیاری از درخواست‌ها به‌دنبال محتوای دردسترس عمومی هستند و بنابراین نیازی به اصالت‌سنجی ندارند. از میان نمونه‌های زیر، فقط نمونه اول به اصالت‌سنجی نیاز دارد، زیرا به‌طور خاص ویدیوهای «من» را درخواست می‌کند. وقتی درخواست تأییدنشده‌ای ارسال می‌کنید، باید آرگومان key را که کلید میانای برنامه‌سازی کاربردی یکتا را برای برنامه‌تان مشخص می‌کند اضافه کنید.

پربازدیدترین ویدیوهای من

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

GET {base_URL}/search?part=snippet
                     &forMine=true
                     &order=viewCount
                     &type=video

ویدیوهای با وضوح بالا قابل‌جاسازی

این درخواست ویدیوهایی را جستجو می‌کند که ویژگی‌های خاصی دارند، یعنی ویدیوهای با وضوح بالا که می‌توانند در سایت‌های دیگر جاسازی شوند. نتایج را به‌ترتیب نزولی رده‌بندی فهرست می‌کند.

GET {base_URL}/search?part=snippet
                     &order=rating
                     &type=video
                     &videoDefinition=high
                     &videoEmbeddable=true
                     &key={YOUR_API_KEY}

ویدیوهایی درباره یک موضوع خاص

این درخواست جستجوی کلیدواژه‌ای برای ویدیوهای مربوط به YouTube Data API که دارای زیرنویس ناشنوایان هستند انجام می‌دهد.

GET {base_URL}/search?part=snippet
                     &q=YouTube+Data+API
                     &type=video
                     &videoCaption=closedCaption
                     &key={YOUR_API_KEY}

جستجوی موضوع‌محور

یک روش پیچیده‌تر برای جستجوی ویدیوها درباره یک موضوع خاص، استفاده از موضوعات Freebase به‌جای کلیدواژه‌ها است. کانال YouTube و منابع ویدیو همگی حاوی یک شیء topicDetails هستند که شامل فهرستی از شناسه‌های موضوع Freebase مرتبط با منبع است. جستجوی مبتنی بر موضوع هوشمندتر از جستجوی کلیدواژه‌ای است، زیرا موضوع Freebase نشان‌دهنده همه جنبه‌های مفهوم یا چیز دنیای واقعی است.

برای جستجو بااستفاده از موضوع Freebase، ابتدا باید شناسه موضوع را بااستفاده از Freebase API بازیابی کنید. این درخواست ویدیوهای مرتبط با موضوع Freebase برای Python را برمی‌گرداند که شناسه موضوع آن /m/05z1_ است.

GET {base_URL}/search?part=snippet
                     &topicId=/m/05z1_
                     &type=video
                     &key={YOUR_API_KEY}

درحال جستجوی فهرست‌های پخش یا کانال‌ها

جستجو به ویدیوها محدود نمی‌شود. همچنین می‌توانید فهرست‌های پخش یا کانال‌ها را جستجو کنید. این درخواست فهرست‌های پخشی را بازیابی می‌کند که با کلیدواژه «فوتبال» مطابقت دارند.

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &type=playlist
                     &key={YOUR_API_KEY}

اگر ترجیح می‌دهید کانال‌های فوتبال را پیدا کنید، کافی است پارامتر type را تغییر دهید.

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &type=channel
                     &key={YOUR_API_KEY}

اگر می‌خواهید همه محتوای مربوط به فوتبال (کانال‌ها، فهرست‌های پخش، و ویدیوها) را ببینید، می‌توانید جستجوی جهانی انجام دهید. اگر پارامتر type را حذف کنید، درخواست محتوای همه انواع را بازیابی می‌کند

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &key={YOUR_API_KEY}

ایجاد و به‌روزرسانی منابع

درخواست‌هایی که تاکنون بررسی کرده‌ایم همگی از روش HTTP GET برای بازیابی داده‌های YouTube استفاده می‌کنند. YouTube Data API همچنین روش‌هایی را ارائه می‌دهد که از HTTP POST برای ایجاد یا به‌روزرسانی منابع YouTube مانند ویدیوها، فهرست‌های پخش یا کانال‌ها استفاده می‌کنند. درخواست‌های زیر نمونه‌هایی ارائه می‌دهند.

روش‌های POST شامل Request body است که نمایش JSON منبع درحال ایجاد یا به‌روزرسانی است. بااستفاده از ابزاری تعاملی می‌توانید نمایش‌های JSON را در «کاوشگر Google APIs» ایجاد کنید.

ایجاد کردن اشتراک

این درخواست کاربر اصالت‌سنجی‌شده را در کانال GoogleDevelopers مشترک می‌کند. به بیانی دیگر، منبع اشتراک ایجاد می‌کند.

POST {base_URL}/subscriptions?part=snippet
 Request body:
  {
    'snippet': {
      'resourceId': {
        'kind': 'youtube#channel',
        'channelId': 'UC_x5XG1OV2P6uZZ5FSM9Ttw' 
       }
     }
  }

ایجاد فهرست پخش

این درخواست یک فهرست پخش عمومی جدید ایجاد می‌کند.

POST {base_URL}/playlists?part=snippet
 Request body:
  {
    'snippet': {
      'title': 'New playlist', 
      'description': 'Sample playlist for Data API',
     }
  }

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

اکنون که فهرست پخش ایجاد کردیم، بیایید ویدیویی به آن اضافه کنیم. این درخواست ویدیویی را به ابتدای فهرست پخش ('position': 0) اضافه می‌کند.

POST {base_URL}/playlistItems?part=snippet
  Request body:
  {
    'snippet': {
      'playlistId': '{PLAYLIST_ID}', 
      'resourceId': {
          'kind': 'youtube#video',
          'videoId': '{VIDEO_ID}'
        }
     'position': 0
      }
   }