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

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

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

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

البدائل

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

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

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

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

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

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

1. افتح مكتبة API في Google API Console.
2. اختَر مشروعًا أو أنشئ مشروعًا جديدًا إذا طُلب منك ذلك.
3. استخدِم صفحة المكتبة للعثور على YouTube Data API وتفعيله. ابحث عن أي واجهات برمجة تطبيقات أخرى سيستخدمها تطبيقك وفعِّلها أيضًا.

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

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

1. انتقِل إلى صفحة العملاء.
2. انقر على إنشاء عميل.
3. اختَر نوع التطبيق أجهزة التلفزيون والأجهزة التي تتطلّب إدخال بيانات محدودة.
4. أدخِل اسم عميل OAuth 2.0 وانقر على إنشاء.

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

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

قبل البدء في تنفيذ عملية تفويض OAuth 2.0، ننصحك بتحديد النطاقات التي سيحتاج تطبيقك إلى إذن للوصول إليها.

يستخدم الإصدار 3 من YouTube Data API النطاقات التالية:

اطّلِع على قائمة النطاقات المسموح بها للتطبيقات أو الأجهزة المثبَّتة.

الحصول على رموز الدخول عبر 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 التالية:

أمثلة

يعرض المقتطف التالي نموذجًا لطلب:

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly

يعرض هذا المثال الأمر curl لإرسال الطلب نفسه:

curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly" \
     https://oauth2.googleapis.com/device/code

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

سيعرض خادم التفويض إحدى الاستجابات التالية:

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

إذا كان الطلب صالحًا، سيكون ردّك عبارة عن عنصر JSON يحتوي على السمات التالية:

يعرض المقتطف التالي نموذجًا لردّ:

{
  "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.

صمِّم واجهة المستخدم مع مراعاة القواعد التالية:

• 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. يتضمّن طلب الاستطلاع المَعلمات التالية:

أمثلة

يعرض المقتطف التالي نموذجًا لطلب:

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 نيابةً عن المستخدم. (تحدّد السمة scope في الردّ واجهات برمجة التطبيقات التي يمكن للجهاز الوصول إليها).

في هذه الحالة، يحتوي الردّ من واجهة برمجة التطبيقات على الحقول التالية:

يعرض المقتطف التالي نموذجًا لردّ:

{
  "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). وتشمل هذه الأخطاء ما يلي:

استدعاء Google APIs

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

يُرجى العِلم أنّ YouTube Data API لا يتيح استخدام حسابات الخدمة إلا لمالكي المحتوى على YouTube الذين يملكون ويديرون قنوات متعددة على YouTube، مثل شركات الإنتاج واستوديوهات الأفلام.

يمكنك تجربة جميع واجهات Google APIs والاطّلاع على نطاقاتها في مساحة بروتوكول OAuth 2.0.

أمثلة على طلبات HTTP GET

قد يبدو طلب إلى نقطة النهاية youtube.channels (YouTube Data API) باستخدام عنوان Authorization: Bearer HTTP على النحو التالي. يُرجى العِلم أنّه عليك تحديد رمز الدخول الخاص بك:

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

في ما يلي طلب موجّه إلى واجهة برمجة التطبيقات نفسها للمستخدم الذي تمّت المصادقة عليه باستخدام مَعلمة سلسلة طلب البحث access_token:

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

أمثلة على curl

يمكنك اختبار هذه الأوامر باستخدام تطبيق سطر الأوامر curl. في ما يلي مثال يستخدم خيار عنوان HTTP (الخيار المفضّل):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

أو بدلاً من ذلك، خيار مَعلمة سلسلة طلب البحث:

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

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

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

لتحديث رمز دخول، يرسل تطبيقك طلب HTTPS POST إلى خادم التفويض في Google (https://oauth2.googleapis.com/token) يتضمّن المَعلمات التالية في نص الطلب:

يعرض المقتطف التالي نموذجًا لطلب:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
refresh_token=refresh_token&
grant_type=refresh_token

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

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
  "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 للأجهزة إلا للنطاقات التالية:

الوصول المستند إلى الوقت

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

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