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

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

يوضح هذا المستند كيفية تنفيذ تفويض 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 للمستخدم. راجِع قائمة النطاقات المسموح بها للتطبيقات أو الأجهزة المثبّتة. تتيح النطاقات لتطبيقك طلب الوصول إلى الموارد التي يحتاجها فقط مع السماح للمستخدمين أيضًا بالتحكم في مقدار الوصول الذي يمنحونه للتطبيق. وبالتالي، هناك علاقة عكسية بين عدد النطاقات المطلوبة واحتمال الحصول على موافقة المستخدم.

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" \
         /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. على سبيل المثال، يحدث هذا الخطأ إذا كانت قيمة المعلَمة `client_id` غير صالحة. نوع عميل 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 للأجهزة فقط للنطاقات التالية:

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

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

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

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

إنشاء بيانات اعتماد التفويض

تحديد نطاقات الوصول

الحصول على رموز دخول OAuth 2.0 المميزة

الخطوة 1: طلب رموز المستخدمين والأجهزة

أمثلة

الخطوة 2: معالجة استجابة خادم التفويض

تم الرد بنجاح

تم تجاوز الحصة المخصصة

الخطوة 3: عرض رمز المستخدم

الخطوة 4: استطلاع خادم تفويض Google

أمثلة

الخطوة 5: استجابة المستخدم لطلب الوصول

الخطوة 6: معالجة الردود على طلبات الاستطلاع

تم منح إذن الوصول

تم رفض الوصول

التفويض معلّق

يتم استطلاعات الرأي كثيرًا جدًا

أخطاء أخرى

استدعاء واجهات Google APIs

أمثلة HTTP GET

أمثلة على curl

تحديث رمز الدخول

إبطال الرمز المميز

النطاقات المسموح بها

OpenID Connect، تسجيل الدخول بحساب Google

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

YouTube API

أمثلة على `curl`