يوضح هذا المستند كيفية تنفيذ تفويض OAuth 2.0 للدخول إلى Google APIs عبر التطبيقات التي تعمل على أجهزة مثل أجهزة التلفزيون ووحدات تحكم الألعاب والطابعات. وبشكل أكثر تحديدًا، تم تصميم هذه العملية للأجهزة التي لا يمكنها الوصول إلى المتصفّح أو التي لديها إمكانات إدخال محدودة.
يتيح بروتوكول OAuth 2.0 للمستخدمين مشاركة بيانات محدّدة مع تطبيق مع الحفاظ على خصوصية أسماء المستخدمين وكلمات المرور والمعلومات الأخرى. على سبيل المثال، قد يستخدم تطبيق TV بروتوكول OAuth 2.0 للحصول على إذن لتحديد ملف مخزن على Google Drive.
ونظرًا لتوزيع التطبيقات التي تستخدم هذا التدفق على أجهزة فردية، يُفترض أنّ التطبيقات لا يمكنها الاحتفاظ بالأسرار. ويمكنه الوصول إلى Google APIs أثناء وجود المستخدم في التطبيق أو أثناء تشغيل التطبيق في الخلفية.
البدائل
إذا كنت تكتب تطبيقًا على نظام أساسي، مثل Android أو iOS أو macOS أو Linux أو Windows (بما في ذلك النظام الأساسي العام لـ Windows)، الذي يمكنه الوصول إلى المتصفّح وإمكانيات الإدخال الكاملة، استخدِم تدفق OAuth 2.0 لتطبيقات الجوّال وسطح المكتب. (يجب استخدام هذه العملية حتى إذا كان تطبيقك هو أداة سطر أوامر بدون واجهة رسومية).
إذا كنت تريد فقط تسجيل دخول المستخدمين باستخدام حساباتهم على Google واستخدام الرمز المميّز للمعرّف JWT للحصول على المعلومات الأساسية عن الملف الشخصي للمستخدم، يمكنك الاطّلاع على القسم تسجيل الدخول على أجهزة التلفزيون وأجهزة الإدخال المحدودة.
المتطلبات الأساسية
تفعيل واجهات برمجة التطبيقات لمشروعك
يحتاج أي تطبيق يستدعي Google APIs إلى تفعيل واجهات برمجة التطبيقات هذه في API Console.
لتمكين واجهة برمجة تطبيقات لمشروعك:
- Open the API Library في Google API Console.
- If prompted, select a project, or create a new one.
- يضم API Library القائمة جميع واجهات برمجة التطبيقات المتاحة، مجمّعةً حسب عائلة المنتج وشعبيته. إذا كانت واجهة برمجة التطبيقات التي تريد تفعيلها غير مرئية في القائمة، استخدم البحث للعثور عليها، أو انقر على عرض الكل في مجموعة المنتجات التي تنتمي إليها.
- حدد واجهة برمجة التطبيقات التي تريد تمكينها، ثم انقر على الزر تمكين.
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
إنشاء بيانات اعتماد التفويض
يجب أن يحتوي أي تطبيق يستخدم OAuth 2.0 للدخول إلى Google APIs على بيانات اعتماد مصادقة تحدد التطبيق في خادم OAuth 2.0 في Google. توضّح الخطوات التالية كيفية إنشاء بيانات اعتماد لمشروعك. ويمكن للتطبيقات بعد ذلك استخدام بيانات الاعتماد للوصول إلى واجهات برمجة التطبيقات التي فعّلتها لهذا المشروع.
- Go to the Credentials page.
- انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.
- حدد نوع تطبيق التلفزيون وأجهزة الإدخال المحدودة.
- أدخِل اسمًا لعميل OAuth 2.0 وانقر على إنشاء.
تحديد نطاقات الوصول
تمكن النطاقات تطبيقك من طلب الوصول إلى الموارد التي يحتاجها فقط مع تمكين المستخدمين أيضًا من التحكم في مقدار الوصول الذي يمنحونه للتطبيق. وبالتالي، قد تكون هناك علاقة عكسية بين عدد النطاقات المطلوبة واحتمالية الحصول على موافقة المستخدم.
قبل البدء في تنفيذ تفويض OAuth 2.0، ننصحك بتحديد النطاقات التي سيحتاج تطبيقك إلى إذن للوصول إليها.
اطلع على قائمة النطاقات المسموح بها للتطبيقات أو الأجهزة المثبتة.
الحصول على رموز دخول OAuth 2.0 المميزة
على الرغم من تشغيل التطبيق على جهاز بإمكانيات إدخال محدودة، يجب أن يتوفّر للمستخدمين إمكانية وصول منفصلة إلى جهاز يتضمّن إمكانات إدخال أكثر ثراءً لإكمال عملية التفويض هذه. وتتّبع الخطوات الخطوات التالية:
- يرسل تطبيقك طلبًا إلى خادم تفويض Google الذي يحدّد النطاقات التي سيطلب تطبيقك إذن الوصول إليها.
- يستجيب الخادم بعدة أجزاء من المعلومات المستخدمة في الخطوات اللاحقة، مثل رمز الجهاز ورمز المستخدم.
- يمكنك عرض المعلومات التي يمكن للمستخدم إدخالها على جهاز منفصل لتفويض تطبيقك.
- يبدأ تطبيقك في استطلاع خادم تفويض Google لتحديد ما إذا كان المستخدم قد فوَّض تطبيقك.
- ينتقل المستخدم إلى جهاز يتمتع بإمكانات إدخال أكثر ثراءً، ويشغِّل متصفِّح ويب، وينتقل إلى عنوان URL المعروض في الخطوة 3 ويُدخِل رمزًا يتم عرضه أيضًا في الخطوة 3. ويمكن للمستخدم حينئذٍ منح إذن الوصول إلى تطبيقك (أو رفضه).
- تحتوي الاستجابة التالية لطلب الاستطلاع على الرموز المميزة التي يحتاجها تطبيقك للسماح بالطلبات نيابةً عن المستخدم. (إذا رفض المستخدم الوصول إلى تطبيقك، لن تحتوي الاستجابة على رموز مميزة).
توضح الصورة أدناه هذه العملية:

