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

نکته مهم: این جریان OAuth 2.0 از مجموعه محدودی از دامنه ها پشتیبانی می کند.

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

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

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

جایگزین ها

اگر در حال نوشتن برنامه ای برای پلتفرمی مانند Android، iOS، macOS، Linux یا Windows (از جمله پلتفرم جهانی ویندوز) هستید که به مرورگر و قابلیت های ورودی کامل دسترسی دارد، از جریان OAuth 2.0 برای برنامه های موبایل و دسکتاپ استفاده کنید. (حتی اگر برنامه شما یک ابزار خط فرمان بدون رابط گرافیکی باشد، باید از آن جریان استفاده کنید.)

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

پیش نیازها

API ها را برای پروژه خود فعال کنید

هر برنامه‌ای که Google API را فراخوانی می‌کند، باید آن APIها را در آن فعال کند API Console.

برای فعال کردن یک API برای پروژه خود:

1. Open the API Library در Google API Console.
2. If prompted, select a project, or create a new one.
3. را API Library همه API های موجود را فهرست می کند که بر اساس خانواده محصول و محبوبیت گروه بندی شده اند. اگر API که می‌خواهید فعال کنید در لیست قابل مشاهده نیست، از جستجو برای پیدا کردن آن استفاده کنید یا روی مشاهده همه در خانواده محصولی که به آن تعلق دارد کلیک کنید.
4. API را که می خواهید فعال کنید انتخاب کنید، سپس روی دکمه Enable کلیک کنید.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

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

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

1. Go to the Credentials page.
2. روی ایجاد اعتبار > شناسه مشتری OAuth کلیک کنید.
3. نوع برنامه تلویزیون ها و دستگاه های ورودی محدود را انتخاب کنید.
4. مشتری OAuth 2.0 خود را نامگذاری کنید و روی ایجاد کلیک کنید.

محدوده های دسترسی را شناسایی کنید

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

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

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

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

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

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

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

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

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

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

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

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

پارامترها
client_id	مورد نیاز شناسه مشتری برای برنامه شما. شما می توانید این مقدار را در API ConsoleCredentials page.
scope	مورد نیاز فهرستی از محدوده‌های محدود شده با فضا که منابعی را که برنامه شما می‌تواند از طرف کاربر به آنها دسترسی داشته باشد، شناسایی می‌کند. این مقادیر صفحه رضایتی را که Google به کاربر نشان می دهد، نشان می دهد. فهرست محدوده های مجاز را برای برنامه ها یا دستگاه های نصب شده ببینید. Scopes به برنامه شما امکان می‌دهد فقط درخواست دسترسی به منابع مورد نیاز خود را داشته باشد در حالی که کاربران را قادر می‌سازد تا میزان دسترسی را که به برنامه شما می‌دهند کنترل کنند. بنابراین، بین تعداد دامنه های درخواستی و احتمال کسب رضایت کاربر رابطه معکوس وجود دارد.

نمونه ها

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

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

مرحله 2: پاسخ سرور مجوز را مدیریت کنید

سرور مجوز یکی از پاسخ‌های زیر را برمی‌گرداند:

پاسخ موفقیت آمیز

اگر درخواست معتبر باشد، پاسخ شما یک شی JSON با ویژگی های زیر خواهد بود:

خواص
device_code	مقداری که Google برای شناسایی دستگاهی که برنامه درخواست مجوز را اجرا می‌کند، اختصاص می‌دهد. کاربر آن دستگاه را از دستگاه دیگری با قابلیت های ورودی غنی تر مجوز می دهد. برای مثال، یک کاربر ممکن است از لپ‌تاپ یا تلفن همراه برای مجوز دادن به برنامه‌ای که روی تلویزیون اجرا می‌شود استفاده کند. در این حالت، device_code تلویزیون را شناسایی می کند. این کد به دستگاهی که برنامه را اجرا می کند به طور ایمن اجازه می دهد تا تشخیص دهد که آیا کاربر اجازه دسترسی داده یا رد کرده است.
expires_in	مدت زمانی که device_code و user_code معتبر هستند، بر حسب ثانیه. اگر در آن زمان، کاربر جریان مجوز را کامل نکرد و دستگاه شما نیز برای بازیابی اطلاعات تصمیم کاربر نظرسنجی نکرد، ممکن است لازم باشد این فرآیند را از مرحله 1 مجدداً راه اندازی کنید.
interval	مدت زمانی، بر حسب ثانیه، که دستگاه شما باید بین درخواست‌های نظرسنجی منتظر بماند. برای مثال، اگر مقدار 5 باشد، دستگاه شما باید هر پنج ثانیه یک درخواست نظرسنجی به سرور مجوز Google ارسال کند. برای جزئیات بیشتر به مرحله 3 مراجعه کنید.
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
}

