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.

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

  1. Open the API Library في Google API Console.
  2. If prompted, select a project, or create a new one.
  3. يضم API Library القائمة جميع واجهات برمجة التطبيقات المتاحة، مجمّعةً حسب عائلة المنتج وشعبيته. إذا كانت واجهة برمجة التطبيقات التي تريد تفعيلها غير مرئية في القائمة، استخدم البحث للعثور عليها، أو انقر على عرض الكل في مجموعة المنتجات التي تنتمي إليها.
  4. حدد واجهة برمجة التطبيقات التي تريد تمكينها، ثم انقر على الزر تمكين.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

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

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

  1. Go to the Credentials page.
  2. انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.
  3. حدد نوع تطبيق التلفزيون وأجهزة الإدخال المحدودة.
  4. أدخِل اسمًا لعميل OAuth 2.0 وانقر على إنشاء.

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

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

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

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