‫OAuth 2.0 برای برنامه‌های تلویزیون و دستگاه‌های ورودی محدود

این سند توضیح می‌دهد که چگونه می‌توان مجوز OAuth 2.0 را برای دسترسی به Google پیاده‌سازی کرد میاناهای برنامه‌سازی کاربردی بااستفاده از برنامه‌هایی که در دستگاه‌هایی مانند تلویزیون، کنسول‌های بازی، و چاپگرها اجرا می‌شوند. به‌طور دقیق‌تر، این جریان برای دستگاه‌هایی طراحی شده است که یا به مرورگر دسترسی ندارند یا قابلیت‌های ورودی محدودی دارند.

‫OAuth 2.0 به کاربران اجازه می‌دهد داده‌های خاصی را با برنامه‌ای هم‌رسانی کنند و درعین‌حال نام‌های کاربری، گذرواژه‌ها، و اطلاعات دیگرشان را خصوصی نگه دارند. برای مثال، یک برنامه تلویزیون می‌تواند از OAuth 2.0 برای دریافت اجازه انتخاب فایلی که در Google Drive ذخیره شده است استفاده کند.

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

جایگزین‌ها

اگر فقط می‌خواهید کاربران را با «حساب Google» آن‌ها به سیستم وارد کنید و از JWT شناسه ژتون برای دریافت اطلاعات نمایه کاربر پایه استفاده کنید، ورود به سیستم در تلویزیون‌ها و دستگاه‌های ورودی محدود را ببینید.

پیش‌نیازها

فعال کردن میاناهای برنامه‌سازی کاربردی برای پروژه

هر برنامه‌ای که میاناهای برنامه‌سازی کاربردی Google را فراخوانی می‌کند باید آن میاناهای برنامه‌سازی کاربردی را در «کنسول میانای برنامه‌سازی کاربردی» فعال کند.

برای فعال کردن میانای برنامه‌سازی کاربردی برای پروژه‌تان:

  1. کتابخانه میانای برنامه‌سازی کاربردی را در «کنسول Google API» باز کنید.
  2. درصورت درخواست، پروژه‌ای را انتخاب کنید یا پروژه جدیدی ایجاد کنید.
  3. «کتابخانه میانای برنامه‌سازی کاربردی» همه میاناهای برنامه‌سازی کاربردی دردسترس را فهرست می‌کند که براساس خانواده محصول و محبوبیت گروه‌بندی شده‌اند. اگر API موردنظرتان برای فعال کردن در فهرست دیده نمی‌شود، از جستجو برای پیدا کردن آن استفاده کنید یا روی مشاهده همه در خانواده محصولی که به آن تعلق دارد کلیک کنید.
  4. میانای برنامه‌سازی کاربردی موردنظرتان را برای فعال کردن انتخاب کنید، سپس روی دکمه فعال کردن کلیک کنید.
  5. اگر درخواست شد، صدور صورت‌حساب را فعال کنید.
  6. درصورت درخواست، «شرایط خدمات» API را بخوانید و بپذیرید.

ایجاد اعتبارنامه مجوز

هر برنامه‌ای که از OAuth 2.0 برای دسترسی به Google API استفاده می‌کند باید اعتبارنامه مجوزدهی داشته باشد که برنامه را برای سرور OAuth 2.0 Google شناسایی کند. مراحل زیر نحوه ایجاد اطلاعات اعتباری برای پروژه را توضیح می‌دهد. سپس برنامه‌هایتان می‌توانند از این اطلاعات اعتباری برای دسترسی به میاناهای برنامه‌سازی کاربردی‌ای که برای آن پروژه فعال کرده‌اید استفاده کنند.

  1. به صفحه کارخواهان بروید.
  2. روی ایجاد کارخواه کلیک کنید.
  3. نوع برنامه تلویزیون‌ها و دستگاه‌های ورودی محدود را انتخاب کنید.
  4. نامی برای کارخواه OAuth 2.0 خود انتخاب کنید و روی ایجاد کلیک کنید.

شناسایی کردن دامنه‌های دسترسی

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

قبل‌از شروع پیاده‌سازی مجوز OAuth 2.0، توصیه می‌کنیم دامنه‌هایی را که برنامه‌تان برای دسترسی به آن‌ها به اجازه نیاز دارد شناسایی کنید.