سهمیه از پاسخ فراتر رفت

اگر درخواست های کد دستگاه شما از سهمیه مربوط به شناسه مشتری شما فراتر رفته باشد، یک پاسخ 403 دریافت خواهید کرد که حاوی خطای زیر است:

{
  "error_code": "rate_limit_exceeded"
}

در آن صورت، از یک استراتژی عقب نشینی برای کاهش نرخ درخواست ها استفاده کنید.

مرحله 3: نمایش کد کاربر

verification_url و user_code بدست آمده در مرحله 2 را به کاربر نمایش دهید. هر دو مقدار می توانند شامل هر کاراکتر قابل چاپ از مجموعه کاراکترهای US-ASCII باشند. محتوایی که به کاربر نمایش می‌دهید باید به کاربر دستور دهد که به verification_url در یک دستگاه جداگانه پیمایش کند و user_code وارد کند.

رابط کاربری (UI) خود را با در نظر گرفتن قوانین زیر طراحی کنید:

• user_code
  • user_code باید در فیلدی نمایش داده شود که بتواند 15 کاراکتر اندازه «W» را مدیریت کند. به عبارت دیگر، اگر بتوانید کد WWWWWWWWWWWWWWW را به درستی نمایش دهید، رابط کاربری شما معتبر است و توصیه می کنیم هنگام آزمایش نحوه نمایش user_code در رابط کاربری خود، از آن مقدار رشته استفاده کنید.
  • user_code به حروف کوچک و بزرگ حساس است و نباید به هیچ وجه تغییر کند، مانند تغییر حروف کوچک یا درج کاراکترهای قالب‌بندی دیگر.
