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

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

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

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

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

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

Go to the Credentials page.
انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.
اختَر نوع التطبيق أجهزة التلفزيون وأجهزة الإدخال المحدودة.
أدخِل اسمًا لعميل 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

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

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

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

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

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

يتم إجراء استطلاعات بشكل متكرّر جدًا

إذا كان الجهاز يرسِل طلبات الاستطلاع بشكل متكرر جدًا، سيعرض الخادم رسالة 403 رمز حالة استجابة HTTP (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

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

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

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

أمثلة على الحصول على HTTP

اتصال 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) بأنه يتضمن المعلَمات التالية:

الحقول
`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

تطبيق ميزة "الحماية العابرة للحساب"

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

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

https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
https://schemas.openid.net/secevent/oauth/event-type/token-revoked
https://schemas.openid.net/secevent/risc/event-type/account-disabled

يمكنك الاطّلاع على حماية حسابات المستخدمين باستخدام صفحة "الحماية العابرة للحساب" للحصول على مزيد من المعلومات حول كيفية تفعيل ميزة "الحماية العابرة للحساب" والاطّلاع على قائمة كاملة بالأحداث المتاحة.

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

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

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

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

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

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

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

أمثلة

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

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

تم تجاوز الحصة المحدّدة

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

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

أمثلة

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

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

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

تم رفض الوصول

التفويض في انتظار المراجعة

يتم إجراء استطلاعات بشكل متكرّر جدًا

أخطاء أخرى

الاتصال بـ Google APIs

أمثلة على الحصول على HTTP

أمثلة على curl

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

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

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

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

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

YouTube API

تطبيق ميزة "الحماية العابرة للحساب"

أمثلة على `curl`