توضح الأقسام التالية هذه الخطوات بالتفصيل. وفقًا لنطاق الإمكانيات وبيئات وقت التشغيل التي قد تمتلكها الأجهزة، تستخدم الأمثلة المعروضة في هذا المستند الأداة المساعدة سطر الأوامر curl
. من المفترض أن يكون من السهل نقل هذه الأمثلة إلى لغات وأوقات تشغيل مختلفة.
الخطوة 1: طلب رموز المستخدمين والأجهزة
في هذه الخطوة، يرسل جهازك طلب HTTP POST إلى خادم تفويض Google، على
https://oauth2.googleapis.com/device/code
، الذي يحدد تطبيقك
بالإضافة إلى نطاقات الدخول التي يريد التطبيق الوصول إليها نيابةً عن المستخدم.
عليك استرداد عنوان URL هذا من مستند أثناء التصفّح باستخدام قيمة البيانات الوصفية device_authorization_endpoint
. أدرِج معلَمات طلب HTTP التالية:
المعلَمات | |
---|---|
client_id |
مطلوب
معرِّف العميل لتطبيقك. ويمكنك العثور على هذه القيمة في API Console Credentials page. |
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
الخطوة 2: معالجة استجابة خادم التفويض
سيعرض خادم التفويض إحدى الاستجابات التالية:
تم الرد بنجاح
إذا كان الطلب صالحًا، سيكون ردك عبارة عن عنصر JSON يحتوي على الخصائص التالية:
أماكن إقامة | |
---|---|
device_code |
قيمة تعينها Google بشكل فريد لتحديد الجهاز الذي يشغل التطبيق الذي يطلب
التفويض. سيفوّض المستخدم هذا الجهاز من جهاز آخر مزوّد بإمكانيات إدخال أكثر ثراءً. على سبيل المثال، قد يستخدم المستخدم كمبيوتر محمولاً أو هاتفًا جوّالاً لتفويض
تطبيق يعمل على التلفزيون. في هذه الحالة، يعرِّف device_code التلفزيون.
يتيح هذا الرمز للجهاز الذي يشغِّل التطبيق إمكانية تحديد ما إذا كان المستخدم قد منح إمكانية الوصول أو رفضها. |
expires_in |
الفترة الزمنية بالثواني التي تكون خلالها السمة device_code وuser_code صالحة. وإذا لم يُكمل المستخدم خلال هذه الفترة عملية التفويض ولم يُجرِ استطلاع رأي في الجهاز أيضًا للحصول على معلومات عن قرار المستخدم، قد تحتاج إلى إعادة تشغيل هذه العملية من الخطوة 1. |
interval |
المدة الزمنية بالثواني التي يجب أن ينتظر خلالها جهازك بين طلبات الاستطلاع. على سبيل المثال، إذا كانت القيمة هي 5 ، يجب أن يرسل جهازك طلب استطلاع إلى خادم تفويض Google كل خمس ثوانٍ. يمكنك الاطّلاع على الخطوة 3 للحصول على مزيد من التفاصيل. |
user_code |
قيمة حسّاسة لحالة الأحرف تحدّد لـ Google النطاقات التي يطلب التطبيق الوصول إليها. وسترشد واجهة المستخدم المستخدم إلى إدخال هذه القيمة على جهاز منفصل مزود بإمكانيات إدخال أكثر ثراءً. بعد ذلك، يستخدم Google القيمة لعرض مجموعة النطاقات الصحيحة عند مطالبة المستخدم بمنح الوصول إلى تطبيقك. |
verification_url |
عنوان 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
.
- يجب أن تكون المساحة التي تعرض فيها
الخطوة 4: استطلاع خادم تفويض Google
بما أنّ المستخدم سيستخدم جهازًا منفصلاً للانتقال إلى verification_url
ومنح الوصول (أو رفضه)، لا يتم إشعار الجهاز صاحب الطلب تلقائيًا عندما
يرد المستخدم على طلب الوصول. ولهذا السبب، يحتاج الجهاز مقدم الطلب إلى استطلاع
خادم تفويض Google لتحديد وقت استجابة المستخدم للطلب.
يجب أن يستمر الجهاز صاحب الطلب في إرسال طلبات الاستطلاع إلى أن يتلقّى استجابة تشير إلى أن المستخدم قد ردّ على طلب الوصول أو إلى أن تنتهي صلاحية device_code
وuser_code
اللذين تم الحصول عليهما في
الخطوة 2. تحدد interval
المعروضة في الخطوة 2 مقدار
الوقت بالثواني للانتظار بين الطلبات.
عنوان URL لنقطة النهاية المطلوب استطلاع رأيها هو https://oauth2.googleapis.com/token
. يحتوي طلب البحث
على المعلّمات التالية:
المعلَمات | |
---|---|
client_id |
معرِّف العميل لتطبيقك. ويمكنك العثور على هذه القيمة في API Console Credentials page. |
client_secret |
سر العميل لـ client_id المُقدَّم. ويمكنك العثور على هذه القيمة في
API Console
Credentials 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 APIs بالنيابة عن المستخدم. (تحدد السمة scope
في الاستجابة واجهات برمجة التطبيقات التي يمكن للجهاز الوصول إليها).
في هذه الحالة، تحتوي استجابة واجهة برمجة التطبيقات على الحقول التالية:
الحقول | |
---|---|
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" }
مدة صلاحية رموز الدخول محدودة. إذا كان تطبيقك يحتاج إلى الوصول إلى واجهة برمجة تطبيقات على مدار فترة زمنية طويلة، يمكن أن يستخدِم الرمز المميز لإعادة التحميل للحصول على رمز دخول جديد. إذا كان تطبيقك يحتاج إلى هذا النوع من الوصول، يجب أن يخزن الرمز المميز لإعادة التحميل لاستخدامه لاحقًا.
تم رفض الوصول
إذا رفض المستخدم منح إمكانية الوصول إلى الجهاز، تتضمّن استجابة الخادم رمز حالة استجابة 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. يُرجى الاطِّلاع على مقالة مساعدة مشرف Google Workspace التحكُّم في اختيار التطبيقات التابعة لجهات خارجية والتطبيقات الداخلية التي يمكنها الوصول إلى بيانات Google Workspace للحصول على مزيد من المعلومات عن الطريقة التي يمكن للمشرف من خلالها حظر الوصول إلى النطاقات حتى يتم منح الوصول صراحةً إلى معرِّف عميل OAuth. |
invalid_client |
401 |
لم يتم العثور على عميل OAuth. على سبيل المثال، يحدث هذا الخطأ إذا كانت
قيمة المعلَمة نوع عميل OAuth غير صحيح. تأكَّد من ضبط نوع التطبيق لمعرِّف العميل على أجهزة التلفزيون وأجهزة الإدخال المحدودة. |
invalid_grant |
400 |
قيمة المعلمة code غير صالحة، أو تمت المطالبة بها من قبل، أو لا يمكن تحليلها. |
unsupported_grant_type |
400 |
قيمة المعلمة grant_type غير صالحة. |
org_internal |
403 |
معرِّف عميل OAuth في الطلب هو جزء من مشروع يحد من الوصول إلى حسابات Google في مؤسسة Google Cloud محددة. أكِّد ضبط نوع المستخدم لتطبيق OAuth. |
استدعاء واجهات Google APIs
بعد حصول تطبيقك على رمز دخول، يمكنك استخدام الرمز المميز لإجراء استدعاءات لواجهة برمجة تطبيقات Google نيابةً عن حساب مستخدم معيّن إذا تم منح نطاق الوصول المطلوب لواجهة برمجة التطبيقات. ولإجراء ذلك، يمكنك تضمين رمز الدخول في طلب إلى واجهة برمجة التطبيقات من خلال تضمين إما مَعلمة طلب البحث access_token
أو قيمة Authorization
لرأس HTTP Bearer
. ويُفضّل استخدام عنوان HTTP كلما أمكن، لأن سلاسل طلبات البحث غالبًا ما تكون مرئية في سجلات الخادم. وفي معظم
الحالات، يمكنك استخدام مكتبة برامج لإعداد عمليات استدعاء إلى Google APIs (على سبيل المثال، عند
استدعاء واجهة برمجة تطبيقات ملفات Drive).
يمكنك تجربة جميع واجهات برمجة تطبيقات Google وعرض نطاقاتها في مساحة تخزين بروتوكول OAuth 2.0.
أمثلة HTTP GET
يمكن أن يبدو استدعاء نقطة نهاية
drive.files
(واجهة برمجة تطبيقات ملفات Drive) باستخدام رأس Authorization: Bearer
HTTP
على النحو التالي. لاحظ أنه يلزمك تحديد رمز الدخول الخاص بك:
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
تحديث رمز الدخول
تنتهي صلاحية رموز الدخول بشكل دوري وتصبح بيانات اعتماد غير صالحة لطلب واجهة برمجة التطبيقات ذي الصلة. يمكنك إعادة تحميل رمز دخول بدون طلب إذن من المستخدم (بما في ذلك في حال عدم وجود المستخدم) إذا طلبت الوصول بلا إنترنت إلى النطاقات المرتبطة بالرمز المميّز.
لإعادة تحميل رمز الدخول، يرسل تطبيقك طلب 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", "token_type": "Bearer" }
تجدر الإشارة إلى أن هناك حدودًا لعدد الرموز المميزة لإعادة التحميل التي سيتم إصدارها، حيث يتم وضع قيد واحد لكل مجموعة عميل/مستخدم ووضع علامة أخرى لكل مستخدم في جميع البرامج. يجب حفظ الرموز المميزة لإعادة التحميل في مساحة تخزين طويلة الأجل ومواصلة استخدامها طالما كانت صالحة. وإذا طلب التطبيق عددًا كبيرًا جدًا من الرموز المميزة لإعادة التحميل، قد يؤدي ذلك إلى تجاوز هذه الحدود المسموح بها، وفي هذه الحالة سيتوقف عمل الرموز المميزة للتحديث القديمة.
إبطال الرمز المميز
في بعض الحالات، قد يرغب المستخدم في إبطال حق الوصول الممنوح لتطبيق. يمكن للمستخدم إبطال الوصول عن طريق الانتقال إلى إعدادات الحساب. للحصول على مزيد من المعلومات، يُرجى الاطّلاع على قسم دعم المواقع الإلكترونية والتطبيقات التابعة لجهات خارجية التي يمكنها الوصول إلى حسابك لإزالة قسم "الموقع الإلكتروني أو التطبيق".
ومن الممكن أيضًا أن يلغي أحد التطبيقات برمجيًا الدخول الممنوحة له. ويعتبر الإبطال الآلي مهمًا عندما يلغي المستخدم اشتراكه أو يزيل تطبيقًا أو يتم تغيير موارد واجهة برمجة التطبيقات التي يتطلبها التطبيق بشكل كبير. بمعنى آخر، يمكن أن يشمل جزء من عملية الإزالة طلبًا لواجهة برمجة التطبيقات لضمان إزالة الأذونات الممنوحة للتطبيق في السابق.
لإبطال الرمز المميز آليًا، يقدم تطبيقك طلبًا لتنفيذ ما يلي:
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
email
openid
profile
واجهة برمجة تطبيقات Drive
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