• verification_url
  • فضایی که verification_url را در آن نمایش می‌دهید باید به اندازه کافی گسترده باشد تا بتواند رشته URL 40 کاراکتری را مدیریت کند.
  • شما نباید verification_url را به هیچ وجه تغییر دهید، به جز حذف اختیاری طرح برای نمایش. اگر قصد دارید طرح (مثلا https:// ) را از URL به دلایل نمایش حذف کنید، مطمئن شوید که برنامه شما می تواند هر دو نوع http و https را مدیریت کند.

هشدار: هر دوی این مقادیر در معرض تغییر هستند و شما نباید هر یک از مقادیر را در کد خود کدگذاری کنید. به طور مشابه، شما نباید مقادیر را به هیچ وجه به جز حذف اختیاری طرح از verification_url تغییر دهید.

مرحله 4: از سرور مجوز Google نظرسنجی کنید

از آنجایی که کاربر از یک دستگاه جداگانه برای پیمایش به verification_url و اعطای (یا رد) دسترسی استفاده می‌کند، هنگامی که کاربر به درخواست دسترسی پاسخ می‌دهد، دستگاه درخواست‌کننده به‌طور خودکار مطلع نمی‌شود. به همین دلیل، دستگاه درخواست‌کننده باید از سرور مجوز Google نظرسنجی کند تا مشخص کند کاربر چه زمانی به درخواست پاسخ داده است.

دستگاه درخواست‌کننده باید به ارسال درخواست‌های نظرسنجی ادامه دهد تا زمانی که پاسخی دریافت کند که نشان می‌دهد کاربر به درخواست دسترسی پاسخ داده است یا تا زمانی که device_code و user_code به‌دست‌آمده در مرحله 2 منقضی شده باشند. interval بازگردانده شده در مرحله 2، مدت زمان انتظار بین درخواست ها را بر حسب ثانیه مشخص می کند.

نشانی اینترنتی نقطه پایانی نظرسنجی https://oauth2.googleapis.com/token است. درخواست نظرسنجی شامل پارامترهای زیر است:

پارامترها
client_id	شناسه مشتری برای برنامه شما. شما می توانید این مقدار را در API ConsoleCredentials page.
client_secret	رمز سرویس گیرنده برای client_id ارائه شده. شما می توانید این مقدار را در API ConsoleCredentials page.
device_code	device_code که توسط سرور مجوز در مرحله 2 بازگردانده شده است.
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

مرحله 5: کاربر به درخواست دسترسی پاسخ می دهد

توجه: برنامه شما در این مرحله به غیر از نظرسنجی سرور مجوز همانطور که در مرحله قبل توضیح داده شد، نیازی به انجام هیچ کاری ندارد.

تصویر زیر صفحه‌ای مشابه آنچه کاربران هنگام رفتن به verification_url که در مرحله 3 نمایش داده‌اید مشاهده می‌کنند نشان می‌دهد:

پس از وارد کردن user_code و در صورتی که قبلاً وارد نشده باشید، وارد Google شوید، کاربر یک صفحه رضایت مانند تصویر زیر را می بیند:

مرحله 6: پاسخ به درخواست های نظرسنجی را رسیدگی کنید

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

دسترسی داده شد

اگر کاربر اجازه دسترسی به دستگاه را داده باشد (با کلیک روی Allow در صفحه رضایت)، پاسخ حاوی یک نشانه دسترسی و یک نشانه بازخوانی است. توکن‌ها به دستگاه شما امکان می‌دهند از طرف کاربر به Google API دسترسی داشته باشد . (ویژگی scope در پاسخ تعیین می کند که دستگاه به کدام API می تواند دسترسی داشته باشد.)

در این مورد، پاسخ API شامل فیلدهای زیر است:

فیلدها
access_token	رمزی که برنامه شما برای تأیید درخواست Google API ارسال می کند.
expires_in	طول عمر باقیمانده رمز دسترسی در ثانیه.
refresh_token	توکنی که می توانید از آن برای به دست آوردن یک نشانه دسترسی جدید استفاده کنید. نشانه‌های Refresh تا زمانی که کاربر دسترسی را لغو نکند معتبر هستند. توجه داشته باشید که نشانه‌های تازه‌سازی همیشه برای دستگاه‌ها برگردانده می‌شوند.
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 Admin مراجعه کنید.
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 API

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

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

نمونه های HTTP GET

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

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

در اینجا یک فراخوانی به همان API برای کاربر تأیید شده با استفاده از پارامتر رشته query 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

یا، گزینه پارامتر query string:

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

در حال بازخوانی نشانه دسترسی

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

برای تازه کردن یک نشانه دسترسی، برنامه شما یک درخواست HTTPS POST به سرور مجوز Google ( https://oauth2.googleapis.com/token ) ارسال می کند که شامل پارامترهای زیر است:

فیلدها
client_id	شناسه مشتری به دست آمده از API Console.
client_secret	راز مشتری به دست آمده از API Console.
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&
client_secret=your_client_secret&
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 است. برای شرایط خطا، کد وضعیت HTTP 400 به همراه یک کد خطا برگردانده می شود.

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

محدوده های مجاز

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

OpenID Connect ، Google Sign-In

• 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 است. این سرویس به شما امکان می دهد در اعلان های رویداد امنیتی مشترک شوید که اطلاعاتی را در مورد تغییرات عمده در حساب کاربری به برنامه شما ارائه می دهد. سپس می‌توانید بسته به نحوه پاسخگویی به رویدادها، از اطلاعات استفاده کنید.

برخی از نمونه‌هایی از انواع رویدادهایی که توسط سرویس محافظت از حساب‌های متقابل 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

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