يوضّح هذا المستند كيفية تنفيذ تفويض OAuth 2.0 للوصول إلى واجهة برمجة تطبيقات YouTube Analytics أو 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 Identity" للتعامل مع مسار OAuth 2.0. يُرجى الاطّلاع على نموذج الرمز المميّز في "خدمات هوية Google"، والذي يستند إلى مسار المنح الضمني لبروتوكول OAuth 2.0.
المتطلبات الأساسية
تفعيل واجهات برمجة التطبيقات لمشروعك
ويجب تفعيل واجهات برمجة التطبيقات هذه في API Consoleلأي تطبيق يستدعي Google APIs.
لتفعيل واجهة برمجة تطبيقات لمشروعك:
- Open the API Library في Google API Console.
- If prompted, select a project, or create a new one.
- استخدِم صفحة "المكتبة" للعثور على "واجهة برمجة تطبيقات YouTube Analytics" و"واجهة برمجة التطبيقات لإعداد التقارير في YouTube" وتفعيلهما. ترتبط أيضًا العديد من التطبيقات التي تسترد بيانات YouTube Analytics بواجهة 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 النطاقات التالية:
| النطاقات | |
|---|---|
| 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 النطاقات التالية:
| النطاقات | |
|---|---|
| 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 API على قائمة كاملة بالنطاقات التي قد تستخدمها للوصول إلى واجهات 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 |
مطلوب
معرِّف العميل لتطبيقك. يمكنك العثور على هذه القيمة في Credentials page API Console. |
||||||||||||||||||
redirect_uri |
مطلوب
تحدد هذه السمة المكان الذي يُعيد فيه خادم واجهة برمجة التطبيقات توجيه المستخدم بعد أن يُكمل
عملية التفويض. يجب أن تتطابق القيمة تمامًا مع أحد معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه في
برنامج OAuth 2.0، والذي ضبطته في
Credentials page API Consoleللبرنامج. وإذا لم تتطابق هذه القيمة مع
معرّف الموارد المنتظم (URI) المعتمَد لإعادة التوجيه للسمة يُرجى العلم أنّه يجب أن تتطابق جميع العناصر في نظام |
||||||||||||||||||
response_type |
مطلوب
تحتاج تطبيقات JavaScript إلى ضبط قيمة المعلَمة على |
||||||||||||||||||
scope |
مطلوب
يشير ذلك إلى قائمة بالنطاقات التي يتم الفصل بينها بمسافات والتي تحدّد الموارد التي يمكن للتطبيق الوصول إليها نيابةً عن المستخدم. وتوضّح هذه القيم شاشة طلب الموافقة التي تعرضها Google للمستخدم. تتيح النطاقات لتطبيقك إمكانية طلب الوصول إلى الموارد التي يحتاجها فقط، مع السماح للمستخدمين في الوقت نفسه بالتحكم في مستوى الوصول الذي يتم منحه لتطبيقك. وبالتالي، هناك علاقة عكسية بين عدد النطاقات المطلوبة واحتمالية الحصول على موافقة المستخدم. تستخدم واجهة برمجة التطبيقات لإحصاءات YouTube النطاقات التالية:
تستخدم واجهة برمجة التطبيقات لإعداد التقارير في YouTube النطاقات التالية:
يوفّر مستند نطاقات واجهة برمجة التطبيقات OAuth 2.0 قائمة كاملة بالنطاقات التي قد تستخدمها للوصول إلى واجهات برمجة تطبيقات Google. ننصحك بأن يطلب تطبيقك الوصول إلى نطاقات التفويض في السياق كلما أمكن ذلك. من خلال طلب الوصول إلى بيانات المستخدمين في السياق المناسب، من خلال الإذن المتزايد، تساعد المستخدمين على فهم سبب احتياج تطبيقك إلى إذن الوصول الذي يطلبه. |
||||||||||||||||||
state |
سمة مقترَحة
يحدد أي قيمة سلسلة يستخدمها تطبيقك للحفاظ على الحالة بين
طلب التفويض واستجابة خادم التفويض.
يعرض الخادم القيمة الدقيقة التي ترسلها كزوج يمكنك استخدام هذه المَعلمة لأغراض متعدّدة، مثل توجيه المستخدم إلى
المورد الصحيح في تطبيقك، وإرسال أرقام خاصة،
والتخفيف من حدّة تزوير الطلبات من مواقع إلكترونية متعددة. بما أنّه يمكن تخمين |
||||||||||||||||||
include_granted_scopes |
اختياريّ
يسمح هذا الإعداد للتطبيقات باستخدام التفويض المتزايد لطلب الوصول إلى
نطاقات إضافية في السياق. في حال ضبط قيمة هذه المعلَمة على |
||||||||||||||||||
enable_granular_consent |
اختياريّ
وتكون الإعدادات التلقائية |
||||||||||||||||||
login_hint |
اختياريّ
إذا كان تطبيقك يعرف المستخدم الذي يحاول المصادقة، يمكنه استخدام هذه المعلَمة لتقديم تلميح إلى خادم مصادقة Google. يستخدم الخادم التلميح لتبسيط عملية تسجيل الدخول، سواء عن طريق ملء حقل البريد الإلكتروني مسبقًا في نموذج تسجيل الدخول أو عن طريق اختيار جلسة تسجيل الدخول المتعدّد المناسبة. اضبط قيمة المعلَمة على عنوان بريد إلكتروني أو معرّف |
||||||||||||||||||
prompt |
اختياريّ
قائمة بطلبات تقديم المستخدم محددة بمسافات وحساسة لحالة الأحرف. إذا لم تحدّد هذه المَعلمة، سيُطلب من المستخدم فقط في المرة الأولى التي يطلب فيها مشروعك الوصول إلى البيانات. راجِع طلب إعادة الموافقة للحصول على مزيد من المعلومات. القيم المتاحة:
|
||||||||||||||||||
نموذج لإعادة التوجيه إلى خادم التفويض في Google
يطلب نموذج عنوان URL أدناه الوصول بلا اتصال بالإنترنت
(access_type=offline) إلى نطاق يسمح بالوصول إلى
تقارير "إحصاءات YouTube" الخاصة بالمستخدم. وهو يستخدم تفويضًا متزايدًا لضمان تغطية رمز الدخول الجديد لأي نطاقات قام المستخدم بمنحها في السابق إذن الوصول إلى التطبيق. يضبط عنوان 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
يتم عرض نقطة نهاية التفويض داخل وكيل مستخدم مضمّن لا تسمح به سياسات OAuth 2.0 في Google.
Android
قد تظهر رسالة الخطأ هذه لمطوّري برامج Android عند فتح طلبات التفويض في android.webkit.WebView.
وبدلاً من ذلك، على المطوّرين استخدام مكتبات Android، مثل ميزة "تسجيل الدخول بحساب Google" لأجهزة Android أو AppAuth لنظام التشغيل Android من OpenID Foundation.
قد يظهر هذا الخطأ لمطوّري البرامج على الويب عندما يفتح تطبيق Android رابط ويب عامًا في وكيل مستخدم مضمّن وينتقل مستخدم إلى نقطة نهاية تفويض OAuth 2.0 من Google من موقعك الإلكتروني. على المطوّرين السماح بفتح الروابط العامة في المعالج التلقائي للروابط في نظام التشغيل، والذي يتضمّن معالِجات روابط تطبيقات Android أو تطبيق المتصفّح التلقائي. ويمكن أيضًا استخدام مكتبة علامات التبويب المخصّصة في Android.
iOS
قد يظهر هذا الخطأ لمطوّري تطبيقات iOS وmacOS عند فتح طلبات التفويض في
WKWebView.
وبدلاً من ذلك، على المطوّرين استخدام مكتبات iOS مثل تسجيل الدخول بحساب Google لنظام التشغيل iOS أو AppAuth for iOS من OpenID Foundation.
قد يظهر هذا الخطأ لمطوّري البرامج على الويب عندما يفتح أحد تطبيقات 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
بعد حصول تطبيقك على رمز دخول، يمكنك استخدام الرمز المميّز لإجراء طلبات بيانات من Google API نيابةً عن حساب مستخدم معيّن، وذلك في حال تم منح نطاقات الوصول التي تطلبها واجهة برمجة التطبيقات. لإجراء ذلك، ضمِّن رمز الدخول في طلب لواجهة برمجة التطبيقات عن طريق تضمين مَعلمة طلب بحث access_token أو قيمة Bearer لعنوان HTTP Authorization. ويفضَّل استخدام عنوان HTTP إذا أمكن، لأنّ سلاسل الطلبات تكون غالبًا مرئية في سجلات الخادم. وفي معظم الحالات، يمكنك استخدام مكتبة برامج لإعداد طلباتك المتعلّقة بواجهات Google APIs (على سبيل المثال، عند طلب البيانات من YouTube Analytics API).
يُرجى العِلم أنّ واجهة برمجة تطبيقات YouTube Analytics لا تتيح استخدام مسار حساب الخدمة. تتيح واجهة YouTube Reporting API استخدام حسابات الخدمة فقط لمالكي المحتوى على YouTube الذين يملكون قنوات متعددة على YouTube ويديرونها، مثل شركات الإنتاج واستوديوهات الأفلام.
ويمكنك تجربة جميع واجهات برمجة تطبيقات Google وعرض نطاقاتها في ملعب OAuth 2.0.
أمثلة على HTTP GET
قد يبدو طلب نقطة نهاية
reports.query (واجهة برمجة تطبيقات YouTube Analytics) باستخدام عنوان HTTP
Authorization: Bearer على النحو التالي: لاحظ أنك تحتاج إلى تحديد رمز الدخول الخاص بك:
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 API. لا يستخدم هذا المثال مكتبة برامج 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 API لاسترداد عدد المشاهدات لقناة المستخدم المفوّض على 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';
var fragmentString = location.hash.substring(1);
// Parse query string to see if page request is coming from OAuth 2.0 server.
var params = {};
var regex = /([^&=]+)=([^&]*)/g, m;
while (m = regex.exec(fragmentString)) {
params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
}
if (Object.keys(params).length > 0) {
localStorage.setItem('oauth2-test-params', JSON.stringify(params) );
if (params['state'] && params['state'] == 'try_sample_request') {
trySampleRequest();
}
}
// 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() {
// 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': 'try_sample_request',
'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 على المكوِّن الفرعي لمعلومات المستخدم. |
| المسار |
لا يمكن أن تحتوي أصول 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" الخاصة بالمستخدم بالإضافة إلى أي إذن وصول آخر سبق أن تم منحه إلى التطبيق.
لإضافة نطاقات إلى رمز دخول حالي، يمكنك تضمين المَعلمة include_granted_scopes
في طلبك إلى خادم OAuth 2.0 من Google.
ويوضّح مقتطف الرمز التالي كيفية إجراء ذلك. ويفترض المقتطف أنّك خزّنت النطاقات التي يكون رمز الدخول صالحًا لها في مساحة التخزين المحلية للمتصفّح. (يخزِّن رمز
المثال الكامل قائمة بالنطاقات التي يكون رمز الدخول صالحًا لها
من خلال ضبط السمة oauth2-test-params.scope في مساحة التخزين المحلية
على المتصفّح).
يقارن المقتطف النطاقات التي يكون رمز الدخول صالحًا لها بالنطاق الذي تريد استخدامه لطلب بحث محدّد. إذا كان رمز الدخول لا يغطي هذا النطاق، سيبدأ مسار 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();
}