پیاده سازی: فیلم ها

این مثال ویدیوهای آپلود شده در یک کانال خاص را بازیابی می‌کند. این مثال دو مرحله دارد:

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

  برای بازیابی شناسه‌ی لیست پخشی که حاوی ویدیوهای آپلود شده‌ی کانال است، متد channels.list را فراخوانی کنید. مقدار پارامتر part درخواست باید شامل contentDetails به عنوان یکی از بخش‌های منبع channel در حال بازیابی باشد. در پاسخ API، ویژگی contentDetails.relatedPlaylists.uploads حاوی شناسه‌ی لیست پخش است.

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

  • برای بازیابی اطلاعات کانال یوتیوب کاربر احراز هویت شده فعلی، مقدار پارامتر mine را روی true تنظیم کنید. درخواست شما باید با استفاده از OAuth 2.0 تأیید شود.

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

  • پارامتر forUsername را روی یک نام کاربری یوتیوب تنظیم کنید تا اطلاعات مربوط به کانال مرتبط با آن نام کاربری بازیابی شود. این مثال مقدار پارامتر forUsername را روی Google تنظیم می‌کند تا اطلاعات مربوط به کانال رسمی یوتیوب گوگل را بازیابی کند.

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

  • پارامتر id را روی شناسه کانال یوتیوب تنظیم کنید که به طور منحصر به فرد کانالی را که اطلاعات آن را بازیابی می‌کنید، مشخص می‌کند. این مثال پارامتر id را روی UCK8sQmJBp8GCxrOtXWBpyEA تنظیم می‌کند که کانال رسمی یوتیوب گوگل را نیز مشخص می‌کند.

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

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

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

  https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlistItems.list?
          part=snippet,contentDetails,status
          &playlistId=UUK8sQmJBp8GCxrOtXWBpyEA

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

برای بازیابی لیست محبوب‌ترین ویدیوها، متد videos.list را فراخوانی کنید و مقدار پارامتر chart را روی mostPopular تنظیم کنید. نمودار mostPopular شامل موسیقی‌ها، فیلم‌ها و ویدیوهای بازی پرطرفدار است.

سپس، می‌توانید پارامترهای زیر را به صورت اختیاری تنظیم کنید:

• regionCode : به API دستور می‌دهد لیستی از ویدیوها را برای منطقه مشخص شده برگرداند. مقدار پارامتر، کد کشور ISO 3166-1 alpha-2 است. می‌توانید از متد i18nRegions.list برای بازیابی لیستی از کدهای منطقه‌ای که YouTube پشتیبانی می‌کند، استفاده کنید.
• videoCategoryId : دسته‌بندی ویدیویی که محبوب‌ترین ویدیوها باید برای آن بازیابی شوند را مشخص می‌کند. می‌توانید از متد videoCategories.list برای بازیابی لیستی از شناسه‌های دسته‌بندی که یوتیوب پشتیبانی می‌کند، استفاده کنید.

برای مثال، درخواست زیر محبوب‌ترین ویدیوهای ورزشی در اسپانیا را بازیابی می‌کند:

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.list?
        part=snippet
        &chart=mostPopular
        &regionCode=es
        &videoCategoryId=17
  

این مثال با استفاده از متد videos.batchGetStats ، آمار مربوط به لیستی از ویدیوها را بازیابی می‌کند.

برای استفاده از این روش، پارامتر id درخواست را روی لیستی از شناسه‌های ویدیوی یوتیوب که می‌خواهید آمار آنها را بازیابی کنید و با کاما از هم جدا شده‌اند، تنظیم کنید. مقدار پارامتر part را روی لیستی از بخش‌های منبع videoStat که می‌خواهید پاسخ شامل آنها باشد و با کاما از هم جدا شده‌اند، تنظیم کنید. بخش‌های پشتیبانی شده عبارتند از snippet ، statistics ، contentDetails و id .

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

درخواست زیر آمار مربوط به شناسه‌های ویدیویی VIDEO_ID_1 و VIDEO_ID_2 را بازیابی می‌کند:

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.batchGetStats?
        part=snippet,statistics
        &id=VIDEO_ID_1,VIDEO_ID_2

از آنجایی که API Explorer از قابلیت آپلود فایل پشتیبانی نمی‌کند، این توضیحات به یک مثال اجرایی لینک نمی‌دهد. منابع زیر به شما کمک می‌کنند تا برنامه خود را طوری تغییر دهید که بتواند ویدیوها را با استفاده از API نسخه ۳ آپلود کند:

• مستندات مربوط به متد videos.insert مربوط به API شامل چندین نمونه کد است که نحوه آپلود ویدیو با استفاده از زبان‌های برنامه‌نویسی مختلف را توضیح می‌دهد.

• راهنمای آپلودهای از سرگیری‌شده، توالی درخواست‌های HTTP را که یک برنامه برای آپلود ویدیوها با استفاده از فرآیند آپلود از سرگیری‌شده استفاده می‌کند، توضیح می‌دهد. این راهنما در درجه اول برای توسعه‌دهندگانی در نظر گرفته شده است که نمی‌توانند از کتابخانه‌های کلاینت API گوگل استفاده کنند، که برخی از آنها پشتیبانی بومی برای آپلودهای از سرگیری‌شده ارائه می‌دهند.

• مثال جاوا اسکریپت برای آپلود یک ویدیو از CORS (اشتراک‌گذاری منابع بین‌منبعی) برای نشان دادن نحوه آپلود یک فایل ویدیویی از طریق یک صفحه وب استفاده می‌کند. کتابخانه آپلود CORS که API نسخه ۳ از آن استفاده می‌کند، به طور طبیعی از آپلود قابل از سرگیری پشتیبانی می‌کند. علاوه بر این، این مثال نحوه بررسی وضعیت یک ویدیوی آپلود شده را با بازیابی بخش processingDetails از منبع video و همچنین نحوه مدیریت تغییرات وضعیت برای ویدیوی آپلود شده نشان می‌دهد.

این مثال نحوه بررسی وضعیت یک ویدیوی آپلود شده را نشان می‌دهد. ویدیوی آپلود شده بلافاصله در فید ویدیوهای آپلود شده کاربر احراز هویت شده قابل مشاهده خواهد بود. با این حال، این ویدیو تا زمانی که پردازش نشود، در YouTube قابل مشاهده نخواهد بود.

• مرحله ۱: ویدیو را آپلود کنید

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

• مرحله ۲: وضعیت ویدیو را بررسی کنید

  برای بررسی وضعیت ویدیو، متد videos.list را فراخوانی کنید. مقدار پارامتر id را برابر با شناسه ویدیو که در مرحله 1 به دست آمده است، قرار دهید. مقدار پارامتر part را برابر با processingDetails قرار دهید.

  اگر درخواست با موفقیت مدیریت شود، پاسخ API شامل یک منبع video خواهد بود. مقدار ویژگی processingDetails.processingStatus را بررسی کنید تا مشخص شود که آیا YouTube هنوز در حال پردازش ویدیو است یا خیر. مقدار این ویژگی به چیزی غیر از processing ، مانند succeeded یا failed ، تغییر خواهد کرد، زمانی که YouTube پردازش ویدیو را به پایان برساند.

  بدنه درخواست یک منبع video است که در آن ویژگی id شناسه ویدیوی ویدیویی را که حذف می‌کنید، مشخص می‌کند. در این مثال، این منبع همچنین شامل یک شیء recordingDetails است.

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

  https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.list?
          part=snippet,processingDetails
          &id=VIDEO_ID

نکته: برنامه شما می‌تواند از API نظرسنجی کند تا به صورت دوره‌ای وضعیت یک ویدیوی تازه آپلود شده را بررسی کند. پس از پردازش ویدیو، برنامه شما می‌تواند یک بولتن ایجاد کند یا بسته به وضعیت ویدیو، اقدام دیگری را انجام دهد.

این مثال نحوه به‌روزرسانی یک ویدیو برای افزودن اطلاعات مربوط به زمان و مکان ضبط ویدیو را نشان می‌دهد. این مثال شامل مراحل زیر است:

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

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

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

• مرحله ۲: به‌روزرسانی یک ویدیو

  برای به‌روزرسانی یک ویدیوی خاص، متد videos.update را فراخوانی کنید. مقدار پارامتر part را برابر با recordingDetails قرار دهید. (مقدار پارامتر به فیلدهای فراداده‌ای که قرار است به‌روزرسانی شوند بستگی دارد.)

  بدنه درخواست یک منبع video است که در آن ویژگی id شناسه ویدیوی ویدیویی را که شما در حال به‌روزرسانی آن هستید، مشخص می‌کند. در این مثال، این منبع همچنین شامل یک شیء recordingDetails است.

  منبع نمونه زیر نشان می‌دهد که این ویدیو در 30 اکتبر 2013 در بوستون ضبط شده است:

  {
    "id": "VIDEO_ID",
    "recordingDetails": {
      "location": {
        "latitude": "42.3464",
        "longitude": "-71.0975"
      }
      "recordingDate": "2013-10-30T23:15:00.000Z"
    }
  }

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

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

