يوضّح هذا المستند كيفية تنفيذ التفويض باستخدام بروتوكول 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 للحصول على معلومات الملف الشخصي الأساسية للمستخدم، يمكنك الاطّلاع على تسجيل الدخول على أجهزة التلفزيون وأجهزة الإدخال المحدودة.
المتطلبات الأساسية
تفعيل واجهات برمجة التطبيقات لمشروعك
يجب أن يفعّل أي تطبيق يستدعي Google APIs واجهات برمجة التطبيقات هذه في .
لتفعيل واجهة برمجة تطبيقات لمشروعك، اتّبِع الخطوات التالية:
- في .
- استخدِم صفحة "المكتبة" للعثور على YouTube Data API وتفعيلها. ابحث عن أي واجهات برمجة تطبيقات أخرى سيستخدمها تطبيقك وفعِّلها أيضًا.
إنشاء بيانات اعتماد التفويض
يجب أن يكون لدى أي تطبيق يستخدم بروتوكول OAuth 2.0 للوصول إلى Google APIs بيانات اعتماد تفويض تُعرّف التطبيق لخادم OAuth 2.0 في Google. توضّح الخطوات التالية كيفية إنشاء بيانات اعتماد لمشروعك. ويمكن بعد ذلك لتطبيقاتك استخدام بيانات الاعتماد للوصول إلى واجهات برمجة التطبيقات التي فعّلتها لهذا المشروع.
- انقر على إنشاء بيانات اعتماد > معرِّف عميل 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 |
مطلوب
معرّف العميل لتطبيقك. يمكنك العثور على هذه القيمة في . |
||||||||||||||||
scope |
مطلوب
قائمة مفصولة بالفواصل بالنطاقات التي تحدِّد الموارد التي يمكن لتطبيقك الوصول إليها نيابةً عن المستخدم وتُستخدَم هذه القيم لعرض شاشة الموافقة التي تعرِضها Google للمستخدم. اطّلِع على قائمة النطاقات المسموح بها للتطبيقات أو الأجهزة المثبَّتة. تتيح النطاقات لتطبيقك طلب الوصول إلى الموارد التي يحتاج إليها فقط، مع السماح للمستخدمين أيضًا بالتحكم في مقدار الوصول الذي يمنحه لتطبيقك. وبالتالي، هناك علاقة عكسية بين عدد النطاقات المطلوبة واحتمالية الحصول على موافقة المستخدم. يستخدم الإصدار 3 من YouTube Data API النطاقات التالية:
يقدّم مستند نطاقات واجهة برمجة التطبيقات OAuth 2.0 قائمة كاملة بالنطاقات التي يمكنك استخدامها للوصول إلى Google APIs. |
||||||||||||||||
أمثلة
يعرض المقتطف التالي نموذج طلب:
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 حرفًا بالحجم "عريض" . بعبارة أخرى، إذا كان بإمكانك عرض الرمزWWWWWWWWWWWWWWWبشكل صحيح، يعني ذلك أنّ واجهة المستخدم صالحة، وننصحك باستخدام قيمة السلسلة هذه عند اختبار طريقة عرض الرمزuser_codeفي واجهة المستخدم. - الرمز
user_codeحسّاس لحالة الأحرف ويجب عدم تعديله بأي شكل من الأشكال، مثل تغيير حالة الأحرف أو إدراج أحرف تنسيق أخرى.
- يجب عرض الرمز
verification_url- يجب أن تكون المساحة التي تعرض فيها
verification_urlعريضة بما يكفي لمعالجةverification_url - يجب عدم تعديل
verification_urlبأي شكل من الأشكال، إلا لإزالة المخطّط للعرض بشكل اختياري. إذا كنت تخطّط لإزالة المخطّط (مثلhttps://) من عنوان URL لأسباب متعلقة بالعرض، تأكّد من أنّ تطبيقك يمكنه التعامل مع الصيغتَينhttpوhttps.
- يجب أن تكون المساحة التي تعرض فيها
الخطوة 4: الاستعلام عن خادم التفويض في Google
بما أنّ المستخدم سيستخدم جهازًا منفصلاً للانتقال إلى verification_url
ومنح الإذن بالوصول (أو رفضه)، لن يتم تلقائيًا إشعار الجهاز المُرسِل للطلب عندما يردّ verification_url
على طلب الوصول. لهذا السبب، يجب أن يستطلِع الجهاز المُرسِل
خادم التفويض في Google لتحديد وقت ردّ المستخدم على الطلب.
يجب أن يواصل الجهاز المُرسِل إرسال طلبات الاستطلاع إلى أن يتلقّى استجابة
تشير إلى أنّ المستخدم قد ردّ على طلب الوصول أو إلى أن تنتهي صلاحية device_code
وuser_code اللذَين تم الحصول عليهما في
الخطوة 2. يحدِّد العنصر interval الذي تم إرجاعه في الخطوة 2 مقدار
الوقت بالثواني الذي يجب الانتظاره بين الطلبات.
عنوان URL لنقطة النهاية التي يتم الاستعلام عنها هو https://oauth2.googleapis.com/token. يحتوي طلب الاستطلاع
على المَعلمات التالية:
| المعلمات | |
|---|---|
client_id |
معرّف العميل لتطبيقك. يمكنك العثور على هذه القيمة في . |
client_secret |
سر العميل لـ client_id المقدَّم يمكنك العثور على هذه القيمة في
. |
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 نيابةً عن المستخدم. (يحدِّد الحقل 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" }
أخطاء أخرى
يعرض خادم التفويض أيضًا أخطاء إذا كان طلب الاستطلاع لا يتضمّن أيًا من المَعلمات المطلوبة
أو إذا كانت قيمة المَعلمة غير صحيحة. تحتوي هذه الطلبات عادةً على رمز حالة استجابة HTTP هو 400
(Bad Request) أو 401 (Unauthorized). وتشمل هذه الأخطاء ما يلي:
| خطأ | رمز حالة HTTP | الوصف |
|---|---|---|
admin_policy_enforced |
400 |
لا يمكن لحساب Google تفويض نطاق واحد أو أكثر من النطاقات المطلوبة بسبب سياسات مشرف Google Workspace. اطّلِع على مقالة التحكّم في اختيار التطبيقات التابعة لجهات خارجية والتطبيقات الداخلية التي يمكنها الوصول إلى بيانات Google Workspace ضمن مساعدة مشرف Google Workspace للحصول على مزيد من المعلومات عن كيفية حظر أحد المشرفين للوصول إلى النطاقات إلى أن يتم منح إذن الوصول صراحةً إلى العميل OAuth. |
invalid_client |
401 |
لم يتم العثور على عميل OAuth. على سبيل المثال، يحدث هذا الخطأ إذا كانت قيمة المَعلمة
نوع عميل OAuth غير صحيح. تأكَّد من ضبط نوع التطبيق لمعرّف العميل على أجهزة التلفزيون والأجهزة التي تتطلّب إدخال بيانات محدودة. |
invalid_grant |
400 |
قيمة المَعلمة code غير صالحة أو سبق أن تمّت المطالبة بها أو لا يمكن
تحليلها. |
unsupported_grant_type |
400 |
قيمة المَعلمة grant_type غير صالحة. |
org_internal |
403 |
معرّف عميل OAuth في الطلب هو جزء من مشروع يحدّ من الوصول إلى حسابات Google في مؤسسة Google Cloud معيّنة. أكِّد إعدادات نوع العميل لتطبيق OAuth. |
استدعاء واجهات برمجة تطبيقات Google
بعد أن يحصل تطبيقك على رمز مميّز للوصول، يمكنك استخدام الرمز المميّز لإجراء طلبات إلى واجهة برمجة تطبيقات Google
نيابةً عن حساب مستخدم معيّن
إذا تم منح نطاق الوصول المطلوب من واجهة برمجة التطبيقات. لإجراء ذلك، أدرِج رمز access_token Bearer access_token ��Authorization يُفضّل استخدام عنوان HTTP كلما أمكن، لأنّ سلاسل طلبات البحث غالبًا ما تكون مرئية في سجلات الخادم. في معظم
الحالات، يمكنك استخدام مكتبة عملاء لإعداد طلباتك إلى واجهات برمجة تطبيقات Google (على سبيل المثال، عند
طلب YouTube Live Streaming API).
تجدر الإشارة إلى أنّ واجهة برمجة التطبيقات YouTube Live Streaming API لا تتيح مسار حساب الخدمة. بما أنّه ليس هناك
طريقة لربط حساب خدمة بحساب YouTube، ستؤدي محاولات تفويض الطلبات باستخدام هذه الخطوات
إلى ظهور خطأ NoLinkedYouTubeAccount.
يمكنك تجربة جميع واجهات برمجة تطبيقات Google والاطّلاع على نطاقات الوصول إليها على مساحة بروتوكول OAuth 2.0.
أمثلة على طلبات HTTP GET
قد تبدو طلبًا موجّهًا إلى نقطة نهاية
liveBroadcasts.list (YouTube Live Streaming API) باستخدام عنوان 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 |
معرِّف العميل الذي تم الحصول عليه من . |
client_secret |
سر العميل الذي تم الحصول عليه من |
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 https://www.googleapis.com/auth/calendar.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
emailopenidprofile
Drive API
https://www.googleapis.com/auth/drive.appdatahttps://www.googleapis.com/auth/drive.file
YouTube API
https://www.googleapis.com/auth/youtubehttps://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
اطّلِع على صفحة "حماية حسابات المستخدمين من خلال ميزة "الحماية العابرة للحساب" للحصول على مزيد من المعلومات عن كيفية تنفيذ ميزة "الحماية العابرة للحساب" والاطّلاع على القائمة الكاملة للأحداث المتاحة.