‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

پیاده‌سازی: ویدیوها

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

بازیابی ویدیوهای بارگذاری‌شده کانال

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

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

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

چند روش برای شناسایی کانال وجود دارد:
- مقدار پارامتر mine را روی true تنظیم کنید تا اطلاعات کانال YouTube کاربر اصالت‌سنجی‌شده فعلی بازیابی شود. درخواست شما باید بااستفاده از OAuth 2.0 مجاز شود.
```
https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.channels.list?
        part=contentDetails
        &mine=true
```
- پارامتر forUsername را روی نام کاربری YouTube تنظیم کنید تا اطلاعات کانال منسوب به آن نام کاربری را بازیابی کنید. این مثال مقدار پارامتر forUsername را روی Google تنظیم می‌کند تا اطلاعات کانال رسمی YouTube متعلق به Google را بازیابی کند.
```
https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.channels.list?
        part=contentDetails
        &forUsername=Google
```
- پارامتر id را روی شناسه کانال YouTube تنظیم کنید که کانالی را که برای آن اطلاعات را بازیابی می‌کنید به‌طور منحصربه‌فرد شناسایی می‌کند. این مثال پارامتر id را روی UCK8sQmJBp8GCxrOtXWBpyEA تنظیم می‌کند که کانال رسمی YouTube متعلق به Google را نیز شناسایی می‌کند.
```
https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.channels.list?
        part=contentDetails
        &id=UCK8sQmJBp8GCxrOtXWBpyEA
```
مرحله ۲: بازیابی فهرست ویدیوهای بارگذاری‌شده

برای بازیابی فهرست ویدیوهای بارگذاری‌شده، روش playlistItems.list را فراخوانی کنید. مقدار پارامتر playlistId را روی مقدار به‌دست‌آمده در مرحله ۱ تنظیم کنید. در این مثال، مقدار پارامتر روی UUK8sQmJBp8GCxrOtXWBpyEA تنظیم شده است که فهرست ویدیوهای بارگذاری‌شده در کانال رسمی YouTube متعلق به Google است.
```
https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlistItems.list?
        part=snippet,contentDetails,status
        &playlistId=UUK8sQmJBp8GCxrOtXWBpyEA
```

بازیابی پرطرفدارترین ویدیوها

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

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

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

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

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

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

بازیابی آمار ویدیوهای دسته‌ای

این نمونه آمار فهرستی از ویدیوها را بااستفاده از روش videos.batchGetStats بازیابی می‌کند.

برای استفاده از این روش، پارامتر id درخواست را روی فهرست جداشده با کاما از شناسه‌های ویدیو YouTube که می‌خواهید آمار آن‌ها را بازیابی کنید تنظیم کنید. مقدار پارامتر 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 میانای برنامه‌سازی کاربردی حاوی چندین نمونه کد است که نحوه بارگذاری ویدیو بااستفاده از زبان‌های برنامه‌نویسی مختلف را توضیح می‌دهد.
راهنمای بارگذاری‌های قابل‌ازسرگیری توالی درخواست‌های HTTP را توضیح می‌دهد که یک برنامه برای بارگذاری ویدیوها بااستفاده از فرایند بارگذاری قابل‌ازسرگیری استفاده می‌کند. این راهنما در درجه اول برای توسعه‌دهندگانی درنظر گرفته شده است که نمی‌توانند از کتابخانه‌های کارخواه Google API استفاده کنند، برخی‌از این کتابخانه‌ها از بارگذاری‌های ازسرگیری‌پذیر به‌صورت بومی پشتیبانی می‌کنند.
نمونه جاوا اسکریپت برای بارگذاری ویدیو از CORS (هم‌رسانی منبع میان‌مبدئی) استفاده می‌کند تا نحوه بارگذاری فایل ویدیویی ازطریق صفحه وب را نشان دهد. کتابخانه بارگذاری CORS که v3 API از آن استفاده می‌کند به‌طور طبیعی از بارگذاری ازسرگرفتنی پشتیبانی می‌کند. علاوه‌براین، این مثال نشان می‌دهد که چگونه می‌توان وضعیت یک ویدیو بارگذاری‌شده را با بازیابی بخش processingDetails از منبع video بررسی کرد و همچنین چگونه می‌توان تغییرات وضعیت ویدیو بارگذاری‌شده را مدیریت کرد.