شما می‌توانید از متد thumbnails.set در API نسخه ۳ برای آپلود یک تصویر بندانگشتی سفارشی و تنظیم آن برای یک ویدیو استفاده کنید. در درخواست شما، مقدار پارامتر videoId ، ویدیویی را که قرار است تصویر بندانگشتی برای آن استفاده شود، مشخص می‌کند.

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

نمونه‌های کد مرتبط: PHP ، Python

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

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

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

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

• مرحله ۲: حذف یک ویدیو

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

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

این مثال نحوه گزارش ویدیویی که حاوی محتوای توهین‌آمیز است را نشان می‌دهد. این مثال شامل مراحل زیر است:

• مرحله ۱: شناسه‌هایی را که دلیل گزارش شدن ویدیو را توضیح می‌دهند، بازیابی کنید

  یک درخواست مجاز به متد videoAbuseReportReasons.list ارسال کنید تا لیستی از دلایل معتبر برای علامت‌گذاری یک ویدیو را بازیابی کنید. منبع نمونه videoAbuseReportReason در زیر حاوی اطلاعاتی برای علامت‌گذاری ویدیویی است که حاوی هرزنامه یا محتوای گمراه‌کننده است.

  {
    "kind": "youtube#videoAbuseReportReason",
    "etag": "\"tbWC5XrSXxe1WOAx6MK9z4hHSU8/Or2VqBIilpHU7j__oPzUFCvGVBw\"",
    "id": "S",
    "snippet": {
      "label": "Spam or misleading",
      "secondaryReasons": [
        {
          "id": "27",
          "label": "Spam or mass advertising"
        },
        {
          "id": "28",
          "label": "Misleading thumbnail"
        },
        {
          "id": "29",
          "label": "Malware or phishing"
        },
        {
          "id": "30",
          "label": "Pharmaceutical drugs for sale"
        },
        {
          "id": "31",
          "label": "Other misleading info"
        }
      ]
    }
  }

  همانطور که در منبع نشان داده شده است، این دلیل با فهرستی از دلایل ثانویه مرتبط است. هنگام علامت‌گذاری یک ویدیو به دلیل حاوی هرزنامه بودن، باید شناسه دلیل را ارائه دهید و اکیداً توصیه می‌شود که دلیل ثانویه را نیز ارائه دهید.

• مرحله ۲: ویدیو را به دلیل محتوای توهین‌آمیز پرچم‌گذاری کنید

  یک درخواست مجاز به متد videos.reportAbuse ارسال کنید تا ویدیو را گزارش دهید. بدنه درخواست یک شیء JSON است که هم ویدیوی علامت‌گذاری شده و هم دلیل علامت‌گذاری آن را مشخص می‌کند. همانطور که در مرحله 1 اشاره شد، برای برخی از انواع دلایل، یک دلیل ثانویه پشتیبانی و قویاً توصیه می‌شود.

  ویژگی videoId شیء JSON، ویدیویی را که علامت‌گذاری شده است، شناسایی می‌کند.

  شیء JSON نمونه زیر، ویدیویی را به دلیل داشتن محتوای هرزنامه یا گمراه‌کننده و به طور خاص‌تر، به دلیل استفاده از تصویر کوچک گمراه‌کننده، علامت‌گذاری می‌کند. همانطور که در شیء JSON نمونه بالا نشان داده شده است، شناسه محتوای هرزنامه یا گمراه‌کننده S است. شناسه تصویر کوچک گمراه‌کننده ۲۸ است.

  {
    "videoId": "VIDEO_ID",
    "reasonId": "S",
    "secondaryReasonId": "28",
    "comments": "Testing the video flagging feature.",
    "language": "en"
  }

  درخواست videos.reportAbuse باید با استفاده از OAuth 2.0 مجاز شود. لینک زیر شیء JSON فوق را در APIs Explorer بارگذاری می‌کند. برای آزمایش پرس و جو، باید یک شناسه ویدیوی معتبر را به جای مقدار ویژگی videoId جایگزین کنید. لطفاً به یاد داشته باشید که ارسال این درخواست در واقع ویدیو را علامت‌گذاری می‌کند.

  https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.reportAbuse