این سند توضیح می‌دهد که چگونه مجوز OAuth 2.0 را برای دسترسی به YouTube Data API بااستفاده از برنامه‌هایی که روی دستگاه‌هایی مانند تلویزیون، کنسول بازی، و چاپگر اجرا می‌شوند، پیاده‌سازی کنید. به‌طور دقیق‌تر، این جریان برای دستگاه‌هایی طراحی شده است که یا به مرورگر دسترسی ندارند یا قابلیت‌های ورودی محدودی دارند.
OAuth 2.0 به کاربران اجازه می‌دهد داده‌های خاصی را با برنامه هم‌رسانی کنند و درعین‌حال نام‌های کاربری، گذرواژه‌ها، و سایر اطلاعات خود را خصوصی نگه دارند. برای مثال، یک برنامه تلویزیون می‌تواند از OAuth 2.0 برای دریافت اجازه انتخاب فایل ذخیره‌شده در Google Drive استفاده کند.
ازآنجایی‌که برنامه‌هایی که از این جریان استفاده می‌کنند در دستگاه‌های شخصی توزیع می‌شوند، فرض می‌شود که برنامه‌ها نمی‌توانند اسرار را حفظ کنند. این برنامه‌ها می‌توانند وقتی کاربر در برنامه حضور دارد یا وقتی برنامه در پس‌زمینه اجرا می‌شود به Google APIs دسترسی داشته باشند.
جایگزین‌ها
اگر برای پلاتفرمی مثل Android، iOS، macOS، Linux، یا Windows (ازجمله «پلاتفرم جهانی Windows») برنامه می‌نویسید که به مرورگر و قابلیت‌های ورودی کامل دسترسی دارد، از جریان OAuth 2.0 برای برنامه‌های تلفن همراه و رایانه استفاده کنید. (حتی اگر برنامه شما ابزار خط فرمان بدون رابط گرافیکی باشد، باید از این جریان استفاده کنید.)
اگر فقط می‌خواهید کاربران را با «حساب Google» خودشان به سیستم وارد کنید و از JWT شناسه ژتون برای دریافت اطلاعات نمایه کاربر پایه استفاده کنید، ورود به سیستم در تلویزیون‌ها و دستگاه‌های ورودی محدود را ببینید.
پیش‌نیازها
فعال کردن میاناهای برنامه‌سازی کاربردی برای پروژه
هر برنامه‌ای که میاناهای برنامه‌سازی کاربردی Google را فراخوانی می‌کند باید آن میاناهای برنامه‌سازی کاربردی را در «کنسول میانای برنامه‌سازی کاربردی» فعال کند.
برای فعال کردن میانای برنامه‌سازی کاربردی برای پروژه‌تان:
- کتابخانه میانای برنامه‌سازی کاربردی را در «کنسول Google API» باز کنید.
- اگر درخواست شد، پروژه‌ای را انتخاب کنید یا پروژه جدیدی ایجاد کنید.
- از صفحه «کتابخانه» برای یافتن و فعال کردن YouTube Data API استفاده کنید. هر API دیگری را که برنامه‌تان استفاده خواهد کرد پیدا کنید و آنها را نیز فعال کنید.
ایجاد اعتبارنامه‌های مجوز
هر برنامه‌ای که از OAuth 2.0 برای دسترسی به Google API استفاده می‌کند باید اعتبارنامه مجوز داشته باشد که برنامه را برای سرور OAuth 2.0 Google شناسایی کند. مراحل زیر نحوه ایجاد اعتبارنامه برای پروژه‌تان را توضیح می‌دهد. سپس برنامه‌هایتان می‌توانند از این اطلاعات اعتباری برای دسترسی به میاناهای برنامه‌سازی کاربردی‌ای که برای آن پروژه فعال کرده‌اید استفاده کنند.
- به صفحه «کارخواهان» بروید.
- روی ایجاد مشتری کلیک کنید.
- نوع برنامه تلویزیون‌ها و دستگاه‌های ورودی محدود را انتخاب کنید.
- نامی برای کارخواه OAuth 2.0 خود انتخاب کنید و روی ایجاد کلیک کنید.
شناسایی کردن دامنه‌های دسترسی
محدوده‌ها به برنامه شما امکان می‌دهند فقط به منابعی که نیاز دارد دسترسی پیدا کند و درعین‌حال به کاربران امکان می‌دهند میزان دسترسی‌ای را که به برنامه شما می‌دهند کنترل کنند. بنابراین، ممکن است بین تعداد گستره‌های درخواستی و احتمال دریافت رضایت کاربر رابطه معکوس وجود داشته باشد.
پیش‌از اینکه پیاده‌سازی مجوز OAuth 2.0 را شروع کنید، توصیه می‌کنیم محدوده‌هایی را که برنامه‌تان برای دسترسی به آنها به اجازه نیاز دارد شناسایی کنید.
YouTube Data API v3 از دامنه‌های زیر استفاده می‌کند:
| دامنه | توضیحات |
|---|---|
https://www. googleapis. com/ auth/ youtube | حساب YouTube خود را مدیریت کنید |
https://www. googleapis. com/ auth/ youtube. channel-memberships. creator | فهرستی از اعضای فعال فعلی کانال خود، سطح فعلی آنها و زمان عضویت آنها را مشاهده کنید |
https://www. googleapis. com/ auth/ youtube. force-ssl | ویدیوها، رتبه‌بندی‌ها، نظرات و زیرنویس‌های YouTube خود را مشاهده، ویرایش و برای همیشه حذف کنید |
https://www. googleapis. com/ auth/ youtube. readonly | حساب YouTube خود را مشاهده کنید |
https://www. googleapis. com/ auth/ youtube. upload | ویدیوهای YouTube خود را مدیریت کنید |
https://www. googleapis. com/ auth/ youtubepartner | دارایی ها و محتوای مرتبط خود را در YouTube مشاهده و مدیریت کنید |
https://www. googleapis. com/ auth/ youtubepartner-channel-audit | اطلاعات خصوصی مربوط به کانال YouTube خود را در طول فرآیند ممیزی با شریک YouTube مشاهده کنید |
فهرست گستره‌های مجاز را برای برنامه‌ها یا دستگاه‌های نصب‌شده ببینید.
دریافت کدهای دسترسی OAuth 2.0
اگرچه برنامه شما در دستگاهی با قابلیت‌های ورودی محدود اجرا می‌شود، کاربران باید دسترسی جداگانه‌ای به دستگاهی با قابلیت‌های ورودی غنی‌تر داشته باشند تا این جریان مجوز را تکمیل کنند. جریان مراحل زیر را دارد:
- برنامه شما درخواستی به سرور صدور مجوز Google ارسال می‌کند که دامنه‌هایی را که برنامه شما برای دسترسی به آنها اجازه درخواست می‌کند، شناسایی می‌کند.
- سرور با چند قطعه اطلاعات که در مراحل بعدی استفاده می‌شود پاسخ می‌دهد، مثلاً کد دستگاه و کد کاربر.
- اطلاعاتی را نمایش می‌دهید که کاربر می‌تواند در دستگاهی جداگانه وارد کند تا به برنامه شما اجازه دهد.
- برنامه شما شروع به نظرسنجی از سرور مجوز Google می‌کند تا تعیین کند کاربر برنامه شما را مجاز کرده است یا نه.
- کاربر به دستگاهی با قابلیت‌های ورودی غنی‌تر می‌رود، مرورگر وب را راه‌اندازی می‌کند، به نشانی وب نمایش‌داده‌شده در مرحله ۳ می‌رود و کدی را که در مرحله ۳ نیز نمایش داده شده است وارد می‌کند. سپس کاربر می‌تواند دسترسی به برنامه شما را اعطا (یا رد) کند.
- پاسخ بعدی به درخواست نظرسنجی شما حاوی نشانه‌هایی است که برنامه شما برای مجاز کردن درخواست‌ها ازطرف کاربر به آنها نیاز دارد. (اگر کاربر دسترسی به برنامه شما را رد کرد، پاسخ شامل کدها نمی‌شود.)
تصویر این فرایند را نشان می‌دهد:
بخش‌های زیر این مراحل را به‌طور دقیق توضیح می‌دهند. با توجه به طیف قابلیت‌ها و محیط‌های زمان اجرایی که دستگاه‌ها ممکن است داشته باشند، نمونه‌های نشان‌داده‌شده در این سند از ابزار خط فرمان curl استفاده می‌کنند. این نمونه‌ها را می‌توان به زبان‌ها و زمان‌های اجرای مختلف منتقل کرد.
مرحله ۱: درخواست کدهای دستگاه و کاربر
در این مرحله، دستگاهتان درخواست HTTP POST را به سرور مجوز Google در
https://oauth2.googleapis.com/device/code ارسال می‌کند که برنامه شما را
و همچنین محدوده‌های دسترسی را که برنامه شما می‌خواهد ازطرف کاربر به آنها دسترسی داشته باشد شناسایی می‌کند.
باید این نشانی وب را از
سند «اکتشاف» بااستفاده از
مقدار فراداده device_authorization_endpoint بازیابی کنید. پارامترهای درخواست اچ‌تی‌تی‌پی زیر را
اضافه کنید:
| پارامترها | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
الزامی
شناسه کارخواه برای برنامه شما. می‌توانید این مقدار را در صفحه «کارخواه‌ها» در «کنسول Cloud» پیدا کنید. |
||||||||||||||||
scope |
الزامی
فهرست جداشده با فاصله از حوزه‌هایی که منابعی را که برنامه شما می‌تواند ازطرف کاربر به آنها دسترسی داشته باشد شناسایی می‌کند. این مقادیر به صفحه موافقت که Google به کاربر نمایش می‌دهد اطلاع می‌دهد. فهرست دامنه‌های مجاز را برای برنامه‌ها یا دستگاه‌های نصب‌شده ببینید. گستره‌ها به برنامه شما امکان می‌دهند فقط به منابعی که نیاز دارد دسترسی داشته باشد و درعین‌حال به کاربران امکان می‌دهند میزان دسترسی‌ای را که به برنامه شما می‌دهند کنترل کنند. بنابراین، رابطه‌ای معکوس بین تعداد دامنه‌های درخواستی و احتمال کسب رضایت کاربر وجود دارد. YouTube Data API v3 از دامنه‌های زیر استفاده می‌کند:
سند OAuth 2.0 API Scopes فهرست کاملی از دامنه‌هایی که ممکن است برای دسترسی به Google APIs استفاده کنید ارائه می‌دهد. |
||||||||||||||||
مثال‌ها
قطعه کد زیر یک درخواست نمونه را نشان می‌دهد:
POST /device/code HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl
این مثال فرمان curl را برای ارسال همان درخواست نشان می‌دهد:
curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl" \
https://oauth2.googleapis.com/device/code
مرحله ۲: مدیریت پاسخ سرور مجوز
سرور صدور مجوز یکی از پاسخ‌های زیر را برمی‌گرداند:
پاسخ موفق
اگر درخواست معتبر باشد، پاسخ شما یک شیء JSON خواهد بود که حاوی ویژگی‌های زیر است:
| مشخصات | |
|---|---|
device_code |
مقداری که Google به‌طور منحصربه‌فرد برای شناسایی دستگاهی که برنامه درخواست‌کننده مجوز را اجرا می‌کند اختصاص می‌دهد. کاربر آن دستگاه را از دستگاه دیگری با قابلیت‌های ورودی غنی‌تر
مجاز خواهد کرد. برای مثال، کاربر ممکن است از رایانه کیفی یا تلفن همراه برای مجاز کردن برنامه‌ای که در تلویزیون اجرا می‌شود استفاده کند. در این مورد، device_code تلویزیون را شناسایی می‌کند.
این کد به دستگاهی که برنامه را اجرا می‌کند اجازه می‌دهد به‌طور ایمن تعیین کند که کاربر دسترسی را اعطا کرده است یا نه. |
expires_in |
مدت زمانی، برحسب ثانیه، که device_code و
user_code معتبر هستند. اگر در این مدت کاربر جریان
مجوزدهی را تکمیل نکند و دستگاه شما نیز برای بازیابی اطلاعات مربوط به تصمیم کاربر
نظرسنجی نکند، ممکن است لازم باشد این فرایند را از مرحله ۱ شروع کنید. |
interval |
مدت زمانی، برحسب ثانیه، که دستگاهتان باید بین درخواست‌های نظرسنجی منتظر بماند. برای
مثال، اگر مقدار 5 باشد، دستگاه شما باید هر پنج ثانیه یک درخواست
نظرسنجی به سرور مجوز Google ارسال کند. برای جزئیات بیشتر،
مرحله ۳ را ببینید. |
user_code |
مقداری حساس به حروف بزرگ و کوچک که دامنه‌هایی را که برنامه درخواست دسترسی به آنها را دارد برای Google مشخص می‌کند. میانای کاربر شما به کاربر دستور می‌دهد این مقدار را در دستگاه جداگانه‌ای با قابلیت‌های ورودی غنی‌تر وارد کند. سپس Google از این مقدار برای نمایش مجموعه صحیح دامنه‌ها هنگام درخواست از کاربر برای اعطای دسترسی به برنامه شما استفاده می‌کند. |
verification_url |
نشانی وبی که کاربر باید در دستگاهی جداگانه به آن پیمایش کند تا
user_code را وارد کند و دسترسی به برنامه شما را اعطا یا رد کند. میانای کاربر شما
نیز این مقدار را نمایش خواهد داد. |
قطعه کد زیر نمونه‌ای از پاسخ را نشان می‌دهد:
{ "device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8", "user_code": "GQVQ-JKEC", "verification_url": "https://www.google.com/device", "expires_in": 1800, "interval": 5 }
پاسخ فراتر رفتن از سهمیه
اگر درخواست‌های کد دستگاه شما از سهمیه مرتبط با شناسه مشتری‌تان فراتر رفته باشد، پاسخ ۴۰۳ دریافت خواهید کرد که حاوی خطای زیر است:
{ "error_code": "rate_limit_exceeded" }
در این صورت، از استراتژی عقب‌نشینی برای کاهش نرخ درخواست‌ها استفاده کنید.
مرحله ۳: نمایش کد کاربر
verification_url و user_code به‌دست‌آمده در مرحله ۲ را به کاربر نمایش دهید. هر دو مقدار می‌توانند شامل هر نویسه چاپ‌شدنی از مجموعه نویسه‌های US-ASCII باشند. محتوایی که به کاربر نمایش می‌دهید باید به کاربر دستور دهد که در دستگاهی جداگانه به verification_url برود و user_code را وارد کند.
واسط کاربر (UI) خود را با درنظر گرفتن قوانین زیر طراحی کنید:
user_codeuser_codeباید در فیلدی نمایش داده شود که بتواند ۱۵ نویسه با اندازه «W» را در خود جای دهد. به‌عبارت دیگر، اگر بتوانید کدWWWWWWWWWWWWWWWرا به‌درستی نمایش دهید، واسط کاربر شما معتبر است و توصیه می‌کنیم هنگام آزمایش نحوه نمایشuser_codeدر واسط کاربرتان، از آن مقدار رشته استفاده کنید.user_codeبه حروف بزرگ و کوچک حساس است و نباید به هیچ وجه تغییر کند، مثلاً تغییر حروف یا درج نویسه‌های قالب‌بندی دیگر.
verification_url- فضایی که
verification_urlرا در آن نمایش می‌دهید باید به‌اندازه کافی عریض باشد تا بتواند رشته نشانی وبی با طول ۴۰ نویسه را در خود جای دهد. - نباید
verification_urlرا به‌هیچ‌وجه تغییر دهید، به‌جز اینکه به‌صورت اختیاری طرح را برای نمایش بردارید. اگر قصد دارید طرح را به‌دلایل نمایشی از نشانی وب حذف کنید (مثلاًhttps://)، مطمئن شوید که برنامه‌تان می‌تواند هر دو نوعhttpوhttpsرا مدیریت کند.
- فضایی که
مرحله ۴: نظرسنجی از سرور مجوز Google
ازآنجایی‌که کاربر از دستگاه جداگانه‌ای برای پیمایش به verification_url
و اعطای (یا رد کردن) دسترسی استفاده می‌کند، وقتی کاربر به درخواست دسترسی پاسخ می‌دهد، دستگاه درخواست‌کننده به‌طور خودکار مطلع نمی‌شود. به همین دلیل، دستگاه درخواست‌کننده باید سرور مجوز Google را نظرسنجی کند تا مشخص شود کاربر چه زمانی به درخواست پاسخ داده است.
دستگاه درخواست‌کننده باید به ارسال درخواست‌های نظرسنجی ادامه دهد تا زمانی که پاسخی دریافت کند که نشان دهد کاربر به درخواست دسترسی پاسخ داده است یا تا زمانی که device_code
و user_code به‌دست‌آمده در
مرحله ۲ منقضی شوند. interval برگردانده‌شده در مرحله ۲ مقدار زمان انتظار بین درخواست‌ها را برحسب ثانیه مشخص می‌کند.
نشانی وب نقطه پایان برای نظرسنجی https://oauth2.googleapis.com/token است. درخواست نظرسنجی
شامل پارامترهای زیر است:
| پارامترها | |
|---|---|
client_id |
شناسه کارخواه برای برنامه شما. این مقدار را می‌توانید در «کنسول Cloud» صفحه «کارخواه‌ها» پیدا کنید. |
client_secret |
رمز کارخواه برای client_id ارائه‌شده. این مقدار را می‌توانید در
«کنسول Cloud»
صفحه «کارخواه‌ها» پیدا کنید. |
device_code |
device_code که توسط سرور صدور مجوز در
مرحله ۲ برگردانده شده است. |
grant_type |
این مقدار را روی urn:ietf:params:oauth:grant-type:device_code تنظیم کنید. |
مثال‌ها
قطعه کد زیر یک درخواست نمونه را نشان می‌دهد:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=client_id& client_secret=client_secret& device_code=device_code& grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code
این مثال فرمان curl را برای ارسال همان درخواست نشان می‌دهد:
curl -d "client_id=client_id&client_secret=client_secret& \
device_code=device_code& \
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
-H "Content-Type: application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/tokenمرحله ۵: کاربر به درخواست دسترسی پاسخ می‌دهد
تصویر زیر صفحه‌ای شبیه به آنچه را نشان می‌دهد که کاربران هنگام پیمایش به
verification_url که در مرحله ۳ نمایش دادید می‌بینند:
پس‌از وارد کردن user_code و، اگر قبلاً به سیستم وارد نشده باشد، وارد شدن به سیستم Google،
کاربر صفحه رضایت را می‌بیند:
مرحله ۶: رسیدگی به پاسخ‌های درخواست‌های نظرسنجی
سرور مجوز Google به هر درخواست نظرسنجی با یکی از پاسخ‌های زیر پاسخ می‌دهد: پاسخ‌ها:
دسترسی داده شد
اگر کاربر دسترسی به دستگاه را اعطا کرده باشد (با کلیک کردن روی Allow در صفحه رضایت)،
پاسخ حاوی کد دسترسی و ژتون بازآوری است. این توکن‌ها به دستگاهتان امکان می‌دهند
ازطرف کاربر به میاناهای برنامه‌سازی کاربردی Google دسترسی داشته باشد. (ویژگی scope
در پاسخ تعیین می‌کند که دستگاه به کدام میاناهای برنامه‌سازی کاربردی
می‌تواند دسترسی داشته باشد.)
در این مورد، پاسخ API شامل فیلدهای زیر است:
| فیلدها | |
|---|---|
access_token |
کدی که برنامه شما برای مجاز کردن درخواست Google API ارسال می‌کند. |
expires_in |
مدت‌زمان باقی‌مانده کد دسترسی برحسب ثانیه. |
refresh_token |
نشانهای که می‌توانید از آن برای دریافت نشانه دسترسی جدید استفاده کنید. ژتون‌های بازآوری تا زمانی معتبر هستند که کاربر دسترسی را لغو کند یا ژتون بازآوری منقضی شود. توجه داشته باشید که نشانهای بازآوری همیشه برای دستگاه‌ها برگردانده می‌شوند. |
scope |
حوزه‌های دسترسی اعطاشده توسط access_token به‌صورت فهرستی از
رشته‌های حساس به حروف بزرگ و کوچک که با فاصله از هم جدا شده‌اند. |
token_type |
نوع کد برگردانده‌شده. این مقدار همیشه Bearer است. |
تکه‌کد زیر پاسخ نمونه‌ای را نشان می‌دهد:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email", "token_type": "Bearer", "refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
کدهای دسترسی طول عمر محدودی دارند. اگر برنامه شما برای مدت طولانی به دسترسی به API نیاز دارد، می‌تواند از کد بازآوری استفاده کند تا کد دسترسی جدیدی دریافت کند. اگر برنامه شما به این نوع دسترسی نیاز دارد، باید رمز بازآوری را برای استفاده‌های بعدی ذخیره کند.
دسترسی امکان‌پذیر نیست
اگر کاربر از اعطای دسترسی به دستگاه خودداری کند، پاسخ سرور دارای
403 کد وضعیت پاسخ HTTP (Forbidden) است. پاسخ حاوی خطای زیر است:
{ "error": "access_denied", "error_description": "Forbidden" }
مجوز دردست انجام است
اگر کاربر هنوز جریان صدور مجوز را تکمیل نکرده باشد، سرور کد وضعیت پاسخ HTTP (428) را برمی‌گرداند. پاسخ حاوی خطای زیر است:Precondition Required
{ "error": "authorization_pending", "error_description": "Precondition Required" }
نظرسنجی بیش‌ازحد مکرر
اگر دستگاه درخواست‌های نظرسنجی را بیش‌ازحد ارسال کند، سرور کد وضعیت پاسخ HTTP 403 (Forbidden) را برمی‌گرداند. پاسخ حاوی خطای زیر است:
{ "error": "slow_down", "error_description": "Forbidden" }
خطاهای دیگر
اگر درخواست نظرسنجی فاقد هریک از پارامترهای الزامی باشد یا مقدار پارامتر نادرست باشد، سرور مجوز نیز خطا برمی‌گرداند. این درخواست‌ها معمولاً دارای کد وضعیت پاسخ HTTP 400
(Bad Request) یا 401 (Unauthorized) هستند. این خطاها شامل موارد زیر می‌شود:
| خطا | رمز وضعیت HTTP | شرح |
|---|---|---|
admin_policy_enforced |
400 |
«حساب Google» به‌دلیل خط‌مشی‌های سرپرست Google Workspace خود نمی‌تواند یک یا چند حوزه درخواستی را مجاز کند. برای اطلاعات بیشتر درباره اینکه سرپرست چگونه می‌تواند دسترسی به دامنه‌ها را تا زمانی که دسترسی صریحاً به شناسه کارخواه OAuth شما اعطا شود محدود کند، به مقاله راهنمای سرپرست Google Workspace با عنوان کنترل اینکه کدام برنامه‌های داخلی و طرف سوم به داده‌های Google Workspace دسترسی داشته باشند مراجعه کنید. |
invalid_client |
401 |
کارخواه OAuth پیدا نشد. برای مثال، این خطا زمانی رخ می‌دهد که
مقدار پارامتر نوع کارخواه OAuth نادرست است. مطمئن شوید که نوع برنامه برای شناسه مشتری روی تلویزیون‌ها و دستگاه‌های ورودی محدود تنظیم شده باشد. |
invalid_grant |
400 |
مقدار پارامتر code نامعتبر است، قبلاً ادعا شده است، یا نمی‌تواند
تجزیه شود. |
unsupported_grant_type |
400 |
مقدار پارامتر grant_type نامعتبر است. |
org_internal |
403 |
شناسه کارخواه OAuth در درخواست بخشی از پروژه‌ای است که دسترسی به «حساب‌های Google» را در «سازمان Google Cloud» خاصی محدود می‌کند. پیکربندی نوع کاربر را برای برنامه OAuth خود تأیید کنید. |
فراخوانی میاناهای برنامه‌سازی کاربردی Google
پس‌از اینکه برنامه شما کد دسترسی را دریافت کرد، می‌توانید از این کد برای تماس با «میانای برنامه‌سازی کاربردی Google» ازطرف حساب کاربری معینی استفاده کنید، به‌شرطی که محدوده(های) دسترسی موردنیاز میانای برنامه‌سازی کاربردی اعطا شده باشد. برای انجام این کار،
کد دسترسی را در درخواست به میانای برنامه‌سازی کاربردی با افزودن پارامتر access_token پُرسمان
یا مقدار Authorization سرصفحه HTTP Bearer اضافه کنید. درصورت امکان،
سرصفحه HTTP ترجیح داده می‌شود، زیرا رشته‌های پرسمان معمولاً در گزارش‌های سرور قابل‌مشاهده هستند. در اکثر موارد می‌توانید از کتابخانه کارخواه برای راه‌اندازی فراخوانی‌هایتان به میاناهای برنامه‌سازی کاربردی Google استفاده کنید (برای مثال، هنگام فراخوانی میانای برنامه‌سازی کاربردی جاری‌سازی زنده YouTube).
توجه داشته باشید که YouTube Live Streaming API از جریان حساب سرویس پشتیبانی نمی‌کند. ازآنجایی‌که راهی برای پیوند دادن «حساب سرویس» به حساب YouTube وجود ندارد، تلاش برای صدور مجوز درخواست‌ها با این جریان، خطای NoLinkedYouTubeAccount را ایجاد می‌کند.
می‌توانید همه میاناهای برنامه‌سازی کاربردی Google را امتحان کنید و دامنه‌های آنها را در OAuth 2.0 Playground مشاهده کنید.
نمونه‌های HTTP GET
تماس با
liveBroadcasts.list
نقطه پایانی (API جاری‌سازی زنده YouTube) بااستفاده از سرصفحه Authorization: Bearer HTTP
ممکن است به این شکل باشد. توجه داشته باشید که باید کد دسترسی خودتان را مشخص کنید:
GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
در اینجا فراخوانی برای همان میانای برنامه‌سازی کاربردی برای کاربر اصالت‌سنجی‌شده بااستفاده از پارامتر رشته پُرسمان access_token ارائه شده است:
GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
curl مثال
می‌توانید این فرمان‌ها را با برنامه خط فرمان curl آزمایش کنید. در اینجا
نمونه‌ای آورده شده است که از گزینه سرصفحه HTTP (ترجیحی) استفاده می‌کند:
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true
یا، به‌طور جایگزین، گزینه پارامتر رشته پُرسمان:
curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
بازآوری کد دسترسی
رمزهای دسترسی به‌صورت دوره‌ای منقضی می‌شوند و برای درخواست API مربوطه اعتبارنامه نامعتبر می‌شوند. اگر دسترسی آفلاین به گستره‌های مرتبط با کد دسترسی را درخواست کرده باشید، می‌توانید کد دسترسی را بدون درخواست اجازه از کاربر (ازجمله زمانی که کاربر حضور ندارد) بازآوری کنید.
برای بازآوری کردن یک کد دسترسی، برنامه شما یک درخواست HTTPS POST
به سرور مجوز Google (https://oauth2.googleapis.com/token) ارسال می‌کند که
شامل پارامترهای زیر در بدنه درخواست است:
| نام | مقدار |
|---|---|
client_id |
شناسه مشتری به‌دست‌آمده از کنسول API. |
client_secret |
اختیاری
رمز کارخواه به‌دست‌آمده از کنسول API. |
grant_type |
همان‌طور که
در
مشخصات OAuth 2.0 تعریف شده است،
مقدار این فیلد باید روی refresh_token تنظیم شود. |
refresh_token |
نماد بازآوری از تبادل کد مجوز برگردانده شد. |
تکه زیر یک درخواست نمونه را نشان می‌دهد:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=your_client_id& refresh_token=refresh_token& grant_type=refresh_token
تا زمانی که کاربر دسترسی اعطاشده به برنامه را لغو نکرده باشد، سرور کد شیء JSON حاوی کد دسترسی جدیدی را برمی‌گرداند. قطعه کد زیر نمونه‌ای از پاسخ را نشان می‌دهد:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "scope": "https://www.googleapis.com/auth/youtube.force-ssl https://www.googleapis.com/auth/calendar.readonly", "token_type": "Bearer" }
توجه داشته باشید که تعداد ژتون‌های بازآوری که صادر می‌شود محدود است؛ یک محدودیت برای هر ترکیب مشتری/کاربر، و محدودیت دیگر برای هر کاربر در همه مشتری‌ها. باید کدهای بازآوری را در فضای ذخیره‌سازی بلندمدت ذخیره کنید و تا زمانی که معتبر هستند از آنها استفاده کنید. اگر برنامه شما ژتون‌های بازآوری زیادی درخواست کند، ممکن است با این محدودیت‌ها مواجه شود که در این صورت ژتون‌های بازآوری قدیمی‌تر از کار خواهند افتاد.
ابطال کد
در برخی موارد، ممکن است کاربر بخواهد دسترسی اعطاشده به برنامه‌ای را لغو کند. کاربر می‌تواند با مراجعه به تنظیمات حساب دسترسی را لغو کند. برای اطلاعات بیشتر، به سند پشتیبانی برداشتن دسترسی سایت یا برنامه در بخش «برنامه‌ها و سایت‌های طرف سوم با امکان دسترسی به حساب شما» مراجعه کنید.
همچنین ممکن است برنامه‌ای دسترسی داده‌شده به آن را به‌صورت برنامه‌ریزی‌شده لغو کند. لغو برنامه‌ریزی‌شده در مواردی که کاربر لغو اشتراک می‌کند، برنامه را برمی‌دارد، یا منابع API موردنیاز برنامه به‌طور قابل‌توجهی تغییر کرده است، اهمیت دارد. به‌عبارت دیگر، بخشی از فرایند برداشتن می‌تواند شامل درخواست API برای اطمینان از برداشته شدن اجازه‌هایی باشد که قبلاً به برنامه اعطا شده است.
برای لغو کردن توکن به‌صورت برنامه‌نویسی‌شده، برنامه شما درخواستی به
https://oauth2.googleapis.com/revoke ارسال می‌کند و توکن را به‌عنوان پارامتر اضافه می‌کند:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/revoke?token={token}این ژتون می‌تواند ژتون دسترسی یا ژتون بازآوری باشد. اگر کد از نوع کد دسترسی باشد و کد بازآوری متناظر داشته باشد، کد بازآوری نیز باطل خواهد شد.
اگر ابطال باموفقیت پردازش شود، کد وضعیت HTTP پاسخ 200 خواهد بود. برای شرایط خطا، یک کد وضعیت HTTP 400 همراه با کد خطا برگردانده می‌شود.
دامنه‌های مجاز
جریان OAuth 2.0 برای دستگاه‌ها فقط برای محدوده‌های زیر پشتیبانی می‌شود:
OpenID Connect، ورود به سیستم با Google
emailopenidprofile
Drive API
https://www.googleapis.com/auth/drive.appdatahttps://www.googleapis.com/auth/drive.file
YouTube API
https://www.googleapis.com/auth/youtubehttps://www.googleapis.com/auth/youtube.readonly
دسترسی زمان‌محور
دسترسی مبتنی بر زمان به کاربر امکان می‌دهد برای انجام یک کنش، به برنامه شما اجازه دهد برای مدت محدودی به داده‌هایش دسترسی داشته باشد. دسترسی مبتنی بر زمان در محصولات منتخب Google درطول جریان موافقت دردسترس است و به کاربران امکان می‌دهد برای مدت محدودی دسترسی اعطا کنند. برای مثال، Data Portability API امکان انتقال یک‌باره داده‌ها را فراهم می‌کند.
وقتی کاربری به برنامه شما دسترسی زمان‌دار اعطا می‌کند، ژتون بازآوری پس‌از مدت مشخص‌شده منقضی می‌شود. توجه داشته باشید که ممکن است نشانهای بازآوری تحت شرایط خاص زودتر نامعتبر شوند؛ برای جزئیات بیشتر، این موارد را ببینید. فیلد refresh_token_expires_in که در پاسخ
تبادل کد
مجوز برگردانده می‌شود، نشان‌دهنده زمان باقی‌مانده تا انقضای ژتون بازآوری در چنین مواردی است.
پیاده‌سازی «محافظت بین‌حسابی»
یکی از اقدامات تکمیلی که باید برای محافظت از حساب‌های کاربران خود انجام دهید، پیاده‌سازی «محافظت بین‌حسابی» بااستفاده از «سرویس محافظت بین‌حسابی» Google است. این سرویس به شما امکان می‌دهد در اعلان‌های رویداد امنیتی که اطلاعاتی درباره تغییرات عمده در حساب کاربر به برنامه شما ارائه می‌دهد مشترک شوید. سپس می‌توانید از این اطلاعات برای اقدام کردن براساس نحوه تصمیم‌گیری‌تان برای پاسخ به رویدادها استفاده کنید.
برخی‌از نمونه‌های انواع رویدادهایی که «سرویس محافظت بین‌حسابی» Google به برنامه‌تان ارسال می‌کند عبارت‌اند از:
-
https://schemas.openid.net/secevent/risc/event-type/sessions-revoked -
https://schemas.openid.net/secevent/oauth/event-type/token-revoked -
https://schemas.openid.net/secevent/risc/event-type/account-disabled
برای اطلاعات بیشتر درباره نحوه پیاده‌سازی «محافظت بین‌حسابی» و فهرست کامل رویدادهای دردسترس، به صفحه «محافظت از حساب‌های کاربر با «محافظت بین‌حسابی»» مراجعه کنید.