فهرست دامنه‌های مجاز را برای برنامه‌ها یا دستگاه‌های نصب‌شده ببینید.

دریافت کدهای دسترسی OAuth 2.0

اگرچه برنامه شما در دستگاهی با قابلیت‌های ورودی محدود اجرا می‌شود، کاربران باید دسترسی جداگانه‌ای به دستگاهی با قابلیت‌های ورودی غنی‌تر داشته باشند تا این جریان صدور مجوز را تکمیل کنند. این جریان مراحل زیر را دارد:

  1. برنامه شما درخواستی به سرور مجوز Google ارسال می‌کند که دامنه‌هایی را که برنامه شما برای دسترسی به آن‌ها درخواست اجازه خواهد کرد شناسایی می‌کند.
  2. سرور با چند بخش اطلاعاتی که در مراحل بعدی استفاده می‌شود، مانند کد دستگاه و کد کاربر، پاسخ می‌دهد.
  3. اطلاعاتی را نمایش می‌دهید که کاربر می‌تواند در دستگاه دیگری وارد کند تا برنامه شما را مجاز کند.
  4. برنامه شما شروع به نظرسنجی از سرور مجوز Google می‌کند تا تعیین کند آیا کاربر به برنامه شما مجوز داده است یا نه.
  5. کاربر به دستگاهی با قابلیت‌های ورودی غنی‌تر می‌رود، مرورگر وب را راه‌اندازی می‌کند، به نشانی وب نمایش‌داده‌شده در مرحله ۳ می‌رود، و کدی را که در مرحله ۳ نیز نمایش داده شده است وارد می‌کند. سپس کاربر می‌تواند دسترسی به برنامه شما را اعطا (یا رد) کند.
  6. پاسخ بعدی به درخواست نظرسنجی شما حاوی نشانه‌هایی است که برنامه‌تان برای مجاز کردن درخواست‌ها ازطرف کاربر نیاز دارد. (اگر کاربر دسترسی به برنامه شما را رد کرده باشد، پاسخ حاوی کد نیست.)

تصویر این فرایند را نشان می‌دهد:

کاربر در دستگاه جداگانه‌ای که مرورگر دارد به سیستم وارد می‌شود

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

مرحله ۱: درخواست کدهای دستگاه و کاربر

در این مرحله، دستگاه شما درخواست HTTP POST را به سرور مجوز Google در https://oauth2.googleapis.com/device/code ارسال می‌کند که برنامه شما و همچنین دامنه‌های دسترسی را که برنامه شما می‌خواهد ازطرف کاربر به آن‌ها دسترسی داشته باشد شناسایی می‌کند. باید این نشانی وب را از سند اکتشاف بااستفاده از مقدار فراداده device_authorization_endpoint بازیابی کنید. پارامترهای درخواست HTTP زیر را اضافه کنید:

پارامترها
client_id الزامی

شناسه کارخواه برای برنامه شما. این مقدار را می‌توانید در صفحه «کارخواه‌ها» در «کنسول Cloud» پیدا کنید.

scope الزامی

فهرستی از دامنه‌ها که با فاصله از هم جدا شده‌اند و منابعی را که برنامه‌تان می‌تواند ازطرف کاربر به آن‌ها دسترسی داشته باشد شناسایی می‌کند. این مقادیر به صفحه رضایت که Google به کاربر نمایش می‌دهد اطلاع‌رسانی می‌کند. فهرست دامنه‌های مجاز را برای برنامه‌ها یا دستگاه‌های نصب‌شده ببینید.

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

مثال‌ها

قطعه کد زیر یک درخواست نمونه را نشان می‌دهد:

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&scope=email%20profile

این مثال فرمان curl را برای ارسال همان درخواست نشان می‌دهد:

curl -d "client_id=client_id&scope=email%20profile" \
     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_code
    • user_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 در طول یک دوره زمانی طولانی دارد، می‌تواند از کد بازآوری استفاده کند تا یک کد دسترسی جدید دریافت کند. اگر برنامه شما به این نوع دسترسی نیاز دارد، باید ژتون بازآوری را برای استفاده بعدی ذخیره کند.

