يشرح هذا المستند كيفية منح الإذن 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 للحصول على معلومات الملف الشخصي الأساسية للمستخدم، يُرجى الاطّلاع على تسجيل الدخول على أجهزة التلفزيون وأجهزة الإدخال المحدودة.
المتطلّبات الأساسية
تمكين واجهات برمجة التطبيقات لمشروعك
على أي تطبيق يستدعي واجهات 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 |
مطلوب
معرِّف العميل لتطبيقك. يمكنك العثور على هذه القيمة في Credentials page API Console. |
||||||||||||||||
scope |
مطلوب
تمثّل هذه السمة قائمة بالنطاقات مع الفصل بينها بمسافات تحدّد الموارد التي يمكن لتطبيقك الوصول إليها نيابةً عن المستخدم. تحدِّد هذه القيم شاشة الموافقة التي تعرضها Google للمستخدم. يمكنك الاطّلاع على قائمة النطاقات المسموح بها للتطبيقات أو الأجهزة المثبّتة. تتيح "النطاقات" لتطبيقك أن يطلب إذن الوصول إلى الموارد التي يحتاج إليها فقط مع السماح أيضًا للمستخدمين بالتحكّم في مقدار أذونات الوصول التي يمنحونها لتطبيقك. وبالتالي، هناك علاقة عكسية بين عدد النطاقات المطلوبة واحتمالية الحصول على موافقة المستخدم. يستخدم الإصدار الثالث من YouTube Data API النطاقات التالية:
يوفّر مستند نطاقات واجهة برمجة التطبيقات 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.
صمِّم واجهة المستخدم (UI) مع وضع القواعد التالية في الاعتبار:
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، وإذا لم يكن المستخدم مسجّلاً الدخول، ستظهر له شاشة موافقة مثل الشاشة الموضّحة أدناه:
الخطوة 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"
}
تظل رموز الدخول لفترة محدودة. إذا كان تطبيقك يحتاج إلى الوصول إلى واجهة برمجة تطبيقات خلال فترة زمنية طويلة، يمكنه استخدام الرمز المميّز لإعادة التحميل للحصول على رمز دخول جديد. إذا كان تطبيقك يحتاج إلى هذا النوع من الوصول، عليه تخزين الرمز المميّز لإعادة التحميل لاستخدامه في وقت لاحق.
تم رفض الوصول
إذا رفض المستخدم منح إذن الوصول إلى الجهاز، ستكون استجابة الخادم
403 لرمز حالة استجابة HTTP (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). وتشمل هذه الأخطاء ما يلي:
| خطأ | رمز حالة 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 APIs
بعد حصول تطبيقك على رمز الدخول، يمكنك استخدام هذا الرمز لإجراء اتصالات بواجهة برمجة تطبيقات Google نيابةً عن حساب مستخدم معيّن إذا تم منح نطاقات الوصول التي تطلبها واجهة برمجة التطبيقات. لإجراء ذلك، يمكنك تضمين رمز الدخول في طلب إلى واجهة برمجة التطبيقات عن طريق تضمين معلَمة طلب البحث access_token أو قيمة Bearer لعنوان HTTP يتضمّن Authorization. ويُفضّل استخدام عنوان HTTP عند الإمكان، لأنّ سلاسل طلبات البحث غالبًا ما تكون مرئية في سجلّات الخادم. وفي معظم
الحالات، يمكنك استخدام مكتبة برامج لإعداد الطلبات الموجّهة إلى Google APIs (على سبيل المثال، عند
طلب بيانات من YouTube Live Streaming API).
تجدر الإشارة إلى أنّ YouTube Live Streaming API لا تتيح تدفق حساب الخدمة. وبما أنّه لا تتوفّر طريقة لربط حساب الخدمة بحساب على YouTube، ستؤدي محاولات منح الإذن في الطلبات خلال هذا الإجراء إلى ظهور خطأ NoLinkedYouTubeAccount.
يمكنك تجربة جميع واجهات Google APIs وعرض نطاقاتها في ملعب OAuth 2.0.
أمثلة على الحصول على HTTP
قد يبدو طلب نقطة نهاية
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 |
معرّف العميل الذي تم الحصول عليه من 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
emailopenidprofile
واجهة برمجة تطبيقات Drive
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