يوضح هذا المستند كيفية تنفيذ تفويض OAuth 2.0 للوصول إلى YouTube Analytics API أو YouTube Reporting API من تطبيق ويب JavaScript يسمح OAuth 2.0 للمستخدمين بإجراء ما يلي: مشاركة بيانات محددة مع أحد التطبيقات مع الاحتفاظ بأسماء المستخدمين وكلمات المرور وغيرها خصوصية المعلومات. على سبيل المثال، يمكن لأحد التطبيقات استخدام OAuth 2.0 للحصول على إذن لاسترداد بيانات "إحصاءات YouTube" لقناة
ويُعرف مسار OAuth 2.0 هذا باسم تدفق المنح الضمني. لقد صُممت من أجل التطبيقات التي يمكنها الوصول إلى واجهات برمجة التطبيقات فقط أثناء تواجد المستخدم في التطبيق هذه لا يمكن للتطبيقات تخزين معلومات سرية.
خلال هذه العملية، يفتح تطبيقك عنوان URL على Google يستخدم مَعلمات طلب البحث لتحديد تطبيقك. ونوع الوصول إلى واجهة برمجة التطبيقات الذي يتطلبه التطبيق. يمكنك فتح عنوان URL في المتصفّح الحالي. نافذة أو نافذة منبثقة. يمكن للمستخدم المصادقة من خلال Google ومنح الأذونات المطلوبة. بعد ذلك، تُعيد Google توجيه المستخدِم مرة أخرى إلى تطبيقك. تتضمن عملية إعادة التوجيه رمز دخول يتحقّق تطبيقك من ذلك ثم يستخدمها لإرسال طلبات البيانات من واجهة برمجة التطبيقات.
مكتبة عملاء Google APIs وخدمات Google Identity
في حال استخدام مكتبة برامج Google APIs للغة JavaScript لإجراء مكالمات مسموح بها مع Google، يجب استخدام مكتبة JavaScript لخدمات هوية Google لمعالجة مسار OAuth 2.0. يُرجى مراجعة Google خدمات الهوية نموذج الرمز المميز، وهو استنادًا إلى تدفق المنح الضمني لـ OAuth 2.0.
المتطلبات الأساسية
تمكين واجهات برمجة التطبيقات لمشروعك
يحتاج أي تطبيق يستدعي واجهات Google APIs إلى تفعيل واجهات برمجة التطبيقات هذه في API Console
لتفعيل واجهة برمجة تطبيقات لمشروعك:
- Open the API Library في Google API Console
- If prompted, select a project, or create a new one.
- يمكنك الانتقال إلى صفحة "المكتبة" للعثور على YouTube Analytics API وواجهة YouTube Reporting API وتفعيلهما. والعديد من التطبيقات التي تسترد بيانات "إحصاءات YouTube" تتفاعل أيضًا مع YouTube Data API. ابحث عن أي واجهات برمجة تطبيقات أخرى سيستخدمها تطبيقك وفعّلها أيضًا.
إنشاء بيانات اعتماد التفويض
يجب أن تكون بيانات اعتماد التفويض متاحة لأي تطبيق يستخدم OAuth 2.0 للوصول إلى واجهات Google APIs. التي تعرّف التطبيق على خادم OAuth 2.0 من Google. توضّح الخطوات التالية كيفية وإنشاء أوراق اعتماد لمشروعك. ويمكن لتطبيقاتك بعد ذلك استخدام بيانات الاعتماد للوصول إلى واجهات برمجة التطبيقات. التي قمت بتمكينها لهذا المشروع.
- Go to the Credentials page.
- انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.
- اختَر نوع تطبيق تطبيق الويب.
- أكمل النموذج. التطبيقات التي تستخدم JavaScript لتقديم طلبات Google API المعتمَدة يجب تحديد مصادر JavaScript معتمَدة. تحدد الأصول النطاقات من الذي يمكن لتطبيقك إرسال طلبات منه إلى خادم OAuth 2.0. يجب أن تتقيّد هذه المصادر قواعد التحقّق في Google
تحديد نطاقات الوصول
تتيح النطاقات لتطبيقك أن يطلب فقط الوصول إلى الموارد التي يحتاج إليها مع لتمكين المستخدمين من التحكم في مقدار الوصول الذي يمنحونه لتطبيقك. وبالتالي، علاقة عكسية بين عدد النطاقات المطلوبة واحتمال والحصول على موافقة المستخدم.
قبل البدء في تنفيذ تفويض OAuth 2.0، ننصحك بتحديد النطاقات سيحتاج تطبيقك إلى إذن للوصول إليه.
تستخدم YouTube Analytics API النطاقات التالية:
النطاقات | |
---|---|
https://www.googleapis.com/auth/youtube | إدارة حساب يوتيوب الخاص بك |
https://www.googleapis.com/auth/youtube.readonly | عرض حساب YouTube الخاص بك |
https://www.googleapis.com/auth/youtubepartner | عرض وإدارة الأصول الخاصة بك والمحتوى المرتبط بها على YouTube |
https://www.googleapis.com/auth/yt-analytics-monetary.readonly | عرض تقارير YouTube Analytics النقدية وغير النقدية لمحتوى YouTube الخاص بك |
https://www.googleapis.com/auth/yt-analytics.readonly | عرض تقارير YouTube Analytics لمحتوى YouTube الخاص بك |
تستخدم YouTube Reporting API النطاقات التالية:
النطاقات | |
---|---|
https://www.googleapis.com/auth/yt-analytics-monetary.readonly | عرض تقارير YouTube Analytics النقدية وغير النقدية لمحتوى YouTube الخاص بك |
https://www.googleapis.com/auth/yt-analytics.readonly | عرض تقارير YouTube Analytics لمحتوى YouTube الخاص بك |
يحتوي مستند نطاقات واجهة برمجة تطبيقات OAuth 2.0 على رابط بالنطاقات التي قد تستخدمها للوصول إلى Google APIs.
الحصول على رموز الدخول عبر OAuth 2.0
توضّح الخطوات التالية كيفية تفاعل تطبيقك مع خادم OAuth 2.0 من Google للحصول على موافقة المستخدم على تنفيذ طلب واجهة برمجة التطبيقات نيابةً عنه يجب أن يحتوي التطبيق على البيانات التالية: الموافقة قبل أن تتمكّن من تنفيذ طلب Google API الذي يتطلب تفويض المستخدم.
الخطوة 1: إعادة التوجيه إلى خادم OAuth 2.0 من Google
لطلب إذن الوصول إلى بيانات أحد المستخدمين، عليك إعادة توجيه المستخدم إلى OAuth 2.0 من Google. الخادم.
نقاط نهاية OAuth 2.0
إنشاء عنوان URL لطلب الوصول من نقطة نهاية OAuth 2.0 من Google على
https://accounts.google.com/o/oauth2/v2/auth
يمكن الوصول إلى نقطة النهاية هذه عبر HTTPS.
يتم رفض اتصالات HTTP العادية.
يدعم خادم تفويض Google معلمات سلسلة طلب البحث التالية للويب تطبيقات الخادم:
المعلمات | |||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
مطلوب
معرِّف العميل لتطبيقك. يمكنك العثور على هذه القيمة في API Console Credentials page |
||||||||||||||||||
redirect_uri |
مطلوب
تحدد المكان الذي يعيد فيه خادم واجهة برمجة التطبيقات توجيه المستخدم بعد إكمال المستخدم لعملية
مسار التفويض. يجب أن تتطابق القيمة تمامًا مع أحد معرّفات الموارد المنتظمة (URI) المصرّح بها لإعادة التوجيه
عميل OAuth 2.0، الذي هيأته في نافذة حساب العميل
API Console
Credentials pageوإذا لم تتطابق هذه القيمة مع
معرّف الموارد المنتظم (URI) المعتمَد لإعادة التوجيه لمعرّف تجدر الإشارة إلى أنّ المخطَّط |
||||||||||||||||||
response_type |
مطلوب
تحتاج تطبيقات JavaScript إلى ضبط قيمة المَعلمة على |
||||||||||||||||||
scope |
مطلوب
حاسمة مفصولة بمسافات قائمة بالنطاقات التي تحدد الموارد التي يمكن لتطبيقك الوصول إليها على نيابة عن المستخدم. تحدِّد هذه القيم شاشة الموافقة التي تعرضها Google على المستخدم. تتيح النطاقات لتطبيقك طلب الوصول إلى الموارد التي يحتاج إليها فقط. مع تمكين المستخدمين أيضًا من التحكم في مقدار الوصول الذي يمنحونه إلى التطبيق. وبالتالي، توجد علاقة عكسية بين عدد النطاقات المطلوبة. واحتمالية الحصول على موافقة المستخدم. تستخدم YouTube Analytics API النطاقات التالية:
تستخدم YouTube Reporting API النطاقات التالية:
يوفر مستند نطاقات واجهة برمجة تطبيقات OAuth 2.0 قائمة كاملة بالنطاقات التي قد تستخدمها للوصول إلى واجهات برمجة تطبيقات Google. ننصح بأن يطلب تطبيقك الوصول إلى نطاقات التفويض في السياق. كلما أمكن ذلك. من خلال طلب الوصول إلى بيانات المستخدم في السياق، عبر تزايديًا، يمكنك مساعدة المستخدمين في فهم سبب احتياج تطبيقك إلى الوصول الذي يطلبه. |
||||||||||||||||||
state |
مقترَح
تحدِّد هذه السياسة أي قيمة سلسلة يستخدمها تطبيقك للحفاظ على الحالة بين
طلب التفويض واستجابة خادم التفويض.
يعرض الخادم القيمة الدقيقة التي ترسلها كزوج ويمكنك استخدام هذه المعلمة لعدة أغراض، مثل توجيه المستخدم إلى الصفحة
المورد الصحيح في تطبيقك، وإرسال nonces، وتخفيف طلبات المواقع الإلكترونية المشتركة
التزوير. بما أنّه يمكن تخمين |
||||||||||||||||||
include_granted_scopes |
اختياريّ
يعمل هذا الإعداد على السماح للتطبيقات باستخدام التفويض التزايدي لطلب الوصول إلى
والنطاقات في السياق. إذا ضبطت قيمة هذه المَعلمة على |
||||||||||||||||||
enable_granular_consent |
اختياريّ
وتكون القيمة التلقائية هي وعند تفعيل Google لأذونات دقيقة لأحد التطبيقات، لن تترتب على هذه المعلَمة يكون لها أي تأثير. |
||||||||||||||||||
login_hint |
اختياريّ
إذا كان التطبيق يعرف المستخدِم الذي يحاول المصادقة، يمكنه استخدام هذه المَعلمة لتقديم تلميح إلى خادم مصادقة Google. ويستخدم الخادم التلميح يمكنك تبسيط عملية تسجيل الدخول إما من خلال ملء حقل البريد الإلكتروني مسبقًا في نموذج تسجيل الدخول أو من خلال واختيار جلسة تسجيل الدخول المتعدد المناسبة. اضبط قيمة المَعلمة على عنوان بريد إلكتروني أو معرِّف |
||||||||||||||||||
prompt |
اختياريّ
قائمة برسائل طلب لعرض المستخدم، مع الفصل بينها بمسافات، حساسة لحالة الأحرف. إذا لم تحدد تحديد هذه المعلمة، فسيتم طلب موافقة المستخدم فقط في المرة الأولى يطلب الوصول إلى الجهاز. عرض طلب إعادة الموافقة لمزيد من المعلومات. القيم المتاحة:
|
نموذج لإعادة التوجيه إلى خادم تفويض Google
يطلب نموذج عنوان URL أدناه الوصول بلا إنترنت
(access_type=offline
) إلى نطاق يسمح بالوصول إلى
تقارير YouTube Analytics للمستخدم. فهو يستخدم تفويضًا تزايديًا
التأكد من أن رمز الدخول الجديد يشمل أي نطاقات يستطيع المستخدم
منح الإذن للتطبيق مسبقًا. يعيِّن عنوان URL أيضًا قيمًا
متطلبات redirect_uri
وresponse_type
و
معلمات client_id
وكذلك state
. يحتوي عنوان URL على فواصل أسطر ومسافات لسهولة القراءة.
https://accounts.google.com/o/oauth2/v2/auth?
scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly&
include_granted_scopes=true&
state=state_parameter_passthrough_value&
redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
response_type=token&
client_id=client_id
بعد إنشاء عنوان URL للطلب، أعِد توجيه المستخدم إليه.
نموذج رمز JavaScript
يعرض مقتطف JavaScript التالي كيفية بدء تدفق التفويض في JavaScript بدون استخدام مكتبة برامج Google APIs للغة JavaScript. بما أن بروتوكول OAuth هذا لا تتيح نقطة النهاية 2.0 استخدام مشاركة الموارد المتعدّدة المصادر (CORS)، وينشئ المقتطف نموذج يفتح الطلب على نقطة النهاية هذه.
/* * Create form to request access token from Google's OAuth 2.0 server. */ function oauthSignIn() { // Google's OAuth 2.0 endpoint for requesting an access token var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth'; // Create <form> element to submit parameters to OAuth 2.0 endpoint. var form = document.createElement('form'); form.setAttribute('method', 'GET'); // Send as a GET request. form.setAttribute('action', oauth2Endpoint); // Parameters to pass to OAuth 2.0 endpoint. var params = {'client_id': 'YOUR_CLIENT_ID', 'redirect_uri': 'YOUR_REDIRECT_URI', 'response_type': 'token', 'scope': 'https://www.googleapis.com/auth/yt-analytics.readonly', 'include_granted_scopes': 'true', 'state': 'pass-through value'}; // Add form parameters as hidden input values. for (var p in params) { var input = document.createElement('input'); input.setAttribute('type', 'hidden'); input.setAttribute('name', p); input.setAttribute('value', params[p]); form.appendChild(input); } // Add form to page and submit it to open the OAuth 2.0 endpoint. document.body.appendChild(form); form.submit(); }
الخطوة 2: طلب الموافقة من Google من المستخدم
في هذه الخطوة، يقرِّر المستخدم ما إذا كان سيمنح تطبيقك إذن الوصول المطلوب. في هذا الوقت تعرض Google نافذة موافقة تعرض اسم تطبيقك وGoogle API. الخدمات التي يطلب الإذن بالوصول إليها باستخدام بيانات اعتماد تفويض المستخدم ملخصًا لنطاقات الوصول التي سيتم منحها. تشير رسالة الأشكال البيانية يمكن للمستخدم الموافقة بعد ذلك على منح إذن الوصول إلى نطاق واحد أو أكثر يطلبه تطبيقك أو لرفض الطلب.
لا يحتاج طلبك إلى اتخاذ أي إجراء في هذه المرحلة، إذ إنّه ينتظر الردّ من خادم OAuth 2.0 في Google يشير إلى ما إذا تم منح أي إمكانية وصول. يتم شرح هذا الرد في الخطوة التالية.
الأخطاء
قد تعرض الطلبات المُرسَلة إلى نقطة نهاية تفويض OAuth 2.0 من Google رسائل خطأ موجّهة للمستخدمين. بدلاً من مسارات المصادقة والترخيص المتوقعة. رموز الخطأ الشائعة والمقترحة والحلول مدرجة أدناه.
admin_policy_enforced
يتعذّر على حساب Google تفويض نطاق واحد أو أكثر من النطاقات المطلوبة بسبب سياسات مشرف Google Workspace. الاطّلاع على مقالة المساعدة "مشرف Google Workspace" التحكّم في الجهات الخارجية وصول التطبيقات الداخلية إلى بيانات Google Workspace لمزيد من المعلومات حول كيفية تقييد المشرف لإمكانية الوصول إلى جميع النطاقات أو الوصول إلى أن يتم منح إذن الوصول صراحةً إلى معرِّف عميل OAuth.
disallowed_useragent
يتم عرض نقطة نهاية التفويض داخل وكيل مستخدم مضمّن غير مسموح به من قِبل Google سياسات OAuth 2.0.
Android
قد تظهر رسالة الخطأ هذه لمطوِّري تطبيقات Android عند فتح طلبات الحصول على إذن في
android.webkit.WebView
وبدلاً من ذلك، على المطوّرين استخدام مكتبات Android مثل
تسجيل الدخول باستخدام حساب Google لنظام التشغيل Android أو OpenID Foundation
تطبيق AppAuth لنظام التشغيل Android
قد يواجه مطوّرو الويب هذا الخطأ عندما يفتح تطبيق Android رابط ويب عامًا في وكيل مستخدم مضمن وينتقل المستخدم إلى نقطة نهاية تفويض OAuth 2.0 في Google من موقعك الإلكتروني. على المطوّرين السماح بفتح الروابط العامة في معالِج الروابط التلقائي نظام التشغيل، والذي يشمل كلاً من Android App Links المستخدم أو تطبيق المتصفح الافتراضي. تشير رسالة الأشكال البيانية علامات التبويب المخصَّصة في Android المكتبة خيارًا متوافقًا.
iOS
قد يواجه مطوّرو iOS وmacOS هذا الخطأ عند فتح طلبات التفويض في
WKWebView
وبدلاً من ذلك، يجب أن يستخدم المطوّرون مكتبات iOS مثل
تسجيل الدخول باستخدام حساب Google لأجهزة iOS أو OpenID Foundation
تطبيق AppAuth لنظام التشغيل iOS
قد يظهر هذا الخطأ لمطوِّري الويب عندما يفتح تطبيق iOS أو macOS رابط ويب عامًا في
وكيل مستخدم مضمن وينتقل المستخدم إلى نقطة نهاية تفويض OAuth 2.0 في Google من
موقعك الإلكتروني. على المطوّرين السماح بفتح الروابط العامة في معالِج الروابط التلقائي
نظام التشغيل، والذي يشمل كلاً من
الروابط العامة
المستخدم أو تطبيق المتصفح الافتراضي. تشير رسالة الأشكال البيانية
SFSafariViewController
المكتبة خيارًا متوافقًا.
org_internal
معرِّف عميل OAuth في الطلب هو جزء من مشروع يحدّ من إمكانية الوصول إلى حسابات Google في محددة مؤسسة Google Cloud: لمزيد من المعلومات حول خيار التهيئة هذا، راجع نوع المستخدِم في مقالة المساعدة "إعداد شاشة طلب الموافقة المتعلقة ببروتوكول OAuth".
invalid_client
المصدر الذي تم تقديم الطلب منه غير مسموح به لهذا العميل. عرض
origin_mismatch
invalid_grant
عند استخدام تفويض متزايد، ربما تكون صلاحية الرمز المميّز قد انتهت. أو تم إبطاله. عليك المصادقة على المستخدم مرة أخرى وطلب موافقة المستخدم للحصول على رموز مميّزة جديدة. في حال المتابعة لمشاهدة هذا الخطأ، فتأكد من تهيئة تطبيقك بشكل صحيح وأنك باستخدام الرموز والمعلمات الصحيحة في طلبك. بخلاف ذلك، قد يحتوي حساب المستخدم على حذف بيانات النشاط التجاري أو إيقافها.
origin_mismatch
قد لا يكون مخطط و/أو نطاق و/أو منفذ JavaScript الذي ينشأ عن طلب التفويض تطابق معرّف موارد منتظم (URI) لمصدر JavaScript معتمد ومسجَّل لمعرّف عميل OAuth. تم منح الإذن بالمراجعة مصادر JavaScript في Google API Console Credentials page
redirect_uri_mismatch
redirect_uri
الذي تم تمريره في طلب التفويض لا يتطابق مع القيمة المُصرّح بها.
معرِّف الموارد المنتظم (URI) لإعادة التوجيه لمعرِّف عميل OAuth. مراجعة معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه في
Google API Console Credentials page
قد لا يكون مخطط و/أو نطاق و/أو منفذ JavaScript الذي ينشأ عن طلب التفويض تطابق معرّف موارد منتظم (URI) لمصدر JavaScript معتمد ومسجَّل لمعرّف عميل OAuth. تعليق مصادر JavaScript المسموح بها في Google API Console Credentials page
قد تشير المعلَمة redirect_uri
إلى مسار OAuth خارج النطاق (OOB) الذي يتضمن
تم إيقافها ولم تعد متاحة. ارجع إلى
دليل نقل البيانات لتعديل
التكامل.
invalid_request
حدث خطأ في الطلب الذي قدّمته. وقد يرجع ذلك إلى عدة أسباب:
- لم يتم تنسيق الطلب بشكل صحيح
- كان الطلب يفتقد إلى المعلمات المطلوبة
- يستخدم الطلب طريقة إذن لا تتوافق مع Google. التحقّق من بروتوكول OAuth طريقة الدمج تستخدم طريقة دمج موصى بها
الخطوة 3: التعامل مع استجابة خادم OAuth 2.0
نقاط نهاية OAuth 2.0
يرسل خادم OAuth 2.0 استجابة إلى redirect_uri
المحددة في
طلب رمز الدخول.
إذا وافق المستخدم على الطلب، سيحتوي الرد على رمز دخول. إذا كان المستخدم لا يوافق على الطلب، يحتوي الرد على رسالة خطأ. رمز الدخول أو على جزء علامة التجزئة من عنوان URI لإعادة التوجيه، كما هو موضح أدناه:
استجابة رمز الدخول:
https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600
بالإضافة إلى المعلمة
access_token
، تتضمن سلسلة التجزئة أيضًا يحتوي على المعلمةtoken_type
، التي يتم تعيينها دائمًا علىBearer
، والمعلمةexpires_in
، التي تحدد فترة بقاء الرمز المميّز بالثواني. إذا تم تحديد مَعلمةstate
في طلب رمز الدخول، يتم تضمين قيمته أيضًا في الاستجابة.- ظهور خطأ:
https://oauth2.example.com/callback#error=access_denied
نموذج استجابة خادم OAuth 2.0
يمكنك اختبار هذا المسار بالنقر على نموذج عنوان URL التالي، الذي يطلب إذن بالقراءة فقط لعرض البيانات الوصفية للملفات في Google Drive:
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly& include_granted_scopes=true& state=state_parameter_passthrough_value& redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback& response_type=token& client_id=client_id
بعد إكمال مسار OAuth 2.0، ستتم إعادة توجيهك إلى
http://localhost/oauth2callback
سيؤدي عنوان URL هذا إلى
خطأ واحد (404 NOT FOUND
) ما لم يتصادف أن يعرض جهازك المحلي ملفًا في
هذا العنوان. توفر الخطوة التالية مزيدًا من التفاصيل حول المعلومات التي يتم عرضها في
معرّف موارد منتظم (URI) عندما تتم إعادة توجيه المستخدم إلى تطبيقك مرة أخرى.
الاتصال بـ Google APIs
نقاط نهاية OAuth 2.0
بعد حصول تطبيقك على رمز الدخول، يمكنك استخدام الرمز لإجراء اتصالات
واجهة برمجة التطبيقات نيابةً عن مستخدم معيّن
حساب مستخدم في حال منح نطاقات الوصول التي تطلبها واجهة برمجة التطبيقات. للقيام بذلك، قم بتضمين
رمز الدخول في طلب إلى واجهة برمجة التطبيقات عن طريق تضمين طلب بحث access_token
مَعلمة أو قيمة Bearer
لعنوان HTTP يتضمّن Authorization
. عندما يكون ذلك ممكنًا،
ويُفضل استخدام عنوان HTTP، لأن سلاسل طلبات البحث غالبًا ما تكون مرئية في سجلات الخادم. في معظم
يمكنك استخدام مكتبة برامج لإعداد الطلبات إلى Google APIs (على سبيل المثال، عند
"واجهة برمجة تطبيقات YouTube Analytics").
تجدر الإشارة إلى أنّ YouTube Analytics API لا تتيح استخدام حساب الخدمة. التدفق. تتيح واجهة YouTube Reporting API استخدام حسابات الخدمة فقط مالكو المحتوى على YouTube الذين يملكون قنوات متعددة على YouTube ويديرونها، مثل كشركات إنتاج واستوديوهات أفلام.
يمكنك تجربة جميع واجهات Google APIs وعرض نطاقاتها من خلال ملعب OAuth 2.0.
أمثلة على الحصول على HTTP
اتصال
reports.query
نقطة نهاية (واجهة برمجة تطبيقات "إحصاءات YouTube") باستخدام Authorization: Bearer
HTTP
على النحو التالي. ملاحظة: يجب تحديد رمز الدخول الخاص بك:
GET /youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
إليك طلب بيانات من واجهة برمجة التطبيقات نفسها للمستخدم الذي تمت مصادقته باستخدام access_token
مَعلمة سلسلة طلب البحث:
GET https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
أمثلة على curl
يمكنك اختبار هذه الأوامر باستخدام تطبيق سطر الأوامر curl
. إليك
مثال يستخدم خيار عنوان HTTP (مفضّل):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
أو بدلاً من ذلك، خيار مَعلمة سلسلة طلب البحث:
curl https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
نموذج رمز JavaScript
يوضح مقتطف الرمز أدناه كيفية استخدام سياسة مشاركة الموارد المتعددة المصادر (CORS) لإرسال إلى واجهة برمجة تطبيقات Google. لا يستخدم هذا المثال مكتبة برامج Google APIs للغة JavaScript. ومع ذلك، حتى إذا لم تكن تستخدم مكتبة البرامج، من المحتمل أن يساعدك دليل دعم سياسة مشاركة الموارد المتعددة المصادر (CORS) في مستندات هذه المكتبة لفهم هذه الطلبات بشكل أفضل.
في مقتطف الرمز هذا، يمثّل المتغيّر access_token
الرمز المميّز الذي تملكه
تم الحصول عليه لتقديم طلبات بيانات من واجهة برمجة التطبيقات نيابةً عن المستخدم المفوّض. يعلم مقياس اكتمال
مثال يوضح كيفية تخزين هذا الرمز المميز في مساحة التخزين المحلية للمتصفح واسترداده
عند تقديم طلب واجهة برمجة التطبيقات.
var xhr = new XMLHttpRequest(); xhr.open('GET', 'https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views&' + 'access_token=' + params['access_token']); xhr.onreadystatechange = function (e) { console.log(xhr.response); }; xhr.send(null);
المثال الكامل
نقاط نهاية OAuth 2.0
يوضح نموذج الرمز هذا كيفية إكمال مسار OAuth 2.0 في JavaScript بدون استخدام مكتبة برامج Google APIs للغة JavaScript. يكون الرمز مخصصًا لصفحة HTML تعرض زرًا جرِّب طلب واجهة برمجة تطبيقات. عند النقر على الزر، يتحقق الرمز البرمجي لمعرفة ما إذا كانت الصفحة قد خزنت رمز الدخول إلى واجهة برمجة التطبيقات في مساحة التخزين المحلية في المتصفّح. في هذه الحالة، سيتم تنفيذ طلب البيانات من واجهة برمجة التطبيقات. وإلا، يؤدي إلى بدء تدفق OAuth 2.0.
بالنسبة إلى مسار OAuth 2.0، تتّبع الصفحة الخطوات التالية:
- وهو يوجه المستخدم إلى خادم OAuth 2.0 من Google، والذي يطلب الوصول إلى
نطاق واحد (
https://www.googleapis.com/auth/yt-analytics.readonly
). - بعد منح (أو رفض) إذن الوصول إلى نطاق واحد أو أكثر من النطاقات المطلوبة، تتم إعادة توجيه المستخدم إلى الصفحة الأصلية، التي تحلل رمز الدخول من سلسلة معرف الجزء.
تستخدم الصفحة رمز الدخول لإجراء نموذج طلب البيانات من واجهة برمجة التطبيقات.
يستدعي طلب البيانات من واجهة برمجة التطبيقات هذا
reports.query
الخاصة بواجهة برمجة تطبيقات YouTube Analytics. لاسترداد عدد المشاهدات لقناة المستخدم المصرّح بها على YouTube.- في حال تنفيذ الطلب بنجاح، يتم تسجيل استجابة واجهة برمجة التطبيقات في عملية تصحيح الأخطاء في المتصفّح. وحدة التحكم.
ويمكنك إبطال إمكانية الوصول إلى التطبيق من خلال الأذونات حساب Google. سيتم إدراج التطبيق على أنّه الإصدار التجريبي من OAuth 2.0 لمستندات Google API.
لتشغيل هذا الرمز محليًا، يجب ضبط قيم للسمة YOUR_CLIENT_ID
متغيرات YOUR_REDIRECT_URI
التي تتوافق مع
بيانات الاعتماد الخاصة بالتفويض. المتغيّر YOUR_REDIRECT_URI
على عنوان URL نفسه الذي يتم عرض الصفحة فيه يجب أن تتطابق القيمة تمامًا مع إحدى
معرفات الموارد المنتظمة (URI) لإعادة التوجيه المسموح بها لعميل OAuth 2.0، والتي هيأتها في
API Console Credentials pageفي حال حذف
لا تتطابق هذه القيمة مع معرّف موارد منتظم (URI) معتمَد، ستحصل على redirect_uri_mismatch
.
خطأ. ينبغي أن يحتوي مشروعك أيضًا على
فعّلت واجهة برمجة التطبيقات المناسبة لهذا الطلب.
<html><head></head><body> <script> var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE'; var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE'; // Parse query string to see if page request is coming from OAuth 2.0 server. var fragmentString = location.hash.substring(1); var params = {}; var regex = /([^&=]+)=([^&]*)/g, m; while (m = regex.exec(fragmentString)) { params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]); } if (Object.keys(params).length > 0 && params['state']) { if (params['state'] == localStorage.getItem('state')) { localStorage.setItem('oauth2-test-params', JSON.stringify(params) ); trySampleRequest(); } else { console.log('State mismatch. Possible CSRF attack'); } } // Function to generate a random state value function generateCryptoRandomState() { const randomValues = new Uint32Array(2); window.crypto.getRandomValues(randomValues); // Encode as UTF-8 const utf8Encoder = new TextEncoder(); const utf8Array = utf8Encoder.encode( String.fromCharCode.apply(null, randomValues) ); // Base64 encode the UTF-8 data return btoa(String.fromCharCode.apply(null, utf8Array)) .replace(/\+/g, '-') .replace(/\//g, '_') .replace(/=+$/, ''); } // If there's an access token, try an API request. // Otherwise, start OAuth 2.0 flow. function trySampleRequest() { var params = JSON.parse(localStorage.getItem('oauth2-test-params')); if (params && params['access_token']) { var xhr = new XMLHttpRequest(); xhr.open('GET', 'https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views&' + 'access_token=' + params['access_token']); xhr.onreadystatechange = function (e) { if (xhr.readyState === 4 && xhr.status === 200) { console.log(xhr.response); } else if (xhr.readyState === 4 && xhr.status === 401) { // Token invalid, so prompt for user permission. oauth2SignIn(); } }; xhr.send(null); } else { oauth2SignIn(); } } /* * Create form to request access token from Google's OAuth 2.0 server. */ function oauth2SignIn() { // create random state value and store in local storage var state = generateCryptoRandomState(); localStorage.setItem('state', state); // Google's OAuth 2.0 endpoint for requesting an access token var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth'; // Create element to open OAuth 2.0 endpoint in new window. var form = document.createElement('form'); form.setAttribute('method', 'GET'); // Send as a GET request. form.setAttribute('action', oauth2Endpoint); // Parameters to pass to OAuth 2.0 endpoint. var params = {'client_id': YOUR_CLIENT_ID, 'redirect_uri': YOUR_REDIRECT_URI, 'scope': 'https://www.googleapis.com/auth/yt-analytics.readonly', 'state': state, 'include_granted_scopes': 'true', 'response_type': 'token'}; // Add form parameters as hidden input values. for (var p in params) { var input = document.createElement('input'); input.setAttribute('type', 'hidden'); input.setAttribute('name', p); input.setAttribute('value', params[p]); form.appendChild(input); } // Add form to page and submit it to open the OAuth 2.0 endpoint. document.body.appendChild(form); form.submit(); } </script> <button onclick="trySampleRequest();">Try sample request</button> </body></html>
قواعد التحقّق من مصدر JavaScript
يطبِّق محرّك بحث Google قواعد التحقّق التالية على مصادر JavaScript للمساعدة في ذلك. يحافظ المطورون على أمان تطبيقاتهم. يجب أن تتقيّد مصادر JavaScript بهذه القواعد. راجِع الفقرة 3 من معيار RFC 3986 للاطّلاع على النطاق والمضيف والمخطط أدناه.
قواعد التحقّق من الصحة | |
---|---|
المخطط |
يجب أن تستخدم أصول JavaScript مخطط HTTPS، وليس HTTP العادي. معرفات الموارد المنتظمة (URI) للمضيف المحلي تُستثنى من هذه القاعدة (بما في ذلك معرّفات الموارد المنتظمة (URI) لعنوان IP للمضيف المحلي). |
المضيف |
لا يمكن للمضيفين أن يكونوا عناوين IP غير معدّلة. تُستثنى من هذه القاعدة عناوين IP للمضيف المحلي. |
النطاق |
“googleusercontent.com” .goo.gl ).
ما لم يكن التطبيق يملك النطاق. |
معلومات المستخدم |
لا يمكن أن تحتوي أصول JavaScript على المكوِّن الفرعي لـ userinfo. |
المسار |
لا يمكن أن تحتوي أصول JavaScript على مكوّن المسار. |
طلب بحث |
لا يمكن أن تحتوي مصادر JavaScript على مكوّن طلب البحث. |
الجزء |
لا يمكن أن تحتوي أصول JavaScript على المكوِّن. |
الشخصيات |
لا يمكن أن تحتوي مصادر JavaScript على أحرف معيّنة، بما في ذلك:
|
التفويض التزايدي
في بروتوكول OAuth 2.0، يطلب تطبيقك إذنًا للوصول إلى الموارد، وهي المحددة من خلال النطاقات. إنّ طلب الحصول على إذن هو من أفضل الممارسات للحفاظ على تجربة المستخدم. للموارد في الوقت الذي تحتاج فيه إليها. ولتفعيل هذه العملية، يستخدم خادم تفويض Google يدعم التفويض التزايدي. وتتيح لك هذه الميزة طلب النطاقات حسب الحاجة. إذا منح المستخدم إذنًا للنطاق الجديد، فيعرض رمز تفويض ربما يكون مقابل رمز مميز يحتوي على جميع النطاقات التي منحها المستخدم المشروع.
على سبيل المثال، لنفترض أن أحد التطبيقات يسترد تقارير YouTube Analytics، فإن بعض
وهي تقارير مالية تتطلب الوصول إلى نطاق إضافي
اللازمة للتقارير الأخرى. في هذه الحالة، أثناء تسجيل الدخول، قد لا يكون التطبيق سوى
طلب الوصول إلى
نطاق واحد (https://www.googleapis.com/auth/yt-analytics.readonly
).
ومع ذلك، إذا حاول المستخدم استرداد تقرير مالي، يمكن للتطبيق أيضًا
طلب الوصول إلى
https://www.googleapis.com/auth/yt-analytics-monetary.readonly
النطاق.
تنطبق القواعد التالية على رمز الدخول الذي يتم الحصول عليه من تفويض متزايد:
- يمكن استخدام الرمز المميز للوصول إلى الموارد المقابلة لأي من النطاقات التي تم إدراجها في تفويض جديد مجمّع.
- عند استخدام رمز التحديث للتفويض المجمّع للحصول على رمز دخول،
ويمثل رمز الدخول التفويض المجمّع ويمكن استخدامه لأي من
تم تضمين
scope
قيمة في الردّ. - يتضمن التفويض المجمَّع جميع النطاقات التي منحها المستخدم لمشروع واجهة برمجة التطبيقات، بما في ذلك إذا تم طلب المنح من عملاء مختلفين على سبيل المثال، إذا منح أحد المستخدمين حق الوصول إلى نطاق واحد باستخدام برنامج سطح المكتب لتطبيق ما ثم منح نطاق آخر لنفس التطبيق عبر برنامج جوّال، فإن التفويض المجمّع سيشمل كلا النطاقين.
- في حال إبطال رمز مميّز يمثّل تفويضًا مجمّعًا، سيكون بإمكانك الوصول إلى كل ذلك يتم إبطال نطاقات التفويض نيابةً عن المستخدم المرتبط في الوقت نفسه.
توضح نماذج الرموز أدناه كيفية إضافة نطاقات إلى رمز دخول حالي. يسمح هذا النهج تطبيقك لتجنب الاضطرار إلى إدارة رموز دخول متعددة.
نقاط نهاية OAuth 2.0
في هذا المثال، يطلب تطبيق الاتصال الوصول لاسترداد بيانات YouTube Analytics الخاصة بالمستخدم بالإضافة إلى أي حق وصول آخر سبق أن تم منحه للتطبيق.
لإضافة نطاقات إلى رمز دخول حالي، يجب تضمين include_granted_scopes
في طلبك المُرسَل إلى خادم OAuth 2.0 في Google.
يوضح مقتطف الرمز التالي كيفية إجراء ذلك. يفترض المقتطف أنك خزّنت
النطاقات التي يكون رمز الدخول الخاص بها صالحًا في مساحة التخزين المحلية للمتصفِّح. (
يخزِّن رمز المثال الكامل قائمة بالنطاقات التي يتوفّر لها رمز دخول.
صالح من خلال ضبط السمة oauth2-test-params.scope
في الصفحة المحلية للمتصفّح
storage.)
يقارن المقتطف النطاقات التي يكون رمز الدخول لها صالحًا للنطاق الذي تريد استخدامه.
لطلب بحث معين. وإذا لم يغطِ رمز الدخول هذا النطاق، سيبدأ مسار OAuth 2.0.
الدالة oauth2SignIn
هي نفسها الدالة التي تم توفيرها هنا
الخطوة 2 (ويتم توفيرها لاحقًا في علامة التبويب إكمال
مثال).
var SCOPE = 'https://www.googleapis.com/auth/yt-analytics.readonly'; var params = JSON.parse(localStorage.getItem('oauth2-test-params')); var current_scope_granted = false; if (params.hasOwnProperty('scope')) { var scopes = params['scope'].split(' '); for (var s = 0; s < scopes.length; s++) { if (SCOPE == scopes[s]) { current_scope_granted = true; } } } if (!current_scope_granted) { oauth2SignIn(); // This function is defined elsewhere in this document. } else { // Since you already have access, you can proceed with the API request. }
إبطال رمز مميّز
في بعض الحالات، قد يرغب المستخدم في إبطال إذن الوصول الممنوح لأحد التطبيقات. يمكن للمستخدم إبطال إذن الوصول عن طريق زيارة إعدادات الحساب يمكنك الاطّلاع على إزالة الوصول إلى الموقع الإلكتروني أو التطبيق ضمن مواقع الجهات الخارجية التطبيقات التي يمكنها الوصول إلى حسابك مستند الدعم للحصول على مزيد من المعلومات.
يمكن أيضًا لأحد التطبيقات إبطال إذن الوصول الممنوح له آليًا. يُعد الإبطال الآلي مهمًا في الحالات التي يلغي فيها المستخدم اشتراكه، أو يزيل أو تغيرت بشكل كبير موارد واجهة برمجة التطبيقات التي يتطلبها التطبيق. أو بعبارةٍ أخرى، أن يتضمن جزء من عملية الإزالة طلب بيانات من واجهة برمجة التطبيقات لضمان الحصول على الأذونات ممنوح للتطبيق.
نقاط نهاية OAuth 2.0
لإبطال رمز مميّز آليًا، يطلب تطبيقك
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
مع
مع رمز خطأ.
يوضح مقتطف JavaScript التالي كيفية إبطال رمز مميز في JavaScript بدون استخدام
مكتبة برامج Google APIs للغة JavaScript. نظرًا لأن نقطة نهاية OAuth 2.0 من Google للإبطال
لا تتيح الرموز المميّزة مشاركة الموارد المتعدّدة المصادر (CORS)، ينشئ الرمز نموذجًا ويرسله.
النموذج إلى نقطة النهاية بدلاً من استخدام طريقة XMLHttpRequest()
لنشر
طلبك.
function revokeAccess(accessToken) { // Google's OAuth 2.0 endpoint for revoking access tokens. var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke'; // Create <form> element to use to POST data to the OAuth 2.0 endpoint. var form = document.createElement('form'); form.setAttribute('method', 'post'); form.setAttribute('action', revokeTokenEndpoint); // Add access token to the form so it is set as value of 'token' parameter. // This corresponds to the sample curl request, where the URL is: // https://oauth2.googleapis.com/revoke?token={token} var tokenField = document.createElement('input'); tokenField.setAttribute('type', 'hidden'); tokenField.setAttribute('name', 'token'); tokenField.setAttribute('value', accessToken); form.appendChild(tokenField); // Add form to page and submit it to actually revoke the token. document.body.appendChild(form); form.submit(); }
تطبيق ميزة "الحماية العابرة للحساب"
خطوة إضافية ينبغي لك اتخاذها لحماية حسابات المستخدمين الحسابات تنفّذ ميزة "على مستوى الحساب" يمكنك الحماية باستخدام "خدمة الحماية العابرة للحساب" من 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
يمكنك الاطّلاع على حماية حسابات المستخدمين باستخدام صفحة "الحماية العابرة للحساب" للحصول على مزيد من المعلومات حول كيفية تفعيل ميزة "الحماية العابرة للحساب" والاطّلاع على قائمة كاملة بالأحداث المتاحة.