نمونه درخواست های API

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

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

بررسی اجمالی

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

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

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 مراجعه کنید.) پس از پیوند دادن به APIs Explorer، روی دکمه تأیید درخواست‌ها با استفاده از OAuth 2.0 کلیک کنید. این مرحله به APIs Explorer اجازه می دهد تا از طرف مالک درخواست کند. شما همچنین محدوده مجوز را انتخاب می‌کنید، که نوع درخواست‌هایی را که APIs Explorer می‌تواند انجام دهد، مشخص می‌کند.

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

• قطعه
• جزئیات محتوا
• بازیکن
• آمار
• وضعیت

همه این بخش‌ها اشیایی هستند که دارای ویژگی‌های تودرتو هستند، و می‌توانید این اشیاء را به عنوان گروه‌هایی از فیلدهای ابرداده در نظر بگیرید که سرور 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" برای هر آیتم بازگردانده شده 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 سفارشی کاربر را بازیابی کنید.

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

این درخواست همه اقداماتی را که کاربر احراز هویت شده در آوریل 2013 انجام داده است، بازیابی می کند.

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

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

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

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

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

جستجو کردن

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

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

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

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

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

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 به جای کلمات کلیدی است. کانال یوتیوب و منابع ویدئویی همگی حاوی یک شی 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 Explorer ایجاد کنید.

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

این درخواست کاربر احراز هویت شده را در کانال 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
      }
   }