بررسی وضعیت ویدیو بارگذاری‌شده

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

مرحله ۱: بارگذاری ویدیو

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

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

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

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

درخواست زیر وضعیت ویدیو را بررسی می‌کند. برای تکمیل درخواست در «کاشف میاناهای برنامه‌سازی کاربردی»، باید مقدار دارایی 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 نیز هست.

منبع نمونه زیر نشان می‌دهد که ویدیو در تاریخ ۳۰ اکتبر ۲۰۱۳ در بوستون ضبط شده است:
```
{
  "id": "VIDEO_ID",
  "recordingDetails": {
    "location": {
      "latitude": "42.3464",
      "longitude": "-71.0975"
    }
    "recordingDate": "2013-10-30T23:15:00.000Z"
  }
}
```
برای تکمیل درخواست در «کاشف میاناهای برنامه‌سازی کاربردی»، باید مقدار دارایی id را تنظیم کنید.
```
https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.update?
        part=snippet
```

مدیریت دسترسی نمانام شریک (دسترسی نمانام شریک آغازشده ازسوی محتواساز)

دسترسی نمانام شریک آغازشده ازسوی محتواساز (CI BPA) به مالک ویدیو اجازه می‌دهد دسترسی به ویدیو خود را با کانال نمانام شریک هم‌رسانی کند. این کار به بخش brandPartner نیاز دارد.

ایجاد دسترسی (درج)

برای ایجاد دسترسی هنگام بارگذاری ویدیو، brandPartner را در پارامتر part اضافه کنید و یک شیء brandPartner در بدنه درخواست ارائه دهید. برای شناسایی کانال نمانام، باید channelId (شناسه کانال خارجی که با «UC» شروع می‌شود) یا channelHandle (که با «@» شروع می‌شود) را مشخص کنید.

POST /youtube/v3/videos?part=snippet,status,brandPartner
{
  "snippet": {
    "title": "Video Title",
    "description": "Video Description",
    "categoryId": "22"
  },
  "status": {
    "privacyStatus": "private"
  },
  "brandPartner": {
    "channelHandle": "@brandchannel"
  }
}

فقط channelId حل‌شده در پاسخ برگردانده خواهد شد.

به‌روزرسانی یا برداشتن دسترسی (به‌روزرسانی)

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

برای جایگزین کردن دسترسی، channelId یا channelHandle جدید را در بدنه درخواست ارائه دهید:

PUT /youtube/v3/videos?part=brandPartner
{
  "id": "VIDEO_ID",
  "brandPartner": {
    "channelId": "UC_SOME_BRAND_CHANNEL_ID"
  }
}

برای برداشتن دسترسی، در پارامتر part درخواستی با brandPartner ارسال کنید، اما با شیء brandPartner خالی در بدنه درخواست:

PUT /youtube/v3/videos?part=brandPartner
{
  "id": "VIDEO_ID",
  "brandPartner": {}
}

بارگذاری تصویر ریزعکس سفارشی و تنظیم آن برای ویدیو

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

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

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

حذف کردن ویدیو

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

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

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

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

برای حذف یک ویدیو خاص، روش videos.delete را فراخوانی کنید. در درخواست، پارامتر id شناسه ویدیو ویدیویی را که حذف می‌کنید مشخص می‌کند. درخواست باید بااستفاده از OAuth 2.0 مجاز شود. اگر این پُرسمان را در «کاوشگر میاناهای برنامه‌سازی کاربردی» آزمایش می‌کنید، باید شناسه ویدیو معتبری را جایگزین مقدار پارامتر 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 است که هم ویدیو پرچم‌گذاری‌شده و هم دلیل پرچم‌گذاری آن را مشخص می‌کند. همان‌طور که در مرحله ۱ ذکر شد، برای برخی‌از انواع دلایل، دلیل ثانویه پشتیبانی می‌شود و به‌شدت توصیه می‌شود.
ویژگی 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 بالا را در «کاوشگر میاناهای برنامه‌سازی کاربردی» بار می‌کند. برای آزمایش پُرسمان، باید مقدار دارایی videoId را با شناسه ویدیو معتبری جایگزین کنید. لطفاً به‌یاد داشته باشید که ارسال این درخواست درواقع ویدیو را پرچم‌گذاری می‌کند.
```
https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.reportAbuse
```

پیاده‌سازی: ویدیوها با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.