تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

OAuth 2.0 لتطبيقات التلفزيون والأجهزة ذات الإدخال المحدود

يوضّح هذا المستند كيفية تنفيذ تفويض OAuth 2.0 للوصول إلى Google APIs من خلال تطبيقات يتم تشغيلها على أجهزة مثل أجهزة التلفزيون ووحدات تحكُّم الألعاب والطابعات. وبشكل أكثر تحديدًا، تم تصميم هذا المسار للأجهزة التي لا يمكنها الوصول إلى متصفّح أو التي لها إمكانات إدخال محدودة.

يسمح بروتوكول OAuth 2.0 للمستخدمين بمشاركة بيانات محددة مع أحد التطبيقات مع الحفاظ على خصوصية أسماء المستخدمين وكلمات المرور والمعلومات الأخرى. على سبيل المثال، يمكن لتطبيق تلفزيون استخدام OAuth 2.0 للحصول على إذن لاختيار ملف مخزَّن على Google Drive.

وبما أنّ التطبيقات التي تستخدم هذا المسار يتم توزيعها على الأجهزة الفردية، يُفترض أنّ التطبيقات لا يمكنها الحفاظ على الأسرار. ويمكنهم الوصول إلى Google APIs أثناء استخدام التطبيق أو عند تشغيل التطبيق في الخلفية.

البدائل

إذا كنت تكتب تطبيقًا لنظام أساسي، مثل Android أو iOS أو macOS أو Linux أو Windows (بما في ذلك النظام الأساسي العام لنظام التشغيل Windows)، بحيث يمكنه الوصول إلى المتصفح وإمكانات الإدخال الكاملة، استخدِم مسار OAuth 2.0 للتطبيقات المتوافقة مع الأجهزة الجوّالة وأجهزة الكمبيوتر المكتبي. (يجب استخدام هذا المسار حتى إذا كان تطبيقك عبارة عن أداة سطر أوامر بدون واجهة رسومية).

إذا كنت تريد فقط تسجيل دخول المستخدمين باستخدام حساباتهم على Google واستخدام الرمز المميّز لرقم تعريف JWT للحصول على المعلومات الأساسية للملف الشخصي للمستخدم، راجِع تسجيل الدخول على أجهزة التلفزيون والأجهزة ذات الإدخال المحدود.

المتطلبات الأساسية

تفعيل واجهات برمجة التطبيقات لمشروعك

ويجب تفعيل واجهات برمجة التطبيقات هذه في API Consoleلأي تطبيق يستدعي Google APIs.

لتفعيل واجهة برمجة تطبيقات لمشروعك:

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 معًا.

تحذير: إنّ هاتين القيمتين عرضة للتغيير، ويجب عدم ترميز أي منهما في الرمز البرمجي. وبالمثل، يجب عدم تعديل القيم بأي طريقة باستثناء إزالة المخطط من verification_url بشكل اختياري.

الخطوة 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"
}

تكون رموز الدخول محدودة المدة. إذا كان تطبيقك يحتاج إلى الوصول إلى واجهة برمجة تطبيقات على مدار فترة زمنية طويلة، يمكنه استخدام الرمز المميّز لإعادة التحميل للحصول على رمز دخول جديد. إذا كان التطبيق يحتاج إلى هذا النوع من الوصول، من المفترض أن يخزّن الرمز المميّز لإعادة التحميل لاستخدامه لاحقًا.

تم رفض الوصول

إذا رفض المستخدم منح إمكانية الوصول إلى الجهاز، سيكون لاستجابة الخادم رمز الاستجابة 403 لحالة HTTP (Forbidden). وتتضمن الاستجابة الخطأ التالي:

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

التفويض في انتظار المراجعة

إذا لم يكمل المستخدم عملية التفويض بعد، يعرض الخادم رمز الاستجابة 428 لحالة HTTP (Precondition Required). وتحتوي الاستجابة على الخطأ التالي:

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

إجراء استطلاعات بشكل متكرّر جدًا

إذا كان الجهاز يرسل طلبات الاستقصاء بشكل متكرّر جدًا، سيعرض الخادم رمز الاستجابة 403 لحالة HTTP (Forbidden). تحتوي الاستجابة على الخطأ التالي:

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

أخطاء أخرى

يعرض خادم التفويض أيضًا أخطاء إذا كان طلب الاستطلاع لا يحتوي على أي معلَمات مطلوبة أو يحتوي على قيمة مَعلمة غير صحيحة. وعادةً ما تتضمّن هذه الطلبات رمز الاستجابة 400 (Bad Request) أو 401 (Unauthorized) لحالة HTTP. وتشمل هذه الأخطاء ما يلي:

خطأ	رمز حالة HTTP	الوصف
`admin_policy_enforced`	`400`	يتعذّر على حساب Google تفويض نطاق واحد أو أكثر تم طلبه بسبب سياسات مشرف Google Workspace. يُرجى الاطّلاع على مقالة مساعدة مشرف Google Workspace التحكّم في اختيار التطبيقات التابعة لجهات خارجية والتطبيقات الداخلية التي يمكنها الوصول إلى بيانات Google Workspace للحصول على مزيد من المعلومات عن الطريقة التي يتّبعها المشرف لحظر الوصول إلى النطاقات إلى أن يتم منحه الإذن بالوصول صراحةً إلى معرِّف عميل OAuth.
`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 APIs

بعد أن يحصل تطبيقك على رمز دخول، يمكنك استخدام الرمز المميّز لإجراء طلبات بيانات من Google API نيابةً عن حساب مستخدم معيّن، وذلك إذا تم منح نطاقات الوصول التي تطلبها واجهة برمجة التطبيقات. ولإجراء ذلك، عليك تضمين رمز الدخول المميز في طلب متعلّق بواجهة برمجة التطبيقات عن طريق تضمين مَعلمة طلب البحث access_token أو قيمة Bearer لعنوان HTTP يتضمّن Authorization. ويفضَّل استخدام عنوان HTTP كلما أمكن ذلك، لأن سلاسل طلبات البحث غالبًا ما تكون مرئية في سجلات الخادم. في معظم الحالات، يمكنك استخدام مكتبة برامج لإعداد اتصالاتك في Google APIs (على سبيل المثال، عند طلب واجهة برمجة التطبيقات Drive Files API).

ويمكنك تجربة جميع واجهات برمجة تطبيقات Google وعرض نطاقاتها في ملعب OAuth 2.0.

أمثلة على HTTP GET

قد يبدو طلب نقطة نهاية drive.files (واجهة برمجة تطبيقات ملفات Drive) باستخدام عنوان 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

إعادة تحميل رمز الدخول

تنتهي صلاحية رموز الدخول بشكل دوري وتصبح بيانات اعتماد غير صالحة لطلب بيانات من واجهة برمجة التطبيقات ذي الصلة. يمكنك إعادة تحميل رمز الدخول بدون طلب الإذن من المستخدم (بما في ذلك في حال عدم توفّر المستخدم) في حال طلبت الوصول بلا اتصال بالإنترنت إلى النطاقات المرتبطة بالرمز المميّز.

لإعادة تحميل رمز الدخول، يرسل تطبيقك طلب POST HTTPS إلى خادم التفويض في 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 للأجهزة إلا مع النطاقات التالية:

email
openid
profile

واجهة برمجة تطبيقات Drive

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

واجهة برمجة تطبيقات YouTube

https://www.googleapis.com/auth/youtube
https://www.googleapis.com/auth/youtube.readonly