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

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

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

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

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

البدائل

إذا كنت تكتب تطبيقًا لنظام أساسي، مثل 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" \
         https://oauth2.googleapis.com/token

الخطوة 5: رد المستخدم على طلب الوصول

تعرض الصورة التالية صفحة مشابهة لما يراه المستخدمون عند الانتقال إلى verification_url الذي عرضته في الخطوة 3:

بعد إدخال user_code، وتسجيل الدخول إلى Google إذا لم يسبق لك تسجيل الدخول، ستظهر للمستخدم شاشة موافقة مثل الشاشة الموضّحة أدناه:

الخطوة 6: التعامل مع طلبات الاستطلاع

يردّ خادم التفويض من Google على كل طلب استطلاع رأي باستخدام إحدى الردود التالية:

تم منحك إمكانية الوصول

إذا منَح المستخدم الوصول إلى الجهاز (من خلال النقر على Allow على شاشة الموافقة)، تحتوي الاستجابة على رمز دخول ورمز مميّز لإعادة التحميل. تتيح الرموز المميزة لجهازك الوصول إلى واجهات Google API نيابةً عن المستخدم. (تحدّد السمة 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 (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

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

يمكنك تجربة جميع واجهات Google API والاطّلاع على نطاقاتها في مساحة بروتوكول 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

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

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

لإعادة تحميل رمز الدخول، يرسل تطبيقك طلب 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 API

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

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

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

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

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

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

الحصول على رموز الدخول عبر بروتوكول OAuth 2.0

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

أمثلة

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

نجاح الاستجابة

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

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

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

أمثلة

الخطوة 5: رد المستخدم على طلب الوصول

الخطوة 6: التعامل مع طلبات الاستطلاع

تم منحك إمكانية الوصول

تم رفض الوصول

في انتظار التفويض

إنشاء استطلاعات بشكل متكرر

أخطاء أخرى

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

أمثلة على HTTP GET

أمثلة على curl

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

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

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

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

Drive API

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

أمثلة على `curl`