نمای کلی API داده YouTube

مقدمه

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

قبل از شروع

1. برای دسترسی به کنسول API گوگل، درخواست کلید API و ثبت برنامه خود، به یک حساب کاربری گوگل نیاز دارید.

2. یک پروژه در کنسول توسعه‌دهندگان گوگل ایجاد کنید و اعتبارنامه‌های لازم را دریافت کنید تا برنامه شما بتواند درخواست‌های API ارسال کند.

3. پس از ایجاد پروژه خود، مطمئن شوید که API داده یوتیوب یکی از سرویس‌هایی است که برنامه شما برای استفاده از آن ثبت شده است:

   1. به کنسول API بروید و پروژه‌ای را که ثبت کرده‌اید انتخاب کنید.
   2. به صفحه APIهای فعال‌شده مراجعه کنید. در لیست APIها، مطمئن شوید که وضعیت برای YouTube Data API نسخه ۳ روشن است.

4. اگر برنامه شما از هر روش API که نیاز به مجوز کاربر دارد استفاده می‌کند، راهنمای احراز هویت را برای یادگیری نحوه پیاده‌سازی مجوز OAuth 2.0 مطالعه کنید.

5. برای ساده‌سازی پیاده‌سازی API خود، یک کتابخانه کلاینت انتخاب کنید.

6. با مفاهیم اصلی قالب داده JSON (نمادگذاری شیء جاوا اسکریپت) آشنا شوید. JSON یک قالب داده رایج و مستقل از زبان است که نمایش متنی ساده‌ای از ساختارهای داده دلخواه را ارائه می‌دهد. برای اطلاعات بیشتر، به json.org مراجعه کنید.

منابع و انواع منابع

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

توجه داشته باشید که در بسیاری از موارد، یک منبع شامل ارجاعاتی به منابع دیگر است. برای مثال، ویژگی snippet.resourceId.videoId یک منبع playlistItem یک منبع ویدیویی را شناسایی می‌کند که به نوبه خود حاوی اطلاعات کاملی در مورد ویدیو است. به عنوان مثال دیگر، یک نتیجه جستجو شامل یک ویژگی videoId ، playlistId یا channelId است که یک منبع ویدیو، لیست پخش یا کانال خاص را شناسایی می‌کند.

عملیات پشتیبانی شده

جدول زیر رایج‌ترین متدهایی را که API پشتیبانی می‌کند نشان می‌دهد. برخی منابع همچنین از متدهای دیگری پشتیبانی می‌کنند که عملکردهای خاص‌تری را برای آن منابع انجام می‌دهند. به عنوان مثال، متد videos.rate امتیاز کاربر را به یک ویدیو مرتبط می‌کند و متد thumbnails.set تصویر کوچک یک ویدیو را در YouTube آپلود کرده و آن را به یک ویدیو مرتبط می‌کند.

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

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

استفاده از سهمیه

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

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

توجه: اگر به حد نصاب سهمیه رسیدید، می‌توانید با تکمیل فرم درخواست تمدید سهمیه برای سرویس‌های API یوتیوب، سهمیه اضافی درخواست کنید.

محاسبه میزان استفاده از سهمیه

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

• یک عملیات خواندن که لیستی از منابع -- کانال‌ها، ویدیوها، لیست‌های پخش -- را بازیابی می‌کند، معمولاً ۱ واحد هزینه دارد.
• یک عملیات نوشتن که یک منبع را ایجاد، به‌روزرسانی یا حذف می‌کند، معمولاً 50 واحد هزینه دارد.
• هزینه یک درخواست جستجو 100 واحد است.
• هزینه آپلود یک ویدیو 100 واحد است.

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

منابع جزئی

این API امکان بازیابی منابع جزئی را فراهم می‌کند و در واقع آن را الزامی می‌داند تا برنامه‌ها از انتقال، تجزیه و ذخیره داده‌های غیرضروری اجتناب کنند. این رویکرد همچنین تضمین می‌کند که API از منابع شبکه، CPU و حافظه به طور کارآمدتری استفاده می‌کند.

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

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

نحوه استفاده از پارامتر part

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

• snippet
• contentDetails
• fileDetails
• player
• processingDetails
• recordingDetails
• statistics
• status
• suggestions
• topicDetails

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