دسترسی امکان‌پذیر نیست

اگر کاربر از اعطای دسترسی به دستگاه خودداری کند، پاسخ سرور دارای کد وضعیت پاسخ‌های HTTP 403 (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 پیدا نشد. برای مثال، این خطا زمانی رخ می‌دهد که مقدار پارامتر client_id نامعتبر باشد.

نوع کارخواه OAuth نادرست است. مطمئن شوید که نوع برنامه برای شناسه مشتری روی تلویزیون‌ها و دستگاه‌های ورودی محدود تنظیم شده باشد.

invalid_grant 400 مقدار پارامتر code نامعتبر است، قبلاً ادعا شده است، یا نمی‌تواند تجزیه شود.
unsupported_grant_type 400 مقدار پارامتر grant_type نامعتبر است.
org_internal 403 شناسه کارخواه OAuth در درخواست بخشی از پروژه‌ای است که دسترسی به «حساب‌های Google» را در «سازمان Google Cloud» خاصی محدود می‌کند. پیکربندی نوع کاربر را برای برنامه OAuth خود تأیید کنید.

فراخوانی میاناهای برنامه‌سازی کاربردی Google

پس‌از اینکه برنامه‌تان کد دسترسی را دریافت کرد، می‌توانید از آن کد برای برقراری تماس با Google API ازطرف حساب کاربری مشخصی استفاده کنید، به‌شرطی که گستره(های) دسترسی موردنیاز API اعطا شده باشد. برای انجام این کار، کد دسترسی را با گنجاندن پارامتر پُرسمان access_token یا مقدار سرصفحه HTTP Authorization Bearer در درخواست به میانای برنامه‌سازی کاربردی بگنجانید. درصورت امکان، سرایند HTTP ترجیح داده می‌شود، زیرا رشته‌های پرسمان معمولاً در گزارش‌های سرور قابل‌مشاهده هستند. در بیشتر موارد، می‌توانید از کتابخانه کارخواه برای راه‌اندازی تماس‌هایتان با Google API استفاده کنید (برای مثال، هنگام فراخوانی Drive Files API).

می‌توانید همه میاناهای برنامه‌سازی کاربردی Google را امتحان کنید و دامنه‌های آن‌ها را در OAuth 2.0 Playground مشاهده کنید.

نمونه‌های HTTP GET

فراخوانی نقطه پایانی drive.files (Drive Files API) بااستفاده از سرایند HTTP Authorization: Bearer ممکن است به‌صورت زیر باشد. توجه داشته باشید که باید کد دسترسی خودتان را مشخص کنید:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

در اینجا فراخوانی برای همان میانای برنامه‌سازی کاربردی برای کاربر اصالت‌سنجی‌شده بااستفاده از پارامتر رشته پُرسمان access_token ارائه شده است:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl مثال

می‌توانید این فرمان‌ها را با برنامه خط فرمان curl آزمایش کنید. در اینجا نمونه‌ای آورده شده است که از گزینه سرایند HTTP (ترجیحی) استفاده می‌کند:

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

یا، به‌عنوان گزینه جایگزین، گزینه پارامتر رشته پُرسمان:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

بازآوری کد دسترسی

کدهای دسترسی به‌طور دوره‌ای منقضی می‌شوند و به اطلاعات اعتباری نامعتبر برای درخواست 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/drive.metadata.readonly 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 است. برای شرایط خطا، رمز وضعیت اچ‌تی‌تی‌پی‌اس 400 همراه با کد خطا برگردانده می‌شود.

دامنه‌های مجاز

جریان OAuth 2.0 برای دستگاه‌ها فقط برای دامنه‌های زیر پشتیبانی می‌شود:

OpenID Connect، ورود به سیستم با Google

  • email
  • openid
  • profile

Drive API

  • https://www.googleapis.com/auth/drive.appdata
  • https://www.googleapis.com/auth/drive.file

YouTube API

  • https://www.googleapis.com/auth/youtube
  • https://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

برای اطلاعات بیشتر درباره نحوه پیاده‌سازی «محافظت بین‌حسابی» و فهرست کامل رویدادهای دردسترس، صفحه «محافظت از حساب‌های کاربری با محافظت بین‌حسابی» را ببینید.