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

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

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

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

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

البدائل

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

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

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

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

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

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

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

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

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

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

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

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

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

يستخدم الإصدار 3 من 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%2Fyoutubepartner

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

curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutubepartner" \
     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 حرفًا بالحجم "عريض" . بمعنى آخر، إذا كان بإمكانك عرض الرمز WWWWWWWWWWWWWWW بشكل صحيح، فإن واجهة المستخدم الخاصة بك صالحة، ونحن نوصي باستخدام قيمة السلسلة هذه عند اختبار الطريقة يعرض user_code في واجهة المستخدم.
- الرمز user_code حسّاس لحالة الأحرف ويجب عدم تعديله بأي شكل من الأشكال، مثل تغيير حالة الأحرف أو إدراج أحرف تنسيق أخرى.
verification_url
- يجب أن تكون المساحة التي تعرض فيها الرمز 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

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

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

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

قد تبدو طلبًا موجّهًا إلى نقطة نهاية contentOwners.list (واجهة برمجة تطبيقات Content ID في YouTube) باستخدام عنوان HTTP Authorization: Bearer على النحو التالي. ملاحظة: يجب تحديد رمز الدخول الخاص بك:

GET /youtubepartner/v1/contentOwners?fetchMine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtubepartner/v1/contentOwners?access_token=access_token&fetchMine=true

أمثلة على `curl`

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtubepartner/v1/contentOwners?fetchMine=true

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

curl https://www.googleapis.com/youtubepartner/v1/contentOwners?access_token=access_token&fetchMine=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 API

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

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

أمثلة على curl

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

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

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

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

Drive API

YouTube API

تنفيذ ميزة "الحماية العابرة للحساب"

أمثلة على `curl`