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

مقدمه

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

قبل از شروع

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

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

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

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

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

5. برای ساده کردن اجرای API خود، یک کتابخانه مشتری انتخاب کنید.

6. با مفاهیم اصلی قالب داده JSON (جاوا اسکریپت Object Notation) آشنا شوید. 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 پیدا کنید.

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

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

محاسبه میزان مصرف

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

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

جدول هزینه های سهمیه برای درخواست های 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=* ) به عنوان علامت عام استفاده کنید.
• از پرانتز ( 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. مثال 1 یک منبع ویدیویی را برمی گرداند که شامل چهار بخش و همچنین ویژگی های kind و etag .
2. مثال 2 یک منبع ویدیویی را برمی گرداند که شامل دو بخش و همچنین ویژگی های kind و etag .
3. مثال 3 یک منبع ویدیویی را برمی گرداند که شامل دو بخش است اما ویژگی های kind و etag را استثنا نمی کند.
4. مثال 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)