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

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

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

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

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

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

  1. Open the API Library في Google API Console.
  2. If prompted, select a project, or create a new one.
  3. استخدِم صفحة "المكتبة" للعثور على YouTube Data API وتفعيلها. ابحث عن أي واجهات برمجة تطبيقات أخرى سيستخدمها تطبيقك وفعِّلها أيضًا.

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

يجب أن تتوفر لدى أي تطبيق يستخدم 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، ننصحك بتحديد النطاقات التي سيحتاج تطبيقك إلى إذن للوصول إليها.

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

المناظير
https://www.googleapis.com/auth/youtubeإدارة حسابك في YouTube
https://www.googleapis.com/auth/youtube.channel-memberships.creatorالاطّلاع على قائمة بأعضاء القناة النشطين حاليًا ومستواهم الحالي وتاريخ انضمامهم
https://www.googleapis.com/auth/youtube.force-sslالاطّلاع على فيديوهاتك على YouTube وتقييماتها وتعليقاتها وترجماتها وكذلك تعديلها وحذفها نهائيًا
https://www.googleapis.com/auth/youtube.readonlyعرض حسابك في YouTube
https://www.googleapis.com/auth/youtube.uploadإدارة فيديوهات YouTube
https://www.googleapis.com/auth/youtubepartnerعرض وإدارة أصولك والمحتوى المرتبط بها على YouTube
https://www.googleapis.com/auth/youtubepartner-channel-auditعرض معلومات خاصة عن قناتك على YouTube ذات صلة أثناء عملية تدقيق شريك YouTube

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

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

معرِّف العميل لتطبيقك. يمكنك العثور على هذه القيمة في Credentials page API Console.

scope مطلوب

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

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

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

المناظير
https://www.googleapis.com/auth/youtubeإدارة حسابك في YouTube
https://www.googleapis.com/auth/youtube.channel-memberships.creatorالاطّلاع على قائمة بأعضاء القناة النشطين حاليًا ومستواهم الحالي وتاريخ انضمامهم
https://www.googleapis.com/auth/youtube.force-sslالاطّلاع على فيديوهاتك على YouTube وتقييماتها وتعليقاتها وترجماتها وكذلك تعديلها وحذفها نهائيًا
https://www.googleapis.com/auth/youtube.readonlyعرض حسابك في YouTube
https://www.googleapis.com/auth/youtube.uploadإدارة فيديوهات YouTube
https://www.googleapis.com/auth/youtubepartnerعرض وإدارة أصولك والمحتوى المرتبط بها على YouTube
https://www.googleapis.com/auth/youtubepartner-channel-auditعرض معلومات خاصة عن قناتك على YouTube ذات صلة أثناء عملية تدقيق شريك YouTube

يوفّر مستند نطاقات واجهة برمجة التطبيقات OAuth 2.0 قائمة كاملة بالنطاقات التي قد تستخدمها للوصول إلى واجهات برمجة تطبيقات Google.

أمثلة

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

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.force-ssl

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

curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl" \
     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.

صمم واجهة المستخدم الخاصة بك مع وضع القواعد التالية في الاعتبار:

  • 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 معرِّف العميل لتطبيقك. يمكنك العثور على هذه القيمة في Credentials page API Console.
client_secret سر العميل للسمة client_id المقدَّمة. يمكنك العثور على هذه القيمة في Credentials page API Console.
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"
}

أخطاء أخرى

يعرض خادم التفويض أيضًا أخطاء إذا كان طلب الاستطلاع لا يحتوي على أي معلَمات مطلوبة أو يحتوي على قيمة معلَمة غير صحيحة. وعادةً ما يكون لهذه الطلبات رمز الاستجابة 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 (على سبيل المثال، عند الاتصال بواجهة YouTube Live Streaming API).

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

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

أمثلة على HTTP GET

قد يبدو طلب نقطة النهاية liveBroadcasts.list (واجهة برمجة التطبيقات لبث YouTube المباشر) باستخدام عنوان HTTP Authorization: Bearer على النحو التالي. لاحظ أنك تحتاج إلى تحديد رمز الدخول الخاص بك:

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

أمثلة على curl

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

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

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

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

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

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

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