• این قابلیت با جلوگیری از صرف وقت سرور API برای بازیابی فیلدهای فراداده‌ای که برنامه شما از آنها استفاده نمی‌کند، تأخیر را کاهش می‌دهد.
• با کاهش (یا حذف) میزان داده‌های غیرضروری که برنامه شما ممکن است بازیابی کند، استفاده از پهنای باند را کاهش می‌دهد.

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

نحوه استفاده از پارامتر fields

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

قوانین زیر، سینتکس پشتیبانی‌شده برای مقدار پارامتر fields را توضیح می‌دهند که تا حدودی مبتنی بر سینتکس XPath است:

• برای انتخاب چندین فیلد از یک لیست جدا شده با کاما ( fields=a,b ) استفاده کنید.
• برای مشخص کردن همه فیلدها از علامت ستاره ( fields=* ) به عنوان wildcard استفاده کنید.
• از پرانتز ( fields=a(b,c) ) برای مشخص کردن گروهی از ویژگی‌های تو در تو که در پاسخ API گنجانده خواهند شد، استفاده کنید.
• برای مشخص کردن یک ویژگی تو در تو، از یک اسلش ( fields=a/b ) استفاده کنید.

در عمل، این قوانین اغلب به چندین مقدار پارامتر fields مختلف اجازه می‌دهند تا پاسخ API یکسانی را بازیابی کنند. برای مثال، اگر می‌خواهید شناسه، عنوان و موقعیت آیتم لیست پخش را برای هر آیتم در یک لیست پخش بازیابی کنید، می‌توانید از هر یک از مقادیر زیر استفاده کنید:

• fields=items/id,playlistItems/snippet/title,playlistItems/snippet/position
• fields=items(id,snippet/title,snippet/position)
• fields=items(id,snippet(title,position))

توجه: همانند تمام مقادیر پارامترهای پرس‌وجو، مقدار پارامتر fields باید به صورت URL کدگذاری شود. برای خوانایی بهتر، مثال‌های این سند از کدگذاری صرف نظر کرده‌اند.

نمونه درخواست‌های جزئی

مثال‌های زیر نشان می‌دهند که چگونه می‌توانید از پارامترهای part و fields استفاده کنید تا مطمئن شوید که پاسخ‌های API فقط شامل داده‌هایی هستند که برنامه شما استفاده می‌کند:

1. مثال ۱ یک منبع ویدیویی را برمی‌گرداند که شامل چهار بخش و همچنین ویژگی‌های kind و etag است.
2. مثال ۲ یک منبع ویدیویی را برمی‌گرداند که شامل دو بخش و همچنین ویژگی‌های kind و etag است.
3. مثال ۳ یک منبع ویدیویی را برمی‌گرداند که شامل دو بخش است اما ویژگی‌های kind و etag را شامل نمی‌شود.
4. مثال ۴ یک منبع ویدیویی را برمی‌گرداند که شامل دو بخش است اما kind و etag و همچنین برخی از ویژگی‌های تو در تو در شیء snippet منبع را شامل نمی‌شود.

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,contentDetails,statistics,status

Description: This example retrieves a video resource and identifies several
             resource parts that should be included in the API response.

API response:

{ 
 "kind": "youtube#videoListResponse",
 "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "kind": "youtube#video",
   "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "contentDetails": {
    "duration": "PT15M51S",
    "aspectRatio": "RATIO_16_9"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   },
   "status": {
    "uploadStatus": "STATUS_PROCESSED",
    "privacyStatus": "PRIVACY_PUBLIC"
   }
  }
 ]
}

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics

Description: This example modifies the part parameter value so that the
             contentDetails and status properties are not included
             in the response.

API response:

{ 
 "kind": "youtube#videoListResponse",
 "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "kind": "youtube#video",
   "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics&fields=items(id,snippet,statistics)

Description: This example adds the fields parameter to remove all
             kind and etag properties from the API response.

API response:

{ 
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &fields=items(id,snippet(channelId,title,categoryId),statistics)&part=snippet,statistics

Description: This example modifies the fields parameter from example 3
             so that in the API response, each video resource's snippet
             object only includes the channelId, title,
             and categoryId properties.

API response:

{ 
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "snippet": { 
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}

بهینه‌سازی عملکرد

Accept-Encoding: gzip
User-Agent: my program (gzip)